xnano.time

The time a canvas runs on.

Get it from Canvas.time or from context.time inside a hook. Everything that moves follows it: animations, effects, formulas, hook timers (every and after), fixed-step updates and the musical beat. Any thread may read it. Used in arithmetic it is the formula for seconds, so canvas.time / 2 is a value that follows the clock. stop freezes all of them while input keeps arriving, and step moves a frozen clock one frame at a time.

elapsed, delta and fps are numbers you read now; seconds and milliseconds are formulas that a placement keeps following. A Frame carries the same numbers as elapsed_seconds and delta_seconds. fps here is the rate measured over recent frames, while Canvas.fps is the most frames the canvas draws per second.

Attributes:

• elapsed (float) –

  Seconds since the canvas started, not counting time spent stopped.

• elapsed_milliseconds (float) –

  The same, in milliseconds.

• delta (float) –

  Seconds between the two most recent frames.

• frame (int) –

  The number of steps the clock has counted.

• fps (float) –

  The frame rate measured over recent frames.

• is_stopped (bool) –

  Whether time is frozen.

• is_realtime (bool) –

  Whether time follows the wall clock. A canvas from xnano.new() without realtime=True moves only when you move it.

• seconds (NumericValue) –

  A formula for elapsed, recomputed every frame.

• milliseconds (NumericValue) –

  A formula for elapsed_milliseconds.

Examples:

import xnano

with xnano.new(width=20, height=1) as canvas:
    ball = canvas.write('o')
    ball.x = (canvas.width - 1) * ((canvas.time.seconds / 2) % 1.0)
    canvas.step(delta_seconds=1.0)
    assert canvas.time.elapsed == 1.0
    canvas.time.stop()
    assert canvas.time.is_stopped
    canvas.time.step(delta_seconds=0.5)
    assert canvas.time.elapsed == 1.5

Create the canvas's time. Use canvas.time instead of calling this.

Parameters:

• canvas (Canvas[object, object]) –

  The canvas the time belongs to.

Methods:

• stop –

  Freeze time.

• resume –

  Let time run on from where stop froze it.

• step –

  Move time by delta_seconds, one frame by default, and draw exactly one frame.

68
69
70
71
72
73
74
75

def __init__(self, canvas: Canvas[object, object]) -> None:
    """
    Create the canvas's time. Use ``canvas.time`` instead of calling this.

    Args:
        canvas: The canvas the time belongs to.
    """
    self._canvas = canvas

elapsed: float

elapsed_milliseconds: float

delta: float

frame: int

fps: float

is_stopped: bool

is_realtime: bool

seconds: NumericValue

milliseconds: NumericValue

stop() -> None

122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

def stop(self) -> None:
    """
    Freeze time.

    Animations, effects, formulas, timers, fixed-step updates and the musical beat stand
    still. The canvas still draws and input still arrives, so a key can
    [`resume`][xnano.time.Time.resume] it, and [`step`][xnano.time.Time.step] moves it one
    frame at a time. Stopping a stopped canvas does nothing.

    Raises:
        TerminalClosedError: The canvas is closed.
    """
    canvas = self._canvas
    canvas._require_open()
    canvas._time_source.stop()
    audio = canvas._audio
    if audio is not None:
        canvas._host.post(audio._hold)
    # A frozen canvas still draws what changes, so it draws once more now.
    canvas._request_frame()

resume() -> None

143
144
145
146
147
148
149
150
151
152
153
154
155
156
157

def resume(self) -> None:
    """
    Let time run on from where [`stop`][xnano.time.Time.stop] froze it.

    Resuming a canvas that is not stopped does nothing.

    Raises:
        TerminalClosedError: The canvas is closed.
    """
    canvas = self._canvas
    canvas._require_open()
    canvas._time_source.resume()
    audio = canvas._audio
    if audio is not None:
        canvas._host.post(audio._release)

step(*, delta_seconds: float | None = None) -> Frame

159
160
161
162
163
164
165
166
167
168
169
170
171
172

def step(self, *, delta_seconds: float | None = None) -> Frame:
    """
    Move time by ``delta_seconds``, one frame by default, and draw exactly one frame.

    This is [`Canvas.step`][xnano.canvas.Canvas.step]; see it for every case.

    Args:
        delta_seconds: How far to move, above zero; one frame of the canvas's ``fps``
            when ``None``.

    Returns:
        The [`Frame`][xnano.context.Frame] that was drawn.
    """
    return self._canvas._step(delta_seconds)