2 * SPDX-FileCopyrightText: 2011 Peter Penz <peter.penz19@gmail.com>
4 * SPDX-License-Identifier: GPL-2.0-or-later
7 #ifndef KFILEITEMMODEL_H
8 #define KFILEITEMMODEL_H
10 #include "dolphin_export.h"
11 #include "kitemviews/kitemmodelbase.h"
12 #include "kitemviews/private/kfileitemmodelfilter.h"
15 #include <KLazyLocalizedString>
34 * @brief KItemModelBase implementation for KFileItems.
36 * Allows to load items of a directory. Sorting and grouping of
37 * items are supported. Roles that are not part of KFileItem can
38 * be added with KFileItemModel::setData().
40 * Recursive expansion of sub-directories is supported by
41 * KFileItemModel::setExpanded().
43 class DOLPHIN_EXPORT KFileItemModel
: public KItemModelBase
48 explicit KFileItemModel(QObject
*parent
= nullptr);
49 ~KFileItemModel() override
;
52 * Loads the directory specified by \a url. The signals
53 * directoryLoadingStarted(), directoryLoadingProgress() and directoryLoadingCompleted()
54 * indicate the current state of the loading process. The items
55 * of the directory are added after the loading has been completed.
57 void loadDirectory(const QUrl
&url
);
60 * Throws away all currently loaded items and refreshes the directory
61 * by reloading all items again.
63 void refreshDirectory(const QUrl
&url
);
66 * @return Parent directory of the items that are shown. In case
67 * if a directory tree is shown, KFileItemModel::dir() returns
68 * the root-parent of all items.
71 QUrl
directory() const override
;
74 * Cancels the loading of a directory which has been started by either
75 * loadDirectory() or refreshDirectory().
77 void cancelDirectoryLoading();
79 int count() const override
;
80 QHash
<QByteArray
, QVariant
> data(int index
) const override
;
81 bool setData(int index
, const QHash
<QByteArray
, QVariant
> &values
) override
;
84 * Sets a separate sorting with directories first (true) or a mixed
85 * sorting of files and directories (false).
87 void setSortDirectoriesFirst(bool dirsFirst
);
88 bool sortDirectoriesFirst() const;
91 * Sets a separate sorting with hidden files and folders last (true) or not (false).
93 void setSortHiddenLast(bool hiddenLast
);
94 bool sortHiddenLast() const;
96 void setShowHiddenFiles(bool show
);
97 bool showHiddenFiles() const;
100 * If set to true, only directories are shown as items of the model. Files
103 void setShowDirectoriesOnly(bool enabled
);
104 bool showDirectoriesOnly() const;
106 QMimeData
*createMimeData(const KItemSet
&indexes
) const override
;
108 int indexForKeyboardSearch(const QString
&text
, int startFromIndex
= 0) const override
;
110 bool supportsDropping(int index
) const override
;
112 bool canEnterOnHover(int index
) const override
;
114 QString
roleDescription(const QByteArray
&role
) const override
;
116 QList
<QPair
<int, QVariant
>> groups() const override
;
119 * @return The file-item for the index \a index. If the index is in a valid
120 * range it is assured that the file-item is not null. The runtime
121 * complexity of this call is O(1).
123 KFileItem
fileItem(int index
) const;
126 * @return The file-item for the url \a url. If no file-item with the given
127 * URL is found KFileItem::isNull() will be true for the returned
128 * file-item. The runtime complexity of this call is O(1).
130 KFileItem
fileItem(const QUrl
&url
) const;
133 * @return The index for the file-item \a item. -1 is returned if no file-item
134 * is found or if the file-item is null. The amortized runtime
135 * complexity of this call is O(1).
137 int index(const KFileItem
&item
) const;
140 * @return The index for the URL \a url. -1 is returned if no file-item
141 * is found. The amortized runtime complexity of this call is O(1).
143 int index(const QUrl
&url
) const;
146 * @return Root item of all items representing the item
147 * for KFileItemModel::dir().
149 KFileItem
rootItem() const;
152 * Clears all items of the model.
157 * Sets the roles that should be shown for each item.
159 void setRoles(const QSet
<QByteArray
> &roles
);
160 QSet
<QByteArray
> roles() const;
162 bool setExpanded(int index
, bool expanded
) override
;
163 bool isExpanded(int index
) const override
;
164 bool isExpandable(int index
) const override
;
165 int expandedParentsCount(int index
) const override
;
167 QSet
<QUrl
> expandedDirectories() const;
170 * Marks the URLs in \a urls as sub-directories which were expanded previously.
171 * After calling loadDirectory() or refreshDirectory() the marked sub-directories
172 * will be expanded step-by-step.
174 void restoreExpandedDirectories(const QSet
<QUrl
> &urls
);
177 * Expands all parent-directories of the item \a url.
179 void expandParentDirectories(const QUrl
&url
);
181 void setNameFilter(const QString
&nameFilter
);
182 QString
nameFilter() const;
184 void setMimeTypeFilters(const QStringList
&filters
);
185 QStringList
mimeTypeFilters() const;
187 void setExcludeMimeTypeFilter(const QStringList
&filters
);
188 QStringList
excludeMimeTypeFilter() const;
196 bool requiresIndexer
;
200 * @return Provides static information for a role that is supported
201 * by KFileItemModel. Some roles can only be determined if
202 * Baloo is enabled and/or the Baloo indexing is enabled.
204 static RoleInfo
roleInformation(const QByteArray
&role
);
207 * @return Provides static information for all available roles that
208 * are supported by KFileItemModel. Some roles can only be
209 * determined if Baloo is enabled and/or the Baloo
210 * indexing is enabled.
212 static QList
<RoleInfo
> rolesInformation();
215 * @return Provides static information for all available grouping
216 * behaviors supported by KFileItemModel but not directly
217 * mapped to roles of KFileItemModel.
219 static QList
<RoleInfo
> extraGroupingInformation();
221 /** set to true to hide application/x-trash files */
222 void setShowTrashMime(bool show
);
226 * Is emitted if the loading of a directory has been started. It is
227 * assured that a signal directoryLoadingCompleted() will be send after
228 * the loading has been finished. For tracking the loading progress
229 * the signal directoryLoadingProgress() gets emitted in between.
231 void directoryLoadingStarted();
234 * Is emitted after the loading of a directory has been completed or new
235 * items have been inserted to an already loaded directory. Usually
236 * one or more itemsInserted() signals are emitted before loadingCompleted()
237 * (the only exception is loading an empty directory, where only a
238 * loadingCompleted() signal gets emitted).
240 void directoryLoadingCompleted();
243 * Is emitted when the model is being refreshed (F5 key press)
245 void directoryRefreshing();
248 * Is emitted after the loading of a directory has been canceled.
250 void directoryLoadingCanceled();
253 * Informs about the progress in percent when loading a directory. It is assured
254 * that the signal directoryLoadingStarted() has been emitted before.
256 void directoryLoadingProgress(int percent
);
259 * Is emitted if the sort-role gets resolved asynchronously and provides
260 * the progress-information of the sorting in percent. It is assured
261 * that the last sortProgress-signal contains 100 as value.
263 void directorySortingProgress(int percent
);
266 * Is emitted if an information message (e.g. "Connecting to host...")
269 void infoMessage(const QString
&message
);
272 * Is emitted if an error message (e.g. "Unknown location")
275 void errorMessage(const QString
&message
, const int kioErrorCode
);
278 * Is emitted if a redirection from the current URL \a oldUrl
279 * to the new URL \a newUrl has been done.
281 void directoryRedirection(const QUrl
&oldUrl
, const QUrl
&newUrl
);
284 * Is emitted when the URL passed by KFileItemModel::setUrl() represents a file.
285 * In this case no signal errorMessage() will be emitted.
287 void urlIsFileError(const QUrl
&url
);
290 * It is emitted for files when they change and
291 * for dirs when files are added or removed.
293 void fileItemsChanged(const KFileItemList
&changedFileItems
);
296 * It is emitted when the parent directory was removed.
298 void currentDirectoryRemoved();
301 void onGroupedSortingChanged(bool current
) override
;
302 void onSortRoleChanged(const QByteArray
¤t
, const QByteArray
&previous
, bool resortItems
= true) override
;
303 void onSortOrderChanged(Qt::SortOrder current
, Qt::SortOrder previous
) override
;
304 void onGroupRoleChanged(const QByteArray
¤t
, const QByteArray
&previous
, bool resortItems
= true) override
;
305 void onGroupOrderChanged(Qt::SortOrder current
, Qt::SortOrder previous
) override
;
309 * Resorts all items dependent on the set sortRole(), sortOrder(),
310 * groupRole(), groupOrder() and foldersFirst() settings.
312 void resortAllItems();
314 void slotCompleted();
316 void slotItemsAdded(const QUrl
&directoryUrl
, const KFileItemList
&items
);
317 void slotItemsDeleted(const KFileItemList
&items
);
318 void slotRefreshItems(const QList
<QPair
<KFileItem
, KFileItem
>> &items
);
320 void slotSortingChoiceChanged();
321 void slotListerError(KIO::Job
*job
);
323 void dispatchPendingItemsToInsert();
327 // User visible roles:
331 ModificationTimeRole
,
342 // User visible roles available with Baloo:
367 // Non-visible roles:
373 ExpandedParentsCountRole
,
374 // Mandatory last entry:
380 QHash
<QByteArray
, QVariant
> values
;
384 struct ItemGroupInfo
{
388 bool operator==(const ItemGroupInfo
&other
) const;
389 bool operator!=(const ItemGroupInfo
&other
) const;
390 bool operator<(const ItemGroupInfo
&other
) const;
393 enum RemoveItemsBehavior
{ KeepItemData
, DeleteItemData
, DeleteItemDataIfUnfiltered
};
395 void insertItems(QList
<ItemData
*> &items
);
396 void removeItems(const KItemRangeList
&itemRanges
, RemoveItemsBehavior behavior
);
399 * Helper method for insertItems() and removeItems(): Creates
400 * a list of ItemData elements based on the given items.
401 * Note that the ItemData instances are created dynamically and
402 * must be deleted by the caller.
404 QList
<ItemData
*> createItemDataList(const QUrl
&parentUrl
, const KFileItemList
&items
) const;
407 * Helper method for prepareItemsForSorting().
408 * For a set role, fills 'values' of ItemData non-lazily.
410 void prepareItemsWithRole(QList
<ItemData
*> &itemDataList
, RoleType roleType
);
413 * Prepares the items for sorting. Normally, the hash 'values' in ItemData is filled
414 * lazily to save time and memory, but for some sort roles, it is expected that the
415 * sort role data is stored in 'values'.
417 void prepareItemsForSorting(QList
<ItemData
*> &itemDataList
);
419 static int expandedParentsCount(const ItemData
*data
);
421 void removeExpandedItems();
424 * This function is called by setData() and slotRefreshItems(). It emits
425 * the itemsChanged() signal, checks if the sort order is still correct,
426 * and starts m_resortAllItemsTimer if that is not the case.
428 void emitItemsChangedAndTriggerResorting(const KItemRangeList
&itemRanges
, const QSet
<QByteArray
> &changedRoles
);
431 * Resets all values from m_requestRole to false.
436 * @return Role-type for the given role.
437 * Runtime complexity is O(1).
439 RoleType
typeForRole(const QByteArray
&role
) const;
442 * @return Role-byte-array for the given role-type.
443 * Runtime complexity is O(1).
445 QByteArray
roleForType(RoleType roleType
) const;
447 QHash
<QByteArray
, QVariant
> retrieveData(const KFileItem
&item
, const ItemData
*parent
) const;
450 * @return True if role values benefit from natural or case insensitive sorting.
452 static bool isRoleValueNatural(const RoleType roleType
);
455 * @return True if \a a has a KFileItem whose text is 'less than' the one
456 * of \a b according to QString::operator<(const QString&).
458 static bool nameLessThan(const ItemData
*a
, const ItemData
*b
);
461 * @return True if the item-data \a a should be ordered before the item-data
462 * \b. The item-data may have different parent-items.
464 bool lessThan(const ItemData
*a
, const ItemData
*b
, const QCollator
&collator
) const;
467 * Sorts the items between \a begin and \a end using the comparison
468 * function lessThan().
470 void sort(const QList
<ItemData
*>::iterator
&begin
, const QList
<ItemData
*>::iterator
&end
) const;
473 * Helper method for lessThan() and expandedParentsCountCompare(): Compares
474 * the passed item-data using m_sortRole as criteria. Both items must
475 * have the same parent item, otherwise the comparison will be wrong.
477 int sortRoleCompare(const ItemData
*a
, const ItemData
*b
, const QCollator
&collator
) const;
480 * Helper method for lessThan() and expandedParentsCountCompare(): Compares
481 * the passed item-data using m_groupRole as criteria. Both items must
482 * have the same parent item, otherwise the comparison will be wrong.
484 int groupRoleCompare(const ItemData
*a
, const ItemData
*b
, const QCollator
&collator
) const;
486 int stringCompare(const QString
&a
, const QString
&b
, const QCollator
&collator
) const;
488 ItemGroupInfo
nameRoleGroup(const ItemData
*itemData
, bool withString
= true) const;
489 ItemGroupInfo
sizeRoleGroup(const ItemData
*itemData
, bool withString
= true) const;
490 ItemGroupInfo
timeRoleGroup(const std::function
<QDateTime(const ItemData
*)> &fileTimeCb
, const ItemData
*itemData
, bool withString
= true) const;
491 ItemGroupInfo
permissionRoleGroup(const ItemData
*itemData
, bool withString
= true) const;
492 ItemGroupInfo
ratingRoleGroup(const ItemData
*itemData
, bool withString
= true) const;
493 ItemGroupInfo
typeRoleGroup(const ItemData
*itemData
) const;
494 ItemGroupInfo
genericStringRoleGroup(const QByteArray
&role
, const ItemData
*itemData
) const;
496 QList
<QPair
<int, QVariant
>> nameRoleGroups() const;
497 QList
<QPair
<int, QVariant
>> sizeRoleGroups() const;
498 QList
<QPair
<int, QVariant
>> timeRoleGroups(const std::function
<QDateTime(const ItemData
*)> &fileTimeCb
) const;
499 QList
<QPair
<int, QVariant
>> permissionRoleGroups() const;
500 QList
<QPair
<int, QVariant
>> ratingRoleGroups() const;
501 QList
<QPair
<int, QVariant
>> typeRoleGroups() const;
502 QList
<QPair
<int, QVariant
>> genericStringRoleGroups(const QByteArray
&typeForRole
) const;
505 * Helper method for all xxxRoleGroups() methods to check whether the
506 * item with the given index is a child-item. A child-item is defined
507 * as item having an expansion-level > 0. All xxxRoleGroups() methods
508 * should skip the grouping if the item is a child-item (although
509 * KItemListView would be capable to show sub-groups in groups this
510 * results in visual clutter for most usecases).
512 bool isChildItem(int index
) const;
514 void scheduleResortAllItems();
517 * Is invoked by KFileItemModelRolesUpdater and results in emitting the
518 * sortProgress signal with a percent-value of the progress.
520 void emitSortProgress(int resolvedCount
);
523 * Applies the filters set through @ref setNameFilter and @ref setMimeTypeFilters.
528 * Removes filtered items whose expanded parents have been deleted
529 * or collapsed via setExpanded(parentIndex, false).
531 void removeFilteredChildren(const KItemRangeList
&parents
);
534 * Loads the selected choice of sorting method from Dolphin General Settings
536 void loadSortingSettings();
539 * Maps the QByteArray-roles to RoleTypes and provides translation- and
543 const char *const role
;
544 const RoleType roleType
;
545 const KLazyLocalizedString roleTranslation
;
546 const KLazyLocalizedString groupTranslation
;
547 const KLazyLocalizedString tooltipTranslation
;
548 const bool requiresBaloo
;
549 const bool requiresIndexer
;
553 * @return Map of user visible roles that are accessible by KFileItemModel::rolesInformation().
555 static const RoleInfoMap
*rolesInfoMap(int &count
);
558 * Determines the MIME-types of all items that can be done within
561 static void determineMimeTypes(const KFileItemList
&items
, int timeout
);
564 * @return Returns a copy of \a value that is implicitly shared
565 * with other users to save memory.
567 static QByteArray
sharedValue(const QByteArray
&value
);
570 * Checks if the model's internal data structures are consistent.
572 bool isConsistent() const;
575 * Filters out the expanded folders that don't pass the filter themselves and don't have any filter-passing children.
576 * Will update the removedItemRanges arguments to include the parents that have been filtered.
577 * @returns the number of parents that have been filtered.
578 * @param removedItemRanges The ranges of items being deleted/filtered, will get updated
579 * @param parentsToEnsureVisible Parents that must be visible no matter what due to being ancestors of newly visible items
581 int filterChildlessParents(KItemRangeList
&removedItemRanges
, const QSet
<ItemData
*> &parentsToEnsureVisible
= QSet
<ItemData
*>());
584 KDirLister
*m_dirLister
= nullptr;
586 QCollator m_collator
;
587 bool m_naturalSorting
;
588 bool m_sortDirsFirst
;
589 bool m_sortHiddenLast
;
592 RoleType m_groupRole
;
593 QByteArray m_sortExtraInfo
;
594 QByteArray m_groupExtraInfo
;
596 int m_sortingProgressPercent
; // Value of directorySortingProgress() signal
597 QSet
<QByteArray
> m_roles
;
599 QList
<ItemData
*> m_itemData
;
601 // m_items is a cache for the method index(const QUrl&). If it contains N
602 // entries, it is guaranteed that these correspond to the first N items in
603 // the model, i.e., that (for every i between 0 and N - 1)
604 // m_items.value(fileItem(i).url()) == i
605 mutable QHash
<QUrl
, int> m_items
;
607 KFileItemModelFilter m_filter
;
608 QHash
<KFileItem
, ItemData
*> m_filteredItems
; // Items that got hidden by KFileItemModel::setNameFilter()
610 bool m_requestRole
[RolesCount
];
612 QTimer
*m_maximumUpdateIntervalTimer
;
613 QTimer
*m_resortAllItemsTimer
;
614 QList
<ItemData
*> m_pendingItemsToInsert
;
616 // Cache for KFileItemModel::groups()
617 mutable QList
<QPair
<int, QVariant
>> m_groups
;
619 // Stores the URLs (key: target url, value: url) of the expanded directories.
620 QHash
<QUrl
, QUrl
> m_expandedDirs
;
622 // URLs that must be expanded. The expanding is initially triggered in setExpanded()
623 // and done step after step in slotCompleted().
624 QSet
<QUrl
> m_urlsToExpand
;
626 friend class KFileItemModelRolesUpdater
; // Accesses emitSortProgress() method
627 friend class KFileItemModelTest
; // For unit testing
628 friend class KFileItemModelBenchmark
; // For unit testing
629 friend class KFileItemListViewTest
; // For unit testing
630 friend class DolphinPart
; // Accesses m_dirLister
633 inline bool KFileItemModel::isRoleValueNatural(RoleType roleType
)
635 return (roleType
== TypeRole
|| roleType
== ExtensionRole
|| roleType
== TagsRole
|| roleType
== CommentRole
|| roleType
== TitleRole
636 || roleType
== ArtistRole
|| roleType
== GenreRole
|| roleType
== AlbumRole
|| roleType
== PathRole
|| roleType
== DestinationRole
637 || roleType
== OriginUrlRole
|| roleType
== OwnerRole
|| roleType
== GroupRole
);
640 inline bool KFileItemModel::nameLessThan(const ItemData
*a
, const ItemData
*b
)
642 // Split extension, taking into account it can be empty
643 constexpr QString::SectionFlags flags
= QString::SectionSkipEmpty
| QString::SectionIncludeLeadingSep
;
644 return a
->item
.text().section('.', 0, 0, flags
) < b
->item
.text().section('.', 0, 0, flags
);
647 inline bool KFileItemModel::isChildItem(int index
) const
649 if (m_itemData
.at(index
)->parent
) {
656 inline bool KFileItemModel::ItemGroupInfo::operator==(const ItemGroupInfo
&other
) const
658 return comparable
== other
.comparable
&& text
== other
.text
;
661 inline bool KFileItemModel::ItemGroupInfo::operator!=(const ItemGroupInfo
&other
) const
663 return comparable
!= other
.comparable
|| text
!= other
.text
;