Skip to main content

Textual Inputs 🔡

Python Versions License: MIT Code style: black Imports: isort

Textual Inputs is a collection of input widgets for the Textual TUI framework.

⚠️ This library is experimental and its interfaces will change. While Textual Inputs is pre-alpha please pin your projects to the minor release number to avoid breaking changes. For example: textual-inputs=0.2.*

News

v0.2.6

  • Support for text overflow in TextInput
  • Patch for crash when IntegerInput is empty and backspace is pressed.

Quick Start

Installation

python -m pip install textual-inputs~=0.2.6

To use Textual Inputs

from textual_inputs import TextInput, IntegerInput

Checkout the examples for reference.

git clone https://github.com/sirfuzzalot/textual-inputs.git
cd textual-inputs
python3 -m venv venv
source venv/bin/activate
python -m pip install -e .
python examples/simple_form.py

Widgets

TextInput 🔡

  • value - string
  • one line of text with overflow support
  • placeholder and title support
  • password mode to hide input
  • syntax mode to highlight code
  • support for Unicode characters
  • controls: arrow right/left, home, end, delete, backspace/ctrl+h, escape
  • emits - InputOnChange, InputOnFocus messages

IntegerInput 🔢

  • value - integer or None
  • placeholder and title support
  • type a number or arrow up/down to increment/decrement the integer.
  • controls: arrow right/left, home, end, delete, backspace/ctrl+h, escape
  • emits - InputOnChange, InputOnFocus messages

Features

One-Line Syntax Highlighting

Textual Inputs takes advantage of rich's built-in Syntax feature. To add highlighting to your input text set the syntax argument to a language supported by pygments. Currently this is set to the default theme.

⚠️ THIS FEATURE IS LIMITED TO ONE LINE OF TEXT

TextInput(
    name="code",
    placeholder="enter some python code...",
    title="Code",
    syntax="python",
)

Event Handlers

Textual Inputs helps make the event handler process easier by providing the following convenient properties for inputs.

  • on_change_handler_name
  • on_focus_handler_name
email = TextInput(name="email", title="Email")
email.on_change_handler_name = "handle_email_on_change"
email.on_focus_handler_name = "handle_email_on_focus"

Under the hood setting this attribute this will generate a Message class with the appropriate name for Textual to send it to the handler name provided. You'll then want add the handler to the input's parent or the App instance. If you opt not to customize these handlers, their values will be the default handle_input_on_change and handle_input_on_focus. See examples/simple_form.py for a working example.

API Reference

Textual Inputs has two widgets, here are their attributes.

class TextInput(Widget):
    """
    A simple text input widget.

    Args:
        name (Optional[str]): The unique name of the widget. If None, the
            widget will be automatically named.
        value (str, optional): Defaults to "". The starting text value.
        placeholder (str, optional): Defaults to "". Text that appears
            in the widget when value is "" and the widget is not focused.
        title (str, optional): Defaults to "". A title on the top left
            of the widget's border.
        password (bool, optional): Defaults to False. Hides the text
            input, replacing it with bullets.
        syntax (Optional[str]): the name of the language for syntax highlighting.

    Attributes:
        value (str): the value of the text field
        placeholder (str): The placeholder message.
        title (str): The displayed title of the widget.
        has_password (bool): True if the text field masks the input.
        syntax (Optional[str]): the name of the language for syntax highlighting.
        has_focus (bool): True if the widget is focused.
        cursor (Tuple[str, Style]): The character used for the cursor
            and a rich Style object defining its appearance.
        on_change_handler_name (str): name of handler function to be
            called when an on change event occurs. Defaults to
            handle_input_on_change.
        on_focus_handler_name (name): name of handler function to be
            called when an on focus event occurs. Defaults to
            handle_input_on_focus.

    Events:
        InputOnChange: Emitted when the contents of the input changes.
        InputOnFocus: Emitted when the widget becomes focused.

    Examples:

    .. code-block:: python

        from textual_inputs import TextInput

        email_input = TextInput(
            name="email",
            placeholder="enter your email address...",
            title="Email",
        )

    """
class IntegerInput(Widget):
    """
    A simple integer input widget.

    Args:
        name (Optional[str]): The unique name of the widget. If None, the
            widget will be automatically named.
        value (Optional[int]): The starting integer value.
        placeholder (Union[str, int, optional): Defaults to "". Text that
            appears in the widget when value is "" and the widget is not focused.
        title (str, optional): Defaults to "". A title on the top left
            of the widget's border.

    Attributes:
        value (Union[int, None]): the value of the input field
        placeholder (str): The placeholder message.
        title (str): The displayed title of the widget.
        has_focus (bool): True if the widget is focused.
        cursor (Tuple[str, Style]): The character used for the cursor
            and a rich Style object defining its appearance.
        on_change_handler_name (str): name of handler function to be
            called when an on change event occurs. Defaults to
            handle_input_on_change.
        on_focus_handler_name (name): name of handler function to be
            called when an on focus event occurs. Defaults to
            handle_input_on_focus.

    Events:
        InputOnChange: Emitted when the contents of the input changes.
        InputOnFocus: Emitted when the widget becomes focused.

    Examples:

    .. code-block:: python

        from textual_inputs import IntegerInput

        age_input = IntegerInput(
            name="age",
            placeholder="enter your age...",
            title="Age",
        )

    """

Contributing

See the Contributing Guide.

Metadata

Release files for textual-inputs 0.2.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for textual-inputs 0.2.6
File Size Uploaded Provenance Actions
textual-inputs-0.2.6.tar.gz 10.8 kB Without provenance Details for textual-inputs-0.2.6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for textual-inputs 0.2.6
File Interpreter ABI Platform Actions
textual_inputs-0.2.6-py3-none-any.whl Python 3 none any Details for textual_inputs-0.2.6-py3-none-any.whl

Total release size: 22.2 kB

Release files / textual-inputs-0.2.6.tar.gz

Download URL textual-inputs-0.2.6.tar.gz
Size 10.8 kB
Tags Source
SHA-256 checksum
How to use checksums
bb571ee88d378a565190027c339770678f4cc57384b051fd6d594a0627a6c8fb
BLAKE2b-256 checksum
How to use checksums
6ccc3600389048dff976fc607272161aeee72d084b36730b7f72124902e44905
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/4.0.1 CPython/3.9.13

Release files / textual_inputs-0.2.6-py3-none-any.whl

Download URL textual_inputs-0.2.6-py3-none-any.whl
Size 11.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5fe988772453f78c755112728e4357da6a97a0b8627202c889089fc5e576998b
BLAKE2b-256 checksum
How to use checksums
3fd3ed99c7d38b86877f75545114355aeb57259278423df6f967737937468e5f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/4.0.1 CPython/3.9.13

Security for textual-inputs 0.2.6

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page