QComboBox Class

QComboBox小部件是一个组合的按钮和弹出列表。

Header	#include < QComboBox>
qmake	QT += widgets
Inherits	QWidget
Inherited By	QFontComboBox

详细说明

QComboBox提供了一种以占用最小屏幕空间的方式向用户呈现选项列表的方法。

组合框是显示当前项目的选择小部件，可以弹出可选择项目的列表。组合框可以编辑，允许用户修改列表中的每个项目。

组合框可以包含pixmap和字符串；insertItem() 和setItemText() 函数可以适当地重载。对于可编辑的组合框，提供了函数clearEditText() ，以清除显示的字符串而不更改组合框的内容。

如果组合框的当前项更改，将发出三个信号：currentIndexChanged() 、currentTextChanged() 和activated() 。currentIndexChanged() 和currentTextChanged() 始终发出，无论更改是通过编程方式还是通过用户交互进行的，而activated() 仅在更改是由用户交互引起时发出。当用户高亮显示组合框弹出列表中的项目时，将发出highlighted() 信号。这三个信号都有两个版本，一个是QString参数，另一个是int参数。如果用户选择或高亮显示一个pixmap，则只会发出int信号。每当更改可编辑组合框的文本时，都会发出editTextChanged() 信号。

当用户在一个可编辑的组合框中输入一个新字符串时，小部件可以插入它，也可以不插入它，它可以在几个位置插入它。默认策略为insertbottom，但可以使用setInsertPolicy() 对此进行更改。

可以使用QValidator将输入约束到可编辑的组合框；请参阅setValidator() 。默认情况下，接受任何输入。

例如，可以使用insert函数insertItem() 和insertItems() 填充组合框。可以使用setItemText() 更改项。可以使用removeItem() 删除项目，也可以使用clear() 删除所有项目。当前项的文本由currentText() 返回，编号项的文本由text() 返回。可以使用setCurrentIndex() 设置当前项。combobox中的项数由count() 返回；可以使用setMaxCount() 设置最大项数。可以使用setEditable() 进行编辑。对于可编辑的组合框，可以使用setCompleter() 设置自动完成，并且用户是否可以添加重复项是使用setDuplicatesEnabled() 设置的。

QComboBox使用模型/视图框架作为其弹出列表并存储其项。默认情况下，QStandardItemModel存储这些项，QListView子类显示popuplist。您可以直接访问模型和视图（使用model() 和view() ），但是QComboBox还提供了设置和获取项目数据的函数（例如setItemData() 和itemText() ）。也可以设置新的模型和视图（使用setModel() 和setView() ）。对于组合框标签中的文本和图标，使用模型中具有Qt::DisplayRole和Qt::DecorationRole的数据。请注意，不能更改view() 的SelectionMode，例如，使用setSelectionMode() 。

公共类型

enum InsertPolicy

此枚举指定当用户输入新字符串时QComboBox应执行的操作。

Constant	Value	Description
NoInsert	0	字符串不会插入到组合框中。
InsertAtTop	1	字符串将作为组合框中的第一项插入。
InsertAtCurrent	2	当前项将替换为字符串。
InsertAtBottom	3	字符串将插入组合框中最后一项之后。
InsertAfterCurrent	4	字符串插入在组合框中的当前项之后。
InsertBeforeCurrent	5	字符串插入到组合框中当前项的前面。
InsertAlphabetically	6	字符串按字母顺序插入组合框中。

enum SizeAdjustPolicy

此枚举指定添加新内容或内容更改时QComboBox的大小提示应如何调整。

Constant	Value	Description
AdjustToContents	0	组合框将始终根据内容进行调整
AdjustToContentsOnFirstShow	1	组合框在第一次显示时将根据其内容进行调整。
AdjustToMinimumContentsLengthWithIcon	AdjustToContentsOnFirstShow + 2	组合框将调整为图标的最小内容长度加上空间。出于性能原因，请在大型模型上使用此策略。

属性

1. count: const int 组合框中的项数
   默认情况下，对于空组合框，此属性的值为0。

   Access functions:

   • int count() const

