QT6 源（157）模型视图架构里的列表窗体视图 QListWidget ：属性，成员函数，槽函数与信号函数，以及源代码带注释。

原创已于 2025-07-07 01:26:15 修改 · 90 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#qt

于 2025-07-06 17:56:05 首次发布

QT6.2.4源码阅读(五章--？) 专栏收录该内容

37 篇文章

订阅专栏

（1）本类的继承关系如下 ：

在这里插入图片描述

++ 在本篇之前，已经阅读与注释了抽象的模型基类，列表模型，表格模型，抽象的视图基类，表格视图，表格窗体，列表模型。所以，对于此列表窗体，就不详细注释了。只对新的知识点添加注释与测试。
++ 开始本类的属性阅读 ：

在这里插入图片描述

++ 另一个属性 ：

在这里插入图片描述

++测试一下 ：

在这里插入图片描述

++ 补充：排序，升序降序都可以的，有成员函数支持排序操作 ：

在这里插入图片描述

（2）接着开始本类的 public 成员函数的学习，跟二维表窗体 QTableWidget 类似的管理条目的成员函数，就不再注释了：

在这里插入图片描述

++既然有了上面的函数，还有必要使用选择模型么？

在这里插入图片描述

++至此，本类的 public 权限的成员函数，就学习完毕了。

（3）接着学习本类的槽函数与信号函数 ：

在这里插入图片描述

++信号函数 ：

在这里插入图片描述

++测试结果 ：

在这里插入图片描述

（4）本类的源代码定义于头文件 qlistwidget . h ：

class QListWidgetPrivate;

/*
The QListWidget class provides an item-based list widget.

QListWidget是一个方便的类,它提供的列表视图类似于 QListView提供的列表视图，
但具有用于添加和删除项目的经典基于项目的界面。
QListWidget 使用内部模型来管理列表中的每个QListWidgetltem。
为了实现更灵活的列表视图小部件，请使用带有标准模型的QListView类。
列表小部件的构建方式与其他小部件相同:
     QListWidget *listWidget = new QListWidget(this);

列表控件的`selectionMode()、属性决定了列表中同时可被选中的项数量，以及是否支持创建复杂的项选择。
这可以通过`setSelectionMode()'函数进行设置。
添加项目到列表有两种方式:它们可以以列表控件作为其父控件来构建，
或者可以没有父控件，然后在稍后阶段添加到列表中。
如果在构建项目时列表控件已经存在，那么第一种方法使用起来更为便捷:
     new QListWidgetItem(tr("Oak"), listWidget);

如果您需要在列表中的特定位置插入一个新项，
那么该新项应被构造为没有父项控件。然后应使用函数将其放置在列表中。
列表控件将取得该项的拥有权。
     QListWidgetItem * newItem = new QListWidgetItem;
     newItem->setText(itemText);
     listWidget->insertItem(row, newItem);

对于多个项目，可以使用insertltems()。列表中的项目数量可以通过count()函数找到。
要从列表中移除项目，请使用takeltem()。

列表中的当前项可以通过、currentltem()函数找到，并通过`setCurrentltem()、函数进行更改。
用户还可以通过键盘导航或点击不同的项来更改当前项。
当当前项发生变化时，会发出`currentltemChanged()、信号，其中包含新的当前项以及之前处于当前状态的项。


*/

class Q_WIDGETS_EXPORT QListWidget : public QListView
{
    Q_OBJECT

    //This property holds the number of items in the list including any hidden items.
    Q_PROPERTY(int            count        READ   count) //会计算隐藏的条目在内

    //This property holds the row of the current item.
    //Depending on the current selection mode, the row may also be selected.
    Q_PROPERTY(int            currentRow
                READ          currentRow
                WRITE      setCurrentRow
                NOTIFY        currentRowChanged
                USER          true)

    /*
    enum QAbstractItemView::SelectionMode { //定义在基类。
                NoSelection,
            SingleSelection,
             MultiSelection,
          ExtendedSelection,  //此项功能最强
        ContiguousSelection
    };
    */

