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