Qt Widgetsで入力補完を自由自在に操る！QCompleter::setPopup()と代替手段で実現する高度な補完機能

QCompleter::setPopup() メソッドは、Qt WidgetsライブラリにおけるQCompleterクラスで使用されるポップアップウィジェットを設定するために使用されます。QCompleterクラスは、入力中に候補リストを表示することで、テキスト入力ウィジェットの入力を補完する機能を提供します。

機能

setPopup() メソッドは、QCompleterクラスが使用するポップアップウィジェットを指定します。このウィジェットは、候補リストを表示するために使用されます。デフォルトでは、QCompleterクラスは内部的に生成されたシンプルなリストウィジェットを使用します。

使用方法

setPopup() メソッドを使用するには、まずポップアップウィジェットを作成する必要があります。このウィジェットは、QWidgetクラスの派生クラスである必要があります。次に、setPopup() メソッドを呼び出し、作成したウィジェットをパラメータとして渡します。

例

// ポップアップウィジェットを作成
QListView *popup = new QListView;

// QCompleterオブジェクトを作成
QCompleter *completer = new QCompleter;

// ポップアップウィジェットを設定
completer->setPopup(popup);

// QLineEditウィジェットにcompleterを設定
QLineEdit *lineEdit = new QLineEdit;
lineEdit->setCompleter(completer);

カスタマイズ

setPopup() メソッドを使用すると、QCompleterクラスのポップアップウィジェットを完全にカスタマイズすることができます。たとえば、独自のスタイルを適用したり、独自のデータモデルを使用したりすることができます。

注意事項

setPopup() メソッドを使用する場合は、ポップアップウィジェットの所有権を自分で管理する必要があります。QCompleterクラスは、ポップアップウィジェットを削除しません。

上記以外にも、QCompleterクラスには、ポップアップウィジェットの外観と動作を制御するためのさまざまなメソッドが用意されています。これらのメソッドの詳細については、Qtドキュメントを参照してください。

Qtのバージョンによって、API仕様が変更される場合があります。
本解説は、Qt Widgets 6.7.1を対象としています。

#include <QApplication>
#include <QCompleter>
#include <QListView>
#include <QStandardItemModel>

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

  // データモデルを作成
  QStandardItemModel *model = new QStandardItemModel;
  model->appendRow(QStandardItem("Alice"));
  model->appendRow(QStandardItem("Bob"));
  model->appendRow(QStandardItem("Charlie"));

  // ポップアップウィジェットを作成
  QListView *popup = new QListView;
  popup->setModel(model);

  // QCompleterオブジェクトを作成
  QCompleter *completer = new QCompleter;

  // ポップアップウィジェットを設定
  completer->setPopup(popup);

  // QLineEditウィジェットにcompleterを設定
  QLineEdit *lineEdit = new QLineEdit;
  lineEdit->setCompleter(completer);

  // ウィジェットを表示
  lineEdit->show();

  return app.exec();
}

説明

このコードは、以下の手順で動作します。

QStandardItemModel オブジェクトを作成し、候補リストのデータを追加します。
QListView オブジェクトを作成し、QStandardItemModel オブジェクトをモデルとして設定します。
QCompleter オブジェクトを作成します。
setPopup() メソッドを使用して、QCompleter オブジェクトのポップアップウィジェットを QListView オブジェクトに設定します。
QLineEdit オブジェクトを作成し、QCompleter オブジェクトを setCompleter() メソッドを使用して設定します。
QLineEdit オブジェクトを表示します。

実行結果

このコードを実行すると、QLineEdit ウィジェットが表示されます。ユーザーがこのウィジェットに入力すると、QCompleter オブジェクトが候補リストを生成し、ポップアップウィジェットに表示します。ユーザーは、矢印キーを使用して候補リストを移動し、Enter キーを押して選択することができます。

カスタマイズ

このコードは、独自のデータモデルやポップアップウィジェットを作成することで、簡単にカスタマイズすることができます。たとえば、QStandardItemModel の代わりに QStringListModel を使用して、文字列のリストを候補リストとして表示することができます。また、QListView の代わりに QComboBox を使用して、ドロップダウンリストを表示することもできます。

Qtのバージョンによって、API仕様が変更される場合があります。
このコードは、Qt Widgets 6.7.1を対象としています。

カスタム QAbstractItemModel を使用する

モデル内で、QCompleter がどのように候補を検索および表示するかを完全に制御できます。
QCompleter::setModel() メソッドを使用して、カスタムモデルを設定します。
複雑なデータモデルや高度なカスタマイズが必要な場合に適しています。

例

class MyModel : public QAbstractItemModel {
  // ... your model implementation
};

// ...

QCompleter *completer = new QCompleter;
completer->setModel(new MyModel);

QCompleter::setFilterMode() を使用する

利用可能なフラグには、Qt::StartsWith, Qt::Contains, Qt::EndsWith, Qt::FuzzyMatch などがあります。
QCompleter::setFilterMode() メソッドを使用して、Qt::MatchFlags 型のフラグを設定します。
候補の絞り込み方法をより細かく制御したい場合に適しています。

例

completer->setFilterMode(Qt::MatchFlags(Qt::StartsWith | Qt::FuzzyMatch));

QCompleter::setCompletionMode() を使用する

利用可能なモードには、PopupCompletion, InlineCompletion, OverlappingCompletion などがあります。
QCompleter::setCompletionMode() メソッドを使用して、QCompleter::CompletionMode 型の列挙体を設定します。
候補の表示方法を制御したい場合に適しています。

例

completer->setCompletionMode(QCompleter::InlineCompletion);

サードパーティ製のライブラリを使用する

例としては、QAutoComplete や QML AutoComplete などがあります。
Qt Widgets には、QCompleter の代替品となるいくつかのサードパーティ製ライブラリが存在します。
標準機能では実現できない高度な機能が必要な場合に適しています。

例

// QAutoComplete ライブラリの使用

#include <QAutoComplete>

// ...

QAutoComplete *autoComplete = new QAutoComplete;
autoComplete->setModel(new MyModel);
lineEdit->setCompleter(autoComplete);

最適な代替手段の選択

どの代替手段が最適かは、具体的な要件によって異なります。以下の点を考慮して選択してください。

高度な機能の必要性
標準機能では実現できない高度な機能が必要な場合は、サードパーティ製のライブラリを検討します。
候補の表示方法
候補の表示方法を制御したい場合は、QCompleter::setCompletionMode() を使用します。
候補の絞り込み方法
より細かい絞り込みが必要な場合は、QCompleter::setFilterMode() を使用します。
必要なカスタマイズレベル
カスタムモデルが必要な場合は、QCompleter::setModel() を使用します。