batgrl.gadgets.recycle_view#

A recycle-view provides a view into a large data-set using as few gadgets as possible.

Classes

RecycleView(*[, recycle_view_data, ...])

A recycle-view provides a view into a large data-set using as few gadgets as possible.

class batgrl.gadgets.recycle_view.RecycleView(*, recycle_view_data: list[T] | None = None, allow_vertical_scroll: bool = True, allow_horizontal_scroll: bool = True, show_vertical_bar: bool = True, show_horizontal_bar: bool = True, dynamic_bars: bool = False, scrollwheel_enabled: bool = True, arrow_keys_enabled: bool = True, is_grabbable: bool = True, ptf_on_grab: bool = False, mouse_button: MouseButton = 'left', alpha: float = 1.0, size: Size = (10, 10), pos: Point = (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: ScrollView, Generic

A recycle-view provides a view into a large data-set using as few gadgets as possible.

RecycleView is an abstract class. The following methods require an implementation:

get_layout(i): Return the size and position of the ith item in recycle_view_data.
new_data_view(): Initialize and return a new data-view gadget for the recycle view.
update_data_view(data_view, datum): Update data_view to display datum.

In addition, one may want to re-implement set_view_size() which sets the size of the view of all the data.

Parameters:

recycle_view_data: list[T] | None, default: None: The recycle-view’s data.
sizeSize, default: Size(10, 10): Size of gadget.
posPoint, 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:

recycle_view_data: list[T]: The recycle-view’s data.
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_hintSizeHint: Gadget’s size as a proportion of its parent’s size.
pos_hintPosHint: 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: The running app.

Methods

get_layout(i)	Return the size and position of the ith item of the recycle-view’s data.
new_data_view()	Initialize and return a new data-view gadget for the recycle-view.
update_data_view(data_view, datum)	Update `data_view` to display `datum`.
set_view_size()	Set the size of the view.
refresh_data()	Refresh data of currently visible data-views.
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(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 is 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 | None#: Absolute position on screen.

add_gadget(gadget: Self) → None#

Add a child gadget.

Parameters:

gadgetGadget: A gadget to add as a child.

add_gadgets(*gadgets: Self) → None#

Add multiple child gadgets.

Parameters:

*gadgetsGadget: Gadgets to add as children. Can also accept a single iterable of gadgets.

allow_horizontal_scroll#: Allow horizontal scrolling.

allow_vertical_scroll#: Allow vertical scrolling.

property alpha: float#: Transparency of gadget.

ancestors() → Iterator[Self]#

Yield all ancestors of this gadget.

Yields:

Gadget: An ancestor of this gadget.

property app#: 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.

arrow_keys_enabled#: Allow scrolling with arrow keys.

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: Self) → 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.

color_theme: _ColorTheme#

property columns: int#: Width of gadget.

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 dynamic_bars: bool#: Whether bars are shown/hidden depending on the view size.

abstract get_layout(i: int) → tuple[Size, Point]#

Return the size and position of the ith item of the recycle-view’s data.

Parameters:

iint: The index of an item in the recycle-view’s data.

Returns:

tuple[Size, Point]: The size and position of the item.

grab(mouse_event: MouseEvent)#

Grab gadget.

Parameters:

mouse_eventMouseEvent: The mouse event that grabbed the gadget.

grab_update(mouse_event: MouseEvent)#: Scroll on grab update.

property height: int#: Height of gadget.

property horizontal_proportion: float#: Horizontal scroll position as a proportion of total width.

property is_enabled: bool#: Whether gadget is enabled. A disabled gadget is not painted and doesn’t receive input events.

property is_grabbed: bool#: Whether gadget is grabbed.

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.

abstract new_data_view() → G#: Initialize and return a new data-view gadget for the recycle-view.

on_add() → None#: Bind the view’s size and pos to update the items in the view.

on_key(key_event: KeyEvent) → bool | None#: Scroll on arrows keys.

on_mouse(mouse_event: MouseEvent) → bool | None#: Scroll on mouse wheel.

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#: Unbind the view’s size and pos from updating the items in the view.

on_size() → None#: Update the recycle-view on 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 port_height: int#: Height of view port.

property port_width: int#: Width of view port.

property pos: Point#: Position relative to parent.

property pos_hint: PosHint#: 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.

recycle_view_data: list[T]#: The recycle-view’s data.

refresh_data() → None#: Refresh data of currently visible data-views.

remove_gadget(gadget: Gadget)#: Unbind from the view on its removal.

property right: int#: x-coordinate of right side of gadget.

property root: Self | None#: Return the root gadget if connected to gadget tree.

property rows: int#: Height of gadget.

scroll_down(n=1)#: Scroll the view down n lines.

scroll_left(n=1)#: Scroll the view left n characters.

scroll_right(n=1)#: Scroll the view right n characters.

scroll_to_rect(pos: Point, size: Size = (1, 1))#

Scroll the view so that a given rect is visible.

The rect is assumed to be within the view’s bounding box.

Parameters:

posPoint: Position of rect.
sizeSize, default: Size(1, 1): Size of rect.

scroll_up(n=1)#: Scroll the view up n lines.

scrollwheel_enabled#: Allow vertical scrolling with scrollwheel.

classmethod set_theme(color_theme: ColorTheme)#: Set color theme.

set_view_size() → None#

Set the size of the view.

The default implementation sets the view size to be the minimum size required to fully encompass the bottom-most, right-most rect returned by get_layout.

property show_horizontal_bar: bool#: Whether the horizontal scrollbar is shown.

property show_vertical_bar: bool#: Whether the vertical scrollbar is shown.

property size: Size#: Size of gadget.

property size_hint: SizeHint#: 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.

property total_horizontal_distance: int#: The distance the view can scroll horizontally.

property total_vertical_distance: int#: The distance the view can scroll vertically.

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: Real | ndarray[Any, dtype[number]] | Sequence[Real] | PosHint | SizeHint) → 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.
**propertiesReal | NDArray[np.number] | Sequence[Real] | PosHint | SizeHint: 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.

ungrab(mouse_event: MouseEvent)#

Ungrab gadget.

Parameters:

mouse_eventMouseEvent: The mouse event that ungrabbed the gadget.

abstract update_data_view(data_view: G, datum: T) → None#: Update data_view to display datum.

update_theme()#: Paint the gadget with current theme.

property vertical_proportion: float#: Vertical scroll position as a proportion of total height.

property view: Gadget | None#: The scrolled gadget.

walk() → Iterator[Self]#

Yield all descendents of this gadget (preorder traversal).

Yields:

Gadget: A descendent of this gadget.

walk_reverse() → Iterator[Self]#

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.