PyQt/C++ Qt QTabWidgetの使い方：タブ追加、切り替え、カスタマイズ徹底解説

2025-05-27

QTabWidget (クラス)

QTabWidget は、Qtフレームワークにおいて、タブ付きのインターフェースを作成するためのウィジェット（部品）です。ウェブブラウザのタブや、設定画面のカテゴリ分けのように、複数のページやコンテンツを切り替えて表示する際に非常に便利です。

主な役割と機能

信号とスロット
QTabWidget は、タブが切り替えられたときなどに信号（シグナル）を発行します。これらの信号を他のオブジェクトのスロット（メソッド）に接続することで、タブの切り替えに応じて特定の処理を実行することができます。例えば、タブが切り替わったときに特定のデータを読み込む、表示を更新するなどの処理を実装できます。
タブのカスタマイズ
各タブのテキストラベルやアイコンを設定できます。また、タブの表示位置や挙動（例えば、ドラッグ＆ドロップによるタブの移動）などをカスタマイズすることも可能です。
タブの追加と削除
プログラムの実行中に、新しいタブ（とそれに対応するウィジェット）を動的に追加したり、既存のタブを削除したりすることができます。
タブによる切り替え
各子ウィジェットは、QTabWidget の上部（または下部、左側、右側にも設定可能）に表示されるタブと関連付けられます。ユーザーがタブをクリックすることで、対応する子ウィジェットが前面に表示され、他のウィジェットは隠れます。
複数の子ウィジェットの管理
QTabWidget は、複数の異なるウィジェット（例えば、QWidget、QLabel、QLineEdit など）を子として持つことができます。

QTabWidget オブジェクトの作成
まず、QTabWidget クラスのインスタンスを作成します。

from PyQt5.QtWidgets import QTabWidget, QWidget, QVBoxLayout, QLabel, QApplication
import sys

app = QApplication(sys.argv)
tab_widget = QTabWidget()

子ウィジェットの作成
タブに表示したい内容を持つウィジェット（例えば、QWidget）を作成します。
```
tab1 = QWidget()
tab2 = QWidget()
```

レイアウトの設定（必要に応じて）
子ウィジェット内にさらに他のウィジェットを配置したい場合は、レイアウトマネージャー（例えば、QVBoxLayout）を使用します。

layout1 = QVBoxLayout(tab1)
label1 = QLabel("最初のタブの内容")
layout1.addWidget(label1)
tab1.setLayout(layout1)

layout2 = QVBoxLayout(tab2)
label2 = QLabel("二番目のタブの内容")
layout2.addWidget(label2)
tab2.setLayout(layout2)

タブの追加
addTab() メソッドを使用して、子ウィジェットとタブのラベルを QTabWidget に追加します。
```
tab_widget.addTab(tab1, "タブ 1")
tab_widget.addTab(tab2, "タブ 2")
```
QTabWidget の表示
作成した QTabWidget を表示します。
```
tab_widget.show()
sys.exit(app.exec_())
```

QTabWidget (クラス) における一般的なエラーとトラブルシューティング

タブが追加されない / 表示されない

トラブルシューティング
- addTab() の呼び出し方を確認し、渡しているオブジェクトとラベルが正しいか確認する。
- 追加したウィジェットに setLayout() で適切なレイアウトを設定しているか確認する。レイアウトがない場合、子ウィジェットは表示されないことがあります。
- QTabWidget を親ウィジェットのレイアウトに追加しているか確認する。例えば、メインウィンドウに QTabWidget を設定する場合は、メインウィンドウのセントラルウィジェットにレイアウトを設定し、そこに QTabWidget を追加する必要があります。
- 追加したウィジェットの isVisible() メソッドを呼び出し、True であることを確認する。もし False であれば、show() メソッドで表示させる。
原因
- addTab() メソッドの引数が間違っている（ウィジェットオブジェクトとタブのラベルが正しく渡されていない）。
- 追加したウィジェットにレイアウトが設定されておらず、サイズがゼロになっている。
- QTabWidget 自体がレイアウトマネージャーに適切に追加されていない、または親ウィジェットが正しく設定されていない。
- 追加したウィジェットが hide() されているなど、非表示状態になっている。

タブのラベルが正しく表示されない

トラブルシューティング
- addTab() に渡しているラベルの文字列を確認する。
- QTabWidget やその親ウィジェットに適用されているスタイルシートを確認し、テキストの色や背景色などが適切に設定されているか確認する。
原因
- addTab() に渡したラベルの文字列が空であるか、意図しない文字列になっている。
- フォントやスタイルシートの設定によって、ラベルが見えにくくなっている。

