tessella.widgets package

Subpackages

tessella.widgets.style package

Submodules

tessella.widgets.align module

class tessella.widgets.align.Align(alignment, child)[source]

Bases: SingleChildWidget

A widget capable of aligning its child.

Parameters:

alignment (PositionalAlignment)
child (Widget)

alignment

The anchor point to align the child from.

Type:: PositionalAlignment

NOTE: This widget takes up all the available space given to it.

calculate_size(constraints)[source]

Calculates the size of this widget with the given constraints. Note that this widget MUST call apply_layout_constraints on its children if applicable. Must be implemented by subclasses.

Parameters:: constraints (WidgetConstraints) – The constraints to be used for determining the sizing of this widget.
Returns:: The calculated size for this widget
Return type:: tuple[int, int]

depends_on_child_size()[source]

A method that indicates whether this widget’s size depends on its child’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its child’s size.
Return type:: bool

depends_on_parent_size()[source]

A method that indicates whether this widget’s size depends on its parent’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its parent’s size.
Return type:: bool

tessella.widgets.button module

class tessella.widgets.button.ButtonState[source]

Bases: WidgetState

The state object used by the widget Button.

gesture_key

The key used by the inner GestureDetector in this widget.

Type:: WidgetKey

class tessella.widgets.button.Button(key, text, width, height, on_click=None, on_hover_start=None, on_hover_end=None, style=None)[source]

Bases: StatefulWidget[ButtonState]

A simple button that can react to clicks and be customized.

Parameters:

key (WidgetKey)
text (str)
width (int | None)
height (int | None)
on_click (Callable[[], None] | None)
on_hover_start (Callable[[], None] | None)
on_hover_end (Callable[[], None] | None)
style (ButtonStyle | None)

text

The text displayed inside this widget.

Type:: str

width

The width of this widget, in pixels.

Type:: int

height

The height of this widget, in pixels.

Type:: int

style

The styling object used to customize the visuals of this widget.

Type:: ButtonStyle

on_click

The optional callback called when the button is clicked.

Type:: Callable[[], None] | None

create_state()[source]

Creates a new WidgetState subclass object, which holds the specific data of this widget implementation. Must be implemented by subclasses.

Raises:: NotImplementedError – This method must be implemented by a subclass.
Returns:: The WidgetState object related to this widget implementation.
Return type:: WidgetState[T]

build()[source]

Method called for building this widget. This method defaults to returning the widget itself, but custom widgets can override this method to return a more complex widget subtree.

Returns:: The Widget object built by this Widget.
Return type:: Widget

tessella.widgets.center module

class tessella.widgets.center.Center(child)[source]

Bases: Align

A widget that centers its child.

NOTE: This widget takes up all the available space given to it.

Parameters:: child (Widget)

tessella.widgets.checkbox module

class tessella.widgets.checkbox.CheckboxState(is_active)[source]

Bases: WidgetState

The state object used by the Checkbox widget.

Parameters:: is_active (bool)

is_active

Whether the checkbox is currently checked.

Type:: bool

is_hovered

Whether the checkbox is currently being hovered.

Type:: bool

class tessella.widgets.checkbox.Checkbox(key, on_changed=None, height=20, style=None, initial_value=False)[source]

Bases: StatefulWidget[CheckboxState]

A checkbox that can be toggled on and off by clicking it.

Parameters:

key (WidgetKey)
on_changed (Callable[[bool], None] | None)
height (int)
style (CheckboxStyle | None)
initial_value (bool)

on_changed

An optional callback called with the new checked state whenever it changes.

Type:: Callable[[bool], None] | None

height

The size of the checkbox’s box, in pixels. Also used as the width, since the box is square.

Type:: int

style

The styling object used to customize the visuals of this widget.

Type:: CheckboxStyle

initial_value

Whether the checkbox starts out checked.

Type:: bool

create_state()[source]

Creates a new WidgetState subclass object, which holds the specific data of this widget implementation. Must be implemented by subclasses.

Raises:: NotImplementedError – This method must be implemented by a subclass.
Returns:: The WidgetState object related to this widget implementation.
Return type:: WidgetState[T]

on_click()[source]

Toggles is_active, invokes on_changed and rebuilds the widget.

Return type:: None

on_hover_start()[source]

Marks the checkbox as hovered and rebuilds it, if it wasn’t already.

Return type:: None

on_hover_end()[source]

Marks the checkbox as no longer hovered and rebuilds it, if it was.

Return type:: None

build()[source]

Builds the checkbox as a square box whose color reacts to hovering, containing an inner square thumb that is only filled with style.thumb_color while is_active is True.

Returns:: The widget built by this widget.
Return type:: Widget

tessella.widgets.column module

class tessella.widgets.column.Column(children=None, main_axis_alignment=MainAxisAlignment.START, cross_axis_alignment=CrossAxisAlignment.CENTER, shrink_wrap=False)[source]

Bases: MultiChildWidget

A widget capable of displaying its children in a column.

Parameters:

children (list[Widget] | None)
main_axis_alignment (MainAxisAlignment)
cross_axis_alignment (CrossAxisAlignment)
shrink_wrap (bool)

children

The list of children belonging to this widget.

Type:: list[Widget]

main_axis_alignment

Property which controls how the widgets are spaced in the column.

Type:: MainAxisAlignment

cross_axis_alignment

Property which controls how the widgets are aligned horizontally in the column.

Type:: CrossAxisAlignment

shrink_wrap

Whether the column should shrink to fit its non-flexible children instead of taking up the whole main axis. Ignored if the column has any flexible children.

Type:: bool

calculate_size(constraints)[source]

Calculates the size of the column in two passes: first laying out non-flexible children to determine how much main axis space is left over, then splitting that leftover space between flexible children according to their flex_factor. If the column has any flexible children, or shrink_wrap is False, it takes up the whole main axis regardless of its children’s combined size.

Parameters:: constraints (WidgetConstraints) – The constraints to be used for determining the sizing of this widget.
Returns:: The calculated size for this widget.
Return type:: tuple[int, int]

render(target_surface, debug_mode=False)[source]

Renders this column and its children as described in MultiChildWidget.render, using an intermediate OffsetSurface so that any content overflowing the column’s bounds gets clipped.

Parameters:

target_surface (pygame.Surface) – The surface to render the widget into.
debug_mode (bool) – Whether to render a debug version of the widget that has some layout lines to help with visualization. Defaults to False.

Return type:

None

depends_on_parent_size()[source]

A method that indicates whether this widget’s size depends on its parent’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its parent’s size.
Return type:: bool

depends_on_child_size()[source]

A method that indicates whether this widget’s size depends on its children’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its children’s size.
Return type:: bool

tessella.widgets.container module

class tessella.widgets.container.Container(width=None, height=None, child=None, style=None)[source]

Bases: SingleChildWidget

A box widget that can hold a child.

Parameters:

width (int | None)
height (int | None)
child (Widget | None)
style (ContainerStyle | None)

width

Defines the width of the widget, in pixels.

Type:: int | None

height

Defines the height of the widget, in pixels.

Type:: int | None

child

The child of this widget, if any.

Type:: Widget | None

style

The styling used by this widget.

Type:: ContainerStyle

get_bitmask()[source]

Builds a bitmask shaped like this container’s rounded rectangle, so that collision checks (see collidepoint) exclude the corners clipped off by style.border_style.border_radius.

Returns:: The mask to be used by this widget.
Return type:: pygame.Mask

collidepoint(point)[source]

Checks if a point lands inside this container, using its rounded rectangle bitmask for a precise check that excludes the clipped corners.

Parameters:: point (tuple[int, int]) – The point to check for collisions.
Returns:: Whether the point is inside the container or not.
Return type:: bool

calculate_size(constraints)[source]

Calculates the size of this container. Any axis with an explicit width/height uses that value; otherwise, if the container has a child, it takes the child’s size on that axis, or the maximum available size if it has none.

Parameters:: constraints (WidgetConstraints) – The constraints to be used for determining the sizing of this widget.
Returns:: The calculated size for this widget.
Return type:: tuple[int, int]

