Qt アプリ開発：QTabWidget でアイコン付きタブを実現する方法まとめ

2025-05-27

QTabWidget::setTabIcon()

QTabWidget クラスのこの関数は、タブに表示されるアイコンを設定するために使用されます。タブコントロールは、複数の子ウィジェットを積み重ねて表示し、それぞれのウィジェットには対応するタブが付いています。setTabIcon() を使うことで、これらのタブのテキストラベルの横に小さなアイコンを表示させ、視覚的にタブの内容を区別したり、特定の意味合いを持たせたりすることができます。

役割
指定されたインデックスのタブにアイコンを設定する。
関数
setTabIcon()
クラス
QTabWidget

引数

setTabIcon() 関数は通常、以下の2つの引数を取ります。

int index: アイコンを設定したいタブのインデックス（0から始まる整数）。タブが追加された順にインデックスが割り振られます。
const QIcon &icon: 設定したいアイコン。QIcon クラスのオブジェクトとして渡されます。QIcon は、様々なサイズや状態で表示できるスケーラブルなアイコンを扱うためのクラスです。

戻り値

この関数は値を返しません (void)。

使用例

例えば、QTabWidget に2つのタブがあり、それぞれのタブにアイコンを設定したい場合、以下のようになります。

#include <QApplication>
#include <QTabWidget>
#include <QIcon>
#include <QWidget>
#include <QVBoxLayout>
#include <QLabel>

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

    QTabWidget *tabWidget = new QTabWidget;

    // 最初のタブを作成
    QWidget *tab1 = new QWidget;
    QVBoxLayout *layout1 = new QVBoxLayout;
    layout1->addWidget(new QLabel("最初のタブの内容"));
    tab1->setLayout(layout1);
    tabWidget->addTab(tab1, "タブ1");

    // 2番目のタブを作成
    QWidget *tab2 = new QWidget;
    QVBoxLayout *layout2 = new QVBoxLayout;
    layout2->addWidget(new QLabel("2番目のタブの内容"));
    tab2->setLayout(layout2);
    tabWidget->addTab(tab2, "タブ2");

    // アイコンを設定
    tabWidget->setTabIcon(0, QIcon(":/images/icon1.png")); // 最初のタブに icon1.png を設定
    tabWidget->setTabIcon(1, QIcon(":/images/icon2.png")); // 2番目のタブに icon2.png を設定

    tabWidget->show();

    return app.exec();
}

上記の例では、まず2つのタブを持つ QTabWidget を作成し、それぞれのタブにラベルを追加しています。その後、setTabIcon() 関数を使って、インデックス 0 の最初のタブに "icon1.png" というアイコンを、インデックス 1 の2番目のタブに "icon2.png" というアイコンを設定しています。

タブにアイコンを設定することで、ユーザーはタブの内容をより直感的に理解しやすくなります。例えば、設定タブには歯車のアイコン、ヘルプタブには疑問符のアイコンなどを設定することが一般的です。
QIcon オブジェクトは、ファイルからロードしたり、プログラム内で作成したりすることができます。
アイコンのパスは、リソースファイル (.qrc) に登録されている相対パスや、絶対パスを指定することができます。上記の例では、":/images/icon1.png" のように、リソースシステム内のパスを指定しています。

QTabWidget::setTabIcon() に関する一般的なエラーとトラブルシューティング

QTabWidget::setTabIcon() を使用する際に遭遇しやすいエラーとその解決策について解説します。

無効なインデックスの指定

トラブルシューティング
- QTabWidget::count() 関数を使用して、現在のタブの数を取得し、指定するインデックスが 0 から count() - 1 の範囲内であることを確認してください。
- タブを追加または削除する処理がある場合は、インデックスの管理が正しく行われているかを見直してください。
- ループ処理などでインデックスを使用している場合は、ループの範囲が適切であることを確認してください。
エラー
setTabIcon() 関数の最初の引数であるインデックスが、QTabWidget が持つタブの範囲外の値を指定している場合に発生します。例えば、タブが3つしかないのにインデックスとして 3 や -1 を指定すると、予期しない動作やプログラムのクラッシュを引き起こす可能性があります。

無効な QIcon オブジェクトの指定

