C++ Qt 開發：ListWidget列表框組件

Qt 是一個跨平臺C++圖形界面開發庫，利用Qt可以快速開發跨平臺窗體應用程式，在Qt中我們可以通過拖拽的方式將不同組件放到指定的位置，實現圖形化開發極大的方便了開發效率，本章將重點介紹ListWidget列表框組件的常用方法及靈活運用。

QListWidget 是 Qt 中的一個列表框組件，用於顯示一列項目，並允許用戶進行選擇。每個項目可以包含一個圖標和文本，可以使用 QListWidgetItem 類來表示。ListWidget組件與TreeWidget有些相似，區別在於TreeWidget可以實現嵌套以及多欄位結構，而ListWidget則只能實現單欄位結構，該組件常用於顯示單條記錄，例如只顯示IP地址，用戶名等數據。

以下是 QListWidget 類的一些常用方法，說明和概述：

這隻是 QListWidget 類的一部分方法。你可以查閱官方文檔以獲取完整的方法列表，以及這些方法的詳細說明。

首先讀者可自行繪製好如下所示的UI界面，在界面中左側包含一個ListWidget列表框，右側包含各類用於控制組件的pushButton按鈕，如下圖所示；

1.1 初始化節點

如下代碼是一個槽函數 on_pushButton_init_clicked，主要作用是初始化一個 QListWidget 列表框，其中包含了一系列的 QListWidgetItem 項。

以下是概述：

1. 清空列表框： 首先，通過 ui->listWidget->clear() 清空了列表框，以確保在初始化之前移除已有的項。
2. 迴圈初始化項： 使用 for 迴圈，遍歷了 0 到 9 的數字，共初始化了 10 個項。
3. 創建 QListWidgetItem： 對於每個迴圈，通過 new QListWidgetItem() 創建了一個新的 QListWidgetItem 對象 aItem。
4. 設置文本標簽： 使用 setText 方法為 QListWidgetItem 設置了文本標簽，內容是形如 "192.168.1.x" 的字元串。
5. 設置圖標： 使用 setIcon 方法為每個項設置了相同的圖標，這裡使用了名為 "1.ico" 的圖標。
6. 設置為選中狀態： 使用 setCheckState 方法將每個項設為選中狀態，即顯示覆選框並勾選。
7. 設置不可編輯狀態： 使用 setFlags 方法將每個項設置為不可編輯狀態，只允許選擇和檢查操作。
8. 增加項到列表中： 使用 ui->listWidget->addItem(aItem) 將每個項添加到 QListWidget 中。

該槽函數用於初始化一個包含特定圖標、文本、覆選框等屬性的 QListWidget，方便用戶進行選擇和操作。

// 初始化列表
void MainWindow::on_pushButton_init_clicked()
{
    // 每一行是一個QListWidgetItem
    QListWidgetItem *aItem;

    // 設置ICON的圖標
    QIcon aIcon;
    aIcon.addFile(":/image/1.ico");

    // 清空列表框
    ui->listWidget->clear();

    // 迴圈初始化
    for(int x=0;x<10;x++)
    {
        // 填充字元串
        QString str = QString::asprintf("192.168.1.%d",x);

        // 新建一個項
        aItem = new QListWidgetItem();

        aItem->setText(str);                        // 設置文字標簽
        aItem->setIcon(aIcon);                      // 設置圖標
        aItem->setCheckState(Qt::Checked);          // 設為選中狀態
        aItem->setFlags(Qt::ItemIsSelectable |      // 設置為不可編輯狀態
                         Qt::ItemIsUserCheckable
                        |Qt::ItemIsEnabled);

        // 增加項到列表中
        ui->listWidget->addItem(aItem);
    }
}

運行效果如下圖；

1.2 設置編輯狀態

如下槽函數 on_pushButton_edit_clicked 的主要功能是將所有項設置為可編輯狀態。

以下是概述：

1. 獲取所有項數量： 使用 ui->listWidget->count() 獲取列表框中的項的數量。
2. 迴圈設置狀態： 使用 for 迴圈遍歷每個項，獲取當前項的句柄。
3. 設置為可編輯狀態： 使用 setFlags 方法將每個項的狀態設置為可編輯，包括可選擇、可編輯、可檢查、可啟用等狀態。

該槽函數的作用是將列表框中的所有項的狀態設置為可編輯，這樣用戶可以在運行時修改這些項的文本內容。

// 設置所有項設置為可編輯狀態
void MainWindow::on_pushButton_edit_clicked()
{
    int x,cnt;
    QListWidgetItem *aItem;

    // 獲取所有項數量
    cnt = ui->listWidget->count();
    for(x=0;x<cnt;x++)
    {
        // 得到當前選中項句柄
        aItem = ui->listWidget->item(x);

        // 設置狀態
        aItem->setFlags(Qt::ItemIsSelectable | Qt::ItemIsEditable
                        |Qt::ItemIsUserCheckable |Qt::ItemIsEnabled);
    }
}

運行效果如下圖；

1.3 全選與反選

如下槽函數 on_pushButton_selectall_clicked 的核心功能是實現一個全選按鈕，即將列表框中的所有項設置為選中狀態。

以下是概述：

1. 獲取總數： 使用 ui->listWidget->count() 獲取列表框中的項的總數。
2. 迴圈設置選中狀態： 使用 for 迴圈遍歷每個項，獲取每個項的指針。
3. 設置為選中狀態： 使用 setCheckState 方法將每個項的狀態設置為選中狀態，即勾選覆選框。

該槽函數的作用是實現一個全選按鈕，方便用戶一次性選中所有列表框中的項。

void MainWindow::on_pushButton_selectall_clicked()
{
    // 獲取總數
    int cnt = ui->listWidget->count();
    for(int x=0;x<cnt;x++)
    {
        // 獲取到項的指針
        QListWidgetItem *aItem = ui->listWidget->item(x);

        // 設置為選中
        aItem->setCheckState(Qt::Checked);
    }

}

如下槽函數 on_pushButton_noselect_clicked 的核心功能是實現一個全不選按鈕，即將列表框中的所有項設置為非選中狀態。

以下是概述：

1. 獲取總數： 使用 ui->listWidget->count() 獲取列表框中的項的總數。
2. 迴圈設置非選中狀態： 使用 for 迴圈遍歷每個項，獲取每個項的指針。
3. 設置為非選中狀態： 使用 setCheckState 方法將每個項的狀態設置為非選中狀態，即取消勾選覆選框。

該槽函數的作用是實現一個全不選按鈕，方便用戶一次性取消選中列表框中的所有項。

void MainWindow::on_pushButton_noselect_clicked()
{
    // 獲取總數
    int cnt = ui->listWidget->count();
    for(int x=0;x<cnt;x++)
    {
        // 獲取到一項指針
        QListWidgetItem *aItem = ui->listWidget->item(x);

        // 設置為非選中
        aItem->setCheckState(Qt::Unchecked);
    }
}

如下槽函數 on_pushButton_deselect_clicked 的核心功能是實現一個反選按鈕，即將列表框中的每個項的選中狀態進行反轉。

以下是概述：

1. 獲取總數： 使用 ui->listWidget->count() 獲取列表框中的項的總數。
2. 迴圈設置反選狀態： 使用 for 迴圈遍歷每個項，獲取每個項的指針。
3. 反選狀態： 使用 checkState 方法獲取每個項的當前選中狀態，如果是選中狀態 (Qt::Checked)，則設置為非選中狀態 (Qt::Unchecked)，反之亦然。

該槽函數的作用是實現一個反選按鈕，方便用戶一次性反轉列表框中的所有項的選中狀態。

void MainWindow::on_pushButton_deselect_clicked()
{
    int x,cnt;
    QListWidgetItem *aItem;

    // 獲取總數
    cnt = ui->listWidget->count();
    for(x=0;x<cnt;x++)
    {
        // 獲取到一項指針
        aItem = ui->listWidget->item(x);

        // 如果未選中則選中否則不選
        if(aItem->checkState() != Qt::Checked)
            aItem->setCheckState(Qt::Checked);
        else
            aItem->setCheckState(Qt::Unchecked);
    }
}

運行效果如下圖；

1.4 插入與追加

如下槽函數 on_pushButton_add_clicked 的核心功能是實現一個“增加一項”按鈕，即在列表框的尾部追加一個新的項。

以下是概述：

1. 創建圖標： 使用 QIcon 創建一個新的圖標，這裡使用了名為 "2.ico" 的圖標。
2. 創建新的 QListWidgetItem： 使用 new QListWidgetItem("新增的項目") 創建一個新的 QListWidgetItem 對象，設置了文本為 "新增的項目"。
3. 設置圖標和狀態： 使用 setIcon 設置項的圖標，setCheckState 設置項的選中狀態為選中，setFlags 設置項的狀態為可選擇、可檢查、可啟用。
4. 追加到控制項： 使用 ui->listWidget->addItem(aItem) 將新創建的項追加到列表框的尾部。

