QTableWidgetItem函数的介绍

前言

Qt版本:6.8.0

作用

QTableWidgetItem 是 Qt 框架中用于表示 QTableWidget 单元格内容的类。它是 QTableWidget 的“数据单元”，每个单元格都由一个 QTableWidgetItem 对象来管理其内容和属性。

---

主要作用

1. 存储和显示单元格数据

   • 可以存储文本、数字、图标、复选框等内容。
   • 控制单元格的显示内容（如 setText()、setIcon()）。

2. 管理单元格的属性

   • 可以设置和获取单元格的字体、颜色、对齐方式、背景色、前景色等。
   • 例如：setFont()、setBackground()、setForeground()、setTextAlignment()。

3. 支持单元格的编辑和交互

   • 可以设置单元格是否可编辑、可选中、可拖拽等（通过 setFlags()）。
   • 支持复选框（setCheckState()）和只读等状态。

4. 存储自定义数据

   • 可以通过 setData() 和 data() 存储和获取自定义数据（如 Qt::UserRole）。

5. 与 QTableWidget 结合使用

   • QTableWidget 通过 setItem(row, column, item) 将 QTableWidgetItem 放入表格的指定单元格。
   • 通过 item(row, column) 获取指定单元格的 QTableWidgetItem。

---

典型应用场景

• 显示和编辑表格中的每个单元格内容
• 设置单元格的样式（如高亮、加粗、颜色区分等）
• 在单元格中显示图标、复选框
• 存储与单元格相关的自定义数据（如ID、状态等）

---

枚举

QTableWidgetItem::ItemType 是 Qt 中用于标识 QTableWidgetItem 类型的枚举，便于自定义和区分不同类型的表格项。
它的定义和用途与 QListWidgetItem::ItemType 类似。

---

1. 标准定义

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

---

2. 说明

• Type

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

• UserType

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

---

3. 自定义类型的用法

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

// 创建一个自定义类型的表格项
QTableWidgetItem *item = new QTableWidgetItem("自定义项", QTableWidgetItem::UserType + 1);

// 判断类型
if (item->type() == QTableWidgetItem::UserType + 1) {
    // 这是自定义类型
}

---

4. 典型场景

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

---

公共函数

1. QTableWidgetItem(int type = Type)

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

  QTableWidgetItem *item = new QTableWidgetItem();
  

---

2. QTableWidgetItem(const QString &text, int type = Type)

• 作用：创建带文本的表格项。
• 参数：text（显示文本），type（项类型，默认 Type）
• 返回值：构造函数
• 示例：

  QTableWidgetItem *item = new QTableWidgetItem("Hello");
  

---

3. QTableWidgetItem(const QIcon &icon, const QString &text, int type = Type)

• 作用：创建带图标和文本的表格项。
• 参数：icon（图标），text（文本），type（项类型，默认 Type）
• 返回值：构造函数
• 示例：

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

---

4. QTableWidgetItem(const QTableWidgetItem &other)

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

  QTableWidgetItem copyItem(*item);
  

---

5. virtual ~QTableWidgetItem()

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

---

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 QTableWidgetItem *clone() const

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

  QTableWidgetItem *newItem = item->clone();
  

---

9. int column() const

• 作用：获取该项所在的列号。
• 参数：无
• 返回值：int
• 示例：

  int col = item->column();
  

---

10. virtual QVariant data(int role) const

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

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

---

11. Qt::ItemFlags flags() const

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

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

---

12. QFont font() const

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

  QFont font = item->font();
  

---

13. QBrush foreground() const

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

  QBrush fg = item->foreground();
  

---

14. QIcon icon() const

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

  QIcon icon = item->icon();
  

---

15. bool isSelected() const

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

  bool selected = item->isSelected();
  

---

16. virtual void read(QDataStream &in)

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

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

---

17. int row() const

• 作用：获取该项所在的行号。
• 参数：无
• 返回值：int
• 示例：

  int row = item->row();
  

---

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 setIcon(const QIcon &icon)

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

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

---

25. void setSelected(bool select)

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

  item->setSelected(true);
  

---

26. void setSizeHint(const QSize &size)

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

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

---

27. void setStatusTip(const QString &statusTip)

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

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

---

28. void setText(const QString &text)

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

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

---

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

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

  item->setTextAlignment(Qt::AlignCenter);
  

---

30. void setToolTip(const QString &toolTip)

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

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

---

31. void setWhatsThis(const QString &whatsThis)

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

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

---

32. QSize sizeHint() const

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

  QSize sz = item->sizeHint();
  

---

33. QString statusTip() const

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

  QString tip = item->statusTip();
  

---

34. QTableWidget *tableWidget() const

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

  QTableWidget *table = item->tableWidget();
  

---

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 QTableWidgetItem &other) const

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

  bool less = (*item1 < *item2);
  

---

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

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

  *item1 = *item2;