【C++】Qt QListWidgetの使い方|基本操作とイベント連携でリスト管理を実現
c++ qt qlistwidgetを使うと、リスト形式の項目管理が手軽に実現できます。
ウィジェットを生成しレイアウトに配置した後、addItem
で項目を追加し、setCurrentRow
で選択状態を操作できます。
また、takeItem
で必要なくなった項目を削除し、シグナルとスロットの接続でダブルクリックなどのイベントにも対応可能です。
QListWidgetの基本機能
特徴と用途
QListWidgetの役割
QListWidgetは、数多くの項目をリスト形式で表示し、ユーザーの選択や操作を簡単に実現できるウィジェットです。
シンプルなリスト表示だけでなく、アイテムごとにアイコンや背景色、文字色を設定することが可能なため、直感的なUI構築が可能になります。
他ウィジェットとの比較
QListWidgetは、データの階層構造が必要な場合に用いるQTreeWidgetや、より柔軟なモデルを利用したQListViewと比べると、設定がシンプルで手軽に使える点が魅力的です。
シンプルなリスト表示専用であり、用途に合わせて適切なウィジェットを選択することで、効率的なUI設計ができます。
ウィジェットの生成と配置
インスタンス生成の基本操作
ウィジェットの作成方法
まずは、QListWidgetのインスタンスを作成する手順です。
下記のサンプルコードでは、ウィンドウ内にリストウィジェットを生成し、ウィンドウオブジェクトとレイアウトに組み込む方法を示しています。
#include <QApplication>
#include <QListWidget>
#include <QVBoxLayout>
#include <QWidget>
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
// ウィンドウ作成
QWidget *window = new QWidget;
window->setWindowTitle("QListWidgetサンプル");
// レイアウトの設定
QVBoxLayout *layout = new QVBoxLayout(window);
// QListWidgetの生成
QListWidget *listWidget = new QListWidget;
// ウィジェットをレイアウトに追加
layout->addWidget(listWidget);
// ウィンドウにレイアウトを適用して表示
window->setLayout(layout);
window->resize(400, 300);
window->show();
return app.exec();
}
// サンプル実行結果
// サイズ400x300のウィンドウが表示され、画面内に空のリストエリアが現れます。

レイアウトへの追加手順
生成したQListWidgetは、QVBoxLayoutやQHBoxLayoutなどの標準レイアウトに簡単に追加できるため、他のウィジェットとの組み合わせもしやすくなっています。
レイアウトに追加するだけで、ウィンドウ全体のデザインに違和感なく溶け込む点が魅力です。
ウィンドウへの統合
コンポーネントとしての組み込み
QListWidgetは、他のウィジェットと同様にウィンドウの一部として統合できるため、ボタンやテキストフィールドと組み合わせた複雑なUIを手軽に実現できます。
コンポーネント間のレイアウト調整も柔軟に行え、ユーザーにとって使いやすいインターフェースを構築できます。
項目の管理操作
アイテムの追加方法
addItemの利用
簡単にアイテムを追加できるaddItem
メソッドを活用すると、ユーザーに表示するリストを動的に拡充することが可能です。
例えば、下記のコードは簡単な文字列のアイテムを順次追加する方法を示しています。
#include <QApplication>
#include <QListWidget>
#include <QVBoxLayout>
#include <QWidget>
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
QWidget *window = new QWidget;
window->setWindowTitle("addItemサンプル");
QVBoxLayout *layout = new QVBoxLayout(window);
QListWidget *listWidget = new QListWidget;
layout->addWidget(listWidget);
// addItemでリストにアイテム追加
listWidget->addItem("アイテム1");
listWidget->addItem("アイテム2");
listWidget->addItem("アイテム3");
window->setLayout(layout);
window->resize(400, 300);
window->show();
return app.exec();
}
// サンプル実行結果
// ウィンドウ内に「アイテム1」「アイテム2」「アイテム3」の各項目が表示されます。