トラブルシューティング
- QIcon オブジェクトがファイルからロードされている場合 (QIcon("パス"))、指定されたパスが正しいか、ファイルが実際に存在するかを確認してください。相対パスを使用している場合は、アプリケーションの実行時のワーキングディレクトリからの相対パスが正しいかを確認してください。
- リソースファイル (.qrc) を使用している場合は、アイコンファイルがリソースファイルに正しく登録されており、パスの指定 (":/prefix/filename.png") が正しいかを確認してください。
- プログラム内で QIcon を作成している場合は、作成ロジックに誤りがないかを確認してください。
- QIcon::isNull() 関数を使用して、QIcon オブジェクトが空かどうかをチェックし、空の場合はその原因を調査してください。
エラー
setTabIcon() 関数の2番目の引数として渡された QIcon オブジェクトが有効でない場合、タブにアイコンが表示されません。これは、アイコンファイルが存在しない、パスが間違っている、または QIcon オブジェクトが正しく初期化されていない場合に起こり得ます。

アイコンが表示されない (見た目の問題)

トラブルシューティング
- アイコンファイルの形式
  Qt がサポートしている画像形式 (PNG, JPG, GIF など) のファイルを使用しているか確認してください。
- アイコンのサイズ
  アイコンが小さすぎる場合や大きすぎる場合に、見えにくいことがあります。適切なサイズのアイコンを用意するか、QIcon がスケーラブルな形式 (SVG など) をサポートしているか検討してください。
- テーマとの競合
  システムのデスクトップ環境のテーマによっては、アプリケーションのアイコン表示に影響を与える場合があります。異なるテーマで試してみるか、アプリケーションのスタイルシートでアイコンのスタイルを明示的に設定することを検討してください。
- タブのスタイル
  QTabWidget のスタイルシートがアイコンの表示に影響を与えている可能性があります。例えば、アイコン領域の幅が狭すぎる場合などです。スタイルシートを確認し、必要に応じて修正してください。
- 他のタブとの比較
  他のタブにはアイコンが表示されているか確認し、特定の一つのタブでのみ問題が発生する場合は、そのタブの設定に問題がある可能性があります。
問題
setTabIcon() を呼び出しても、タブにアイコンが表示されない、または意図したサイズや品質で表示されない場合があります。

リソースファイルのコンパイル忘れ

トラブルシューティング
- プロジェクトのビルドプロセスでリソースファイルが正しくコンパイルされているか確認してください。Qt Creator を使用している場合は、プロジェクトファイルを右クリックして "Run qmake" を実行し、再度ビルドしてみてください。
エラー
リソースファイル (.qrc) にアイコンファイルを登録している場合、リソースファイルをコンパイルしてアプリケーションに組み込む必要があります。コンパイルを忘れると、QIcon(":/...") のようなパスでアイコンをロードしようとしても失敗します。

スレッドの問題 (可能性は低いが)

トラブルシューティング
- GUI 関連の操作は、QMetaObject::invokeMethod() を使用してメインスレッドで実行するようにしてください。
問題
GUI 操作は通常メインスレッドで行う必要があります。もし別のスレッドから setTabIcon() を呼び出している場合、予期しない動作を引き起こす可能性があります。

簡単なテストプログラムを作成し、setTabIcon() の基本的な動作を確認することで、問題の切り分けを行うことができます。
qDebug() などの Qt のデバッグ出力機能を使用して、setTabIcon() が呼び出されているか、渡されているインデックスや QIcon オブジェクトの状態などを確認すると、問題の原因を特定しやすくなります。

QTabWidget::setTabIcon() のプログラミング例

ここでは、QTabWidget::setTabIcon() の基本的な使い方から、少し応用的な例までを紹介します。

例1: 基本的なアイコン設定

この例では、2つのタブを持つ QTabWidget を作成し、それぞれのタブに異なるアイコンを設定します。

