QListWidgetItem的函数介绍

Qt版本

6.8.0

枚举

QListWidgetItem::ItemType 是 Qt 中用于标识 QListWidgetItem 类型的枚举，便于自定义和区分不同类型的列表项。
它的定义如下：

---

1. 标准定义

enum QListWidgetItem::ItemType {Type = 0,         // 默认类型UserType = 1000   // 用户自定义类型的起始值
};

---

2. 说明

• Type

  • 值为 0
  • 表示标准的、普通的列表项类型。
  • 绝大多数情况下，直接使用即可。

• UserType

  • 值为 1000
  • 用户自定义类型的起始值。
  • 如果你需要区分不同的自定义项类型，可以用 UserType 及其以上的值。

---

3. 自定义类型的用法

你可以通过继承 QListWidgetItem 或直接传递 type 参数来创建自定义类型的项。例如：

// 创建一个自定义类型的项
QListWidgetItem *item = new QListWidgetItem("自定义项", listWidget, QListWidgetItem::UserType + 1);// 判断类型
if (item->type() == QListWidgetItem::UserType + 1) {// 这是自定义类型
}

---

4. 典型场景

• 当你需要在同一个 QListWidget 里放多种不同类型的项，并且希望能区分它们时，可以用 type() 和 ItemType。
• 例如：普通项、分组项、特殊功能项等。

---

公共函数

1. QListWidgetItem(QListWidget *parent = nullptr, int type = Type)

• 作用：创建一个空的列表项，可指定父 QListWidget 和类型。
• 参数：
  • parent：所属的 QListWidget（可选）
  • type：项类型（默认 Type）
• 返回值：构造函数，无返回值
• 示例：

  QListWidgetItem *item = new QListWidgetItem(listWidget);
  

---

2. QListWidgetItem(const QString &text, QListWidget *parent = nullptr, int type = Type)

• 作用：创建带文本的列表项。
• 参数：
  • text：显示文本
  • parent：所属 QListWidget（可选）
  • type：项类型（可选）
• 返回值：构造函数
• 示例：

  QListWidgetItem *item = new QListWidgetItem("Hello", listWidget);
  

---

3. QListWidgetItem(const QIcon &icon, const QString &text, QListWidget *parent = nullptr, int type = Type)

• 作用：创建带图标和文本的列表项。
• 参数：
  • icon：图标
  • text：文本
  • parent：所属 QListWidget（可选）
  • type：项类型（可选）
• 返回值：构造函数
• 示例：

  QListWidgetItem *item = new QListWidgetItem(QIcon(":/icon.png"), "带图标", listWidget);
  

---

4. QListWidgetItem(const QListWidgetItem &other)

• 作用：拷贝构造函数，复制一个列表项。
• 参数：other：要复制的项
• 返回值：构造函数
• 示例：

  QListWidgetItem copyItem(*item);
  

---

5. virtual ~QListWidgetItem()

• 作用：析构函数，释放资源。
• 参数：无
• 返回值：无
• 示例：自动调用，无需手动使用。

---

6. QBrush background() const

• 作用：获取项的背景画刷。
• 参数：无
• 返回值：QBrush
• 示例：

  QBrush bg = item->background();
  

---

7. Qt::CheckState checkState() const

• 作用：获取复选框状态。
• 参数：无
• 返回值：Qt::CheckState（Unchecked, PartiallyChecked, Checked）
• 示例：

  Qt::CheckState state = item->checkState();
  

---

8. virtual QListWidgetItem *clone() const

• 作用：克隆当前项，返回新对象指针。
• 参数：无
• 返回值：QListWidgetItem*
• 示例：

  QListWidgetItem *newItem = item->clone();
  

---

9. virtual QVariant data(int role) const

• 作用：获取指定角色的数据。
• 参数：role：数据角色（如 DisplayRole, UserRole 等）
• 返回值：QVariant
• 示例：

  QVariant v = item->data(Qt::DisplayRole);
  

---

10. Qt::ItemFlags flags() const

• 作用：获取项的标志（可选、可编辑等）。
• 参数：无
• 返回值：Qt::ItemFlags
• 示例：

  Qt::ItemFlags f = item->flags();
  

---

11. QFont font() const

• 作用：获取项的字体。
• 参数：无
• 返回值：QFont
• 示例：

  QFont font = item->font();
  

---

12. QBrush foreground() const

• 作用：获取项的前景画刷（通常是文本颜色）。
• 参数：无
• 返回值：QBrush
• 示例：

  QBrush fg = item->foreground();
  

---

13. QIcon icon() const

• 作用：获取项的图标。
• 参数：无
• 返回值：QIcon
• 示例：

  QIcon icon = item->icon();
  

---

14. bool isHidden() const

• 作用：判断项是否隐藏。
• 参数：无
• 返回值：bool
• 示例：

  bool hidden = item->isHidden();
  

---

15. bool isSelected() const

• 作用：判断项是否被选中。
• 参数：无
• 返回值：bool
• 示例：

  bool selected = item->isSelected();
  

---

16. QListWidget *listWidget() const

• 作用：获取所属的 QListWidget。
• 参数：无
• 返回值：QListWidget*
• 示例：

  QListWidget *w = item->listWidget();
  

---

17. virtual void read(QDataStream &in)