QListWidgetItemによるカスタマイズ
QListWidgetItem
を使用すると、アイコンや文字色、背景色など各アイテムの詳細なプロパティをカスタマイズできるため、視覚的な区別を行いたい場合に役立ちます。
以下は、アイコンと色設定の例です。
#include <QApplication>
#include <QListWidget>
#include <QVBoxLayout>
#include <QWidget>
#include <QListWidgetItem>
#include <QIcon>
#include <QBrush>
#include <QColor>
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
QWidget *window = new QWidget;
window->setWindowTitle("カスタマイズアイテムサンプル");
QVBoxLayout *layout = new QVBoxLayout(window);
QListWidget *listWidget = new QListWidget;
layout->addWidget(listWidget);
// QListWidgetItemでカスタマイズしたアイテムを作成
QListWidgetItem *customItem = new QListWidgetItem;
customItem->setText("カスタムアイテム");
customItem->setIcon(QIcon(":/icons/sample.png")); // 画像パスは環境に合わせて設定
customItem->setForeground(QBrush(QColor(255, 0, 0))); // 文字色を赤に設定
customItem->setBackground(QBrush(QColor(220, 220, 220))); // 背景色を薄いグレーに設定
listWidget->addItem(customItem);
window->setLayout(layout);
window->resize(400, 300);
window->show();
return app.exec();
}
// サンプル実行結果
// ウィンドウ内に、赤い文字と薄いグレーの背景を持つ「カスタムアイテム」が表示されます。
// アイコンは指定した画像パスに存在する画像が表示されます。

アイテムの編集操作
テキストの変更
既存のアイテムのテキストは、setText
メソッドを利用して容易に変更できます。
たとえば、ユーザーの操作に応じてリスト内のテキストを更新することが可能です。
アイコンの設定
アイテムに対してアイコンを設定するには、setIcon
メソッドを使います。
アイコンを指定することで、項目ごとに視覚的な印象を変えることができます。
文字色・背景色の変更
個々のアイテムの前景色や背景色は、setForeground
とsetBackground
メソッドにより自由に変更できます。
これにより、特定の条件下でアイテムの色を変更し、ユーザーに重要な情報を直感的に伝えることが可能です。
アイテムの削除と取得
選択項目の削除処理
リストから項目を削除したい場合、まずtakeItem
で対象のアイテムを取り出し、その後delete
することでメモリ管理にも対応できます。
以下のサンプルコードは、現在選択されているアイテムを削除する例です。
#include <QApplication>
#include <QListWidget>
#include <QVBoxLayout>
#include <QWidget>
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
QWidget *window = new QWidget;
window->setWindowTitle("アイテム削除サンプル");
QVBoxLayout *layout = new QVBoxLayout(window);
QListWidget *listWidget = new QListWidget;
listWidget->addItem("削除対象アイテム1");
listWidget->addItem("削除対象アイテム2");
listWidget->addItem("削除対象アイテム3");
layout->addWidget(listWidget);
// 現在選択中のアイテムを取得して削除
listWidget->setCurrentRow(1); // 例として2番目のアイテムを選択
QListWidgetItem *item = listWidget->takeItem(listWidget->currentRow());
delete item; // メモリを解放
window->setLayout(layout);
window->resize(400, 300);
window->show();
return app.exec();
}
// サンプル実行結果
// 起動時に「削除対象アイテム1」「削除対象アイテム3」の2項目のみが表示されます。

