Events

Event sources and handlers.

Contents:

• k.EventSource: A concrete event of one owner.
• k.EventInfo: One firing of an event, received by .on handlers and returned by s.wait_for: e.time (instant), e.data (typed payload), e.count (n-th firing) and e.value(sig) (value of any signal at the instant of the event).

Methods in this area:

• event.on: Decorator that reacts to every firing of an event: @source.on registers def handler(s, e), run during resolve with its own s whose cursor starts at e.time (the main cursor does not change).

Back to the reference index.

k.EventSource (class)#

k.EventSource(
    scene: Scene,
    name: str,
    owner: Any = None,
    computed: Callable[[], list[tuple[float, Any]]] | None = None,
    bounded: bool = False,
)

A concrete event of one owner. React with @src.on, wait with s.wait_for(src).

Firings come from explicit emit() calls, from k.when conditions, from simulations and from computed sources (object lifecycle, end of an animation).

Documented together with event.on.

Parameters:

Attributes:

Members:

• emit: Fire at the cursor (in a build, clip or handler).
• on: Decorator that reacts to every firing of an event: @source.on registers def handler(s, e), run during resolve with its own s whose cursor starts at e.time (the main cursor does not change).

k.EventSource.emit (method)

event.emit()
event.emit(data: P)

Fire at the cursor (in a build, clip or handler).

Parameters:

k.EventSource.on (method)

event.on(fn: EventHandler[P], *, once: bool = False) -> EventHandler[P]
event.on(fn: None = None, *, once: bool = False) -> Callable[[HandlerT], HandlerT]

Written as: @event.on · @event.on(once=True)

Decorator that reacts to every firing of an event: @source.on registers def handler(s, e), run during resolve with its own s whose cursor starts at e.time (the main cursor does not change). .on(once=True) reacts only to the first one. Objects created in the handler must leave the scene (lint W0701).

Parameters:

Example:

@k.scene
def reaction(s: k.Scene):
    box = k.Square(1.5).place(at="center")
    h = s.play(k.draw(box))

    @h.done.on
    def notify(s: k.Scene, e: k.EventInfo) -> None:
        note = k.Text("done").place(above=box, gap=0.3)
        s.play(k.fade_in(note))
        s.play(k.fade_out(note))

See also: s.wait_for, k.when, k.EventInfo.

k.EventInfo (class)#

k.EventInfo(time: float, data: P_co, count: int)

Written as: e.time · e.data · e.count · e.value(sig)

One firing of an event, received by .on handlers and returned by s.wait_for: e.time (instant), e.data (typed payload), e.count (n-th firing) and e.value(sig) (value of any signal at the instant of the event).

Parameters:

Example:

@k.scene
def instant(s: k.Scene):
    x = k.signal(0.0)
    dot = k.Dot(r=0.2, x=x)
    s.add(dot)
    h = s.start(x.to(4), duration=2)
    e = s.wait_for(h.done)
    label = k.Text(f"x = {e.value(x):.0f} at t = {e.time:.0f} s").place(at="top", margin=0.8)
    s.play(k.write(label))

See also: event.on, s.wait_for.

Members:

• value: Value of any signal or expression at the instant of the event.

k.EventInfo.value (method)

e.value(sig: Val[T]) -> T

Value of any signal or expression at the instant of the event.

Parameters: