目录
引言
一、基本概念和特性
- 项目（Items）：QListWidget通过QListWidgetItem管理每个列表项。每个项目都可以包含文本、图标、工具提示等。
- 选择模式：QListWidget支持多种选择模式，如单选、多选等，可以通过设setSelectionMode来改变。
- 排序：列表项可以根据需要进行排序，通过调用
sortItems方法，并可选地提供一个自定义的比较函数。 - 拖拽与放置：QListWidget支持拖拽与放置功能，允许用户通过拖拽重新排序列表项或在不同列表间移动项。
- 委托（Delegates）：虽然 QListWidget较少直接使用委托，但了解委托机制可以帮助理解如何在更复杂的场景下自定义列表项的显示和编辑。
二、基本用法
2.1 创建和初始化
在 Qt 应用程序中，你可以通过代码或 Qt Designer 来创建QListWidget。以下是通过代码创建并初始化QListWidget的示例：
#include <QListWidget>
#include <QApplication>
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
QListWidget listWidget;
listWidget.addItem("Item 1");
listWidget.addItem("Item 2");
listWidget.addItem("Item 3");
listWidget.show();
return app.exec();
}在这个例子中，我们首先包含了必要的头文件QListWidget和QApplication。然后，在main函数中创建了一个QApplication对象和一个QListWidget对象。接着，我们通过调用addItem方法向列表中添加了几个项。最后，调用show方法显示列表窗口，并启动事件循环。
2.2 添加和删除项
除了addItem方法外，QListWidget还提供了其他几种添加项的方法，如addItems（添加项列表）、insertItem（在指定位置插入项）、insertItems（在指定位置插入项列表）。删除项可以使用removeItemWidget（根据项的小部件删除）、takeItem（根据索引删除并返回项）。
// 添加多个项
QStringList items = {"Item 4", "Item 5", "Item 6"};
listWidget.addItems(items);
// 在特定位置插入项
listWidget.insertItem(1, "New Item");
// 删除项
QListWidgetItem* item = listWidget.takeItem(0); // 删除第一个项并返回
delete item; // 释放内存2.3 选择和遍历项
你可以通过selectedItems方法获取当前所有被选中的项，或者通过currentItem方法获取当前被选中的项（如果有的话）。遍历所有项可以通过count方法和索引访问器完成。
// 获取所有选中的项
QList<QListWidgetItem*> selected = listWidget.selectedItems();
for (QListWidgetItem* item : selected) {
qDebug() << item->text();
}
// 遍历所有项
for (int i = 0; i < listWidget.count(); ++i) {
QListWidgetItem* item = listWidget.item(i);
qDebug() << item->text();
}三、信号与槽
QListWidget发出多种信号，允许开发者在列表项被选中、添加、删除等事件发生时执行特定的操作。这些信号包括itemClicked、itemDoubleClicked、itemSelectionChanged等。
3.1 itemClicked
列表项单击信号连接对应的槽函数
connect(&listWidget, &QListWidget::itemClicked, [](QListWidgetItem* item){
qDebug() << "Clicked:" << item->text();
}); 3.2 itemDoubleClicked
列表项双击信号连接对应的槽函数
connect(&listWidget, &QListWidget::itemDoubleClicked, [](QListWidgetItem* item){
qDebug() << "Double Clicked:" << item->text();
}); 3.3 itemSelectionChanged
列表项选择改变信号连接对应的槽函数
connect(&listWidget, &QListWidget::itemSelectionChanged, [&](){
qDebug() << "Selection changed.";
QList<QListWidgetItem*> selectedItems = listWidget.selectedItems();
qDebug() << "Selected items count:" << selectedItems.size();
});四、自定义项
QListWidget允许你通过QListWidgetItem的子类或设置项的图标、文本等来自定义列表项的外观。
QListWidgetItem* item = new QListWidgetItem(QIcon(":/path/to/icon.png"), "Custom Item");
listWidget.addItem(item);
// 或者设置已存在项的图标和文本
item->setIcon(QIcon(":/path/to/another_icon.png"));
item->setText("Updated Item");五、排序和查找
虽然QListWidget没有直接提供排序方法，但你可以通过移除所有项，然后根据需要对项进行排序后重新添加来实现排序功能。查找项通常通过遍历所有项并比较它们的文本或数据来完成。
六、代码示例
下面是一个包含QListWidget控件的完整Qt Widgets应用程序示例代码，该代码展示了如何设置QListWidget的基础功能，包括添加项、设置图标、启用多选、处理点击项的槽函数以及基本的样式设置。
6.1 头文件
自定义了一个类名为MainWindow继承自QWidget
class MainWindow : public QWidget {
Q_OBJECT
public:
MainWindow(QWidget *parent = nullptr);
private slots:
void onItemClicked(QListWidgetItem *item);
void addNewItem();
void selectAllItems();
void deselectAllItems();
private:
QListWidget *listWidget;
QLineEdit *lineEdit;
};6.2 源文件
MainWindow::MainWindow(QWidget *parent = nullptr) : QWidget(parent) {
auto *layout = new QVBoxLayout(this);
// 创建 QListWidget 并设置其属性
listWidget = new QListWidget(this);
listWidget->setSelectionMode(QListWidget::MultiSelection); // 启用多选
// 添加带图标的项
QListWidgetItem *item1 = new QListWidgetItem(QIcon(":/path/to/icon1.png"), "项目 1", listWidget);
QListWidgetItem *item2 = new QListWidgetItem(QIcon(":/path/to/icon2.png"), "项目 2", listWidget);
listWidget->addItem(item1);
listWidget->addItem(item2);
// 设置样式
QString styleSheet = R"(
QListWidget {
background-color: #f0f0f0; /* 背景色 */
border: 1px solid #ccc; /* 边框 */
border-radius: 5px; /* 边框圆角 */
padding: 5px; /* 内边距 */
}
QListWidget::item {
height: 40px; /* 列表项高度 */
}
QListWidget::item:selected {
background-color: #3399ff; /* 选中项背景色 */
color: white; /* 选中项文字颜色 */
}
)";
listWidget->setStyleSheet(styleSheet);
// 连接点击项的槽函数
connect(listWidget, &QListWidget::itemClicked, this, &MainWindow::onItemClicked);
// 添加一个按钮作为示例（非必需）
QPushButton *button = new QPushButton("添加新项目", this);
connect(button, &QPushButton::clicked, this, &MainWindow::addNewItem);
// 添加一个lineEdit控件作为项目名字输入
lineEdit = new QLineEdit(this);
lineEdit->setPlaceholderText("请输入项目名称...");
// 设置一个widget包含按钮与lineEdit控件
QWidget *wid = new QWidget(this);
QHBoxLayout *hlayout = new QHBoxLayout(wid);
hlayout->addWidget(lineEdit);
hlayout->addWidget(button);
// 添加全选和反选按钮
QPushButton *selectAllButton = new QPushButton("全选", this);
QPushButton *deselectAllButton = new QPushButton("反选", this);
connect(selectAllButton, &QPushButton::clicked, this, &MainWindow::selectAllItems);
connect(deselectAllButton, &QPushButton::clicked, this, &MainWindow::deselectAllItems);
// 设置一个widget包含两个按钮
QWidget *wid1 = new QWidget(this);
QHBoxLayout *hlayout1 = new QHBoxLayout(wid1);
hlayout1->addWidget(deselectAllButton);
hlayout1->addWidget(selectAllButton);
// 将控件添加到布局中
layout->addWidget(listWidget);
layout->addWidget(wid);
layout->addWidget(wid1);
setLayout(layout);
}
void MainWindow::onItemClicked(QListWidgetItem *item) {
if (item) {
qDebug() << "点击了项：" << item->text();
}
}
void MainWindow::addNewItem() {
// 示例：动态添加一个新项目
QString newItemText;
if(lineEdit->text() == "")
{
newItemText = QString("新项目 %1").arg(listWidget->count() + 1);
}
else
{
newItemText = lineEdit->text();
}
new QListWidgetItem(QIcon(":/path/to/default_icon.png"), newItemText, listWidget);
lineEdit->setText("");
}
void MainWindow::selectAllItems() {
for (int i = 0; i < listWidget->count(); ++i) {
QListWidgetItem *item = listWidget->item(i);
if (item) {
item->setSelected(true);
}
}
}
void MainWindow::deselectAllItems() {
for (int i = 0; i < listWidget->count(); ++i) {
QListWidgetItem *item = listWidget->item(i);
if (item) {
item->setSelected(false);
}
}
}6.3 主函数文件
#include "widget.h" // 更换成自己头文件名称
#include <QApplication>
int main(int argc, char *argv[]) {
QApplication app(argc, argv);
MainWindow window;
window.resize(400, 300);
window.show();
return app.exec();
}
6.4 实现效果
6.5 代码解析
结语
以上就是关于Qt中QListWidget控件的全部介绍，如有不足与缺陷之处，欢迎评论区留言！！！
