use_controls
An input handler acts on the app by returning controls,
but an effect, or a callback that a program or a timer calls, has no event to return them for.
use_controls gives a component a sender that hands the app a control from anywhere:
from asyncio import sleep
from counterweight.components import component
from counterweight.controls import Quit
from counterweight.elements import Text
from counterweight.hooks import use_controls, use_effect
@component
def farewell() -> Text:
send_control = use_controls()
async def quit_soon() -> None:
await sleep(3)
send_control(Quit())
use_effect(quit_soon, deps=())
return Text(content="Quitting in three seconds...")
The multiplexer example
quits the same way when its last pane's shell exits,
and moves focus with FocusNext when the focused pane's shell exits.
The app handles a sent control as it handles one a handler returns, after the events already waiting,
so state set just before sending it changes the same frame the control does.
Every render returns an equal sender, so it can be left out of an effect's deps.
API
use_controls() -> ControlSender
Sends the app controls from outside an input handler, such as from an effect, or a callback a program or a timer calls. An input handler returns its controls instead.
| RETURNS | DESCRIPTION |
|---|---|
ControlSender
|
A sender that hands the app each control it's called with, |
ControlSender
|
which the app handles as it handles a control an input handler returns, |
ControlSender
|
after the events already waiting. |
ControlSender
|
Every render returns an equal sender, so it can be left out of an effect's |
ControlSender
|
and including it never reruns the effect. |
ControlSender
|
It keeps working after the component unmounts, so a control sent as it goes, such as |
dataclass
ControlSender(queue: Queue[AnyEvent])
What use_controls returns:
call it with a control to send it to the app, as send_control(Quit()).