API
Application
async
app(
root: Callable[[], Component],
output_stream: TextIO = sys.stdout,
input_stream: TextIO = sys.stdin,
headless: bool = False,
dimensions: tuple[int, int] | None = None,
autopilot: Iterable[AnyEvent | AnyControl] = (),
) -> None
| PARAMETER | DESCRIPTION |
|---|---|
root |
The root component of the application. |
output_stream |
The stream to which the application will write its output. |
input_stream |
The stream from which the application will read its input. |
headless |
If
TYPE:
|
dimensions |
The dimensions of the terminal window, in characters.
If |
autopilot |
An iterable of events and controls to be processed by the application. This is primarily useful for testing or generating screenshots programmatically. Note that the autopilot will not be processed until after the initial render cycle, and that using the autopilot does not automatically cause the application to quit!
TYPE:
|
Components
component(
func: Callable[P, AnyElement]
) -> Callable[P, Component]
A decorator that marks a function as a component.
dataclass
Component(
func: Callable[..., AnyElement],
args: tuple[object, ...],
kwargs: dict[str, object],
key: str | int | None = None,
)
The result of calling a component function.
These should not be instantiated directly;
instead, use the @component decorator on a function
and call it normally.
Elements
class-attribute
instance-attribute
children: Sequence[Component | AnyElement] = Field(
default=()
)
class-attribute
instance-attribute
on_key: Callable[[KeyPressed], AnyControl | None] | None = (
None
)
class-attribute
instance-attribute
on_mouse: (
Callable[[MouseEvent], AnyControl | None] | None
) = None
class-attribute
instance-attribute
on_key: Callable[[KeyPressed], AnyControl | None] | None = (
None
)
class-attribute
instance-attribute
on_mouse: (
Callable[[MouseEvent], AnyControl | None] | None
) = None
Hooks
| PARAMETER | DESCRIPTION |
|---|---|
initial_value |
The initial value of the state. It can either be the initial value itself, or a zero-argument function that returns the initial value.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
T
|
The current value of the state (i.e., for the current render cycle). |
Setter[T]
|
A function that can be called to update the value of the state (e.g., in an event handler). It can either be called with the new value of the state, or a function that takes the current value of the state and returns the new value of the state. If the value is not equal to the current of the state, Counterweight will trigger a render cycle. |
| PARAMETER | DESCRIPTION |
|---|---|
setup |
The setup function that will be called when the component first mounts or if its dependencies have changed (see below).
TYPE:
|
deps |
The dependencies of the effect.
If any of the dependencies change, the previous invocation of the
TYPE:
|
use_mouse() -> Mouse
| RETURNS | DESCRIPTION |
|---|---|
Mouse
|
A record describing the current state of the mouse. |
dataclass
Mouse(
absolute: Position, motion: Position, button: int | None
)
instance-attribute
The absolute position of the mouse on the screen (i.e., the top-left corner of the screen is Position(x=0, y=0)).
instance-attribute
The difference in the absolute position of the mouse since the last render cycle.
instance-attribute
button: int | None
The button that is currently pressed, or None if no button is pressed.
use_rects() -> Rects
| RETURNS | DESCRIPTION |
|---|---|
Rects
|
A recording describing the rectangular areas of the
|
dataclass
use_hovered() -> Hovered
| RETURNS | DESCRIPTION |
|---|---|
Hovered
|
A record describing which of the calling component's top-level element's
|
dataclass
Events
module-attribute
MouseEvent = Union[
MouseMoved,
MouseDown,
MouseUp,
MouseScrolledDown,
MouseScrolledUp,
]
dataclass
MouseMoved(absolute: Position, button: int | None)
instance-attribute
The absolute position on the screen that the mouse moved to.
instance-attribute
button: int | None
The button that was held during the motion, or None if no button was pressed.
dataclass
MouseDown(absolute: Position, button: int)
instance-attribute
The absolute position on the screen that the mouse moved to.
dataclass
MouseUp(absolute: Position, button: int)
instance-attribute
The absolute position on the screen that the mouse moved to.
dataclass
MouseScrolledDown(absolute: Position, direction: int = 1)
instance-attribute
The absolute position on the screen that the mouse moved to.
class-attribute
instance-attribute
direction: int = 1
The direction that the mouse was scrolled as an integer offset; -1 for up, +1 for down.
dataclass
MouseScrolledUp(absolute: Position, direction: int = -1)
instance-attribute
The absolute position on the screen that the mouse moved to.
class-attribute
instance-attribute
direction: int = -1
The direction that the mouse was scrolled as an integer offset; -1 for up, +1 for down.
Controls
module-attribute
AnyControl = Union[
Quit, Bell, Screenshot, Suspend, ToggleBorderHealing
]
dataclass
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.
dataclass
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.
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!).
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:
|
indent |
The number of spaces to indent the SVG by (for readability).
If
TYPE:
|
dataclass
Toggle whether border healing occurs.
Styles
class-attribute
instance-attribute
Layout
class-attribute
instance-attribute
class-attribute
instance-attribute
align_self: Literal[
"none", "start", "center", "end", "stretch"
] = "none"
class-attribute
instance-attribute
justify_children: Literal[
"start",
"center",
"end",
"space-between",
"space-around",
"space-evenly",
] = "start"
class-attribute
instance-attribute
align_children: Literal[
"start", "center", "end", "stretch"
] = "start"
Relative positioning is relative to the parent element's content box. Elements occupy space and are laid out next to their siblings according to the parent's layout direction.
Absolute positioning is relative to the parent element's content box, but the element does not occupy space in the layout.
The inset property determines which corner of the
parent element's content box this element is positioned relative to.