Класс QComboBox

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

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

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

Свойства

• 59 свойств унаследовано от QWidget
• 1 свойство унаследовано от QObject

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

Реализованные публичные функции

• 214 общедоступных функций, унаследованных от QWidget
• 32 общедоступных функций, унаследованных от QObject
• 14 общедоступных функций, унаследованных от QPaintDevice

Открытые слоты

• 19 открытых слотов, унаследованных от QWidget
• 1 открытый слот, унаследованный от QObject

Сигналы

• 3 сигнала, унаследованные от QWidget
• 2 сигнала, унаследованные от QObject

Защищённые функции

Переопределённые защищённые функции

• 35 защищённых функций, унаследованных от QWidget
• 9 защищённых функций, унаследованных от QObject
• 1 защищённая функция, унаследованная от QPaintDevice

Дополнительные унаследованные члены

• 5 статических общедоступных членов, унаследованных от QWidget
• 11 статических общедоступных членов, унаследованных от QObject
• 1 защищённый слот, унаследованный от QWidget

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

Виджет QComboBox представляет собой объединённую кнопку и всплывающий список.

Виджет 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()). Для текста и значка в метке combobox используются данные в модели, имеющие Qt::DisplayRole и Qt::DecorationRole. Обратите внимание, что вы не можете изменить режим выбора представления view(), например, с помощью setSelectionMode().

См. также QLineEdit, QSpinBox, QRadioButton, QButtonGroup и Справочник по проектированию пользовательского интерфейса: Комбо-боксы, выпадающие списки.

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

enum QComboBox::InsertPolicy

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

enum QComboBox::SizeAdjustPolicy

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

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

QComboBox::QComboBox(QWidget *parent = Q_NULLPTR)

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

QComboBox::~QComboBox()

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

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

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

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

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

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

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

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

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

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

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

Переопределено из QWidget::changeEvent().

[slot] void QComboBox::clear()

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

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

[slot] void QComboBox::clearEditText()

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

QCompleter *QComboBox::completer() const

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

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

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

[virtual protected] void QComboBox::contextMenuEvent(QContextMenuEvent *e)

Переопределено из QWidget::contextMenuEvent().

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

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

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

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

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

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

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

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

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

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

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

[virtual] bool QComboBox::event(QEvent *event)

Переопределено из QObject::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 = static_cast<Qt::MatchFlags> ( Qt::MatchExactly | Qt::MatchCaseSensitive )) const

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

Параметр flags определяет способ поиска элементов в combobox.

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

Переопределено из QWidget::focusInEvent().

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

Переопределено из QWidget::focusOutEvent().

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

Переопределено из QWidget::hideEvent().

[virtual] void QComboBox::hidePopup()

Скрывает список элементов в combobox, если он в данный момент отображается, и сбрасывает внутреннее состояние. Таким образом, если пользовательский всплывающее окно было показано внутри переопределенного showPopup(), то необходимо переопределить функцию hidePopup() для скрытия пользовательского всплывающего окна и вызвать реализацию базового класса для сброса внутреннего состояния всякий раз, когда пользовательское всплывающее окно скрывается.

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

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

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

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

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

[signal] void QComboBox::highlighted(const QString &текст)

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

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

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

[protected] void QComboBox::initStyleOption(QStyleOptionComboBox *option) const

Инициализирует option значениями из этого QComboBox. Этот метод полезен для подклассов, когда им нужен QStyleOptionComboBox, но они не хотят заполнять всю информацию самостоятельно.

См. также QStyleOption::initFrom().

[virtual protected] void QComboBox::inputMethodEvent(QInputMethodEvent *e)

Переопределено из QWidget::inputMethodEvent().

[virtual] QVariant QComboBox::inputMethodQuery(Qt::InputMethodQuery запрос) const

Переопределено из QWidget::inputMethodQuery().

void QComboBox::insertItem(int индекс, const QString &текст, const QVariant &userData = QVariant())

Вставляет текст и userData (хранится в Qt::UserRole) в combobox по указанному индексу.

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

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

void QComboBox::insertItem(int индекс, const QIcon &иконка, const QString &текст, const QVariant &userData = QVariant())

Вставляет иконку, текст и userData (хранится в Qt::UserRole) в combobox по указанному индексу.

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

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

void QComboBox::insertItems(int индекс, const QStringList &список)

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

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

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

void QComboBox::insertSeparator(int индекс)

Вставляет разделитель в combobox по указанному индексу.

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

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

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

QVariant QComboBox::itemData(int индекс, int роль = Qt::UserRole) const

Возвращает данные для заданной роли в заданном индексе combobox или QVariant::Invalid, если данных для этой роли нет.

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

QAbstractItemDelegate *QComboBox::itemDelegate() const

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

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

QIcon QComboBox::itemIcon(int индекс) const

Возвращает иконку для данного индекса в combobox.

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

QString QComboBox::itemText(int индекс) const

Возвращает текст для данного индекса в combobox.

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

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

Переопределено из QWidget::keyPressEvent().

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

Переопределено из QWidget::keyReleaseEvent().

QLineEdit *QComboBox::lineEdit() const

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

Только редактируемые combobox имеют редактор строки.

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

[virtual] QSize QComboBox::minimumSizeHint() const

Переопределено из QWidget::minimumSizeHint().

QAbstractItemModel *QComboBox::model() const

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

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

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

Переопределено из QWidget::mousePressEvent().

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

Переопределено из QWidget::mouseReleaseEvent().

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

Переопределено из QWidget::paintEvent().

void QComboBox::removeItem(int индекс)

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

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

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

Переопределено из QWidget::resizeEvent().

QModelIndex QComboBox::rootModelIndex() const

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

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

void QComboBox::setCompleter(QCompleter *completer)

Устанавливает completer для использования вместо текущего. Если completer равен 0, автозаполнение отключается.

По умолчанию для редактируемого combobox автоматически создаётся QCompleter, который выполняет регистронезависимое встраиваемое дополнение.

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

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

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

[slot] void QComboBox::setEditText(const QString &текст)

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

void QComboBox::setItemData(int индекс, const QVariant &значение, int роль = Qt::UserRole)

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

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

void QComboBox::setItemDelegate(QAbstractItemDelegate *delegate)

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

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

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

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

Устанавливает icon для элемента с заданным index в combobox.

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

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

Устанавливает text для элемента с заданным index в combobox.

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

void QComboBox::setLineEdit(QLineEdit *edit)

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

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

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

void QComboBox::setModel(QAbstractItemModel *model)

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

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

void QComboBox::setRootModelIndex(const QModelIndex &index)

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

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

void QComboBox::setValidator(const QValidator *validator)

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

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

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

void QComboBox::setView(QAbstractItemView *itemView)

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

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

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

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

Переопределено из QWidget::showEvent().

[virtual] void QComboBox::showPopup()

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

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

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

[virtual] QSize QComboBox::sizeHint() const

Переопределено из QWidget::sizeHint().

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

const QValidator *QComboBox::validator() const

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

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

QAbstractItemView *QComboBox::view() const

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

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

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

Переопределено из QWidget::wheelEvent().