Класс QComboBox

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

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

Типы

Свойства

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

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

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

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

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

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

Сигналы

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

Статические общедоступные члены

• 5 статических общедоступных членов, унаследованных от QWidget
• 9 статических общедоступных членов, унаследованных от QObject

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

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

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

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

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

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

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

enum QComboBox::InsertPolicy

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

enum QComboBox::SizeAdjustPolicy

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

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

QComboBox::QComboBox(QWidget *parent = nullptr)

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

[virtual] QComboBox::~QComboBox()

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

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

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

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

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

[signal] void QComboBox::activated(const QString &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())

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

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

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

void QComboBox::addItems(const QStringList &texts)

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

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

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

[slot] void QComboBox::clear()

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

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

[slot] void QComboBox::clearEditText()

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

QCompleter *QComboBox::completer() const

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Предупреждение: Не следует использовать один и тот же экземпляр делегата для нескольких виджетов 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().