Класс QCompleter

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

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

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

Типы публичного интерфейса

Свойства

Публичные функции

Public Slots

Signals

Reimplemented Protected Functions

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

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