タブを切り替えてもコンテンツが更新されない

トラブルシューティング
- QTabWidget の currentChanged(int index) シグナルを、タブが切り替えられた際に実行したい処理を行うスロットに接続しているか確認する。
- 接続先のスロットのロジックが正しいかデバッグする。引数として渡されるインデックスを使用して、現在選択されているタブを特定し、対応する処理を行っているか確認する。
原因
- タブが切り替えられた際の処理（例えば、データの読み込みや表示の更新）が実装されていない。
- currentChanged() シグナルが適切なスロットに接続されていない、または接続先のスロットの処理が間違っている。

タブの順序が意図しないものになる

トラブルシューティング
- addTab() の呼び出し順序を見直す。
- タブの移動を禁止したい場合は、setMovable(False) メソッドを QTabWidget オブジェクトに対して呼び出す。
原因
- addTab() を呼び出す順序が、意図したタブの表示順序と異なる。
- タブの移動を許可する設定になっている場合に、ユーザーがドラッグ＆ドロップでタブの順序を変更した。

特定のタブでイベントが正しく処理されない

トラブルシューティング
- イベントの伝播（イベントが親ウィジェットに伝わるかどうか）を確認する。必要に応じて、イベントフィルタを使用することを検討する。
- タブ内の子ウィジェットで必要なイベントハンドラが正しく実装されているか確認する。
原因
- タブ内の子ウィジェットがイベントを横取りしている。
- タブに関連付けられたウィジェットで、必要なイベントハンドラ（例えば、マウスイベント、キーイベント）が実装されていない。

パフォーマンスの問題 (タブが多い場合)

トラブルシューティング
- 必要に応じて、タブのコンテンツを遅延ロードすることを検討する。つまり、タブが実際に選択されたときにのみ、そのコンテンツを生成またはロードする。
- タブの切り替え時の処理を最適化する。不要な処理を避け、効率的なアルゴリズムを使用する。
原因
- 多数のタブと複雑なコンテンツを持つウィジェットを同時に作成・管理しようとしている。
- タブが切り替えられるたびに、重い処理を実行している。

Qtのドキュメントを参照
Qtの公式ドキュメントは、各クラスやメソッドの詳細な情報を提供しています。
シンプルな例でテスト
問題が発生している箇所を切り出し、最小限のコードで再現できるかどうか試す。
デバッグ出力の活用
qDebug() などのQtのデバッグ出力機能を使用して、ウィジェットの階層構造、プロパティの値、シグナルとスロットの接続などを確認する。

基本的な例：2つのタブを持つシンプルな QTabWidget

この例では、2つのタブを持つ QTabWidget を作成し、それぞれのタブに簡単なラベルを表示します。

from PyQt5.QtWidgets import QApplication, QWidget, QTabWidget, QVBoxLayout, QLabel
import sys

app = QApplication(sys.argv)

# メインウィンドウの作成
mainWindow = QWidget()
mainWindow.setWindowTitle("QTabWidgetの例")
layout = QVBoxLayout(mainWindow)

# QTabWidget の作成
tabWidget = QTabWidget()

# 最初のタブとその内容
tab1 = QWidget()
layout1 = QVBoxLayout(tab1)
label1 = QLabel("これは最初のタブの内容です。")
layout1.addWidget(label1)
tab1.setLayout(layout1)
tabWidget.addTab(tab1, "タブ 1")

# 二番目のタブとその内容
tab2 = QWidget()
layout2 = QVBoxLayout(tab2)
label2 = QLabel("こちらは二番目のタブの内容です。")
layout2.addWidget(label2)
tab2.setLayout(layout2)
tabWidget.addTab(tab2, "タブ 2")

# QTabWidget をメインウィンドウのレイアウトに追加
layout.addWidget(tabWidget)
mainWindow.setLayout(layout)

# メインウィンドウを表示
mainWindow.show()

sys.exit(app.exec_())

解説

QApplication のインスタンスを作成し、Qtアプリケーションを初期化します。
メインとなる QWidget (mainWindow) を作成し、タイトルを設定します。
メインウィンドウのレイアウトとして QVBoxLayout を作成します。
QTabWidget のインスタンス (tabWidget) を作成します。
最初のタブ (tab1) 用の QWidget を作成し、そのレイアウト (layout1) とラベル (label1) を設定します。addTab() メソッドを使って、tab1 とタブのラベル "タブ 1" を tabWidget に追加します。
同様に、二番目のタブ (tab2) とその内容を作成し、addTab() で "タブ 2" というラベルとともに tabWidget に追加します。
作成した tabWidget をメインウィンドウのレイアウトに追加します。
メインウィンドウを表示し、Qtアプリケーションのイベントループを開始します。