depends_on_child_size()[source]

A method that indicates whether this widget’s size depends on its child’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its child’s size.
Return type:: bool

depends_on_parent_size()[source]

A method that indicates whether this widget’s size depends on its parent’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its parent’s size.
Return type:: bool

tessella.widgets.dropdown module

class tessella.widgets.dropdown.DropdownItem(value, label)[source]

Bases: object

Parameters:

value (T)
label (str)

class tessella.widgets.dropdown.DropdownState[source]

Bases: WidgetState

The state object used by the Dropdown widget.

is_open

Whether the dropdown is open or closed.

Type:: bool

selected_entry

The currently selected entry.

Type:: int

hovered_entry

The currently hovered entry.

Type:: int

is_hovered

Whether the dropdown is hovered.

Type:: bool

class tessella.widgets.dropdown.Dropdown(key, items, style=None)[source]

Bases: StatefulWidget[DropdownState]

A widget that displays a list of selectable options.

Parameters:

key (WidgetKey)
items (list[DropdownItem])
style (DropdownStyle | None)

items

The list of selectable options displayed by this widget.

Type:: list[DropdownItem]

_width

The internal width of this widget.

Type:: int

_height

The internal height of this widget.

Type:: int

overlay

The overlay displayed when the dropdown is open.

Type:: Overlay

keys

Keys used internally for detecting clicks.

Type:: list[WidgetKey]

main_key

The default key for this widget.

Type:: WidgetKey

style

The styling used when rendering this widget.

Type:: DropdownStyle

create_state()[source]

Creates a new WidgetState subclass object, which holds the specific data of this widget implementation. Must be implemented by subclasses.

Raises:: NotImplementedError – This method must be implemented by a subclass.
Returns:: The WidgetState object related to this widget implementation.
Return type:: WidgetState[T]

open_or_close()[source]

Toggles whether the dropdown’s entry list overlay is open, showing/hiding it via overlay.active. Also resets hovered_entry to 0 when opening, since the first entry overlaps the closed dropdown’s position.

Return type:: None

on_entry_hover(entry_index)[source]

Marks the given entry as hovered and rebuilds the widget so it gets highlighted.

Parameters:: entry_index (int) – The index of the entry being hovered, into items.
Return type:: None

on_hover_start()[source]

Marks the closed dropdown as hovered and rebuilds it.

Return type:: None

on_hover_end()[source]

Marks the closed dropdown as no longer hovered and rebuilds it.

Return type:: None

calculate_size(constraints)[source]

Calculates the size needed to fit the widest/tallest entry label, plus room for the dropdown’s arrow indicator and style.padding. Also (re)builds the entry list overlay, since it depends on this size, and starts it out closed.

Parameters:: constraints (WidgetConstraints) – The constraints to be used for determining the sizing of this widget.
Returns:: The calculated size for this widget.
Return type:: tuple[int, int]

on_click_outside()[source]

Closes the entry list overlay if a click lands outside of it.

Return type:: None

build_overlay()[source]

(Re)builds the Overlay widget that displays the dropdown’s entry list, disposing of the previous one if any and preserving whether it was active. The overlay is positioned directly below the closed dropdown’s bounds.

Return type:: None

set_position(new_position)[source]

Updates this widget’s position as described in StatefulWidget, then repositions the entry list overlay so it stays directly below the dropdown.

Parameters:: new_position (tuple[int, int]) – The new position for the topleft corner of this widget.
Return type:: None

on_entry_selected(entry_index)[source]

Selects the given entry, closes the dropdown and rebuilds the widget.

Parameters:: entry_index (int) – The index of the entry being selected, into items.
Return type:: None

build()[source]

Builds the closed dropdown: a box showing the selected entry’s label and an arrow indicator, wrapped in a GestureDetector that opens/closes the entry list overlay built by build_overlay.

Returns:: The widget built by this widget.
Return type:: Widget

tessella.widgets.enums module

class tessella.widgets.enums.PositionalAlignment(*values)[source]

Bases: Enum

Anchor points used to position a widget within an area, as used by Align and Stack.

TOP_LEFT = 1: Anchors to the top left corner.

TOP_CENTER = 2: Anchors to the top edge, centered horizontally.

TOP_RIGHT = 3: Anchors to the top right corner.

CENTER_LEFT = 4: Anchors to the left edge, centered vertically.

CENTER = 5: Anchors to the center of the area.

CENTER_RIGHT = 6: Anchors to the right edge, centered vertically.

BOTTOM_LEFT = 7: Anchors to the bottom left corner.

BOTTOM_CENTER = 8: Anchors to the bottom edge, centered horizontally.

BOTTOM_RIGHT = 9: Anchors to the bottom right corner.

class tessella.widgets.enums.MainAxisAlignment(*values)[source]

Bases: Enum

Controls how children are spaced along the main axis of a Row or Column.

START = 1: Packs the children at the start of the main axis, with no extra spacing.

CENTER = 2: Packs the children at the center of the main axis, with no extra spacing.

END = 3: Packs the children at the end of the main axis, with no extra spacing.

SPACE_BETWEEN = 4: Distributes the free space evenly between the children, with none before the first or after the last.

SPACE_AROUND = 5: Distributes the free space evenly around each child, with half of that space before the first and after the last.

SPACE_EVENLY = 6: Distributes the free space evenly between the children, as well as before the first and after the last.

class tessella.widgets.enums.CrossAxisAlignment(*values)[source]

Bases: Enum

Controls how children are aligned along the cross axis of a Row or Column.

START = 1: Aligns the children to the start of the cross axis.

CENTER = 2: Aligns the children to the center of the cross axis.

END = 3: Aligns the children to the end of the cross axis.

class tessella.widgets.enums.ClipBehavior(*values)[source]

Bases: Enum

Controls how a Stack deals with children that overflow its bounds.

NONE = 1: Does not clip overflowing content.

CLIP = 2: Clips content that overflows the widget’s bounds.

class tessella.widgets.enums.ImageFit(*values)[source]

Bases: Enum

Controls how an Image widget scales its image to fit its bounds.

CONTAIN = 1: Scales the image to fit entirely within the bounds, preserving its aspect ratio.

COVER = 2: Scales the image to fully cover the bounds, preserving its aspect ratio and clipping any overflow.

STRETCH = 3: Stretches the image to exactly fill the bounds, ignoring its aspect ratio.

class tessella.widgets.enums.SliderOrientation(*values)[source]

Bases: Enum

Controls the axis a Slider widget is laid out and dragged along.

HORIZONTAL = 1: The slider’s track runs left to right.

VERTICAL = 2: The slider’s track runs top to bottom.

class tessella.widgets.enums.TextAlign(*values)[source]

Bases: Enum

Controls the horizontal alignment of text within a TextWrap widget.

LEFT = 1: Aligns each wrapped line to the left.

RIGHT = 2: Aligns each wrapped line to the right.

CENTER = 3: Centers each wrapped line horizontally.

class tessella.widgets.enums.ScrollbarBehavior(*values)[source]

Bases: Enum

Controls when a Scrollable widget displays its scrollbar.

AUTO = 1: Only shows the scrollbar when the content overflows the viewport.

HIDDEN = 2: Never shows the scrollbar.

ALWAYS_VISIBLE = 3: Always shows the scrollbar, regardless of overflow.

tessella.widgets.flexible module

class tessella.widgets.flexible.Flexible(child, flex_factor=1)[source]

Bases: SingleChildWidget

A widget that has a flexible size depending on the content

Parameters:

child (Widget)
flex_factor (int)

flex_factor

An integer representing which fraction of the available space this widget should take.

Type:: int

NOTE: This widget only has effect inside Rows and Columns.

calculate_size(constraints)[source]

Calculates the size of this widget with the given constraints. Note that this widget MUST call apply_layout_constraints on its children if applicable. Must be implemented by subclasses.

Parameters:: constraints (WidgetConstraints) – The constraints to be used for determining the sizing of this widget.
Returns:: The calculated size for this widget
Return type:: tuple[int, int]

depends_on_child_size()[source]

