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

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

перечисление QComboBox::InsertPolicy

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

перечисление 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

Возвращает автозаполняющий механизм, который используется для автоматического завершения ввода текста в 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, если данных для этого role нет.

См. также 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, который выполняет регистронезависимое встраиваемое дополнение.

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

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

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

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

void QComboBox::setItemDelegate(QAbstractItemDelegate *delegate)

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

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

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

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

Устанавливает иконку для элемента по заданному индексу в combobox.

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

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

Устанавливает текст для элемента по заданному индексу в combobox.

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

void QComboBox::setLineEdit(QLineEdit *edit)

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

Комбобокс принимает во владение поле ввода.

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

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

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

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

void QComboBox::setRootModelIndex(const QModelIndex &index)

Устанавливает индекс корневого элемента модели для элементов в combobox.

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

void QComboBox::setValidator(const QValidator *validator)

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

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

void QComboBox::setView(QAbstractItemView *itemView)

Устанавливает представление, используемое в всплывающем окне combobox, в указанное itemView. Комбобокс принимает во владение представление.

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

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

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

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

[virtual] void QComboBox::showPopup()

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

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

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

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

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

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

const QValidator *QComboBox::validator() const

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

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

QAbstractItemView *QComboBox::view() const

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

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

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

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