Qt的技巧笔记(二)：ComboBox 下拉组合框组件

QComboBox控件简介

​ Qt是一个跨平台的C++图形界面开发库，利用Qt可以快速开发跨平台窗体应用程序，在Qt中我们可以通过拖拽的方式将不同组件放到指定的位置，实现图形化开发极大的方便了开发效率，本章将重点介绍ComboBox下拉组合框组件的常用方法及灵活运用。QComboBox适用于以下场景：

• 选项较少：提供直观的交互体验；
• 自定义样式：支持丰富的样式定制，适合美观界面需求。
• 下拉菜单：如语言选择，地区选择和单位选择等。

​ 在Qt中，ComboBox(组合框)是一种常用的用户界面控件， 它提供了一个下拉列表，允许用户从预设的选项中选择一个。该组件提供了一种比较的方便方式让用户从预定义的选项中进行选择，一般来说ComboBox 会以按钮的形式在界面上，用户点击按钮后，会弹出一个下拉列表，其中包含预定义的选项。当然ComboBox 不仅局限于选择，也允许用户手动输入内容。 下面QComboBox类的一些常用方法的说明的，下列按照表格总结如下：

QComboBox的方法接口	描述
QComboBox(QWidget *parent = nullptr)	构造函数，创建一个组件对象。
addItem(const QString &text, const QVariant &userData = QVariant())	向组件添加一个项，可以附带用户数据。
addItems(const QStringList &texts)	向组件添加多个项，使用字符串列表。 `
insertItem(int index, const QString &text, const QVariant &userData = QVariant())	在指定索引处插入一个项。
insertItems(int index, const QStringList &texts)	在指定索引处插入多个项。
removeItem(int index)	移除指定索引处的项。
clear()	清除组件中的所有项。
setCurrentIndex(int index)	设置组件当前选择的项的索引。
currentText()	返回当前组件中显示的文本。
currentIndex()	返回当前组件中选择的项的索引。
count()	返回组件中项的总数。
itemText(int index)	返回指定索引处项的文本。
itemData(int index, int role = Qt::UserRole)	返回指定索引处项的用户数据。
setItemText(int index, const QString &text)	设置指定索引处项的文本。
setItemData(int index, const QVariant &value, int role = Qt::UserRole)	为指定索引处项设置额外的数据。
clearEditText()	清除组件的编辑文本。
setEditable(bool editable)	设置组件是否可编辑。如果可编辑，用户可以手动输入文本。
setMaxCount(int max)	设置组件中显示的最大项数。如果超过该数目，将出现垂直滚动条。
setMinimumContentsLength(int characters)	设置组件的最小内容长度，以便显示完整的项。
setModel(QAbstractItemModel *model)	设置组件的数据模型。通过模型，可以更灵活地管理组件中的项。
view()	返回组件的视图，允许对视图进行定制。
clear()	清除组件中的所有项。
showPopup()	打开组件的下拉列表。
hidePopup()	隐藏组件的下拉列表。
activated(int index)	信号，当用户选择组件中的项时发出。
currentIndexChanged(int index)	信号，当组件中的当前项发生变化时发出。
setEditable(bool editable)	设置是否允许用户输入自定义文本
setStyleSheet(const QString &styleSheet)	设置样式表

上述这些方法提供了对ComboBox进行配置、管理和与之交互的灵活性。你可以根据具体的应用需求使用这些方法，使ComboBox在你的Qt应用程序中按照期望的方式工作。

核心信号	说明
activated(int) 及 activated(const QString &text)	当用户选择了一个选项时发出这个时候相当于用户点开下拉框，并且鼠标划过某个选项，此时还没有确认做出选择。
currentIndexChanged(int)及currentIndexChanged(const QString &text)	当前选项改变发出，此时用户已经明确的选择一个选项。用户操作或者通过程序操作都触发这个信号。
editTextChanged(const QString & text)	当编辑框中的文本改变时发生（editable为true时有效）

QComboBox的核心功能包括：

• 添加项目：使用addItem()方法添加文本项目，或使用addItem(const QIcon &icon, const QString &text)添加带图标的项目。
• 设置默认值：通过setCurrentText()或setCurrentIndex()设置默认选中项。
• 获取选中值：使用currentText()或currentIndex()获取用户选择

QComboBox基本用法

• 创建QComboBox对象

  QComboBox *comboBox = new QComboBox(parent);
  

• QComboBox添加项目

  comboBox->addItem("选项1");
  comboBox->addItem("选项2");
  comboBox->addItem("选项3");
  

• QComboBox设置默认值(选项)

  comboBox->setCurrentText("选项2"); // 设置默认选中"选项2"
  // 或者
  comboBox->setCurrentIndex(1); // 设置默认选中索引为1的项目
  

• QComboBox处理用户选择(信号槽连接)

  connect(comboBox, &QComboBox::currentTextChanged, [](const QString &text) {
      qDebug() << "选中的值为：" << text;
  });
  

QComboBox高级用法

• QComboBox自适应项目

  // 添加带图标的项目
  comboBox->addItem(QIcon(":/images/icon1.png"), "选项1");
  comboBox->addItem(QIcon(":/images/icon2.png"), "选项2");
  // 设置样式
  comboBox->setStyleSheet(R"(
      QComboBox {
          border: 1px solid #ccc;
          padding: 5px;
          min-width: 120px;
      }
      QComboBox::drop-down {
          border-left: 1px solid #ccc;
      }
  )");
  

• QComboBox动态添加项目

  comboBox->addItem("新选项");
  

• QComboBox获取所有项目

  for (int i = 0; i < comboBox->count(); ++i) {
      qDebug() << "项目" << i << ":" << comboBox->itemText(i);
  }
  

• QComboBox的QSS美化

  基本样式

  QComboBox {
      background-color: #ffffff;
      border: 1px solid #ccc;
      border-radius: 4px;
      padding: 5px;
      min-width: 120px;
  }
  

  下拉箭头样式

  QComboBox::drop-down {
      border-left: 1px solid #ccc;
      width: 20px;
      height: 20px;
  }
  QComboBox::down-arrow {
      image: url(:/images/down_arrow.png);
  }
  

  项目样式

  QComboBox QAbstractItemView {
      background-color: #ffffff;
      border: 1px solid #ccc;
      border-radius: 4px;
      padding: 5px;
  }
  QComboBox QAbstractItemView::item {
      padding: 5px;
  }
  QComboBox QAbstractItemView::item:hover {
      background-color: #f0f0f0;
  }
  QComboBox QAbstractItemView::item:selected {
      background-color: #e0e0e0;
  }
  

自定义QComboBox示例

以下是一个带复选框的下拉列表控件实现示例：

#ifndef CCHECKCOMBOX_H
#define CCHECKCOMBOX_H

#include <QtWidgets/QComboBox>
#include <QtWidgets/QAbstractItemView>

class CCheckCombox : public QComboBox {
    Q_OBJECT
public:
    explicit CCheckCombox(QWidget* parent = nullptr);
    void appendItem(const QString& text, bool bChecked);
    QList<QString> getSelectedItems() const;

protected:
    void mousePressEvent(QMouseEvent* event) override;

private:
    void updateIndexStatus(int index);

signals:
    void checkedStateChange(int index, bool bChecked);
};

#endif // CCHECKCOMBOX_H

#include "ccheckcombox.h"
#include <QIcon>
#include <QMouseEvent>
#include <QDebug>

CCheckCombox::CCheckCombox(QWidget* parent) : QComboBox(parent) {}

void CCheckCombox::appendItem(const QString& text, bool bChecked) {
    QIcon icon(bChecked ? ":/images/check.png" : ":/images/uncheck.png");
    addItem(icon, text);
    setItemData(count() - 1, bChecked, Qt::UserRole);
}

void CCheckCombox::updateIndexStatus(int index) {
    bool bChecked = !itemData(index, Qt::UserRole).toBool();
    QIcon icon(bChecked ? ":/images/check.png" : ":/images/uncheck.png");
    setItemIcon(index, icon);
    setItemData(index, bChecked, Qt::UserRole);
    emit checkedStateChange(index, bChecked);
}

void CCheckCombox::mousePressEvent(QMouseEvent* event) {
    int x = event->pos().x();
    int iconWidth = iconSize().width();
    if (x <= iconWidth) {
        int index = currentIndex();
        updateIndexStatus(index);
    } else {
        QComboBox::mousePressEvent(event);
    }
}

QList<QString> CCheckCombox::getSelectedItems() const {
    QList<QString> selectedItems;
    for (int i = 0; i < count(); ++i) {
        if (itemData(i, Qt::UserRole).toBool()) {
            selectedItems.append(itemText(i));
        }
    }
    return selectedItems;
}