QT6 源（159）模型视图架构里的文件系统模型 QFileSystemModel 篇二：本类的源代码带注释

（12）本类定义于头文件 qfilesystemmodel . h ：

#ifndef QFILESYSTEMMODEL_H
#define QFILESYSTEMMODEL_H

#include <QtGui/qtguiglobal.h>
#include <QtCore/qabstractitemmodel.h>
#include <QtCore/qpair.h>
#include <QtCore/qdir.h>
#include <QtGui/qicon.h>
#include <QtCore/qdiriterator.h>

QT_REQUIRE_CONFIG(filesystemmodel);

QT_BEGIN_NAMESPACE

class ExtendedInformation;
class QFileSystemModelPrivate;
class QAbstractFileIconProvider;


/*
The QFileSystemModel class provides a data model for the local filesystem.

Detailed Description :
这个类提供了对本地文件系统的访问权限，提供了重命名和删除文件和目录以及创建新目录的函数。
在最简单的情况下，它可与合适的显示小部件一起使用，作为浏览器或过滤器的一部分。

QFileSystemModel可以使用 QAbstractItemModel提供的标准接口进行访问，
但它也提供了一些特定函数提供有关与于目录模型的便捷功能。
fileInfo()、isDir()、fileName()和filePath()模型中的项目相关的基础文件和目录的信息。
可以使用mkdir()和rmdir()创建和删除目录。

Note: QFileSystemModel requires an instance of QApplication.

Example Usage :
显示默认目录内容的目录模型通常使用父对象构建:
     QFileSystemModel * model = new QFileSystemModel;
     model->setRootPath(QDir::currentPath());

树状视图可以用来显示模型的内容 :
     QTreeView * tree = new QTreeView(splitter);
     tree->setModel(model);

可以通过设置树视图的根索引来显示特定目录的内容:
     tree->setRootIndex(model->index(QDir::currentPath()));

该视图的根索引可用于控制显示多大比例的层次模型。QFileSystemModel提供了一个便捷函数，用于返回与模型内某
个目录路径相对应的合适模型索引。

Caching and Performance :
OFileSystemModel`在调用`setRootPath()'之前不会加载任何文件或目录。
这样可以在那之前防止对文件系统进行任何不必要的查询，例如在Windows上列出驱动器。

QFileSystemModel使用一个单独的线程来填充自身，这样就不会在查询文件系统时导致主线程挂起。
在模型填充一个目录之前，调用rowCount()将返回0。

QFileSystemModel保持一个包含文件信息的缓存。该缓存使用 QFileSystemWatcher 自动更新。


*/

class Q_GUI_EXPORT QFileSystemModel : public QAbstractItemModel
{
    Q_OBJECT

    //此属性包含影响模型的各种选项。默认情况下，所有选项都已禁用。在更改属性之前应设置选项。
    Q_PROPERTY(Options   options   //经测试，本属性的默认值是0。没有启用任何 dont
                READ     options   WRITE   setOptions)

    //此属性表示目录模型是否允许写入文件系统。
    //如果将此属性设置为false，目录模型将允许重命名、复制和删除文件和目录。此属性默认为真。
    //只读模式下，树视图是不响应鼠标右键的。测试发现，即使改为 F，也仅仅只能修改文件名。
    Q_PROPERTY(bool   readOnly    READ   isReadOnly   WRITE   setReadOnly)

    //此属性表示未通过名称过滤器的文件是隐藏还是禁用。此属性默认为真。
    Q_PROPERTY(bool   nameFilterDisables
                READ  nameFilterDisables   WRITE   setNameFilterDisables)

    //此属性表示目录模型是否应解析符号链接。这仅在Windows上适用。默认情况下，此属性为真。
    Q_PROPERTY(bool   resolveSymlinks      //应该是解析快捷方式的意思。
                READ  resolveSymlinks      WRITE   setResolveSymlinks)

private:
    Q_DECLARE_PRIVATE(QFileSystemModel)
    Q_DISABLE_COPY(QFileSystemModel)

