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

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

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

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

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

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

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

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

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

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

[slot] void QComboBox::clear()

Очищает раскрывающийся список, удаляя все элементы.

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

[slot] void QComboBox::clearEditText()

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

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

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

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

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

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

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

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

Этот сигнал отправляется всякий раз, когда currentIndex в раскрывающемся списке изменяется, как при взаимодействии пользователя, так и программно. Передаётся индекс элемента index, или -1, если раскрывающийся список становится пустым или 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)

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

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

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

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

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

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

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

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

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

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

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

[virtual] QComboBox::~QComboBox()

Уничтожает раскрывающийся список.

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

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

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

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

void QComboBox::addItems(const QStringList &texts)

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

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

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

QCompleter *QComboBox::completer() const

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

Эта функция была добавлена в 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 определяют способ поиска элементов в раскрывающемся списке.

int QComboBox::findText(const QString &text, Qt::MatchFlags flags = ...) const

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

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

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

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

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

Reimplements: QWidget::focusOutEvent(QFocusEvent *event).

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

Reimplements: 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)

Reimplements: QWidget::inputMethodEvent(QInputMethodEvent *event).

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

Reimplements: 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)

Reimplements: QWidget::keyPressEvent(QKeyEvent *event).

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

Reimplements: QWidget::keyReleaseEvent(QKeyEvent *event).

QLineEdit *QComboBox::lineEdit() const

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

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

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

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

Reimplements: QWidget::minimumSizeHint() const.

QAbstractItemModel *QComboBox::model() const

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

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

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

Reimplements: QWidget::mousePressEvent(QMouseEvent *event).

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

Reimplements: QWidget::mouseReleaseEvent(QMouseEvent *event).

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

Reimplements: QWidget::paintEvent(QPaintEvent *event).

void QComboBox::removeItem(int index)

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

Функция ничего не делает, если index вне диапазона.

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

Reimplements: 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)

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

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

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

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

Эта реализация кэширует размер подсказки, чтобы избежать изменения размера при динамическом изменении содержимого. Для сброса кэшированного значения измените 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).