1 | // -*- c++ -*- |
2 | // vim: ts=4 sw=4 et |
3 | /* This file is part of the KDE libraries |
4 | Copyright (C) 2000 David Faure <faure@kde.org> |
5 | 2000 Carsten Pfeiffer <pfeiffer@kde.org> |
6 | 2001 Malte Starostik <malte.starostik@t-online.de> |
7 | |
8 | This library is free software; you can redistribute it and/or |
9 | modify it under the terms of the GNU Library General Public |
10 | License as published by the Free Software Foundation; either |
11 | version 2 of the License, or (at your option) any later version. |
12 | |
13 | This library is distributed in the hope that it will be useful, |
14 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
15 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
16 | Library General Public License for more details. |
17 | |
18 | You should have received a copy of the GNU Library General Public License |
19 | along with this library; see the file COPYING.LIB. If not, write to |
20 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
21 | Boston, MA 02110-1301, USA. |
22 | */ |
23 | |
24 | #ifndef KIO_PREVIEWJOB_H |
25 | #define KIO_PREVIEWJOB_H |
26 | |
27 | #include <kfileitem.h> |
28 | #include <kio/job.h> |
29 | |
30 | class QPixmap; |
31 | |
32 | namespace KIO { |
33 | class PreviewJobPrivate; |
34 | /*! |
35 | * This class catches a preview (thumbnail) for files. |
36 | * @short KIO Job to get a thumbnail picture |
37 | */ |
38 | class KIO_EXPORT PreviewJob : public KIO::Job |
39 | { |
40 | Q_OBJECT |
41 | public: |
42 | /** |
43 | * Specifies the type of scaling that is applied to the generated preview. |
44 | * @since 4.7 |
45 | */ |
46 | enum ScaleType { |
47 | /** |
48 | * The original size of the preview will be returned. Most previews |
49 | * will return a size of 256 x 256 pixels. |
50 | */ |
51 | Unscaled, |
52 | /** |
53 | * The preview will be scaled to the size specified when constructing |
54 | * the PreviewJob. The aspect ratio will be kept. |
55 | */ |
56 | Scaled, |
57 | /** |
58 | * The preview will be scaled to the size specified when constructing |
59 | * the PreviewJob. The result will be cached for later use. Per default |
60 | * ScaledAndCached is set. |
61 | */ |
62 | ScaledAndCached |
63 | }; |
64 | |
65 | #ifndef KDE_NO_DEPRECATED |
66 | /** |
67 | * Creates a new PreviewJob. |
68 | * @param items a list of files to create previews for |
69 | * @param width the desired width |
70 | * @param height the desired height, 0 to use the @p width |
71 | * @param iconSize the size of the mimetype icon to overlay over the |
72 | * preview or zero to not overlay an icon. This has no effect if the |
73 | * preview plugin that will be used doesn't use icon overlays. |
74 | * @param iconAlpha transparency to use for the icon overlay |
75 | * @param scale if the image is to be scaled to the requested size or |
76 | * returned in its original size |
77 | * @param save if the image should be cached for later use |
78 | * @param enabledPlugins If non-zero, this points to a list containing |
79 | * the names of the plugins that may be used. If enabledPlugins is zero |
80 | * all available plugins are used. |
81 | * |
82 | * @deprecated Use PreviewJob(KFileItemList, QSize, QStringList) in combination |
83 | * with the setter-methods instead. Note that the semantics of |
84 | * \p enabledPlugins has been slightly changed. |
85 | */ |
86 | KDE_DEPRECATED PreviewJob(const KFileItemList& items, int width, int height, |
87 | int iconSize, int iconAlpha, bool scale, bool save, |
88 | const QStringList *enabledPlugins); |
89 | #endif |
90 | |
91 | /** |
92 | * @param items List of files to create previews for. |
93 | * @param size Desired size of the preview. |
94 | * @param enabledPlugins If non-zero it defines the list of plugins that |
95 | * are considered for generating the preview. If |
96 | * enabledPlugins is zero the plugins specified in the |
97 | * KConfigGroup "PreviewSettings" are used. |
98 | * @since 4.7 |
99 | */ |
100 | PreviewJob(const KFileItemList &items, |
101 | const QSize &size, |
102 | const QStringList *enabledPlugins = 0); |
103 | |
104 | virtual ~PreviewJob(); |
105 | |
106 | /** |
107 | * Sets the size of the MIME-type icon which overlays the preview. If zero |
108 | * is passed no overlay will be shown at all. The setting has no effect if |
109 | * the preview plugin that will be used does not use icon overlays. Per |
110 | * default the size is set to 0. |
111 | * @since 4.7 |
112 | */ |
113 | void setOverlayIconSize(int size); |
114 | |
115 | /** |
116 | * @return The size of the MIME-type icon which overlays the preview. |
117 | * @see PreviewJob::setOverlayIconSize() |
118 | * @since 4.7 |
119 | */ |
120 | int overlayIconSize() const; |
121 | |
122 | /** |
123 | * Sets the alpha-value for the MIME-type icon which overlays the preview. |
124 | * The alpha-value may range from 0 (= fully transparent) to 255 (= opaque). |
125 | * Per default the value is set to 70. |
126 | * @see PreviewJob::setOverlayIconSize() |
127 | * @since 4.7 |
128 | */ |
129 | void setOverlayIconAlpha(int alpha); |
130 | |
131 | /** |
132 | * @return The alpha-value for the MIME-type icon which overlays the preview. |
133 | * Per default 70 is returned. |
134 | * @see PreviewJob::setOverlayIconAlpha() |
135 | * @since 4.7 |
136 | */ |
137 | int overlayIconAlpha() const; |
138 | |
139 | /** |
140 | * Sets the scale type for the generated preview. Per default |
141 | * PreviewJob::ScaledAndCached is set. |
142 | * @see PreviewJob::ScaleType |
143 | * @since 4.7 |
144 | */ |
145 | void setScaleType(ScaleType type); |
146 | |
147 | /** |
148 | * @return The scale type for the generated preview. |
149 | * @see PreviewJob::ScaleType |
150 | * @since 4.7 |
151 | */ |
152 | ScaleType scaleType() const; |
153 | |
154 | /** |
155 | * Removes an item from preview processing. Use this if you passed |
156 | * an item to filePreview and want to delete it now. |
157 | * |
158 | * @param url the url of the item that should be removed from the preview queue |
159 | */ |
160 | void removeItem( const KUrl& url ); |
161 | |
162 | /** |
163 | * If @p ignoreSize is true, then the preview is always |
164 | * generated regardless of the settings |
165 | **/ |
166 | void setIgnoreMaximumSize(bool ignoreSize = true); |
167 | |
168 | /** |
169 | * Sets the sequence index given to the thumb creators. |
170 | * Use the sequence index, it is possible to create alternative |
171 | * icons for the same item. For example it may allow iterating through |
172 | * the items of a directory, or the frames of a video. |
173 | * |
174 | * @since KDE 4.3 |
175 | **/ |
176 | void setSequenceIndex(int index); |
177 | |
178 | /** |
179 | * Returns the currently set sequence index |
180 | * |
181 | * @since KDE 4.3 |
182 | **/ |
183 | int sequenceIndex() const; |
184 | |
185 | /** |
186 | * Returns a list of all available preview plugins. The list |
187 | * contains the basenames of the plugins' .desktop files (no path, |
188 | * no .desktop). |
189 | * @return the list of plugins |
190 | */ |
191 | static QStringList availablePlugins(); |
192 | |
193 | /** |
194 | * Returns a list of all supported MIME types. The list can |
195 | * contain entries like text/ * (without the space). |
196 | * @return the list of mime types |
197 | */ |
198 | static QStringList supportedMimeTypes(); |
199 | |
200 | /** |
201 | * Returns the default "maximum file size", in bytes, used by PreviewJob. |
202 | * This is useful for applications providing a GUI for letting the user change the size. |
203 | * @since 4.1 |
204 | * @deprecated PreviewJob uses different maximum file sizes dependent on the URL since 4.5. |
205 | * The returned file size is only valid for local URLs. |
206 | */ |
207 | #ifndef KDE_NO_DEPRECATED |
208 | KDE_DEPRECATED static KIO::filesize_t maximumFileSize(); |
209 | #endif |
210 | |
211 | |
212 | Q_SIGNALS: |
213 | /** |
214 | * Emitted when a thumbnail picture for @p item has been successfully |
215 | * retrieved. |
216 | * @param item the file of the preview |
217 | * @param preview the preview image |
218 | */ |
219 | void gotPreview( const KFileItem& item, const QPixmap &preview ); |
220 | /** |
221 | * Emitted when a thumbnail for @p item could not be created, |
222 | * either because a ThumbCreator for its MIME type does not |
223 | * exist, or because something went wrong. |
224 | * @param item the file that failed |
225 | */ |
226 | void failed( const KFileItem& item ); |
227 | |
228 | protected Q_SLOTS: |
229 | virtual void slotResult( KJob *job ); |
230 | |
231 | private: |
232 | Q_PRIVATE_SLOT(d_func(), void startPreview()) |
233 | Q_PRIVATE_SLOT(d_func(), void slotThumbData(KIO::Job *, const QByteArray &)) |
234 | Q_DECLARE_PRIVATE(PreviewJob) |
235 | }; |
236 | |
237 | #ifndef KDE_NO_DEPRECATED |
238 | /** |
239 | * Creates a PreviewJob to generate or retrieve a preview image |
240 | * for the given URL. |
241 | * |
242 | * @param items files to get previews for |
243 | * @param width the maximum width to use |
244 | * @param height the maximum height to use, if this is 0, the same |
245 | * value as width is used. |
246 | * @param iconSize the size of the mimetype icon to overlay over the |
247 | * preview or zero to not overlay an icon. This has no effect if the |
248 | * preview plugin that will be used doesn't use icon overlays. |
249 | * @param iconAlpha transparency to use for the icon overlay |
250 | * @param scale if the image is to be scaled to the requested size or |
251 | * returned in its original size |
252 | * @param save if the image should be cached for later use |
253 | * @param enabledPlugins if non-zero, this points to a list containing |
254 | * the names of the plugins that may be used. |
255 | * @return the new PreviewJob |
256 | * @see PreviewJob::availablePlugins() |
257 | * @deprecated Use KIO::filePreview(KFileItemList, QSize, QStringList) in combination |
258 | * with the setter-methods instead. Note that the semantics of |
259 | * \p enabledPlugins has been slightly changed. |
260 | */ |
261 | KIO_EXPORT_DEPRECATED PreviewJob *filePreview( const KFileItemList &items, int width, int height = 0, int iconSize = 0, int iconAlpha = 70, bool scale = true, bool save = true, const QStringList *enabledPlugins = 0 ); // KDE5: use enums instead of bool scale + bool save |
262 | |
263 | /** |
264 | * Creates a PreviewJob to generate or retrieve a preview image |
265 | * for the given URL. |
266 | * |
267 | * @param items files to get previews for |
268 | * @param width the maximum width to use |
269 | * @param height the maximum height to use, if this is 0, the same |
270 | * value as width is used. |
271 | * @param iconSize the size of the mimetype icon to overlay over the |
272 | * preview or zero to not overlay an icon. This has no effect if the |
273 | * preview plugin that will be used doesn't use icon overlays. |
274 | * @param iconAlpha transparency to use for the icon overlay |
275 | * @param scale if the image is to be scaled to the requested size or |
276 | * returned in its original size |
277 | * @param save if the image should be cached for later use |
278 | * @param enabledPlugins if non-zero, this points to a list containing |
279 | * the names of the plugins that may be used. |
280 | * @return the new PreviewJob |
281 | * @see PreviewJob::availablePlugins() |
282 | * @deprecated Use KIO::filePreview(KFileItemList, QSize, QStringList) in combination |
283 | * with the setter-methods instead. Note that the semantics of |
284 | * \p enabledPlugins has been slightly changed. |
285 | */ |
286 | KIO_EXPORT_DEPRECATED PreviewJob *filePreview( const KUrl::List &items, int width, int height = 0, int iconSize = 0, int iconAlpha = 70, bool scale = true, bool save = true, const QStringList *enabledPlugins = 0 ); |
287 | #endif |
288 | |
289 | /** |
290 | * Creates a PreviewJob to generate a preview image for the given items. |
291 | * @param items List of files to create previews for. |
292 | * @param size Desired size of the preview. |
293 | * @param enabledPlugins If non-zero it defines the list of plugins that |
294 | * are considered for generating the preview. If |
295 | * enabledPlugins is zero the plugins specified in the |
296 | * KConfigGroup "PreviewSettings" are used. |
297 | * @since 4.7 |
298 | */ |
299 | KIO_EXPORT PreviewJob *filePreview(const KFileItemList &items, const QSize &size, const QStringList *enabledPlugins = 0); |
300 | } |
301 | |
302 | #endif |
303 | |