#include <QApplication>
#include <QTabWidget>
#include <QWidget>
#include <QVBoxLayout>
#include <QLabel>
#include <QIcon>

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

    QTabWidget *tabWidget = new QTabWidget;

    // 最初のタブを作成
    QWidget *tab1 = new QWidget;
    QVBoxLayout *layout1 = new QVBoxLayout;
    layout1->addWidget(new QLabel("最初のタブの内容"));
    tab1->setLayout(layout1);
    tabWidget->addTab(tab1, "タブ1");

    // 2番目のタブを作成
    QWidget *tab2 = new QWidget;
    QVBoxLayout *layout2 = new QVBoxLayout;
    layout2->addWidget(new QLabel("2番目のタブの内容"));
    tab2->setLayout(layout2);
    tabWidget->addTab(tab2, "タブ2");

    // アイコンを設定 (リソースファイルからの読み込みを想定)
    tabWidget->setTabIcon(0, QIcon(":/icons/home.png"));
    tabWidget->setTabIcon(1, QIcon(":/icons/settings.png"));

    tabWidget->show();

    return app.exec();
}

説明

QApplication, QTabWidget, QWidget, QVBoxLayout, QLabel, QIcon などの必要なクラスをインクルードします。
QTabWidget のインスタンス tabWidget を作成します。
2つの QWidget (それぞれ tab1 と tab2) を作成し、それぞれに QVBoxLayout と QLabel を追加して、タブの内容を設定します。
tabWidget->addTab() を使用して、タブとそのラベルを追加します。
tabWidget->setTabIcon() を使用して、各タブにアイコンを設定します。
- 最初の引数はタブのインデックス (0から始まる) です。
- 2番目の引数は設定する QIcon オブジェクトです。ここでは、リソースファイル (.qrc) に登録された "home.png" と "settings.png" を使用していることを想定しています。リソースファイルのプレフィックスが /icons であると仮定しています。

例2: ファイルパスからアイコンを設定

この例では、ファイルパスを指定して QIcon オブジェクトを作成し、タブに設定します。

#include <QApplication>
#include <QTabWidget>
#include <QWidget>
#include <QVBoxLayout>
#include <QLabel>
#include <QIcon>

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

    QTabWidget *tabWidget = new QTabWidget;

    QWidget *tab1 = new QWidget;
    tabWidget->addTab(tab1, "ファイルアイコン");

    // ファイルパスから QIcon を作成
    QIcon fileIcon("path/to/your/file_icon.png"); // 実際のファイルパスに置き換えてください

    // アイコンを設定
    tabWidget->setTabIcon(0, fileIcon);

    tabWidget->show();

    return app.exec();
}

説明

QIcon fileIcon("path/to/your/file_icon.png"); の部分で、指定されたファイルパスの画像ファイルから QIcon オブジェクトを作成します。"path/to/your/file_icon.png" は、実際のアイコンファイルのパスに置き換える必要があります。
作成した fileIcon を setTabIcon() の第二引数として渡すことで、最初のタブにアイコンが設定されます。

注意
ファイルパスを指定する場合、アプリケーションの実行時にそのファイルが存在している必要があります。

例3: タブの追加時にアイコンを設定

QTabWidget::addTab() 関数は、タブのラベルだけでなく、アイコンも同時に設定できるオーバーロードがあります。

#include <QApplication>
#include <QTabWidget>
#include <QWidget>
#include <QVBoxLayout>
#include <QLabel>
#include <QIcon>

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

    QTabWidget *tabWidget = new QTabWidget;

    QWidget *tab1 = new QWidget;
    QVBoxLayout *layout1 = new QVBoxLayout;
    layout1->addWidget(new QLabel("ホーム"));
    tab1->setLayout(layout1);
    tabWidget->addTab(tab1, QIcon(":/icons/home.png"), "ホーム"); // アイコンとラベルを同時に設定

    QWidget *tab2 = new QWidget;
    QVBoxLayout *layout2 = new QVBoxLayout;
    layout2->addWidget(new QLabel("設定"));
    tab2->setLayout(layout2);
    tabWidget->addTab(tab2, QIcon(":/icons/settings.png"), "設定"); // アイコンとラベルを同時に設定

    tabWidget->show();

    return app.exec();
}

説明

QTabWidget::addTab() のこのオーバーロードは、最初の引数にタブのウィジェット、2番目の引数に QIcon オブジェクト、3番目の引数にタブのラベルを取ります。これにより、タブの追加と同時にアイコンを設定することができます。

例4: 動的にアイコンを変更する

この例では、ボタンをクリックすることで、特定のタブのアイコンを動的に変更します。

