qt6-desktop-ux

Qt6 デスクトップ UX パターン

1. QDockWidget（ドッキング可能なパネル）

使用する場面

• ナビゲーターパネル
• プロパティパネル
• ログパネル
• その他のサイドパネル

パターン

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（視覚的なグループ化）

使用する場面

• 関連するコントロールをグループ化する
• 設定セクション
• フォームセクション

パターン

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. 間隔とマージン

標準値

• コントロール間：6px
• グループのマージン：11px
• ダイアログのマージン：11px

パターン

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

4. QSizePolicy

ポリシー

ポリシー	動作
Fixed	固定サイズ。伸縮しません
Preferred	推奨サイズ。縮小・拡大できます
Expanding	利用可能なスペースを埋めます
Minimum	最小サイズ以上
Maximum	最大サイズ以下

パターン

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

5. ストレッチ係数

レイアウト内

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

6. QDialog（モーダルウィンドウ）

パターン

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. アクセシビリティ

すべてのコントロールで必須

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

タブ順序

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

8. レスポンシブデザイン

最小サイズ

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

最大サイズ（必要な場合）

widget->setMaximumWidth(400);

9. QToolBar

パターン

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. テーマ連携

テーマの変更に接続する

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

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

新しいテーマカラーの追加

コンポーネントに新しいカスタムカラーが必要な場合は、自動化スクリプトを使用します。

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

詳しいドキュメントについては、kalahari-coding スキルを参照してください。

11. Qt6 ドキュメント（Context7 MCP）

Qt6 の API、シグナル、スロット、プロパティがわからない場合は、必ず最初に Context7 を確認してください。

ステップ 1：Qt6 ライブラリ ID を解決する（セッションごとに 1 回）

mcp__context7__resolve-library-id("Qt6")

戻り値：/qt/qtdoc など

ステップ 2：特定のトピックのドキュメントを取得する

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

よく調べる Qt6 のトピック：

トピック	使用する場面
QDockWidget	ドッキング可能なパネルの作成
QDialog	モーダルダイアログ
QLayout	レイアウト管理
QSizePolicy	ウィジェットのサイズ設定動作
signals slots	シグナル／スロット接続
QToolBar	ツールバーの作成
QAction	アクション／コマンドのパターン
QStyle	スタイル設定とテーマ設定

Context7 を使用する場面：

• ✅ メソッドのパラメーターがわからない場合
• ✅ 利用可能なシグナル／スロットを知る必要がある場合
• ✅ Qt6 固有のパターンを調べる場合
• ✅ 非推奨になっているか確認する場合