A method that indicates whether this widget’s size depends on its child’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its child’s size.
Return type:: bool

depends_on_parent_size()[source]

A method that indicates whether this widget’s size depends on its parent’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its parent’s size.
Return type:: bool

tessella.widgets.gesture_detector module

class tessella.widgets.gesture_detector.GestureDetectorState[source]

Bases: WidgetState

The state object used by the GestureDetector widget.

is_pressed

Whether the GestureDetector is being held.

Type:: bool

is_hovered

Whether the GestureDetector is being hovered.

Type:: bool

class tessella.widgets.gesture_detector.GestureDetector(child, on_click=None, on_hover_start=None, on_hover_end=None, on_click_outside=None, on_drag_start=None, on_dragging=None, on_drag_end=None, key=None)[source]

Bases: StatefulWidget[GestureDetectorState]

A widget capable or detecting interactions via callbacks.

Parameters:

child (Widget)
on_click (Callable[[], None] | None)
on_hover_start (Callable[[], None] | None)
on_hover_end (Callable[[], None] | None)
on_click_outside (Callable[[], None] | None)
on_drag_start (Callable[[Event], None] | None)
on_dragging (Callable[[Event], None] | None)
on_drag_end (Callable[[Event], None] | None)
key (WidgetKey | None)

on_click

An optional callback function called when a click is detected.

Type:: Callable[[], None] | None

on_hover_start

An optional callback function called when it starts being hovered.

Type:: Callable[[], None] | None

on_hover_end

An optional callback function called when it stops being hovered.

Type:: Callable[[], None] | None

on_click_outside

An optional callback function called when a click happens OUTSIDE the widget.

Type:: Callable[[], None] | None

on_drag_start

An optional callback function called when the widget starts being dragged. Defaults to None.

Type:: Callable[[], None] | None

on_dragging

An optional callback function called when the widget is being dragged. Defaults to None.

Type:: Callable[[pygame.event.Event], None] | None

on_drag_end

An optional callback function called when the widget stops being dragged. Defaults to None.

Type:: Callable[[], None] | None

child

The child of this widget.

Type:: Widget

NOTE: This widget wraps its child.

create_state()[source]

Creates a new WidgetState subclass object, which holds the specific data of this widget implementation. Must be implemented by subclasses.

Raises:: NotImplementedError – This method must be implemented by a subclass.
Returns:: The WidgetState object related to this widget implementation.
Return type:: WidgetState[T]

build()[source]

Method called for building this widget. This method defaults to returning the widget itself, but custom widgets can override this method to return a more complex widget subtree.

Returns:: The Widget object built by this Widget.
Return type:: Widget

process_event(event, consumed=False)[source]

Processes pygame events to detect clicks, hovers and drags on the child, invoking the relevant callback for each:

A left MOUSEBUTTONDOWN on the child sets is_pressed and fires on_drag_start; one outside the child fires on_click_outside instead.
A left MOUSEBUTTONUP fires on_drag_end if the widget was pressed, and on_click if it was pressed and released while still over the child.
MOUSEMOTION fires on_dragging while pressed, and on_hover_start/on_hover_end when the pointer enters or leaves the child.

A collision is checked via self.child.collidepoint, and clicks are ignored if consumed is already True.

Parameters:

event (pygame.event.Event) – The pygame event to be processed.
consumed (bool) – Whether this event has been used or not.

Returns:

Whether this event was consumed by this widget.

Return type:

bool

tessella.widgets.image module

class tessella.widgets.image.Image(image, width=None, height=None, fit=ImageFit.CONTAIN, smooth_scale=True)[source]

Bases: Widget

A widget that displays a pygame.Surface as an image, optionally scaling it to fit a given size.

Parameters:

image (Surface)
width (int | None)
height (int | None)
fit (ImageFit)
smooth_scale (bool)

image

The image to be displayed.

Type:: pygame.Surface

width

The width of the widget, in pixels.

Type:: int | None

height

The height of the widget, in pixels.

Type:: int | None

scale_ratio

The scale factor last applied to image, computed by calculate_size according to fit.

Type:: float

fit

Controls how the image is scaled to fit its bounds.

Type:: ImageFit

smooth_scale

Whether to use smooth (bilinear-filtered) scaling instead of nearest-neighbor scaling.

Type:: bool

calculate_size(constraints)[source]

Calculates the size of the widget based on width/height (or the image’s own size, if left unset), then adjusts scale_ratio and the resulting size according to fit: ImageFit.CONTAIN scales the image down to fit entirely within the bounds, ImageFit.COVER scales it up to fully cover the bounds, and ImageFit.STRETCH leaves the size untouched.

Parameters:: constraints (WidgetConstraints) – The constraints to be used for determining the sizing of this widget.
Raises:: ValueError – If fit doesn’t match any ImageFit value.
Returns:: The calculated size for this widget.
Return type:: tuple[int, int]

depends_on_parent_size()[source]

A method that indicates whether this widget’s size depends on its parent’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its parent’s size.
Return type:: bool

tessella.widgets.listener module

class tessella.widgets.listener.Listener(observable, builder)[source]

Bases: SingleChildWidget

A Widget used for listening and reacting to changes in an observable object.

Parameters:

observable (Observable)
builder (Callable[[Observable], Widget])

observable

Observable object being watched.

Type:: Observable

builder

Function responsible for creating the Widget.

Type:: Callable[[Observable], Widget]

child

The Widget returned by self.builder.

Type:: Widget

calculate_size(constraints)[source]

Calculates the size of this widget with the given constraints. Note that this widget MUST call apply_layout_constraints on its children if applicable. Must be implemented by subclasses.

Parameters:: constraints (WidgetConstraints) – The constraints to be used for determining the sizing of this widget.
Returns:: The calculated size for this widget
Return type:: tuple[int, int]

dispose()[source]

Disposes of this widget and its child, as described in SingleChildWidget.dispose, then unsubscribes update_child from observable so it stops reacting to further changes.

Return type:: None

update_child()[source]

Rebuilds the child from scratch by calling builder again, discarding the previous one. Registered as a listener on observable, so this runs automatically whenever it changes.

Return type:: None

depends_on_parent_size()[source]

A method that indicates whether this widget’s size depends on its parent’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its parent’s size.
Return type:: bool

depends_on_child_size()[source]

A method that indicates whether this widget’s size depends on its child’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its child’s size.
Return type:: bool

tessella.widgets.multi_child_widget module

class tessella.widgets.multi_child_widget.MultiChildWidget(children=None)[source]

Bases: Widget

Baseclass for widgets with multiple children.

Parameters:: children (list[Widget] | None)

children

The children of this widget, if any.

Type:: list[Widget]

request_relayout()[source]

Invalidates this widget’s layout calculation, spreading the call to its parent as described in Widget.request_relayout, as well as to every child whose size depends on this widget’s size.

Return type:: None

process_event(event, consumed=False)[source]

Processes the given event, as described in Widget.process_event, then propagates it to every child, in order.

Parameters:

event (pygame.event.Event) – The pygame event to be processed.
consumed (bool) – Whether this event has been used or not.

Returns:

Whether this event was consumed by this widget or any of its children.

Return type:

bool

update(delta_time)[source]

Updates every child of this widget.

Parameters:: delta_time (float) – Time elapsed since the last frame in seconds.
Return type:: None

render(target_surface, debug_mode=False)[source]

Draws and renders this widget as described in Widget.render, then lays out (if needed) and renders each of its children on top of it, in order.

Parameters:

target_surface (pygame.Surface) – The surface to render the widget into.
debug_mode (bool) – Whether to render a debug version of the widget that has some layout lines to help with visualization. Defaults to False.

Return type:

None

dispose()[source]

Disposes of every child of this widget.

Return type:: None

set_position(new_position)[source]

Updates this widget’s position, as described in Widget.set_position, then repositions its children accordingly.

Parameters:: new_position (tuple[int, int]) – The new position for the topleft corner of this widget.
Return type:: None

abstractmethod depends_on_child_size()[source]

A method that indicates whether this widget’s size depends on its children’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its children’s size.
Return type:: bool

