1// -*- c++ -*-
2/*
3 This file is part of the KDE libraries
4 SPDX-FileCopyrightText: 2000 David Faure <faure@kde.org>
5 SPDX-FileCopyrightText: 2000 Carsten Pfeiffer <pfeiffer@kde.org>
6 SPDX-FileCopyrightText: 2001 Malte Starostik <malte.starostik@t-online.de>
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 "kiogui_export.h"
15#include <kfileitem.h>
16#include <kio/job.h>
17
18class QPixmap;
19class KPluginMetaData;
20
21namespace KIO
22{
23class PreviewJobPrivate;
24/*!
25 * \class KIO::PreviewJob
26 * \inmodule KIOGui
27 * \inheaderfile KIO/PreviewJob
28 *
29 * This class catches a preview (thumbnail) for files.
30 *
31 * \brief KIO Job to get a thumbnail picture.
32 */
33class KIOGUI_EXPORT PreviewJob : public KIO::Job
34{
35 Q_OBJECT
36public:
37 /*!
38 * Specifies the type of scaling that is applied to the generated preview.
39 * For HiDPI, pixel density scaling, see setDevicePixelRatio
40 *
41 * \value Unscaled The original size of the preview will be returned. Most previews will return a size of 256 x 256 pixels.
42 * \value Scaled The preview will be scaled to the size specified when constructing the PreviewJob. The aspect ratio will be kept.
43 * \value ScaledAndCached The preview will be scaled to the size specified when constructing the PreviewJob. The result will be cached for later use. Per
44 * default ScaledAndCached is set.
45 */
46 enum ScaleType {
47 Unscaled,
48 Scaled,
49 ScaledAndCached,
50 };
51
52 /*!
53 * \a items List of files to create previews for.
54 * \a size Desired size of the preview.
55 * \a enabledPlugins If non-zero it defines the list of plugins that
56 * are considered for generating the preview. If
57 * enabledPlugins is zero the plugins specified in the
58 * KConfigGroup "PreviewSettings" are used.
59 */
60 PreviewJob(const KFileItemList &items, const QSize &size, const QStringList *enabledPlugins = nullptr);
61
62 ~PreviewJob() override;
63
64 /*!
65 * Sets the scale type for the generated preview. Per default
66 * PreviewJob::ScaledAndCached is set.
67 * \sa PreviewJob::ScaleType
68 */
69 void setScaleType(ScaleType type);
70
71 /*!
72 * Returns The scale type for the generated preview.
73 * \sa PreviewJob::ScaleType
74 */
75 ScaleType scaleType() const;
76
77 /*!
78 * Removes an item from preview processing. Use this if you passed
79 * an item to filePreview and want to delete it now.
80 *
81 * \a url the url of the item that should be removed from the preview queue
82 */
83 void removeItem(const QUrl &url);
84
85 /*!
86 * If \a ignoreSize is true, then the preview is always
87 * generated regardless of the settings
88 **/
89 void setIgnoreMaximumSize(bool ignoreSize = true);
90
91 /*!
92 * Sets the sequence \a index given to the thumb creators.
93 * Use the sequence index, it is possible to create alternative
94 * icons for the same item. For example it may allow iterating through
95 * the items of a directory, or the frames of a video.
96 *
97 **/
98 void setSequenceIndex(int index);
99
100 /*!
101 * Returns the currently set sequence index
102 *
103 **/
104 int sequenceIndex() const;
105
106 /*!
107 * Returns the index at which the thumbs of a ThumbSequenceCreator start
108 * wrapping around ("looping"). Fractional values may be returned if the
109 * ThumbSequenceCreator supports sub-integer precision, but frontends
110 * supporting only integer sequence indices may choose to round it down.
111 *
112 * \since 5.80
113 */
114 float sequenceIndexWraparoundPoint() const;
115
116 /*!
117 * Determines whether the ThumbCreator in use is a ThumbSequenceCreator.
118 *
119 * \since 5.80
120 */
121 bool handlesSequences() const;
122
123 /*!
124 * Request preview to use the device pixel ratio \a dpr.
125 * The returned thumbnail may not respect the device pixel ratio requested.
126 * Use QPixmap::devicePixelRatio to check, or paint as necessary.
127 *
128 * \since 5.84
129 */
130 void setDevicePixelRatio(qreal dpr);
131
132 /*!
133 * Returns a list of all available preview plugins. The list
134 * contains the basenames of the plugins' .desktop files (no path,
135 * no .desktop).
136 * Returns the list of all available plugins
137 */
138 static QStringList availablePlugins();
139
140 /*!
141 * Returns all plugins that are considered when a preview is generated
142 * The result is internally cached, meaning any further method call will not reload the plugins
143 * \since 5.90
144 */
145 static QList<KPluginMetaData> availableThumbnailerPlugins();
146
147 /*!
148 * Returns a list of plugins that should be enabled by default, which is all plugins
149 * Minus the plugins specified in an internal blacklist
150 * Returns the list of plugins that should be enabled by default
151 * \since 5.40
152 */
153 static QStringList defaultPlugins();
154
155 /*!
156 * Returns a list of all supported MIME types. The list can
157 * contain entries like text/ * (without the space).
158 * Returns the list of MIME types
159 */
160 static QStringList supportedMimeTypes();
161
162Q_SIGNALS:
163 /*!
164 * Emitted when a thumbnail picture for \a item has been successfully
165 * retrieved.
166 *
167 * \a item the file of the preview
168 *
169 * \a preview the preview image
170 *
171 * \note If you need a preview as a QImage object, use the generated() signal.
172 * \sa generated()
173 */
174 void gotPreview(const KFileItem &item, const QPixmap &preview);
175 /*!
176 * Emitted when a thumbnail for \a item could not be created,
177 * either because a ThumbCreator for its MIME type does not
178 * exist, or because something went wrong.
179 *
180 * \a item the file that failed
181 */
182 void failed(const KFileItem &item);
183 /*!
184 * Emitted when a \a preview for \a item has been successfully generated.
185 *
186 * \since 6.15
187 */
188 void generated(const KFileItem &item, const QImage &preview);
189
190protected Q_SLOTS:
191 void slotResult(KJob *job) override;
192
193private:
194 Q_DECLARE_PRIVATE(PreviewJob)
195
196public:
197 /*!
198 * Sets a default device Pixel Ratio used for Previews
199 * \sa setDevicePixelRatio
200 *
201 * Defaults to 1
202 *
203 * \since 5.84
204 */
205 static void setDefaultDevicePixelRatio(qreal devicePixelRatio);
206};
207
208/*!
209 * \relates KIO::PreviewJob
210 *
211 * Creates a PreviewJob to generate a preview image for the given items.
212 *
213 * \a items List of files to create previews for.
214 *
215 * \a size Desired size of the preview.
216 *
217 * \a enabledPlugins If non-zero it defines the list of plugins that
218 * are considered for generating the preview. If
219 * enabledPlugins is zero the plugins specified in the
220 * KConfigGroup "PreviewSettings" are used.
221 */
222KIOGUI_EXPORT PreviewJob *filePreview(const KFileItemList &items, const QSize &size, const QStringList *enabledPlugins = nullptr);
223}
224
225#endif
226

source code of kio/src/gui/previewjob.h