    //此属性表示是否启用排序。默认值为false。经测试，这个排序只有一种，强制从上到下的增序排序。
    //如果此属性为真，则在列表中启用排序;如果属性为假，则不启用排序。
    Q_PROPERTY(bool sortingEnabled READ isSortingEnabled WRITE setSortingEnabled)

    friend class QListWidgetItem;
    friend class QListModel;

private:
    void setModel(QAbstractItemModel * model) override; //本表格窗体不需要模型了

    Qt::SortOrder sortOrder() const; //无法从外部调用了，只有增序一个结果，不必查询了。

    Q_DECLARE_PRIVATE(QListWidget)
    Q_DISABLE_COPY(QListWidget)

    Q_PRIVATE_SLOT(d_func(), void _q_emitItemEntered(const QModelIndex & index))
    Q_PRIVATE_SLOT(d_func(), void _q_emitItemPressed(const QModelIndex & index))
    Q_PRIVATE_SLOT(d_func(), void _q_emitItemClicked(const QModelIndex & index))
    Q_PRIVATE_SLOT(d_func(), void _q_emitItemDoubleClicked(const QModelIndex & index))
    Q_PRIVATE_SLOT(d_func(), void _q_emitItemActivated(const QModelIndex & index))

    Q_PRIVATE_SLOT(d_func(), void _q_emitItemChanged(const QModelIndex & index))
    Q_PRIVATE_SLOT(d_func(), void _q_emitCurrentItemChanged(const QModelIndex & previous,
                                                            const QModelIndex & current))
    Q_PRIVATE_SLOT(d_func(), void _q_dataChanged(const QModelIndex & topLeft,
                                                 const QModelIndex & bottomRight))

    Q_PRIVATE_SLOT(d_func(), void _q_sort())

public:
    //Constructs an empty QListWidget with the given parent.
    explicit QListWidget(QWidget * parent = nullptr);

    ~QListWidget();

    //Reimplements: QAbstractItemView::s
    //               etSelectionModel(QItemSelectionModel * selectionModel).
    void setSelectionModel(QItemSelectionModel * selectionModel) override;


//   Q_PROPERTY(int   count    READ   count) //会计算隐藏的条目在内
                int   count() const;

// //This property holds the row of the current item.
// //Depending on the current selection mode, the row may also be selected.
//   Q_PROPERTY(int          currentRow
//              READ         currentRow
//              WRITE     setCurrentRow
//              NOTIFY       currentRowChanged
//              USER         true)
                int          currentRow(  ) const;
                void      setCurrentRow(int row);
                void      setCurrentRow(int row,
                                        QItemSelectionModel::SelectionFlags command);
Q_SIGNALS:
                void         currentRowChanged(int currentRow);


public:
// //此属性表示是否启用排序。默认值为false。经测试，这个排序只有一种，强制从上到下的增序排序。
// //如果此属性为真，则在列表中启用排序;如果属性为假，则不启用排序。
//   Q_PROPERTY(bool        sortingEnabled
//              READ      isSortingEnabled
//              WRITE    setSortingEnabled)
                bool      isSortingEnabled() const;
                void     setSortingEnabled(bool enable);


    QListWidgetItem *                item (int row) const;

    int row(const QListWidgetItem *  item) const;

    void                       insertItem (int row,       QListWidgetItem * item  );
    void                       insertItem (int row, const QString         & label );
    void                       insertItems(int row, const QStringList     & labels);
    inline
    void                          addItem (const QString         & label )
    {   insertItem(count(), label); }
    inline
    void                          addItem (      QListWidgetItem * item  )
    {   insertItem(count(), item); }
    inline
    void                          addItems(const QStringList     & labels)
    {   insertItems(count(), labels); }
    QListWidgetItem *            takeItem (int row);


    QListWidgetItem *                itemAt(const QPoint & p) const;
    inline
    QListWidgetItem *                itemAt(int x,     int y) const
    {   return itemAt(QPoint(x, y)); }
    QRect                      visualItemRect(const QListWidgetItem * item) const;

