ADR-006: UI Framework Choices

Status

Accepted

Context

MouseMaster needs a user interface for:

  • Selecting mouse model

  • Choosing and managing presets

  • Editing button mappings

  • Configuring context-sensitive bindings

  • Running button detection wizard

Slicer extensions can use:

  1. Qt Designer .ui files: Visual design, loaded at runtime

  2. Programmatic Qt: Build UI in Python code

  3. ctk widgets: Slicer’s custom widgets (ctkCollapsibleButton, etc.)

  4. qMRML widgets: MRML-aware widgets for scene data

Decision

Use Qt Designer .ui files as the primary UI definition, supplemented with programmatic Qt for dynamic elements.

UI Structure

MouseMaster.ui
├── qMRMLWidget (top-level, scene connection)
│   ├── ctkCollapsibleButton: "Mouse Selection"
│   │   ├── QComboBox: mouseSelector
│   │   └── QPushButton: detectMouseButton
│   │
│   ├── ctkCollapsibleButton: "Preset"
│   │   ├── QComboBox: presetSelector
│   │   ├── QPushButton: savePresetButton
│   │   ├── QPushButton: exportPresetButton
│   │   └── QPushButton: importPresetButton
│   │
│   ├── ctkCollapsibleButton: "Button Mappings"
│   │   └── QTableWidget: mappingTable
│   │
│   └── ctkCollapsibleButton: "Advanced" (collapsed by default)
│       ├── QCheckBox: contextSensitiveCheckbox
│       └── QTableWidget: contextMappingTable

Design Principles

  1. Collapsible sections: Use ctkCollapsibleButton for organization

  2. Minimal clutter: Hide advanced options by default

  3. Immediate feedback: Changes apply immediately (no separate “Apply” button for mappings)

  4. Standard Slicer patterns: Match other Slicer modules’ look and feel

Dynamic Elements

Some UI elements are built programmatically:

  • Action selector dropdowns (populated from ActionRegistry)

  • Button detection wizard dialog

  • Context-specific mapping rows

Consequences

Positive

  • Qt Designer provides visual design environment

  • .ui files are readable XML (git-friendly)

  • Easy to iterate on layout without code changes

  • Standard Slicer patterns (ctk) for consistency

  • Designers can contribute without Python knowledge

Negative

  • Qt Designer requires separate installation/learning

  • Split between .ui and programmatic code can be confusing

  • Dynamic elements require Python code anyway

Neutral

  • Need to maintain both .ui file and Python connections

  • UI modifications require updating both if widgets change

References