QCompleter Class

 QStringList wordList;
 wordList << "alpha" << "omega" << "omicron" << "zeta";

 QLineEdit *lineEdit = new QLineEdit(this);

 QCompleter *completer = new QCompleter(wordList, this);
 completer->setCaseSensitivity(Qt::CaseInsensitive);
 lineEdit->setCompleter(completer);

 QCompleter *completer = new QCompleter(this);
 completer->setModel(new QFileSystemModel(completer));
 lineEdit->setCompleter(completer);

 for (int i = 0; completer->setCurrentRow(i); i++)
     qDebug() << completer->currentCompletion() << " is match number " << i;

Member Function Documentation

QCompleter::QCompleter(QObject *parent = nullptr)

Constructs a completer object with the given parent.

QCompleter::QCompleter(QAbstractItemModel *model, QObject *parent = nullptr)

Constructs a completer object with the given parent that provides completions from the specified model.

QCompleter::QCompleter(const QStringList &list, QObject *parent = nullptr)

Constructs a QCompleter object with the given parent that uses the specified list as a source of possible completions.

[override virtual noexcept] QCompleter::~QCompleter()

Destroys the completer object.

[signal] void QCompleter::activated(const QString &text)

This signal is sent when an item in the popup() is activated by the user (by clicking or pressing return). The item's text is given.

Note: Signal activated is overloaded in this class. To connect to this signal by using the function pointer syntax, Qt provides a convenient helper for obtaining the function pointer as shown in this example:

 connect(completer, QOverload<const QString &>::of(&QCompleter::activated),
     [=](const QString &text){ /* ... */ });

[signal] void QCompleter::activated(const QModelIndex &index)

This signal is sent when an item in the popup() is activated by the user. (by clicking or pressing return). The item's index in the completionModel() is given.

Note: Signal activated is overloaded in this class. To connect to this signal by using the function pointer syntax, Qt provides a convenient helper for obtaining the function pointer as shown in this example:

 connect(completer, QOverload<const QModelIndex &>::of(&QCompleter::activated),
     [=](const QModelIndex &index){ /* ... */ });

[slot] void QCompleter::complete(const QRect &rect = QRect())

For QCompleter::PopupCompletion and QCompletion::UnfilteredPopupCompletion modes, calling this function displays the popup displaying the current completions. By default, if rect is not specified, the popup is displayed on the bottom of the widget(). If rect is specified the popup is displayed on the left edge of the rectangle.

For QCompleter::InlineCompletion mode, the highlighted() signal is fired with the current completion.

int QCompleter::completionCount() const

Returns the number of completions for the current prefix. For an unsorted model with a large number of items this can be expensive. Use setCurrentRow() and currentCompletion() to iterate through all the completions.

QAbstractItemModel *QCompleter::completionModel() const

Returns the completion model. The completion model is a read-only list model that contains all the possible matches for the current completion prefix. The completion model is auto-updated to reflect the current completions.

See also completionPrefix and model().

QString QCompleter::currentCompletion() const

Returns the current completion string. This includes the completionPrefix. When used alongside setCurrentRow(), it can be used to iterate through all the matches.

See also setCurrentRow() and currentIndex().

QModelIndex QCompleter::currentIndex() const

Returns the model index of the current completion in the completionModel().

See also setCurrentRow(), currentCompletion(), and model().

int QCompleter::currentRow() const

Returns the current row.

See also setCurrentRow().

[override virtual protected] bool QCompleter::event(QEvent *ev)

Reimplements: QObject::event(QEvent *e).

[override virtual protected] bool QCompleter::eventFilter(QObject *o, QEvent *e)

Reimplements: QObject::eventFilter(QObject *watched, QEvent *event).

[signal] void QCompleter::highlighted(const QString &text)

This signal is sent when an item in the popup() is highlighted by the user. It is also sent if complete() is called with the completionMode() set to QCompleter::InlineCompletion. The item's text is given.

Note: Signal highlighted is overloaded in this class. To connect to this signal by using the function pointer syntax, Qt provides a convenient helper for obtaining the function pointer as shown in this example:

 connect(completer, QOverload<const QString &>::of(&QCompleter::highlighted),
     [=](const QString &text){ /* ... */ });

[signal] void QCompleter::highlighted(const QModelIndex &index)

This signal is sent when an item in the popup() is highlighted by the user. It is also sent if complete() is called with the completionMode() set to QCompleter::InlineCompletion. The item's index in the completionModel() is given.

Note: Signal highlighted is overloaded in this class. To connect to this signal by using the function pointer syntax, Qt provides a convenient helper for obtaining the function pointer as shown in this example:

 connect(completer, QOverload<const QModelIndex &>::of(&QCompleter::highlighted),
     [=](const QModelIndex &index){ /* ... */ });

QAbstractItemModel *QCompleter::model() const

Returns the model that provides completion strings.

See also setModel() and completionModel().

[virtual] QString QCompleter::pathFromIndex(const QModelIndex &index) const

Returns the path for the given index. The completer object uses this to obtain the completion text from the underlying model.

The default implementation returns the edit role of the item for list models. It returns the absolute file path if the model is a QFileSystemModel.

See also splitPath().

QAbstractItemView *QCompleter::popup() const

Returns the popup used to display completions.

See also setPopup().

bool QCompleter::setCurrentRow(int row)

Sets the current row to the row specified. Returns true if successful; otherwise returns false.

This function may be used along with currentCompletion() to iterate through all the possible completions.

See also currentRow(), currentCompletion(), and completionCount().

void QCompleter::setModel(QAbstractItemModel *model)

Sets the model which provides completions to model. The model can be list model or a tree model. If a model has been already previously set and it has the QCompleter as its parent, it is deleted.

For convenience, if model is a QFileSystemModel, QCompleter switches its caseSensitivity to Qt::CaseInsensitive on Windows and Qt::CaseSensitive on other platforms.

See also completionModel(), modelSorting, and Handling Tree Models.

void QCompleter::setPopup(QAbstractItemView *popup)

Sets the popup used to display completions to popup. QCompleter takes ownership of the view.

A QListView is automatically created when the completionMode() is set to QCompleter::PopupCompletion or QCompleter::UnfilteredPopupCompletion. The default popup displays the completionColumn().

Ensure that this function is called before the view settings are modified. This is required since view's properties may require that a model has been set on the view (for example, hiding columns in the view requires a model to be set on the view).

See also popup().

void QCompleter::setWidget(QWidget *widget)

Sets the widget for which completion are provided for to widget. This function is automatically called when a QCompleter is set on a QLineEdit using QLineEdit::setCompleter() or on a QComboBox using QComboBox::setCompleter(). The widget needs to be set explicitly when providing completions for custom widgets.

See also widget(), setModel(), and setPopup().

[virtual] QStringList QCompleter::splitPath(const QString &path) const

Splits the given path into strings that are used to match at each level in the model().

The default implementation of splitPath() splits a file system path based on QDir::separator() when the sourceModel() is a QFileSystemModel.

When used with list models, the first item in the returned list is used for matching.

See also pathFromIndex() and Handling Tree Models.

QWidget *QCompleter::widget() const

Returns the widget for which the completer object is providing completions.

See also setWidget().