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