tessella.widgets.overlay module

class tessella.widgets.overlay.Overlay(child)[source]

Bases: SingleChildWidget

A widget that will be rendered as an overlay.

Parameters:: child (Widget)

active

Whether the widget should be visible or not.

Type:: bool

dispose()[source]

Disposes of this widget and its child, as described in SingleChildWidget.dispose, then unregisters it from OverlayManager so it stops being rendered.

Return type:: None

calculate_size(constraints)[source]

Calculates the size of this widget with the given constraints. Note that this widget MUST call apply_layout_constraints on its children if applicable. Must be implemented by subclasses.

Parameters:: constraints (WidgetConstraints) – The constraints to be used for determining the sizing of this widget.
Returns:: The calculated size for this widget
Return type:: tuple[int, int]

depends_on_child_size()[source]

A method that indicates whether this widget’s size depends on its child’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its child’s size.
Return type:: bool

depends_on_parent_size()[source]

A method that indicates whether this widget’s size depends on its parent’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its parent’s size.
Return type:: bool

tessella.widgets.padding module

class tessella.widgets.padding.EdgeInsets(left=0, top=0, right=0, bottom=0)[source]

Bases: object

A class represeting the directional padding offset used by a Padding widget.

Parameters:

left (int)
top (int)
right (int)
bottom (int)

left

The padding on the left side of the widget, in pixels.

Type:: int

top

The padding at the top of the widget, in pixels.

Type:: int

right

The padding on the right side of the widget, in pixels.

Type:: int

bottom

The padding at the bottom of the widget, in pixels.

Type:: int

classmethod symmetric(horizontal=0, vertical=0)[source]

A constructor for this class which only takes two arguments, representing the left/right and top/bottom padding, respectively.

Parameters:

horizontal (int) – Left/right padding, in pixels. Defaults to 0.
vertical (int) – Top/bottom padding, in pixels. Defaults to 0.

Returns:

A new EdgeInsets instance.

Return type:

EdgeInsets

classmethod all(size)[source]

A constructor for this class which only takes one argument, representing the padding on all sides.

Parameters:: size (int) – Left/top/right/bottom padding, in pixels.
Returns:: A new EdgeInsets instance.
Return type:: EdgeInsets

get_horizontal_padding()[source]

Returns:: The combined left and right padding, in pixels.
Return type:: int

get_vertical_padding()[source]

Returns:: The combined top and bottom padding, in pixels.
Return type:: int

class tessella.widgets.padding.Padding(padding, child)[source]

Bases: SingleChildWidget

A widget that surrounds its child with empty space, according to an EdgeInsets object.

Parameters:

padding (EdgeInsets)
child (Widget)

padding

The padding to apply around the child.

Type:: EdgeInsets

child

The child of this widget, if any.

Type:: Widget | None

calculate_size(constraints)[source]

Shrinks the available constraints by the combined horizontal and vertical padding, lays out the child within what’s left, then adds the padding back on top of the child’s size to get this widget’s final size.

Parameters:: constraints (WidgetConstraints) – The constraints to be used for determining the sizing of this widget.
Returns:: The calculated size for this widget.
Return type:: tuple[int, int]

render(target_surface, debug_mode=False)[source]

Renders this widget and its child as described in SingleChildWidget.render, using an intermediate OffsetSurface so that any content overflowing the padded area gets clipped.

Parameters:

target_surface (pygame.Surface) – The surface to render the widget into.
debug_mode (bool) – Whether to render a debug version of the widget that has some layout lines to help with visualization. Defaults to False.

Return type:

None

depends_on_child_size()[source]

A method that indicates whether this widget’s size depends on its child’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its child’s size.
Return type:: bool

depends_on_parent_size()[source]

A method that indicates whether this widget’s size depends on its parent’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its parent’s size.
Return type:: bool

tessella.widgets.placeholder module

class tessella.widgets.placeholder.Placeholder(width=None, height=None, box_color='#C97A7A', box_thickness=2, visible=True)[source]

Bases: Widget

A widget meant to be used as a placeholder child, which has no practical function whatsoever. This widget optionally renders a simple box to show its position.

Parameters:

width (int | None)
height (int | None)
box_color (str)
box_thickness (int)
visible (bool)

width

The width of the widget, in pixels.

Type:: int

height

The height of the widget, in pixels.

Type:: int

box_color

The color of the rendered box.

Type:: str

box_thickness

The thickness of the lines of the rendered box.

Type:: int

visible

Whether to render the box or not

Type:: bool

calculate_size(constraints)[source]

Calculates the size of this widget with the given constraints. Note that this widget MUST call apply_layout_constraints on its children if applicable. Must be implemented by subclasses.

Parameters:: constraints (WidgetConstraints) – The constraints to be used for determining the sizing of this widget.
Returns:: The calculated size for this widget
Return type:: tuple[int, int]

depends_on_parent_size()[source]

A method that indicates whether this widget’s size depends on its parent’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its parent’s size.
Return type:: bool

tessella.widgets.positioned module

class tessella.widgets.positioned.Positioned(child, left=None, right=None, top=None, bottom=None)[source]

Bases: SingleChildWidget

A widget capable of manually positioning its children in regards to the edges of the space available, usually inside a Stack widget.

Parameters:

child (Widget)
left (int | None)
right (int | None)
top (int | None)
bottom (int | None)

left

The left side offset, in pixels.

Type:: int | None

right

The right side offset, in pixels.

Type:: int | None

top

The top side offset, in pixels.

Type:: int | None

bottom

The bottom side offset, in pixels.

Type:: int | None

NOTE: left and right cannot be both set at once. The same applies for top and bottom.

set_position(new_position)[source]

Ignores new_position and instead derives this widget’s position from its parent’s bounds and its left/right/top/ bottom offsets, so that it stays correctly positioned regardless of layout changes elsewhere in the tree. Also repositions the child accordingly.

Parameters:: new_position (tuple[int, int]) – Unused; kept for signature compatibility with Widget.set_position.
Return type:: None

calculate_size(constraints)[source]

Shrinks the available constraints by whichever horizontal and vertical offsets are set, then lays out the child within what’s left.

Parameters:: constraints (WidgetConstraints) – The constraints to be used for determining the sizing of this widget.
Returns:: The calculated size for this widget.
Return type:: tuple[int, int]

depends_on_child_size()[source]

A method that indicates whether this widget’s size depends on its child’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its child’s size.
Return type:: bool

depends_on_parent_size()[source]

A method that indicates whether this widget’s size depends on its parent’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its parent’s size.
Return type:: bool

tessella.widgets.radio module

class tessella.widgets.radio.RadioState[source]

Bases: WidgetState

The state object used by the Radio widget.

is_hovered

Whether the radio button is currently being hovered.

Type:: bool

gesture_key

The key used by the inner GestureDetector in this widget.

Type:: WidgetKey

class tessella.widgets.radio.Radio(key, value, group_value, on_changed=None, size=20, style=None)[source]

Bases: StatefulWidget[RadioState]

A radio button that, together with other Radio widgets sharing the same group_value, allows a single value to be selected out of a group.

Parameters:

key (WidgetKey)
value (T)
group_value (ValueNotifier[T])
on_changed (Callable[[T], None] | None)
size (int)
style (RadioStyle | None)

value

The value this radio button represents. It is selected whenever group_value equals this.

Type:: T

group_value

The shared, observable value that determines which radio button in the group is selected. Every Radio widget in the same group should be given the same ValueNotifier instance.

Type:: ValueNotifier[T]

on_changed

An optional callback called with value whenever this radio button gets selected.

Type:: Callable[[T], None] | None

size

The size of the radio button’s box, in pixels. Both its width and height, since the box is square.

Type:: int

style

The styling object used to customize the visuals of this widget.

Type:: RadioStyle

dispose()[source]

Disposes of this widget and its child, as described in StatefulWidget, then unsubscribes from group_value so it stops reacting to further selection changes.

Return type:: None

create_state()[source]

Creates a new WidgetState subclass object, which holds the specific data of this widget implementation. Must be implemented by subclasses.

