Класс QCompleter

Класс QCompleter предоставляет автодополнение на основе модели элементов. Подробнее...

• Список всех членов, включая унаследованные

Общедоступные типы

Свойства

Общедоступные функции

Public Slots

Signals

Reimplemented Protected Functions

Detailed Description

С помощью QCompleter можно реализовать автодополнение в любом виджете Qt, например, QLineEdit и QComboBox. Когда пользователь начинает вводить слово, QCompleter предлагает возможные варианты завершения слова, основанные на списке слов. Список слов предоставляется как QAbstractItemModel. (Для простых приложений, где список слов статичен, вы можете передать QStringList в конструктор QCompleter.)

Основные возможности

QCompleter обычно используется с QLineEdit или QComboBox. Например, вот как можно обеспечить автодополнение из простого списка слов в QLineEdit:

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);

Для обеспечения автодополнения имён файлов можно использовать QFileSystemModel. Например:

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

Чтобы установить модель, с которой должен работать QCompleter, вызовите setModel(). По умолчанию QCompleter попытается сопоставить префикс автодополнения (т.е. слово, с которого пользователь начал набирать) с данными Qt::EditRole в столбце 0 модели, учитывая регистр. Это можно изменить, используя setCompletionRole(), setCompletionColumn() и setCaseSensitivity().

Если модель отсортирована по столбцу и роли, используемым для автодополнения, вы можете вызвать setModelSorting() с аргументом либо QCompleter::CaseSensitivelySortedModel, либо QCompleter::CaseInsensitivelySortedModel. В больших моделях это может значительно улучшить производительность, поскольку QCompleter сможет использовать двоичный поиск вместо линейного. Двоичный поиск работает только тогда, когда filterMode равен Qt::MatchStartsWith.

Модель может быть списковой моделью, табличной моделью или деревянной моделью. Автодополнение для древовидных моделей немного сложнее и описано в разделе Обработка древовидных моделей ниже.

Свойство completionMode() определяет режим предоставления предложений пользователю.

Перебор предложений

Чтобы получить одну строку кандидата, вызовите setCompletionPrefix() со строкой, которая должна быть дополнена, и вызовите currentCompletion(). Вы можете перебрать список предложений следующим образом:

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

completionCount() возвращает общее количество предложений для текущего префикса. completionCount() следует избегать, когда это возможно, так как это требует сканирования всей модели.

Модель автодополнения

completionModel() возвращает список моделей, содержащий все возможные предложения для текущего префикса автодополнения в том порядке, в котором они появляются в модели. Эта модель может быть использована для отображения текущих предложений в пользовательском представлении. Вызов setCompletionPrefix() автоматически обновляет модель предложений.

Обработка древовидных моделей

QCompleter может искать предложения в древовидных моделях, предполагая, что любой элемент (или подэлемент или под-подэлемент) может быть однозначно представлен строкой путём указания пути к элементу. Затем автодополнение выполняется по одному уровню за раз.

Рассмотрим пример пользователя, набирающего путь к файлу. Модель — (иерархическая) QFileSystemModel. Автодополнение выполняется для каждого элемента в пути. Например, если текущий текст — C:\Wind, QCompleter может предложить Windows для завершения текущего элемента пути. Аналогично, если текущий текст — C:\Windows\Sy, QCompleter может предложить System.

Для работы такого автодополнения QCompleter должен иметь возможность разделить путь на список строк, которые сопоставляются на каждом уровне. Для C:\Windows\Sy, он должен быть разделён на "C:", "Windows" и "Sy". Стандартная реализация splitPath() разделяет completionPrefix с помощью QDir::separator(), если модель — QFileSystemModel.

Для предоставления предложений QCompleter должен знать путь из индекса. Это предоставляется методом pathFromIndex(). Стандартная реализация pathFromIndex() возвращает данные для роли редактирования для списковых моделей и абсолютный путь к файлу, если модель — QFileSystemModel.

См. также QAbstractItemModel, QLineEdit, QComboBox и Пример Completer.

Документация по типам членов

перечисление QCompleter::CompletionMode

Это перечисление определяет, как предоставляются предложения пользователю.

См. также setCompletionMode().

перечисление QCompleter::ModelSorting

Это перечисление определяет, как сортируются элементы в модели.

См. также setModelSorting().

Документация по членам-функциям

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

Конструктор QCompleter с заданным parent, использующий переданный list в качестве источника возможных дополнений.

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

Конструктор объекта дополнения с заданным parent, предоставляющим дополнения из указанной model.

QCompleter::QCompleter(QObject *parent = nullptr)

Конструктор объекта дополнения с заданным parent.

void QCompleter::activated(const QModelIndex &index)

Этот сигнал отправляется, когда пользователь активирует элемент в popup() (щелчком или нажатием клавиши возврата). Передаётся индекс элемента в completionModel().

Примечание: Сигнал activated перегружен в этом классе. Для подключения к этому сигналу с помощью синтаксиса указателя на функцию Qt предоставляет удобную вспомогательную функцию, как показано в этом примере:

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

void QCompleter::activated(const QString &text)

Этот сигнал отправляется, когда пользователь активирует элемент в popup() (щелчком или нажатием клавиши возврата). Передаётся текст элемента.

Примечание: Сигнал activated перегружен в этом классе. Для подключения к этому сигналу с помощью синтаксиса указателя на функцию Qt предоставляет удобную вспомогательную функцию, как показано в этом примере:

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

void QCompleter::complete(const QRect &rect = QRect())

