Interaction

app.ui.qt.widgets.preview.layer_bbox.interaction

View source code

State-transition helpers for bbox interaction flows.

These functions are intentionally side-effect-light and operate on BBoxState so the widget facade can remain thin and easier to test.

See Also

• BBoxState — holds gesture and selection state
• MouseReleaseOutcome — describes release handling results

Layer: Presentation. Context: Contains concrete Qt presentation components and supporting utilities.

BBoxLookupFn = Callable[[QPoint], tuple[str | None, QRect | None]] module-attribute

HitTestHandleFn = Callable[[QPoint], DragMode] module-attribute

ClampPointFn = Callable[[QPoint], QPoint] module-attribute

ClampRectFn = Callable[[QRect], QRect] module-attribute

ApplyHandleDragFn = Callable[[QRect, DragMode, QPoint], QRect] module-attribute

begin_add_drag(state: BBoxState, clamped_pos: QPoint) -> None

Initialize state for drawing a new bbox.

PARAMETER	DESCRIPTION
state	Mutable drag state to initialize. TYPE: BBoxState
clamped_pos	Pointer position clamped to the drawable image area. TYPE: QPoint

Side Effects

Sets the initial zero-size rectangle, draw mode, and drag origin on state.

try_start_panning(is_panning: bool, button_is_left: bool, is_ctrl_pressed: bool, pos: QPoint) -> tuple[bool, QPoint | None]

Start panning when Ctrl+Left is pressed.

PARAMETER	DESCRIPTION
is_panning	Whether a pan gesture is already active. TYPE: bool
button_is_left	Whether the pressed mouse button is the left button. TYPE: bool
is_ctrl_pressed	Whether Ctrl is held. TYPE: bool
pos	Pointer position at the start of the gesture. TYPE: QPoint

RETURNS	DESCRIPTION
tuple[bool, QPoint | None]	(True, pos) when panning should start; otherwise (False, None).

update_panning(is_panning: bool, last_pan_pos: QPoint, pos: QPoint) -> tuple[bool, QPoint, QPoint | None]

Update panning delta while dragging the viewport.

PARAMETER	DESCRIPTION
is_panning	Whether a pan gesture is active. TYPE: bool
last_pan_pos	Pointer position from the previous pan update. TYPE: QPoint
pos	Current pointer position. TYPE: QPoint

RETURNS	DESCRIPTION
tuple[bool, QPoint, QPoint | None]	(True, pos, delta) while panning, or (False, last_pan_pos, None) otherwise.

stop_panning(is_panning: bool) -> bool

Return True when panning was active and should be cancelled on release.

PARAMETER	DESCRIPTION
is_panning	Whether panning was active before the mouse release. TYPE: bool

RETURNS	DESCRIPTION
bool	The input state, used by the caller to decide whether to cancel panning.

try_begin_existing_edit_drag(state: BBoxState, pos: QPoint, hit_test_handle: HitTestHandleFn) -> bool

Start handle-resize or move drag when the active bbox is already selected.

PARAMETER	DESCRIPTION
state	Current bbox rectangle and drag state. TYPE: BBoxState
pos	Pointer position used to identify a handle or interior hit. TYPE: QPoint
hit_test_handle	Callback returning the handle drag mode at pos. TYPE: HitTestHandleFn

RETURNS	DESCRIPTION
bool	True if a resize or move drag started; otherwise False.

Side Effects

On a hit, stores the drag mode, origin, and starting rectangle in state.

try_select_bbox_for_edit(state: BBoxState, pos: QPoint, get_bbox_at_pos: BBoxLookupFn) -> str | None

Pick a bbox under cursor and initialize drag-ready state for edit mode.

PARAMETER	DESCRIPTION
state	Mutable bbox drag state to initialize. TYPE: BBoxState
pos	Pointer position used to select a box. TYPE: QPoint
get_bbox_at_pos	Lookup callback returning a box key and widget rectangle. TYPE: BBoxLookupFn

RETURNS	DESCRIPTION
str | None	Selected box key, or None when no box is found.

Side Effects

On a hit, stores the selected rectangle and drag origin in state.

update_drag_rect(state: BBoxState, pos: QPoint, clamp_point: ClampPointFn, clamp_rect: ClampRectFn, apply_handle_drag: ApplyHandleDragFn) -> bool

Apply draw/move/resize updates for the current drag state.

PARAMETER	DESCRIPTION
state	Mutable rectangle and drag mode being updated. TYPE: BBoxState
pos	Current pointer position. TYPE: QPoint
clamp_point	Callback constraining the pointer to the drawable image area. TYPE: ClampPointFn
clamp_rect	Callback constraining a moved rectangle to the image bounds. TYPE: ClampRectFn
apply_handle_drag	Callback resizing the starting rectangle for the active handle. TYPE: ApplyHandleDragFn

RETURNS	DESCRIPTION
bool	True if a draw, move, or resize operation updated the rectangle.

Side Effects

Updates state.rect when state.drag_mode is not NONE.

finalize_release(state: BBoxState, editing_bbox_id: str | None, min_bbox_px: int, widget_rect_to_image_space: Callable[[QRect], tuple[int, int, int, int]]) -> tuple[MouseReleaseOutcome, tuple[str, int, int, int, int] | tuple[int, int, int, int] | None]

Finalize mouse release into cancel/draw/edit/none outcomes.

PARAMETER	DESCRIPTION
state	Current rectangle and drag mode to finalize. TYPE: BBoxState
editing_bbox_id	Key of the box being edited, or None for a new box. TYPE: str | None
min_bbox_px	Minimum widget-space width and height accepted for a new box. TYPE: int
widget_rect_to_image_space	Callback converting the final rectangle to image coordinates. TYPE: Callable[[QRect], tuple[int, int, int, int]]

RETURNS	DESCRIPTION
MouseReleaseOutcome	Outcome and payload: a coordinate tuple for a new box, a key plus coordinates
tuple[str, int, int, int, int] | tuple[int, int, int, int] | None	for an edit, or None when the gesture is cancelled or has no action.