1// -*- c++ -*-
2/*
3 This file is part of the KDE libraries
4 SPDX-FileCopyrightText: 2000 David Faure <faure@kde.org>
5 SPDX-FileCopyrightText: 2000 Carsten Pfeiffer <pfeiffer@kde.org>
6 SPDX-FileCopyrightText: 2001 Malte Starostik <malte.starostik@t-online.de>
7
8 SPDX-License-Identifier: LGPL-2.0-or-later
9*/
10
11#ifndef KIO_PREVIEWJOB_H
12#define KIO_PREVIEWJOB_H
13
14#include "kiogui_export.h"
15#include <kfileitem.h>
16#include <kio/job.h>
17
18class QPixmap;
19class KPluginMetaData;
20
21namespace KIO
22{
23class PreviewJobPrivate;
24/*!
25 * @class KIO::PreviewJob previewjob.h <KIO/PreviewJob>
26 *
27 * This class catches a preview (thumbnail) for files.
28 * @short KIO Job to get a thumbnail picture
29 */
30class KIOGUI_EXPORT PreviewJob : public KIO::Job
31{
32 Q_OBJECT
33public:
34 /**
35 * Specifies the type of scaling that is applied to the generated preview.
36 * For HiDPI, pixel density scaling, @see setDevicePixelRatio
37 *
38 */
39 enum ScaleType {
40 /**
41 * The original size of the preview will be returned. Most previews
42 * will return a size of 256 x 256 pixels.
43 */
44 Unscaled,
45 /**
46 * The preview will be scaled to the size specified when constructing
47 * the PreviewJob. The aspect ratio will be kept.
48 */
49 Scaled,
50 /**
51 * The preview will be scaled to the size specified when constructing
52 * the PreviewJob. The result will be cached for later use. Per default
53 * ScaledAndCached is set.
54 */
55 ScaledAndCached,
56 };
57
58 /**
59 * @param items List of files to create previews for.
60 * @param size Desired size of the preview.
61 * @param enabledPlugins If non-zero it defines the list of plugins that
62 * are considered for generating the preview. If
63 * enabledPlugins is zero the plugins specified in the
64 * KConfigGroup "PreviewSettings" are used.
65 */
66 PreviewJob(const KFileItemList &items, const QSize &size, const QStringList *enabledPlugins = nullptr);
67
68 ~PreviewJob() override;
69
70 /**
71 * Sets the scale type for the generated preview. Per default
72 * PreviewJob::ScaledAndCached is set.
73 * @see PreviewJob::ScaleType
74 */
75 void setScaleType(ScaleType type);
76
77 /**
78 * @return The scale type for the generated preview.
79 * @see PreviewJob::ScaleType
80 */
81 ScaleType scaleType() const;
82
83 /**
84 * Removes an item from preview processing. Use this if you passed
85 * an item to filePreview and want to delete it now.
86 *
87 * @param url the url of the item that should be removed from the preview queue
88 */
89 void removeItem(const QUrl &url);
90
91 /**
92 * If @p ignoreSize is true, then the preview is always
93 * generated regardless of the settings
94 **/
95 void setIgnoreMaximumSize(bool ignoreSize = true);
96
97 /**
98 * Sets the sequence index given to the thumb creators.
99 * Use the sequence index, it is possible to create alternative
100 * icons for the same item. For example it may allow iterating through
101 * the items of a directory, or the frames of a video.
102 *
103 **/
104 void setSequenceIndex(int index);
105
106 /**
107 * Returns the currently set sequence index
108 *
109 **/
110 int sequenceIndex() const;
111
112 /**
113 * Returns the index at which the thumbs of a ThumbSequenceCreator start
114 * wrapping around ("looping"). Fractional values may be returned if the
115 * ThumbSequenceCreator supports sub-integer precision, but frontends
116 * supporting only integer sequence indices may choose to round it down.
117 *
118 * @see ThumbSequenceCreator::sequenceIndexWraparoundPoint()
119 * @since 5.80
120 */
121 float sequenceIndexWraparoundPoint() const;
122
123 /**
124 * Determines whether the ThumbCreator in use is a ThumbSequenceCreator.
125 *
126 * @since 5.80
127 */
128 bool handlesSequences() const;
129
130 /**
131 * Request preview to use the device pixel ratio @p dpr.
132 * The returned thumbnail may not respect the device pixel ratio requested.
133 * Use QPixmap::devicePixelRatio to check, or paint as necessary.
134 *
135 * @since 5.84
136 */
137 void setDevicePixelRatio(qreal dpr);
138
139 /**
140 * Returns a list of all available preview plugins. The list
141 * contains the basenames of the plugins' .desktop files (no path,
142 * no .desktop).
143 * @return the list of all available plugins
144 */
145 static QStringList availablePlugins();
146
147 /**
148 * Returns all plugins that are considered when a preview is generated
149 * The result is internally cached, meaning any further method call will not reload the plugins
150 * @since 5.90
151 */
152 static QList<KPluginMetaData> availableThumbnailerPlugins();
153
154 /**
155 * Returns a list of plugins that should be enabled by default, which is all plugins
156 * Minus the plugins specified in an internal blacklist
157 * @return the list of plugins that should be enabled by default
158 * @since 5.40
159 */
160 static QStringList defaultPlugins();
161
162 /**
163 * Returns a list of all supported MIME types. The list can
164 * contain entries like text/ * (without the space).
165 * @return the list of MIME types
166 */
167 static QStringList supportedMimeTypes();
168
169Q_SIGNALS:
170 /**
171 * Emitted when a thumbnail picture for @p item has been successfully
172 * retrieved.
173 * @param item the file of the preview
174 * @param preview the preview image
175 */
176 void gotPreview(const KFileItem &item, const QPixmap &preview);
177 /**
178 * Emitted when a thumbnail for @p item could not be created,
179 * either because a ThumbCreator for its MIME type does not
180 * exist, or because something went wrong.
181 * @param item the file that failed
182 */
183 void failed(const KFileItem &item);
184
185protected Q_SLOTS:
186 void slotResult(KJob *job) override;
187
188private:
189 Q_DECLARE_PRIVATE(PreviewJob)
190
191public:
192 /**
193 * Sets a default device Pixel Ratio used for Previews
194 * @see setDevicePixelRatio
195 *
196 * Defaults to 1
197 *
198 * @since 5.84
199 */
200 static void setDefaultDevicePixelRatio(qreal devicePixelRatio);
201};
202
203/**
204 * Creates a PreviewJob to generate a preview image for the given items.
205 * @param items List of files to create previews for.
206 * @param size Desired size of the preview.
207 * @param enabledPlugins If non-zero it defines the list of plugins that
208 * are considered for generating the preview. If
209 * enabledPlugins is zero the plugins specified in the
210 * KConfigGroup "PreviewSettings" are used.
211 */
212KIOGUI_EXPORT PreviewJob *filePreview(const KFileItemList &items, const QSize &size, const QStringList *enabledPlugins = nullptr);
213}
214
215#endif
216

source code of kio/src/gui/previewjob.h