Raises:: NotImplementedError – This method must be implemented by a subclass.
Returns:: The WidgetState object related to this widget implementation.
Return type:: WidgetState[T]

on_click()[source]

Selects this radio button’s value in the group, if not already selected, and invokes on_changed. Updating group_value also triggers a rebuild of every other Radio widget sharing it, so they can deselect themselves.

Return type:: None

on_hover_start()[source]

Marks the radio button as hovered and rebuilds it, if it wasn’t already.

Return type:: None

on_hover_end()[source]

Marks the radio button as no longer hovered and rebuilds it, if it was.

Return type:: None

build()[source]

Builds the radio button as a square box whose color reacts to hovering, containing an inner square thumb that is only filled with style.thumb_color while value matches group_value.

Returns:: The widget built by this widget.
Return type:: Widget

tessella.widgets.row module

class tessella.widgets.row.Row(children=None, main_axis_alignment=MainAxisAlignment.START, cross_axis_alignment=CrossAxisAlignment.CENTER, shrink_wrap=False)[source]

Bases: MultiChildWidget

A widget capable of displaying its children in a row.

Parameters:

children (list[Widget] | None)
main_axis_alignment (MainAxisAlignment)
cross_axis_alignment (CrossAxisAlignment)
shrink_wrap (bool)

children

The list of children belonging to this widget.

Type:: list[Widget]

main_axis_alignment

Property which controls how the widgets are spaced in the row.

Type:: MainAxisAlignment

cross_axis_alignment

Property which controls how the widgets are aligned vertically in the row.

Type:: CrossAxisAlignment

shrink_wrap

Whether the row should shrink to fit its non-flexible children instead of taking up the whole main axis. Ignored if the row has any flexible children.

Type:: bool

calculate_size(constraints)[source]

Calculates the size of the row in two passes: first laying out non-flexible children to determine how much main axis space is left over, then splitting that leftover space between flexible children according to their flex_factor. If the row has any flexible children, or shrink_wrap is False, it takes up the whole main axis regardless of its children’s combined size.

Parameters:: constraints (WidgetConstraints) – The constraints to be used for determining the sizing of this widget.
Returns:: The calculated size for this widget.
Return type:: tuple[int, int]

render(target_surface, debug_mode=False)[source]

Renders this row and its children as described in MultiChildWidget.render, using an intermediate OffsetSurface so that any content overflowing the row’s bounds gets clipped.

Parameters:

target_surface (pygame.Surface) – The surface to render the widget into.
debug_mode (bool) – Whether to render a debug version of the widget that has some layout lines to help with visualization. Defaults to False.

Return type:

None

depends_on_parent_size()[source]

A method that indicates whether this widget’s size depends on its parent’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its parent’s size.
Return type:: bool

depends_on_child_size()[source]

A method that indicates whether this widget’s size depends on its children’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its children’s size.
Return type:: bool

tessella.widgets.scrollable module

class tessella.widgets.scrollable.ScrollableState[source]

Bases: WidgetState

The state object used by the Scrollable widget.

scroll_key

The key used by the inner scrollbar Slider, if visible.

Type:: WidgetKey

offset

How far the content has been scrolled down, in pixels.

Type:: int

built

Whether this widget has completed its first rebuild. Used to force one extra rebuild after the first frame, once inner_child’s real size is known; see Scrollable.update.

Type:: bool

class tessella.widgets.scrollable.Scrollable(child, scroll_style=None, scroll_behavior=None, key=None)[source]

Bases: StatefulWidget[ScrollableState]

A widget that makes its child scrollable vertically, clipping it to the space available and showing a scrollbar when appropriate.

Parameters:

child (Widget)
scroll_style (SliderStyle | None)
scroll_behavior (ScrollbarBehavior | None)
key (WidgetKey | None)

inner_child

The scrollable content. Note that this is distinct from the inherited child property, which holds the widget subtree built by build (viewport, clipping and scrollbar included).

Type:: Widget

scroll_style

The styling object used to customize the visuals of the scrollbar.

Type:: SliderStyle | None

scroll_behavior

Controls when the scrollbar is shown.

Type:: ScrollbarBehavior

create_state()[source]

Creates a new WidgetState subclass object, which holds the specific data of this widget implementation. Must be implemented by subclasses.

Raises:: NotImplementedError – This method must be implemented by a subclass.
Returns:: The WidgetState object related to this widget implementation.
Return type:: WidgetState[T]

calculate_size(constraints)[source]

Calculates the size of the viewport: at least as large as the available constraints, but expanded to fit the built child subtree if it happens to be bigger (e.g. once the scrollbar is accounted for).

Parameters:: constraints (WidgetConstraints) – The constraints to be used for determining the sizing of this widget.
Returns:: The calculated size for this widget.
Return type:: tuple[int, int]

update(delta_time)[source]

Forces a single extra rebuild right after the first frame. This is needed because inner_child’s real size (used to compute the max scroll value and the scrollbar’s thumb size) is only known after it has been laid out once.

Parameters:: delta_time (float) – Time elapsed since the last frame in seconds.

dispose()[source]

Disposes of this widget as described in StatefulWidget, and resets built so a freshly re-added Scrollable correctly forces its extra rebuild again.

Return type:: None

process_event(event, consumed=False)[source]

Processes events as described in StatefulWidget.process_event, additionally scrolling the content when the mouse wheel is used while the pointer is over this widget.

Parameters:

event (pygame.event.Event) – The pygame event to be processed.
consumed (bool) – Whether this event has been used or not.

Returns:

Whether this event was consumed by this widget or its children.

Return type:

bool

build()[source]

Builds the scrollable viewport: inner_child positioned with a negative top offset of state.offset inside a clipped Stack, next to an optional vertical scrollbar Slider bound to _on_scroll when _should_display_scrollbar returns True.

Returns:: The widget built by this widget.
Return type:: Widget

tessella.widgets.single_child_widget module

class tessella.widgets.single_child_widget.SingleChildWidget(child=None)[source]

Bases: Widget

Baseclass for widgets with a single child.

Parameters:: child (Widget | None)

child

The child of this widget, if any.

Type:: Widget | None

has_child()[source]

Checks if this widget has a child.

Returns:: Whether this widget has a child or not.
Return type:: bool

request_relayout()[source]

Invalidates this widget’s layout calculation, spreading the call to its parent as described in Widget.request_relayout, as well as to its child, if the child’s size depends on this widget’s size.

Return type:: None

process_event(event, consumed=False)[source]

Processes the given event, as described in Widget.process_event, then propagates it to the child, if any.

Parameters:

event (pygame.event.Event) – The pygame event to be processed.
consumed (bool) – Whether this event has been used or not.

Returns:

Whether this event was consumed by this widget or its child.

Return type:

bool

update(delta_time)[source]

Updates the child of this widget, if any.

Parameters:: delta_time (float) – Time elapsed since the last frame in seconds.
Return type:: None

render(target_surface, debug_mode=False)[source]

Draws and renders this widget as described in Widget.render, then lays out (if needed) and renders its child on top of it.

Parameters:

target_surface (pygame.Surface) – The surface to render the widget into.
debug_mode (bool) – Whether to render a debug version of the widget that has some layout lines to help with visualization. Defaults to False.

Return type:

None

dispose()[source]

Disposes of this widget, as well as its child, if any.

Return type:: None

set_position(new_position)[source]

Updates this widget’s position, as described in Widget.set_position, then repositions its child accordingly.

Parameters:: new_position (tuple[int, int]) – The new position for the topleft corner of this widget.
Return type:: None

abstractmethod depends_on_child_size()[source]

A method that indicates whether this widget’s size depends on its child’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its child’s size.
Return type:: bool

tessella.widgets.sized_box module

class tessella.widgets.sized_box.SizedBox(width=None, height=None, child=None)[source]

Bases: SingleChildWidget

A box widget that can be used to limit the size its child or creating spaces between widgets.

Parameters:

width (int | None)
height (int | None)
child (Widget | None)

width

Width of the box, in pixels.

Type:: int | None

height

