batgrl.gadgets.flat_toggle#

An animated toggle button gadget.

Classes

FlatToggle(*[, callback, group, ...])

An animated toggle button gadget.

class batgrl.gadgets.flat_toggle.FlatToggle(*, callback: Callable[[Literal['on', 'off']], None] | None = None, group: None | Hashable = None, allow_no_selection: bool = False, always_release: bool = False, default_cell: ndarray[Any, dtype[dtype(['char', '<U1', 'bold', '?', 'italic', '?', 'underline', '?', 'strikethrough', '?', 'overline', '?', 'reverse', '?', 'fg_color', 'u1', 3, 'bg_color', 'u1', 3])]] | str = ' ', alpha: float = 0.0, size: Size = (1, 3), 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: ToggleButtonBehavior, Text

An animated toggle button gadget.

Parameters:

callbackCallable[ToggleState], None] | None, default: None: Called when button is released.
groupHashable | None, default: None: If a group is provided, only one button in a group can be in the on state.
allow_no_selectionbool, default: False: If a group is provided, setting this to true allows no selection, i.e., every button can be in the off state.
always_releasebool, default: False: Whether a mouse up event outside the button will trigger it.
default_cellNDArray[Cell] | str, default: “ “: Default cell of text canvas.
alphafloat, default: 0.0: Transparency of gadget.
sizeSize, default: Size(1, 3): 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:

callbackCallable[[ToggleState], None] | None: Called when button is released.
groupHashable | None: If a group is provided, only one button in a group can be in the on state.
allow_no_selectionbool: If true and button is in a group, every button can be in the off state.
toggle_stateToggleState: Toggle state of button.
always_releasebool: Whether a mouse up event outside the button will trigger it.
button_stateButtonState: Current button state.
canvasNDArray[Cell]: The array of characters for the gadget.
default_cellNDArray[Cell]: Default character for text canvas.
default_fg_colorColor: Foreground color of default character.
default_bg_colorColor: Background color of default character.
alphafloat: Transparency of gadget.
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.
parent: Gadget | 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

on_toggle()	Triggled on toggle state change.
update_off()	Paint the off state.
update_on()	Paint the on state.
on_release()	Triggered when a button is released.
update_normal()	Paint the normal state.
update_hover()	Paint the hover state.
update_down()	Paint the down state.
update_disallowed()	Paint the disallowed state.
add_border(style=”light”, …)	Add a border to the gadget.
add_syntax_highlighting(lexer, style)	Add syntax highlighting to current text in canvas.
add_str(str, pos, …)	Add a single line of text to the canvas.
set_text(text, …)	Resize gadget to fit text, erase canvas, then fill canvas with text.
clear()	Fill canvas with default cell.
shift(n=1)	Shift content in canvas up (or down in case of negative n).
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_border(style: Literal['light', 'heavy', 'double', 'curved', 'ascii', 'outer', 'inner', 'thick', 'dashed', 'dashed_2', 'dashed_3', 'heavy_dashed', 'heavy_dashed_2', 'heavy_dashed_3', 'near', 'mcgugan_tall', 'mcgugan_wide'] = 'light', bold: bool = False, fg_color: Color | None = None, bg_color: Color | None = None)#

Add a text border (gadget height and width must be at least 2).

Parameters:

styleBorder, default: “light”: Style of border. Default style uses light box-drawing characters.
boldbool, default: False: Whether the border is bold.
fg_colorColor | None, default: None: Foreground color of border if not None.
bg_colorColor | None, default: None: Background color of border if not None.

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.

add_str(str: str, *, pos: Point = (0, 0), fg_color: Color | None = None, bg_color: Color | None = None, markdown: bool = False, truncate_str: bool = False)#

Add a single line of text to the canvas at position pos.

If markdown is true, text can be styled using batgrl markdown. The syntax is: - italic: *this is italic text* - bold: **this is bold text** - strikethrough: ~~this is strikethrough text~~ - underlined: __this is underlined text__ - overlined: ^^this is overlined text^^

Parameters:

strstr: A single line of text to add to canvas.
posPoint, default: Point(0, 0): Position of first character of string. Negative coordinates position from the right or bottom of canvas (like negative indices).
fg_colorColor | None, default: None: Foreground color of text.
bg_colorColor | None, default: None: Background color of text.
markdownbool, default: False: Whether to parse text for batgrl markdown.
truncate_strbool, default: False: If false, an IndexError is raised if the text would not fit on canvas.