annie.pages.timeline_view

Visible-window geometry of the event timeline (pure, no UI).

The timeline shows a window [start, start + span] of the clip’s frames. The window is state of its own: it never derives from the playhead, so the playhead can travel inside it (or leave it) while the user pans, zooms, or follows playback. Everything here is plain arithmetic so the rules are unit-testable without a browser.

Attributes

MAX_ZOOM	Upper bound on the zoom factor.
FOLLOW_LEAD	Fraction of the window left behind the playhead after a page-flip.

Classes

TimelineView

The visible window of a clip's timeline.

Module Contents

annie.pages.timeline_view.MAX_ZOOM = 100.0

Upper bound on the zoom factor.

annie.pages.timeline_view.FOLLOW_LEAD = 0.1

Fraction of the window left behind the playhead after a page-flip.

class annie.pages.timeline_view.TimelineView

The visible window of a clip’s timeline.

total_frames

Clip length in frames (0 while unknown).

zoom

Zoom factor, >= 1; 1 shows the whole clip.

start

First visible frame. Clamped whenever it is read, so it may be set freely.

property last_frame: int

Index of the clip’s last frame (0 for an empty/unknown clip).

property zoomed_in: bool

Whether the window is narrower than the clip (pan/scrollbar make sense).

property span: int

Number of frames between the window’s edges (>= 1).

window() → tuple[int, int]

Return the visible (first, last) frames, clamped inside the clip.

contains(frame: int) → bool

Whether frame lies inside the visible window.

fraction_of(frame: int) → float | None

Return frame’s horizontal position [0, 1], or None if off-screen.

fraction_clamped(frame: int) → float

Return frame’s position clipped to [0, 1] (for bands that clip at an edge).

frame_at(fraction: float) → int

Map a window fraction [0, 1] back to an absolute frame.

zoom_by(factor: float, anchor_frame: int | None = None) → None

Multiply the zoom, keeping anchor_frame at the same screen position.

Parameters:

• factor – Multiplier (> 1 zooms in).

• anchor_frame – Frame to hold still; None anchors on the window’s centre. An anchor outside the window is treated like None.

pan_by(delta_frames: int) → None

Slide the window by delta_frames (no-op when not zoomed in).

pan_by_fraction(fraction: float) → None

Slide the window by a fraction of its own width (negative pans left).

set_start_fraction(fraction: float) → None

Place the window’s left edge at fraction of the pannable range (scrollbar).

center_on(frame: int) → None

Centre the window on frame (no-op when not zoomed in).

page_to(frame: int, lead: float = FOLLOW_LEAD) → None

Flip the window so frame sits lead of the way in (forward playback).

Moving backwards past the left edge shows the history instead, leaving lead of the window ahead of frame.

thumb() → tuple[float, float]

Return the scrollbar thumb as (left, width) fractions of its track.