batgrl.gadgets.gadget#

Base class for all gadgets.

Module Attributes

Anchor

Point of gadget attached to a pos hint.

Functions

_normalize_pos_hint(pos_hint)

_normalize_size_hint(size_hint)

bindable(setter)

Decorate property setters to make them bindable.

Classes

Gadget(*[, size, pos, size_hint, pos_hint, ...])

Base class for creating gadgets.

PosHint

A position hint.

SizeHint

A size hint.

TotalPosHint

A position hint.

TotalSizeHint

A size hint.

_GadgetList()

A sequence of sibling gadgets.
batgrl.gadgets.gadget.Anchor#

Point of gadget attached to a pos hint.

alias of Literal[‘top-left’, ‘top’, ‘top-right’, ‘left’, ‘center’, ‘right’, ‘bottom-left’, ‘bottom’, ‘bottom-right’]

class batgrl.gadgets.gadget.Gadget(*, size: Sizelike = (10, 10), pos: Pointlike = (0, 0), size_hint: SizeHint | None = None, pos_hint: PosHint | None = None, is_transparent: bool = False, is_visible: bool = True, is_enabled: bool = True)#

Bases: object

Base class for creating gadgets.

Parameters:
sizeSizelike, default: Size(10, 10)

Size of gadget.

posPointlike, default: Point(0, 0)

Position of upper-left corner in parent.

size_hintSizeHint | None, default: None

Size as a proportion of parent’s height and width.

pos_hintPosHint | None, default: None

Position as a proportion of parent’s height and width.

is_transparentbool, default: False

Whether gadget is transparent.

is_visiblebool, default: True

Whether gadget is visible. Gadget will still receive input events if not visible.

is_enabledbool, default: True

Whether gadget is enabled. A disabled gadget is not painted and doesn’t receive input events.

Attributes:
sizeSize

Size of gadget.

heightint

Height of gadget.

rowsint

Height of gadget.

widthint

Width of gadget.

columnsint

Width of gadget.

posPoint

Position relative to parent.

topint

y-coordinate of top of gadget.

yint

y-coordinate of top of gadget.

leftint

x-coordinate of left side of gadget.

xint

x-coordinate of left side of gadget.

bottomint

y-coordinate of bottom of gadget.

rightint

x-coordinate of right side of gadget.

centerPoint

Position of center of gadget.

absolute_posPoint

Absolute position on screen.

size_hintTotalSizeHint

Gadget’s size as a proportion of its parent’s size.

pos_hintTotalPosHint

Gadget’s position as a proportion of its parent’s size.

parentGadget | None

Parent gadget.

childrenlist[Gadget]

Children gadgets.

is_transparentbool

Whether gadget is transparent.

is_visiblebool

Whether gadget is visible.

is_enabledbool

Whether gadget is enabled.

rootGadget | None

Return the root gadget if connected to gadget tree.

appApp | None

The running app.

Methods

apply_hints()

Apply size and pos hints.

to_local(point)

Convert point in absolute coordinates to local coordinates.

collides_point(point)

Return true if point collides with visible portion of gadget.

collides_gadget(other)

Return true if other is within gadget’s bounding box.

pull_to_front()

Move to end of gadget stack so gadget is drawn last.

walk()

Yield all descendents of this gadget (preorder traversal).

walk_reverse()

Yield all descendents of this gadget (reverse postorder traversal).

ancestors()

Yield all ancestors of this gadget.

add_gadget(gadget)

Add a child gadget.

add_gadgets(gadget_it, *gadgets)

Add multiple child gadgets.

remove_gadget(gadget)

Remove a child gadget.

prolicide()

Recursively remove all children.

destroy()

Remove this gadget and recursively remove all its children.

bind(prop, callback)

Bind callback to a gadget property.

unbind(uid)

Unbind a callback from a gadget property.

tween(…)

Sequentially update gadget properties over time.

on_size()

Update gadget after a resize.

on_transparency()

Update gadget after transparency enabled/disabled.

on_add()

Update gadget after being added to the gadget tree.

on_remove()