Для режимов QCompleter::PopupCompletion и QCompletion::UnfilteredPopupCompletion вызов этой функции отображает всплывающее окно, отображающее текущие дополнения. По умолчанию, если rect не указан, всплывающее окно отображается внизу виджета widget(). Если rect указан, всплывающее окно отображается слева от прямоугольника.

Для режима QCompleter::InlineCompletion сигнал highlighted() срабатывает с текущим дополнением.

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

Этот сигнал отправляется, когда пользователь выделяет элемент во всплывающем окне popup(). Он также отправляется, если complete() вызывается с completionMode() установленным в QCompleter::InlineCompletion. Приводится индекс index элемента в completionModel().

Примечание: Сигнал highlighted перегружен в этом классе. Для подключения к этому сигналу с использованием синтаксиса указателя на функцию Qt предоставляет удобную функцию для получения указателя на функцию, как показано в этом примере:

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

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

Этот сигнал отправляется, когда пользователь выделяет элемент во всплывающем окне popup(). Он также отправляется, если complete() вызывается с completionMode() установленным в QCompleter::InlineCompletion. Приводится text элемента.

Примечание: Сигнал highlighted перегружен в этом классе. Для подключения к этому сигналу с использованием синтаксиса указателя на функцию Qt предоставляет удобную функцию для получения указателя на функцию, как показано в этом примере:

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

[override virtual] QCompleter::~QCompleter()

Удаляет объект дополнения.

int QCompleter::completionCount() const

Возвращает количество дополнений для текущего префикса. Для неупорядоченного модели с большим количеством элементов это может быть дорогостоящим. Используйте setCurrentRow() и currentCompletion() для перебора всех дополнений.

QAbstractItemModel *QCompleter::completionModel() const

Возвращает модель дополнений. Модель дополнений — это только для чтения список моделей, содержащий все возможные совпадения для текущего префикса дополнения. Модель дополнений автоматически обновляется, чтобы отразить текущие дополнения.

Примечание: Значение, возвращаемое этой функцией, определено как QAbstractItemModel исключительно для общности. Фактический тип возвращаемой модели — это экземпляр подкласса QAbstractProxyModel.

См. также completionPrefix и model().

QString QCompleter::currentCompletion() const

Возвращает текущую строку дополнения. Она включает completionPrefix. В сочетании с setCurrentRow() может использоваться для перебора всех совпадений.

См. также setCurrentRow() и currentIndex().

QModelIndex QCompleter::currentIndex() const

Возвращает индекс модели текущего дополнения в completionModel().

См. также setCurrentRow(), currentCompletion() и model().

int QCompleter::currentRow() const

Возвращает текущую строку.

См. также setCurrentRow().

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

Переопределяет: QObject::event(QEvent *e).

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

Переопределяет: QObject::eventFilter(QObject *watched, QEvent *event).

QAbstractItemModel *QCompleter::model() const

Возвращает модель, предоставляющую строки дополнения.

См. также setModel() и completionModel().

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

Возвращает путь для данного index. Объект дополнения использует его для получения текста дополнения из базовой модели.

По умолчанию реализация возвращает роль редактирования edit role элемента для списковых моделей. Возвращает абсолютный путь к файлу, если моделью является QFileSystemModel.

См. также splitPath().

QAbstractItemView *QCompleter::popup() const

Возвращает всплывающее окно, используемое для отображения дополнений.

См. также setPopup().

bool QCompleter::setCurrentRow(int row)

Устанавливает текущую строку на указанную row. Возвращает true в случае успеха; в противном случае возвращает false.

Эта функция может использоваться вместе с currentCompletion() для перебора всех возможных дополнений.

См. также currentRow(), currentCompletion() и completionCount().

void QCompleter::setModel(QAbstractItemModel *model)

Устанавливает модель, предоставляющую дополнения, на model. Моделью может быть списковая или древовидная модель. Если модель уже была установлена ранее и имеет QCompleter в качестве родителя, она удаляется.

Для удобства, если model — это QFileSystemModel, QCompleter переключает caseSensitivity на Qt::CaseInsensitive в Windows и Qt::CaseSensitive на других платформах.

См. также completionModel(), modelSorting и Обработка древовидных моделей.

void QCompleter::setPopup(QAbstractItemView *popup)

Устанавливает всплывающее окно для отображения дополнений на popup. QCompleter принимает владение представлением.

Класс QListView автоматически создается, когда completionMode() устанавливается в QCompleter::PopupCompletion или QCompleter::UnfilteredPopupCompletion. По умолчанию всплывающее окно отображает completionColumn().

Убедитесь, что эта функция вызвана до изменения настроек представления. Это необходимо, так как свойства представления могут потребовать, чтобы модель была установлена в представлении (например, скрытие столбцов в представлении требует установки модели в представлении).

См. также popup().

void QCompleter::setWidget(QWidget *widget)

Устанавливает виджет, для которого предоставляются дополнения, на widget. Эта функция автоматически вызывается, когда QCompleter устанавливается на QLineEdit с помощью QLineEdit::setCompleter() или на QComboBox с помощью QComboBox::setCompleter(). Необходимо явно установить виджет, предоставляя дополнения для пользовательских виджетов.

См. также widget(), setModel() и setPopup().

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

Разделяет заданный path на строки, используемые для сопоставления на каждом уровне в model().

По умолчанию реализация splitPath() разделяет путь к файловой системе на основе QDir::separator(), когда sourceModel() является QFileSystemModel.

При использовании со списковыми моделями первый элемент в возвращаемом списке используется для сопоставления.

См. также pathFromIndex() и Обработка древовидных моделей.

QWidget *QCompleter::widget() const

Возвращает виджет, для которого объект дополнения предоставляет дополнения.

См. также setWidget().