タブの切り替えに応じた処理：currentChanged シグナル

この例では、タブが切り替えられたときに、どのタブが選択されたかをコンソールに出力します。

from PyQt5.QtWidgets import QApplication, QWidget, QTabWidget, QVBoxLayout, QLabel
from PyQt5.QtCore import pyqtSlot
import sys

class MainWindow(QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("currentChangedシグナルの例")
        layout = QVBoxLayout(self)

        self.tabWidget = QTabWidget()

        tab1 = QWidget()
        layout1 = QVBoxLayout(tab1)
        label1 = QLabel("最初のタブ")
        layout1.addWidget(label1)
        tab1.setLayout(layout1)
        self.tabWidget.addTab(tab1, "タブ 1")

        tab2 = QWidget()
        layout2 = QVBoxLayout(tab2)
        label2 = QLabel("二番目のタブ")
        layout2.addWidget(label2)
        tab2.setLayout(layout2)
        self.tabWidget.addTab(tab2, "タブ 2")

        layout.addWidget(self.tabWidget)
        self.setLayout(layout)

        # currentChanged シグナルをスロットに接続
        self.tabWidget.currentChanged.connect(self.tabChanged)

    @pyqtSlot(int)
    def tabChanged(self, index):
        print(f"現在のタブのインデックス: {index}")
        if index == 0:
            print("最初のタブが選択されました。")
        elif index == 1:
            print("二番目のタブが選択されました。")

app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec_())

解説

MainWindow クラスを作成し、その中で QTabWidget を作成します。
self.tabWidget.currentChanged.connect(self.tabChanged) の行で、QTabWidget の currentChanged シグナルを self.tabChanged スロットに接続しています。currentChanged シグナルは、タブが切り替えられるたびに発行され、引数として選択されたタブのインデックス（0から始まる）が渡されます。
tabChanged スロットでは、受け取ったインデックスを表示し、どのタブが選択されたかに応じてメッセージを出力しています。@pyqtSlot(int) は、このメソッドが整数の引数を受け取るスロットであることを明示的に示しています。

タブの追加と削除（動的）：

この例では、ボタンを使って新しいタブを動的に追加したり、現在のタブを削除したりします。

from PyQt5.QtWidgets import QApplication, QWidget, QTabWidget, QVBoxLayout, QPushButton, QLabel, QLineEdit
from PyQt5.QtCore import pyqtSlot
import sys

class MainWindow(QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("タブの動的追加と削除の例")
        layout = QVBoxLayout(self)

        self.tabWidget = QTabWidget()
        layout.addWidget(self.tabWidget)

        # コントロール用のウィジェット
        controlWidget = QWidget()
        controlLayout = QVBoxLayout(controlWidget)

        self.addTabLineEdit = QLineEdit("新しいタブのラベル")
        controlLayout.addWidget(self.addTabLineEdit)

        addButton = QPushButton("タブを追加")
        addButton.clicked.connect(self.add_new_tab)
        controlLayout.addWidget(addButton)

        removeButton = QPushButton("現在のタブを削除")
        removeButton.clicked.connect(self.remove_current_tab)
        controlLayout.addWidget(removeButton)

        layout.addWidget(controlWidget)
        self.setLayout(layout)

    @pyqtSlot()
    def add_new_tab(self):
        new_tab = QWidget()
        new_layout = QVBoxLayout(new_tab)
        label = QLabel(f"これは新しいタブ '{self.addTabLineEdit.text()}' の内容です。")
        new_layout.addWidget(label)
        new_tab.setLayout(new_layout)
        self.tabWidget.addTab(new_tab, self.addTabLineEdit.text())

    @pyqtSlot()
    def remove_current_tab(self):
        currentIndex = self.tabWidget.currentIndex()
        if currentIndex != -1:
            self.tabWidget.removeTab(currentIndex)

app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec_())

QLineEdit を使って新しいタブのラベルを入力できるようにします。
"タブを追加" ボタンがクリックされると add_new_tab スロットが呼び出されます。このスロットでは、新しい QWidget を作成し、ラベルを設定した後、self.tabWidget.addTab() を使って QTabWidget に追加します。タブのラベルは QLineEdit のテキストを使用します。
"現在のタブを削除" ボタンがクリックされると remove_current_tab スロットが呼び出されます。このスロットでは、self.tabWidget.currentIndex() で現在選択されているタブのインデックスを取得し、self.tabWidget.removeTab() を使ってそのタブを削除します。

