Debian Codegraph @

core/libs/threadimageio/thumb/thumbnailloadthread.h

raw
1 /* ============================================================
2 *
3 * This file is a part of digiKam project
4 * https://www.digikam.org
5 *
6 * Date : 2007-06-05
7 * Description : Thumbnail loading
8 *
9 * SPDX-FileCopyrightText: 2006-2011 by Marcel Wiesweg <marcel dot wiesweg at gmx dot de>
10 * SPDX-FileCopyrightText: 2008-2026 by Gilles Caulier <caulier dot gilles at gmail dot com>
11 *
12 * SPDX-License-Identifier: GPL-2.0-or-later
13 *
14 * ============================================================ */
15
16 #pragma once
17
18 // Qt includes
19
20 #include <QPixmap>
21 #include <QImage>
22
23 // Local includes
24
25 #include "managedloadsavethread.h"
26 #include "thumbnailinfo.h"
27
28 namespace Digikam
29 {
30
31 class DbEngineParameters;
32 class ThumbnailCreator;
33 class ThumbnailInfoProvider;
34
35 class DIGIKAM_EXPORT ThumbnailLoadThread : public ManagedLoadSaveThread
36 {
37 Q_OBJECT
38
39 public:
40
41 explicit ThumbnailLoadThread(QObject* const parent = nullptr);
42 ~ThumbnailLoadThread() override;
43
44 /**
45 * Return application-wide default thumbnail threads.
46 * It is perfectly all right to create an extra object of the class,
47 * but it is useful to have default object
48 */
49 static ThumbnailLoadThread* defaultThread();
50 static ThumbnailLoadThread* defaultIconViewThread();
51
52 static void cleanUp();
53
54 /**
55 * Disable storing thumbnails in the disk cache.
56 * This shall be called once at application startup.
57 * This need not be called, then the FreeDesktop standard is used.
58 */
59 static void initializeNoThumbnailStorage();
60
61 /**
62 * Enable loading of thumbnails from a thumbnail database.
63 * This shall be called once at application startup.
64 * This need not be called, then the FreeDesktop standard is used.
65 * You can optionally provide a thumbnail info provider.
66 */
67 static void initializeThumbnailDatabase(const DbEngineParameters& params, ThumbnailInfoProvider* const provider = nullptr);
68
69 /**
70 * For color management, this sets the widget the thumbnails will be color managed for.
71 * (currently it is only possible to set one global widget)
72 */
73 static void setDisplayingWidget(QWidget* const widget);
74
75 /**
76 * Find a thumbnail.
77 * If the pixmap is found in the cache, returns true and sets pixmap
78 * to the found QPixmap.
79 * If the pixmap is not found in the cache, load() is called to start the loading process,
80 * false is returned and pixmap is not touched.
81 */
82 bool find(const ThumbnailIdentifier& identifier, QPixmap& pixmap);
83
84 /**
85 * Same as above, but does not use the global size, but an extra specified size.
86 */
87 bool find(const ThumbnailIdentifier& identifier,
88 QPixmap& pixmap, int size, bool onlyStorage = false);
89
90 /**
91 * Find a thumbnail.
92 * This method sends the signals and does not return values like the method above.
93 * If you certainly need asynchronous return, connect with Qt::QueuedConnection to the signals.
94 * If you connect directly, the signals may be sent from within the method call.
95 */
96 void find(const ThumbnailIdentifier& identifier);
97
98 /**
99 * Same as above, but does not use the global size, but an extra specified size.
100 */
101 void find(const ThumbnailIdentifier& identifier, int size);
102
103 /**
104 * Find a group of thumbnails. The items will be loaded in order and signals will be sent.
105 * Can be used to ensure that thumbnails are loaded in a particular order.
106 *
107 * @note: the signal signalThumbnailLoaded() is only fired once, after it has been loaded, this behavior is intentional.
108 * On all subsequent attempts, during the conversion from ThumbnailIdentifier to LoadingDescription, it checks whether the
109 * thumbnail is already in the cache. The load request is then discarded.
110 */
111 void findGroup(QList<ThumbnailIdentifier>& identifiers);
112 void findGroup(QList<ThumbnailIdentifier>& identifiers, int size);
113
114 /**
115 * All tastes of find() methods, for loading the thumbnail of a detail
116 */
117 bool find(const ThumbnailIdentifier& identifier, const QRect& rect, QPixmap& pixmap);
118 bool find(const ThumbnailIdentifier& identifier,
119 const QRect& rect, QPixmap& pixmap, int size, bool onlyStorage = false);
120 void find(const ThumbnailIdentifier& identifier, const QRect& rect);
121 void find(const ThumbnailIdentifier& identifier, const QRect& rect, int size);
122 void findGroup(const QList<QPair<ThumbnailIdentifier, QRect> >& filePathAndRects);
123 void findGroup(const QList<QPair<ThumbnailIdentifier, QRect> >& filePathsAndRects, int size);
124
125 /**
126 * Find the thumbnail pixmap in the buffered cache to
127 * avoid flickering while loading a new thumbnail.
128 */
129 bool findBuffered(const ThumbnailIdentifier& identifier,
130 const QRect& rect, QPixmap& pixmap, int size);
131
132 /**
133 * Preload the thumbnail or thumbnail group.
134 * This is essentially the same as loading, but with a lower priority.
135 */
136 void preload(const ThumbnailIdentifier& identifier);
137 void preload(const ThumbnailIdentifier& identifier, int size);
138 void preloadGroup(QList<ThumbnailIdentifier>& identifiers);
139 void preloadGroup(QList<ThumbnailIdentifier>& identifiers, int size);
140
141 /**
142 * Pregenerate the thumbnail group.
143 * No signals will be emitted when these are loaded.
144 */
145 void pregenerateGroup(const QList<ThumbnailIdentifier>& identifiers);
146 void pregenerateGroup(const QList<ThumbnailIdentifier>& identifiers, int size);
147
148 /**
149 * Load a thumbnail.
150 * You do not need to use this method directly, it will not access the pixmap cache. Use find().
151 * The LoadingDescription shall be constructed with the constructor for preview/thumbnail jobs.
152 * (in the description constructor, you need to specify file path, thumbnail size and Exif rotation)
153 */
154 void load(const LoadingDescription& description) override;
155
156 /**
157 * Returns the descriptions used by the last call to any of the above methods.
158 * After calling single-thumbnail methods (find, preload) the list will have size 1,
159 * after the group methods (findGroup, preloadGroup, pregenerateGroup) the list can
160 * be larger than 1.
161 * There is no information if the description was ever scheduled in the thread,
162 * already processed, skipped or canceled.
163 */
164 QList<LoadingDescription> lastDescriptions() const;
165
166 /**
167 * @note If the thread is currently loading thumbnails, there is no guarantee as to when
168 * the property change by one of the following methods takes effect.
169 */
170
171 /**
172 * Set the requested thumbnail size.
173 * Default value: 128
174 */
175 void setThumbnailSize(int size, bool forFace = false);
176
177 /**
178 * Returns the maximum possible size of a thumbnail.
179 * If you request a larger size, the thumbnail will not load.
180 * The size of the pixmap can slightly differ, especially when highlighting.
181 */
182 static int maximumThumbnailSize();
183 static int maximumThumbnailPixmapSize(bool withHighlighting);
184
185 /**
186 * If you enable this, the signal thumbnailLoaded(LoadingDescription, QPixmap) will be emitted.
187 * If you do not enable this, only the QImage-based signal (see LoadSaveThread) will be emitted.
188 *
189 * If you disable this, pay attention to the (global) setting of the LoadingCache, which per default
190 * does not cache the images !!
191 *
192 * Default value: Enabled.
193 */
194 void setPixmapRequested(bool wantPixmap);
195
196 /**
197 * If you enable this, a highlighting border will be drawn around the pixmap.
198 * This option has only an effect if pixmapRequested is true.
199 * Default value: Enabled.
200 */
201 void setHighlightPixmap(bool highlight);
202
203 /**
204 * Computes the pixmap size for the give thumbnail size.
205 * These can differ when highlighting is turned on.
206 */
207 int thumbnailToPixmapSize(int size) const;
208 static int thumbnailToPixmapSize(bool withHighlight, int size);
209
210 /**
211 * Computes the thumbnail size for the give pixmap size.
212 */
213 int pixmapToThumbnailSize(int size) const;
214
215 /**
216 * If you enable this, the thread will try hard to send a pixmap if thumbnail loading failed.
217 * It will use standard system icons to replace the real thumbnail.
218 * If you disable this, a null QPixmap will be sent.
219 * This does not influence the QImage-based signal; this signal will be emitted with a null
220 * QImage regardless of this setting here, if the loading failed.
221 * Default value: Enabled.
222 */
223 void setSendSurrogatePixmap(bool send);
224
225 /**
226 * Stores the given detail thumbnail on disk.
227 * Use this if possible because generation of detail thumbnails
228 * is potentially slower.
229 * The image should at least have storedSize().
230 */
231 void storeDetailThumbnail(const QString& filePath,
232 const QRect& detailRect,
233 const QImage& image,
234 bool isFace = false);
235 int storedSize() const;
236
237 /**
238 * This is a tool to force regeneration of thumbnails.
239 * All thumbnail files for the given file will be removed from disk,
240 * and the cached instances will be removed as well.
241 * Use this method if you know that the contents of the file has changed.
242 * This method works independently from the multithreaded thumbnail loading.
243 */
244 static void deleteThumbnail(const QString& filePath);
245
246 Q_SIGNALS:
247
248 /// @note See LoadSaveThread for a QImage-based thumbnailLoaded() signal.
249 void signalThumbnailLoaded(const LoadingDescription& loadingDescription, const QPixmap& pix);
250
251 public:
252
253 /// @note For internal use - may only be used from the thread
254 ThumbnailCreator* thumbnailCreator() const;
255
256 protected:
257
258 void thumbnailLoaded(const LoadingDescription& loadingDescription, const QImage& img) override;
259
260 private:
261
262 bool find(const ThumbnailIdentifier& identifier, int size, QPixmap* retPixmap,
263 bool emitSignal, const QRect& detailRect, bool onlyStorage = false);
264 void load(const LoadingDescription& description, bool pregenerate);
265 bool checkSize(int size);
266 QPixmap surrogatePixmap(const LoadingDescription& loadingDescription);
267
268 Q_SIGNALS:
269
270 /// @note For internal use only.
271 void thumbnailsAvailable();
272 void ThumbnailLoaded(const LoadingDescription&, const QImage&);
273
274 private Q_SLOTS:
275
276 void slotThumbnailsAvailable();
277 void slotThumbnailLoaded(const LoadingDescription&, const QImage&);
278
279 private:
280
281 /// @note disabled
282 ThumbnailLoadThread(const ThumbnailLoadThread&) = delete;
283 ThumbnailLoadThread& operator=(const ThumbnailLoadThread&) = delete;
284
285 private:
286
287 class Private;
288 Private* const d = nullptr;
289 };
290
291 // --------------------------------------------------------------------------------------------------
292
293 class DIGIKAM_EXPORT ThumbnailImageCatcher : public QObject
294 {
295 Q_OBJECT
296
297 public:
298
299 /**
300 * Use this class to get a thumbnail synchronously.
301 * 1. Create the ThumbnailImageCatcher object with your ThumbnailLoadThread
302 * 2. a) Request a thumbnail
303 * b) Call enqueue()
304 * 3. Call waitForThumbnails which returns the thumbnail QImage(s).
305 *
306 * Note: Not meant for loading QPixmap thumbnails.
307 */
308
309 explicit ThumbnailImageCatcher(QObject* const parent = nullptr);
310 explicit ThumbnailImageCatcher(ThumbnailLoadThread* const thread,
311 QObject* const parent = nullptr);
312 ~ThumbnailImageCatcher() override;
313
314 ThumbnailLoadThread* thread() const;
315 void setThumbnailLoadThread(ThumbnailLoadThread* const thread);
316
317 /**
318 * After requesting a thumbnail from the thread, call enqueue()
319 * each time. Enqueue records the requested loading operation in an internal list.
320 * A loading operation can result in the return of more than one thumbnail,
321 * so enqueue() returns the number of expected results.
322 * Then call waitForThumbnails. The returned list is the sum of previous calls
323 * to enqueue, one entry per expected result, in order.
324 * If stopped prematurely or loading failed, the respective entries will be null.
325 */
326 int enqueue();
327 QList<QImage> waitForThumbnails();
328
329 public Q_SLOTS:
330
331 /**
332 * The catcher is active per default after construction.
333 * Deactivate it if you use the catcher as a longer-lived
334 * object and do not use it for some time,
335 * then activate it before you request a thumbnail from the thread again.
336 */
337 void setActive(bool active);
338
339 /**
340 * If the catcher is waiting in waitForThumbnails() in a different thread,
341 * cancels the waiting. The results will be returned as received so far.
342 */
343 void cancel();
344
345 protected Q_SLOTS:
346
347 void slotThumbnailLoaded(const LoadingDescription&, const QImage&);
348
349 private:
350
351 /// @note disabled
352 ThumbnailImageCatcher(const ThumbnailImageCatcher&) = delete;
353 ThumbnailImageCatcher& operator=(const ThumbnailImageCatcher&) = delete;
354
355 private:
356
357 class Private;
358 Private* const d = nullptr;
359 };
360
361 } // namespace Digikam