timeline_slider

_timeline_slider ¶

Timeline/scrubber widget for DCC applications.

Classes:

Name	Description
`FXTimelineSlider`	A timeline/scrubber widget perfect for DCC applications.

Classes¶

FXTimelineSlider ¶

FXTimelineSlider(
    parent: Optional[QWidget] = None,
    start_frame: int = 1,
    end_frame: int = 100,
    current_frame: Optional[int] = None,
    fps: int = 24,
    show_controls: bool = True,
    show_spinbox: bool = True,
    show_loop_controls: bool = False,
    show_keyframe_controls: bool = False,
    controls_position: str = "left",
)

Bases: FXThemeAware, QWidget


              flowchart TD
              fxgui.fxwidgets._timeline_slider.FXTimelineSlider[FXTimelineSlider]
              fxgui.fxstyle.FXThemeAware[FXThemeAware]

                              fxgui.fxstyle.FXThemeAware --> fxgui.fxwidgets._timeline_slider.FXTimelineSlider
                


              click fxgui.fxwidgets._timeline_slider.FXTimelineSlider href "" "fxgui.fxwidgets._timeline_slider.FXTimelineSlider"
              click fxgui.fxstyle.FXThemeAware href "" "fxgui.fxstyle.FXThemeAware"

A timeline/scrubber widget perfect for DCC applications.

This widget provides a timeline slider with: - Frame range display - Keyframe markers - Current frame indicator - Optional playback controls - Track zoom: mouse wheel over the track zooms the visible frame window around the cursor, middle-mouse drag pans it, reset_view() restores the full range (view_changed reports the visible window). - Named marker layers: per-frame markers rendered as vertical lines or a top strip (e.g. cached frames), and named regions (e.g. a loop range), all mapped through the zoomed window. The widget assigns no meaning to a layer: the consumer picks names, colors and styles. - Optional in/out controls (show_loop_controls): bracket buttons that request marking the current frame as loop in/out point; the consumer decides what marking does and typically calls set_loop_region. - Optional keyframe navigation (show_keyframe_controls): buttons jumping to the nearest keyframe before/after the current frame (go_to_previous_keyframe / go_to_next_keyframe). - Hover indicator: a crosshair-style line with the hovered frame number, cleared when the cursor leaves the track.

Parameters:

Name	Type	Description	Default
`parent` ¶	`Optional[QWidget]`	Parent widget.	`None`
`start_frame` ¶	`int`	Start frame of the timeline.	`1`
`end_frame` ¶	`int`	End frame of the timeline.	`100`
`current_frame` ¶	`Optional[int]`	Initial current frame.	`None`
`fps` ¶	`int`	Frames per second for playback (default 24).	`24`
`show_controls` ¶	`bool`	Whether to show playback controls.	`True`
`show_spinbox` ¶	`bool`	Whether to show the frame spinbox.	`True`
`show_loop_controls` ¶	`bool`	Whether to show the mark-in/mark-out buttons.	`False`
`show_keyframe_controls` ¶	`bool`	Whether to show the previous/next-keyframe navigation buttons.	`False`
`controls_position` ¶	`str`	"left" (classic single row) or "below" (Nuke-style: full-width track on top, centered transport row below with I/O flanking the cluster, fps far left, consumer extras -- added via add_control_widget() -- far right).	`'left'`

Signals

frame_changed: Emitted when the current frame changes. playback_started: Emitted when playback starts. playback_stopped: Emitted when playback stops. view_changed: Emitted with (first, last) when the visible frame window changes (zoom, pan, or reset). in_point_requested: Mark-in button pressed; carries the current frame. The widget draws nothing by itself. out_point_requested: Mark-out button pressed; carries the current frame.

Examples:

>>> timeline = FXTimelineSlider(start_frame=1, end_frame=100)
>>> timeline.frame_changed.connect(lambda f: print(f"Frame: {f}"))
>>> timeline.add_keyframe(10)
>>> timeline.add_keyframe(50)
>>> timeline.set_marker_frames("cached", {2, 3, 4}, "#22c55e", "strip")
>>> timeline.set_marker_frames("errors", {40, 41}, "#ef4444")
>>> timeline.set_loop_region(20, 60)

Methods:

Name	Description
`add_control_widget`	Append a consumer widget to the controls area.
`add_keyframe`	Add a keyframe marker.
`clear_keyframes`	Remove all keyframe markers.
`clear_region`	Remove a named region (no-op if absent).
`go_to_end`	Go to the end frame.
`go_to_next_keyframe`	Jump to the nearest keyframe after the current frame (no-op if
`go_to_previous_keyframe`	Jump to the nearest keyframe before the current frame (no-op if
`go_to_start`	Go to the start frame.
`next_frame`	Advance to the next frame.
`play`	Start playback.
`previous_frame`	Go to the previous frame.
`remove_keyframe`	Remove a keyframe marker.
`remove_markers`	Remove a named marker layer (no-op if absent).
`reset_view`	Restore the track to the full frame range.
`set_fps`	Set the frames per second.
`set_frame`	Set the current frame.
`set_loop_playback`	Set loop playback (reflected on the toggle button, no re-emit).
`set_loop_region`	Show the loop in/out range on the track (None, None clears).
`set_marker_frames`	Set (or replace) a named marker layer painted on the track.
`set_range`	Set the frame range.
`set_region`	Set (or replace) a named frame region painted on the track.
`set_view_range`	Zoom the track to the [first, last] frame window.
`stop`	Stop playback.
`toggle_playback`	Toggle playback state.

Attributes:

Name	Type	Description
`current_frame`	`int`	Return the current frame.
`fps`	`int`	Return the current FPS.
`frame_range`	`Tuple[int, int]`	Return the frame range as (start, end).
`is_view_zoomed`	`bool`	Whether the track shows a sub-window of the full range.
`loop_playback`	`bool`	Whether playback wraps to the start at the end of the range.
`view_range`	`Tuple[int, int]`	Return the visible frame window as (first, last).

Attributes¶

current_frame `property` `writable` ¶

current_frame: int

Return the current frame.

fps `property` ¶

fps: int

Return the current FPS.

frame_range `property` ¶

frame_range: Tuple[int, int]

Return the frame range as (start, end).

is_view_zoomed `property` ¶

is_view_zoomed: bool

Whether the track shows a sub-window of the full range.

loop_playback `property` ¶

loop_playback: bool

Whether playback wraps to the start at the end of the range.

view_range `property` ¶

view_range: Tuple[int, int]

Return the visible frame window as (first, last).

Equals frame_range unless the track has been zoomed.

Methods:¶

add_control_widget ¶

add_control_widget(widget: QWidget) -> None

Append a consumer widget to the controls area.

In the "below" (Nuke-style) layout the widget lands on the right side of the transport row; in the classic single-row layout it is appended at the far right.

add_keyframe ¶

add_keyframe(frame: int) -> None

Add a keyframe marker.

Parameters:

Name	Type	Description	Default
`frame` ¶	`int`	The frame number to mark.	required

clear_keyframes ¶

clear_keyframes() -> None

Remove all keyframe markers.

clear_region ¶

clear_region(name: str) -> None

Remove a named region (no-op if absent).

go_to_end ¶

go_to_end() -> None

Go to the end frame.

go_to_next_keyframe ¶

go_to_next_keyframe() -> None

Jump to the nearest keyframe after the current frame (no-op if there is none).

go_to_previous_keyframe ¶

go_to_previous_keyframe() -> None

Jump to the nearest keyframe before the current frame (no-op if there is none).

go_to_start ¶

go_to_start() -> None

Go to the start frame.

next_frame ¶

next_frame() -> None

Advance to the next frame.

play ¶

play() -> None

Start playback.

previous_frame ¶

previous_frame() -> None

Go to the previous frame.

remove_keyframe ¶

remove_keyframe(frame: int) -> None

Remove a keyframe marker.

Parameters:

Name	Type	Description	Default
`frame` ¶	`int`	The frame number to remove.	required

remove_markers ¶

remove_markers(name: str) -> None

Remove a named marker layer (no-op if absent).

reset_view ¶

reset_view() -> None

Restore the track to the full frame range.

set_fps ¶

set_fps(fps: int) -> None

Set the frames per second.

Parameters:

Name	Type	Description	Default
`fps` ¶	`int`	Frames per second for playback.	required

set_frame ¶

set_frame(frame: int, emit: bool = True) -> None

Set the current frame.

Parameters:

Name	Type	Description	Default
`frame` ¶	`int`	The frame number.	required
`emit` ¶	`bool`	Whether to emit the frame_changed signal.	`True`

set_loop_playback ¶

set_loop_playback(enabled: bool) -> None

Set loop playback (reflected on the toggle button, no re-emit).

set_loop_region ¶

set_loop_region(
    start: Optional[int], end: Optional[int], color: Optional[str] = None
) -> None

Show the loop in/out range on the track (None, None clears).

Sugar over set_region("loop", ...) for the common loop-range pairing with the in/out controls.

set_marker_frames ¶

set_marker_frames(
    name: str, frames, color: Optional[str] = None, style: str = "line"
) -> None

Set (or replace) a named marker layer painted on the track.

The widget assigns no meaning to a layer: the consumer picks the name, color and style (a render-farm app may mark cached frames, a review app approved ones).

Parameters:

Name	Type	Description	Default
`name` ¶	`str`	Layer identifier; setting the same name replaces it.	required
`frames` ¶		Iterable of frame numbers. Empty removes the layer.	required
`color` ¶	`Optional[str]`	Marker color (any QColor-compatible value). None follows the theme accent, resolved at paint time so theme switches recolor it. For semantic colors, pick from `fxstyle.get_feedback_colors()` (theme-aware) rather than hardcoding hex values.	`None`
`style` ¶	`str`	"line" for 1px vertical lines at each frame, or "strip" for a translucent band along the top edge with a 1px solid top line over contiguous frame runs.	`'line'`

set_range ¶

set_range(start: int, end: int) -> None

Set the frame range.

Parameters:

Name	Type	Description	Default
`start` ¶	`int`	Start frame.	required
`end` ¶	`int`	End frame.	required

set_region ¶

set_region(
    name: str,
    start: int,
    end: int,
    color: Optional[str] = None,
    bracket_edges: bool = False,
) -> None

Set (or replace) a named frame region painted on the track.

Rendered as a translucent fill across the track with 1px solid edge lines, like a graph's linear region.

Parameters:

Name	Type	Description	Default
`name` ¶	`str`	Region identifier; setting the same name replaces it.	required
`start` ¶	`int`	First frame of the region.	required
`end` ¶	`int`	Last frame of the region.	required
`color` ¶	`Optional[str]`	Region color (edges solid, fill translucent). None follows the theme accent, resolved at paint time so theme switches recolor it.	`None`
`bracket_edges` ¶	`bool`	Render the edges as bold [ ] brackets instead of plain lines -- a zero-width region then still reads as a clear I-beam marker (used by set_loop_region so a lone in/out point is visible).	`False`

set_view_range ¶

set_view_range(first: int, last: int) -> None

Zoom the track to the [first, last] frame window.

The window is clamped inside the full range; a window covering the full range (or more) resets the view.

stop ¶

stop() -> None

Stop playback.

toggle_playback ¶

toggle_playback() -> None

Toggle playback state.

timeline_slider

_timeline_slider ¶

Classes¶

FXTimelineSlider ¶

parent ¶

start_frame ¶

end_frame ¶

current_frame ¶

fps ¶

show_controls ¶

show_spinbox ¶

show_loop_controls ¶

show_keyframe_controls ¶

controls_position ¶

Attributes¶

current_frame property writable ¶

fps property ¶

frame_range property ¶

is_view_zoomed property ¶

loop_playback property ¶

view_range property ¶

Methods:¶

add_control_widget ¶

add_keyframe ¶

clear_keyframes ¶

clear_region ¶

go_to_end ¶

go_to_next_keyframe ¶

go_to_previous_keyframe ¶

go_to_start ¶

next_frame ¶

play ¶

previous_frame ¶

remove_keyframe ¶

remove_markers ¶

reset_view ¶

set_fps ¶

set_frame ¶

set_loop_playback ¶

set_loop_region ¶

set_marker_frames ¶

set_range ¶

set_region ¶

set_view_range ¶

stop ¶

toggle_playback ¶

`parent` ¶

`start_frame` ¶

`end_frame` ¶

`current_frame` ¶

`fps` ¶

`show_controls` ¶

`show_spinbox` ¶

`show_loop_controls` ¶

`show_keyframe_controls` ¶

`controls_position` ¶

current_frame `property` `writable` ¶

fps `property` ¶

frame_range `property` ¶

is_view_zoomed `property` ¶

loop_playback `property` ¶

view_range `property` ¶