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

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

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)

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

Примечание: Сигнал-уведомление для свойства 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)

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

Любой существующий делегат будет удален, но не удален. 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).