Update gadget after being removed from the gadget tree.

on_key(key_event)

Handle a key press event.

on_mouse(mouse_event)

Handle a mouse event.

on_paste(paste_event)

Handle a paste event.

on_terminal_focus(focus_event)

Handle a focus event.
property absolute_pos: Point#

Absolute position on screen.

add_gadget(gadget: Gadget) → None#

Add a child gadget.

Parameters:
gadgetGadget

A gadget to add as a child.

add_gadgets(gadget_it: Gadget | Iterable[Gadget], *gadgets: Gadget) → None#

Add multiple child gadgets.

Parameters:
gadget_itGadget | Iterable[Gadget]

A gadget or iterable of gadgets to add as children.

*gadgetsGadget

Gadgets to add as children.

ancestors() → Iterator[Gadget]#

Yield all ancestors of this gadget.

Yields:
Gadget

An ancestor of this gadget.

property app: App | None#

The running app.

apply_hints() → None#

Apply size and pos hints.

This is called automatically when the gadget is added to the gadget tree and when the gadget’s parent’s size changes.

bind(prop: str, callback: Callable[[], None]) → int#

Bind callback to a gadget property. When the property is updated, callback is called with no arguments.

Parameters:
propstr

The name of the gadget property.

callbackCallable[[], None]

Callback to bind to property.

Returns:
int

A unique id used to unbind the callback.

property bottom: int#

y-coordinate of bottom of gadget.

property center: Point#

Position of center of gadget.

children: _GadgetList#

The gadget’s children.

collides_gadget(other: Gadget) → bool#

Return true if other is within gadget’s bounding box.

Parameters:
otherGadget

Another gadget.

Returns:
bool

Whether other collides with gadget.

collides_point(point: Point) → bool#

Return true if point collides with visible portion of gadget.

Parameters:
pointPoint

A point.

Returns:
bool

Whether point collides with gadget.

property columns: int#

Alias for width.

destroy() → None#

Remove this gadget and recursively remove all its children.

dispatch_key(key_event: KeyEvent) → bool | None#

Dispatch a key press event until handled.

A key press event is handled if a handler returns True.

Parameters:
key_eventKeyEvent

The key event to dispatch.

Returns:
bool | None

Whether the dispatch was handled.

dispatch_mouse(mouse_event: MouseEvent) → bool | None#

Dispatch a mouse event until handled.

A mouse event is handled if a handler returns True.

Parameters:
mouse_eventMouseEvent

The mouse event to dispatch.

Returns:
bool | None

Whether the dispatch was handled.

dispatch_paste(paste_event: PasteEvent) → bool | None#

Dispatch a paste event until handled.

A paste event is handled if a handler returns True.

Parameters:
paste_eventPasteEvent

The paste event to dispatch.

Returns:
bool | None

Whether the dispatch was handled.

dispatch_terminal_focus(focus_event: FocusEvent) → bool | None#

Dispatch a focus event until handled.

A focus event is handled if a handler returns True.

Parameters:
focus_eventFocusEvent

The focus event to dispatch.

Returns:
bool | None

Whether the dispatch was handled.

property height: int#

Height of gadget.

property is_enabled: bool#

Whether gadget is enabled. A disabled gadget is not painted and doesn’t receive input events.

property is_transparent: bool#

Whether gadget is transparent.

property is_visible: bool#

Whether gadget is visible. Gadget will still receive input events if not visible.

property left: int#

x-coordinate of left side of gadget.

on_add() → None#

Update gadget after being added to the gadget tree.

on_key(key_event: KeyEvent) → bool | None#

Handle a key press event.

Handled key presses should return True.

Parameters:
key_eventKeyEvent

The key event to handle.

Returns:
bool | None

Whether the key event was handled.

on_mouse(mouse_event: MouseEvent) → bool | None#

Handle a mouse event.

Handled mouse events should return True.

Parameters:
mouse_eventMouseEvent

The mouse event to handle.

Returns:
bool | None

Whether the mouse event was handled.

on_paste(paste_event: PasteEvent) → bool | None#

Handle a paste event.

Handled paste events should return True.

