🚧 Work in progress: this documentation is still being written and reviewed. Check details against the source code.

Task queue display

Show editable task rows, selection, and execution progress.

mtc_gui.step_list_panel · Source

Operator GUI · Guide · Symbol index

How it is used

MTCMainWindow owns the task document and calls StepListPanel.refresh() to render it. The panel emits row selections, edit requests, pose drops, and reorder requests; the window applies those changes to the document. All widget updates belong on the GUI thread.

During a run, the window calls start_execution(), forwards feedback to update_step(), and completes the display with finish_execution(). Feedback steps are one-based within the submitted sequence; start_index maps them back to the full queue. Pausing changes the status indicator but does not stop elapsed-time counters.

Start here

Callable	Purpose
StepListPanel.refresh	Render the task sequence, reusing row widgets when the row count is unchanged.
StepListPanel.start_execution	Prepare the queue display for a run beginning at the specified row.
StepListPanel.update_step	Map one-based execution feedback to the full queue and update row progress.
StepListPanel.finish_execution	Stop timing and mark the executed queue segment from the reported result.
StepListPanel.selected_indices	Collect currently selected list-row positions.

StepListPanel

Coordinate task rows, selection, drag/drop signals, and execution display. It renders the main window’s tasks without owning or submitting the task document.

Inherits from: QWidget.

StepListPanel.refresh()

Render the task sequence, reusing row widgets when the row count is unchanged.

Method · Source

refresh(self, tasks: list, summary_fn)

Parameter	Meaning
tasks	Ordered list of task mappings; task_type defaults to “?” for display.
summary_fn	Callable taking a task mapping and returning its subtitle string.

Returns: None.

Errors: Task/summary/Qt errors propagate; updates are disabled before processing and there is no finally to re-enable them after failure.

Side effects: Resets row execution state, rebuilds or updates widgets and UserRole indices, sets total count/current step, reenables updates on success, and refreshes the empty overlay.

StepListPanel.start_execution()

Prepare the queue display for a run beginning at the specified row.

Method · Source

start_execution(self, total_steps: int, start_index: int=0)

Parameter	Meaning
total_steps	Full queue-step count used by the toolbar.
start_index	Zero-based first row to execute; callers provide a valid nonnegative index.

Returns: None.

Errors: No bounds validation beyond the first-next check; negative values follow Python slicing/indexing behavior and can fail on an empty list.

Side effects: Disables the panel’s editing flag, resets suffix rows to PENDING, clears/sets next badges, shows toolbar, and starts the elapsed timer. The list’s drag flags are changed separately by set_editing_enabled.

StepListPanel.update_step()

Map one-based execution feedback to the full queue and update row progress.

Method · Source

update_step(self, current_step: int, progress: float, action_name: str)

Parameter	Meaning
current_step	One-based step number within the submitted execution suffix.
progress	Accepted feedback percentage but not used; toolbar percentage is recomputed from the full-queue row index.
action_name	Task-type label displayed by the toolbar.

Returns: None.

Errors: Ignores nonpositive or out-of-range step indices; other type/Qt errors propagate.

Side effects: Updates row states/badges/current index, toolbar step/percentage, and scrolls to the active item. A row timer restarts only when that row first becomes RUNNING.

StepListPanel.finish_execution()

Stop timing and mark the executed queue segment from the reported result.

Method · Source

finish_execution(self, status: str, completed_steps: int)

Parameter	Meaning
status	“success” marks every suffix row DONE; any other value marks the first uncompleted row FAILED and later rows PENDING.
completed_steps	Completed count relative to _execution_start_index.

Returns: None.

Errors: No completion-count bounds validation; Qt errors propagate.

Side effects: Sets execution inactive/editing flag true, stops timer, clears all next badges, preserves skipped prefix states, marks suffix states, and hides toolbar. Drag/drop flags are not changed here.

StepListPanel.selected_indices()

Collect currently selected list-row positions.

Method · Source

selected_indices(self) -> list

Returns: Sorted list of zero-based visible row indices.

Errors: Qt errors propagate.

Referenced in source (1)

• StepListPanel._on_selection_changed — mtc_gui.step_list_panel

StepListPanel.__init__()

Create the task list, execution display, and elapsed-time timer.

Lifecycle · Source

__init__(self, parent=None)

Parameter	Meaning
parent	Optional parent widget.

Errors: Qt construction errors propagate.

