[QT_008]Qt学习之QListWidgetItem详解
本文转自：《Qt编程指南》 作者：奇先生
Qt编程指南，Qt新手教程，Qt Programming Guide
8.1.2 QListWidgetItem
QListWidgetItem 专门用于表示列表控件 QListWidget 的数据条目，注意： QListWidgetItem 是一个纯数据类，不是控件，没有基类，也就没有信号和槽函数。QListWidgetItem 可以直接用数据流 QDataStream 读写。
QListWidgetItem 不单单有字符串，还可以有自己的图标、复选框等特性，列表控件会根据条目对象的丰富特性来呈现数据并进行交互操作。
（1）首先来看看列表控件条目的构造函数：
QListWidgetItem(QListWidget * parent = 0, int type = Type)
QListWidgetItem(const QString & text, QListWidget * parent = 0, int type = Type)
QListWidgetItem(const QIcon & icon, const QString & text, QListWidget * parent = 0, int type = Type)那第三个构造函数的参数来讲，icon 是条目显示的图标，text 是条目文本，parent 是条目隶属的列表控件，type 是条目的自定义类型。
如果在构造函数指定了条目隶属的列表控件，那么这个条目会自动添加到列表控件末尾，而不需要调用列表控件的 add*() 和 insert*()函数，比如：
new QListWidgetItem(tr("Hazel"), listWidget);只需要上面一句代码，"Hazel" 条目就自动显示在列表控件 listWidget 里面了，只要指定所隶属的列表控件，新建的条目自动添加并显示在末尾。
（2）条目的复制方式，有三个函数可以实现：
QListWidgetItem(const QListWidgetItem & other) //复制构造函数
QListWidgetItem & operator=(const QListWidgetItem & other) // = 赋值函数
virtual QListWidgetItem * clone() const //克隆函数复制构造函数和 "=" 赋值函数 函数原理是一样的，它们除了 type() 和 listWidget() 函数指定的两个数据不复制，其他的数据都复制。type() 是条目的自定义类型，listWidget() 是该条目所隶属的列表控件。
而克隆函数 clone() 会精确复制所有数据，如果原条目隶属某个列表控件，克隆出来的也会自动隶属该列表控件，自定义条目类型也一样。
顺便说一下列表条目的比较函数：
virtual bool operator<(const QListWidgetItem & other) const只有一个小于号函数，是比较列表条目文本的字典序先后关系，没有等于号函数和大于号函数，如果确实用到条目文本比较，建议直接用 QString 变量进行比较。
（3）QListWidgetItem 的功能函数与内部数据
QListWidgetItem 绝大部分的功能函数都是围绕内部数据处理的，QListWidgetItem 内部的数据大致分为两类：第一类是以数据角色形式管理的通用数据，这些数据自动参与 QDataStream 数据流的读写；第二类是非通用数据，不参与数据流读写，与 QListWidgetItem 和 QListWidget 自身特性有关。
● 第一类：QListWidgetItem 的通用数据
通用数据是以数据角色与数据变量一一对应的形式存储管理，比如设置文本 setText()、设置图标 setIcon() 等函数，其本质都是根据各自的角色调用通用设置数据的函数：
virtual void setData(int role, const QVariant & value)也可以根据角色来获取各个数据变量：
virtual QVariant data(int role) const查看列表控件源码文件：
C:\Qt\Qt5.4.0\5.4\Src\qtbase\src\widgets\itemviews\qlistwidget.h
可以看到关于文本变量的函数 text() 和 setText() 源代码：
inline QString text() const
{ return data(Qt::DisplayRole).toString(); }
inline void QListWidgetItem::setText(const QString &atext)
{ setData(Qt::DisplayRole, atext); }关于 QListWidgetItem 内部通用数据的获取和设置函数、数据角色列表如下：
| 获取函数 | 设置函数 | 数据角色 | 描述 |
| text() | setText(const QString &text) | Qt::DisplayRole | 条目显示的文本。 |
| icon() | setIcon(const QIcon &icon) | Qt::DecorationRole | 条目显示的图标。 |
| statusTip() | setStatusTip(const QString &statusTip) | Qt::StatusTipRole | 如果主界面有状态栏，鼠标悬停在该条目上时显示该状态信息到状态栏。 |
| toolTip() | setToolTip(const QString &toolTip) | Qt::ToolTipRole | 鼠标悬停在该条目上时显示的工具提示信息。 |
| whatsThis() | setWhatsThis(const QString &whatsThis) | Qt::WhatsThisRole | 如果主界面窗口标题栏有？帮助按钮，点击帮助按钮再点击该条目会显示该帮助信息。 |
| font() | setFont(const QFont &font) | Qt::FontRole | 显示条目文本用的字体。 |
| textAlignment() | setTextAlignment(int alignment) | Qt::TextAlignmentRole | 文本的对齐方式。 |
| backgroundColor() | setBackgroundColor(const QColor &color) | Qt::BackgroundColorRole | 文本背景色。 |
| textColor() | setTextColor(const QColor &color) | Qt::TextColorRole | 文字颜色。 |
| background() | setBackground(const QBrush &brush) | Qt::BackgroundRole | 条目的背景画刷。 |
| foreground() | setForeground(const QBrush &brush) | Qt::ForegroundRole | 条目的前景画刷。 |
| checkState() | setCheckState(Qt::CheckState state) | Qt::CheckStateRole | 条目自带的复选框选中状态，可以是三态复选框。 |
| sizeHint() | setSizeHint(const QSize &size) | Qt::SizeHintRole | 条目显示的建议尺寸。 |
QListWidgetItem 可以直接用数据流 QDataStream 读写，涉及到读写的内部数据就是上表所列举的以角色形式表述的数据，QListWidgetItem 通过两个外部全局运算符重载函数支持 QDataStream 数据流读写：
QDataStream &operator<<(QDataStream &out, const QListWidgetItem &item)
QDataStream &operator>>(QDataStream &in, QListWidgetItem &item)使用运算符的形式比较方便，当然也可以用 QListWidgetItem 内部的读写函数：
void QListWidgetItem::read(QDataStream & in)
void QListWidgetItem::write(QDataStream & out) constQListWidgetItem 内部采用私有的 QVector 向量存储通用数据的 role 和 value 对：
QVector<QWidgetItemData> values;条目通用数据的读写就是读写私有向量 values，其中 QWidgetItemData 内部包含 role 和 value 成员变量：
class QWidgetItemData
{
public:
inline QWidgetItemData() : role(-1) {}
inline QWidgetItemData(int r, QVariant v) : role(r), value(v) {}
int role;
QVariant value;
inline bool operator==(const QWidgetItemData &other) const { return role == other.role && value == other.value; }
};在 8.2 节表格控件的单元格条目也是类似的私有向量存储 role 和 value 对。
● 第二类：QListWidgetItem 的非通用数据
条目自定义类型：
int QListWidgetItem::type() const这个条目类型只能在构造函数指定，指定之后不能修改，默认值为 QListWidgetItem::Type （数值 0），如果程序员希望自己区分列表控件条目的类型，那么可以自己定义大于 QListWidgetItem::UserType （数值 1000）的类型值，一般用在 QListWidgetItem 派生类里面。
条目所隶属的列表控件：
QListWidget * QListWidgetItem::listWidget() const条目自身不能修改所隶属的列表控件，要通过列表控件的删除函数 QListWidget::takeItem(int row) 才能解除隶属关系。
列表条目本身的选中状态（与复选框无关，是用户在列表控件点击条目的高亮选中状态）：
void QListWidgetItem::setSelected(bool select)
bool QListWidgetItem::isSelected() const一般是用户在列表控件图形界面点击哪个条目，哪个条目就处于高亮选中状态，这里可以用条目自身的函数设置高亮选中状态。
条目在列表控件里面显示或者隐藏：
void QListWidgetItem::setHidden(bool hide)
bool QListWidgetItem::isHidden() const条目的特性标志：
void QListWidgetItem::setFlags(Qt::ItemFlags flags)
Qt::ItemFlags QListWidgetItem::flags() constflags 会决定条目的工作特性，比如是否有三态复选框，是否在用户双击该条目时开启文本编辑器等等，Qt::ItemFlags 枚举值见下面表格：
| Qt::ItemFlags 枚举常量 | 数值 | 描述 |
| Qt::NoItemFlags | 0 | 不设置任何特性，条目会处于完全的不可用状态。 |
| Qt::ItemIsSelectable | 1 | 条目本身可以被高亮选中。 |
| Qt::ItemIsEditable | 2 | 条目可以被编辑，比如用户双击条目时自动启用文本编辑器。 |
| Qt::ItemIsDragEnabled | 4 | 条目可以被拖拽出去。 |
| Qt::ItemIsDropEnabled | 8 | 条目可以作为拖拽的目的地。 |
| Qt::ItemIsUserCheckable | 16 | 条目可以有复选框，用户能勾选复选框。 |
| Qt::ItemIsEnabled | 32 | 条目处于可用状态。 |
| Qt::ItemIsTristate | 64 | 条目的复选框可以有三种勾选状态：选中、非选中、部分选中。 |
| Qt::ItemNeverHasChildren | 128 | 条目不能有子条目（指树形控件）。 |
上表中的 Qt::ItemFlags 也适用于后面 8.2 节的表格控件条目和 8.3 节的树形控件条目，表格条目和树形条目也都有一样的条目标志位设置函数，功能与本节列表条目一样，参数也一样。
列表控件条目默认的特性标志为同时启用四个：
Qt::ItemIsSelectable | Qt::ItemIsUserCheckable | Qt::ItemIsEnabled | Qt::ItemIsDragEnabled按照默认标志位，列表条目是可以有复选框进行勾选的，调用 QListWidgetItem::setCheckState() 函数可以让列表条目的复选框显示出来。
如果要设置三态复选框，可以使用下面的代码：
item->setFlags( (item->flags()) | Qt::ItemIsTristate ); //开启三态复选
item->setCheckState( Qt::Unchecked ); //显示复选框如果希望用户在双击条目时，自动开启条目文本的编辑器，可以用下面代码：
item->setFlags( (item->flags()) | Qt::ItemIsEditable ); //双击条目会自动 开启文本编辑器因为可以设置条目的 Qt::ItemIsEditable 标志位，所以列表控件 QListWidget 的一对持续编辑器函数 openPersistentEditor() 和 closePersistentEditor() 一般不需要手动调用，直接设置条目自身的可编辑标志位就行了。
对于启用可编辑标志位的条目，如果希望通过代码开启条目的编辑，可以调用列表控件的 editItem() 函数来实现，而不需要使用一对开关持续编辑器函数那么麻烦：
void QListWidget::editItem(QListWidgetItem * item)这里说明一下：列表条目本身是可以存储复选框的勾选状态数值，而条目显示的复选框是由列表控 件绘制并提供，列表条目自身不是控件，也不包含子控件。类似地，列表控件根据 Qt::ItemIsEditable 标志位检查是否需要为条目提供文本编辑器。
旨在为数千万中国开发者提供一个无缝且高效的云端环境，以支持学习、使用和贡献开源项目。
更多推荐
3
0- 0
已为社区贡献13条内容
所有评论(0)