Класс QCompleter

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

Этот класс был введен в Qt 4.2.

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

Открытые типы

Свойства

Открытые функции

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

Сигналы

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

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

Вы можете использовать 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 может использовать двоичный поиск вместо линейного поиска. Двоичный поиск работает только тогда, когда режим фильтрации равен 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)

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

QCompleter::QCompleter(QObject *parent = nullptr)

Создаёт объект completer с заданным parent.

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

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

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

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

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

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

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

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

[slot] 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. Объект автодополнения использует его для получения текста автодополнения из базовой модели.

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

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

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