Side effects: Starts with no rows, inactive execution, enabled editing, zero start offset, and an inactive QTimer.

Referenced in source (1)

• MTCMainWindow._build_center_pane — mtc_gui.main_window

StepListPanel.select_range()

Select and reveal a contiguous range of queue rows.

Method · Source

select_range(self, start: int, count: int)

Parameter	Meaning
start	First zero-based row index.
count	Number of rows included; a nonpositive count selects none.

Returns: None.

Errors: Type/range-construction errors propagate; unavailable rows are ignored by select_indices.

Side effects: Delegates to select_indices(range(start, start + count)).

StepListPanel.select_indices()

Clear selection, select all existing requested rows, and reveal the first one.

Method · Source

select_indices(self, indices)

Parameter	Meaning
indices	Iterable of zero-based row indices; out-of-range rows yielding no item are ignored.

Returns: None.

Errors: Qt/index-type errors propagate.

Side effects: Changes selection/current item and scroll position; selection-change signals may be emitted.

Referenced in source (1)

• StepListPanel.select_range — mtc_gui.step_list_panel

StepListPanel.set_editing_enabled()

Apply queue editability to double-click handling and drag/drop controls.

Method · Source

set_editing_enabled(self, enabled: bool)

Parameter	Meaning
enabled	Whether editing and reordering should be available.

Returns: None.

Errors: Qt errors propagate.

Side effects: Updates _editing_enabled and inner-list reordering state.

StepListPanel.set_paused()

Forward pause appearance to the execution toolbar.

Method · Source

set_paused(self, paused: bool)

Parameter	Meaning
paused	Boolean paused display state.

Returns: None.

Errors: Toolbar/Qt errors propagate.

Side effects: Changes toolbar indicator; does not suspend row or elapsed timers.

StepListPanel.set_current_row()

Clear the selection and select a valid row after a move operation.

Method · Source

set_current_row(self, index: int)

Parameter	Meaning
index	Zero-based row to select; invalid indices leave selection empty.

Returns: None.

Errors: Index-comparison/Qt errors propagate.

Side effects: Changes selected/current row and may emit selection_changed.

StepListPanel.editing_enabled

Expose the current panel editability flag.

Method · Source

@property
editing_enabled(self) -> bool

Access this as an instance property, without parentheses.

Returns: Boolean _editing_enabled.

Internal callbacks and helpers

StepListPanel._build_ui()

Build the queue list, execution toolbar, and empty-list hint.

Internal helper · Source

_build_ui(self)

Returns: None.

Errors: Optional qtawesome empty-state icon failures are suppressed; other Qt errors propagate.

Side effects: Creates widgets, forwards drop/reorder signals, connects selection/double-click handlers, and installs a resize event filter.

Referenced in source (1)

• StepListPanel.__init__ — mtc_gui.step_list_panel

StepListPanel._update_empty_state()

Show and fit the empty-list hint to the viewport only when no items exist.

Internal helper · Source

_update_empty_state(self)

Returns: None.

Errors: Returns if the overlay has not been created; Qt errors otherwise propagate.

Side effects: Changes overlay visibility and, while empty, its size, position, and stacking order.

Referenced in source (3)

• StepListPanel._build_ui — mtc_gui.step_list_panel
• StepListPanel.eventFilter — mtc_gui.step_list_panel
• StepListPanel.refresh — mtc_gui.step_list_panel

StepListPanel.eventFilter()

Recenter the empty-state hint when the inner list receives a resize event.

Callback · Source

eventFilter(self, obj, event)

Parameter	Meaning
obj	Watched QObject; only the panel’s inner list is handled specially.
event	Qt event whose type is checked for Resize.

Returns: Base QWidget.eventFilter result; the resize event is not consumed here.

Errors: Qt errors propagate.

Side effects: May update the empty overlay before delegating to the superclass.

StepListPanel._on_double_click()

Forward an editable double-click as a row-index event.

Callback · Source

_on_double_click(self, item: QListWidgetItem)

Parameter	Meaning
item	Double-clicked QListWidgetItem from the inner list.

Returns: None.

Errors: Returns when editing is disabled; otherwise Qt errors propagate.

Side effects: Emits item_double_clicked(row).

Referenced in source (1)

• StepListPanel._build_ui — mtc_gui.step_list_panel

StepListPanel._on_selection_changed()

Forward the current sorted selection to consumers.

Callback · Source

_on_selection_changed(self)

