UI

View

class ember.ui.View(*layers: ViewLayer | Sequence[ViewLayer])
class ember.ui.View(element: Element, focused: 'Element' | None = None, keyboard_nav: bool = True, listen_for_exit: DefaultType | bool = DEFAULT)

class ember.ui.ViewLayer(*args, **kwargs)

Elements

class ember.ui.Element(*args, **kwargs)

The base element class. All UI elements in the library inherit from this class.

layer: 'ViewLayer' | None: The View that the Element is (directly or indirectly) attributed to.

parent: 'Container' | None: The Container that the Element is directly attributed to. For example, if the Element is placed inside of a VStack, it’s parent would be that VStack object.

ancestry: list['Container']: A list containing the parent nodes of the element.

build() → None

abstract unpack() → tuple[HasGeometry, ...]

update_ancestry(ancestry: list[Element]) → None

update_cascading_value(value: CascadingTraitValue, depth: int) → None

copy() → Element

kill() → None: Remove the element from its parent container. Fails gracefully without raising an exception if the element doesn’t have a parent.

class ember.ui.HasGeometry(*args, **kwargs)

rect: A pygame.FRect object containing the absolute position and size of the element. Read-only.

x: Trait[Position] = <ember.trait.bound_trait.BoundTrait object>

y: Trait[Position] = <ember.trait.bound_trait.BoundTrait object>

w: Trait[Size] = <ember.trait.bound_trait.BoundTrait object>

h: Trait[Size] = <ember.trait.bound_trait.BoundTrait object>

visible: bool: Is True when any part of the element is visible on the screen. Read-only.

unpack() → tuple[HasGeometry, ...]

build() → None

update_rect(surface: Surface, x: float | None = None, y: float | None = None, w: float | None = None, h: float | None = None, rel_pos1: float | None = None, rel_pos2: float | None = None, rel_size1: float | None = None, rel_size2: float | None = None) → None

update_rect_next_tick() → None: On the next view update, call update_rect for this element.

update_min_size_next_tick(must_update_parent: bool = False) → None: On the next view update, call update_min_size for this element.

update_min_size(proprogate: bool = True, must_update_parent: bool = False) → None

render(surface: Surface, offset: tuple[int, int], alpha: int = 255) → None: Used internally by the library.

update() → None: Used internally by the library. Updates the element, with transitions taken into consideration.

event(event: Event) → bool

get_x(container_width: float, element_width: float | None = None) → float

get_y(container_height: float, element_height: float | None = None) → float

get_w(max_width: float = 0) → float: Get the width of the element as a float, given the maximum width to fill.

get_h(max_height: float = 0) → float: Get the height of the element as a float, given the maximum height to fill.

get_abs_rel_size1(max_size: float = 0) → float

get_abs_rel_size2(max_size: float = 0) → float

property rel_pos1: Position

property rel_pos2: Position

property rel_size1: Size

property rel_size2: Size

is_animating(trait: Trait) → bool

class ember.ui.CanPivot(*args, **kwargs)

axis = <ember.trait.bound_trait.BoundTrait object>

get_x(container_width: float, element_width: float | None = None) → float

get_y(container_height: float, element_height: float | None = None) → float

get_w(max_width: float = 0) → float

get_h(max_height: float = 0) → float

class ember.ui.Container(*args, **kwargs)

Base class for Containers. Should not be instantiated directly.

text_class: Type[Text] | None = None

start_cascade(value: CascadingTraitValue) → None

update_ancestry(ancestry: list[Element]) → None

update_cascading_value(value: CascadingTraitValue, depth: int) → None

abstract remove_child(element: Element) → None

make_visible(element: Element) → None

adding_element(element: Element | str, update: bool = True) → Generator[Element | None, None, None]

removing_element(element: Element | None, update: bool = True) → None

class ember.ui.SingleElementContainer(*args, **kwargs)

multi_element_wrapper: type[MultiElementContainer] | None = None

property element: Element | None

set_element(element: Element | None, _update: bool = True) → None: Replace the element in the Container with a new element.

remove_child(element: Element) → None

class ember.ui.MultiElementContainer(*args, **kwargs)

set_elements(*elements: Element | str | None | Sequence[Element | str | None] | Generator[Element | str | None, None, None], update: bool = True) → None: Replace the elements in the stack with new elements.

append(element: Element | str | None, update: bool = True) → None: Append an element to the end of the stack.

insert(index: int, element: Element | str | None, update: bool = True) → None: Insert an element before at an index.

pop(index: int = -1, update: bool = True) → Element | None: Remove and return an element at an index (default last).

remove(element: Element | None, update: bool = True) → None: Remove an element from the stack.