Height of the box, in pixels.

Type:: int | None

child

The child of this widget, if any.

Type:: Widget | None

calculate_size(constraints)[source]

Calculates the size of this widget with the given constraints. Note that this widget MUST call apply_layout_constraints on its children if applicable. Must be implemented by subclasses.

Parameters:: constraints (WidgetConstraints) – The constraints to be used for determining the sizing of this widget.
Returns:: The calculated size for this widget
Return type:: tuple[int, int]

depends_on_child_size()[source]

A method that indicates whether this widget’s size depends on its child’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its child’s size.
Return type:: bool

depends_on_parent_size()[source]

A method that indicates whether this widget’s size depends on its parent’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its parent’s size.
Return type:: bool

tessella.widgets.slider module

class tessella.widgets.slider.SliderState(initial_value)[source]

Bases: WidgetState

The state object used by the Slider widget.

Parameters:: initial_value (int)

gesture_key

The key used by the inner GestureDetector in this widget.

Type:: WidgetKey

thumb_position

The thumb’s position along the track, in pixels from the start of the track. This is a pixel offset, not a value in the min_value/max_value range; see get_value.

Type:: int

class tessella.widgets.slider.Slider(key, thickness=25, min_value=0, max_value=100, initial_value=0, on_changed=None, snap=True, orientation=SliderOrientation.HORIZONTAL, style=None, thumb_scale=None)[source]

Bases: StatefulWidget[SliderState]

A slider that lets the user pick a value within a range by dragging a thumb along a track.

Parameters:

key (WidgetKey)
thickness (int)
min_value (int)
max_value (int)
initial_value (int)
on_changed (Callable[[int], None] | None)
snap (bool)
orientation (SliderOrientation)
style (SliderStyle | None)
thumb_scale (float | None)

thickness

The thickness of the track (its height when horizontal, or its width when vertical), in pixels.

Type:: int

min_value

The minimum value the slider can be set to.

Type:: int

max_value

The maximum value the slider can be set to.

Type:: int

initial_value

The value the slider starts at, clamped between min_value and max_value.

Type:: int

on_changed

An optional callback called with the new value whenever the thumb moves to a different value.

Type:: Callable[[int], None] | None

snap

Whether the thumb should snap to the pixel positions that correspond to whole values, instead of moving freely along the track.

Type:: bool

orientation

Whether the track runs horizontally or vertically.

Type:: SliderOrientation

style

The styling object used to customize the visuals of this widget.

Type:: SliderStyle

thumb_scale

The thumb’s length as a fraction of the track’s length, clamped between 0 and 1. If None, the thumb’s length instead equals thickness.

Type:: float | None

get_value()[source]

Converts the thumb’s current pixel position into a value within the min_value/max_value range.

Returns:: The slider’s current value.
Return type:: int

set_value(value)[source]

Moves the thumb to the pixel position that corresponds to value (clamped between min_value and max_value), then forces the widget subtree to be rebuilt from scratch to reflect the new position.

Parameters:: value (int) – The value to move the thumb to.
Return type:: None

on_thumb_movement(event)[source]

Recalculates the thumb’s position based on the mouse and, if it changed, updates the state, rebuilds the widget and invokes on_changed with the new value. Used as the GestureDetector callback for drag start/end/movement.

Parameters:: event (pygame.event.Event) – The drag event that triggered this call. Unused, but required to match the GestureDetector drag callback signature.

apply_layout_constraints(constraints)[source]

Applies the given constraints as described in Widget.apply_layout_constraints, then re-applies initial_value via set_value, since the thumb’s pixel position depends on the track’s now-known size.

Parameters:: constraints (WidgetConstraints) – The constraints to be used for determining the sizing of this widget.
Returns:: The calculated size for this widget.
Return type:: tuple[int, int]

create_state()[source]

Creates a new WidgetState subclass object, which holds the specific data of this widget implementation. Must be implemented by subclasses.

Raises:: NotImplementedError – This method must be implemented by a subclass.
Returns:: The WidgetState object related to this widget implementation.
Return type:: WidgetState[T]

build()[source]

Builds the slider as a track Container, with a Positioned thumb offset by state.thumb_position along the main axis, wrapped in a GestureDetector that drives on_thumb_movement.

Returns:: The widget built by this widget.
Return type:: Widget

tessella.widgets.stack module

class tessella.widgets.stack.Stack(children=None, alignment=PositionalAlignment.TOP_LEFT, clip_behavior=ClipBehavior.NONE)[source]

Bases: MultiChildWidget

A widget capable of displaying its child on top of one another.

Parameters:

children (list[Widget] | None)
alignment (PositionalAlignment)
clip_behavior (ClipBehavior)

children

The list of children to be laid on top of one another. They will be laid in order, so the first widget will be at the bottom and so on.

Type:: list[Widget]

alignment

Controls how to align the widget within the space available.

Type:: PositionalAlignment

clip_behavior

Controls how to deal with overflowing content.

Type:: ClipBehavior

render(target_surface, debug_mode=False)[source]

Renders this stack and its children as described in MultiChildWidget.render. If clip_behavior is ClipBehavior.CLIP, an intermediate OffsetSurface is used so that any content overflowing the stack’s bounds gets clipped.

Parameters:

target_surface (pygame.Surface) – The surface to render the widget into.
debug_mode (bool) – Whether to render a debug version of the widget that has some layout lines to help with visualization. Defaults to False.

Return type:

None

calculate_size(constraints)[source]

Lays out every child with the same, unrestricted constraints, letting each one take up as much space as it needs. This widget always takes up the whole area available to it, regardless of its children’s sizes.

Parameters:: constraints (WidgetConstraints) – The constraints to be used for determining the sizing of this widget.
Returns:: The calculated size for this widget.
Return type:: tuple[int, int]

depends_on_child_size()[source]

A method that indicates whether this widget’s size depends on its children’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its children’s size.
Return type:: bool

depends_on_parent_size()[source]

A method that indicates whether this widget’s size depends on its parent’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its parent’s size.
Return type:: bool

tessella.widgets.stateful_widget module

class tessella.widgets.stateful_widget.WidgetKey[source]

Bases: object

A pseudo-class used as a unique identifier for stateful widgets.

Instances of WidgetKey are unique by default, but can be shared between widgets to explicitly share state.

class tessella.widgets.stateful_widget.WidgetState[source]

Bases: object

Base class used to represent the state of a widget, which is able to persist between reloads of the widget tree.

class tessella.widgets.stateful_widget.StatefulWidget(key=None)[source]

Bases: SingleChildWidget, Generic[T]

A widget which might implement a custom build method like StatelessWidget, while also being able to keep data between rebuilds.

Parameters:: key (WidgetKey | None)

class.__state_registry

Map responsible for holding state objects internally. This data is kept between rebuilds.

Type:: dict[WidgetKey, WidgetState]

key

Key used to retrieve the widget’s state object after it gets initialized. If this is None, this widget will keep creating a new state object whenever it is built.

Type:: WidgetKey | None

_child

Widget built by the build() method (lazily-initialized).

Type:: Widget | None

NOTE: If multiple widgets share the same key, the will share the same state object. This might be used intentionally, or cause problems if a widget ends up retrieving a different WidgetState subclass than it expected to find.

property state: T

This widget’s state object, lazily retrieved (or created) via get_state on first access.

Type:: WidgetState[T]

get_state()[source]

Retrives the state of this widget based on its key. If it is None, this method will always create a new state object.

Returns:: The state found/created for this widget.
Return type:: WidgetState[T]

abstractmethod create_state()[source]

Creates a new WidgetState subclass object, which holds the specific data of this widget implementation. Must be implemented by subclasses.

Raises:: NotImplementedError – This method must be implemented by a subclass.
Returns:: The WidgetState object related to this widget implementation.
Return type:: WidgetState[T]

property child: Widget

The widget built by this widget, built and laid out lazily on first access, then cached until invalidate_child is called.

Type:: Widget

invalidate_child()[source]

Disposes of the cached built child, if any, forcing this widget to call build again the next time its child is accessed. This should be called whenever a state change requires the widget subtree to be rebuilt.

