src/kitemviews/kfileitemmodel.h

   1 /***************************************************************************
   2  *   Copyright (C) 2011 by Peter Penz <peter.penz19@gmail.com>             *
   3  *                                                                         *
   4  *   This program is free software; you can redistribute it and/or modify  *
   5  *   it under the terms of the GNU General Public License as published by  *
   6  *   the Free Software Foundation; either version 2 of the License, or     *
   7  *   (at your option) any later version.                                   *
   8  *                                                                         *
   9  *   This program is distributed in the hope that it will be useful,       *
  10  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  11  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  12  *   GNU General Public License for more details.                          *
  13  *                                                                         *
  14  *   You should have received a copy of the GNU General Public License     *
  15  *   along with this program; if not, write to the                         *
  16  *   Free Software Foundation, Inc.,                                       *
  17  *   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA            *
  18  ***************************************************************************/
  19
  20 #ifndef KFILEITEMMODEL_H
  21 #define KFILEITEMMODEL_H
  22
  23 #include <libdolphin_export.h>
  24 #include <KFileItemList>
  25 #include <KUrl>
  26 #include <kitemviews/kfileitemmodelfilter_p.h>
  27 #include <kitemviews/kitemmodelbase.h>
  28
  29 #include <QHash>
  30
  31 class KDirLister;
  32 class QTimer;
  33
  34 /**
  35  * @brief KItemModelBase implementation for KFileItems.
  36  *
  37  * KFileItemModel is connected with one KDirLister. Each time the KDirLister
  38  * emits new items, removes items or changes items the model gets synchronized.
  39  *
  40  * KFileItemModel supports sorting and grouping of items. Additional roles that
  41  * are not part of KFileItem can be added with KFileItemModel::setData().
  42  *
  43  * Also the recursive expansion of sub-directories is supported by
  44  * KFileItemModel::setExpanded().
  45  *
  46  * TODO: In the longterm instead of passing a KDirLister just an URL should
  47  * be passed and a KDirLister used internally. This solves the following issues:
  48  * - The user of the API does not need to decide whether he listens to KDirLister
  49  *   or KFileItemModel.
  50  * - It resolves minor conceptual differences between KDirLister and KFileItemModel.
  51  *   E.g. there is no way for KFileItemModel to check whether a completed() signal
  52  *   will be emitted after newItems() will be send by KDirLister or not (in the case
  53  *   of setShowingDotFiles() no completed() signal will get emitted).
  54  */
  55 class LIBDOLPHINPRIVATE_EXPORT KFileItemModel : public KItemModelBase
  56 {
  57     Q_OBJECT
  58
  59 public:
  60     explicit KFileItemModel(KDirLister* dirLister, QObject* parent = 0);
  61     virtual ~KFileItemModel();
  62
  63     virtual int count() const;
  64     virtual QHash<QByteArray, QVariant> data(int index) const;
  65     virtual bool setData(int index, const QHash<QByteArray, QVariant>& values);
  66
  67     /**
  68      * Sets a separate sorting with folders first (true) or a mixed sorting of files and folders (false).
  69      */
  70     void setSortFoldersFirst(bool foldersFirst);
  71     bool sortFoldersFirst() const;
  72
  73     void setShowHiddenFiles(bool show);
  74     bool showHiddenFiles() const;
  75
  76     /**
  77      * If set to true, only folders are shown as items of the model. Files
  78      * are ignored.
  79      */
  80     void setShowFoldersOnly(bool enabled);
  81     bool showFoldersOnly() const;
  82
  83     /** @reimp */
  84     virtual QMimeData* createMimeData(const QSet<int>& indexes) const;
  85
  86     /** @reimp */
  87     virtual int indexForKeyboardSearch(const QString& text, int startFromIndex = 0) const;
  88
  89     /** @reimp */
  90     virtual bool supportsDropping(int index) const;
  91
  92     /** @reimp */
  93     virtual QString roleDescription(const QByteArray& typeForRole) const;
  94
  95     /** @reimp */
  96     virtual QList<QPair<int, QVariant> > groups() const;
  97
  98     /**
  99      * @return The file-item for the index \a index. If the index is in a valid
 100      *         range it is assured that the file-item is not null. The runtime
 101      *         complexity of this call is O(1).
 102      */
 103     KFileItem fileItem(int index) const;
 104
 105     /**
 106      * @return The file-item for the url \a url. If no file-item with the given
 107      *         URL is found KFileItem::isNull() will be true for the returned
 108      *         file-item. The runtime complexity of this call is O(1).
 109      */
 110     KFileItem fileItem(const KUrl& url) const;
 111
 112     /**
 113      * @return The index for the file-item \a item. -1 is returned if no file-item
 114      *         is found or if the file-item is null. The runtime
 115      *         complexity of this call is O(1).
 116      */
 117     int index(const KFileItem& item) const;
 118
 119     /**
 120      * @return The index for the URL \a url. -1 is returned if no file-item
 121      *         is found. The runtime complexity of this call is O(1).
 122      */
 123     int index(const KUrl& url) const;
 124
 125     /**
 126      * @return Root item of all items.
 127      */
 128     KFileItem rootItem() const;
 129
 130     /**
 131      * Clears all items of the model.
 132      */
 133     void clear();
 134
 135     // TODO: "name" + "isDir" is default in ctor
 136     void setRoles(const QSet<QByteArray>& roles);
 137     QSet<QByteArray> roles() const;
 138
 139     virtual bool setExpanded(int index, bool expanded);
 140     virtual bool isExpanded(int index) const;
 141     virtual bool isExpandable(int index) const;
 142     virtual int expandedParentsCount(int index) const;
 143
 144     QSet<KUrl> expandedUrls() const;
 145
 146     /**
 147      * Marks the URLs in \a urls as subfolders which were expanded previously.
 148      * They are re-expanded one by one each time the KDirLister's completed() signal is received.
 149      * Note that a manual triggering of the KDirLister is required.
 150      */
 151     void restoreExpandedUrls(const QSet<KUrl>& urls);
 152
 153     /**
 154      * Expands all parent-items of \a url.
 155      */
 156     void expandParentItems(const KUrl& url);
 157
 158     void setNameFilter(const QString& nameFilter);
 159     QString nameFilter() const;
 160
 161     struct RoleInfo
 162     {   QByteArray role;
 163         QString translation;
 164         QString group;
 165         bool requiresNepomuk;
 166         bool requiresIndexer;
 167     };
 168
 169     /**
 170      * @return Provides static information for all available roles that
 171      *         are supported by KFileItemModel. Some roles can only be
 172      *         determined if Nepomuk is enabled and/or the Nepomuk
 173      *         indexing is enabled.
 174      */
 175     static QList<RoleInfo> rolesInformation();
 176
 177 signals:
 178     /**
 179      * Is emitted after the loading of a directory has been completed or new
 180      * items have been inserted to an already loaded directory. Usually
 181      * one or more itemsInserted() signals are emitted before loadingCompleted()
 182      * (the only exception is loading an empty directory, where only a
 183      * loadingCompleted() signal gets emitted).
 184      */
 185     void loadingCompleted();
 186
 187     /**
 188      * Is emitted if the sort-role gets resolved asynchronously and provides
 189      * the progress-information of the sorting in percent. It is assured
 190      * that the last sortProgress-signal contains 100 as value.
 191      */
 192     void sortProgress(int percent);
 193
 194 protected:
 195     virtual void onGroupedSortingChanged(bool current);
 196     virtual void onSortRoleChanged(const QByteArray& current, const QByteArray& previous);
 197     virtual void onSortOrderChanged(Qt::SortOrder current, Qt::SortOrder previous);
 198
 199 private slots:
 200     /**
 201      * Resorts all items dependent on the set sortRole(), sortOrder()
 202      * and foldersFirst() settings.
 203      */
 204     void resortAllItems();
 205
 206     void slotCompleted();
 207     void slotCanceled();
 208     void slotNewItems(const KFileItemList& items);
 209     void slotItemsDeleted(const KFileItemList& items);
 210     void slotRefreshItems(const QList<QPair<KFileItem, KFileItem> >& items);
 211     void slotClear();
 212     void slotClear(const KUrl& url);
 213     void slotNaturalSortingChanged();
 214
 215     void dispatchPendingItemsToInsert();
 216
 217 private:
 218     enum RoleType {
 219         // User visible roles:
 220         NoRole, NameRole, SizeRole, DateRole, PermissionsRole, OwnerRole,
 221         GroupRole, TypeRole, DestinationRole, PathRole,
 222         // User visible roles available with Nepomuk:
 223         CommentRole, TagsRole, RatingRole, ImageSizeRole, OrientationRole,
 224         WordCountRole, LineCountRole, ArtistRole, AlbumRole, DurationRole, TrackRole,
 225         CopiedFromRole,
 226         // Non-visible roles:
 227         IsDirRole, IsExpandedRole, IsExpandableRole, ExpandedParentsCountRole,
 228         // Mandatory last entry:
 229         RolesCount
 230     };
 231
 232     struct ItemData
 233     {
 234         KFileItem item;
 235         QHash<QByteArray, QVariant> values;
 236         ItemData* parent;
 237     };
 238
 239     void insertItems(const KFileItemList& items);
 240     void removeItems(const KFileItemList& items);
 241
 242     /**
 243      * Helper method for insertItems() and removeItems(): Creates
 244      * a list of ItemData elements based on the given items.
 245      * Note that the ItemData instances are created dynamically and
 246      * must be deleted by the caller.
 247      */
 248     QList<ItemData*> createItemDataList(const KFileItemList& items) const;
 249
 250     void removeExpandedItems();
 251
 252     /**
 253      * Resets all values from m_requestRole to false.
 254      */
 255     void resetRoles();
 256
 257     /**
 258      * @return Role-type for the given role.
 259      *         Runtime complexity is O(1).
 260      */
 261     RoleType typeForRole(const QByteArray& role) const;
 262
 263     /**
 264      * @return Role-byte-array for the given role-type.
 265      *         Runtime complexity is O(1).
 266      */
 267     QByteArray roleForType(RoleType roleType) const;
 268
 269     QHash<QByteArray, QVariant> retrieveData(const KFileItem& item) const;
 270
 271     /**
 272      * @return True if the item-data \a a should be ordered before the item-data
 273      *         \b. The item-data may have different parent-items.
 274      */
 275     bool lessThan(const ItemData* a, const ItemData* b) const;
 276
 277     /**
 278      * Helper method for lessThan() and expandedParentsCountCompare(): Compares
 279      * the passed item-data using m_sortRole as criteria. Both items must
 280      * have the same parent item, otherwise the comparison will be wrong.
 281      */
 282     int sortRoleCompare(const ItemData* a, const ItemData* b) const;
 283
 284     int stringCompare(const QString& a, const QString& b) const;
 285
 286     /**
 287      * Compares the expansion level of both items. The "expansion level" is defined
 288      * by the number of parent directories. However simply comparing just the numbers
 289      * is not sufficient, it is also important to check the hierarchy for having
 290      * a correct order like shown in a tree.
 291      */
 292     int expandedParentsCountCompare(const ItemData* a, const ItemData* b) const;
 293
 294     /**
 295      * Helper method for expandedParentsCountCompare().
 296      */
 297     QString subPath(const KFileItem& item,
 298                     const QString& itemPath,
 299                     int start,
 300                     bool* isDir) const;
 301
 302     bool useMaximumUpdateInterval() const;
 303
 304     QList<QPair<int, QVariant> > nameRoleGroups() const;
 305     QList<QPair<int, QVariant> > sizeRoleGroups() const;
 306     QList<QPair<int, QVariant> > dateRoleGroups() const;
 307     QList<QPair<int, QVariant> > permissionRoleGroups() const;
 308     QList<QPair<int, QVariant> > ratingRoleGroups() const;
 309     QList<QPair<int, QVariant> > genericStringRoleGroups(const QByteArray& typeForRole) const;
 310
 311     /**
 312      * Helper method for all xxxRoleGroups() methods to check whether the
 313      * item with the given index is a child-item. A child-item is defined
 314      * as item having an expansion-level > 0. All xxxRoleGroups() methods
 315      * should skip the grouping if the item is a child-item (although
 316      * KItemListView would be capable to show sub-groups in groups this
 317      * results in visual clutter for most usecases).
 318      */
 319     bool isChildItem(int index) const;
 320
 321     /**
 322      * @return Recursive list of child items that have \a item as upper most parent.
 323      */
 324     KFileItemList childItems(const KFileItem& item) const;
 325
 326     /**
 327      * Is invoked by KFileItemModelRolesUpdater and results in emitting the
 328      * sortProgress signal with a percent-value of the progress.
 329      */
 330     void emitSortProgress(int resolvedCount);
 331
 332     /**
 333      * Maps the QByteArray-roles to RoleTypes and provides translation- and
 334      * group-contexts.
 335      */
 336     struct RoleInfoMap
 337     {
 338         const char* const role;
 339         const RoleType roleType;
 340         const char* const roleTranslationContext;
 341         const char* const roleTranslation;
 342         const char* const groupTranslationContext;
 343         const char* const groupTranslation;
 344         const bool requiresNepomuk;
 345         const bool requiresIndexer;
 346     };
 347
 348     /**
 349      * @return Map of user visible roles that are accessible by KFileItemModel::rolesInformation().
 350      */
 351     static const RoleInfoMap* rolesInfoMap(int& count);
 352
 353     /**
 354      * Determines the MIME-types of all items that can be done within
 355      * the given timeout.
 356      */
 357     static void determineMimeTypes(const KFileItemList& items, int timeout);
 358
 359 private:
 360     QWeakPointer<KDirLister> m_dirLister;
 361
 362     bool m_naturalSorting;
 363     bool m_sortFoldersFirst;
 364
 365     RoleType m_sortRole;
 366     int m_sortProgressPercent; // Value of sortProgress() signal
 367     QSet<QByteArray> m_roles;
 368     Qt::CaseSensitivity m_caseSensitivity;
 369
 370     QList<ItemData*> m_itemData;
 371     QHash<KUrl, int> m_items; // Allows O(1) access for KFileItemModel::index(const KFileItem& item)
 372
 373     KFileItemModelFilter m_filter;
 374     QSet<KFileItem> m_filteredItems; // Items that got hidden by KFileItemModel::setNameFilter()
 375
 376     bool m_requestRole[RolesCount];
 377
 378     QTimer* m_maximumUpdateIntervalTimer;
 379     QTimer* m_resortAllItemsTimer;
 380     KFileItemList m_pendingItemsToInsert;
 381
 382     // Cache for KFileItemModel::groups()
 383     mutable QList<QPair<int, QVariant> > m_groups;
 384
 385     // Stores the smallest expansion level of the root-URL. Is required to calculate
 386     // the "expandedParentsCount" role in an efficient way. A value < 0 indicates a
 387     // special meaning:
 388     enum ExpandedParentsCountRootTypes
 389     {
 390         // m_expandedParentsCountRoot is uninitialized and must be determined by checking
 391         // the root URL from the KDirLister.
 392         UninitializedExpandedParentsCountRoot = -1,
 393         // All items should be forced to get an expanded parents count of 0 even if they
 394         // represent child items. This is useful for slaves that provide no parent items
 395         // for child items like e.g. the search IO slaves.
 396         ForceExpandedParentsCountRoot = -2
 397     };
 398     mutable int m_expandedParentsCountRoot;
 399
 400     // Stores the URLs of the expanded folders.
 401     QSet<KUrl> m_expandedUrls;
 402
 403     // URLs that must be expanded. The expanding is initially triggered in setExpanded()
 404     // and done step after step in slotCompleted().
 405     QSet<KUrl> m_urlsToExpand;
 406
 407     friend class KFileItemModelSortAlgorithm;  // Accesses lessThan() method
 408     friend class KFileItemModelRolesUpdater;   // Accesses emitSortProgress() method
 409     friend class KFileItemModelTest;           // For unit testing
 410 };
 411
 412 inline bool KFileItemModel::isChildItem(int index) const
 413 {
 414     return m_requestRole[ExpandedParentsCountRole] && m_itemData.at(index)->values.value("expandedParentsCount").toInt() > 0;
 415 }
 416
 417 #endif
 418
 419