#include <QApplication>
#include <QTabWidget>
#include <QWidget>
#include <QVBoxLayout>
#include <QLabel>
#include <QPushButton>
#include <QIcon>

class MainWindow : public QWidget
{
public:
    MainWindow()
    {
        tabWidget = new QTabWidget;
        QWidget *tab1 = new QWidget;
        tabWidget->addTab(tab1, "タブ1");
        QWidget *tab2 = new QWidget;
        tabWidget->addTab(tab2, "タブ2");

        changeIconButton = new QPushButton("アイコンを変更");
        connect(changeIconButton, &QPushButton::clicked, this, &MainWindow::changeTabIcon);

        QVBoxLayout *mainLayout = new QVBoxLayout;
        mainLayout->addWidget(tabWidget);
        mainLayout->addWidget(changeIconButton);
        setLayout(mainLayout);
    }

private slots:
    void changeTabIcon()
    {
        // 最初のタブのアイコンを変更
        tabWidget->setTabIcon(0, QIcon(":/icons/new_icon.png"));
    }

private:
    QTabWidget *tabWidget;
    QPushButton *changeIconButton;
};

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    MainWindow window;
    window.show();
    return app.exec();
}

MainWindow クラスを作成し、QTabWidget と QPushButton を含めます。
ボタンの clicked シグナルを、スロット関数 changeTabIcon() に接続します。
changeTabIcon() スロットでは、tabWidget->setTabIcon(0, QIcon(":/icons/new_icon.png")); を呼び出すことで、インデックス 0 の最初のタブのアイコンを "new_icon.png" に変更します。

QTabWidget::setTabIcon() の代替プログラミング方法

QTabWidget のタブにアイコンを設定する方法は、setTabIcon() 以外にもいくつか存在します。それぞれの方法には特徴があり、状況によって使い分けることができます。

QTabWidget::addTab() のオーバーロードを使用する

前回の例でも触れましたが、QTabWidget::addTab() 関数には、ウィジェット、アイコン (QIcon)、ラベル (QString) を引数に取るオーバーロードがあります。タブを追加する際に、アイコンを同時に設定できるため、コードが簡潔になる場合があります。

#include <QApplication>
#include <QTabWidget>
#include <QWidget>
#include <QVBoxLayout>
#include <QLabel>
#include <QIcon>

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

    QTabWidget *tabWidget = new QTabWidget;

    QWidget *tab1 = new QWidget;
    tab1->setLayout(new QVBoxLayout);
    tabWidget->addTab(tab1, QIcon(":/icons/home.png"), "ホーム");

    QWidget *tab2 = new QWidget;
    tab2->setLayout(new QVBoxLayout);
    tabWidget->addTab(tab2, QIcon(":/icons/settings.png"), "設定");

    tabWidget->show();

    return app.exec();
}

利点

タブが追加されるタイミングでアイコンが設定されるため、初期設定としては自然な方法です。
タブの追加とアイコンの設定を1行で記述できるため、コードが読みやすく、簡潔になります。

欠点

既に存在するタブのアイコンを後から変更する場合には、やはり setTabIcon() を使用する必要があります。

カスタムタブウィジェットを作成する

より複雑な表現やインタラクションが必要な場合、QTabWidget のデフォルトのタブの外観をカスタマイズするために、独自のウィジェットをタブとして使用する方法があります。この場合、アイコンの表示はカスタムウィジェット内で自由に行うことができます。

#include <QApplication>
#include <QTabWidget>
#include <QWidget>
#include <QHBoxLayout>
#include <QLabel>
#include <QIcon>

class CustomTabWidget : public QWidget
{
public:
    CustomTabWidget(const QIcon &icon, const QString &text, QWidget *parent = nullptr)
        : QWidget(parent)
    {
        QHBoxLayout *layout = new QHBoxLayout(this);
        iconLabel = new QLabel();
        iconLabel->setPixmap(icon.pixmap(32, 32)); // アイコンをPixmapとして設定
        textLabel = new QLabel(text);
        layout->addWidget(iconLabel);
        layout->addWidget(textLabel);
        setLayout(layout);
    }

private:
    QLabel *iconLabel;
    QLabel *textLabel;
};

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

    QTabWidget *tabWidget = new QTabWidget;

    QWidget *content1 = new QWidget;
    tabWidget->addTab(content1, new CustomTabWidget(QIcon(":/icons/home.png"), "ホーム"));

    QWidget *content2 = new QWidget;
    tabWidget->addTab(content2, new CustomTabWidget(QIcon(":/icons/settings.png"), "設定"));

    tabWidget->show();

    return app.exec();
}