該槽函數的作用是在列表框的尾部追加一個新的項，該項包含指定的文本、圖標以及初始的選中狀態。

void MainWindow::on_pushButton_add_clicked()
{
    QIcon aIcon;
    aIcon.addFile(":/image/2.ico");

    QListWidgetItem *aItem = new QListWidgetItem("新增的項目");    // 增加項目名
    aItem->setIcon(aIcon);                                       // 設置圖標
    aItem->setCheckState(Qt::Checked);                           // 設置為選中
    aItem->setFlags(Qt::ItemIsSelectable |Qt::ItemIsUserCheckable |Qt::ItemIsEnabled);
    ui->listWidget->addItem(aItem);                              // 增加到控制項
}

如下槽函數 on_pushButton_ins_clicked 的核心功能是實現一個“指定位置插入一項”按鈕，即在列表框的指定位置插入一個新的項。

以下是概述：

1. 創建圖標： 使用 QIcon 創建一個新的圖標，這裡使用了名為 "3.ico" 的圖標。
2. 創建新的 QListWidgetItem： 使用 new QListWidgetItem("插入的數據") 創建一個新的 QListWidgetItem 對象，設置了文本為 "插入的數據"。
3. 設置圖標和狀態： 使用 setIcon 設置項的圖標，setCheckState 設置項的選中狀態為選中，setFlags 設置項的狀態為可選擇、可檢查、可啟用。
4. 在指定位置插入項： 使用 ui->listWidget->insertItem(ui->listWidget->currentRow(), aItem) 在當前行的上方插入一個新項。

該槽函數的作用是在列表框的指定位置插入一個新的項，該項包含指定的文本、圖標以及初始的選中狀態。

void MainWindow::on_pushButton_ins_clicked()
{
    QIcon aIcon;
    aIcon.addFile(":/image/3.ico");

    QListWidgetItem *aItem = new QListWidgetItem("插入的數據");
    aItem->setIcon(aIcon);
    aItem->setCheckState(Qt::Checked);
    aItem->setFlags(Qt::ItemIsSelectable |Qt::ItemIsUserCheckable |Qt::ItemIsEnabled);

    // 在當前行的上方插入一個項
    ui->listWidget->insertItem(ui->listWidget->currentRow(),aItem);
}

運行效果如下圖；

1.5 刪除列表一行

如下槽函數 on_pushButton_delete_clicked 的核心功能是實現一個“刪除選中項”按鈕，即刪除列表框中當前選中的項。

以下是概述：

1. 獲取當前行： 使用 ui->listWidget->currentRow() 獲取當前選中項的行索引。
2. 移除指定行的項： 使用 ui->listWidget->takeItem(row) 移除指定行的項，該方法返回被移除的項的指針，但不釋放空間。
3. 釋放空間： 使用 delete aItem 釋放被移除項的空間，確保不發生記憶體泄漏。

該槽函數的作用是刪除列表框中當前選中的項，同時釋放相應的記憶體空間。

void MainWindow::on_pushButton_delete_clicked()
{
    // 獲取當前行
    int row = ui->listWidget->currentRow();

    // 移除指定行的項,但不delete
    QListWidgetItem *aItem = ui->listWidget->takeItem(row);

    // 釋放空間
    delete aItem;
}

運行效果如下圖；

1.6 綁定右鍵菜單

在之前的內容中我們展示瞭如何給MainWindow主窗體增加右鍵菜單，本節我們將給ListWidget增加右鍵菜單，當用戶在ListWidget組件中的任意一個子項下右鍵，則讓其彈出這個菜單，並根據選擇提供不同的功能。

首先我們繪製兩個UI界面，並通過Tab組件將其分離開，為了方便演示我們需要手動增加列表項內容，增加方法是在ListWidget上面右鍵並選中編輯項目按鈕，此時就可以逐行向列表中錄入數據集。

為了增加菜單，我們首先需要在程式全局增加QAction其中每一個QAction則代表一個菜單選項指針，由於我們計劃增加三個菜單選項，則此處就保留三個全局菜單指針。

#include <QMenuBar>
#include <QMenu>
#include <QToolBar>
#include <iostream>

// 全局下設置增加刪除菜單
QAction *NewAction;
QAction *InsertAction;
QAction *DeleteAction;

