KDirModel Class
A model for a KIO-based directory tree. More...
| Header: | #include <KDirModel> |
| CMake: | find_package(KF6 REQUIRED COMPONENTS KIO)target_link_libraries(mytarget PRIVATE KF6::KIOWidgets) |
| Inherits: | QAbstractItemModel |
Public Types
| enum | AdditionalRoles { FileItemRole, ChildCountRole, HasJobRole } |
| flags | DropsAllowed |
| enum | DropsAllowedFlag { NoDrops, DropOnDirectory, DropOnAnyFile, DropOnLocalExecutable } |
| enum | ModelColumns { Name, Size, ModifiedTime, Permissions, Owner, …, ColumnCount } |
(since 5.69) enum | OpenUrlFlag { NoFlags, Reload, ShowRoot } |
| flags | OpenUrlFlags |
Public Functions
| KDirModel(QObject *parent = nullptr) | |
(since 5.28) void | clearAllPreviews() |
| KDirLister * | dirLister() const |
| void | expandToUrl(const QUrl &url) |
| QModelIndex | indexForItem(const KFileItem &) const |
| QModelIndex | indexForUrl(const QUrl &url) const |
| void | itemChanged(const QModelIndex &index) |
| KFileItem | itemForIndex(const QModelIndex &index) const |
| bool | jobTransfersVisible() const |
(since 5.69) void | openUrl(const QUrl &url, KDirModel::OpenUrlFlags flags = NoFlags) |
| void | requestSequenceIcon(const QModelIndex &index, int sequenceIndex) |
| void | setDirLister(KDirLister *dirLister) |
| void | setDropsAllowed(KDirModel::DropsAllowed dropsAllowed) |
| void | setJobTransfersVisible(bool show) |
Reimplemented Public Functions
| virtual bool | canFetchMore(const QModelIndex &parent) const override |
| virtual void | fetchMore(const QModelIndex &parent) override |
| virtual bool | hasChildren(const QModelIndex &parent = QModelIndex()) const override |
| virtual QVariant | headerData(int section, Qt::Orientation orientation, int role = Qt::DisplayRole) const override |
| virtual bool | setData(const QModelIndex &index, const QVariant &value, int role = Qt::EditRole) override |
| virtual void | sort(int column, Qt::SortOrder order = Qt::AscendingOrder) override |
Signals
| void | expand(const QModelIndex &index) |
| void | needSequenceIcon(const QModelIndex &index, int sequenceIndex) |
Static Public Members
| QList<QUrl> | simplifiedUrlList(const QList<QUrl> &urls) |
Detailed Description
KDirModel implements the QAbstractItemModel interface (for use with Qt's model/view widgets) around the directory listing for one directory or a tree of directories.
Note that there are some cases when using QPersistentModelIndexes from this model will not give expected results. QPersistentIndexes will remain valid and updated if its siblings are added or removed. However, if the QPersistentIndex or one of its ancestors is moved, the QPersistentIndex will become invalid. For example, if a file or directory is renamed after storing a QPersistentModelIndex for it, the index (along with any stored children) will become invalid even though it is still in the model. The reason for this is that moves of files and directories are treated as separate insert and remove actions.
See also KDirSortFilterProxyModel.
Member Type Documentation
enum KDirModel::AdditionalRoles
| Constant | Value | Description |
|---|---|---|
KDirModel::FileItemRole | 0x07A263FF | Returns the KFileItem for a given index. roleName is "fileItem". |
KDirModel::ChildCountRole | 0x2C4D0A40 | Returns the number of items in a directory, or ChildCountUnknown. roleName is "childCount". |
KDirModel::HasJobRole | 0x01E555A5 | Returns whether or not there is a job on an item (file/directory). roleName is "hasJob". |
enum KDirModel::DropsAllowedFlag
flags KDirModel::DropsAllowed
| Constant | Value | Description |
|---|---|---|
KDirModel::NoDrops | 0 | |
KDirModel::DropOnDirectory | 1 | Allow drops on any directory |
KDirModel::DropOnAnyFile | 2 | Allow drops on any file |
KDirModel::DropOnLocalExecutable | 4 | Allow drops on local executables, shell scripts and desktop files. Can be used with DropOnDirectory. |
The DropsAllowed type is a typedef for QFlags<DropsAllowedFlag>. It stores an OR combination of DropsAllowedFlag values.
enum KDirModel::ModelColumns
Useful "default" columns. Views can use a proxy to have more control over this.
| Constant | Value |
|---|---|
KDirModel::Name | 0 |
KDirModel::Size | 1 |
KDirModel::ModifiedTime | 2 |
KDirModel::Permissions | 3 |
KDirModel::Owner | 4 |
KDirModel::Group | 5 |
KDirModel::Type | 6 |
KDirModel::ColumnCount | 7 |
[since 5.69] enum KDirModel::OpenUrlFlag
flags KDirModel::OpenUrlFlags
Flags for the openUrl() method
| Constant | Value | Description |
|---|---|---|
KDirModel::NoFlags | 0x0 | No additional flags specified. |
KDirModel::Reload | 0x1 | Indicates whether to use the cache or to reread the directory from the disk. Use only when opening a dir not yet listed by our dirLister() without using the cache. Otherwise use dirLister()->updateDirectory(). |
KDirModel::ShowRoot | 0x2 | Display a root node for the URL being opened. |
This enum was introduced in 5.69.
The OpenUrlFlags type is a typedef for QFlags<OpenUrlFlag>. It stores an OR combination of OpenUrlFlag values.
Member Function Documentation
[explicit] KDirModel::KDirModel(QObject *parent = nullptr)
parent parent qobject
[override virtual] bool KDirModel::canFetchMore(const QModelIndex &parent) const
Reimplements: QAbstractItemModel::canFetchMore(const QModelIndex &parent) const.
Returns true for empty directories.
[invokable, since 5.28] void KDirModel::clearAllPreviews()
Forget all previews (optimization for turning previews off). The items will again have their default appearance (not controlled by the model).
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
This function was introduced in 5.28.
KDirLister *KDirModel::dirLister() const
Return the directory lister used by this model.
See also setDirLister().
[signal] void KDirModel::expand(const QModelIndex &index)
Emitted for each subdirectory that is a parent of a url passed to expandToUrl This allows to asynchronously open a tree view down to a given directory. Also emitted for the final file, if expandToUrl is called with a file (for instance so that it can be selected).
[invokable] void KDirModel::expandToUrl(const QUrl &url)
Lists subdirectories using fetchMore() as needed until the given url exists in the model.
When the model is used by a treeview, call KDirLister::openUrl with the base url of the tree, then the treeview will take care of calling fetchMore() when the user opens directories. However if you want the tree to show a given URL (i.e. open the tree recursively until that URL), call expandToUrl(). Note that this is asynchronous; the necessary listing of subdirectories will take time so the model will not immediately have this url available. The model emits the signal expand() when an index has become available; this can be connected to the treeview in order to let it open that index.
url the url of a subdirectory of the directory model (or a file in a subdirectory)
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[override virtual] void KDirModel::fetchMore(const QModelIndex &parent)
Reimplements: QAbstractItemModel::fetchMore(const QModelIndex &parent).
[override virtual] bool KDirModel::hasChildren(const QModelIndex &parent = QModelIndex()) const
Reimplements: QAbstractItemModel::hasChildren(const QModelIndex &parent) const.
Returns true for directories
[override virtual] QVariant KDirModel::headerData(int section, Qt::Orientation orientation, int role = Qt::DisplayRole) const
Reimplements: QAbstractItemModel::headerData(int section, Qt::Orientation orientation, int role) const.
Returns the column titles.
[invokable] QModelIndex KDirModel::indexForItem(const KFileItem &) const
Return the index for a given kfileitem. This can be slow.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[invokable] QModelIndex KDirModel::indexForUrl(const QUrl &url) const
Return the index for a given url. This can be slow.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[invokable] void KDirModel::itemChanged(const QModelIndex &index)
Notify the model that the item at this index has changed. For instance because KMimeTypeResolver called determineMimeType on it. This makes the model emit its dataChanged signal at this index, so that views repaint. Note that for most things (renaming, changing size etc.), KDirLister's signals tell the model already.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
KFileItem KDirModel::itemForIndex(const QModelIndex &index) const
Return the fileitem for a given index. This is O(1), i.e. fast.
bool KDirModel::jobTransfersVisible() const
Returns whether or not displaying job transfers has been enabled.
See also setJobTransfersVisible().
[signal] void KDirModel::needSequenceIcon(const QModelIndex &index, int sequenceIndex)
Emitted when another icon sequence index is requested
index Index of the item that should get another icon
sequenceIndex Index in the sequence. If it is zero, the standard icon should be assigned. For higher indices, arbitrary different meaningful icons should be generated. This is usually slowly counted up while the user hovers the icon. If no meaningful alternative icons can be generated, this should be ignored.
[invokable, since 5.69] void KDirModel::openUrl(const QUrl &url, KDirModel::OpenUrlFlags flags = NoFlags)
Display the contents of url in the model.
Apart from the support for the ShowRoot flag, this is equivalent to dirLister()->openUrl(url, flags)
url the URL of the directory whose contents should be listed. Unless ShowRoot is set, the item for this directory will NOT be shown, the model starts at its children.
flags see OpenUrlFlag
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
This function was introduced in 5.69.
void KDirModel::requestSequenceIcon(const QModelIndex &index, int sequenceIndex)
This emits the needSequenceIcon signal, requesting another sequence icon
If there is a KFilePreviewGenerator attached to this model, that generator will care about creating another preview.
index Index of the item that should get another icon
sequenceIndex Index in the sequence. If it is zero, the standard icon will be assigned. For higher indices, arbitrary different meaningful icons will be generated.
[override virtual] bool KDirModel::setData(const QModelIndex &index, const QVariant &value, int role = Qt::EditRole)
Reimplements: QAbstractItemModel::setData(const QModelIndex &index, const QVariant &value, int role).
Call this to set a new icon, e.g. a preview
void KDirModel::setDirLister(KDirLister *dirLister)
Set the directory lister to use by this model, instead of the default KDirLister created internally. The model takes ownership.
See also dirLister().
[invokable] void KDirModel::setDropsAllowed(KDirModel::DropsAllowed dropsAllowed)
Set whether dropping onto items should be allowed, and for which kind of item Drops are disabled by default.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
void KDirModel::setJobTransfersVisible(bool show)
Enable/Disable the displaying of an animated overlay that is shown for any destination urls (in the view). When enabled, the animations (if any) will be drawn automatically.
Only the files/folders that are visible and have jobs associated with them will display the animation. You would likely not want this enabled if you perform some kind of custom painting that takes up a whole item, and will just make this(and what you paint) look funky.
Default is disabled.
Note: KFileItemDelegate needs to have it's method called with the same value, when you make the call to this method.
See also jobTransfersVisible().
[static] QList<QUrl> KDirModel::simplifiedUrlList(const QList<QUrl> &urls)
Remove urls from the list if an ancestor is present on the list. This can be used to delete only the ancestor url and skip a potential error of a non-existent url.
For example, for a list of "/home/foo/a", "/home/foo/a/a.txt", "/home/foo/a/a/a.txt", "/home/foo/a/b/b.txt", "home/foo/b/b.txt", this method will return the list "/home/foo/a", "/home/foo/b/b.txt".
Returns the list urls without parented urls inside.
[override virtual] void KDirModel::sort(int column, Qt::SortOrder order = Qt::AscendingOrder)
Reimplements: QAbstractItemModel::sort(int column, Qt::SortOrder order).
Not implemented.
See also KDirSortFilterProxyModel.