Класс 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()

Уничтожает объект completer.

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. Объект completer использует это для получения текста предложения из базовой модели.

Реализация по умолчанию возвращает роль редактирования элемента для моделей списка. Возвращает абсолютный путь к файлу, если модель является 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. Модель 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

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

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