Класс QComboBox

Виджет QComboBox представляет собой сочетание кнопки и всплывающего списка. Подробнее...

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

Типы

Свойства

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

Реализованные публичные функции

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

Сигналы

Защищенные функции

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

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

QComboBox предоставляет способ отображения списка вариантов пользователю таким образом, чтобы занимать минимальное количество места на экране.

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

Комбобоксы могут содержать пиктограммы и строки; функции insertItem() и setItemText() надлежащим образом перегружены. Для редактируемых комбобоксов функция clearEditText() предоставлена для очистки отображаемой строки без изменения содержимого комбобокса.

Если текущий элемент комбобокса изменяется, генерируются три сигнала: currentIndexChanged(), currentTextChanged() и activated(). currentIndexChanged() и currentTextChanged() всегда генерируются независимо от того, было ли изменение выполнено программно или пользователем, а activated() генерируется только при изменении, вызванном взаимодействием пользователя. Сигнал highlighted() генерируется, когда пользователь выделяет элемент в всплывающем списке комбобокса. Все три сигнала существуют в двух версиях, одна с аргументом QString, а другая с аргументом int. Если пользователь выбирает или выделяет пиктограмму, генерируются только сигналы int. Всякий раз, когда изменяется текст редактируемого комбобокса, генерируется сигнал editTextChanged().

Когда пользователь вводит новую строку в редактируемый комбобокс, виджет может или не может вставить ее, и может вставить ее в различных местах. По умолчанию используется политика InsertAtBottom, но вы можете изменить ее с помощью setInsertPolicy().

Можно ограничить входные данные в редактируемый комбобокс с помощью QValidator; см. setValidator(). По умолчанию принимаются любые входные данные.

Комбобокс можно заполнить, используя функции вставки, например, insertItem() и insertItems(). Элементы можно изменить с помощью setItemText(). Элемент можно удалить с помощью removeItem(), а все элементы можно удалить с помощью clear(). Текст текущего элемента возвращается функцией currentText(), а текст элемента с заданным номером — функцией text(). Текущий элемент можно установить функцией setCurrentIndex(). Количество элементов в комбобоксе возвращает функция count(); максимальное количество элементов можно установить с помощью setMaxCount(). Можно разрешить редактирование с помощью setEditable(). Для редактируемых комбобоксов можно настроить автозаполнение с помощью setCompleter(), а возможность добавления дубликатов устанавливается с помощью setDuplicatesEnabled().

QComboBox использует фреймворк «модель/представление» для своего всплывающего списка и для хранения своих элементов. По умолчанию QStandardItemModel хранит элементы, а подкласс QListView отображает всплывающий список. Вы можете напрямую получить доступ к модели и представлению (с помощью model() и view()), но QComboBox также предоставляет функции для установки и получения данных элементов (например, setItemData() и itemText()). Вы также можете установить новую модель и представление (с помощью setModel() и setView()). Для текста и значка в метке комбобокса используются данные в модели, имеющие роли Qt::DisplayRole и Qt::DecorationRole. Обратите внимание, что вы не можете изменить режим выбора (SelectionMode) представления view(), например, с помощью setSelectionMode().

См. также QLineEdit, QSpinBox, QRadioButton, QButtonGroup и GUI Design Handbook: Combo Box, Drop-Down List Box.

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

enum QComboBox::InsertPolicy

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

enum QComboBox::SizeAdjustPolicy

Этот перечисление определяет, как размер раскрывающегося списка QComboBox должен изменяться при добавлении или изменении содержимого.

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

QComboBox::QComboBox(QWidget *parent = nullptr)

Конструирует combobox с заданным parent, используя модель по умолчанию QStandardItemModel.

[signal] void QComboBox::activated(int index)

Этот сигнал отправляется, когда пользователь выбирает элемент в combobox. Передаётся индекс элемента index. Обратите внимание, что этот сигнал отправляется даже при неизменном выборе. Если нужно узнать, когда выбор действительно изменяется, используйте сигнал currentIndexChanged() или currentTextChanged().

[slot] void QComboBox::clear()

Очищает combobox, удаляя все элементы.

Примечание: если вы установили внешнюю модель на combobox, эта модель всё равно будет очищена при вызове этой функции.

[slot] void QComboBox::clearEditText()

Очищает содержимое поля ввода, используемого для редактирования в combobox.

[signal] void QComboBox::currentIndexChanged(int index)

