【C++】Qt QToolBoxの使い方：直感的なウィジェット管理と基本操作テクニック

2025-04-29更新日: 2025-04-29

C++でQtのQToolBoxを使えば、複数のウィジェットをタブ形式で管理でき、各ページは直感的に切り替えられる点が魅力です。

まず、QToolBoxのインスタンスを生成し、QWidgetを使って各ページを作成、addItemで追加します。

ページごとにタイトル、アイコン、ツールチップを設定できるため、ユーザーに分かりやすいインターフェースを実現できます。

目次から探す

QToolBoxの基本機能

QToolBoxの役割と概要

QToolBoxは、複数のウィジェットをタブ形式で整理できる便利なコンテナです。

たくさんのコンテンツを1つのウィンドウにまとめる際、スムーズな切り替えが実現し、ユーザーに直感的な操作感を提供します。

ウィジェット管理の利点

ウィジェット同士の整理が簡単になり、操作しやすいインターフェースを作ることができる
必要な情報や機能をタブごとに分けることで、使いやすさが向上する
各ページごとに個別のレイアウトやウィジェットを設定可能なため、柔軟なデザインが楽しめる

他のコンテナウィジェットとの比較

QTabWidgetとの違いには、表示スタイルや切り替え方法がある
QToolBoxは、アコーディオン形式の操作が可能なため、情報の階層が深い場合にも使いやすい
デザイン面でのカスタマイズが容易なため、シンプルなタブ切り替えに加え、よりリッチなレイアウトが求められる場合にも適している

基本操作の実装

QToolBoxのインスタンス生成

簡単にインスタンスを生成できるため、必要な場所で手軽に利用できます。

まず、QApplicationとQToolBoxのインスタンスを準備し、ウィジェット管理のベースとして利用します。

#include <QApplication>
#include <QToolBox>
#include <QWidget>
#include <QLabel>
#include <QVBoxLayout>
int main(int argc, char *argv[]) {
    QApplication app(argc, argv);
    // QToolBoxのインスタンスを作成
    QToolBox *toolBox = new QToolBox();
    // メインウィンドウとしてQToolBoxを表示
    toolBox->resize(300, 200);
    toolBox->show();
    return app.exec();
}

(ウィンドウが表示され、空のQToolBoxが見える)

上記のサンプルコードは、必要なヘッダーをインクルードし、基本的なウィンドウ表示を実現する例です。

初めて使うときに参考になるコードです。

ページの追加と削除

QToolBoxにページを追加することで、複数の項目を管理できるようになります。

ページの追加は簡単な手順で実現でき、必要に応じてページの削除も可能です。

ページ追加時のポイント

addItemメソッドを使ってページを追加する
各ページはQWidgetで作成し、さらにレイアウトやウィジェットを配置できる
ページのタイトルはaddItemの第2引数に指定し、直感的に管理できる

以下に、ページ追加のサンプルコードを示します。

#include <QApplication>
#include <QToolBox>
#include <QWidget>
#include <QLabel>
#include <QVBoxLayout>
int main(int argc, char *argv[]) {
    QApplication app(argc, argv);
    QToolBox *toolBox = new QToolBox();
    // ページ1の作成
    QWidget *page1 = new QWidget();
    QVBoxLayout *layout1 = new QVBoxLayout(page1);
    QLabel *label1 = new QLabel("こちらはページ1です");
    layout1->addWidget(label1);
    toolBox->addItem(page1, "ページ1");
    // ページ2の作成
    QWidget *page2 = new QWidget();
    QVBoxLayout *layout2 = new QVBoxLayout(page2);
    QLabel *label2 = new QLabel("こちらはページ2です");
    layout2->addWidget(label2);
    toolBox->addItem(page2, "ページ2");
    toolBox->resize(300, 200);
    toolBox->show();
    return app.exec();
}

(ウィンドウに「ページ1」と「ページ2」のタブが表示され、それぞれのページを切り替えられる)

ページ削除時の注意事項

特定のページを削除する場合は、removeItemメソッドを使用する
インデックスに注意して削除する必要があるため、削除前に現在のページ数を確認すると安心
削除後に残ったページの順番が変わるため、表示インデックスが変わる点に気を付ける

ページ削除のコード例は以下の通り。