remove_child(element: Element) → None

copy() → Element

index(element: Element | None) → int: Returns the index of the element.

property elements: list[Element | None]: Returns the child elements of the Container as a list. Read-only.

class ember.ui.MaskedContainer(*args, **kwargs)

render(surface: Surface, offset: tuple[int, int], alpha: int = 255) → None: Used internally by the library.

event(event: Event) → bool

cascading: CascadeRepository

layer: 'ViewLayer' | None: The View that the Element is (directly or indirectly) attributed to.

parent: 'Container' | None: The Container that the Element is directly attributed to. For example, if the Element is placed inside of a VStack, it’s parent would be that VStack object.

ancestry: list['Container']: A list containing the parent nodes of the element.

class ember.ui.PanelContainer(*args, **kwargs)

property panel: Panel

cascading: CascadeRepository

layer: 'ViewLayer' | None: The View that the Element is (directly or indirectly) attributed to.

parent: 'Container' | None: The Container that the Element is directly attributed to. For example, if the Element is placed inside of a VStack, it’s parent would be that VStack object.

ancestry: list['Container']: A list containing the parent nodes of the element.

class ember.ui.View(*layers: ViewLayer | Sequence[ViewLayer])

class ember.ui.View(element: Element, focused: 'Element' | None = None, keyboard_nav: bool = True, listen_for_exit: DefaultType | bool = DEFAULT)

keyboard_nav: bool: Whether keyboard and controller navigation is enabled for this View.

update(surface: ~pygame.surface.Surface, rect: ~typing.Sequence[float] | ~typing.Sequence[int] | ~pygame.rect.Rect | ~pygame.rect.FRect | None = None, update_positions: bool = True, update_elements: bool = True, render: bool = True, alpha: int = 255, display_zoom: ~ember.common.DefaultType | int = <ember.common.DefaultType object>) → None: Update the View. This should be called every tick.

event(event: Event) → bool: Passes Pygame Events to the View. This should be called for each event in the event stack.

append(element: Element, focused: 'Element' | None = None, listen_for_exit: DefaultType | bool = DEFAULT) → None
append(layer: ViewLayer) → None

pop(index: int = -1) → ViewLayer: Remove and return a layer at an index (default last).

update_elements() → None

shift_focus(direction: FocusDirection, element: Element | None = None) → None

start_manual_update() → None: Starts the update chain on the next tick. You shouldn’t need to call this manually, it exists incase the library misses something.

property layers: list[ViewLayer]: A list of the View’s ViewLayers.

class ember.ui.ViewLayer(*args, **kwargs)

property index: int

shift_focus(direction: FocusDirection, element: Element | None = None) → None: Shift the focus in a direction.

start_manual_update() → None: Starts the update chain on the next tick. You shouldn’t need to call this manually, it exists incase the library misses something.

update_can_focus() → None

update_rect_next_tick() → None: On the next view update, call update_rect for this element.

class ember.ui.Group(*args, **kwargs)

unpack() → tuple[HasGeometry, ...]

class ember.ui.Stack(*args, **kwargs)

A Stack is a collection of Elements. There are two subclasses of Stack - ember.ui.VStack and ember.ui.HStack. Depsite the name, ember.ui.ZStack is not a subclass.

spacing = <ember.trait.bound_trait.BoundTrait object>

class ember.ui.HStack(*args, **kwargs)

context_queue: list['Element']: FIFO. Holds the elements that have been instantiated in this context.

cascading: CascadeRepository

visible: bool: Is True when any part of the element is visible on the screen. Read-only.

layer: 'ViewLayer' | None: The View that the Element is (directly or indirectly) attributed to.

parent: 'Container' | None: The Container that the Element is directly attributed to. For example, if the Element is placed inside of a VStack, it’s parent would be that VStack object.

ancestry: list['Container']: A list containing the parent nodes of the element.

class ember.ui.VStack(*args, **kwargs)

context_queue: list['Element']: FIFO. Holds the elements that have been instantiated in this context.

cascading: CascadeRepository

visible: bool: Is True when any part of the element is visible on the screen. Read-only.

layer: 'ViewLayer' | None: The View that the Element is (directly or indirectly) attributed to.

parent: 'Container' | None: The Container that the Element is directly attributed to. For example, if the Element is placed inside of a VStack, it’s parent would be that VStack object.

ancestry: list['Container']: A list containing the parent nodes of the element.

class ember.ui.ZStack(*args, **kwargs)

class ember.ui.Box(*args, **kwargs)

A Box is a container that can optionally hold one Element.

update_can_focus() → None: Update the can_handle_focus attribute of the container.

