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

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