qt6-desktop-ux

Qt6 Desktop UX Patterns

1. QDockWidget (Dockable Panels)

When to use

• Navigator panel
• Properties panel
• Log panel
• Any side panel

Pattern

QDockWidget* dock = new QDockWidget(tr("Panel Title"), parent);
dock->setObjectName("uniquePanelName");  // for state persistence
dock->setAllowedAreas(Qt::LeftDockWidgetArea | Qt::RightDockWidgetArea);
dock->setFeatures(QDockWidget::DockWidgetMovable |
                  QDockWidget::DockWidgetClosable |
                  QDockWidget::DockWidgetFloatable);

QWidget* content = new QWidget();
// ... setup content layout
dock->setWidget(content);

parent->addDockWidget(Qt::RightDockWidgetArea, dock);

2. QGroupBox (Visual Grouping)

When to use

• Group related controls
• Settings sections
• Form sections

Pattern

QGroupBox* group = new QGroupBox(tr("Section Title"));
QVBoxLayout* groupLayout = new QVBoxLayout(group);

// Add controls to groupLayout
groupLayout->addWidget(control1);
groupLayout->addWidget(control2);

// Add group to parent layout
mainLayout->addWidget(group);

3. Spacing and Margins

Standard values

• Between controls: 6px
• Group margins: 11px
• Dialog margins: 11px

Pattern

layout->setSpacing(6);
layout->setContentsMargins(11, 11, 11, 11);

4. QSizePolicy

Policies

Policy	Behavior
Fixed	Exact size, no stretching
Preferred	Preferred size, can shrink/grow
Expanding	Fills available space
Minimum	At least minimum size
Maximum	At most maximum size

Pattern

widget->setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Fixed);

5. Stretch Factors

In layouts

layout->addWidget(widget1, 0);  // fixed
layout->addWidget(widget2, 1);  // fills remaining space
layout->addStretch(1);          // spacer that expands

6. QDialog (Modal Windows)

Pattern

class MyDialog : public QDialog {
    Q_OBJECT
public:
    explicit MyDialog(QWidget* parent = nullptr);

private:
    void setupUI();
    void createConnections();

    // Controls as members
    QLineEdit* m_nameEdit;
    QDialogButtonBox* m_buttonBox;
};

MyDialog::MyDialog(QWidget* parent)
    : QDialog(parent)
{
    setWindowTitle(tr("Dialog Title"));
    setupUI();
    createConnections();
}

void MyDialog::setupUI() {
    QVBoxLayout* mainLayout = new QVBoxLayout(this);

    // Content
    m_nameEdit = new QLineEdit();
    mainLayout->addWidget(m_nameEdit);

    // Standard buttons
    m_buttonBox = new QDialogButtonBox(
        QDialogButtonBox::Ok | QDialogButtonBox::Cancel);
    mainLayout->addWidget(m_buttonBox);
}

void MyDialog::createConnections() {
    connect(m_buttonBox, &QDialogButtonBox::accepted, this, &QDialog::accept);
    connect(m_buttonBox, &QDialogButtonBox::rejected, this, &QDialog::reject);
}

7. Accessibility

Required for all controls

widget->setToolTip(tr("Descriptive tooltip"));
widget->setWhatsThis(tr("Detailed help text"));
widget->setAccessibleName(tr("Name for screen readers"));

Tab order

setTabOrder(widget1, widget2);
setTabOrder(widget2, widget3);

8. Responsive Design

Minimum sizes

widget->setMinimumWidth(200);
widget->setMinimumHeight(100);

Maximum sizes (when needed)

widget->setMaximumWidth(400);

9. QToolBar

Pattern

QToolBar* toolbar = new QToolBar(tr("Main Toolbar"), parent);
toolbar->setObjectName("mainToolbar");
toolbar->setMovable(true);
toolbar->setIconSize(QSize(24, 24));

// Add actions (use ArtProvider!)
QAction* action = core::ArtProvider::getInstance().createAction("file.new", tr("New"), toolbar);
toolbar->addAction(action);
toolbar->addSeparator();

10. Theme Integration

Connect to theme changes

connect(&core::ThemeManager::getInstance(), &core::ThemeManager::themeChanged,
        this, &MyWidget::onThemeChanged);

void MyWidget::onThemeChanged() {
    // Update colors, refresh UI
    update();
}

Adding new theme colors

When a component needs a new custom color, use the automated script:

python scripts/add_theme_color.py colorName "#darkHex" "#lightHex" -d "description" -s

See kalahari-coding skill for full documentation.

11. Qt6 Documentation (Context7 MCP)

When unsure about Qt6 API, signals, slots, or properties - ALWAYS check Context7 first:

Step 1: Resolve Qt6 library ID (once per session)

mcp__context7__resolve-library-id("Qt6")

Returns: /qt/qtdoc or similar

Step 2: Get documentation for specific topic

mcp__context7__query-docs(
    context7CompatibleLibraryID="/qt/qtdoc",
    topic="QDockWidget"
)

Common Qt6 topics to look up:

Topic	When to use
QDockWidget	Creating dockable panels
QDialog	Modal dialogs
QLayout	Layout management
QSizePolicy	Widget sizing behavior
signals slots	Signal/slot connections
QToolBar	Toolbar creation
QAction	Action/command patterns
QStyle	Styling and theming

When to use Context7:

• ✅ Unsure about method parameters
• ✅ Need to know available signals/slots
• ✅ Looking for Qt6-specific patterns
• ✅ Checking deprecation status