QComboBox は GUI アプリで選択肢をコンパクトに表示する定番ウィジェットです。
ドロップダウンリストとして複数の選択肢を切り替えられるため、フォーム入力やオプション設定で大活躍します。

この記事では QComboBox の基本から、よく使うプロパティ・メソッド、便利な実用例まで丁寧に解説します。

「PySideで選択肢リストを使いこなしたい」「QComboBox の設定や操作方法が知りたい」方はぜひ最後までご覧ください。

QComboBoxとは？

QComboBox は、複数の選択肢をコンパクトに表示し、ユーザーがその中から1つを選ぶためのドロップダウン型ウィジェットです。

フォーム入力やオプション設定、選択リストなど幅広い場面で使われ、必要に応じて新しい選択肢の入力や補完機能も持たせることができます。

基本コード

QComboBox の基本的な使い方は以下のとおりです。

from PySide6.QtWidgets import QApplication, QWidget, QVBoxLayout, QComboBox
import sys

app = QApplication(sys.argv)
window = QWidget()
layout = QVBoxLayout()

combo = QComboBox()
combo.addItems(["選択肢1", "選択肢2", "選択肢3"])

# ========================================
# ここにコードを追加します
# ========================================

layout.addWidget(combo)

window.setLayout(layout)
window.show()
app.exec()

主なプロパティとメソッド一覧（全解説）

各プロパティ・メソッド 詳細解説

【1】現在の選択インデックスを設定・取得

• 概要： 特定のインデックスの選択肢を選んだり，選ばれている選択肢のインデックス番号を返します。
• メソッド：setCurrentIndex(int)
/currentIndex()

• 使い方：

combo.setCurrentIndex(1)
index = combo.currentIndex()

print(f"現在の選択インデックス: {index}")
# 現在の選択インデックス: 1

【2】現在の選択テキストを設定・取得

• 概要： 現在選ばれているテキストを設定・取得します。
• メソッド：setCurrentText(str)/currentText()

• 使い方：

combo.setCurrentText("選択肢3")
text = combo.currentText()

print(f"現在の選択テキスト: {text}")
# 現在の選択テキスト: 選択肢3

【3】 単一の選択肢を追加

• 概要： 一つの選択肢をリストに追加します。
• メソッドaddItem(str, userData=None)

• 使い方：

combo.addItem("新しい選択肢")

【4】 複数の選択肢を一括追加

• 概要： リスト形式で複数の選択肢を追加します。
• メソッド：addItems(list)

• 使い方：

combo.addItems(["A", "B", "C"])

【5】 指定位置に選択肢を挿入

• 概要： 任意のインデックス位置に選択肢を挿入します。
• メソッド：insertItem(int, str, userData=None)

• 使い方：

combo.insertItem(1, "挿入された選択肢")

【6】 選択肢を削除

• 概要： 指定のインデックスの選択肢を削除します。
• メソッド：removeItem(int)

• 使い方：

combo.removeItem(0)

【7】 全選択肢を削除

• 概要： コンボボックス内の選択肢を全て削除します。
• メソッド：clear()

• 使い方：

combo.clear()

【8】 選択肢の数を取得

• 概要： 現在の選択肢の数を返します。
• メソッド：count()

• 使い方：

numbers = combo.count()

print(f"選択肢の数: {numbers}")
# 3

【9】コンボボックスを編集可能に設定・取得

• 概要：コンボボックスを編集可能に設定します。編集可能にすると、ユーザーが新しい値を入力できます。isEditable はその状態を確認します。
• メソッド：setEditable(bool)/isEditable()
• 使い方：

combo.setEditable(True)
print(f"編集可能か？: {combo.isEditable()}")
# 編集可能か？: True

編集前	編集後

【10】 選択肢の最大数を設定

• 概要：ドロップダウンリストで一度に表示される選択肢の最大数を設定します。
• メソッド：setMaxVisibleItems(int)
• 使い方：