    Q_PRIVATE_SLOT(d_func(), void _q_directoryChanged(const QString &directory, const QStringList &list))
    Q_PRIVATE_SLOT(d_func(), void _q_performDelayedSort())
    Q_PRIVATE_SLOT(d_func(),
                   void _q_fileSystemChanged(const QString &path,
                                             const QList<QPair<QString, QFileInfo>> &))
    Q_PRIVATE_SLOT(d_func(), void _q_resolvedName(const QString &fileName, const QString &resolvedName))

    friend class QFileDialogPrivate;


public:
    enum Roles {
        FileIconRole    = Qt::DecorationRole, //DecorationRole = 1
        FilePathRole    = Qt::UserRole + 1,   //UserRole = 0x0100
        FileNameRole    = Qt::UserRole + 2,   //这些都是自定义属性
        FilePermissions = Qt::UserRole + 3
    };

    explicit QFileSystemModel(QObject * parent = nullptr); //有参构造函数

    ~QFileSystemModel(); //析构函数


    //*************************以下继承于基类的成员函数，不再注释************************
    QModelIndex index(int row, int column,
                      const QModelIndex & parent = QModelIndex()) const override;

    using QObject::parent;
    QModelIndex parent(const QModelIndex & child) const override;

    QModelIndex sibling(int row, int column, const QModelIndex & idx) const override;

    bool hasChildren(const QModelIndex & parent = QModelIndex()) const override;

    bool canFetchMore(const QModelIndex & parent) const override;
    void    fetchMore(const QModelIndex & parent)       override;

    int    rowCount(const QModelIndex & parent = QModelIndex()) const override;
    int columnCount(const QModelIndex & parent = QModelIndex()) const override;


    QVariant       data(const QModelIndex & index,
                        int role = Qt::DisplayRole) const override;
    bool        setData(const QModelIndex & index,
                        const QVariant    & value, int role = Qt::EditRole) override;

    QVariant headerData(int section, Qt::Orientation orientation,
                        int role = Qt::DisplayRole) const override;

    Qt::ItemFlags flags(const QModelIndex & index) const override;

    void sort(int column, Qt::SortOrder order = Qt::AscendingOrder) override;

    Qt::DropActions         supportedDropActions() const override;
    QHash<int, QByteArray>             roleNames() const override;

    QStringList         mimeTypes() const override;
    QMimeData    *        mimeData (const QModelIndexList & indexes) const override;
    bool              dropMimeData (const QMimeData * data, Qt::DropAction action,
                                    int row, int column,
                                    const QModelIndex & parent) override;
    //**********************至此，继承于基类的虚成员函数，整理完毕*************************

    // QFileSystemModel specific API

//   //此属性包含影响模型的各种选项。默认情况下，所有选项都已禁用。在更改属性之前应设置选项。
//   Q_PROPERTY(Options     options   //经测试，本属性的默认值是0。没有启用任何 dont
//              READ        options     WRITE     setOptions)
                Options     options() const;
                void     setOptions(Options options);

                //Returns true if the given option is enabled; otherwise, returns false.
                bool    testOption(Option option) const;
                void     setOption(Option option, bool on = true);
    //Sets the given option to be enabled if on is true; otherwise, clears the given option.
    //Options should be set before changing properties.


    enum Option
    {
        DontWatchForChanges         = 0x00000001, //不要在路径中添加文件监视器。
        //这会在使用模型进行简单任务(如行编辑补全)时减少开销。
        DontResolveSymlinks         = 0x00000002, //不要在文件系统模型中解析符号链接。
        //默认情况下，符号链接被解析。
        DontUseCustomDirectoryIcons = 0x00000004  //请始终使用默认目录图标。
        //某些平台允许用户设置不同的图标。自定义图标查找在网络或可移动驱动器上会产生显著的性能影响。
        //这相应地在图标提供程序中设置了 QFileIconProvider::DontUseCustomDirectoryIcons~选项。
    };
    Q_ENUM(Option)
    Q_DECLARE_FLAGS(Options, Option)


//   //此属性表示目录模型是否允许写入文件系统。此属性默认为真。
//   Q_PROPERTY(bool       readOnly
//              READ     isReadOnly     WRITE     setReadOnly)
                bool     isReadOnly() const;
                void    setReadOnly(bool enable);


//   //此属性表示目录模型是否应解析符号链接。这仅在Windows上适用。默认情况下，此属性为真。
//   Q_PROPERTY(bool     resolveSymlinks       //应该是解析快捷方式的意思。
//              READ     resolveSymlinks       WRITE    setResolveSymlinks)
                bool     resolveSymlinks() const;
                void  setResolveSymlinks(bool enable);


