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