Класс 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 и Пример QCompleter.

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

Перечисление 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.

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

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

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

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

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

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

Примечание: Сигнал 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 не указан, всплывающее окно отображается в нижней части виджета(). Если rect указан, всплывающее окно отображается слева от прямоугольника.

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

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

Этот сигнал отправляется, когда пользователь выделяет элемент во всплывающем окне popup(). Он также отправляется, если complete() вызывается с completionMode() установленным в QCompleter::InlineCompletion. Указывается индекс элемента в 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. Передается текст элемента.

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

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

См. также 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. Модель может быть моделью списка или древовидной моделью. Если модель уже была установлена ранее и она имеет QCompleter в качестве родителя, она удаляется.

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

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

void QCompleter::setPopup(QAbstractItemView *popup)

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

При установке completionMode() в QCompleter::PopupCompletion или QCompleter::UnfilteredPopupCompletion автоматически создается QListView. По умолчанию всплывающее окно отображает 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().