Класс QComboBox

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

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

Общедоступные типы

Свойства

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

Общедоступные функции

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

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

Общедоступные слоты

• 19 общедоступных слотов, унаследованных от QWidget
• 1 общедоступный слот, унаследованный от QObject

Сигналы

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

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

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

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

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

• 1 общедоступная переменная, унаследованная от QObject
• 5 статические общедоступные члены, унаследованные от QWidget
• 10 статических общедоступных членов, унаследованных от QObject
• 1 защищенный слот, унаследованный от QWidget
• 2 защищенные переменные, унаследованные от QObject
• 1 защищенный тип, унаследованный от QPaintDevice

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

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

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

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

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

[slot] void QComboBox::clear()

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

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

[slot] void QComboBox::clearEditText()

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

QCompleter *QComboBox::completer() const

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

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

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

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

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

Переопределяет QWidget::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

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

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

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

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

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

Переопределяет QWidget::focusOutEvent().

[override 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 элемента.

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

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

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

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

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

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

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

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

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

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

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

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

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

void QComboBox::insertItem(int index, const QString &text, const QVariant &userData = QVariant())

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

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

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

void QComboBox::insertItem(int index, const QIcon &icon, const QString &text, const QVariant &userData = QVariant())

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

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

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

void QComboBox::insertItems(int index, const QStringList &list)

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

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

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

void QComboBox::insertSeparator(int index)

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

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

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

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

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

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

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

QAbstractItemDelegate *QComboBox::itemDelegate() const

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

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

QIcon QComboBox::itemIcon(int index) const

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

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

QString QComboBox::itemText(int index) const

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

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

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

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

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

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

QLineEdit *QComboBox::lineEdit() const

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

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

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

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

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

QAbstractItemModel *QComboBox::model() const

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

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

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

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

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

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

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

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

void QComboBox::removeItem(int index)

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

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

[override 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 &text)

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

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

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

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

void QComboBox::setItemDelegate(QAbstractItemDelegate *delegate)

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

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

Комбобокс принимает во владение line 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().

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

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

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