#include <QApplication>
#include <QToolBox>
#include <QWidget>
#include <QLabel>
#include <QVBoxLayout>
int main(int argc, char *argv[]) {
    QApplication app(argc, argv);
    QToolBox *toolBox = new QToolBox();
    QWidget *page1 = new QWidget();
    QVBoxLayout *layout1 = new QVBoxLayout(page1);
    layout1->addWidget(new QLabel("ページ1の内容"));
    toolBox->addItem(page1, "ページ1");
    QWidget *page2 = new QWidget();
    QVBoxLayout *layout2 = new QVBoxLayout(page2);
    layout2->addWidget(new QLabel("ページ2の内容"));
    toolBox->addItem(page2, "ページ2");
    // インデックス0のページを削除する
    toolBox->removeItem(0);
    toolBox->resize(300, 200);
    toolBox->show();
    return app.exec();
}

(「ページ2」のみ表示され、インデックス0のページが削除される)

ページ設定のカスタマイズ

タイトルの設定方法

ページのタイトルは、addItem時に指定できるほか、後から変更することも可能です。

タイトルを変更するには、setItemTextメソッドを利用します。

#include <QApplication>
#include <QToolBox>
#include <QWidget>
#include <QLabel>
#include <QVBoxLayout>
int main(int argc, char *argv[]) {
    QApplication app(argc, argv);
    QToolBox *toolBox = new QToolBox();
    QWidget *page = new QWidget();
    QVBoxLayout *layout = new QVBoxLayout(page);
    layout->addWidget(new QLabel("サンプルページの内容"));
    toolBox->addItem(page, "初期タイトル");
    // タイトルを変更する
    toolBox->setItemText(0, "新しいタイトル");
    toolBox->resize(300, 200);
    toolBox->show();
    return app.exec();
}

(ウィンドウに新しいタイトルが反映されたタブが表示される)

アイコンの設定方法

ページのデザインをより魅力的にするために、アイコンを設定することができます。

setItemIconメソッドにより、ページに画像を割り当てることが可能です。

#include <QApplication>
#include <QToolBox>
#include <QWidget>
#include <QLabel>
#include <QVBoxLayout>
#include <QIcon>
int main(int argc, char *argv[]) {
    QApplication app(argc, argv);
    QToolBox *toolBox = new QToolBox();
    QWidget *page = new QWidget();
    QVBoxLayout *layout = new QVBoxLayout(page);
    layout->addWidget(new QLabel("ページにアイコンが設定されています"));
    toolBox->addItem(page, "アイコン付き");
    // アイコンファイルのパスを正しく指定してください
    QIcon icon(":/resources/icon.png");
    toolBox->setItemIcon(0, icon);
    toolBox->resize(300, 200);
    toolBox->show();
    return app.exec();
}

(ウィンドウのタブに指定したアイコンが表示される)

ツールチップの設定

各ページにツールチップを設定すると、ユーザーがマウスを合わせた際に補足情報が表示され、使いやすさが向上します。

#include <QApplication>
#include <QToolBox>
#include <QWidget>
#include <QLabel>
#include <QVBoxLayout>
int main(int argc, char *argv[]) {
    QApplication app(argc, argv);
    QToolBox *toolBox = new QToolBox();
    QWidget *page = new QWidget();
    QVBoxLayout *layout = new QVBoxLayout(page);
    layout->addWidget(new QLabel("ツールチップが設定されたページ"));
    toolBox->addItem(page, "ツールチップ");
    // ツールチップの設定
    toolBox->setItemToolTip(0, "このページはツールチップで説明されています");
    toolBox->resize(300, 200);
    toolBox->show();
    return app.exec();
}

(ウィンドウに表示されたタブにマウスカーソルを合わせると、設定されたツールチップが表示される)

ツールチップ活用例

各ページの内容について簡単な説明を表示
ユーザーが各タブの目的を把握しやすくなる
情報量が多い場合に、補足情報として利用することで表示エリアをすっきり保つ

ページ切替とイベント操作

現在ページの取得と設定

現在表示されているページのインデックスを取得するためには、currentIndexメソッドを利用します。

特定のページに切り替える場合は、setCurrentIndexメソッドを利用します。

