KIO

previewjob.h
1 // -*- c++ -*-
2 /*
3  This file is part of the KDE libraries
4  SPDX-FileCopyrightText: 2000 David Faure <[email protected]>
5  SPDX-FileCopyrightText: 2000 Carsten Pfeiffer <[email protected]>
6  SPDX-FileCopyrightText: 2001 Malte Starostik <[email protected]>
7 
8  SPDX-License-Identifier: LGPL-2.0-or-later
9 */
10 
11 #ifndef KIO_PREVIEWJOB_H
12 #define KIO_PREVIEWJOB_H
13 
14 #include "kiowidgets_export.h"
15 #include <kfileitem.h>
16 #include <kio/job.h>
17 
18 class QPixmap;
19 
20 namespace KIO
21 {
22 class PreviewJobPrivate;
23 /*!
24  * @class KIO::PreviewJob previewjob.h <KIO/PreviewJob>
25  *
26  * This class catches a preview (thumbnail) for files.
27  * @short KIO Job to get a thumbnail picture
28  */
29 class KIOWIDGETS_EXPORT PreviewJob : public KIO::Job
30 {
31  Q_OBJECT
32 public:
33  /**
34  * Specifies the type of scaling that is applied to the generated preview.
35  * For HiDPI, pixel density scaling, @see setDevicePixelRatio
36  *
37  * @since 4.7
38  */
39  enum ScaleType {
40  /**
41  * The original size of the preview will be returned. Most previews
42  * will return a size of 256 x 256 pixels.
43  */
45  /**
46  * The preview will be scaled to the size specified when constructing
47  * the PreviewJob. The aspect ratio will be kept.
48  */
50  /**
51  * The preview will be scaled to the size specified when constructing
52  * the PreviewJob. The result will be cached for later use. Per default
53  * ScaledAndCached is set.
54  */
56  };
57 
58 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(4, 7)
59  /**
60  * Creates a new PreviewJob.
61  * @param items a list of files to create previews for
62  * @param width the desired width
63  * @param height the desired height, 0 to use the @p width
64  * @param iconSize the size of the MIME type icon to overlay over the
65  * preview or zero to not overlay an icon. This has no effect if the
66  * preview plugin that will be used doesn't use icon overlays.
67  * @param iconAlpha transparency to use for the icon overlay
68  * @param scale if the image is to be scaled to the requested size or
69  * returned in its original size
70  * @param save if the image should be cached for later use
71  * @param enabledPlugins If non-zero, this points to a list containing
72  * the names of the plugins that may be used. If enabledPlugins is zero
73  * all available plugins are used.
74  *
75  * @deprecated Since 4.7, use PreviewJob(const KFileItemList&, const QSize&, const QStringList*) in combination
76  * with the setter-methods instead. Note that the semantics of
77  * \p enabledPlugins has been slightly changed.
78  */
79  KIOWIDGETS_DEPRECATED_VERSION(4, 7, "Use PreviewJob(const KFileItemList&, const QSize&, const QStringList*)")
80  PreviewJob(const KFileItemList &items, int width, int height, int iconSize, int iconAlpha, bool scale, bool save, const QStringList *enabledPlugins);
81 #endif
82 
83  /**
84  * @param items List of files to create previews for.
85  * @param size Desired size of the preview.
86  * @param enabledPlugins If non-zero it defines the list of plugins that
87  * are considered for generating the preview. If
88  * enabledPlugins is zero the plugins specified in the
89  * KConfigGroup "PreviewSettings" are used.
90  * @since 4.7
91  */
92  PreviewJob(const KFileItemList &items, const QSize &size, const QStringList *enabledPlugins = nullptr);
93 
94  ~PreviewJob() override;
95 
96  /**
97  * Sets the size of the MIME-type icon which overlays the preview. If zero
98  * is passed no overlay will be shown at all. The setting has no effect if
99  * the preview plugin that will be used does not use icon overlays. Per
100  * default the size is set to 0.
101  * @since 4.7
102  */
103  void setOverlayIconSize(int size);
104 
105  /**
106  * @return The size of the MIME-type icon which overlays the preview.
107  * @see PreviewJob::setOverlayIconSize()
108  * @since 4.7
109  */
110  int overlayIconSize() const;
111 
112  /**
113  * Sets the alpha-value for the MIME-type icon which overlays the preview.
114  * The alpha-value may range from 0 (= fully transparent) to 255 (= opaque).
115  * Per default the value is set to 70.
116  * @see PreviewJob::setOverlayIconSize()
117  * @since 4.7
118  */
119  void setOverlayIconAlpha(int alpha);
120 
121  /**
122  * @return The alpha-value for the MIME-type icon which overlays the preview.
123  * Per default 70 is returned.
124  * @see PreviewJob::setOverlayIconAlpha()
125  * @since 4.7
126  */
127  int overlayIconAlpha() const;
128 
129  /**
130  * Sets the scale type for the generated preview. Per default
131  * PreviewJob::ScaledAndCached is set.
132  * @see PreviewJob::ScaleType
133  * @since 4.7
134  */
135  void setScaleType(ScaleType type);
136 
137  /**
138  * @return The scale type for the generated preview.
139  * @see PreviewJob::ScaleType
140  * @since 4.7
141  */
142  ScaleType scaleType() const;
143 
144  /**
145  * Removes an item from preview processing. Use this if you passed
146  * an item to filePreview and want to delete it now.
147  *
148  * @param url the url of the item that should be removed from the preview queue
149  */
150  void removeItem(const QUrl &url);
151 
152  /**
153  * If @p ignoreSize is true, then the preview is always
154  * generated regardless of the settings
155  **/
156  void setIgnoreMaximumSize(bool ignoreSize = true);
157 
158  /**
159  * Sets the sequence index given to the thumb creators.
160  * Use the sequence index, it is possible to create alternative
161  * icons for the same item. For example it may allow iterating through
162  * the items of a directory, or the frames of a video.
163  *
164  * @since 4.3
165  **/
166  void setSequenceIndex(int index);
167 
168  /**
169  * Returns the currently set sequence index
170  *
171  * @since 4.3
172  **/
173  int sequenceIndex() const;
174 
175  /**
176  * Returns the index at which the thumbs of a ThumbSequenceCreator start
177  * wrapping around ("looping"). Fractional values may be returned if the
178  * ThumbSequenceCreator supports sub-integer precision, but frontends
179  * supporting only integer sequence indices may choose to round it down.
180  *
181  * @see ThumbSequenceCreator::sequenceIndexWraparoundPoint()
182  * @since 5.80
183  */
184  float sequenceIndexWraparoundPoint() const;
185 
186  /**
187  * Determines whether the ThumbCreator in use is a ThumbSequenceCreator.
188  *
189  * @since 5.80
190  */
191  bool handlesSequences() const;
192 
193 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 86)
194  /**
195  * Request preview to use the device pixel ratio @p dpr.
196  * The returned thumbnail may not respect the device pixel ratio requested.
197  * Use QPixmap::devicePixelRatio to check, or paint as necessary.
198  *
199  * @since 5.80
200  * @deprecated Since 5.86, use setDevicePixelRatio(qreal dpr) instead
201  */
202  KIOWIDGETS_DEPRECATED_VERSION(5, 86, "Use setDevicePixelRatio(qreal dpr)")
203  void setDevicePixelRatio(int dpr);
204 #endif
205 
206  /**
207  * Request preview to use the device pixel ratio @p dpr.
208  * The returned thumbnail may not respect the device pixel ratio requested.
209  * Use QPixmap::devicePixelRatio to check, or paint as necessary.
210  *
211  * @since 5.84
212  */
213  void setDevicePixelRatio(qreal dpr);
214 
215  /**
216  * Returns a list of all available preview plugins. The list
217  * contains the basenames of the plugins' .desktop files (no path,
218  * no .desktop).
219  * @return the list of all available plugins
220  */
221  static QStringList availablePlugins();
222 
223  /**
224  * Returns a list of plugins that should be enabled by default, which is all plugins
225  * Minus the plugins specified in an internal blacklist
226  * @return the list of plugins that should be enabled by default
227  * @since 5.40
228  */
229  static QStringList defaultPlugins();
230 
231  /**
232  * Returns a list of all supported MIME types. The list can
233  * contain entries like text/ * (without the space).
234  * @return the list of MIME types
235  */
236  static QStringList supportedMimeTypes();
237 
238 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(4, 5)
239  /**
240  * Returns the default "maximum file size", in bytes, used by PreviewJob.
241  * This is useful for applications providing a GUI for letting the user change the size.
242  * @since 4.1
243  * @deprecated Since 4.5, PreviewJob uses different maximum file sizes dependent on the URL.
244  * The returned file size is only valid for local URLs.
245  */
246  KIOWIDGETS_DEPRECATED_VERSION(4, 5, "See API dox")
247  static KIO::filesize_t maximumFileSize();
248 #endif
249 
250 Q_SIGNALS:
251  /**
252  * Emitted when a thumbnail picture for @p item has been successfully
253  * retrieved.
254  * @param item the file of the preview
255  * @param preview the preview image
256  */
257  void gotPreview(const KFileItem &item, const QPixmap &preview);
258  /**
259  * Emitted when a thumbnail for @p item could not be created,
260  * either because a ThumbCreator for its MIME type does not
261  * exist, or because something went wrong.
262  * @param item the file that failed
263  */
264  void failed(const KFileItem &item);
265 
266 protected Q_SLOTS:
267  void slotResult(KJob *job) override;
268 
269 private:
270  Q_PRIVATE_SLOT(d_func(), void startPreview())
271  Q_PRIVATE_SLOT(d_func(), void slotThumbData(KIO::Job *, const QByteArray &))
272  Q_DECLARE_PRIVATE(PreviewJob)
273 
274 public:
275 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 86)
276  /**
277  * Sets a default device Pixel Ratio used for Previews
278  * @see setDevicePixelRatio
279  *
280  * Defaults to 1
281  *
282  * @since 5.80
283  * @deprecated Since 5.86, use setDefaultDevicePixelRatio(qreal dpr) instead
284  */
285  KIOWIDGETS_DEPRECATED_VERSION(5, 86, "Use setDefaultDevicePixelRatio(qreal dpr)")
286  static void setDefaultDevicePixelRatio(int devicePixelRatio);
287 #endif
288 
289  /**
290  * Sets a default device Pixel Ratio used for Previews
291  * @see setDevicePixelRatio
292  *
293  * Defaults to 1
294  *
295  * @since 5.84
296  */
297  static void setDefaultDevicePixelRatio(qreal devicePixelRatio);
298 };
299 
300 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(4, 7)
301 /**
302  * Creates a PreviewJob to generate or retrieve a preview image
303  * for the given URL.
304  *
305  * @param items files to get previews for
306  * @param width the maximum width to use
307  * @param height the maximum height to use, if this is 0, the same
308  * value as width is used.
309  * @param iconSize the size of the MIME type icon to overlay over the
310  * preview or zero to not overlay an icon. This has no effect if the
311  * preview plugin that will be used doesn't use icon overlays.
312  * @param iconAlpha transparency to use for the icon overlay
313  * @param scale if the image is to be scaled to the requested size or
314  * returned in its original size
315  * @param save if the image should be cached for later use
316  * @param enabledPlugins if non-zero, this points to a list containing
317  * the names of the plugins that may be used.
318  * @return the new PreviewJob
319  * @see PreviewJob::availablePlugins()
320  * @deprecated Since 4.7, use KIO::filePreview(const KFileItemList&, const QSize&, const QStringList*) in combination
321  * with the setter-methods instead. Note that the semantics of
322  * \p enabledPlugins has been slightly changed.
323  */
324 KIOWIDGETS_EXPORT
325 KIOWIDGETS_DEPRECATED_VERSION(4, 7, "Use KIO::filePreview(const KFileItemList &, const QSize &, const QStringList *")
326 PreviewJob *filePreview(const KFileItemList &items,
327  int width,
328  int height = 0,
329  int iconSize = 0,
330  int iconAlpha = 70,
331  bool scale = true,
332  bool save = true,
333  const QStringList *enabledPlugins = nullptr); // KDE5: use enums instead of bool scale + bool save
334 #endif
335 
336 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(4, 7)
337 /**
338  * Creates a PreviewJob to generate or retrieve a preview image
339  * for the given URL.
340  *
341  * @param items files to get previews for
342  * @param width the maximum width to use
343  * @param height the maximum height to use, if this is 0, the same
344  * value as width is used.
345  * @param iconSize the size of the MIME type icon to overlay over the
346  * preview or zero to not overlay an icon. This has no effect if the
347  * preview plugin that will be used doesn't use icon overlays.
348  * @param iconAlpha transparency to use for the icon overlay
349  * @param scale if the image is to be scaled to the requested size or
350  * returned in its original size
351  * @param save if the image should be cached for later use
352  * @param enabledPlugins if non-zero, this points to a list containing
353  * the names of the plugins that may be used.
354  * @return the new PreviewJob
355  * @see PreviewJob::availablePlugins()
356  * @deprecated Since 4.7, use KIO::filePreview(const KFileItemList&, const QSize&, const QStringList*) in combination
357  * with the setter-methods instead. Note that the semantics of
358  * \p enabledPlugins has been slightly changed.
359  */
360 KIOWIDGETS_EXPORT
361 KIOWIDGETS_DEPRECATED_VERSION(4, 7, "Use KIO::filePreview(const KFileItemList &, const QSize &, const QStringList *")
362 PreviewJob *filePreview(const QList<QUrl> &items,
363  int width,
364  int height = 0,
365  int iconSize = 0,
366  int iconAlpha = 70,
367  bool scale = true,
368  bool save = true,
369  const QStringList *enabledPlugins = nullptr);
370 #endif
371 
372 /**
373  * Creates a PreviewJob to generate a preview image for the given items.
374  * @param items List of files to create previews for.
375  * @param size Desired size of the preview.
376  * @param enabledPlugins If non-zero it defines the list of plugins that
377  * are considered for generating the preview. If
378  * enabledPlugins is zero the plugins specified in the
379  * KConfigGroup "PreviewSettings" are used.
380  * @since 4.7
381  */
382 KIOWIDGETS_EXPORT PreviewJob *filePreview(const KFileItemList &items, const QSize &size, const QStringList *enabledPlugins = nullptr);
383 }
384 
385 #endif
qulonglong filesize_t
64-bit file size
Definition: global.h:39
A namespace for KIO globals.
The original size of the preview will be returned.
Definition: previewjob.h:44
List of KFileItems, which adds a few helper methods to QList<KFileItem>.
Definition: kfileitem.h:601
KIOWIDGETS_EXPORT PreviewJob * filePreview(const KFileItemList &items, int width, int height=0, int iconSize=0, int iconAlpha=70, bool scale=true, bool save=true, const QStringList *enabledPlugins=nullptr)
Creates a PreviewJob to generate or retrieve a preview image for the given URL.
KIO Job to get a thumbnail picture.
Definition: previewjob.h:29
The preview will be scaled to the size specified when constructing the PreviewJob.
Definition: previewjob.h:55
The base class for all jobs.
Definition: job_base.h:44
ScaleType
Specifies the type of scaling that is applied to the generated preview.
Definition: previewjob.h:39
The preview will be scaled to the size specified when constructing the PreviewJob.
Definition: previewjob.h:49
A KFileItem is a generic class to handle a file, local or remote.
Definition: kfileitem.h:35
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sun Nov 28 2021 22:53:21 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.