Класс QCompleter

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

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

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

Свойства

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

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

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

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

• 1 открытый слот, унаследованный от QObject

Сигналы

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

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

• 9 защищённых функций, унаследованных от QObject

Дополнительные унаследованные члены

• 1 общедоступная переменная, унаследованная от QObject
• 10 статические общедоступные члены, унаследованные от QObject
• 9 защищенные функции, унаследованные от QObject
• 2 защищенные переменные, унаследованные от 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() разделяет префикс автодополнения с помощью QDir::separator(), если модель — QFileSystemModel.

Чтобы предоставить автозаполнения, QCompleter должен знать путь от индекса. Это предоставляется методом pathFromIndex(). По умолчанию реализация pathFromIndex() возвращает данные для роли редактирования для моделей списка и абсолютный путь к файлу, если модель — QFileSystemModel.

См. также QAbstractItemModel, QLineEdit, QComboBox и Пример Completer.

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

enum QCompleter::CompletionMode

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

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

enum QCompleter::ModelSorting

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

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

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

QCompleter::QCompleter(QObject *parent = nullptr)

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

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

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

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

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

[virtual] QCompleter::~QCompleter()

Уничтожает объект completer.

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

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

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

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

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

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