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