Skip to content

Controls

Controls are objects that can be returned from event handlers (e.g., on_key) to instruct Counterweight to take some action during the render loop, such as gracefully quitting the application or playing the terminal "bell" sound.

API

counterweight.controls.AnyControl module-attribute 

AnyControl = Union[
    Quit, Bell, Screenshot, Suspend, ToggleBorderHealing
]

counterweight.controls.Quit dataclass 

Quit()

Cause the application to quit.

The quit occurs at the beginning of the next render cycle, so all other events that are due to be processed in the current cycle will be processed before the application exits.

counterweight.controls.Bell dataclass 

Bell()

Cause the terminal to emit a bell sound.

The bell occurs at the beginning of the next render cycle, so all other events that are due to be processed in the current cycle will be processed before the sound is played.

counterweight.controls.Screenshot dataclass 

Screenshot(
    handler: Callable[[ElementTree], Awaitable[None] | None]
)

Take a "screenshot" of the rendered UI, using the given handler callback function. The screenshot is passed to the handler as an ElementTree containing an SVG representation of the UI.

The screenshot is taken at the beginning of the next render cycle, so all other events that are due to be processed in the current cycle will be processed before the screenshot is taken (but the screenshot will still be of the UI from before the next render occurs!).

handler instance-attribute 

handler: Callable[[ElementTree], Awaitable[None] | None]

to_file classmethod 

to_file(
    path: Path, indent: int | None = None
) -> Screenshot

A convenience method for producing a Screenshot that writes the resulting SVG to the given path.

PARAMETER DESCRIPTION
path

The path to write the SVG to. Parent directories will be created if they do not exist.

TYPE: Path

indent

The number of spaces to indent the SVG by (for readability). If None, the SVG will not be indented.

TYPE: int | None DEFAULT: None

counterweight.controls.Suspend dataclass 

Suspend(handler: Callable[[], Awaitable[None] | None])

Suspend the application while the handler function is running.

The application will be suspended (and then resumed) at the beginning of the next render cycle, so all other events that are due to be processed in the current cycle will be processed before the application is suspended.

handler instance-attribute 

handler: Callable[[], Awaitable[None] | None]

counterweight.controls.ToggleBorderHealing dataclass 

ToggleBorderHealing()

Toggle whether border healing occurs.