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

lyshark發表於2023-12-18
C++QT元件

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

QListWidget 是 Qt 中的一個列表框元件，用於顯示一列專案，並允許使用者進行選擇。每個專案可以包含一個圖示和文字，可以使用 QListWidgetItem 類來表示。ListWidget元件與TreeWidget有些相似，區別在於TreeWidget可以實現巢狀以及多欄位結構，而ListWidget則只能實現單欄位結構，該元件常用於顯示單條記錄，例如只顯示IP地址，使用者名稱等資料。

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

方法 描述
addItem(QListWidgetItem *item) 向列表中新增一個專案。
addItems(const QStringList &labels) 向列表中新增多個專案。
count() 返回列表中的專案數量。
currentItem() 返回當前選擇的專案。
item(int row) 返回給定行索引的專案。
itemAt(const QPoint &p) 返回給定座標處的專案。
takeItem(int row) 從列表中刪除並返回給定行索引的專案。
clear() 刪除列表中的所有專案。
clearSelection() 取消選擇所有專案。
removeItemWidget(QListWidgetItem *item) 從列表中刪除一個專案並釋放與之關聯的任何小部件。
scrollToItem(QListWidgetItem *item, QAbstractItemView::ScrollHint hint = EnsureVisible) 滾動列表以確保給定專案可見。
sortItems(Qt::SortOrder order = Qt::AscendingOrder) 對列表中的專案進行排序。
itemClicked(QListWidgetItem *item) 專案被點選時發出的訊號。
itemDoubleClicked(QListWidgetItem *item) 專案被雙擊時發出的訊號。
setItemWidget(QListWidgetItem *item, QWidget *widget) 在給定專案的位置設定小部件。
setIconSize(const QSize &size) 設定專案圖示的大小。
setCurrentRow(int row) 設定當前選擇的行。
setCurrentItem(QListWidgetItem *item) 設定當前選擇的專案。
selectedItems() 返回當前選擇的所有專案。
selectedIndexes() 返回當前選擇的所有專案的模型索引。
setSelectionMode(QAbstractItemView::SelectionMode mode) 設定選擇模式，例如 SingleSelection 或 MultiSelection。

這只是 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);       // 增加項
}

使用時只需要按照相同的方式繫結選單即可，執行效果如下圖所示；

完整案例下載

相關文章