context_queue: list['Element']: FIFO. Holds the elements that have been instantiated in this context.

cascading: CascadeRepository

layer: 'ViewLayer' | None: The View that the Element is (directly or indirectly) attributed to.

parent: 'Container' | None: The Container that the Element is directly attributed to. For example, if the Element is placed inside of a VStack, it’s parent would be that VStack object.

ancestry: list['Container']: A list containing the parent nodes of the element.

class ember.ui.MaskedBox(*args, **kwargs)

cascading: CascadeRepository

layer: 'ViewLayer' | None: The View that the Element is (directly or indirectly) attributed to.

parent: 'Container' | None: The Container that the Element is directly attributed to. For example, if the Element is placed inside of a VStack, it’s parent would be that VStack object.

ancestry: list['Container']: A list containing the parent nodes of the element.

visible: bool: Is True when any part of the element is visible on the screen. Read-only.

class ember.ui.PanelBox(*args, **kwargs)

cascading: CascadeRepository

layer: 'ViewLayer' | None: The View that the Element is (directly or indirectly) attributed to.

parent: 'Container' | None: The Container that the Element is directly attributed to. For example, if the Element is placed inside of a VStack, it’s parent would be that VStack object.

ancestry: list['Container']: A list containing the parent nodes of the element.

class ember.ui.Text(*args, **kwargs)

An Element that displays some text.

variant: TextVariant = <ember.trait.bound_trait.BoundTrait object>

font = <ember.trait.bound_trait.BoundTrait object>

property text: str: Get or set the text string. The property setter is synonymous with the set_text method.

set_text(text: str) → None: Set the text string. This method is synonymous with the :py:property:`text<ember.ui.Text.text>` property setter.

get_line(line_index: int) → Line | None: Get the Line object for a given line index.

get_line_index_from_letter_index(letter_index: int) → int: Get the line index for a given letter index.

class ember.ui.Spacer(*args, **kwargs)

class ember.ui.Panel(*args, **kwargs)

class ember.ui.Divider(*args, **kwargs)

material = <ember.trait.bound_trait.BoundTrait object>

update_ancestry(ancestry: list[Element]) → None

class ember.ui.Button(*args, **kwargs)

A Button is an interactive Element. Buttons can hold exactly one child Element, which is rendered on the button. When the button is clicked, it will post the ember.BUTTONCLICKED event.

class WrapperZStack(*args, **kwargs)

multi_element_wrapper: alias of WrapperZStack

class ember.ui.PanelButton(*args, **kwargs)

cascading: CascadeRepository

layer: 'ViewLayer' | None: The View that the Element is (directly or indirectly) attributed to.

parent: 'Container' | None: The Container that the Element is directly attributed to. For example, if the Element is placed inside of a VStack, it’s parent would be that VStack object.

ancestry: list['Container']: A list containing the parent nodes of the element.

class ember.ui.Gauge(*args, **kwargs)

class ValueCause

class Cause

PROPERTY = <ember.ui.gauge.Gauge.ValueCause.Cause object>

property value: float

property progress: float

property min_value: float

property max_value: float

class ember.ui.Bar(*args, **kwargs)

class ember.ui.InteractiveLinearGauge(*args, **kwargs)

scroll_to_adjust: bool = True

center_handle_on_pickup: bool = True

keyboard_adjustment_steps: int = 10

scroll_speed: float = 0.1

invert_y_axis: bool = True

class ValueCause

CLICK = <ember.ui.gauge.Gauge.ValueCause.Cause object>

DRAG = <ember.ui.gauge.Gauge.ValueCause.Cause object>

SCROLL = <ember.ui.gauge.Gauge.ValueCause.Cause object>

KEY = <ember.ui.gauge.Gauge.ValueCause.Cause object>

class ember.ui.InteractiveBar(*args, **kwargs)

click_animation: Animation | None = <ember.animation.ease.EaseInOut object>

class ember.ui.Slider(*args, **kwargs)

class ember.ui.ToggleButton(*args, **kwargs)

property active: bool

class ember.ui.PanelToggleButton(*args, **kwargs)

cascading: CascadeRepository

layer: 'ViewLayer' | None: The View that the Element is (directly or indirectly) attributed to.

parent: 'Container' | None: The Container that the Element is directly attributed to. For example, if the Element is placed inside of a VStack, it’s parent would be that VStack object.

ancestry: list['Container']: A list containing the parent nodes of the element.

context_queue: list['Element']: FIFO. Holds the elements that have been instantiated in this context.

visible: bool: Is True when any part of the element is visible on the screen. Read-only.

class ember.ui.Switch(*args, **kwargs)

animation: Animation = <ember.animation.ease.EaseInOut object>