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

KDE's Doxygen guidelines are available online.