アイテムオブジェクトの取得方法
リスト内の特定のアイテムオブジェクトは、item
メソッドなどを利用することで取得できます。
取得したアイテムは、テキスト変更や色設定など、後から柔軟にカスタマイズ可能です。
選択状態の管理
選択項目の設定方法
setCurrentRowとsetCurrentItemの活用
任意の行またはアイテムを選択状態にする場合、setCurrentRow
やsetCurrentItem
を使用することで、プログラム内から簡単に指定できます。
これにより、ユーザーに対して初期状態で何らかの選択を提示することが可能です。
選択項目の取得方法
現在選択中の行の検出
ユーザーが選択したアイテムの行番号は、currentRow
メソッドで取得できます。
取得した行番号を元に処理を分岐させるなど、ユーザーインターフェースの改善に役立ちます。
イベントの連携
シグナルの種類と役割
クリックおよびダブルクリックイベント
QListWidgetは、クリックやダブルクリックなどの基本イベントに対してシグナルを発生させます。
ユーザーがアイテムを操作したときの反応を柔軟に組み込むことができ、例えばダブルクリック時に詳細な情報を表示するなどの動作を実現できます。
その他のイベント種類
さらに、アイテムの追加や削除、フォーカスの変化などに対するシグナルも用意されており、細かい内部状態の変化を捉えた連動処理が可能になります。
スロットとの接続手法
ラムダ式による接続
ラムダ式を用いた接続は、コードを簡潔に記述できるためおすすめです。
下記のサンプルコードは、ダブルクリック時のイベントをラムダ式で処理する例です。
#include <QApplication>
#include <QListWidget>
#include <QVBoxLayout>
#include <QWidget>
#include <QDebug>
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
QWidget *window = new QWidget;
window->setWindowTitle("ラムダ式接続サンプル");
QVBoxLayout *layout = new QVBoxLayout(window);
QListWidget *listWidget = new QListWidget;
listWidget->addItem("ラムダ式で処理するアイテム");
layout->addWidget(listWidget);
// ダブルクリックイベントにラムダ式で接続
QObject::connect(listWidget, &QListWidget::itemDoubleClicked,
[=](QListWidgetItem *item) {
qDebug() << item->text() << "がダブルクリックされました";
});
window->setLayout(layout);
window->resize(400, 300);
window->show();
return app.exec();
}
// サンプル実行結果(ターミナル出力)
// "ラムダ式で処理するアイテム がダブルクリックされました" と表示されます。

メンバ関数による接続
クラス内のメンバ関数をスロットとして使用する方法もあります。
下記のサンプルコードは、Widgetクラス内でメンバ関数を定義し、シグナルと接続する方法を示します。
#include <QApplication>
#include <QListWidget>
#include <QVBoxLayout>
#include <QWidget>
#include <QDebug>
class Widget : public QWidget
{
public:
Widget(QWidget *parent = nullptr) : QWidget(parent)
{
QVBoxLayout *layout = new QVBoxLayout(this);
listWidget = new QListWidget;
listWidget->addItem("メンバ関数で処理するアイテム");
layout->addWidget(listWidget);
setLayout(layout);
// アイテムダブルクリック時にメンバ関数onItemDoubleClickedを呼び出す
connect(listWidget, &QListWidget::itemDoubleClicked,
this, &Widget::onItemDoubleClicked);
}
public slots:
void onItemDoubleClicked(QListWidgetItem *item)
{
qDebug() << item->text() << "がダブルクリックされました";
}
private:
QListWidget *listWidget;
};
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
Widget widget;
widget.setWindowTitle("メンバ関数接続サンプル");
widget.resize(400, 300);
widget.show();
return app.exec();
}
// サンプル実行結果(ターミナル出力)
// "メンバ関数で処理するアイテム がダブルクリックされました" と表示されます。

