Session Handler
app.ui.handlers.session_handlerSession management handler for UI layer.
See Also
SessionManager— manages the active session collectionSessionFileListViewModel— supplies session entries for display
Layer: Presentation. Context: Converts user actions and worker signals into application calls and UI feedback.
SessionHandler
Bases: QObject
Orchestrate session lifecycle events and UI synchronization.
Responsibilities
- Handle video file loading and session creation.
- Manage active-session switching.
- Synchronize session view_state with UI widgets.
- Coordinate playback initialization on session load.
Notes
Signal flow:
- Receives signals from MainWindow (file selection/menu) and
BottomPanel (session selection).
- Delegates to Application and UIController to perform actions.
- Triggers UI updates to reflect session view_state changes.
| PARAMETER | DESCRIPTION |
|---|---|
controller
|
Controller supplying session lifecycle operations and the window and panel to refresh.
TYPE:
|
__init__(controller: UIController) -> None
on_open_videos(paths: list[str]) -> None
Receive file paths and create new sessions for each video.
| PARAMETER | DESCRIPTION |
|---|---|
paths
|
Video file paths selected by the user.
TYPE:
|
Notes
Signal cascade (complete flow):
1. MainWindow File menu Open Videos action triggers file selection UI.
2. MainWindow._choose_video_files() emits open_videos_requested(paths).
3. SessionHandler.on_open_videos(paths) receives the signal.
4. Existing playback is stopped.
5. App.open_videos(paths) creates sessions via session manager.
6. New sessions are adopted for parent-managed cleanup.
7. Session list widget is refreshed.
8. Video-related widgets are enabled.
9. Active session is selected and seek-complete hookup is attached.
Triggered by:
MainWindow.open_videos_requested carrying list[str].
Effects: - Prevents playback conflicts. - Delegates session creation to application layer. - Synchronizes newly created sessions into UI view_state.
Downstream:
May indirectly trigger on_session_selected() when active
session view_state updates.
on_session_selected(s_id: SessionId) -> None
Switch active session and restore UI view_state for the selected session.
| PARAMETER | DESCRIPTION |
|---|---|
s_id
|
Identifier for the session to activate.
TYPE:
|
Notes
Triggered by:
BottomPanel.session_selected carrying SessionId.
Effects: - Stops playback in the previously active session. - Sets selected session as active. - Restores session settings in UI controls. - Renders initial frame for the selected session.
Downstream: None. This slot is a leaf UI update operation.
on_video_seek_completed(index: int) -> None
Render initial frame after seek completion if playback is paused.
| PARAMETER | DESCRIPTION |
|---|---|
index
|
Frame index emitted by decode worker on seek completion.
TYPE:
|
Notes
Triggered by:
VideoDecodeWorker.signals.seek_completed connected with
Qt.ConnectionType.SingleShotConnection.
Effects: - If playback is paused, forces one manual frame render. - If playback is already running, avoids redundant redraw.
Why single-shot: - Ensures this slot fires once for initial frame readiness. - Prevents duplicate first-frame render behavior.
prepare_active_session_initial_frame_render() -> None
Handle prepare active session initial frame render.
refresh_session_views() -> None
Refresh session views.
update_video_related_widgets_state(is_enabled: bool = False) -> None
Enable or disable video-related widgets across UI panels.
| PARAMETER | DESCRIPTION |
|---|---|
is_enabled
|
True to enable controls, False to disable.
TYPE:
|
Notes
Called during startup (disabled) and after video load (enabled). Propagates view_state to bottom, right, and transport panels.