Return type:: None

calculate_size(constraints)[source]

Calculates the size of this widget with the given constraints. Note that this widget MUST call apply_layout_constraints on its children if applicable. Must be implemented by subclasses.

Parameters:: constraints (WidgetConstraints) – The constraints to be used for determining the sizing of this widget.
Returns:: The calculated size for this widget
Return type:: tuple[int, int]

depends_on_parent_size()[source]

A method that indicates whether this widget’s size depends on its parent’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its parent’s size.
Return type:: bool

depends_on_child_size()[source]

A method that indicates whether this widget’s size depends on its child’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its child’s size.
Return type:: bool

tessella.widgets.stateless_widget module

class tessella.widgets.stateless_widget.StatelessWidget[source]

Bases: SingleChildWidget

A widget which implements a custom build method, effectively wrapping a widget subtree into a single widget.

property child: Widget

Ensures the widget is built before accessing it.

Returns:: The widget built by this widget.
Return type:: Widget

calculate_size(constraints)[source]

Calculates the size of this widget with the given constraints. Note that this widget MUST call apply_layout_constraints on its children if applicable. Must be implemented by subclasses.

Parameters:: constraints (WidgetConstraints) – The constraints to be used for determining the sizing of this widget.
Returns:: The calculated size for this widget
Return type:: tuple[int, int]

depends_on_parent_size()[source]

A method that indicates whether this widget’s size depends on its parent’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its parent’s size.
Return type:: bool

depends_on_child_size()[source]

A method that indicates whether this widget’s size depends on its child’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its child’s size.
Return type:: bool

tessella.widgets.switch module

class tessella.widgets.switch.SwitchState[source]

Bases: WidgetState

The state object used by the Switch widget.

is_active

Whether the switch is currently on.

Type:: bool

is_hovered

Whether the switch is currently being hovered.

Type:: bool

class tessella.widgets.switch.Switch(key, on_changed=None, height=20, style=None)[source]

Bases: StatefulWidget[SwitchState]

A switch that can be toggled on and off by clicking it.

Parameters:

key (WidgetKey)
on_changed (Callable[[bool], None] | None)
height (int)
style (SwitchStyle | None)

on_changed

An optional callback called with the new on/off state whenever it changes.

Type:: Callable[[bool], None] | None

height

The height of the switch’s track, in pixels. The track’s width is always twice this value.

Type:: int

style

The styling object used to customize the visuals of this widget.

Type:: SwitchStyle

create_state()[source]

Creates a new WidgetState subclass object, which holds the specific data of this widget implementation. Must be implemented by subclasses.

Raises:: NotImplementedError – This method must be implemented by a subclass.
Returns:: The WidgetState object related to this widget implementation.
Return type:: WidgetState[T]

on_click()[source]

Toggles is_active, invokes on_changed and rebuilds the widget.

Return type:: None

on_hover_start()[source]

Marks the switch as hovered and rebuilds it, unless it was already hovered or is on (both of which already use style.active_color, so a rebuild wouldn’t change anything).

Return type:: None

on_hover_end()[source]

Marks the switch as no longer hovered and rebuilds it, unless it is on (in which case it keeps using style.active_color regardless of hover, so a rebuild wouldn’t change anything).

Return type:: None

build()[source]

Builds the switch as a pill-shaped track whose color reacts to being on or hovered, containing a draggable-looking thumb that slides to the end of the track while on.

Returns:: The widget built by this widget.
Return type:: Widget

tessella.widgets.text module

class tessella.widgets.text.Text(text, style=None)[source]

Bases: Widget

A simple Text widget.

Parameters:

text (str)
style (TextStyle | None)

text

Text to be displayed.

Type:: str

style

Styling used for rendering the text.

Type:: TextStyle

calculate_size(constraints)[source]

Calculates the size of this widget with the given constraints. Note that this widget MUST call apply_layout_constraints on its children if applicable. Must be implemented by subclasses.

Parameters:: constraints (WidgetConstraints) – The constraints to be used for determining the sizing of this widget.
Returns:: The calculated size for this widget
Return type:: tuple[int, int]

depends_on_parent_size()[source]

A method that indicates whether this widget’s size depends on its parent’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its parent’s size.
Return type:: bool

tessella.widgets.text_field module

class tessella.widgets.text_field.TextEditingController(text='')[source]

Bases: ValueNotifier[str]

A ValueNotifier specialized for holding and observing the text content of a TextField widget.

Multiple TextField widgets can share the same controller instance to stay in sync with one another, and external code can read or overwrite the current text at any time through text.

Parameters:: text (str)

property text: str

Alias for value, holding the current text content.

Type:: str

clear()[source]

Clears the text content, setting it back to an empty string.

Return type:: None

class tessella.widgets.text_field.TextFieldState[source]

Bases: WidgetState

The state object used by the TextField widget.

is_focused

Whether the field is currently focused and accepting keyboard input.

Type:: bool

cursor_position

The index into the controller’s text where the cursor currently sits.

Type:: int

selection_anchor

The index the current selection was started from, if any. The selected range spans between this and cursor_position, in either order.

Type:: int | None

cursor_visible

Whether the blinking cursor is currently visible. Toggled every _CURSOR_BLINK_INTERVAL_MS while focused.

Type:: bool

blink_timer

Milliseconds accumulated since the cursor last toggled visibility.

Type:: float

scroll_offset

How far the text is scrolled left, in pixels, so the cursor stays visible when the text overflows the field’s width.

Type:: int

gesture_key

The key used by the inner GestureDetector in this widget.

Type:: WidgetKey

class tessella.widgets.text_field.TextField(key, controller=None, hint_text='', width=200, height=36, on_changed=None, on_submit=None, style=None)[source]

Bases: StatefulWidget[TextFieldState]

A single-line text input that can be focused by clicking it, edited with the keyboard (including selection and clipboard shortcuts), and observed/driven externally through a TextEditingController.

Parameters:

key (WidgetKey)
controller (TextEditingController | None)
hint_text (str)
width (int | None)
height (int | None)
on_changed (Callable[[str], None] | None)
on_submit (Callable[[str], None] | None)
style (TextFieldStyle | None)

controller

The observable holding this field’s text content.

Type:: TextEditingController

hint_text

Text displayed in place of the content while the field is empty and unfocused.

Type:: str

width

The width of the field’s box, in pixels.

Type:: int | None

height

The height of the field’s box, in pixels.

Type:: int | None

on_changed

An optional callback called with the new text whenever it changes.

Type:: Callable[[str], None] | None

on_submit

An optional callback called with the current text whenever Enter is pressed while the field is focused.

Type:: Callable[[str], None] | None

style

The styling object used to customize the visuals of this widget.

Type:: TextFieldStyle

Supported keyboard interactions while focused:

Typing inserts text at the cursor (or replaces the selection).
Left/Right move the cursor by one character; holding either repeats via pygame.key.set_repeat.
Ctrl+Left/Right jumps by whole words.
Shift+Left/Right/Home/End extends the selection; adding Ctrl extends it by whole words.
Backspace/Delete remove the previous/next character, or the selection if any.
Ctrl+A/C/X/V select all, copy, cut and paste, using pyperclip for the system clipboard.
Enter invokes on_submit.

Clicking the field focuses it and places the cursor at the clicked character, using pygame.font.Font.size to measure where each character falls.

NOTE: Only one TextField can be focused at a time; focusing one blurs whichever other instance (if any) was previously focused. pygame.key.start_text_input/stop_text_input and pygame.key.set_repeat are toggled accordingly, since both are process-wide pygame settings.

dispose()[source]

Blurs this field if it was the focused one (releasing the process-wide text input/key repeat state), then disposes of this widget and its child, as described in StatefulWidget, and unsubscribes from controller so it stops reacting to further text changes.

Return type:: None

create_state()[source]

Creates a new WidgetState subclass object, which holds the specific data of this widget implementation. Must be implemented by subclasses.

Raises:: NotImplementedError – This method must be implemented by a subclass.
Returns:: The WidgetState object related to this widget implementation.
Return type:: WidgetState[T]