• 作用：从数据流读取项的数据（反序列化）。
• 参数：in：QDataStream
• 返回值：无
• 示例：

  QDataStream in(&file);
  item->read(in);
  

---

18. void setBackground(const QBrush &brush)

• 作用：设置背景画刷。
• 参数：brush：QBrush
• 返回值：无
• 示例：

  item->setBackground(QBrush(Qt::yellow));
  

---

19. void setCheckState(Qt::CheckState state)

• 作用：设置复选框状态。
• 参数：state：Qt::CheckState
• 返回值：无
• 示例：

  item->setCheckState(Qt::Checked);
  

---

20. virtual void setData(int role, const QVariant &value)

• 作用：为指定角色设置数据。
• 参数：
  • role：数据角色
  • value：数据
• 返回值：无
• 示例：

  item->setData(Qt::UserRole, 123);
  

---

21. void setFlags(Qt::ItemFlags flags)

• 作用：设置项的标志（可选、可编辑等）。
• 参数：flags：Qt::ItemFlags
• 返回值：无
• 示例：

  item->setFlags(Qt::ItemIsSelectable | Qt::ItemIsEditable);
  

---

22. void setFont(const QFont &font)

• 作用：设置字体。
• 参数：font：QFont
• 返回值：无
• 示例：

  item->setFont(QFont("Arial", 12));
  

---

23. void setForeground(const QBrush &brush)

• 作用：设置前景画刷（文本颜色）。
• 参数：brush：QBrush
• 返回值：无
• 示例：

  item->setForeground(QBrush(Qt::red));
  

---

24. void setHidden(bool hide)

• 作用：设置项是否隐藏。
• 参数：hide：bool
• 返回值：无
• 示例：

  item->setHidden(true);
  

---

25. void setIcon(const QIcon &icon)

• 作用：设置图标。
• 参数：icon：QIcon
• 返回值：无
• 示例：

  item->setIcon(QIcon(":/icon.png"));
  

---

26. void setSelected(bool select)

• 作用：设置项是否选中。
• 参数：select：bool
• 返回值：无
• 示例：

  item->setSelected(true);
  

---

27. void setSizeHint(const QSize &size)

• 作用：设置项的建议显示大小。
• 参数：size：QSize
• 返回值：无
• 示例：

  item->setSizeHint(QSize(100, 30));
  

---

28. void setStatusTip(const QString &statusTip)

• 作用：设置状态栏提示文本。
• 参数：statusTip：QString
• 返回值：无
• 示例：

  item->setStatusTip("状态栏提示");
  

---

29. void setText(const QString &text)

• 作用：设置显示文本。
• 参数：text：QString
• 返回值：无
• 示例：

  item->setText("新文本");
  

---

30. (since 6.4) void setTextAlignment(Qt::Alignment alignment)

• 作用：设置文本对齐方式。
• 参数：alignment：Qt::Alignment
• 返回值：无
• 示例：

  item->setTextAlignment(Qt::AlignCenter);
  

---

31. void setToolTip(const QString &toolTip)

• 作用：设置悬浮提示文本。
• 参数：toolTip：QString
• 返回值：无
• 示例：

  item->setToolTip("悬浮提示");
  

---

32. void setWhatsThis(const QString &whatsThis)

• 作用：设置 What’s This 帮助文本。
• 参数：whatsThis：QString
• 返回值：无
• 示例：

  item->setWhatsThis("帮助信息");
  

---

33. QSize sizeHint() const

• 作用：获取建议显示大小。
• 参数：无
• 返回值：QSize
• 示例：

  QSize sz = item->sizeHint();
  

---

34. QString statusTip() const

• 作用：获取状态栏提示文本。
• 参数：无
• 返回值：QString
• 示例：

  QString tip = item->statusTip();
  

---

35. QString text() const

• 作用：获取显示文本。
• 参数：无
• 返回值：QString
• 示例：

  QString t = item->text();
  

---

36. int textAlignment() const

• 作用：获取文本对齐方式。
• 参数：无
• 返回值：int（Qt::Alignment）
• 示例：

  int align = item->textAlignment();
  

---

37. QString toolTip() const

• 作用：获取悬浮提示文本。
• 参数：无
• 返回值：QString
• 示例：

  QString tip = item->toolTip();
  

---

38. int type() const

• 作用：获取项类型（用于区分自定义子类）。
• 参数：无
• 返回值：int
• 示例：

  int t = item->type();
  

---

39. QString whatsThis() const

• 作用：获取 What’s This 帮助文本。
• 参数：无
• 返回值：QString
• 示例：

  QString help = item->whatsThis();
  

---

40. virtual void write(QDataStream &out) const

• 作用：将项的数据写入数据流（序列化）。
• 参数：out：QDataStream
• 返回值：无
• 示例：

  QDataStream out(&file);
  item->write(out);
  

---

41. virtual bool operator<(const QListWidgetItem &other) const

• 作用：比较两个项的大小（排序用）。
• 参数：other：另一个项
• 返回值：bool
• 示例：

  bool less = (*item1 < *item2);
  

---

42. QListWidgetItem & operator=(const QListWidgetItem &other)

• 作用：赋值运算符，复制另一个项的内容。
• 参数：other：另一个项
• 返回值：自身引用
• 示例：

  *item1 = *item2;