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