Returns: None.

Errors: Selection/signal errors propagate.

Side effects: Emits selection_changed(selected_indices()).

Referenced in source (1)

• StepListPanel._build_ui — mtc_gui.step_list_panel

StepListPanel._tick_elapsed()

Update the current row’s timer when its index is valid and always refresh total elapsed time.

Callback · Source

_tick_elapsed(self)

Returns: None.

Errors: Qt errors propagate.

Side effects: Changes elapsed labels; a non-running row’s own update_elapsed is a no-op.

Referenced in source (1)

• StepListPanel.__init__ — mtc_gui.step_list_panel

StepRowWidget

Render one task’s number, summary, status, and elapsed time. StepListPanel updates these widgets as the queue or execution state changes.

Inherits from: QFrame.

StepRowWidget.__init__()

Create one task row with its summary, status, and timing display.

Lifecycle · Source

__init__(self, index: int, task_type: str, detail_text: str, parent=None)

Parameter	Meaning
index	Zero-based queue index displayed as index + 1 with at least two digits.
task_type	Task type used in TASK_TYPE_CONFIG; unknown types show a question mark and their raw name.
detail_text	Step summary displayed as the subtitle.
parent	Optional parent widget.

Errors: Qt errors propagate; unknown task types have a fallback.

Side effects: Creates the 52-pixel row in PENDING state with no timer start or next badge.

Referenced in source (1)

• StepListPanel.refresh — mtc_gui.step_list_panel

StepRowWidget.update_content()

Reuse an existing row for new queue content while resetting its execution display.

Method · Source

update_content(self, index: int, task_type: str, detail_text: str)

Parameter	Meaning
index	New zero-based queue index.
task_type	New type key, with the same unknown-type fallback as construction.
detail_text	New subtitle string.

Returns: None.

Errors: Qt errors propagate.

Side effects: Updates labels/icons/colors and resets state to PENDING, start time to None, next status to False, and hides timer/check/badge.

StepRowWidget.set_state()

Set a row’s execution state and refresh status/timer/check styling.

Method · Source

set_state(self, state: StepState)

Parameter	Meaning
state	StepState.PENDING, RUNNING, DONE, or FAILED.

Returns: None.

Errors: Invalid state keys raise KeyError after some state mutation; no validation wrapper exists.

Side effects: RUNNING restarts its monotonic elapsed timer at zero; other states hide it. DONE shows a check; status icon and row background update. Next-badge state is managed separately.

StepRowWidget.set_is_next()

Show the next-step badge only for a pending row marked as next.

Method · Source

set_is_next(self, is_next: bool)

Parameter	Meaning
is_next	Boolean next-step flag.

Returns: None.

Errors: Qt errors propagate.

Side effects: Updates _is_next and next-badge visibility.

StepRowWidget.update_elapsed()

Refresh a running row’s elapsed label from monotonic time.

Method · Source

update_elapsed(self)

Returns: None.

Errors: No explicit error handling.

Side effects: Displays whole elapsed minutes and zero-padded seconds only while RUNNING with a start time.

Internal callbacks and helpers

StepRowWidget._apply_state_style()

Refresh the row’s appearance for its execution state.

Internal helper · Source

_apply_state_style(self)

Returns: None.

Errors: Qt stylesheet errors propagate.

Side effects: Updates the row stylesheet and left-border stylesheet.

Referenced in source (3)

• StepRowWidget.__init__ — mtc_gui.step_list_panel
• StepRowWidget.set_state — mtc_gui.step_list_panel
• StepRowWidget.update_content — mtc_gui.step_list_panel

ExecutionToolbar

Render the overall execution status, progress, and elapsed time above the queue. StepListPanel controls its lifetime and values.

Inherits from: QFrame.

ExecutionToolbar.__init__()

Create the overall execution status, progress, and timing display.

Lifecycle · Source

__init__(self, parent=None)

Parameter	Meaning
parent	Optional parent widget.

Errors: Qt construction errors propagate.

Side effects: Creates a compact toolbar with no active elapsed-time origin.

Referenced in source (1)

• StepListPanel._build_ui — mtc_gui.step_list_panel

ExecutionToolbar.start()

Start total elapsed timing and initialize progress for an execution beginning partway through a queue.

Method · Source

start(self, total_steps: int, start_index: int=0)

Parameter	Meaning
total_steps	Full queue length used for displayed denominator and initial percent; zero avoids division.
start_index	Zero-based index where execution starts.