    /*
    enum QDir::Filter
    {
        Dirs           = 0x0001, //List directories that match the filters.
        Files          = 0x0002, //List files.
        Drives         = 0x0004, //List disk drives (ignored under Unix).
        NoSymLinks     = 0x0008, //不要列出符号链接(不支持符号链接的操作系统会忽略它们)
        AllEntries     = Dirs | Files | Drives, //列出目录、文件、驱动器和符号链接
                                    //(除非你指定系统，否则不会列出损坏的符号链接)
        TypeMask       = 0x000f,

        Readable       = 0x0010, //列出应用程序具有读取权限的文件。可读值需要与目录或文件结合使用。
        Writable       = 0x0020, //列出应用程序具有写入权限的文件。
                                    //Writable值需要与 Dirs或 Files结合使用
        Executable     = 0x0040, //列出应用程序具有执行权限的文件。
                                    //Executable值需要与Dirs或Files结合使用。
        PermissionMask = 0x0070,

        Modified       = 0x0080, //仅列出已修改的文件(在Unix上忽略)
        Hidden         = 0x0100, //列出隐藏文件(在Unix系统中，以"."开头的文件)
        System         = 0x0200, //列出系统文件(在Unix上，包括FIFO、套接字和设备文件;
                                    //在Windows上包括Lnk文件)
        AccessMask     = 0x03F0,

        AllDirs        = 0x0400, //列出所有目录;即不要对目录名称应用过滤器。
        CaseSensitive  = 0x0800, //The filter should be case sensitive.
        NoDot          = 0x2000, //Do not list the special entry ".".
        NoDotDot       = 0x4000, //Do not list the special entry "..".
        NoDotAndDotDot = NoDot | NoDotDot, //Do not list the special entries "." and "..".

        NoFilter       = -1
    };
    Q_DECLARE_FLAGS(Filters, Filter)
    */

//   //此属性表示未通过名称过滤器的文件是隐藏还是禁用。此属性默认为真。
//   Q_PROPERTY(bool     nameFilterDisables
//              READ     nameFilterDisables    WRITE    setNameFilterDisables)
                bool     nameFilterDisables() const;
                void  setNameFilterDisables(bool enable);

    //Returns a list of filters applied to the names in the model.
    QStringList         nameFilters() const; //只留下名字属于 filter的文件
    void             setNameFilters(const QStringList & filters);
    //Sets the name filters to apply against the existing files.设置应用于现有文件的名称过滤器。

    //Returns the filter specified for the directory model.
    //If a filter has not been set,
    //  the default filter is QDir::AllEntries | QDir::NoDotAndDotDot | QDir::AllDirs.
    QDir::Filters           filter() const; //按 QDir::Filters 里的枚举值过滤文件
    void                 setFilter(QDir::Filters filters);
    //测试发现过滤是面向电脑的整个文件系统，都会受到影响，而非只对某个子目录过滤。

    QModelIndex             index   (const QString     & path, int column = 0) const;
    //Returns the model item index for the given path and column.//本子类扩展的成员函数

    QString                 filePath(const QModelIndex & index) const;
    //Returns the path of the item stored in the model under the index given.

    //Returns the file name for the item stored in the model under the given index.
    inline
    QString                 fileName(const QModelIndex & index) const
    { return index.data(Qt::DisplayRole).toString(); } //这里的 file,可是文件,也可是目录
    inline
    QIcon                   fileIcon(const QModelIndex & index) const
    { return qvariant_cast<QIcon>(index.data(Qt::DecorationRole)); }
    //Returns the  icon     for the item stored in the model under the given index.

    //Returns the file icon provider for this directory model.
    QAbstractFileIconProvider * iconProvider() const;
    void                     setIconProvider(QAbstractFileIconProvider * provider);
    //Sets the provider of file icons for the directory model.