#include <QApplication>
#include <QToolBox>
#include <QWidget>
#include <QLabel>
#include <QVBoxLayout>
int main(int argc, char *argv[]) {
    QApplication app(argc, argv);
    QToolBox *toolBox = new QToolBox();
    QWidget *page1 = new QWidget();
    QVBoxLayout *layout1 = new QVBoxLayout(page1);
    layout1->addWidget(new QLabel("内容1"));
    toolBox->addItem(page1, "ページ1");
    QWidget *page2 = new QWidget();
    QVBoxLayout *layout2 = new QVBoxLayout(page2);
    layout2->addWidget(new QLabel("内容2"));
    toolBox->addItem(page2, "ページ2");
    // 現在のページインデックスを取得
    int currentPage = toolBox->currentIndex();
    // インデックス1のページに切り替え
    toolBox->setCurrentIndex(1);
    toolBox->resize(300, 200);
    toolBox->show();
    return app.exec();
}

(ウィンドウが起動し、最初はデフォルトのページが表示され、その後インデックス1のページに切り替わる)

イベント処理の基礎

イベント処理を行うことで、ユーザーの操作に応じた動作が可能になります。

Qtのシグナルとスロット機構を利用すると、柔軟にイベントを処理することができます。

シグナルとスロットの連携

たとえば、ページ変更時にシグナルが送出されるので、これにスロットを接続するコード例を下記に示します。

#include <QApplication>
#include <QToolBox>
#include <QWidget>
#include <QLabel>
#include <QVBoxLayout>
#include <QObject>
#include <QDebug>
void onCurrentChanged(int index) {
    qDebug() << "現在のページはインデックス" << index << "に切り替えました";
}
int main(int argc, char *argv[]) {
    QApplication app(argc, argv);
    QToolBox *toolBox = new QToolBox();
    QWidget *page1 = new QWidget();
    QVBoxLayout *layout1 = new QVBoxLayout(page1);
    layout1->addWidget(new QLabel("ページ1の内容"));
    toolBox->addItem(page1, "ページ1");
    QWidget *page2 = new QWidget();
    QVBoxLayout *layout2 = new QVBoxLayout(page2);
    layout2->addWidget(new QLabel("ページ2の内容"));
    toolBox->addItem(page2, "ページ2");
    // シグナルとスロットの接続
    QObject::connect(toolBox, &QToolBox::currentChanged, onCurrentChanged);
    toolBox->resize(300, 200);
    toolBox->show();
    return app.exec();
}

# ページ切替時に、コンソールに現在のページインデックスが表示される
現在のページはインデックス 1 に切り替えました
現在のページはインデックス 0 に切り替えました

カスタムイベント処理

特別な動作が必要な場合には、QToolBoxのサブクラスを作成し、イベントハンドラを上書きすることも可能です。

たとえば、マウスイベントやキーボードイベントのカスタマイズにより、独自の動作を実現できます。

以下はカスタムイベントの例のひとつ。

#include <QApplication>
#include <QToolBox>
#include <QWidget>
#include <QLabel>
#include <QVBoxLayout>
#include <QMouseEvent>
#include <QDebug>
// QToolBoxを継承してカスタムイベント処理を追加
class CustomToolBox : public QToolBox {
public:
    CustomToolBox(QWidget *parent = nullptr) : QToolBox(parent) {}
protected:
    void mousePressEvent(QMouseEvent *event) override {
        qDebug() << "マウスボタンが押されました。";
        QToolBox::mousePressEvent(event);
    }
};
int main(int argc, char *argv[]) {
    QApplication app(argc, argv);
    CustomToolBox *toolBox = new CustomToolBox();
    QWidget *page = new QWidget();
    QVBoxLayout *layout = new QVBoxLayout(page);
    layout->addWidget(new QLabel("カスタムイベントのページ"));
    toolBox->addItem(page, "カスタムページ");
    toolBox->resize(300, 200);
    toolBox->show();
    return app.exec();
}

(ウィンドウのタブをクリックすると、コンソールに「マウスボタンが押されました。」と表示される)

外観とレイアウトの調整

スタイルシートによるカスタマイズ

スタイルシートを用いると、直感的に背景色やフォントなどの見た目を変更できます。

柔らかい印象を与えるカスタマイズもお手軽に実施可能です。

背景色とフォントの変更

次のコード例では、CSSを用いて背景色とフォントサイズを変更しています。