Parameters:
paste_eventPasteEvent

The paste event to handle.

Returns:
bool | None

Whether the paste event was handled.

on_remove() → None#

Update gadget after being removed from the gadget tree.

on_size() → None#

Update gadget after a resize.

on_terminal_focus(focus_event: FocusEvent) → bool | None#

Handle a focus event.

Handled focus events should return True.

Parameters:
focus_eventFocusEvent

The focus event to handle.

Returns:
bool | None

Whether the focus event was handled.

on_transparency() → None#

Update gadget after transparency is enabled/disabled.

parent: Gadget | None#

The gadget’s parent.

property pos: Point#

Position relative to parent.

property pos_hint: TotalPosHint#

Gadget’s position as a proportion of its parent’s size.

prolicide() → None#

Recursively remove all children.

pull_to_front() → None#

Move gadget to end of gadget stack so that it is drawn last.

remove_gadget(gadget: Gadget) → None#

Remove a child gadget.

Parameters:
gadgetGadget

The gadget to remove from children.

property right: int#

x-coordinate of right side of gadget.

property root: _Root | None#

Return the root gadget if connected to gadget tree.

property rows: int#

Alias for height.

property size: Size#

Size of gadget.

property size_hint: TotalSizeHint#

Gadget’s size as a proportion of its parent’s size.

to_local(point: Point) → Point#

Convert point in absolute coordinates to local coordinates.

Parameters:
pointPoint

Point in absolute (screen) coordinates.

Returns:
Point

The point in local coordinates.

property top: int#

y-coordinate of top of gadget.

async tween(*, duration: float = 1.0, easing: Literal['linear', 'in_quad', 'out_quad', 'in_out_quad', 'in_cubic', 'out_cubic', 'in_out_cubic', 'in_quart', 'out_quart', 'in_out_quart', 'in_quint', 'out_quint', 'in_out_quint', 'in_sine', 'out_sine', 'in_out_sine', 'in_exp', 'out_exp', 'in_out_exp', 'in_circ', 'out_circ', 'in_out_circ', 'in_elastic', 'out_elastic', 'in_out_elastic', 'in_back', 'out_back', 'in_out_back', 'in_bounce', 'out_bounce', 'in_out_bounce'] = 'linear', on_start: Callable[[], None] | None = None, on_progress: Callable[[float], None] | None = None, on_complete: Callable[[], None] | None = None, **properties: Any) → None#

Coroutine that sequentially updates gadget properties over a duration (in seconds).

Parameters:
durationfloat, default: 1.0

The duration of the tween in seconds.

easingEasing, default: “linear”

The easing used for tweening.

on_startCallable[[], None] | None, default: None

Called when tween starts.

on_progressCallable[[float], None] | None, default: None

Called as tween updates with current progress.

on_completeCallable[[], None] | None, default: None

Called when tween completes.

**propertiesAny

Gadget properties’ target values. E.g., to smoothly tween a gadget’s position to (5, 10) over 2.5 seconds, specify the pos property as a keyword-argument: await gadget.tween(pos=(5, 10), duration=2.5, easing="out_bounce")

Warning

Running several tweens on the same properties concurrently will probably result in unexpected behavior.

Notes

Tweened values will be coerced to match the type of the initial value of their corresponding property.

Non-numeric values will be set immediately.

unbind(uid: int) → None#

Unbind a callback from a gadget property.

Parameters:
uidint

Unique id returned by the bind() method.

walk() → Iterator[Gadget]#

Yield all descendents of this gadget (preorder traversal).

Yields:
Gadget

A descendent of this gadget.

walk_reverse() → Iterator[Gadget]#

Yield all descendents of this gadget (reverse postorder traversal).

Yields:
Gadget

A descendent of this gadget.

property width: int#

Width of gadget.

property x: int#

x-coordinate of left side of gadget.

property y: int#

y-coordinate of top of gadget.

class batgrl.gadgets.gadget.PosHint#

Bases: TypedDict

A position hint.