    QString                 rootPath     () const; //The currently set root path.根路径
    QDir                    rootDirectory() const; //The currently set directory.根目录
    QModelIndex          setRootPath(const QString & newpath);//手写路径里要对分隔符 \转义成\\
    //Sets the directory that is being watched by the
    //  model to newPath by installing a file system watcher on it.
    //通过在目标目录上安装文件系统监视器，将正在由模型监视的目录设置为新路径。
    //该目录内的文件和目录的任何更改都将反映在模型中。
    //如果路径被更改，将发出rootPathChanged()信号。
    //注:此功能不会改变模型的架构，也不会修改可供视图使用的数据。
    //换言之，模型的“根”不会发生改变，以仅包含文件系统中新路径所指定的目录内的文件和目录。
    //意思是设置本模型对文件系统的监视范围，只监视文件系统其中的一部分。
Q_SIGNALS:
    void                    rootPathChanged(const QString & newPath);
    //This signal is emitted whenever the root path has been changed to a newPath.


public :
    //Returns true if the model item index represents a directory; otherwise returns false.
    bool           isDir(const QModelIndex & index) const;
    QModelIndex    mkdir(const QModelIndex & parent, const QString & name);
    //Create a directory with the name in the parent model index.
    //在父目录 parent中创建名为 name的目录。
    bool           rmdir(const QModelIndex & index);
    //移除与文件系统模型中的模型项索引相对应的目录，并从文件系统中删除相应的目录，
    //如果操作成功则返回 true。如果无法删除该目录，则返回 false。
    //警告:此函数会从文件系统中删除目录;不会将它们移动到可以恢复的位置。

    bool          remove(const QModelIndex & index);
    //从文件系统模型中移除模型项索引，并从文件系统中删除相应的文件，
    //如果操作成功则返回 true。如果无法移除该项，则返回 false。
    //警告:此函数从文件系统中删除文件;它们不会被移动到可以恢复的位置

    //Returns the data stored under the given role for the item "My Computer".
    QVariant       myComputer(int role = Qt::DisplayRole) const;

    //Returns the size in bytes of index. If the file does not exist, 0 is returned.
    //以字节为基础单位,也可以是 Kb， Mb
    qint64                      size(const QModelIndex & index) const;
    QString                     type(const QModelIndex & index) const;
    //Returns the type of file index such as "Directory" or "JPEG file".
    QDateTime           lastModified(const QModelIndex & index) const;
    //Returns the date and time when index was last modified.

    /*
    enum QFile::Permission {
        ReadOwner = 0x4000, WriteOwner = 0x2000, ExeOwner = 0x1000,
        ReadUser  = 0x0400, WriteUser  = 0x0200, ExeUser  = 0x0100,
        ReadGroup = 0x0040, WriteGroup = 0x0020, ExeGroup = 0x0010,
        ReadOther = 0x0004, WriteOther = 0x0002, ExeOther = 0x0001
    };
    Q_DECLARE_FLAGS(Permissions, Permission)
    */
    //Returns the complete OR-ed together combination of QFile::Permission for the index.
    QFile::Permissions   permissions(const QModelIndex & index) const;
    QFileInfo               fileInfo(const QModelIndex & index) const;
    //Returns the QFileInfo for the item stored in the model under the given index.


protected:
    QFileSystemModel(QFileSystemModelPrivate &, QObject * parent = nullptr);
    void timerEvent(QTimerEvent * event) override;
    bool      event(QEvent      * event) override;

Q_SIGNALS:
    //void rootPathChanged(const QString & newPath);  这是函数。

    void        fileRenamed(const QString & path,    //修改文件与目录的名字是通过视图进行的
                            const QString & oldName, const QString & newName);
    //This signal is emitted whenever a file with the
    //  oldName is successfully renamed to newName.
    //The file is located in in the directory path.

    void    directoryLoaded(const QString & path); //当收集线程完成路径加载时，会发出此信号。
    //This signal is emitted when the gatherer thread has finished to load the path.
    //当在视图里依次点开目录时，都会触发本信号函数，因为磁盘寻址是相对于内存寻址慢一点的过程。

}; //完结 class QFileSystemModel : public QAbstractItemModel
Q_DECLARE_OPERATORS_FOR_FLAGS(QFileSystemModel::Options)

QT_END_NAMESPACE

#endif // QFILESYSTEMMODEL_H

（13）

谢谢