Skip to content

The batteries included

We provide a growing selection of widgets you can drop straight into your projects. Looking at the widgets submodule's contents can help illuminate you on the exact selection, but this page describes the most commonly used ones.

A note about auto

Some widgets below will have an Auto syntax field shown. The format shown can be used by the auto function to generate widgets from Python datatypes. This function is conveniently called within Container and all its subclasses (Splitter, Window, Collapsible & more) to let you easily create widgets with minimal imports.

For example:

from pytermgui import Container

container = Container(
    "[bold accent]This is my example",
    "",
    "[surface+1 dim italic]It is very cool, you see",
    "",
    {"My first label": ["Some button"]},
    {"My second label": [False]},
    "",
    ("Left side", "Middle", "Right side"),
    "",
    ["Submit button"]
)

...is functionally identical to:

from pytermgui import Container, Label, Splitter, Button, Checkbox

container = Container(
    Label("[bold accent]This is my example"),
    Label(""),
    Label("[surface+1 dim italic]It is very cool, you see"),
    Label(""),
    Splitter(
        Label("My first label", parent_align=0),
        Button("Some button", parent_align=2),
    ),
    Splitter(
        Label("My second label"),
        Checkbox(),
    ),
    Label(""),
    Splitter(Label("Left side"), Label("Middle"), Label("Right side")),
    Label(""),
    Button("Submit button"),
)

You can use whichever you find more convenient and readable.

Label

A simple widget meant to display text. Supports line breaking and styling using both markup and simple callables.

Auto syntax: "label_value"

Chars: N/A

Styles:

  • value: Applies to the text within the label.

    Default: No styling.

Container

A widget to display other widgets, stacked vertically. It may display a box around said widgets as well, using the border and corner characters.

Auto syntax: N/A

Chars:

  • border: A list[str] in the order left, top, right, bottom that makes up the borders of the outer box.
  • corner: A list[str] in the order top_left, top_right, bottom_right, bottom_left that makes up the corners of the outer box.

Styles:

  • border: Applies to all border characters of the outer box.

    Default: surface.

  • corner: Applies to all corner characters of the outer box.

    Default: surface.

  • fill: Applies to the filler characters used for padding.

    Default: background.

Splitter

Similar to Container, but displays widgets stacked horizontally instead. Each widget is separated by the separator character set.

Auto syntax:

  • (widget1, widget2, ...)
  • {widget_aligned_left: widget_aligned_right}

Chars:

  • separator: The str used to join the contained widgets.

Styles:

  • separator: Applies to the separator character.

    Default: surface.

Collapsible

A widget that hides or shows whatever other widgets it is given. It will always display its "trigger", the Button used to collapse or expand its content.

Auto syntax: N/A

Chars:

  • See Container.

Styles:

  • See Container.

Window

An extended version of Container, used in the window_manager context.

Auto syntax: N/A

Chars:

See Container.

Styles:

Same as Container, but expanded with:

  • border_focused: Analogous to border, but only applied when the window is focused.

    Default: surface.

  • corner_focused: Analogous to corner, but only applied when the window is focused.

    Default: surface.

  • border_blurred: Analogous to border, but only applied when the window is NOT focused.

    Default: surface-2.

  • corner_blurred: Analogous to corner, but only applied when the window is NOT focused.

    Default: surface-2.

Button

Something clickable. All widgets can be made clickable by defining an on_click method, but this widget looks the part as well.

Auto syntax:

  • ["button_label", button_callback]

Chars:

  • delimiter: a list[str] in the order left, right. Each character will be placed at the respective sides of the label.

Styles:

All styles here apply to the full label, including the left and right hand side delimiters.

  • label: Applies in the normal state (e.g. no hover, click applied).

    Default: @surface dim.

  • highlight: Applies when the button is interacted with.

    Default: @surface+1 dim.

KeyboardButton

Much like button, but has a default binding applied to it. This binding is also reflected in its label.

Auto syntax: N/A

Chars:

  • All Button chars
  • bracket: Used to wrap the button's bound key.

Styles:

  • See Button.

Checkbox

A simple check box, you know the drill.

Auto syntax:

  • [bool_default, callback_method]

Chars:

  • delimiter: Wraps the checkbox's value
  • checked: The character inserted between delimiters when the widget is checked.
  • unchecked: The character inserted between delimiters when the widget is unchecked.

Styles:

  • See Button.

Toggle

A button that toggles its label between the two given values.

Auto syntax:

  • [("label_1", "label_2"), callback_method]

Chars:

  • See Button.

Styles:

  • See Button.

Slider

A widget to display and/or control a floating point value.

Auto syntax: N/A

Chars:

  • cursor: The character placed at the end of the filled section. If nothing is given, rail is used.
  • rail: Used to fill up the width of the slider, colored as applicable.
  • delimiter: Wraps the rail characters on both sides.

Styles:

  • cursor: Applied to the cursor character, or the last character of the rail.

    Default: primary.

  • filled: Applied to the filled section of the rail if the slider is not selected.

    Default: surface+1.

  • filled_selected: Applied to the filled section of the rail if the slider is selected.

    Default: primary.

  • unfilled: Applied to the unfilled section of the rail if the slider is not selected.

    Default: surface-1.

  • unfilled_selected: Applied to the unfilled section of the rail if the slider is selected.

    Default: surface.

InputField

A field to display input. Should be used in a context that sends it keyboard inputs, such as WindowManager.

Auto syntax: N/A

Chars: N/A

Styles:

  • value: Applies to the text of the input field.

    Default: No styling.

  • prompt: Applies to the string displayed before the field's value, controlled by the prompt parameter.

    Default: surface+2

  • cursor: Applies to the field's cursor.

    Default: @primary dim #auto

PixelMatrix

A customizable matrix of unicode pixels. With some image decoding, it can be used to display low-resolution pictures.

Auto syntax: N/A

Chars: N/A

Styles: N/A

DensePixelMatrix

Similar to PixelMatrix, but instead of using two unicode block characters per pixel, it uses either the upper or lower half of one. Allows for higher resolution pictures!

Auto syntax: N/A

Chars: See PixelMatrix

Styles: See PixelMatrix