src/kitemviews/kfileitemmodel.h

   1 /*
   2  * SPDX-FileCopyrightText: 2011 Peter Penz <peter.penz19@gmail.com>
   3  *
   4  * SPDX-License-Identifier: GPL-2.0-or-later
   5  */
   6
   7 #ifndef KFILEITEMMODEL_H
   8 #define KFILEITEMMODEL_H
   9
  10 #include "dolphin_export.h"
  11 #include "kitemviews/kitemmodelbase.h"
  12 #include "kitemviews/private/kfileitemmodelfilter.h"
  13
  14 #include <KFileItem>
  15 #include <KLazyLocalizedString>
  16
  17 #include <QCollator>
  18 #include <QHash>
  19 #include <QSet>
  20 #include <QUrl>
  21
  22 #include <functional>
  23
  24 class KDirLister;
  25
  26 class QTimer;
  27
  28 namespace KIO {
  29     class Job;
  30 }
  31
  32 /**
  33  * @brief KItemModelBase implementation for KFileItems.
  34  *
  35  * Allows to load items of a directory. Sorting and grouping of
  36  * items are supported. Roles that are not part of KFileItem can
  37  * be added with KFileItemModel::setData().
  38  *
  39  * Recursive expansion of sub-directories is supported by
  40  * KFileItemModel::setExpanded().
  41  */
  42 class DOLPHIN_EXPORT KFileItemModel : public KItemModelBase
  43 {
  44     Q_OBJECT
  45
  46 public:
  47     explicit KFileItemModel(QObject* parent = nullptr);
  48     ~KFileItemModel() override;
  49
  50     /**
  51      * Loads the directory specified by \a url. The signals
  52      * directoryLoadingStarted(), directoryLoadingProgress() and directoryLoadingCompleted()
  53      * indicate the current state of the loading process. The items
  54      * of the directory are added after the loading has been completed.
  55      */
  56     void loadDirectory(const QUrl& url);
  57
  58     /**
  59      * Throws away all currently loaded items and refreshes the directory
  60      * by reloading all items again.
  61      */
  62     void refreshDirectory(const QUrl& url);
  63
  64     /**
  65      * @return Parent directory of the items that are shown. In case
  66      *         if a directory tree is shown, KFileItemModel::dir() returns
  67      *         the root-parent of all items.
  68      * @see rootItem()
  69      */
  70     QUrl directory() const override;
  71
  72     /**
  73      * Cancels the loading of a directory which has been started by either
  74      * loadDirectory() or refreshDirectory().
  75      */
  76     void cancelDirectoryLoading();
  77
  78     int count() const override;
  79     QHash<QByteArray, QVariant> data(int index) const override;
  80     bool setData(int index, const QHash<QByteArray, QVariant>& values) override;
  81
  82     /**
  83      * Sets a separate sorting with directories first (true) or a mixed
  84      * sorting of files and directories (false).
  85      */
  86     void setSortDirectoriesFirst(bool dirsFirst);
  87     bool sortDirectoriesFirst() const;
  88
  89     /**
  90      * Sets a separate sorting with hidden files and folders last (true) or not (false).
  91      */
  92     void setSortHiddenLast(bool hiddenLast);
  93     bool sortHiddenLast() const;
  94
  95     void setShowHiddenFiles(bool show);
  96     bool showHiddenFiles() const;
  97
  98     /**
  99      * If set to true, only directories are shown as items of the model. Files
 100      * are ignored.
 101      */
 102     void setShowDirectoriesOnly(bool enabled);
 103     bool showDirectoriesOnly() const;
 104
 105     QMimeData* createMimeData(const KItemSet& indexes) const override;
 106
 107     int indexForKeyboardSearch(const QString& text, int startFromIndex = 0) const override;
 108
 109     bool supportsDropping(int index) const override;
 110
 111     QString roleDescription(const QByteArray& role) const override;
 112
 113     QList<QPair<int, QVariant> > groups() const override;
 114
 115     /**
 116      * @return The file-item for the index \a index. If the index is in a valid
 117      *         range it is assured that the file-item is not null. The runtime
 118      *         complexity of this call is O(1).
 119      */
 120     KFileItem fileItem(int index) const;
 121
 122     /**
 123      * @return The file-item for the url \a url. If no file-item with the given
 124      *         URL is found KFileItem::isNull() will be true for the returned
 125      *         file-item. The runtime complexity of this call is O(1).
 126      */
 127     KFileItem fileItem(const QUrl& url) const;
 128
 129     /**
 130      * @return The index for the file-item \a item. -1 is returned if no file-item
 131      *         is found or if the file-item is null. The amortized runtime
 132      *         complexity of this call is O(1).
 133      */
 134     int index(const KFileItem& item) const;
 135
 136     /**
 137      * @return The index for the URL \a url. -1 is returned if no file-item
 138      *         is found. The amortized runtime complexity of this call is O(1).
 139      */
 140     int index(const QUrl &url) const;
 141
 142     /**
 143      * @return Root item of all items representing the item
 144      *         for KFileItemModel::dir().
 145      */
 146     KFileItem rootItem() const;
 147
 148     /**
 149      * Clears all items of the model.
 150      */
 151     void clear();
 152
 153     /**
 154      * Sets the roles that should be shown for each item.
 155      */
 156     void setRoles(const QSet<QByteArray>& roles);
 157     QSet<QByteArray> roles() const;
 158
 159     bool setExpanded(int index, bool expanded) override;
 160     bool isExpanded(int index) const override;
 161     bool isExpandable(int index) const override;
 162     int expandedParentsCount(int index) const override;
 163
 164     QSet<QUrl> expandedDirectories() const;
 165
 166     /**
 167      * Marks the URLs in \a urls as sub-directories which were expanded previously.
 168      * After calling loadDirectory() or refreshDirectory() the marked sub-directories
 169      * will be expanded step-by-step.
 170      */
 171     void restoreExpandedDirectories(const QSet<QUrl>& urls);
 172
 173     /**
 174      * Expands all parent-directories of the item \a url.
 175      */
 176     void expandParentDirectories(const QUrl& url);
 177
 178     void setNameFilter(const QString& nameFilter);
 179     QString nameFilter() const;
 180
 181     void setMimeTypeFilters(const QStringList& filters);
 182     QStringList mimeTypeFilters() const;
 183
 184     struct RoleInfo
 185     {   QByteArray role;
 186         QString translation;
 187         QString group;
 188         bool requiresBaloo;
 189         bool requiresIndexer;
 190     };
 191
 192     /**
 193      * @return Provides static information for all available roles that
 194      *         are supported by KFileItemModel. Some roles can only be
 195      *         determined if Baloo is enabled and/or the Baloo
 196      *         indexing is enabled.
 197      */
 198     static QList<RoleInfo> rolesInformation();
 199
 200 Q_SIGNALS:
 201     /**
 202      * Is emitted if the loading of a directory has been started. It is
 203      * assured that a signal directoryLoadingCompleted() will be send after
 204      * the loading has been finished. For tracking the loading progress
 205      * the signal directoryLoadingProgress() gets emitted in between.
 206      */
 207     void directoryLoadingStarted();
 208
 209     /**
 210      * Is emitted after the loading of a directory has been completed or new
 211      * items have been inserted to an already loaded directory. Usually
 212      * one or more itemsInserted() signals are emitted before loadingCompleted()
 213      * (the only exception is loading an empty directory, where only a
 214      * loadingCompleted() signal gets emitted).
 215      */
 216     void directoryLoadingCompleted();
 217
 218     /**
 219      * Is emitted after the loading of a directory has been canceled.
 220      */
 221     void directoryLoadingCanceled();
 222
 223     /**
 224      * Informs about the progress in percent when loading a directory. It is assured
 225      * that the signal directoryLoadingStarted() has been emitted before.
 226      */
 227     void directoryLoadingProgress(int percent);
 228
 229     /**
 230      * Is emitted if the sort-role gets resolved asynchronously and provides
 231      * the progress-information of the sorting in percent. It is assured
 232      * that the last sortProgress-signal contains 100 as value.
 233      */
 234     void directorySortingProgress(int percent);
 235
 236     /**
 237      * Is emitted if an information message (e.g. "Connecting to host...")
 238      * should be shown.
 239      */
 240     void infoMessage(const QString& message);
 241
 242     /**
 243      * Is emitted if an error message (e.g. "Unknown location")
 244      * should be shown.
 245      */
 246     void errorMessage(const QString& message);
 247
 248     /**
 249      * Is emitted if a redirection from the current URL \a oldUrl
 250      * to the new URL \a newUrl has been done.
 251      */
 252     void directoryRedirection(const QUrl& oldUrl, const QUrl& newUrl);
 253
 254     /**
 255      * Is emitted when the URL passed by KFileItemModel::setUrl() represents a file.
 256      * In this case no signal errorMessage() will be emitted.
 257      */
 258     void urlIsFileError(const QUrl& url);
 259
 260     /**
 261      * It is emitted for files when they change and
 262      * for dirs when files are added or removed.
 263      */
 264     void fileItemsChanged(const KFileItemList &changedFileItems);
 265
 266     /**
 267      * It is emitted when the parent directory was removed.
 268      */
 269     void currentDirectoryRemoved();
 270
 271 protected:
 272     void onGroupedSortingChanged(bool current) override;
 273     void onSortRoleChanged(const QByteArray& current, const QByteArray& previous, bool resortItems = true) override;
 274     void onSortOrderChanged(Qt::SortOrder current, Qt::SortOrder previous) override;
 275
 276 private Q_SLOTS:
 277     /**
 278      * Resorts all items dependent on the set sortRole(), sortOrder()
 279      * and foldersFirst() settings.
 280      */
 281     void resortAllItems();
 282
 283     void slotCompleted();
 284     void slotCanceled();
 285     void slotItemsAdded(const QUrl& directoryUrl, const KFileItemList& items);
 286     void slotItemsDeleted(const KFileItemList& items);
 287     void slotRefreshItems(const QList<QPair<KFileItem, KFileItem> >& items);
 288     void slotClear();
 289     void slotSortingChoiceChanged();
 290     void slotListerError(KIO::Job *job);
 291
 292     void dispatchPendingItemsToInsert();
 293
 294 private:
 295     enum RoleType {
 296         // User visible roles:
 297         NoRole, NameRole, SizeRole, ModificationTimeRole, CreationTimeRole, AccessTimeRole, PermissionsRole, OwnerRole,
 298         GroupRole, TypeRole, ExtensionRole, DestinationRole, PathRole, DeletionTimeRole,
 299         // User visible roles available with Baloo:
 300         CommentRole, TagsRole, RatingRole, DimensionsRole, WidthRole, HeightRole, ImageDateTimeRole, OrientationRole,
 301         WordCountRole, TitleRole, AuthorRole, LineCountRole, ArtistRole, GenreRole, AlbumRole, DurationRole, TrackRole, ReleaseYearRole,
 302         BitrateRole, OriginUrlRole, AspectRatioRole, FrameRateRole,
 303         // Non-visible roles:
 304         IsDirRole, IsLinkRole, IsHiddenRole, IsExpandedRole, IsExpandableRole, ExpandedParentsCountRole,
 305         // Mandatory last entry:
 306         RolesCount
 307     };
 308
 309     struct ItemData
 310     {
 311         KFileItem item;
 312         QHash<QByteArray, QVariant> values;
 313         ItemData* parent;
 314     };
 315
 316     enum RemoveItemsBehavior {
 317         KeepItemData,
 318         DeleteItemData,
 319         DeleteItemDataIfUnfiltered
 320     };
 321
 322     void insertItems(QList<ItemData*>& items);
 323     void removeItems(const KItemRangeList& itemRanges, RemoveItemsBehavior behavior);
 324
 325     /**
 326      * Helper method for insertItems() and removeItems(): Creates
 327      * a list of ItemData elements based on the given items.
 328      * Note that the ItemData instances are created dynamically and
 329      * must be deleted by the caller.
 330      */
 331     QList<ItemData*> createItemDataList(const QUrl& parentUrl, const KFileItemList& items) const;
 332
 333     /**
 334      * Prepares the items for sorting. Normally, the hash 'values' in ItemData is filled
 335      * lazily to save time and memory, but for some sort roles, it is expected that the
 336      * sort role data is stored in 'values'.
 337      */
 338     void prepareItemsForSorting(QList<ItemData*>& itemDataList);
 339
 340     static int expandedParentsCount(const ItemData* data);
 341
 342     void removeExpandedItems();
 343
 344     /**
 345      * This function is called by setData() and slotRefreshItems(). It emits
 346      * the itemsChanged() signal, checks if the sort order is still correct,
 347      * and starts m_resortAllItemsTimer if that is not the case.
 348      */
 349     void emitItemsChangedAndTriggerResorting(const KItemRangeList& itemRanges, const QSet<QByteArray>& changedRoles);
 350
 351     /**
 352      * Resets all values from m_requestRole to false.
 353      */
 354     void resetRoles();
 355
 356     /**
 357      * @return Role-type for the given role.
 358      *         Runtime complexity is O(1).
 359      */
 360     RoleType typeForRole(const QByteArray& role) const;
 361
 362     /**
 363      * @return Role-byte-array for the given role-type.
 364      *         Runtime complexity is O(1).
 365      */
 366     QByteArray roleForType(RoleType roleType) const;
 367
 368     QHash<QByteArray, QVariant> retrieveData(const KFileItem& item, const ItemData* parent) const;
 369
 370     /**
 371      * @return True if role values benefit from natural or case insensitive sorting.
 372      */
 373     static bool isRoleValueNatural(const RoleType roleType);
 374
 375     /**
 376      * @return True if \a a has a KFileItem whose text is 'less than' the one
 377      *         of \a b according to QString::operator<(const QString&).
 378      */
 379     static bool nameLessThan(const ItemData* a, const ItemData* b);
 380
 381     /**
 382      * @return True if the item-data \a a should be ordered before the item-data
 383      *         \b. The item-data may have different parent-items.
 384      */
 385     bool lessThan(const ItemData* a, const ItemData* b, const QCollator& collator) const;
 386
 387     /**
 388      * Sorts the items between \a begin and \a end using the comparison
 389      * function lessThan().
 390      */
 391     void sort(const QList<ItemData*>::iterator &begin, const QList<ItemData*>::iterator &end) const;
 392
 393     /**
 394      * Helper method for lessThan() and expandedParentsCountCompare(): Compares
 395      * the passed item-data using m_sortRole as criteria. Both items must
 396      * have the same parent item, otherwise the comparison will be wrong.
 397      */
 398     int sortRoleCompare(const ItemData* a, const ItemData* b, const QCollator& collator) const;
 399
 400     int stringCompare(const QString& a, const QString& b, const QCollator& collator) const;
 401
 402     QList<QPair<int, QVariant> > nameRoleGroups() const;
 403     QList<QPair<int, QVariant> > sizeRoleGroups() const;
 404     QList<QPair<int, QVariant> > timeRoleGroups(const std::function<QDateTime(const ItemData *)> &fileTimeCb) const;
 405     QList<QPair<int, QVariant> > permissionRoleGroups() const;
 406     QList<QPair<int, QVariant> > ratingRoleGroups() const;
 407     QList<QPair<int, QVariant> > genericStringRoleGroups(const QByteArray& typeForRole) const;
 408
 409     /**
 410      * Helper method for all xxxRoleGroups() methods to check whether the
 411      * item with the given index is a child-item. A child-item is defined
 412      * as item having an expansion-level > 0. All xxxRoleGroups() methods
 413      * should skip the grouping if the item is a child-item (although
 414      * KItemListView would be capable to show sub-groups in groups this
 415      * results in visual clutter for most usecases).
 416      */
 417     bool isChildItem(int index) const;
 418
 419     /**
 420      * Is invoked by KFileItemModelRolesUpdater and results in emitting the
 421      * sortProgress signal with a percent-value of the progress.
 422      */
 423     void emitSortProgress(int resolvedCount);
 424
 425     /**
 426      * Applies the filters set through @ref setNameFilter and @ref setMimeTypeFilters.
 427      */
 428     void applyFilters();
 429
 430     /**
 431      * Removes filtered items whose expanded parents have been deleted
 432      * or collapsed via setExpanded(parentIndex, false).
 433      */
 434     void removeFilteredChildren(const KItemRangeList& parents);
 435
 436     /**
 437      * Loads the selected choice of sorting method from Dolphin General Settings
 438      */
 439     void loadSortingSettings();
 440
 441     /**
 442      * Maps the QByteArray-roles to RoleTypes and provides translation- and
 443      * group-contexts.
 444      */
 445     struct RoleInfoMap
 446     {
 447         const char* const role;
 448         const RoleType roleType;
 449         const KLazyLocalizedString roleTranslation;
 450         const KLazyLocalizedString groupTranslation;
 451         const bool requiresBaloo;
 452         const bool requiresIndexer;
 453     };
 454
 455     /**
 456      * @return Map of user visible roles that are accessible by KFileItemModel::rolesInformation().
 457      */
 458     static const RoleInfoMap* rolesInfoMap(int& count);
 459
 460     /**
 461      * Determines the MIME-types of all items that can be done within
 462      * the given timeout.
 463      */
 464     static void determineMimeTypes(const KFileItemList& items, int timeout);
 465
 466     /**
 467      * @return Returns a copy of \a value that is implicitly shared
 468      * with other users to save memory.
 469      */
 470     static QByteArray sharedValue(const QByteArray& value);
 471
 472     /**
 473      * Checks if the model's internal data structures are consistent.
 474      */
 475     bool isConsistent() const;
 476
 477     /**
 478      * Filters out the expanded folders that don't pass the filter themselves and don't have any filter-passing children.
 479      * Will update the removedItemRanges arguments to include the parents that have been filtered.
 480      * @returns the number of parents that have been filtered.
 481      * @param removedItemRanges The ranges of items being deleted/filtered, will get updated
 482      * @param parentsToEnsureVisible Parents that must be visible no matter what due to being ancestors of newly visible items
 483      */
 484     int filterChildlessParents(KItemRangeList &removedItemRanges, const QSet<ItemData *> &parentsToEnsureVisible = QSet<ItemData *>());
 485
 486 private:
 487     KDirLister *m_dirLister = nullptr;
 488
 489     QCollator m_collator;
 490     bool m_naturalSorting;
 491     bool m_sortDirsFirst;
 492     bool m_sortHiddenLast;
 493
 494     RoleType m_sortRole;
 495     int m_sortingProgressPercent; // Value of directorySortingProgress() signal
 496     QSet<QByteArray> m_roles;
 497
 498     QList<ItemData*> m_itemData;
 499
 500     // m_items is a cache for the method index(const QUrl&). If it contains N
 501     // entries, it is guaranteed that these correspond to the first N items in
 502     // the model, i.e., that (for every i between 0 and N - 1)
 503     // m_items.value(fileItem(i).url()) == i
 504     mutable QHash<QUrl, int> m_items;
 505
 506     KFileItemModelFilter m_filter;
 507     QHash<KFileItem, ItemData*> m_filteredItems; // Items that got hidden by KFileItemModel::setNameFilter()
 508
 509     bool m_requestRole[RolesCount];
 510
 511     QTimer* m_maximumUpdateIntervalTimer;
 512     QTimer* m_resortAllItemsTimer;
 513     QList<ItemData*> m_pendingItemsToInsert;
 514
 515     // Cache for KFileItemModel::groups()
 516     mutable QList<QPair<int, QVariant> > m_groups;
 517
 518     // Stores the URLs (key: target url, value: url) of the expanded directories.
 519     QHash<QUrl, QUrl> m_expandedDirs;
 520
 521     // URLs that must be expanded. The expanding is initially triggered in setExpanded()
 522     // and done step after step in slotCompleted().
 523     QSet<QUrl> m_urlsToExpand;
 524
 525     friend class KFileItemModelRolesUpdater;   // Accesses emitSortProgress() method
 526     friend class KFileItemModelTest;           // For unit testing
 527     friend class KFileItemModelBenchmark;      // For unit testing
 528     friend class KFileItemListViewTest;        // For unit testing
 529     friend class DolphinPart;                  // Accesses m_dirLister
 530 };
 531
 532 inline bool KFileItemModel::isRoleValueNatural(RoleType roleType)
 533 {
 534     return (roleType == TypeRole ||
 535             roleType == ExtensionRole ||
 536             roleType == TagsRole ||
 537             roleType == CommentRole ||
 538             roleType == TitleRole ||
 539             roleType == ArtistRole ||
 540             roleType == GenreRole ||
 541             roleType == AlbumRole ||
 542             roleType == PathRole ||
 543             roleType == DestinationRole ||
 544             roleType == OriginUrlRole ||
 545             roleType == OwnerRole ||
 546             roleType == GroupRole);
 547 }
 548
 549 inline bool KFileItemModel::nameLessThan(const ItemData* a, const ItemData* b)
 550 {
 551     return a->item.text() < b->item.text();
 552 }
 553
 554 inline bool KFileItemModel::isChildItem(int index) const
 555 {
 556     if (m_itemData.at(index)->parent) {
 557         return true;
 558     } else {
 559         return false;
 560     }
 561 }
 562
 563 #endif
 564
 565