Skip to content

MultilineTextInput

Usage

import toga

textbox = toga.MultilineTextInput()
textbox.value = "Some text.\nIt can be multiple lines of text."

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.

Notes

  • Winforms does not support the use of partially or fully transparent colors for the MultilineTextInput 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.

Reference

Bases: Widget

Source code in core/src/toga/widgets/multilinetextinput.py 
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
class MultilineTextInput(Widget):
    def __init__(
        self,
        id: str | None = None,
        style: StyleT | None = None,
        value: str | None = None,
        readonly: bool = False,
        placeholder: str | None = None,
        on_change: toga.widgets.multilinetextinput.OnChangeHandler | None = None,
        **kwargs,
    ):
        """Create a new multi-line text input widget.

        :param id: The ID for the widget.
        :param style: A style object. If no style is provided, a default style
            will be applied to the widget.
        :param value: The initial content to display in the widget.
        :param readonly: Can the value of the widget be modified by the user?
        :param placeholder: The content to display as a placeholder when
            there is no user content to display.
        :param on_change: A handler that will be invoked when the value of
            the widget changes.
        :param kwargs: Initial style properties.
        """
        super().__init__(id, style, **kwargs)

        # Set a dummy handler before installing the actual on_change, because we do not
        # want on_change triggered by the initial value being set
        self.on_change = None
        self.value = value

        # Set all the properties
        self.readonly = readonly
        self.placeholder = placeholder
        self.on_change = on_change

    def _create(self) -> Any:
        return self.factory.MultilineTextInput(interface=self)

    @property
    def placeholder(self) -> 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()`.
        """
        return self._impl.get_placeholder()

    @placeholder.setter
    def placeholder(self, value: object) -> None:
        self._impl.set_placeholder("" if value is None else str(value))
        self.refresh()

    @property
    def readonly(self) -> 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.
        """
        return self._impl.get_readonly()

    @readonly.setter
    def readonly(self, value: object) -> None:
        self._impl.set_readonly(bool(value))

    @property
    def value(self) -> 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()`.
        """
        return self._impl.get_value()

    @value.setter
    def value(self, value: object) -> None:
        self._impl.set_value("" if value is None else str(value))
        self.refresh()

    def scroll_to_bottom(self) -> None:
        """Scroll the view to make the bottom of the text field visible."""
        self._impl.scroll_to_bottom()

    def scroll_to_top(self) -> None:
        """Scroll the view to make the top of the text field visible."""
        self._impl.scroll_to_top()

    @property
    def on_change(self) -> OnChangeHandler:
        """The handler to invoke when the value of the widget changes."""
        return self._on_change

    @on_change.setter
    def on_change(
        self, handler: toga.widgets.multilinetextinput.OnChangeHandler
    ) -> None:
        self._on_change = wrapped_handler(self, handler)

on_change property writable

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

placeholder property writable

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().

readonly property writable

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.

value property writable

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().

__init__(id=None, style=None, value=None, readonly=False, placeholder=None, on_change=None, **kwargs)

Create a new multi-line text input widget.

:param id: The ID for the widget. :param style: A style object. If no style is provided, a default style will be applied to the widget. :param value: The initial content to display in the widget. :param readonly: Can the value of the widget be modified by the user? :param placeholder: The content to display as a placeholder when there is no user content to display. :param on_change: A handler that will be invoked when the value of the widget changes. :param kwargs: Initial style properties.

Source code in core/src/toga/widgets/multilinetextinput.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
def __init__(
    self,
    id: str | None = None,
    style: StyleT | None = None,
    value: str | None = None,
    readonly: bool = False,
    placeholder: str | None = None,
    on_change: toga.widgets.multilinetextinput.OnChangeHandler | None = None,
    **kwargs,
):
    """Create a new multi-line text input widget.

    :param id: The ID for the widget.
    :param style: A style object. If no style is provided, a default style
        will be applied to the widget.
    :param value: The initial content to display in the widget.
    :param readonly: Can the value of the widget be modified by the user?
    :param placeholder: The content to display as a placeholder when
        there is no user content to display.
    :param on_change: A handler that will be invoked when the value of
        the widget changes.
    :param kwargs: Initial style properties.
    """
    super().__init__(id, style, **kwargs)

    # Set a dummy handler before installing the actual on_change, because we do not
    # want on_change triggered by the initial value being set
    self.on_change = None
    self.value = value

    # Set all the properties
    self.readonly = readonly
    self.placeholder = placeholder
    self.on_change = on_change

scroll_to_bottom()

Scroll the view to make the bottom of the text field visible.

Source code in core/src/toga/widgets/multilinetextinput.py 
101
102
103
def scroll_to_bottom(self) -> None:
    """Scroll the view to make the bottom of the text field visible."""
    self._impl.scroll_to_bottom()

scroll_to_top()

Scroll the view to make the top of the text field visible.

Source code in core/src/toga/widgets/multilinetextinput.py 
105
106
107
def scroll_to_top(self) -> None:
    """Scroll the view to make the top of the text field visible."""
    self._impl.scroll_to_top()

Bases: Protocol

Source code in core/src/toga/widgets/multilinetextinput.py 
11
12
13
14
15
16
17
class OnChangeHandler(Protocol):
    def __call__(self, widget: MultilineTextInput, **kwargs: Any) -> None:
        """A handler to invoke when the value is changed.

        :param widget: The MultilineTextInput that was changed.
        :param kwargs: Ensures compatibility with arguments added in future versions.
        """

__call__(widget, **kwargs)

A handler to invoke when the value is changed.

:param widget: The MultilineTextInput that was changed. :param kwargs: Ensures compatibility with arguments added in future versions.

Source code in core/src/toga/widgets/multilinetextinput.py 
12
13
14
15
16
17
def __call__(self, widget: MultilineTextInput, **kwargs: Any) -> None:
    """A handler to invoke when the value is changed.

    :param widget: The MultilineTextInput that was changed.
    :param kwargs: Ensures compatibility with arguments added in future versions.
    """