2. currentData: const QVariant 当前项的数据
   默认情况下，对于空组合框或未设置当前项的组合框，此属性包含无效的QVariant。

   Access functions:

   • QVariant currentData(int role = Qt::UserRole) const

3. currentIndex: int 当前项的索引
   插入或删除项目时，当前索引可能会更改。
   默认情况下，对于空组合框或未设置当前项的组合框，此属性的值为-1。

   Access functions:

   • int currentIndex() const
   1. void setCurrentIndex(int index)

   Notifier signal:

   • void currentIndexChanged(int index)

4. currentText: QString 当前文本
   如果组合框是可编辑的，则当前文本是行编辑显示的值。否则，如果组合框为空或未设置当前项，则为当前项的值或空字符串。

   如果组合框是可编辑的，设置器 setCurrentText() 只调用setEditText() 。否则，如果列表中有匹配的文本，currentIndex将设置为相应的索引。

   Access functions:

   • QString currentText() const
   1. void setCurrentText(const QString &text)

   Notifier signal:

   • void currentTextChanged(const QString &text)

5. duplicatesEnabled: bool 是否允许输入重复项
   请注意，总是可以通过编程方式将重复项插入到组合框中。
   默认情况下，此属性为false（不允许重复）。

   Access functions:

   • bool duplicatesEnabled() const
   1. void setDuplicatesEnabled(bool enable)

6. editable: bool 是否允许编辑

   默认情况下，此属性为false。编辑的效果取决于插入策略。

   注意：禁用可编辑状态时，将删除验证程序和完成程序。
   Access functions:

   • bool isEditable() const
   1. void setEditable(bool editable)

7. Access functions:

8. frame: bool 是否使用框架绘制自身
   如果启用（默认设置），组合框将在一个框架内绘制自身，否则组合框将在没有任何框架的情况下绘制自身。

   Access functions:

   • bool hasFrame() const
   1. void setFrame(bool)

9. iconSize: QSize 显示的图标的大小
   除非显式设置，否则返回当前样式的默认值。此大小是图标可以具有的最大尺寸；较小尺寸的图标不会按比例放大。

   Access functions:

   • QSize iconSize() const
   1. void setIconSize(const QSize &size)

10. insertPolicy: InsertPolicy 用于确定用户插入的项应显示在组合框中的位置的策略
    默认值为insertbottom，表示新项目将出现在项目列表的底部。

    Access functions:

    • QComboBox::InsertPolicy insertPolicy() const
    1. void setInsertPolicy(QComboBox::InsertPolicy policy)

11. maxCount: int 组合框中允许的最大项数
    注意：如果将最大数量设置为小于组合框中当前项目的数量，则多余的项目将被截断。如果您在组合框上设置了外部模型，这也适用。
    默认情况下，此属性的值是从可用的最高有符号整数（通常为2147483647）引申的。

    Access functions:

    • int maxCount() const
    1. void setMaxCount(int max)

12. maxVisibleItems: int 组合框屏幕上允许显示的最大大小（以项为单位）
    默认情况下，此属性的值为10。
    注意：对于QStyle::SH_ComboBox_Popup（如Mac样式或Gtk+样式）返回true的样式中的不可编辑组合框，忽略此属性。

    Access functions:

    • int maxVisibleItems() const
    1. void setMaxVisibleItems(int maxItems)

13. minimumContentsLength: int 组合框中应包含的最小字符数
    默认值为0。
    如果此属性设置为正值，则minimumSizeHint() 和sizeHint() 会将其考虑在内。

    Access functions:

    • int minimumContentsLength() const
    1. void setMinimumContentsLength(int characters)

14. modelColumn: int 模型中可见的列
    如果在填充组合框之前设置，弹出视图将不受影响，并将显示第一列（使用此属性的默认值）。
    默认情况下，此属性的值为0。

    Access functions:

    • int modelColumn() const
    1. void setModelColumn(int visibleColumn)

