Класс QCompleter

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

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

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

Свойства

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

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

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

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

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

Сигналы

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

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

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

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

• 11 статических публичных членов унаследованных от 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 QDirModel(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::CompletionMode

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

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

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

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

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

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

QCompleter::QCompleter(QObject *parent = Q_NULLPTR)

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

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

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

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

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

QCompleter::~QCompleter()

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

void QCompleter::activated(const QString &text)

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

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

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

void QCompleter::activated(const QModelIndex &index)

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

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

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

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

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

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

[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 перегружен в этом классе. Чтобы подключиться к этому сигналу с помощью синтаксиса указателя на функцию, необходимо указать тип сигнала в явном преобразовании, как показано в этом примере:

connect(completer, static_cast<void(QCompleter::*)(const QString &)>(&QCompleter::highlighted),
    [=](const QString &text){ /* ... */ });

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

Этот сигнал отправляется, когда пользователь выделяет элемент в popup(). Он также отправляется, если complete() вызывается с completionMode(), установленным в QCompleter::InlineCompletion. Приводится индекс элемента index в completionModel().

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

connect(completer, static_cast<void(QCompleter::*)(const QModelIndex &)>(&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().