on_click_start(event)[source]

Focuses the field and places the cursor at the character under the click, if any. Bound to the inner GestureDetector’s on_drag_start, which fires on mouse-down rather than mouse-up, so the field reacts as soon as it’s pressed.

Parameters:: event (pygame.event.Event) – The MOUSEBUTTONDOWN event.
Return type:: None

on_click_outside()[source]

Blurs the field when a click lands outside of it.

Return type:: None

update(delta_time)[source]

Advances the cursor blink cycle while the field is focused and has no active selection, toggling state.cursor_visible and rebuilding every _CURSOR_BLINK_INTERVAL_MS.

Parameters:: delta_time (float) – Time elapsed since the last frame, in milliseconds (see _CURSOR_BLINK_INTERVAL_MS).
Return type:: None

process_event(event, consumed=False)[source]

Processes events as described in StatefulWidget.process_event (which also handles focusing/positioning through the inner GestureDetector), then, while focused, additionally handles TEXTINPUT for character entry and KEYDOWN for the shortcuts listed in the class docstring.

Parameters:

event (pygame.event.Event) – The pygame event to be processed.
consumed (bool) – Whether this event has been used or not.

Returns:

Whether this event was consumed by this widget or its children.

Return type:

bool

build()[source]

Builds the field as a box whose border reacts to focus, wrapped around the content built by _build_content and padded according to style.padding. The box is wrapped in a GestureDetector that focuses/positions the cursor on mouse-down and blurs the field on clicks outside.

Returns:: The widget built by this widget.
Return type:: Widget

tessella.widgets.text_wrap module

class tessella.widgets.text_wrap.TextWrap(text, style=None, word_split=True)[source]

Bases: StatelessWidget

A widget that displays text broken up into multiple lines, so that it never exceeds the width available to it.

Parameters:

text (str)
style (TextWrapStyle | None)
word_split (bool)

text

Text to be displayed.

Type:: str

style

Styling used for rendering the text.

Type:: TextWrapStyle

word_split

Whether to break lines at word boundaries instead of at any character.

Type:: bool

split_text(width_available, word_split=True)[source]

Splits text into a list of lines that each fit within width_available, according to the current text style’s font. Existing newlines in text are always respected as paragraph breaks, including consecutive ones, which produce empty lines.

Parameters:

width_available (int) – The maximum width a line of text can take, in pixels.
word_split (bool) – If True, lines are broken at word boundaries, dropping whole words that don’t fit onto the next line. If False, lines are broken at any character. Defaults to True.

Returns:

The text, split into lines that fit within width_available.

Return type:

list[str]

build()[source]

Builds the widget subtree that displays the wrapped text: one Text widget per line, separated by SizedBox spacers sized according to style.line_spacing, laid out in a shrink-wrapped Column.

Returns:: The widget built by this widget.
Return type:: Widget

tessella.widgets.widget module

class tessella.widgets.widget.Widget[source]

Bases: ABC

The baseclass for pretty much everything else.

bounds

The area occupied by this widget.

Type:: pygame.Rect

surface

The widget’s rendered surface, if any.

Type:: pygame.Surface | None

contraints

The constraints used to build this widget.

Type:: WidgetConstraints

flex_factor

The flex factor used by this widget on flexible layouts.

Type:: int | None

__is_drawn

Whether this widget is drawn or not. Should be manipulated using the methods request_redraw, is_draw and mark_as_drawn.

Type:: bool

__is_laid

Whether this widget’s size has been determined by calling apply_layout_constraints to it Should be manipulated using the methods request_relayout, is_laid and mark_as_laid.

Type:: bool

in_update_cycle

Whether this widget is part of the current relayout calculation. Used to avoid infinite recursion.

Type:: bool

parent

The parent of this widget, if any.

Type:: Widget | None

property bitmask: Mask

A lazy-initialized bitmask used for precise collision checks in some widgets. Laying out the widget and calling get_bitmask on it if it hasn’t been computed yet.

Type:: pygame.Mask

get_bitmask()[source]

Returns the bitmask used by this widget. Can be overwriten by custom widgets that require a custom collision mask.

NOTE: The return value for this function will also be used for self.bitmask.

Returns:: The mask to be used by this widget.
Return type:: pygame.Mask

collidepoint(point)[source]

Checks if a point lands inside this widget. Can be overwriten by custom widgets that require a custom collision check.

Parameters:: point (tuple[int, int]) – The point to check for collisions.
Returns:: Whether the point is inside the widget or not.
Return type:: bool

request_redraw()[source]

Marks this widget to be redraw on the next time it tries to render. This should only be called when the content of the widget is updated.

Return type:: None

is_drawn()[source]

Checks whether the widget is currently draw or not.

Returns:: Whether the widget is draw or not.
Return type:: bool

mark_as_drawn()[source]

Marks the widget as drawn to avoid unnecessary redraws when the content has not changed between frames.

Return type:: None

request_relayout()[source]

Invalidates this widgets layout calculation and spreads the call to other affected widgets. For example, if the parent of this widget depends on the size of its child, it will also be marked for relayout.

Return type:: None

is_laid()[source]

Checks whether this widget’s size has been calculated.

Returns:: Whether this widget’s has been calculated.
Return type:: bool

mark_as_laid()[source]

Marks this widget as laid, which means it has a set size.

Return type:: None

build()[source]

Method called for building this widget. This method defaults to returning the widget itself, but custom widgets can override this method to return a more complex widget subtree.

Returns:: The Widget object built by this Widget.
Return type:: Widget

calculate_layout(available_area)[source]

Calculates the layout sizing of this widget using the given rect.

Parameters:: available_area (pygame.Rect) – The area available for this widget to use.
Return type:: None

process_event(event, consumed=False)[source]

Process pygame events, being able to consume them if needed. If a widget consumes an event, it will keep being propagated but will not be used again.

Parameters:

event (pygame.event.Event) – The pygame event to be processed.
consumed (bool) – Whether this event has been used or not.

Returns:

Whether this event was consumed or not. Used to avoid having multiple widgets reacting to the same event. By default, this method returns consumed.

Return type:

bool

update(delta_time)[source]

Method called every frame to update this widget. This method should also call the update of its children, if applicable.

Parameters:: delta_time (float) – Time elapsed since the last frame in seconds.
Return type:: None

render(target_surface, debug_mode=False)[source]

Draws the widget if needed and renders it on the given surface.

Parameters:

target_surface (pygame.Surface) – The surface to render the widget into.
debug_mode (bool) – Whether to render a debug version of the widget that has some layout lines to help with visualization. Defaults to False.

Return type:

None

dispose()[source]

Method called when this widget gets discarded from the widget tree. This method is meant to be used as a way to clear all references this object might have so that it can be garbage collected.

Return type:: None

set_position(new_position)[source]

Updates this widget’s position. Usually called by its parent to position it correctly.

Parameters:: new_position (tuple[int, int]) – The new position for the topleft corner of this widget.
Return type:: None

apply_layout_constraints(constraints)[source]

Builds the widget using the given layout constraints.

Parameters:: constraints (WidgetConstraints) – The constraints to be used for determining the sizing of this widget.
Returns:: The calculated size for this widget
Return type:: tuple[int, int]

get_bounds()[source]

Return the bounds of this widget as a pygame.Rect.

Returns:: The bounds of this widget.
Return type:: pygame.Rect

abstractmethod calculate_size(constraints)[source]

Calculates the size of this widget with the given constraints. Note that this widget MUST call apply_layout_constraints on its children if applicable. Must be implemented by subclasses.

Parameters:: constraints (WidgetConstraints) – The constraints to be used for determining the sizing of this widget.
Returns:: The calculated size for this widget
Return type:: tuple[int, int]

abstractmethod depends_on_parent_size()[source]

A method that indicates whether this widget’s size depends on its parent’s size. This method is used to conditionally propagate relayouts across the widget tree only to affected widgets. Must be implemented by subclasses.

Returns:: Whether this widget’s size depends on its parent’s size.
Return type:: bool