Этот сигнал отправляется всякий раз, когда currentIndex в combobox изменяется либо через взаимодействие с пользователем, либо программно. Передаётся индекс элемента index или -1, если combobox становится пустым или currentIndex был сброшен.

Примечание: Сигнал-уведомление для свойства currentIndex.

[signal, since 5.0] void QComboBox::currentTextChanged(const QString &text)

Этот сигнал отправляется всякий раз, когда currentText изменяется. Новое значение передаётся как text.

Примечание: Сигнал-уведомление для свойства currentText.

Эта функция была введена в Qt 5.0.

[signal] void QComboBox::editTextChanged(const QString &text)

Этот сигнал генерируется при изменении текста в поле редактирования combobox. Новый текст указан в text.

[signal] void QComboBox::highlighted(int index)

Этот сигнал отправляется, когда пользователь выделяет элемент в раскрывающемся списке combobox. Передаётся индекс элемента index.

[slot] void QComboBox::setEditText(const QString &text)

Устанавливает text в поле редактирования combobox.

[signal, since 5.14] void QComboBox::textActivated(const QString &text)

Этот сигнал отправляется, когда пользователь выбирает элемент в combobox. Передаётся текст элемента text. Обратите внимание, что этот сигнал отправляется даже при неизменном выборе. Если нужно узнать, когда выбор действительно изменяется, используйте сигнал currentIndexChanged() или currentTextChanged().

Эта функция была введена в Qt 5.14.

[signal, since 5.14] void QComboBox::textHighlighted(const QString &text)

Этот сигнал отправляется, когда пользователь выделяет элемент в раскрывающемся списке combobox. Передаётся текст элемента text.

Эта функция была введена в Qt 5.14.

[virtual] QComboBox::~QComboBox()

Удаляет combobox.

void QComboBox::addItem(const QString &text, const QVariant &userData = QVariant())

Добавляет элемент в combobox с заданным text и содержащим указанную userData (хранится в Qt::UserRole). Элемент добавляется в конец списка существующих элементов.

void QComboBox::addItem(const QIcon &icon, const QString &text, const QVariant &userData = QVariant())

Добавляет элемент в combobox с заданным icon и text, и содержащим указанную userData (хранится в Qt::UserRole). Элемент добавляется в конец списка существующих элементов.

void QComboBox::addItems(const QStringList &texts)

Добавляет каждый из строк в заданном texts в combobox. Каждый элемент добавляется в список существующих элементов по очереди.

[override virtual protected] void QComboBox::changeEvent(QEvent *e)

Переопределяет: QWidget::changeEvent(QEvent *event).

QCompleter *QComboBox::completer() const

Возвращает completer, используемый для автоматического завершения ввода текста в combobox.

См. также setCompleter() и editable.

[override virtual protected] void QComboBox::contextMenuEvent(QContextMenuEvent *e)

Переопределяет: QWidget::contextMenuEvent(QContextMenuEvent *event).

[override virtual] bool QComboBox::event(QEvent *event)

Переопределяет: QWidget::event(QEvent *event).

int QComboBox::findData(const QVariant &data, int role = Qt::UserRole, Qt::MatchFlags flags = static_cast<Qt::MatchFlags>(Qt::MatchExactly|Qt::MatchCaseSensitive)) const

Возвращает индекс элемента, содержащего заданные data для заданного role; в противном случае возвращает -1.

flags определяют способ поиска элементов в combobox.

int QComboBox::findText(const QString &text, Qt::MatchFlags flags = Qt::MatchExactly|Qt::MatchCaseSensitive) const

Возвращает индекс элемента, содержащего заданный text; в противном случае возвращает -1.

flags определяют способ поиска элементов в combobox.

[override virtual protected] void QComboBox::focusInEvent(QFocusEvent *e)

Переопределяет: QWidget::focusInEvent(QFocusEvent *event).

[override virtual protected] void QComboBox::focusOutEvent(QFocusEvent *e)

Переопределяет: QWidget::focusOutEvent(QFocusEvent *event).

[override virtual protected] void QComboBox::hideEvent(QHideEvent *e)

Переопределяет: QWidget::hideEvent(QHideEvent *event).

[virtual] void QComboBox::hidePopup()

Скрывает список элементов в раскрывающемся списке, если он в настоящее время отображается, и сбрасывает внутреннее состояние, так что если пользовательский всплывающее окно было показано внутри переопределенного метода showPopup(), то необходимо также переопределить функцию hidePopup(), чтобы скрыть пользовательское всплывающее окно и вызвать реализацию базового класса для сброса внутреннего состояния всякий раз, когда пользовательское виджет всплывающего окна скрывается.

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

