asciimatics

Asciimatics provides a cross-platform Python interface for terminal-based animations and text UIs.

Low-level console functions:

• Coloured/styled text (including 256 colour terminals)
• Cursor positioning
• Non-blocking/non-echoing keyboard input
• Mouse input (terminal permitting)
• Console resize detection and handling
• Screen scraping

High-level APIs:

• Anti-aliased ASCII line-drawing
• Image to ASCII conversion (JPEG and GIF)
• Animation effects (sprites, particle systems, banners, etc.)
• Text UI widgets (buttons, text boxes, radio buttons, etc.)

The asciimatics.widgets package provides a comprehensive suite of UI components for building terminal-based interfaces. Available submodules include:

• Selection & Lists: baselistbox, basepicker, dropdownlist, listbox, multicolumnlistbox, popupmenu, radiobuttons.
• Input & Controls: button, checkbox, datepicker, timepicker, textbox.
• Display & Layout: divider, verticaldivider, frame, label, scrollbar, text, layout.
• Navigation & Dialogs: filebrowser, popupdialog, temppopup.
• Core & Utilities: widget, utilities.

Asciimatics provides a widgets sub-package for creating interactive text user interfaces. The architecture relies on three main components:

1. Widget: The basic building block (e.g., buttons, checkboxes).
2. Layout: Manages the arrangement and resizing of Widgets on the Screen.
3. Frame: An Effect that contains one or more Layouts. It acts like a window in a GUI framework, drawing the visible parts of its layouts within its boundaries.

You can trigger application logic by setting callbacks for key events, such as button clicks or value changes.

The asciimatics.renderers package provides various visual rendering modules for creating animations and terminal effects. Available submodules include:

• asciimatics.renderers.base: Base classes for renderers.
• asciimatics.renderers.box: Box rendering.
• asciimatics.renderers.charts: Chart and graph rendering.
• asciimatics.renderers.figlettext: FIGlet text rendering.
• asciimatics.renderers.fire: Fire effects.
• asciimatics.renderers.images: Image rendering.
• asciimatics.renderers.kaleidoscope: Kaleidoscope effects.
• asciimatics.renderers.plasma: Plasma effects.
• asciimatics.renderers.players: Player/character rendering.
• asciimatics.renderers.rainbow: Rainbow effects.
• asciimatics.renderers.rotatedduplicate: Rotated duplicate effects.
• asciimatics.renderers.scales: Scales effects.
• asciimatics.renderers.speechbubble: Speech bubble rendering.

While asciimatics maintains its own themes on resize, it will not automatically re-invoke external applications that use terminal control sequences to set colors (like pywal). If you use such tools, you must manually re-apply the sequences when screen.has_resized() is true.

from pathlib import Path
from asciimatics.screen import ManagedScreen
import sys

with ManagedScreen() as screen:
    # do stuff
    if screen.has_resized():
        wal_sequences = Path.home() / ".cache" / "wal" / "sequences"
        try:
            with wal_sequences.open("rb") as fd:
                contents = fd.read()
                sys.stdout.buffer.write(contents)
        except Exception:
            pass

You can layer different effects in a single Scene. To layer content, add multiple effects to the list passed to the Scene constructor.

Important: Z-order The order of the effects in the list determines their Z-order. Effects at the end of the list are drawn on top of effects earlier in the list. For example, to place an input form over an animated background, place the InputFormFrame after the background effect in the list.

scenes = []
effects = [
    Julia(screen),
    InputFormFrame(screen)
]
scenes.append(Scene(effects, -1))
screen.play(scenes)

To build a UI, you define a Frame and associate it with one or more Layout objects. Layouts stack vertically within a Frame. Each Layout defines horizontal columns as proportions of the Frame width. You then add widgets to specific columns within a layout.

To create a 4-column layout in an 80x20 frame:

frame = Frame(screen, 80, 20, has_border=False)
layout = Layout([1, 1, 1, 1])
frame.add_layout(layout)

# Add widgets to specific columns (0-indexed)
layout.add_widget(Button("OK", self._ok), 0)
layout.add_widget(Button("Cancel", self._cancel), 3)

If you add multiple widgets with labels to the same column, Asciimatics automatically aligns and indents them for a consistent look.

To create layouts like a fixed header/footer with a variable middle section, you can use the following methods to fill remaining space:

1. Layout level: Set fill_frame=True when constructing a Layout.
2. Widget level: Set the height of a widget to Widget.FILL_FRAME during construction.

Warning: You can only have one Layout or one Widget that fills the frame. Attempting to set more than one will be rejected.

Install the asciimatics package using pip. This will automatically install necessary dependencies.

Note for Windows users: You must also install pywin32 manually if it is not handled by the installation process.

$ pip install asciimatics

Input Focus

Focus determines which widget receives keyboard input. Users can navigate focus using cursor keys, Tab/Backtab, or the mouse. If you set hover_focus=True on a Frame and your terminal supports mouse move events, simply hovering over a widget will move the focus to it.

Modal Frames

When creating a Frame, you can set is_modal=True. A modal frame prevents input from filtering through to other Effects in the Scene, ensuring only the modal frame processes user input. This is ideal for PopUpDialog notifications.