TextInput

A widget for the display and editing of a single line of text.

Usage

import toga

text_input = toga.TextInput()
text_input.value = "Jane Developer"

The input can be provided a placeholder value - this is a value that will be displayed to the user as a prompt for appropriate content for the widget. This placeholder will only be displayed if the widget has no content; as soon as a value is provided (either by the user, or programmatically), the placeholder content will be hidden.

The input can also be provided a list of validators. A validator is a function that will be invoked whenever the content of the input changes. The function should return None if the current value of the input is valid; if the current value is invalid, it should return an error message. When on_change is invoked, the field will automatically be validated based on specified validators.

Notes

  • Although an error message is provided when validation fails, Toga does not guarantee that this error message will be displayed to the user.

  • Winforms does not support the use of partially or fully transparent colors for the TextInput background. If a color with an alpha value is provided (including TRANSPARENT), the alpha channel will be ignored. A TRANSPARENT background will be rendered as white.

  • On Winforms, if a TextInput is given an explicit height, the rendered widget will not expand to fill that space. The widget will have the fixed height determined by the font used on the widget. In general, you should avoid setting a height style property on TextInput widgets.

Reference

class toga.TextInput(id=None, style=None, value=None, readonly=False, placeholder=None, on_change=None, on_confirm=None, on_gain_focus=None, on_lose_focus=None, validators=None, **kwargs)

Bases: Widget

Create a new single-line text input widget.

Parameters:

  • id (str | None) – The ID for the widget.

  • style (StyleT | None) – A style object. If no style is provided, a default style will be applied to the widget.

  • value (str | None) – The initial content to display in the widget.

  • readonly (bool) – Can the value of the widget be modified by the user?

  • placeholder (str | None) – The content to display as a placeholder when there is no user content to display.

  • on_change (toga.widgets.textinput.OnChangeHandler | None) – A handler that will be invoked when the value of the widget changes.

  • on_confirm (OnConfirmHandler | None) – A handler that will be invoked when the user accepts the value of the input (usually by pressing Return on the keyboard).

  • on_gain_focus (OnGainFocusHandler | None) – A handler that will be invoked when the widget gains input focus.

  • on_lose_focus (OnLoseFocusHandler | None) – A handler that will be invoked when the widget loses input focus.

  • validators (Iterable[Callable[[str], bool]] | None) – A list of validators to run on the value of the input.

  • kwargs – Initial style properties.

property is_valid: bool

Does the value of the widget currently pass all validators without error?

property on_change: OnChangeHandler

The handler to invoke when the value of the widget changes.

property on_confirm: OnConfirmHandler

The handler to invoke when the user accepts the value of the widget, usually by pressing return/enter on the keyboard.

property on_gain_focus: OnGainFocusHandler

The handler to invoke when the widget gains input focus.

property on_lose_focus: OnLoseFocusHandler

The handler to invoke when the widget loses input focus.

property placeholder: str

The placeholder text for the widget.

A value of None will be interpreted and returned as an empty string. Any other object will be converted to a string using str().

property readonly: bool

Can the value of the widget be modified by the user?

This only controls manual changes by the user (i.e., typing at the keyboard). Programmatic changes are permitted while the widget has readonly enabled.

property validators: list[Callable[[str], bool]]

The list of validators being used to check input on the widget.

Changing the list of validators will cause validation to be performed.

property value: str

The text to display in the widget.

A value of None will be interpreted and returned as an empty string. Any other object will be converted to a string using str().

Any newline (\n) characters in the string will be replaced with a space.

Validation will be performed as a result of changing widget value.

protocol toga.widgets.textinput.OnChangeHandler

typing.Protocol.

Classes that implement this protocol must have the following methods / attributes:

__call__(widget, **kwargs)

A handler to invoke when the text input is changed.

Parameters:

  • widget (TextInput) – The TextInput that was changed.

  • kwargs (Any) – Ensures compatibility with arguments added in future versions.

Return type:

object

protocol toga.widgets.textinput.OnConfirmHandler

typing.Protocol.

Classes that implement this protocol must have the following methods / attributes:

__call__(widget, **kwargs)

A handler to invoke when the text input is confirmed.

Parameters:

  • widget (TextInput) – The TextInput that was confirmed.

  • kwargs (Any) – Ensures compatibility with arguments added in future versions.

Return type:

object

protocol toga.widgets.textinput.OnGainFocusHandler

typing.Protocol.

Classes that implement this protocol must have the following methods / attributes:

__call__(widget, **kwargs)

A handler to invoke when the text input gains focus.

Parameters:

  • widget (TextInput) – The TextInput that gained focus.

  • kwargs (Any) – Ensures compatibility with arguments added in future versions.

Return type:

object

protocol toga.widgets.textinput.OnLoseFocusHandler

typing.Protocol.

Classes that implement this protocol must have the following methods / attributes:

__call__(widget, **kwargs)

A handler to invoke when the text input loses focus.

Parameters:

  • widget (TextInput) – The TextInput that lost focus.

  • kwargs (Any) – Ensures compatibility with arguments added in future versions.

Return type:

object