batgrl.gadgets.textbox

A textbox gadget for single-line editable text.

Classes

Textbox(*[, enter_callback, placeholder, ...])	A textbox gadget for single-line editable text.
_Box(*[, default_cell, alpha, size, pos, ...])
_Cursor([fg_color, bg_color])

class batgrl.gadgets.textbox.Textbox(*, enter_callback: Callable[[Textbox], None] | None = None, placeholder: str = '', hide_input: bool = False, hide_char: ndarray[Any, dtype[dtype(['char', '<U1', 'bold', '?', 'italic', '?', 'underline', '?', 'strikethrough', '?', 'overline', '?', 'reverse', '?', 'fg_color', 'u1', 3, 'bg_color', 'u1', 3])]] | str = '*', max_chars: int | None = None, is_grabbable: bool = True, ptf_on_grab: bool = False, mouse_button: Literal['left', 'middle', 'no_button', 'right'] = '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: Themable, Focusable, Grabbable, Gadget

A textbox gadget for single-line editable text.

Supports pasting, mouse selection, and cursor navigation.

Parameters:

enter_callbackCallable[[Textbox], None] | None, default: None

Called when textbox has focus and enter is pressed.

placeholderstr, default: “”

Placeholder text for textbox.

hide_inputbool, default: False

Whether input is hidden with hide_char.

hide_charstr, default: “*”

Character to hide input when hide_input is true.

max_charsint | None, default: None

Maximum allowed number of characters in textbox.

alphafloat, default: 1.0

Transparency of gadget.

is_grabbablebool, default: True

Whether grabbable behavior is enabled.

ptf_on_grabbool, default: False

Whether the gadget will be pulled to front when grabbed.

mouse_buttonMouseButton, default: “left”

Mouse button used for grabbing.

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:

enter_callbackCallable[[Textbox], None] | None

Called when textbox has focus and enter is pressed.

placeholderstr

Placeholder text for textbox.

hide_inputbool

Whether input is hidden with hide_char.

hide_charstr

Character to hide input when hide_input is true.

max_charsint | None

Maximum allowed number of characters in textbox.

alphafloat

Transparency of gadget.

textstr

The textbox’s text.

cursorint

The cursor column.

is_selectingbool

Whether there is a selection.

has_nonempty_selectionbool

Whether selection is non-empty.

is_focusedbool

Whether gadget has focus.

any_focusedbool

Whether any gadget has focus.

is_grabbablebool

Whether grabbable behavior is enabled.

ptf_on_grabbool

Whether the gadget will be pulled to front when grabbed.

mouse_buttonMouseButton

Mouse button used for grabbing.

is_grabbedbool

Whether gadget is grabbed.

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

undo()	Undo previous edit.
redo()	Redo previous undo.
select()	Start a new selection at cursor if none.
unselect()	Unselect current selection.
delete_selection()	Delete current selection.
move_cursor_left(n)	Move cursor left n characters.
move_cursor_right(n)	Move cursor right n characters.
move_word_left()	Move cursor a word left.
move_word_right()	Move cursor a word right.
update_theme()	Paint the gadget with current theme.
focus()	Focus gadget.
blur()	Un-focus gadget.
focus_next()	Focus next focusable gadget.
focus_previous()	Focus previous focusable gadget.
on_focus()	Update gadget when it gains focus.
on_blur()	Update gadget when it loses focus.
grab(mouse_event)	Grab the gadget.
ungrab(mouse_event)	Ungrab the gadget.
grab_update(mouse_event)	Update gadget with incoming mouse events while grabbed.
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.

property alpha: float

Transparency of gadget.

ancestors() → Iterator[Self]

Yield all ancestors of this gadget.

Yields:

Gadget

An ancestor of this gadget.

any_focused: bool = False

Whether any gadget has focus.

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.

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.

blur()

Un-focus gadget.

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.

property cursor: int

The cursor column.

delete_selection()

Delete current selection.

destroy() → None

Remove this gadget and recursively remove all its children.

dispatch_key(key_event) → bool | None

Dispatch key press only if focused.

dispatch_mouse(mouse_event) → bool | None

Focus if mouse event is 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.

enter_callback

Called when textbox has focus and enter is pressed.

focus()

Focus gadget.

classmethod focus_next()

Focus next focusable gadget.

classmethod focus_previous()

Focus previous focusable gadget.

grab(mouse_event)

Start selection on grab.

grab_update(mouse_event: MouseEvent)

Update selection on grab update.

property has_nonempty_selection: bool

Whether selection is non-empty.

property height: int

Height of gadget.

property hide_char: str

Character to hide input if hide_input is true.

hide_input

Whether input is hidden with hide_char.

property is_enabled: bool

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

property is_focused: bool

Whether gadget has focus.

property is_grabbed: bool

Whether gadget is grabbed.

property is_selecting: bool

Whether there is a selection.

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.

max_chars

Maximum allowed number of characters in textbox.

move_cursor_left(n: int = 1)

Move cursor left n characters.

move_cursor_right(n: int = 1)

Move cursor right n characters.

move_word_left()

Move cursor a word left.

move_word_right()

Move cursor a word right.

on_add()

Update theme.

on_blur()

Hide cursor on blur.

on_focus()

Show cursor and select all text on focus.

on_key(key_event: KeyEvent) → bool | None

Process key press.

on_mouse(mouse_event) → bool | None

Focus on mouse down collision and blur otherwise.

on_paste(paste_event: PasteEvent) → bool | None

Add paste to textbox.

on_remove()

Remove from focusable gadgets and blur on remove.

on_size()

Resize and reposition children 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 placeholder: str

Placeholder text for textbox.

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.

redo()

Redo previous undo.

remove_gadget(gadget: Self) → 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: Self | None

Return the root gadget if connected to gadget tree.

property rows: int

Height of gadget.

select()

Start a new selection at cursor if none.

classmethod set_theme(color_theme: ColorTheme)

Set color theme.

property size: Size

Size of gadget.

property size_hint: SizeHint

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

property text: str

The textbox’s text.

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: 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.

undo()

Undo previous edit.

ungrab(mouse_event)

Clear an empty selection on ungrab.

unselect()

Unselect current selection.

update_theme()

Paint the gadget with current theme.

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.