KIO

thumbnailcreator.h
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  * 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  */
37 class KIOGUI_EXPORT ThumbnailRequest
38 {
39 public:
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 
100 private:
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  */
113 class KIOGUI_EXPORT ThumbnailResult
114 {
115 public:
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 
177 private:
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  */
234 class KIOGUI_EXPORT ThumbnailCreator : public QObject
235 {
236  Q_OBJECT
237 public:
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 
246 private:
247  void *d; // Placeholder
248 };
249 }
250 #endif
KCALUTILS_EXPORT QString mimeType()
Encapsulates the output of a thumbnail request.
A namespace for KIO globals.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Thu Feb 15 2024 03:51:27 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.