Qt QListWidget列表框用法详解

很多应用程序中需要以列表的形式向用户展示数据（资源），比如 Windows 操作系统会以列表的方式展示很多张桌面背景图（如图 1a) 所示），再比如很多音乐播放器中以列表的形式展示音乐资源，用户可以选择自己喜欢的音乐（如图 1b) 所示）。

图 1 常见的列表窗口

使用 Qt 框架开发 GUI 程序，如果需要以列表的方法展示数据，可以优先考虑用 QListWidget 类实现。

QListWidget列表框的创建

QListWidget 是 Qt 提供的控件类，专门用来创建列表。QListWidget 类的继承关系如下：

这里着重介绍一下 QListView 类，它也可以用来创建列表。对于初学者来说，我强烈建议先学习 QListWidget，它是“简易版”的 QListView，创建和使用列表的方式更简单、门槛更低，对初学者更友好。当然，QListWidget 只能创建结构简单的列表，如果要制作复杂的列表，应优先考虑 QListView，因为它的功能更强大，很多 QListWidget 难以实现的功能，QListView 都能实现。

通过实例化 QListWidget 类，可以很轻松地创建一个列表。QListWidget 类只提供了 1 个构造函数：

parent 参数用来指定新建列表的父窗口，该参数的默认值是 Q_NULLPTR，表示新建控件没有父窗口。

语法层面上分析，可以不为 QListWidget 列表指定父窗口，那么它将作为一个独立的窗口。但实际开发中，通常会为 QListWidget 列表指定一个父窗口（例如 QWidget 窗口），它将作为父窗口中的一个子控件，和窗口中的其它控件一起搭配使用。

QListWidgetItem列表项

QListWidget 列表控件可以显示多份数据，每份数据习惯称为列表项（简称项），每个列表项都是 QListWidgetItem 类的实例对象。也就是说，QListWidget 中有多少个列表项，就有多少个 QListWidgetItem 类对象。

默认情况下，QListWidget 中每个列表项独自占用一行，每个列表项中可以包含文字、图标等内容。实际开发中，我们还可以将指定的窗口或者控件放置到列表项中显示，例如 QWidget 窗口、QLabel 文本框、QPushButton 按钮、QLineEdit 输入框等。

借助 QListWidgetItem 类，可以轻松管理 QListWidget 中的每个列表项，包括：

• 借助 QListWidgetItemo 类提供的 setIcon()、setText() 等方法，可以轻松地指定每个列表项要包含的内容；
• 借助 QListWidgetItemo 类提供的 setFont()、setBackground() 等方法，可以轻松地设置每个列表项的外观（文字大小、列表项背景等）。

当然，QListWidgetItem 类还提供有很多其它的成员方法，这里不再一一罗列。

QListWidget列表框的使用

对于刚刚创建好的 QListWidget 类对象，不包含任何 QListWidgetItem 类对象，就是一个空列表。借助 QListWidget 类以及父类提供的属性和方法，我们可以对新建列表执行多种操作。

下表给大家罗列了一些 QListWidget 类常用的属性和方法：

QListWidget列表框的信号和槽

对于给定的 QlistWidget 列表，用户可以选中其中的一个或者某些列表项，甚至还可以修改列表项中的内容。QListWidget 类具有很多信号和槽信息，可以捕捉用户的很多动作，还可以针对用户的动作做出适当地响应。

下表给大家罗列了一些常用的信号和槽函数：

实例演示QListWidget列表框的用法

接下来，我们亲自制作一个 QListWidget 列表：

//main.cpp
#include <QApplication>
#include <QWidget>
#include <QListWidget>
#include <QLabel>
#include <QListWidgetItem>
using namespace std;

class QMyLabel:public QLabel{
    Q_OBJECT
public slots:
    void rsetText(QListWidgetItem *item);
};

void QMyLabel::rsetText(QListWidgetItem *item){
    this->setText(item->text());
}

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);
    //创建一个窗口，作为输入框的父窗口
    QWidget widget;
    //设置窗口的标题
    widget.setWindowTitle("QWidget窗口");
    widget.resize(500,500);
    QListWidget listWidget(&widget);
    listWidget.resize(500,400);
    listWidget.setFont(QFont("宋体",14));
    listWidget.addItem("城东书院");
    listWidget.addItem("https://www.cdsy.xyz");
    listWidget.addItem(new QListWidgetItem("Qt教程"));
    QMyLabel print;
    print.setText("选中内容");
    print.setParent(&widget);
    print.resize(500,100);
    print.move(0,400);
    print.setAlignment(Qt::AlignCenter);

    QObject::connect(&listWidget,&QListWidget::itemClicked,&print,&QMyLabel::rsetText);

    widget.show();
    return a.exec();
}
//QMyLabel类的定义应该放到 .h 文件中，本例中将其写到 main.cpp 中，程序最后需要添加 #include "当前源文件名.moc" 语句，否则无法通过编译。
#include "main.moc"

程序中，我们自定义了一个 QMyLabel 类，它继承自 QLabel 文本框类，因此 QMyLabel 也是一个文本框类。在 QMyLabel 类中，我们自定义了一个 rsetText() 槽函数。

程序的运行结果为：

图 2 QListMidget 控件实际应用

通过运行动画可以看到，我们将 QListMidget 和自定义的 QMyLabel 控件合理地分布在 QWidget 窗口上，通过为它们的信号和槽建立连接，使得当点击列表中的某个列表项时，文本框可以显示列表项中的文本内容。