1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2000 Malte Starostik <malte@kde.org>
4 SPDX-FileCopyrightText: 2022 Nicolas Fella <nicolas.fella@gmx.de>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8
9#ifndef _THUMBNAILCREATOR_H_
10#define _THUMBNAILCREATOR_H_
11
12#include "kiogui_export.h"
13
14#include <QObject>
15#include <QUrl>
16
17#include <memory>
18
19class QString;
20class QImage;
21
22namespace KIO
23{
24
25class ThumbnailCreatorPrivate;
26class ThumbnailRequestPrivate;
27class ThumbnailResultPrivate;
28
29/*!
30 * \class KIO::ThumbnailRequest
31 * \inheaderfile KIO/ThumbnailCreator
32 * \inmodule KIOGui
33 *
34 * \brief Encapsulates the input data for a thumbnail request.
35 *
36 * This includes the URL of the target file as well as additional
37 * data such as the target size
38 *
39 * \since 5.100
40 */
41class KIOGUI_EXPORT ThumbnailRequest
42{
43public:
44 /*!
45 * Contruct a new ThumbnailRequest for a given file.
46 *
47 * \a url URL of the relevant file.
48 *
49 * \a targetSize A size hint for the result image.
50 * The actual result size may be different. This already
51 * accounts for highdpi scaling, i.e. if a 500x500px thumbnail
52 * with a DPR of 2 is requested 1000x1000 is passed here.
53 *
54 * \a mimeType The MIME type of the target file.
55 *
56 * \a dpr The device pixle ratio for this request. This can
57 * be used to adjust the level of detail rendered. For example
58 * a thumbnail for text of size 1000x1000 and DPR 1 should have
59 * the name number of text lines as for a request of size 2000x2000
60 * and DPR 2.
61 *
62 * \a sequenceIndex If the thumbnailer supports sequences this
63 * determines which sequence frame is used. Pass 0 otherwise.
64 */
65 explicit ThumbnailRequest(const QUrl &url, const QSize &targetSize, const QString &mimeType, qreal dpr, float sequenceIndex);
66 ThumbnailRequest(const ThumbnailRequest &);
67 ThumbnailRequest &operator=(const ThumbnailRequest &);
68 ~ThumbnailRequest();
69
70 /*!
71 * URL of the relevant file
72 */
73 QUrl url() const;
74
75 /*!
76 * The target thumbnail size
77 */
78 QSize targetSize() const;
79
80 /*!
81 * The target file's MIME type
82 */
83 QString mimeType() const;
84
85 /*!
86 * The device Pixel Ratio used for thumbnail creation
87 */
88 qreal devicePixelRatio() const;
89
90 /*!
91 * If the thumb-creator can create a sequence of thumbnails,
92 * it should use this to decide what sequence item to use.
93 *
94 * If the value is zero, the standard thumbnail should be created.
95 *
96 * This can be used for example to create thumbnails for different
97 * timeframes in videos(For example 0m, 10m, 20m, ...).
98 *
99 * If the thumb-creator supports a high granularity, like a video,
100 * the sub-integer precision coming from the float should be respected.
101 *
102 * If the end of the sequence is reached, the sequence should start
103 * from the beginning.
104 */
105 float sequenceIndex() const;
106
107private:
108 std::unique_ptr<ThumbnailRequestPrivate> d;
109};
110
111/*!
112 * \class KIO::ThumbnailResult
113 * \inheaderfile KIO/ThumbnailCreator
114 * \inmodule KIOGui
115 *
116 * \brief Encapsulates the output of a thumbnail request.
117 *
118 * It contains information on whether the request was successful and,
119 * if successful, the requested thumbnail
120 *
121 * To create a result use KIO::ThumbnailResult::pass(image) or KIO::ThumbnailResult::fail()
122 *
123 * \since 5.100
124 */
125class KIOGUI_EXPORT ThumbnailResult
126{
127public:
128 ThumbnailResult(const ThumbnailResult &);
129 ThumbnailResult &operator=(const ThumbnailResult &);
130 ~ThumbnailResult();
131
132 /*!
133 * The requested thumbnail.
134 *
135 * If the request failed the image is null
136 */
137 QImage image() const;
138
139 /*!
140 * Whether the request was successful.
141 */
142 bool isValid() const;
143
144 /*!
145 * Returns the point at which this thumb-creator's sequence indices
146 * will wrap around (loop).
147 *
148 * Usually, the frontend will call setSequenceIndex() with indices
149 * that increase indefinitely with time, e.g. as long as the user
150 * keeps hovering a video file. Most thumb-creators however only
151 * want to display a finite sequence of thumbs, after which their
152 * sequence repeats.
153 *
154 * This method can return the sequence index at which this
155 * thumb-creator's sequence starts wrapping around to the start
156 * again ("looping"). The frontend may use this to generate only
157 * thumbs up to this index, and then use cached versions for the
158 * repeating sequence instead.
159 *
160 * Like sequenceIndex(), fractional values can be used if the
161 * wraparound does not happen at an integer position, but
162 * frontends handling only integer sequence indices may choose
163 * to round it down.
164 *
165 * By default, this method returns a negative index, which signals
166 * the frontend that it can't rely on this fixed-length sequence.
167 *
168 */
169 float sequenceIndexWraparoundPoint() const;
170
171 /*!
172 * Sets the point at which this thumb-creator's sequence indices
173 * will wrap around.
174 *
175 * \sa sequenceIndexWraparoundPoint()
176 */
177 void setSequenceIndexWraparoundPoint(float wraparoundPoint);
178
179 /*!
180 * Create a successful result with a given image
181 */
182 static ThumbnailResult pass(const QImage &image);
183
184 /*!
185 * Create an error result, i.e. the thumbnail creation failed
186 */
187 static ThumbnailResult fail();
188
189private:
190 KIOGUI_NO_EXPORT ThumbnailResult();
191 std::unique_ptr<ThumbnailResultPrivate> d;
192};
193
194/*!
195 * \class KIO::ThumbnailCreator
196 * \inheaderfile KIO/ThumbnailCreator
197 * \inmodule KIOGui
198 *
199 * \brief Base class for thumbnail generator plugins.
200 *
201 * KIO::PreviewJob, via the "thumbnail" KIO worker, uses instances of this class
202 * to generate the thumbnail previews.
203 *
204 * To add support for a new document type, subclass KIO::ThumbnailCreator and implement
205 * create() to generate a thumbnail for a given path.
206 *
207 * Compile your ThumbCreator as a plugin; for example, the relevant CMake code
208 * for a thumbnailer for the "foo" filetype might look like
209 * \code
210 * kcoreaddons_add_plugin(foothumbnail SOURCES foothumbnail.cpp INSTALL_NAMESPACE "kf6/thumbcreator")
211 * target_link_libraries(foothumbnail PRIVATE KF5::KIOGui)
212 * \endcode
213 *
214 * You also need a JSON file containing the metadata:
215 * \code
216 * {
217 * "CacheThumbnail": true,
218 * "KPlugin": {
219 * "MimeTypes": [
220 * "image/x-foo"
221 * ],
222 * "Name": "Foo Documents"
223 * }
224 * }
225 * \endcode
226 *
227 * MIME types can also use
228 * simple wildcards, like "text/\*"
229 *
230 * If the thumbnail creation is cheap (such as text previews), you can set
231 * \code
232 * "CacheThumbnail": false
233 * \endcode
234 * in metadata to prevent your thumbnails from being cached on disk.
235 *
236 * You can also use the "ThumbnailerVersion" optional property in the .desktop
237 * file, like
238 * \code
239 * "ThumbnailerVersion": 5
240 * \endcode
241 * When this is incremented (or defined when it previously was not), all the
242 * previously-cached thumbnails for this creator will be discarded. You should
243 * increase the version if and only if old thumbnails need to be regenerated.
244 *
245 * \since 5.100
246 */
247class KIOGUI_EXPORT ThumbnailCreator : public QObject
248{
249 Q_OBJECT
250public:
251 explicit ThumbnailCreator(QObject *parent, const QVariantList &args);
252 virtual ~ThumbnailCreator();
253
254 /*!
255 * Creates a thumbnail for a given request
256 */
257 virtual ThumbnailResult create(const ThumbnailRequest &request) = 0;
258
259private:
260 void *d; // Placeholder
261};
262}
263#endif
264

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