15. placeholderText: QString 设置未设置有效索引时显示的文本占位符
    设置无效索引时，将显示占位符文本。在下拉列表中无法访问文本。在添加项之前调用此函数时，将显示占位符文本，否则，如果要显示占位符文本，必须以编程方式调用setCurrentIndex（-1）。设置空占位符文本以重置设置。
    当QComboBox可编辑时，请改用QLineEdit:：setPlaceholderText() 。

    Access functions:

    • QString placeholderText() const
    1. void setPlaceholderText(const QString &placeholderText)

16. sizeAdjustPolicy: SizeAdjustPolicy 内容更改时组合框大小如何更改的策略
    默认值为AdjustToContentsOnFirstShow。

    Access functions:

    • QComboBox::SizeAdjustPolicy sizeAdjustPolicy() const
    1. void setSizeAdjustPolicy(QComboBox::SizeAdjustPolicy policy)

公共函数

构造和析构

1. QComboBox(QWidget *parent = nullptr)
2. virtual ~QComboBox()

属性相关

1. int count() const
2. QVariant currentData(int role = Qt::UserRole) const
3. int currentIndex() const
4. void setCurrentIndex(int index)
5. QString currentText() const
6. void setCurrentText(const QString &text)
7. bool duplicatesEnabled() const
8. void setDuplicatesEnabled(bool enable)
9. bool isEditable() const
10. void setEditable(bool editable)
11. bool hasFrame() const
12. void setFrame(bool)
13. QSize iconSize() const
14. void setIconSize(const QSize &size)
15. QComboBox::InsertPolicy insertPolicy() const
16. void setInsertPolicy(QComboBox::InsertPolicy policy)
17. int maxCount() const
18. void setMaxCount(int max)
19. int maxVisibleItems() const
20. void setMaxVisibleItems(int maxItems)
21. int minimumContentsLength() const
22. void setMinimumContentsLength(int characters)
23. int modelColumn() const
24. void setModelColumn(int visibleColumn)
25. QString placeholderText() const
26. void setPlaceholderText(const QString &placeholderText)
27. QComboBox::SizeAdjustPolicy sizeAdjustPolicy() const
28. void setSizeAdjustPolicy(QComboBox::SizeAdjustPolicy policy)

增、删、改、查

1. void addItem(const QString &text, const QVariant &userData = QVariant())
2. void addItem(const QIcon &icon, const QString &text, const QVariant &userData = QVariant())
3. void addItems(const QStringList &texts)
4. void insertItem(int index, const QString &text, const QVariant &userData = QVariant())
5. void insertItem(int index, const QIcon &icon, const QString &text, const QVariant &userData = QVariant())
6. void insertItems(int index, const QStringList &list)
7. void insertSeparator(int index)
8. void removeItem(int index)
9. QVariant itemData(int index, int role = Qt::UserRole) const
10. void setItemData(int index, const QVariant &value, int role = Qt::UserRole)
11. QIcon itemIcon(int index) const
12. void setItemIcon(int index, const QIcon &icon)
13. QString itemText(int index) const
14. void setItemText(int index, const QString &text)
15. int findData(const QVariant &data, int role = Qt::UserRole, Qt::MatchFlags flags = static_cast< Qt::MatchFlags >(Qt::MatchExactly|Qt::MatchCaseSensitive) ) const
16. int findText(const QString &text, Qt::MatchFlags flags = Qt::MatchExactly|Qt::MatchCaseSensitive) const

特殊

1. QCompleter * completer() const 自动完成组合框文本输入的完成器
2. void setCompleter(QCompleter *completer)
3. virtual void hidePopup() 隐藏弹出列表
4. virtual void showPopup() 显示弹出列表
5. const QValidator * validator() const 验证器
6. void setValidator(const QValidator *validator)
7. QLineEdit * lineEdit() const 编辑框
8. void setLineEdit(QLineEdit *edit)

模型视图部分

1. QAbstractItemModel * model() const
2. void setModel(QAbstractItemModel *model)
3. QModelIndex rootModelIndex() const
4. void setRootModelIndex(const QModelIndex &index)
5. QAbstractItemView * view() const
6. void setView(QAbstractItemView *itemView)
7. QAbstractItemDelegate * itemDelegate() const
8. void setItemDelegate(QAbstractItemDelegate *delegate)

