Класс 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().

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

connect(comboBox, QOverload<int>::of(&QComboBox::activated),
    [=](int index){ /* ... */ });

[slot] void QComboBox::clear()

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

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

[slot] void QComboBox::clearEditText()

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

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

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

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

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

connect(comboBox, QOverload<int>::of(&QComboBox::currentIndexChanged),
    [=](int index){ /* ... */ });

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

[signal] 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.

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

connect(comboBox, QOverload<int>::of(&QComboBox::highlighted),
    [=](int index){ /* ... */ });

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

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

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

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

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

[signal] 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.

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

См. также 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().

[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.

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

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

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

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

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

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

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

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

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

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

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

void QComboBox::setItemDelegate(QAbstractItemDelegate *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)

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

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

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

void QComboBox::setModel(QAbstractItemModel *model)

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

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

void QComboBox::setRootModelIndex(const QModelIndex &index)

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

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

void QComboBox::setValidator(const QValidator *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).