#include <QApplication>
#include <QToolBox>
#include <QWidget>
#include <QLabel>
#include <QVBoxLayout>

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    QToolBox *toolBox = new QToolBox();
    toolBox->setAttribute(Qt::WA_StyledBackground);      // ←★ 背景塗りを許可

    // ページを 1 枚だけ追加
    QWidget *page = new QWidget();
    QVBoxLayout *layout = new QVBoxLayout(page);
    layout->addWidget(new QLabel(u8"スタイルシートでカスタマイズされたページ"));
    toolBox->addItem(page, u8"スタイルページ");

    // スタイルシート
    toolBox->setStyleSheet(
        // 本体（pane）
        "QToolBox {"
        "  background:#f0f0f0;"          // 背景色
        "  border:1px solid #808080;"    // 任意：枠線
        "}"

        // タブ
        "QToolBox::tab {"
        "  background:#d0d0ff;"
        "  padding:4px 8px;"
        "  font-size:14px;"
        "}"

        // 選択中のタブ
        "QToolBox::tab:selected {"
        "  background:#8080ff;"
        "  color:white;"
        "  font-weight:bold;"
        "}"
        );

    toolBox->resize(300, 200);
    toolBox->show();
    return app.exec();
}

境界線とパディングの調整

境界線やパディングもスタイルシートで調整できるため、より一層洗練された見た目にカスタマイズ可能です。

#include <QApplication>
#include <QToolBox>
#include <QWidget>
#include <QLabel>
#include <QVBoxLayout>
int main(int argc, char *argv[]) {
    QApplication app(argc, argv);
    QToolBox *toolBox = new QToolBox();
    QWidget *page = new QWidget();
    QVBoxLayout *layout = new QVBoxLayout(page);
    layout->addWidget(new QLabel("境界線とパディング調整のサンプル"));
    toolBox->addItem(page, "調整ページ");
    // 境界線とパディングの調整
    toolBox->setStyleSheet(
        "QToolBox::tab { border: 1px solid #888; padding: 5px; }"
    );
    toolBox->resize(300, 200);
    toolBox->show();
    return app.exec();
}

(各タブに薄い境界線と適度なパディングが適用され、見やすいデザインになる)

レイアウトの工夫

ウィジェット内で、垂直レイアウトや水平レイアウトを組み合わせることで、情報を整理整頓し、ユーザーに優しい見た目を実現できます。

垂直レイアウトと水平レイアウトの選択

シンプルな構造の場合は、垂直レイアウトが使いやすく、画面スペースを有効に活用できます。

複数のウィジェットを横並びに配置する場合には水平レイアウトを用いると、視認性が向上します。

垂直レイアウト：

ウィジェットが上から下に順番に配置されるため、読みやすい

水平レイアウト：

ウィジェットが左右に並び、スペースの活用がしやすい

トラブルシューティングと最適化

よくあるエラーの対処方法

ページ追加時にレイアウトが反映されない場合、ウィジェットのサイズやレイアウト設定の確認をする
インデックス指定のエラーは、追加順序や削除後のインデックス確認を行うことで解決できる
スタイルシートの効果が反映されない場合、指定のセレクタやプロパティを再確認する

パフォーマンス改善のポイント

大量のページを扱う場合、リソースの消費が気になることがあるため、適切なリソース管理と動的なページ生成を心掛けます。

メモリ管理とリソースの最適化

不要なウィジェットは削除して、メモリリークが起こらないように注意する
動的にページを生成し、使用状況に応じてキャッシュする手法も検討する
Qtのスマートポインタや親子関係を利用して、メモリ管理を容易にする

既存ウィジェットとの連携

QToolBox内でのウィジェット統合

QToolBoxは、複数のウィジェットやコンポーネントを1つの管理画面にまとめることができるため、複雑なUIでも扱いやすくなります。

たとえば、リストウィジェットやボタン、入力フォームなど、さまざまなウィジェットを組み合わせることが可能です。

複数ページ間の連携方法

各ページで異なる機能や情報をまとめ、ユーザーが簡単に切り替えられるようにする
異なるウィジェット間でデータを共有する際は、SignalやSlotを活用することでスムーズな連携が実現できる
必要に応じて、複数ページを動的に同期するロジックを実装すると使い勝手が向上する

まとめ

今回紹介した内容で、QToolBoxの基本機能から実装のポイント、カスタマイズ方法、イベント処理、外観調整、エラー対策まで幅広くご紹介しました。

各項目の例やサンプルコードを参考に、柔軟で扱いやすいウィジェット管理ができるよう工夫してほしいです。

効率的にUI設計を進めるためのヒントが多数詰まっているので、実際の開発で積極的に応用していただければ嬉しいです。