Uicontroller

app.ui.uicontroller

View source code

Module for uicontroller; presents application behavior to users.

See Also

• Application — supplies application workflows
• UIControllerInterface — defines the handler-facing controller contract

Layer: Presentation. Context: Presents application behavior to users at this architectural boundary.

UIController

Bases: QObject

Central coordinator for all UI operations and handler management. Acts as the bridge between App (application/business logic) and Qt UI layer.

Responsibilities

• Initialize and own all UI handlers (playback, detection, tracking, detection, export, etc.).
• Coordinate handler signal connections and event flow.
• Provide unified interface for handlers to access app and window.
• Manage Qt application lifecycle (initialization, shutdown).
• Route frame render requests to UIHandler.
• Manage data table event filtering (keyboard shortcuts).
• Handle critical Qt events (close, quit).

Note

Does NOT inherit from App (circular dependency prevention). Delegates handler ownership and coordination, frame rendering, and status updates. Handlers communicate through the controller, never directly to each other (avoid coupling).

Signal flow: Qt events (clicks, signals) → Handlers (via signal connections). Handlers call controller methods for coordination. Controller triggers frame renders, status updates, dialog creation.

PARAMETER	DESCRIPTION
q_app	Qt application instance. TYPE: QApplication
window	Window instance used by this component. TYPE: Window
app	Application facade exposed to UI handlers and adapters for session and settings operations. TYPE: Application

active_session: Session | None property

Return the currently active session, if any.

RETURNS	DESCRIPTION
Session | None	Active session, or None when no session is selected.

annotation_handler = handlers.AnnotationHandler(self) instance-attribute

app = app instance-attribute

detection_handler = handlers.DetectionHandler(self) instance-attribute

detection_tab_data_table: QTableWidget property

Return the detection-layer table shown in the bottom panel.

RETURNS	DESCRIPTION
QTableWidget	Detection table widget.

dialogue_handler = handlers.DialogueHandler(self) instance-attribute

export_handler = handlers.ExportHandler(self) instance-attribute

import_export_handler = handlers.ImportExportHandler(self) instance-attribute

model_handler = handlers.ModelHandler(self) instance-attribute

playback_handler = handlers.PlaybackHandler(self) instance-attribute

preferences_handler = handlers.PreferencesHandler(self) instance-attribute

project_handler = handlers.ProjectHandler(self) instance-attribute

q_app = q_app instance-attribute

session_handler = handlers.SessionHandler(self) instance-attribute

tracker_tab_data_table: QTableWidget property

Return the tracking-layer table shown in the bottom panel.

RETURNS	DESCRIPTION
QTableWidget	Tracking table widget.

tracking_handler = handlers.TrackingHandler(self) instance-attribute

ui_app = adapters.UIApplicationAdapter(app) instance-attribute

ui_controller = adapters.UIControllerAdapter(self) instance-attribute

ui_handler = handlers.UIHandler(self) instance-attribute

window = window instance-attribute

__init__(q_app: QApplication, window: Window, app: Application) -> None

create_edit_annotation_dialogue(initial_label: str, initial_bbox_xyxy: tuple[int, int, int, int]) -> EditAnnotationDialog

Create and return an EditAnnotationDialog with the given initial label and bounding box.

create_model_change_warning_dialog(s_id: SessionId) -> ModelChangeWarningDialog

Create model change warning dialog.

PARAMETER	DESCRIPTION
s_id	Session whose detection model would be changed. TYPE: SessionId

RETURNS	DESCRIPTION
ModelChangeWarningDialog	Dialog describing the consequences of changing that model.

on_about_to_quit() -> None

Handle application shutdown cleanup.

Note

Triggered by QApplication.aboutToQuit signal (before main window closes).

Flow: on_about_to_quit() [this slot] ├── Stop active playback (if running) ├── Wait for active exports to finish ├── Close App instance (saves state, cleans up sessions) └──> Close model load thread (if running)

Graceful Shutdown: Ensures playback stops before closing. Waits for exports to complete before exiting. Properly closes App and cleans up resources. Handles case where no session is active (LookupError).

on_close_requested() -> bool

Handle main window close request (checks if export in progress).

RETURNS	DESCRIPTION
bool	True — Allow window to close. False — Prevent window from closing (user cancelled). TYPE: bool

Note

Triggered by MainWindow.closeEvent → set_close_request_handler().

Flow:

on_close_requested() [this slot] | ├── Check if export currently in progress | ├── If no export: allow close | └── If export: ask user for confirmation | ├── If user confirms: cancel export (wait), then allow close | └── If user declines: prevent close

Safety: Prevents accidental data loss by prompting before closing during export.

on_seek_requested(idx: int) -> None

Handle seek slider position change from transport panel.

Note

Triggered by transport_panel.seek_pos_changed signal.

Delegates To: PlaybackHandler.on_seek(idx) for actual seeking.

render_frame_for_session_id(s_id: SessionId) -> None

Render the saved frame for the given session ID.

Note

Delegates to UIHandler.render_saved_frame(s_id) for actual rendering.

set_ui_data_tab_frame_boxes(tab: VideoDataLayerGroup, boxes: ListOfBoxes) -> None

Display frame boxes in the specified detection or tracking table.

PARAMETER	DESCRIPTION
tab	Data-layer table to update. TYPE: VideoDataLayerGroup
boxes	Boxes to display in that table. TYPE: ListOfBoxes

update_ui_status_bar()

Update ui status bar.