Класс QCompleter

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

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

Типы публичного доступа

Свойства

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

Функции публичного доступа

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

Публичные слоты

• 1 публичный слот унаследовано от QObject

Сигналы

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

Статические публичные члены

• 9 статических публичных членов унаследовано от 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.

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

перечисление QCompleter::CompletionMode

Это перечисление определяет, как предоставляются предложения автодополнения пользователю.

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

перечисление QCompleter::ModelSorting

Это перечисление определяет, как сортируются элементы в модели.

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

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

QCompleter::QCompleter(QObject *parent = nullptr)

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

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

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

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

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

[override virtual] QCompleter::~QCompleter()

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

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

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

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

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

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

Этот сигнал отправляется, когда пользователь активирует элемент в popup() (нажатием мыши или клавиши возврата). Приводится 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().

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

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

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