Класс QCompleter

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

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

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

Свойства

• 1 свойство унаследовано от QObject

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

• 32 общедоступных функций унаследовано от QObject

Открытые слоты

• 1 открытый слот унаследовано от QObject

Сигналы

• 2 сигнала унаследовано от QObject

Переопределенные защищенные функции

• 9 защищенных функций унаследовано от QObject

Дополнительные унаследованные члены

• 11 статических публичных членов, унаследованных от QObject
• 9 защищённых функций, унаследованных от QObject

Подробное описание

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

Вы можете использовать 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() возвращает данные для роли edit role для моделей списка и абсолютный путь к файлу, если режим — QFileSystemModel.

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

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

enum QCompleter::CompletionMode

Этот перечисление задаёт способ предоставления вариантов автодополнения пользователю.

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

enum QCompleter::ModelSorting

Этот перечисление задаёт способ сортировки элементов в модели.

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

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

QCompleter::QCompleter(QObject *parent = Q_NULLPTR)

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

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

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

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

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

QCompleter::~QCompleter()

Уничтожает объект автозаполнения.

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

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

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

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

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

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

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

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

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

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

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

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().

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

Переопределено из QObject::event().

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

Переопределено из QObject::eventFilter().

[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){ /* ... */ });

[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){ /* ... */ });

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().