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
30class QPixmap;
31
32namespace 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