首先以右鍵菜單演示為例，在MainWindow主函數中，首先通過創建頂部菜單並將其設置為隱藏屬性，接著通過Connect將每一個子菜單與Action進行連接，代碼如下所示；

MainWindow::MainWindow(QWidget *parent): QMainWindow(parent), ui(new Ui::MainWindow)
{
    ui->setupUi(this);

    // ----------------------------------------------------
    // 繪製部分
    // ----------------------------------------------------

    // 使用 customContextMenuRequested 信號則需要設置
    ui->listWidget->setContextMenuPolicy(Qt::CustomContextMenu);

    // 隱藏菜單欄上的右擊菜單
    this->setContextMenuPolicy(Qt::NoContextMenu);

    // 創建基礎頂部菜單
    QMenuBar *bar = menuBar();
    this->setMenuBar(bar);
    QMenu * fileMenu = bar->addMenu("菜單1");

    // 隱藏頂部菜單欄
    bar->setVisible(false);

    // 添加子菜單
     NewAction = fileMenu->addAction("增加IP地址");
     InsertAction = fileMenu->addAction("插入IP地址");
     DeleteAction = fileMenu->addAction("刪除IP地址");

    // 分別設置圖標
    NewAction->setIcon(QIcon(":/image/1.ico"));
    InsertAction->setIcon(QIcon(":/image/2.ico"));
    DeleteAction->setIcon(QIcon(":/image/3.ico"));

    // ----------------------------------------------------
    // 綁定槽函數
    // ----------------------------------------------------
    connect(NewAction,&QAction::triggered,this,[=](){
        std::cout << "new action" << std::endl;
    });

    connect(InsertAction,&QAction::triggered,this,[=](){
        std::cout << "insert action" << std::endl;
    });

    // 以刪除為例,演示如何刪除選中行
    connect(DeleteAction,&QAction::triggered,this,[=](){
        int row = ui->listWidget->currentRow();
        QListWidgetItem *aItem = ui->listWidget->takeItem(row);
        delete aItem;
        std::cout << "delete action" << std::endl;
    });
}

接著，當ListWidget右鍵被點擊時，則觸發on_listWidget_customContextMenuRequested槽函數，在該槽函數內我們通過new QMenu新建菜單，並通過addAction屬性將其插入到被點擊位置上，其代碼如下所示；

// 當listWidget被右鍵點擊時則觸發
void MainWindow::on_listWidget_customContextMenuRequested(const QPoint &pos)
{
    std::cout << "x pos = "<< pos.x() << "y pos = " << pos.y() << std::endl;
    Q_UNUSED(pos);

    // 新建Menu菜單
    QMenu *ptr = new QMenu(this);

    // 添加Actions創建菜單項
    ptr->addAction(NewAction);
    ptr->addAction(InsertAction);
    // 添加一個分割線
    ptr->addSeparator();
    ptr->addAction(DeleteAction);

    // 在滑鼠游標位置顯示右鍵快捷菜單
    ptr->exec(QCursor::pos());

    // 手工創建的指針必須手工刪除
    delete ptr;
}

運行後讀者可自行在特定行上點擊右鍵，此時則會彈出菜單欄，如下圖所示；

接著來看下圖標組的設置與綁定右鍵菜單的實現方式，第二種方式的綁定與第一種一致，唯一的區別僅僅只是顯示設置上的不同，如下是第二種方法的顯示配置代碼；

// 第二個ListWidget_使用圖標方式展示
ui->listWidget_ico->setViewMode(QListView::IconMode);

// 每一行是一個QListWidgetItem
QListWidgetItem *aItem;

// 設置ICON的圖標
QIcon aIcon;
aIcon.addFile(":/image/1.ico");

ui->listWidget_ico->clear();
for(int x=0;x<10;x++)
{
    QString str = QString::asprintf("admin_%d",x);
    aItem = new QListWidgetItem();           // 新建一個項

    aItem->setText(str);                     // 設置文字標簽
    aItem->setIcon(aIcon);                   // 設置圖標
    //aItem->setCheckState(Qt::Checked);     // 設為選中狀態
    aItem->setFlags(Qt::ItemIsSelectable |   // 設置為不可編輯狀態
                     Qt::ItemIsUserCheckable
                    |Qt::ItemIsEnabled);

    ui->listWidget_ico->addItem(aItem);       // 增加項
}

使用時只需要按照相同的方式綁定菜單即可，運行效果如下圖所示；

完整案例下載