QStackedWidget と独自のタブ UI の組み合わせ

QStackedWidget は、複数の子ウィジェットを重ねて表示し、一度に一つのウィジェットだけを表示するためのクラスです。これと、独自のタブ UI（例えば、QPushButton のグループや、カスタムウィジェット）を組み合わせることで、QTabWidget と同様のタブ切り替え機能を実現できます。

利点

QTabWidget の制約を受けない
QTabWidget が持つ特定のレイアウトや挙動に縛られません。
高いカスタマイズ性
タブの外観や動作を完全に自由に設計できます。例えば、タブを垂直方向に配置したり、アイコンだけでなく画像を表示したり、複雑なアニメーションを伴うタブ切り替えを実装したりできます。

欠点

アクセシビリティへの配慮
QTabWidget はキーボード操作やスクリーンリーダーとの連携が比較的容易ですが、カスタム UI ではこれらの配慮を自分で行う必要があります。
実装の手間
タブの作成、選択状態の管理、QStackedWidget の切り替え処理などを自分で実装する必要があります。

基本的な実装の考え方

複数のコンテンツ表示用のウィジェットを作成します。
これらのウィジェットを QStackedWidget に追加します。
タブとして機能するウィジェット（例：ボタンのリスト）を作成します。
各タブウィジェットがクリックされたときに、対応するインデックスのウィジェットを QStackedWidget に表示するように、シグナルとスロットを接続します。
タブの選択状態を視覚的に表現するための処理（例：選択されたボタンのスタイルを変更）を実装します。

QToolBox クラス

QToolBox は、複数のパネルを垂直方向に積み重ねて表示し、一度に一つのパネルだけを展開して表示するウィジェットです。タブのような水平方向の切り替えではありませんが、カテゴリ分けされたコンテンツを切り替えて表示するという点で、QTabWidget の代替となる場合があります。

利点

比較的シンプルなAPI
QTabWidget と同様に、addItem() メソッドなどでコンテンツを追加できます。
垂直方向のカテゴリ表示
多くの設定画面やツールバーなどで見られる、垂直方向のカテゴリ表示を容易に実現できます。

欠点

カスタマイズの自由度
QTabWidget ほど、タブ部分の見た目を細かくカスタマイズすることはできません。
水平方向のタブではない
水平方向のタブによる切り替えが必要な場合には適していません。

QDockWidget の組み合わせ

複数の QDockWidget を使用し、それぞれに異なるコンテンツを表示することで、タブのような切り替えに近いインターフェースを実現できます。ユーザーはドックウィジェットをドラッグ＆ドロップで移動したり、タブ化したりすることができます。

利点

複雑なアプリケーションに適している
複数の独立した機能を持つビューを統合するのに適しています。
柔軟なレイアウト
ユーザーが自由にウィンドウの配置を変更できます。タブ化をサポートしているため、必要に応じてタブのような表示も可能です。

欠点

実装の複雑さ
ドッキング機能の制御や初期レイアウトの設定など、QTabWidget より複雑になる場合があります。
基本的なタブコントロールとは異なる挙動
デフォルトではドッキング可能なウィンドウとして扱われるため、QTabWidget のような固定されたタブインターフェースとは異なります。

カスタムウィジェットによる完全な独自実装

QWidget を継承して完全に独自のタブコントロールを実装することも可能です。これは最も自由度が高い方法ですが、描画、イベント処理、子ウィジェットの管理など、多くの処理を自分で実装する必要があります。

利点

究極のカスタマイズ性
ピクセル単位での描画や、完全に独自のロジックを実装できます。

欠点

アクセシビリティへの配慮
スクリーンリーダーなどとの連携を自分で実装する必要があります。
保守が難しい
独自のロジックは標準的なQtの挙動と異なる場合があり、保守が難しくなる可能性があります。
開発コストが高い
実装に多くの時間と労力がかかります。

非常に特殊な要件があり、標準のウィジェットでは対応できない場合
カスタムウィジェットによる独自実装を検討する必要がありますが、開発コストと保守性を慎重に考慮する必要があります。
ユーザーが自由にレイアウトを調整できる柔軟なインターフェースが必要な場合
QDockWidget の組み合わせが良いでしょう。
垂直方向のカテゴリ表示が必要な場合
QToolBox を検討してください。
タブの外観や動作を高度にカスタマイズしたい場合
QStackedWidget と独自のタブ UI の組み合わせが適しています。
シンプルで標準的なタブインターフェースが必要な場合
QTabWidget が最も簡単で効率的な選択肢です。

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

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

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

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