Класс 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 может использовать бинарный поиск вместо линейного поиска. Бинарный поиск работает только когда 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)

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

QCompleter::QCompleter(QObject *parent = nullptr)

Конструктор объекта completer с заданным parent.

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

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

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

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

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

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

Примечание: Сигнал 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().