    QListWidgetItem *         currentItem() const;
    void                   setCurrentItem(QListWidgetItem * item);
    void                   setCurrentItem(QListWidgetItem * item,
                                        QItemSelectionModel::SelectionFlags command);

    void                         sortItems(Qt::SortOrder order = Qt::AscendingOrder);

    QList<QListWidgetItem *>         items(const QMimeData * data) const;

    QModelIndex             indexFromItem         (const QListWidgetItem * item ) const;
    QListWidgetItem *                itemFromIndex(const QModelIndex     & index) const;

    //Returns a list of all selected items in the list widget.
    //测试发现，多选后，即使失去光标焦点，表格窗体也依然会维持多选的状态。
    QList<QListWidgetItem *> selectedItems() const; //本函数没有使用选择模型

    QList<QListWidgetItem *>     findItems( const QString & text,
                                            Qt::MatchFlags  flags) const;

    //Returns the widget displayed in the given item.
    QWidget *                        itemWidget(QListWidgetItem * item) const;
    void                          setItemWidget(QListWidgetItem * item, QWidget * widget);
    //Sets the widget to be displayed in the given item.
    //此函数只能用于在列表小部件项目的位置显示静态内容。
    //如果要显示自定义动态内容或实现自定义编辑器窗口小部件,
    //  请改用QListView和子类QStyledltemDelegate。
    inline void                removeItemWidget(QListWidgetItem * item)
    {   setItemWidget(Item, nullptr);  }
    //Removes the widget set on the given item.
    //To remove an item (row) from the list entirely,
    //  either delete the item or use takeItem().

    //Starts editing the item if it is editable.
    void                         editItem(QListWidgetItem * item);

    using  QAbstractItemView::isPersistentEditorOpen;
    //bool QAbstractItemView::isPersistentEditorOpen(QModelIndex & index) const;

    bool                      isPersistentEditorOpen(QListWidgetItem * item) const;
    void                    openPersistentEditor    (QListWidgetItem * item);
    void                   closePersistentEditor    (QListWidgetItem * item);


protected:
    virtual Qt::DropActions supportedDropActions() const;

    bool     event(QEvent *e) override;
    void dropEvent(QDropEvent *event) override;

    virtual QStringList        mimeTypes() const;
    virtual QMimeData   *      mimeData(const QList<QListWidgetItem *> & items) const;
    virtual bool           dropMimeData(int index, const QMimeData * data,
                              Qt::DropAction action);


public Q_SLOTS:
    //Scrolls the view if necessary to ensure that the item is visible.
    //hint specifies where the item should be located after the operation.
    void   scrollToItem(const QListWidgetItem * item,
                        QAbstractItemView::ScrollHint hint = EnsureVisible);

    void clear();   //Removes all items and selections in the view.
                    //Warning: All items will be permanently deleted.

Q_SIGNALS:
    
    void itemEntered  (QListWidgetItem * item); //这几个信号函数关注于鼠标点击的信号
    void itemPressed  (QListWidgetItem * item);
    void itemClicked  (QListWidgetItem * item);
    void itemDoubleClicked(QListWidgetItem * item);
    void itemActivated(QListWidgetItem * item);
    
    //This signal is emitted whenever the data of item has changed.
    void        itemChanged(QListWidgetItem * item);   //当本条目的内容变化时，调用本函数。
    void currentTextChanged(const QString & currentText);
    //This signal is emitted whenever the current item changes.
    //currentText is the text data in the current item.
    //If there is no current item, the currentText is invalid.
    void currentRowChanged (int currentRow);
    //This signal is emitted whenever the current item changes.
    //currentRow is the row of the current item.
    //If there is no current item, the currentRow is -1.
    
    void currentItemChanged(QListWidgetItem * current, QListWidgetItem * previous);
    
    void itemSelectionChanged();
    //This signal is emitted whenever the selection changes.
    
}; //完结 class QListWidget : public QListView