説明

CustomTabWidget という独自のウィジェットクラスを作成します。このウィジェットは、アイコンを表示するための QLabel とテキストを表示するための QLabel を水平方向に配置します。
CustomTabWidget のコンストラクタで、渡された QIcon を QLabel の Pixmap として設定します。
QTabWidget::addTab() の第二引数に、作成した CustomTabWidget のインスタンスを渡します。QTabWidget は、このウィジェットをタブとして表示します。

利点

アイコンだけでなく、他のウィジェット (例えば、閉じるボタンなど) をタブに含めることもできます。
タブの外観を完全にカスタマイズできます。アイコンのサイズ、配置、アニメーションなど、より自由な表現が可能です。

欠点

QTabWidget のデフォルトのタブの機能 (ドラッグアンドドロップでのタブの移動など) を再実装する必要がある場合があります。
実装がやや複雑になります。

スタイルシートを使用する (限定的)

スタイルシートを使ってタブのアイコンを設定することも可能ですが、これは主にタブのスタイルを装飾する目的で使用され、動的なアイコンの変更や複雑なアイコンの管理には向きません。

QTabBar::tab:first {
    icon: url(":/icons/home.png");
}

QTabBar::tab:last {
    icon: url(":/icons/settings.png");
}

説明

Qt スタイルシートでは、QTabBar::tab セレクタを使用して個々のタブのスタイルを設定できます。:first や :last などの疑似セレクタを使って、特定のインデックスのタブにアイコンを設定することもできます。

利点

コードを変更せずに外観を調整できます。
アプリケーション全体で一貫したスタイルを適用できます。

欠点

複雑な条件に基づいてアイコンを変更することはできません。
インデックスに依存するため、タブの順序が変わると意図しないタブにアイコンが適用される可能性があります。
動的にアイコンを変更することが難しいです。

QStyle をサブクラス化する (高度な方法)

Qt の描画処理をカスタマイズするための高度な方法として、QStyle クラスをサブクラス化し、タブのアイコンの描画方法を独自に実装する方法があります。これは非常に柔軟性が高い反面、複雑で高度な知識が必要です。

利点

描画処理を完全に制御できるため、非常に高度なカスタマイズが可能です。

Qt のバージョンが変わると、互換性の問題が発生する可能性があります。
実装が非常に複雑で、Qt の内部構造に関する深い理解が必要です。

QStyle のサブクラス化
最も高度な方法で、描画処理を完全に制御できますが、複雑性が高いです。
スタイルシート
静的なアイコン設定や、他のスタイルの装飾と組み合わせる場合に利用できますが、動的な変更には不向きです。
カスタムタブウィジェット
タブの外観を大幅にカスタマイズしたい場合に有効です。
addTab() のオーバーロード
タブの追加時にアイコンを同時に設定する場合に簡潔に記述できます。
setTabIcon()
最も一般的で、既存のタブのアイコンを動的に変更するのに適しています。

Qt開発者向け：QTabWidget の clear() をマスターする

QTabWidget::clear() は、QTabWidget ウィジェットに追加されているすべてのタブとその内容を削除するための関数（メソッド）です。具体的には、この関数を呼び出すと以下の処理が行われます。内部的に保持しているタブに関する情報がクリアされます。タブのインデックスやタイトルなどの情報がリセットされます。

QtのQTabWidgetでコーナーウィジェットを活用！基本から応用まで徹底解説

QTabWidgetは、複数のタブとそれぞれのタブに関連付けられたページ（ウィジェット）を管理するためのウィジェットです。通常、上部にタブが並び、その下に選択されたタブに対応するコンテンツが表示されます。QTabWidget::cornerWidget()は、タブバーの特定の隅（通常は右上）に表示されるウィジェットを取得するために使用されます。この関数は、setCornerWidget()と組み合わせて使用され、タブバーの隅に任意のウィジェット（例えば、追加のボタンや検索フィールドなど）を配置することができます。