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