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 | |
19 | class QString; |
20 | class QImage; |
21 | |
22 | namespace KIO |
23 | { |
24 | |
25 | class ThumbnailCreatorPrivate; |
26 | class ThumbnailRequestPrivate; |
27 | class 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 | */ |
41 | class KIOGUI_EXPORT ThumbnailRequest |
42 | { |
43 | public: |
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 | |
107 | private: |
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 | */ |
125 | class KIOGUI_EXPORT ThumbnailResult |
126 | { |
127 | public: |
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 | |
189 | private: |
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 | */ |
247 | class KIOGUI_EXPORT ThumbnailCreator : public QObject |
248 | { |
249 | Q_OBJECT |
250 | public: |
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 | |
259 | private: |
260 | void *d; // Placeholder |
261 | }; |
262 | } |
263 | #endif |
264 | |