プロパティの設定とカスタマイズ
表示プロパティの調整
ドロップ操作およびソート設定
QListWidgetは、ドラッグ&ドロップ操作が可能な設定や自動ソート機能を備えています。
設定プロパティを変更することで、ユーザーが項目を並べ替えたり、直接リストにアイテムをドロップしたりすることができます。
例えば、以下のような点に注意するとよいです。
- ドロップ操作の有効化:
setDragDropMode(QAbstractItemView::InternalMove)
- 自動ソートの設定:
setSortingEnabled(true)
前景・背景プロパティの変更
各アイテムの前景色および背景色は、アイテムの視認性やアクセントを調整するために自由に変更可能です。
ユーザーの視線の誘導や、重要な情報の区別に役立ちます。
カスタム設定のオプション
表示オプションの詳細調整
QListWidgetは、選択時のハイライト色やアイテム間のスペースなど、表示に関するさまざまなオプションを細かく設定できます。
各プロパティを調整することで、オリジナルのテーマに合わせたリスト表示が実現できます。
- アイテム間の間隔調整
- ハイライト色の変更
- 選択モードのカスタマイズ(シングル、複数選択など)
インタラクションと操作性の向上
マウス操作の工夫
複数選択の実現
ユーザーが効率的に複数の項目を同時に選択できるように、選択モードを変更する設定が用意されています。
例えば、下記のように設定することで、複数選択が可能なリストに変更できます。
listWidget->setSelectionMode(QAbstractItemView::MultiSelection);
この設定により、ShiftキーやCtrlキーを使用して複数の項目を同時に選択することが可能になります。
キーボード操作の活用
ショートカットキーの設定
キーボードショートカットを設定することで、ユーザーは効率的に操作できるようになります。
例えば、Deleteキーで選択項目を削除するショートカットを実装する場合、以下のようなコードが利用できます。
#include <QApplication>
#include <QListWidget>
#include <QVBoxLayout>
#include <QWidget>
#include <QKeyEvent>
#include <QDebug>
class ShortcutWidget : public QWidget
{
public:
ShortcutWidget(QWidget *parent = nullptr) : QWidget(parent)
{
QVBoxLayout *layout = new QVBoxLayout(this);
listWidget = new QListWidget;
listWidget->addItem("ショートカットで削除されるアイテム1");
listWidget->addItem("ショートカットで削除されるアイテム2");
layout->addWidget(listWidget);
setLayout(layout);
}
protected:
void keyPressEvent(QKeyEvent *event) override
{
if(event->key() == Qt::Key_Delete) {
// 現在選択中のアイテムを削除
int currentRow = listWidget->currentRow();
if(currentRow >= 0)
{
QListWidgetItem *item = listWidget->takeItem(currentRow);
delete item;
qDebug() << "Deleteキーで選択項目を削除しました";
}
}
QWidget::keyPressEvent(event);
}
private:
QListWidget *listWidget;
};
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
ShortcutWidget widget;
widget.setWindowTitle("キーボードショートカットサンプル");
widget.resize(400, 300);
widget.show();
return app.exec();
}
// サンプル実行結果(動作例)
// リスト内の選択された項目がDeleteキーで削除され、ターミナルに「Deleteキーで選択項目を削除しました」と表示されます。
注意点とトラブルシューティング
よくある問題と対策
メモリ管理の注意点
QListWidgetでは、アイテム削除時にtakeItem
とdelete
を組み合わせる必要があるため、メモリリークに気を付ける必要があります。
特に、動的に生成したアイテムは、適切なタイミングで削除し、不要なメモリの確保を防ぐように心がけましょう。
- アイテム削除後に
delete
を実行 - 削除対象のアイテムがインスタンス管理から漏れないよう確認
シグナル接続の検証方法
シグナルとスロットの接続が期待通りに動作しない場合、connect
関数の戻り値を確認するのも一つの手段です。
正しく接続できたかどうかを検証することで、デバッグ作業の効率を向上させることができます。
また、シグナルが他のイベントに影響していないかも確認するようにするとよいです。
まとめ
今回の内容では、QListWidgetを使ってリスト形式のアイテム管理がどのように実現できるかを柔らかい文体で説明しました。
各項目の生成、カスタマイズ、イベント連携、そして操作性向上の方法についてサンプルコードを含めながら詳しく紹介しました。
これを参考に、実際のアプリケーション開発で使いやすく見やすいリスト管理を工夫してみるとよいでしょう。