# アイテムの追加
combo.addItems(["A", "B", "C"])
# 表示されるアイテム数の最大値を設定
combo.setMaxVisibleItems(5)

【11】 挿入動作を制御

• 概要：編集可能モードで新しい値が入力された際の挿入動作を制御します。
• メソッド：setInsertPolicy(QComboBox.InsertPolicy)
• 使い方：

from PySide6.QtWidgets import QComboBox
combo.setEditable(True)
combo.setInsertPolicy(QComboBox.InsertAtTop)

【12】ユーザー入力時に候補を提示

• 概要：補完機能を追加します。ユーザー入力時に候補を提示できます。
• メソッド：setCompleter(QCompleter オブジェクト)
• 使い方：

from PySide6.QtWidgets import QCompleter
combo.setEditable(True)
completer = QCompleter(["候補1", "候補2", "候補3"])
combo.setCompleter(completer)

【13】 選択肢を選んだときのシグナル

• 概要：ユーザーが選択肢を選んだときに発生するシグナルです。
• メソッド：activated.connect(スロット関数)
• 使い方：

combo.activated.connect(lambda i: print(f"選ばれたインデックス: {i}"))

# 選ばれたインデックス: 0
# 選ばれたインデックス: 2

【14】 選択インデックスが変更されたときのシグナル

• 概要：選択インデックスが変更されたときに発生するシグナルです。
• メソッド：currentIndexChanged.connect(スロット関数)
• 使い方：

combo.currentIndexChanged.connect(lambda i: print(f"新しいインデックス: {i}"))

# 新しいインデックス: 1

【15】アイテムに追加データの付与・取得

• 概要：アイテムに追加データを持たせたり取得したりします。
• メソッド：setItemData / itemData
• 使い方：

combo.addItem("選択肢1", userData=123)
data = combo.itemData(0)

print(f"選択肢0のデータ: {data}")
# 追加されたデータ: 123

【16】特定の選択肢のテキストを設定・取得

• 概要：特定の選択肢のテキストを設定・取得します。
• メソッド：setItemText / itemText
• 使い方：

combo.setItemText(0, "新しいテキスト")

print(combo.itemText(0))
# 新しいテキスト

よくある質問（FAQ）

編集可能モードで入力値の検証はできますか？

QValidator を組み合わせることで可能です。

アイテムの並び替えはできますか？

手動で削除・挿入を組み合わせて並び替えます。

編集可能コンボボックスで入力値を制限できますか？

setCompleter と組み合わせる、または入力チェックロジックをシグナルで追加する方法があります。

プレースホルダーが表示されないのはなぜですか？

setEditable(True) にしないとプレースホルダーは有効になりません。

ユーザーが新しい選択肢を入力したとき、どうやってデータに反映すればよい？

currentTextChanged シグナルで取得可能です。

コンボボックスの選択肢にアイコンを付けたい

addItem(QIcon, str) を使います。

QComboBoxの選択状態を保存・復元するには？

currentIndex や currentText を記録し、起動時に setCurrentIndex 等で復元します。

まとめ

QComboBox は、選択肢リストをスマートに管理できる強力なウィジェットです。ドロップダウン型で省スペースかつ使いやすく、フォームや設定画面など幅広い場面で活躍します。基本の使い方に加えて、編集可能モード、補完機能、挿入ポリシーの設定などを組み合わせれば、より柔軟で実用的なインターフェースが作れます。

この記事で紹介したプロパティやメソッドを一通り試し、どの機能がどんな場面に適しているかをぜひ実際に確認してみてください。選択肢の動的操作やシグナルの活用など、QComboBox の奥深い機能を使いこなすことで、あなたのアプリの操作性は一段と向上するはずです。

次回は、「QSlider と QProgressBar」 を取り上げ、値の調整や進捗表示のUIについて詳しく解説します。QComboBox と組み合わせることで、さらにリッチなGUIを構築できるようになりますので、ぜひ続けてご覧ください！