src/kitemviews/kfileitemmodelrolesupdater.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 KFILEITEMMODELROLESUPDATER_H
  21 #define KFILEITEMMODELROLESUPDATER_H
  22
  23 #include <config-nepomuk.h>
  24
  25 #include <KFileItem>
  26 #include <kitemviews/kitemmodelbase.h>
  27
  28 #include <libdolphin_export.h>
  29
  30 #include <QObject>
  31 #include <QSet>
  32 #include <QSize>
  33 #include <QStringList>
  34
  35 class KDirWatch;
  36 class KFileItemModel;
  37 class KJob;
  38 class QPixmap;
  39 class QTimer;
  40
  41 #ifdef HAVE_NEPOMUK
  42     namespace Nepomuk2
  43     {
  44         class ResourceWatcher;
  45         class Resource;
  46     }
  47 #else
  48     // Required for the slot applyChangedNepomukRoles() that
  49     // cannot be ifdefined due to moc.
  50     namespace Nepomuk2
  51     {
  52         class Resource;
  53     }
  54 #endif
  55
  56 /**
  57  * @brief Resolves expensive roles asynchronously and applies them to the KFileItemModel.
  58  *
  59  * KFileItemModel only resolves roles that are inexpensive like e.g. the file name or
  60  * the permissions. Creating previews or determining the MIME-type can be quite expensive
  61  * and KFileItemModelRolesUpdater takes care to update such roles asynchronously.
  62  *
  63  * To prevent a huge CPU and I/O load, these roles are not updated for all
  64  * items, but only for the visible items, some items around the visible area,
  65  * and the items on the first and last pages of the view. This is a compromise
  66  * that aims to minimize the risk that the user sees items with unknown icons
  67  * in the view when scrolling or pressing Home or End.
  68  *
  69  * Determining the roles is done in several phases:
  70  *
  71  * 1.   If the sort role is "slow", it is determined for all items. If this
  72  *      cannot be finished synchronously in 200 ms, the remaining items are
  73  *      handled asynchronously by \a resolveNextSortRole().
  74  *
  75  * 2.   The function startUpdating(), which is called if either the sort role
  76  *      has been successfully determined for all items, or items are inserted
  77  *      in the view, or the visible items might have changed because items
  78  *      were removed or moved, tries to determine the icons for all visible
  79  *      items synchronously for 200 ms. Then:
  80  *
  81  *      (a) If previews are disabled, icons and all other roles are determined
  82  *          asynchronously for the interesting items. This is done by the
  83  *          function \a resolveNextPendingRoles().
  84  *
  85  *      (b) If previews are enabled, a \a KIO::PreviewJob is started that loads
  86  *          the previews for the interesting items. At the same time, the icons
  87  *          for these items are determined asynchronously as fast as possible
  88  *          by \a resolveNextPendingRoles(). This minimizes the risk that the
  89  *          user sees "unknown" icons when scrolling before the previews have
  90  *          arrived.
  91  *
  92  * 3.   Finally, the entire process is repeated for any items that might have
  93  *      changed in the mean time.
  94  */
  95 class LIBDOLPHINPRIVATE_EXPORT KFileItemModelRolesUpdater : public QObject
  96 {
  97     Q_OBJECT
  98
  99 public:
 100     explicit KFileItemModelRolesUpdater(KFileItemModel* model, QObject* parent = 0);
 101     virtual ~KFileItemModelRolesUpdater();
 102
 103     void setIconSize(const QSize& size);
 104     QSize iconSize() const;
 105
 106     /**
 107      * Sets the range of items that are visible currently. The roles
 108      * of visible items are resolved first.
 109      */
 110     void setVisibleIndexRange(int index, int count);
 111
 112     void setMaximumVisibleItems(int count);
 113
 114     /**
 115      * If \a show is set to true, the "iconPixmap" role will be filled with a preview
 116      * of the file. If \a show is false the MIME type icon will be used for the "iconPixmap"
 117      * role.
 118      */
 119     void setPreviewsShown(bool show);
 120     bool previewsShown() const;
 121
 122     /**
 123      * If enabled a small preview gets upscaled to the icon size in case where
 124      * the icon size is larger than the preview. Per default enlarging is
 125      * enabled.
 126      */
 127     void setEnlargeSmallPreviews(bool enlarge);
 128     bool enlargeSmallPreviews() const;
 129
 130     /**
 131      * If \a paused is set to true the asynchronous resolving of roles will be paused.
 132      * State changes during pauses like changing the icon size or the preview-shown
 133      * will be remembered and handled after unpausing.
 134      */
 135     void setPaused(bool paused);
 136     bool isPaused() const;
 137
 138     /**
 139      * Sets the roles that should be resolved asynchronously.
 140      */
 141     void setRoles(const QSet<QByteArray>& roles);
 142     QSet<QByteArray> roles() const;
 143
 144     /**
 145      * Sets the list of enabled thumbnail plugins that are used for previews.
 146      * Per default all plugins enabled in the KConfigGroup "PreviewSettings"
 147      * are used.
 148      *
 149      * For a list of available plugins, call KServiceTypeTrader::self()->query("ThumbCreator").
 150      *
 151      * @see enabledPlugins
 152      */
 153     void setEnabledPlugins(const QStringList& list);
 154
 155     /**
 156      * Returns the list of enabled thumbnail plugins.
 157      * @see setEnabledPlugins
 158      */
 159     QStringList enabledPlugins() const;
 160
 161 private slots:
 162     void slotItemsInserted(const KItemRangeList& itemRanges);
 163     void slotItemsRemoved(const KItemRangeList& itemRanges);
 164     void slotItemsMoved(const KItemRange& itemRange, QList<int> movedToIndexes);
 165     void slotItemsChanged(const KItemRangeList& itemRanges,
 166                           const QSet<QByteArray>& roles);
 167     void slotSortRoleChanged(const QByteArray& current,
 168                              const QByteArray& previous);
 169
 170     /**
 171      * Is invoked after a preview has been received successfully.
 172      * @see startPreviewJob()
 173      */
 174     void slotGotPreview(const KFileItem& item, const QPixmap& pixmap);
 175
 176     /**
 177      * Is invoked after generating a preview has failed.
 178      * @see startPreviewJob()
 179      */
 180     void slotPreviewFailed(const KFileItem& item);
 181
 182     /**
 183      * Is invoked when the preview job has been finished. Starts a new preview
 184      * job if there are any interesting items without previews left, or updates
 185      * the changed items otherwise.     *
 186      * @see startPreviewJob()
 187      */
 188     void slotPreviewJobFinished();
 189
 190     /**
 191      * Resolves the sort role of the next item in m_pendingSortRole, applies it
 192      * to the model, and invokes itself if there are any pending items left. If
 193      * that is not the case, \a startUpdating() is called.
 194      */
 195     void resolveNextSortRole();
 196
 197     /**
 198      * Resolves the icon name and (if previews are disabled) all other roles
 199      * for the next interesting item. If there are no pending items left, any
 200      * changed items are updated.
 201      */
 202     void resolveNextPendingRoles();
 203
 204     /**
 205      * Resolves items that have not been resolved yet after the change has been
 206      * notified by slotItemsChanged(). Is invoked if the m_changedItemsTimer
 207      * expires.
 208      */
 209     void resolveRecentlyChangedItems();
 210
 211     void applyChangedNepomukRoles(const Nepomuk2::Resource& resource);
 212
 213     /**
 214      * Is invoked if a directory watched by KDirWatch got dirty. Updates
 215      * the "isExpandable"- and "size"-roles of the item that matches to
 216      * the given path.
 217      */
 218     void slotDirWatchDirty(const QString& path);
 219
 220 private:
 221     /**
 222      * Starts the updating of all roles. The visible items are handled first.
 223      */
 224     void startUpdating();
 225
 226     /**
 227      * Loads the icons for the visible items. After 200 ms, the function
 228      * stops determining mime types and only loads preliminary icons.
 229      * This is a compromise that prevents that
 230      * (a) the GUI is blocked for more than 200 ms, and
 231      * (b) "unknown" icons could be shown in the view.
 232      */
 233     void updateVisibleIcons();
 234
 235     /**
 236      * Tries to load at least preliminary icons (without determining the
 237      * mime type) for all items for \a timeout milliseconds.
 238      */
 239     void updateAllIconsFast(int timeout);
 240
 241     /**
 242      * Creates previews for the items starting from the first item in
 243      * m_pendingPreviewItems.
 244      * @see slotGotPreview()
 245      * @see slotPreviewFailed()
 246      * @see slotPreviewJobFinished()
 247      */
 248     void startPreviewJob();
 249
 250     /**
 251      * Ensures that icons, previews, and other roles are determined for any
 252      * items that have been changed.
 253      */
 254     void updateChangedItems();
 255
 256     /**
 257      * Resolves the sort role of the item and applies it to the model.
 258      */
 259     void applySortRole(int index);
 260
 261     void applySortProgressToModel();
 262
 263     enum ResolveHint {
 264         ResolveFast,
 265         ResolveAll
 266     };
 267     bool applyResolvedRoles(const KFileItem& item, ResolveHint hint);
 268     QHash<QByteArray, QVariant> rolesData(const KFileItem& item) const;
 269
 270     /**
 271      * @return The number of items of the path \a path.
 272      */
 273     int subItemsCount(const QString& path) const;
 274
 275     /**
 276      * Must be invoked if a property has been changed that affects
 277      * the look of the preview. Takes care to update all previews.
 278      */
 279     void updateAllPreviews();
 280
 281     void killPreviewJob();
 282
 283     QList<int> indexesToResolve() const;
 284
 285 private:
 286     enum State {
 287         Idle,
 288         Paused,
 289         ResolvingSortRole,
 290         ResolvingAllRoles,
 291         PreviewJobRunning
 292     };
 293
 294     State m_state;
 295
 296     // Property changes during pausing must be remembered to be able
 297     // to react when unpausing again:
 298     bool m_previewChangedDuringPausing;
 299     bool m_iconSizeChangedDuringPausing;
 300     bool m_rolesChangedDuringPausing;
 301
 302     // Property for setPreviewsShown()/previewsShown().
 303     bool m_previewShown;
 304
 305     // Property for setEnlargeSmallPreviews()/enlargeSmallPreviews()
 306     bool m_enlargeSmallPreviews;
 307
 308     // True if the role "iconPixmap" should be cleared when resolving the next
 309     // role with resolveRole(). Is necessary if the preview gets disabled
 310     // during the roles-updater has been paused by setPaused().
 311     bool m_clearPreviews;
 312
 313     // Remembers which items have been handled already, to prevent that
 314     // previews and other expensive roles are determined again.
 315     QSet<KFileItem> m_finishedItems;
 316
 317     KFileItemModel* m_model;
 318     QSize m_iconSize;
 319     int m_firstVisibleIndex;
 320     int m_lastVisibleIndex;
 321     int m_maximumVisibleItems;
 322     QSet<QByteArray> m_roles;
 323     QSet<QByteArray> m_resolvableRoles;
 324     QStringList m_enabledPlugins;
 325
 326     // Items for which the sort role still has to be determined.
 327     QSet<KFileItem> m_pendingSortRoleItems;
 328
 329     // Determines if the next call of startUpdating() will try to do a fast
 330     // icon loading (i.e., without determining the mime type) for all items.
 331     bool m_hasUnknownIcons;
 332     int m_firstIndexWithoutIcon;
 333
 334     // Indexes of items which still have to be handled by
 335     // resolveNextPendingRoles().
 336     QList<int> m_pendingIndexes;
 337
 338     // Items which have been left over from the last call of startPreviewJob().
 339     // A new preview job will be started from them once the first one finishes.
 340     KFileItemList m_pendingPreviewItems;
 341
 342     KJob* m_previewJob;
 343
 344     // When downloading or copying large files, the slot slotItemsChanged()
 345     // will be called periodically within a quite short delay. To prevent
 346     // a high CPU-load by generating e.g. previews for each notification, the update
 347     // will be postponed until no file change has been done within a longer period
 348     // of time.
 349     QTimer* m_recentlyChangedItemsTimer;
 350     QSet<KFileItem> m_recentlyChangedItems;
 351
 352     // Items which have not been changed repeatedly recently.
 353     QSet<KFileItem> m_changedItems;
 354
 355     KDirWatch* m_dirWatcher;
 356     mutable QSet<QString> m_watchedDirs; // Required as sadly KDirWatch does not offer a getter method
 357                                          // to get all watched directories.
 358 #ifdef HAVE_NEPOMUK
 359     Nepomuk2::ResourceWatcher* m_nepomukResourceWatcher;
 360     mutable QHash<QUrl, KUrl> m_nepomukUriItems;
 361 #endif
 362 };
 363
 364 #endif
 365
 366