Returns: None.

Errors: No range validation; Qt errors propagate.

Side effects: Stores time.monotonic(), shows Step start_index+1/total_steps, sets percentage from start_index/total_steps, and clears task/elapsed text.

ExecutionToolbar.update_progress()

Display current step, task title, and integer percentage.

Method · Source

update_progress(
    self,
    current_step: int,
    total_steps: int,
    task_name: str,
    progress_pct: float,
)

Parameter	Meaning
current_step	Already display-ready one-based step number.
total_steps	Displayed total queue-step count.
task_name	Task-type key mapped to a friendly title, or displayed raw when unknown.
progress_pct	Percentage converted to int and passed to QProgressBar.

Returns: None.

Errors: Invalid numeric conversion/Qt errors propagate; no explicit percentage bounds check.

Side effects: Updates step/task labels and progress value.

ExecutionToolbar.update_elapsed()

Refresh the elapsed-time label from the stored start time.

Method · Source

update_elapsed(self)

Returns: None.

Errors: No explicit error handling.

Side effects: Updates elapsed label; paused time is included.

ExecutionToolbar.set_paused()

Change the pause indicator without stopping the elapsed timer.

Method · Source

set_paused(self, paused: bool)

Parameter	Meaning
paused	Truthy selects paused appearance.

Returns: None.

Errors: Qt errors propagate.

Side effects: Changes indicator text/color; does not stop elapsed timing.

ExecutionToolbar.reset()

Clear toolbar execution labels and remove its timing origin.

Method · Source

reset(self)

Returns: None.

Errors: Qt errors propagate.

Side effects: Sets _start_time=None, percentage zero, empty step/task text, and 00:00 elapsed; does not reset the indicator glyph.

_DropTargetListWidget

Translate external pose drops and internal row drags into signals. The main window validates and applies the resulting reorder request.

Inherits from: QListWidget.

_DropTargetListWidget.__init__()

Enable external pose drops and internal move-style queue reordering.

Lifecycle · Source

__init__(self, parent=None)

Parameter	Meaning
parent	Optional parent widget.

Errors: Qt construction errors propagate.

Side effects: Configures drag/drop flags, move default, visible drop indicator, and _reordering_enabled=True.

Referenced in source (1)

• StepListPanel._build_ui — mtc_gui.step_list_panel

Internal callbacks and helpers

_DropTargetListWidget.set_reordering_enabled()

Toggle both dragging and accepting drops with the queue-editing flag.

Internal helper · Source

set_reordering_enabled(self, enabled: bool)

Parameter	Meaning
enabled	Whether interactive queue reorder and pose drop operations are enabled.

Returns: None.

Errors: Qt errors propagate.

Side effects: Sets the internal flag and Qt dragEnabled/acceptDrops state.

_DropTargetListWidget.dragEnterEvent()

Accept custom pose-name MIME drags; delegate other drag entry events to QListWidget.

Callback · Source

dragEnterEvent(self, event)

Parameter	Meaning
event	QDragEnterEvent exposing mimeData and acceptProposedAction.

Returns: None.

Errors: Event/Qt errors propagate; this handler itself does not inspect _reordering_enabled.

Side effects: Accepts the proposed pose-drop action or invokes the base event handler.

_DropTargetListWidget.dragMoveEvent()

Keep custom pose-name MIME drags accepted while they move over the list.

Callback · Source

dragMoveEvent(self, event)

Parameter	Meaning
event	QDragMoveEvent with MIME data and proposed action.

Returns: None.

Errors: Event/Qt errors propagate; this handler itself does not inspect _reordering_enabled.

Side effects: Accepts the proposed pose-drop action or delegates to QListWidget.

_DropTargetListWidget.dropEvent()

Decode external pose names or perform internal row moves and emit their original row identities.

Callback · Source

dropEvent(self, event)

Parameter	Meaning
event	QDropEvent; pose drops use application/x-mtc-pose-name UTF-8 bytes, and internal moves require event.source() is this list.

Returns: None.

Errors: UTF-8 decoding/Qt errors propagate. Empty pose names produce no signal. Disabled/other drops are delegated to the base handler.

Side effects: Emits pose_dropped(name) for enabled pose drops. For internal moves, calls the base handler then emits steps_reordered(new_order, moved_rows) only if order changed; both lists contain pre-refresh UserRole indices.