[virtual protected] void QComboBox::initStyleOption(QStyleOptionComboBox *option) const

Инициализирует option значениями из этого QComboBox. Этот метод полезен для подклассов, когда им требуется QStyleOptionComboBox, но они не хотят заполнять всю информацию сами.

См. также QStyleOption::initFrom().

[override virtual protected] void QComboBox::inputMethodEvent(QInputMethodEvent *e)

Переопределяет: QWidget::inputMethodEvent(QInputMethodEvent *event).

[override virtual] QVariant QComboBox::inputMethodQuery(Qt::InputMethodQuery query) const

Переопределяет: QWidget::inputMethodQuery(Qt::InputMethodQuery query) const.

void QComboBox::insertItem(int index, const QString &text, const QVariant &userData = QVariant())

Вставляет text и userData (хранится в Qt::UserRole) в раскрывающийся список по заданному index.

Если индекс равен или больше общего количества элементов, новый элемент добавляется в конец списка существующих элементов. Если индекс равен нулю или отрицателен, новый элемент добавляется в начало списка существующих элементов.

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

void QComboBox::insertItem(int index, const QIcon &icon, const QString &text, const QVariant &userData = QVariant())

Вставляет icon, text и userData (хранится в Qt::UserRole) в раскрывающийся список по заданному index.

Если индекс равен или больше общего количества элементов, новый элемент добавляется в конец списка существующих элементов. Если индекс равен нулю или отрицателен, новый элемент добавляется в начало списка существующих элементов.

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

void QComboBox::insertItems(int index, const QStringList &list)

Вставляет строки из list в раскрывающийся список в качестве отдельных элементов, начиная с указанного index.

Если индекс равен или больше общего количества элементов, новые элементы добавляются в конец списка существующих элементов. Если индекс равен нулю или отрицателен, новые элементы добавляются в начало списка существующих элементов.

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

void QComboBox::insertSeparator(int index)

Вставляет разделительный элемент в раскрывающийся список по заданному index.

Если индекс равен или больше общего количества элементов, новый элемент добавляется в конец списка существующих элементов. Если индекс равен нулю или отрицателен, новый элемент добавляется в начало списка существующих элементов.

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

QVariant QComboBox::itemData(int index, int role = Qt::UserRole) const

Возвращает данные для заданного role в заданном index раскрывающегося списка или недействительный QVariant, если данных для этого роли нет.

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

QAbstractItemDelegate *QComboBox::itemDelegate() const

Возвращает делегат элемента, используемый списком всплывающего окна.

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

QIcon QComboBox::itemIcon(int index) const

Возвращает значок для заданного index в раскрывающемся списке.

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

QString QComboBox::itemText(int index) const

Возвращает текст для заданного index в раскрывающемся списке.

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

[override virtual protected] void QComboBox::keyPressEvent(QKeyEvent *e)

Переопределяет: QWidget::keyPressEvent(QKeyEvent *event).

[override virtual protected] void QComboBox::keyReleaseEvent(QKeyEvent *e)

Переопределяет: QWidget::keyReleaseEvent(QKeyEvent *event).

QLineEdit *QComboBox::lineEdit() const

Возвращает поле редактирования, используемое для редактирования элементов в раскрывающемся списке, или nullptr если поля редактирования нет.

Только изменяемые раскрывающиеся списки имеют поле редактирования.

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

[override virtual] QSize QComboBox::minimumSizeHint() const

Переопределяет функцию доступа к свойству: QWidget::minimumSizeHint.

QAbstractItemModel *QComboBox::model() const

Возвращает модель, используемую раскрывающимся списком.

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

[override virtual protected] void QComboBox::mousePressEvent(QMouseEvent *e)

Переопределяет: QWidget::mousePressEvent(QMouseEvent *event).

[override virtual protected] void QComboBox::mouseReleaseEvent(QMouseEvent *e)

Переопределяет: QWidget::mouseReleaseEvent(QMouseEvent *event).

[override virtual protected] void QComboBox::paintEvent(QPaintEvent *e)

Переопределяет: QWidget::paintEvent(QPaintEvent *event).

void QComboBox::removeItem(int index)

Удаляет элемент по заданному index из раскрывающегося списка. Это обновит текущий индекс, если индекс был удалён.

Эта функция ничего не делает, если index выходит за пределы диапазона.

[override virtual protected] void QComboBox::resizeEvent(QResizeEvent *e)

Переопределяет: QWidget::resizeEvent(QResizeEvent *event).

