KIO

thumbcreator.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 2000 Malte Starostik <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7 
8 #ifndef _THUMBCREATOR_H_
9 #define _THUMBCREATOR_H_
10 
11 #include "kiowidgets_export.h"
12 
13 class QString;
14 class QImage;
15 class QWidget;
16 
17 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 101)
18 /**
19  * @class ThumbCreator thumbcreator.h <KIO/ThumbCreator>
20  *
21  * Base class for thumbnail generator plugins.
22  *
23  * KIO::PreviewJob, via the "thumbnail" KIO worker, uses instances of this class
24  * to generate the thumbnail previews.
25  *
26  * To add support for a new document type, subclass ThumbCreator and implement
27  * create() to generate a thumbnail for a given path. Then create a factory
28  * method called "new_creator" to return instances of your subclass:
29  * \code
30  * extern "C"
31  * {
32  * Q_DECL_EXPORT ThumbCreator *new_creator()
33  * {
34  * return new FooThumbCreator();
35  * }
36  * };
37  * \endcode
38  *
39  * Compile your ThumbCreator as a module; for example, the relevant CMake code
40  * for a thumbnailer for the "foo" filetype might look like
41  * \code
42  * add_library(foothumbnail MODULE foothumbnail.cpp)
43  * target_link_libraries(foothumbnail PRIVATE KF5::KIOWidgets)
44  *
45  * install(TARGETS foothumbnail DESTINATION ${KDE_INSTALL_PLUGINDIR})
46  * \endcode
47  *
48  * You also need to create a desktop file describing the thumbnailer. For
49  * example:
50  * \code
51  * [Desktop Entry]
52  * Type=Service
53  * Name=Foo Documents
54  * X-KDE-ServiceTypes=ThumbCreator
55  * MimeType=application/x-foo;
56  * CacheThumbnail=true
57  * X-KDE-Library=foothumbcreator
58  * \endcode
59  *
60  * Of course, you will need to install it:
61  * \code
62  * install(FILES foothumbcreator.desktop DESTINATION ${KDE_INSTALL_KSERVICESDIR})
63  * \endcode
64  *
65  * Note that you can supply a comma-separated list of MIME types to the MimeTypes
66  * entry, naming all MIME types your ThumbCreator supports. You can also use
67  * simple wildcards, like
68  * \htmlonly "text/&#42;".\endhtmlonly\latexonly text/$\ast$.\endlatexonly
69  *
70  * If the thumbnail creation is cheap (such as text previews), you can set
71  * \code
72  * CacheThumbnail=false
73  * \endcode
74  * in the desktop file to prevent your thumbnails from being cached on disk.
75  *
76  * You can also use the "ThumbnailerVersion" optional property in the .desktop
77  * file, like
78  * \code
79  * ThumbnailerVersion=5
80  * \endcode
81  * When this is incremented (or defined when it previously was not), all the
82  * previously-cached thumbnails for this creator will be discarded. You should
83  * increase the version if and only if old thumbnails need to be regenerated.
84  *
85  * @deprecated since 5.101, use KIO::ThumbnailCreator instead
86  */
87 class KIOWIDGETS_EXPORT ThumbCreator
88 {
89 public:
90  /**
91  * Flags to provide hints to the user of this plugin.
92  * @see flags()
93  */
94  enum Flags {
95  None = 0, /**< No hints. */
96 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 32)
97  DrawFrame KIOWIDGETS_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 32, "See API dox") =
98  1, /**< \deprecated since 5.32. Used to paint a frame around the preview, but applications take care of that nowadays. */
99 #endif
100  BlendIcon = 2, /**< The MIME type icon should be blended over the preview. */
101  };
102 
103  /**
104  * Destructor.
105  */
106  virtual ~ThumbCreator();
107 
108  /**
109  * Creates a thumbnail.
110  *
111  * Note that this method should not do any scaling. The @p width and @p
112  * height parameters are provided as hints for images that are generated
113  * from non-image data (like text).
114  *
115  * @param path The path of the file to create a preview for. This is
116  * always a local path.
117  * @param width The requested preview width (see the note on scaling
118  * above).
119  * @param height The requested preview height (see the note on scaling
120  * above).
121  * @param img The QImage to store the preview in.
122  *
123  * @return @c true if a preview was successfully generated and store in @p
124  * img, @c false otherwise.
125  * @deprecated since 5.101, use KIO::ThumbnailCreator instead.
126  */
127  KIOWIDGETS_DEPRECATED_VERSION(5, 101, "Use KIO::ThumbnailCreator instead")
128  virtual bool create(const QString &path, int width, int height, QImage &img) = 0; // KF6 TODO: turn first arg into QUrl (see thumbnail/htmlcreator.cpp)
129 
130  /**
131  * Returns the flags for this plugin.
132  *
133  * @return XOR'd flags values.
134  * @see Flags
135  */
136  virtual Flags flags() const;
137 
138 #if KIOWIDGETS_BUILD_DEPRECATED_SINCE(5, 87)
139  /**
140  * Create a widget for configuring the thumb creator.
141  *
142  * The caller will take ownership of the returned instance and must ensure
143  * its deletion.
144  *
145  * The default implementation returns @c nullptr.
146  *
147  * The following key in the thumbcreator .desktop file must be set to
148  * mark the plugin as configurable:
149  * \code
150  * Configurable=true
151  * \endcode
152  *
153  * @return A QWidget instance, which the caller takes ownership of, or @c nullptr.
154  * @deprecated Since 5.87, deprecated for lack of usage and only being used for niche usecases.
155  * Instead use sane defaults and keep reading the config if it exists.
156  */
157  KIOWIDGETS_DEPRECATED_VERSION(5, 87, "See API docs")
158  virtual QWidget *createConfigurationWidget();
159 #endif
160 
161 #if KIOWIDGETS_BUILD_DEPRECATED_SINCE(5, 87)
162  /**
163  * Write the updated configuration.
164  *
165  * @param configurationWidget An object returned by
166  * createConfigurationWidget().
167  * @deprecated Since 5.87, see API docs of @p createConfigurationWidget
168  */
169  KIOWIDGETS_DEPRECATED_VERSION(5, 87, "See API docs of createConfigurationWidget")
170  virtual void writeConfiguration(const QWidget *configurationWidget);
171 #endif
172 };
173 
174 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 0)
175 /**
176  * @class ThumbCreatorV2 thumbcreator.h <KIO/ThumbCreator>
177  * @since 4.7
178  * @deprecated since 5.0, use ThumbCreator
179  */
180 class KIOWIDGETS_EXPORT KIOWIDGETS_DEPRECATED_VERSION(5, 0, "Use ThumbCreator") ThumbCreatorV2 : public ThumbCreator
181 {
182 public:
183  ~ThumbCreatorV2() override;
184 };
185 #endif
186 
187 // KF6 TODO: rename this to something less generic
188 typedef ThumbCreator *(*newCreator)();
189 
190 #endif
191 
192 #endif
Flags
Flags to provide hints to the user of this plugin.
Definition: thumbcreator.h:94
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Nov 28 2023 03:55:14 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.