Класс QComboBox

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

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

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

Свойства

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

Реализованные общедоступные функции

Public Slots

Signals

Protected Functions

Реализованные защищенные функции

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

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

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

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

Если текущий элемент комбобокса изменяется, генерируются два сигнала: currentIndexChanged() и activated(). currentIndexChanged() всегда генерируется, независимо от того, было ли изменение произведено программно или пользователем, в то время как 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, когда пользователь вводит новую строку.

enum QComboBox::SizeAdjustPolicy

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

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

QComboBox::QComboBox(QWidget *parent = nullptr)

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

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

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

Примечание: Сигнал 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(const QString &text)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[virtual] QComboBox::~QComboBox()

Уничтожает combobox.

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

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

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

Добавляет элемент в combobox с заданным icon и текстом, и содержащим заданные данные 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.

Эта функция была введена в 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 = ...) const

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

См. также 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 равен 0, автозаполнение отключено.

По умолчанию, для изменяемого раскрывающегося списка автоматически создается 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)

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

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

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

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

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

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

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

Устанавливает текст для элемента с заданным индексом в QComboBox.

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

void QComboBox::setLineEdit(QLineEdit *edit)

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

QComboBox принимает во владение поле ввода.

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

void QComboBox::setModel(QAbstractItemModel *model)

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

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

void QComboBox::setRootModelIndex(const QModelIndex &index)

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

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

void QComboBox::setValidator(const QValidator *validator)

Устанавливает валидатор вместо текущего.

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

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

void QComboBox::setView(QAbstractItemView *itemView)

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

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

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

void QComboBox::showEvent(QShowEvent *e)

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

void QComboBox::showPopup()

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

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

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

QSize QComboBox::sizeHint() const

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

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

const QValidator *QComboBox::validator() const

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

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

QAbstractItemView *QComboBox::view() const

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

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

void QComboBox::wheelEvent(QWheelEvent *e)

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