QModelIndex QComboBox::rootModelIndex() const

Возвращает индекс корневого элемента модели для элементов в раскрывающемся списке.

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

void QComboBox::setCompleter(QCompleter *completer)

Устанавливает completer для использования вместо текущего. Если completer равен nullptr, автодополнение отключено.

По умолчанию для изменяемого раскрывающегося списка автоматически создаётся QCompleter, выполняющий регистронезависимое встроенное дополнение.

Примечание: Делегат удаляется, когда свойство editable становится false, или когда поле редактирования заменяется вызовом setLineEdit(). Установка делегата для QComboBox, который не является изменяемым, будет проигнорирована.

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

void QComboBox::setItemData(int index, const QVariant &value, int role = Qt::UserRole)

Устанавливает данные role для элемента с заданным index в раскрывающемся списке в указанное значение value.

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

void QComboBox::setItemDelegate(QAbstractItemDelegate *delegate)

Устанавливает делегат элемента delegate для списка всплывающего окна. Раскрывающийся список принимает владение над делегатом.

Любой существующий делегат будет удалён, но не удалён. QComboBox не принимает владение над delegate.

Предупреждение: Не следует использовать один и тот же экземпляр делегата для нескольких раскрывающихся списков, отобразителей виджетов или представлений. Это может привести к некорректному или неинтуитивному поведению редактирования, так как каждое представление, подключенное к данному делегату, может получить сигнал closeEditor() и попытаться получить доступ к, изменить или закрыть редактор, который уже был закрыт.

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

void QComboBox::setItemIcon(int index, const QIcon &icon)

Устанавливает иконку для элемента с заданным индексом в раскрывающемся списке.

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

void QComboBox::setItemText(int index, const QString &text)

Устанавливает текст для элемента с заданным индексом в раскрывающемся списке.

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

void QComboBox::setLineEdit(QLineEdit *edit)

Устанавливает поле ввода edit для использования вместо текущего поля ввода.

Раскрывающийся список принимает во владение поле ввода.

Примечание: Поскольку поле ввода раскрывающегося списка владеет QCompleter, любые предыдущие вызовы setCompleter() больше не будут иметь никакого эффекта.

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

[virtual] void QComboBox::setModel(QAbstractItemModel *model)

Устанавливает модель model. model не должен быть nullptr. Если вы хотите очистить содержимое модели, вызовите clear().

Примечание: Если раскрывающийся список редактируемый, то model также будет установлен для автодополнения поля ввода.

См. также model(), clear() и setCompleter().

void QComboBox::setRootModelIndex(const QModelIndex &index)

Устанавливает индекс корневого элемента модели index для элементов в раскрывающемся списке.

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

void QComboBox::setValidator(const QValidator *validator)

Устанавливает validator для использования вместо текущего.

Примечание: Валидатор удаляется, когда свойство editable становится false.

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

void QComboBox::setView(QAbstractItemView *itemView)

Устанавливает представление, используемое в всплывающем окне раскрывающегося списка, на заданное itemView. Раскрывающийся список принимает во владение представление.

Примечание: Если вы хотите использовать удобные представления (например, QListWidget, QTableWidget или QTreeWidget), убедитесь, что вы вызываете setModel() для раскрывающегося списка с моделью удобных виджетов перед вызовом этой функции.

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

[override virtual protected] void QComboBox::showEvent(QShowEvent *e)

Переопределяет: QWidget::showEvent(QShowEvent *event).

[virtual] void QComboBox::showPopup()

Отображает список элементов в раскрывающемся списке. Если список пуст, элементы не будут отображаться.

Если вы переопределяете эту функцию для отображения пользовательского всплывающего окна, убедитесь, что вызываете hidePopup() для сброса внутреннего состояния.

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

[override virtual] QSize QComboBox::sizeHint() const

Переопределяет функцию доступа к свойству: QWidget::sizeHint.

Это реализация кеширует размер подсказки, чтобы избежать изменения размера при динамическом изменении содержимого. Чтобы аннулировать кэшированное значение, измените sizeAdjustPolicy.

const QValidator *QComboBox::validator() const

Возвращает валидатор, используемый для ограничения ввода текста для раскрывающегося списка.

См. также setValidator() и editable.

QAbstractItemView *QComboBox::view() const

Возвращает представление списка, используемое для всплывающего окна раскрывающегося списка.

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

[override virtual protected] void QComboBox::wheelEvent(QWheelEvent *e)

Переопределяет: QWidget::wheelEvent(QWheelEvent *event).