A pos hint allows a gadget to automatically position itself when added to the gadget tree or when its parent resizes. y_hint controls vertical position and x_hint horizontal. anchor determines which point of the gadget is attached to the pos hint. For instance, in the diagram below, if the y_hint and x_hint are both 0.5 the pos hint will be at point c on the parent (50% of the parent’s height and width). Additionally, if the anchor is "top", the anchor will be at point a on the gadget:

     parent
+---------------+
|               |    +---a---+
|       c       |    |gadget |
|               |    +-------+
+---------------+

Subsequently, a will be aligned with c, so that the gadget is positioned as below:

     parent
+---------------+
|               |
|   +-------+   |
|   |gadget |   |
+---+-------+---+

The additional parameters y_offset and x_offset allow one to translate the gadget by some integer offsets after the pos hint has been applied.

Attributes:
anchorAnchor | tuple[float, float]

Determines which point is attached to the pos hint.

y_hintfloat | None

Vertical position as a proportion of parent’s height.

x_hintfloat | None

Horizontal position as a proportion of parent’s width.

y_offsetint

Vertical offset after pos hint is applied.

x_offsetint

Horizontal offset after pos hint is applied.

anchor: ReadOnly[Literal['top-left', 'top', 'top-right', 'left', 'center', 'right', 'bottom-left', 'bottom', 'bottom-right'] | tuple[float, float]]#

Determines which point is attached to the pos hint.

x_hint: ReadOnly[float | None]#

Horizontal position as a proportion of parent’s width.

x_offset: ReadOnly[int]#

Horizontal offset after pos hint is applied.

y_hint: ReadOnly[float | None]#

Vertical position as a proportion of parent’s height.

y_offset: ReadOnly[int]#

Vertical offset after pos hint is applied.

class batgrl.gadgets.gadget.SizeHint#

Bases: TypedDict

A size hint.

A size hint allows a gadget to automatically size itself when added to the gadget tree or when its parent resizes. height_hint is the proportion of the parent’s height the gadget’s height will be and width_hint the proportion of the parent’s width. Additional parameters height_offset and width_offset allow adjusting the size by some integer amount after the size hint has been applied. If given, min_height, max_height, min_width, and max_width will prevent the gadget from sizing too small or too large.

Attributes:
height_hintfloat | None

Height as a proportion of parent’s height.

width_hintfloat | None

Width as a proportion of parent’s width.

height_offsetint

Height offset after height-hint is applied.

width_offsetint

Width offset after width-hint is applied.

max_heightint | None

Maximum allowed height.

min_heightint | None

Minimum allowed height.

max_widthint | None

Maximum allowed width.

min_widthint | None

Minimum allowed width.

height_hint: ReadOnly[float | None]#

Height as a proportion of parent’s height.

height_offset: ReadOnly[int]#

Height offset after height-hint is applied.

max_height: ReadOnly[int | None]#

Maximum allowed height.

max_width: ReadOnly[int | None]#

Maximum allowed width.

min_height: ReadOnly[int | None]#

Minimum allowed height.

min_width: ReadOnly[int | None]#

Minimum allowed width.

width_hint: ReadOnly[float | None]#

Width as a proportion of parent’s width.

width_offset: ReadOnly[int]#

Width offset after width-hint is applied.

class batgrl.gadgets.gadget.TotalPosHint#

Bases: TypedDict

A position hint.

anchor: ReadOnly[tuple[float, float]]#
x_hint: ReadOnly[float | None]#
x_offset: ReadOnly[int]#
y_hint: ReadOnly[float | None]#
y_offset: ReadOnly[int]#
class batgrl.gadgets.gadget.TotalSizeHint#

Bases: TypedDict

A size hint.

height_hint: ReadOnly[float | None]#
height_offset: ReadOnly[int]#
max_height: ReadOnly[int | None]#
max_width: ReadOnly[int | None]#
min_height: ReadOnly[int | None]#
min_width: ReadOnly[int | None]#
width_hint: ReadOnly[float | None]#
width_offset: ReadOnly[int]#
batgrl.gadgets.gadget.bindable(setter)#

Decorate property setters to make them bindable.

On this page

This Page