Класс QComboBox

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

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

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

Свойства

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

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

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

• 211 публичных функций, унаследованных от QWidget
• 31 публичная функция, унаследованная от 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. Обратите внимание, что вы не можете изменить SelectionMode представления view(), например, используя setSelectionMode().

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

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

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

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

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

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

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

connect(comboBox, static_cast<void(QComboBox::*)(const QString &)>(&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)

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

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

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

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

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

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

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

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

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

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

connect(comboBox, static_cast<void(QComboBox::*)(const QString &)>(&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.

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

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

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

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

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

connect(comboBox, static_cast<void(QComboBox::*)(const QString &)>(&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 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().

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

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

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

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

QLineEdit *QComboBox::lineEdit() const

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

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

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

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

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

[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 для списка выпадающего меню. combobox принимает владение делегатом.

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

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

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

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

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

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

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

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

void QComboBox::setLineEdit(QLineEdit *edit)

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

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

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

void QComboBox::setModel(QAbstractItemModel *model)

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

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

void QComboBox::setRootModelIndex(const QModelIndex &index)

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

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

void QComboBox::setValidator(const QValidator *validator)

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

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

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

void QComboBox::setView(QAbstractItemView *itemView)

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

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

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

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

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

[virtual] void QComboBox::showPopup()

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

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

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

[virtual] QSize QComboBox::sizeHint() const

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

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

const QValidator *QComboBox::validator() const

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

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

QAbstractItemView *QComboBox::view() const

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

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

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

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