重写的公共函数

1. virtual bool event(QEvent *event) override
2. virtual QVariant inputMethodQuery(Qt::InputMethodQuery query) const override
3. virtual QSize minimumSizeHint() const override
4. virtual QSize sizeHint() const override

公共槽

1. void clear() 清除组合框，删除所有项
2. void clearEditText() 清除行编辑的内容
3. void setEditText(const QString &text) 在编辑中设置文本
4. void setCurrentIndex(int index) 属性相关
5. void setCurrentText(const QString &text) 属性相关

信号

1. void activated(int index)
2. void currentIndexChanged(int index)
3. void currentTextChanged(const QString &text)
4. void editTextChanged(const QString &text)
5. void highlighted(int index)
6. void textActivated(const QString &text)
7. void textHighlighted(const QString &text)

受保护的函数

1. void initStyleOption(QStyleOptionComboBox *option) const

重写的受保护的函数

1. virtual void changeEvent(QEvent *e) override
2. virtual void contextMenuEvent(QContextMenuEvent *e) override
3. virtual void focusInEvent(QFocusEvent *e) override
4. virtual void focusOutEvent(QFocusEvent *e) override
5. virtual void hideEvent(QHideEvent *e) override
6. virtual void inputMethodEvent(QInputMethodEvent *e) override
7. virtual void keyPressEvent(QKeyEvent *e) override
8. virtual void keyReleaseEvent(QKeyEvent *e) override
9. virtual void mousePressEvent(QMouseEvent *e) override
10. virtual void mouseReleaseEvent(QMouseEvent *e) override
11. virtual void paintEvent(QPaintEvent *e) override
12. virtual void resizeEvent(QResizeEvent *e) override
13. virtual void showEvent(QShowEvent *e) override
14. virtual void wheelEvent(QWheelEvent *e) override

小案例

#include <QtWidgets>

int main(int argc, char *argv[])
{
    
    QApplication app(argc,argv);
    app.setApplicationName ("QComboBox");
//    app.setStyleSheet ("QLabel{background:green}");
    QWidget w;
    w.resize (300,50);
    QFrame frame1;
    QFrame frame2;
    QFrame frame3;
    QGridLayout mainLayout(&w);

    QComboBox widget1;
    QComboBox widget2;
    QComboBox widget3;

    QCommonStyle cs;

    for(int i=0;  i < 20; i++){
    
        widget1.addItem (cs.standardIcon ((QStyle::StandardPixmap)i),         QString::number (i));
        widget2.addItem (cs.standardIcon ((QStyle::StandardPixmap)(i+20)),QString::number (i+20));
        widget3.addItem (cs.standardIcon ((QStyle::StandardPixmap)(i+40)),QString::number (i+40));
    }
// 设置图标的最大尺寸
    widget1.setIconSize (QSize(32,32));
    widget2.setIconSize (QSize(32,32));
    widget3.setIconSize (QSize(32,32));

    QLabel label1("0-19");
    QLabel label2("20-39");
    QLabel label3("40-59");

    label1.setAlignment (Qt::AlignCenter);
    label2.setAlignment (Qt::AlignCenter);
    label3.setAlignment (Qt::AlignCenter);

    frame1.setFrameShape (QFrame::Panel);
    frame2.setFrameShape (QFrame::Panel);
    frame3.setFrameShape (QFrame::Panel);

    QVBoxLayout *V1 = new QVBoxLayout(&frame1);
    QVBoxLayout *V2 = new QVBoxLayout(&frame2);
    QVBoxLayout *V3 = new QVBoxLayout(&frame3);

    V1->addWidget (&label1);
    V1->addWidget (&widget1);
    V2->addWidget (&label2);
    V2->addWidget (&widget2);
    V3->addWidget (&label3);
    V3->addWidget (&widget3);

    // 布局加入，此时部件的父类是mainLayout
    mainLayout.addWidget (&frame1,0,1);
    mainLayout.addWidget (&frame2,0,2);
    mainLayout.addWidget (&frame3,0,3);

    w.show ();

    app.exec();
    return 0;
}