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 "kiowidgets_export.h" 15 #include <kfileitem.h> 16 #include <kio/job.h> 17 18 class QPixmap; 19 20 namespace KIO 21 { 22 class PreviewJobPrivate; 23 /*! 24 * @class KIO::PreviewJob previewjob.h <KIO/PreviewJob> 25 * 26 * This class catches a preview (thumbnail) for files. 27 * @short KIO Job to get a thumbnail picture 28 */ 29 class KIOWIDGETS_EXPORT PreviewJob : public KIO::Job 30 { 31 Q_OBJECT 32 public: 33 /** 34 * Specifies the type of scaling that is applied to the generated preview. 35 * For HiDPI, pixel density scaling, @see setDevicePixelRatio 36 * 37 * @since 4.7 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 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(4, 7) 59 /** 60 * Creates a new PreviewJob. 61 * @param items a list of files to create previews for 62 * @param width the desired width 63 * @param height the desired height, 0 to use the @p width 64 * @param iconSize the size of the MIME type icon to overlay over the 65 * preview or zero to not overlay an icon. This has no effect if the 66 * preview plugin that will be used doesn't use icon overlays. 67 * @param iconAlpha transparency to use for the icon overlay 68 * @param scale if the image is to be scaled to the requested size or 69 * returned in its original size 70 * @param save if the image should be cached for later use 71 * @param enabledPlugins If non-zero, this points to a list containing 72 * the names of the plugins that may be used. If enabledPlugins is zero 73 * all available plugins are used. 74 * 75 * @deprecated Since 4.7, use PreviewJob(const KFileItemList&, const QSize&, const QStringList*) in combination 76 * with the setter-methods instead. Note that the semantics of 77 * \p enabledPlugins has been slightly changed. 78 */ 79 KIOWIDGETS_DEPRECATED_VERSION(4, 7, "Use PreviewJob(const KFileItemList&, const QSize&, const QStringList*)") 80 PreviewJob(const KFileItemList &items, int width, int height, int iconSize, int iconAlpha, bool scale, bool save, const QStringList *enabledPlugins); 81 #endif 82 83 /** 84 * @param items List of files to create previews for. 85 * @param size Desired size of the preview. 86 * @param enabledPlugins If non-zero it defines the list of plugins that 87 * are considered for generating the preview. If 88 * enabledPlugins is zero the plugins specified in the 89 * KConfigGroup "PreviewSettings" are used. 90 * @since 4.7 91 */ 92 PreviewJob(const KFileItemList &items, const QSize &size, const QStringList *enabledPlugins = nullptr); 93 94 ~PreviewJob() override; 95 96 /** 97 * Sets the size of the MIME-type icon which overlays the preview. If zero 98 * is passed no overlay will be shown at all. The setting has no effect if 99 * the preview plugin that will be used does not use icon overlays. Per 100 * default the size is set to 0. 101 * @since 4.7 102 */ 103 void setOverlayIconSize(int size); 104 105 /** 106 * @return The size of the MIME-type icon which overlays the preview. 107 * @see PreviewJob::setOverlayIconSize() 108 * @since 4.7 109 */ 110 int overlayIconSize() const; 111 112 /** 113 * Sets the alpha-value for the MIME-type icon which overlays the preview. 114 * The alpha-value may range from 0 (= fully transparent) to 255 (= opaque). 115 * Per default the value is set to 70. 116 * @see PreviewJob::setOverlayIconSize() 117 * @since 4.7 118 */ 119 void setOverlayIconAlpha(int alpha); 120 121 /** 122 * @return The alpha-value for the MIME-type icon which overlays the preview. 123 * Per default 70 is returned. 124 * @see PreviewJob::setOverlayIconAlpha() 125 * @since 4.7 126 */ 127 int overlayIconAlpha() const; 128 129 /** 130 * Sets the scale type for the generated preview. Per default 131 * PreviewJob::ScaledAndCached is set. 132 * @see PreviewJob::ScaleType 133 * @since 4.7 134 */ 135 void setScaleType(ScaleType type); 136 137 /** 138 * @return The scale type for the generated preview. 139 * @see PreviewJob::ScaleType 140 * @since 4.7 141 */ 142 ScaleType scaleType() const; 143 144 /** 145 * Removes an item from preview processing. Use this if you passed 146 * an item to filePreview and want to delete it now. 147 * 148 * @param url the url of the item that should be removed from the preview queue 149 */ 150 void removeItem(const QUrl &url); 151 152 /** 153 * If @p ignoreSize is true, then the preview is always 154 * generated regardless of the settings 155 **/ 156 void setIgnoreMaximumSize(bool ignoreSize = true); 157 158 /** 159 * Sets the sequence index given to the thumb creators. 160 * Use the sequence index, it is possible to create alternative 161 * icons for the same item. For example it may allow iterating through 162 * the items of a directory, or the frames of a video. 163 * 164 * @since 4.3 165 **/ 166 void setSequenceIndex(int index); 167 168 /** 169 * Returns the currently set sequence index 170 * 171 * @since 4.3 172 **/ 173 int sequenceIndex() const; 174 175 /** 176 * Returns the index at which the thumbs of a ThumbSequenceCreator start 177 * wrapping around ("looping"). Fractional values may be returned if the 178 * ThumbSequenceCreator supports sub-integer precision, but frontends 179 * supporting only integer sequence indices may choose to round it down. 180 * 181 * @see ThumbSequenceCreator::sequenceIndexWraparoundPoint() 182 * @since 5.80 183 */ 184 float sequenceIndexWraparoundPoint() const; 185 186 /** 187 * Determines whether the ThumbCreator in use is a ThumbSequenceCreator. 188 * 189 * @since 5.80 190 */ 191 bool handlesSequences() const; 192 193 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 86) 194 /** 195 * Request preview to use the device pixel ratio @p dpr. 196 * The returned thumbnail may not respect the device pixel ratio requested. 197 * Use QPixmap::devicePixelRatio to check, or paint as necessary. 198 * 199 * @since 5.80 200 * @deprecated Since 5.86, use setDevicePixelRatio(qreal dpr) instead 201 */ 202 KIOWIDGETS_DEPRECATED_VERSION(5, 86, "Use setDevicePixelRatio(qreal dpr)") 203 void setDevicePixelRatio(int dpr); 204 #endif 205 206 /** 207 * Request preview to use the device pixel ratio @p dpr. 208 * The returned thumbnail may not respect the device pixel ratio requested. 209 * Use QPixmap::devicePixelRatio to check, or paint as necessary. 210 * 211 * @since 5.84 212 */ 213 void setDevicePixelRatio(qreal dpr); 214 215 /** 216 * Returns a list of all available preview plugins. The list 217 * contains the basenames of the plugins' .desktop files (no path, 218 * no .desktop). 219 * @return the list of all available plugins 220 */ 221 static QStringList availablePlugins(); 222 223 /** 224 * Returns a list of plugins that should be enabled by default, which is all plugins 225 * Minus the plugins specified in an internal blacklist 226 * @return the list of plugins that should be enabled by default 227 * @since 5.40 228 */ 229 static QStringList defaultPlugins(); 230 231 /** 232 * Returns a list of all supported MIME types. The list can 233 * contain entries like text/ * (without the space). 234 * @return the list of MIME types 235 */ 236 static QStringList supportedMimeTypes(); 237 238 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(4, 5) 239 /** 240 * Returns the default "maximum file size", in bytes, used by PreviewJob. 241 * This is useful for applications providing a GUI for letting the user change the size. 242 * @since 4.1 243 * @deprecated Since 4.5, PreviewJob uses different maximum file sizes dependent on the URL. 244 * The returned file size is only valid for local URLs. 245 */ 246 KIOWIDGETS_DEPRECATED_VERSION(4, 5, "See API dox") 247 static KIO::filesize_t maximumFileSize(); 248 #endif 249 250 Q_SIGNALS: 251 /** 252 * Emitted when a thumbnail picture for @p item has been successfully 253 * retrieved. 254 * @param item the file of the preview 255 * @param preview the preview image 256 */ 257 void gotPreview(const KFileItem &item, const QPixmap &preview); 258 /** 259 * Emitted when a thumbnail for @p item could not be created, 260 * either because a ThumbCreator for its MIME type does not 261 * exist, or because something went wrong. 262 * @param item the file that failed 263 */ 264 void failed(const KFileItem &item); 265 266 protected Q_SLOTS: 267 void slotResult(KJob *job) override; 268 269 private: 270 Q_PRIVATE_SLOT(d_func(), void startPreview()) 271 Q_PRIVATE_SLOT(d_func(), void slotThumbData(KIO::Job *, const QByteArray &)) 272 Q_DECLARE_PRIVATE(PreviewJob) 273 274 public: 275 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 86) 276 /** 277 * Sets a default device Pixel Ratio used for Previews 278 * @see setDevicePixelRatio 279 * 280 * Defaults to 1 281 * 282 * @since 5.80 283 * @deprecated Since 5.86, use setDefaultDevicePixelRatio(qreal dpr) instead 284 */ 285 KIOWIDGETS_DEPRECATED_VERSION(5, 86, "Use setDefaultDevicePixelRatio(qreal dpr)") 286 static void setDefaultDevicePixelRatio(int devicePixelRatio); 287 #endif 288 289 /** 290 * Sets a default device Pixel Ratio used for Previews 291 * @see setDevicePixelRatio 292 * 293 * Defaults to 1 294 * 295 * @since 5.84 296 */ 297 static void setDefaultDevicePixelRatio(qreal devicePixelRatio); 298 }; 299 300 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(4, 7) 301 /** 302 * Creates a PreviewJob to generate or retrieve a preview image 303 * for the given URL. 304 * 305 * @param items files to get previews for 306 * @param width the maximum width to use 307 * @param height the maximum height to use, if this is 0, the same 308 * value as width is used. 309 * @param iconSize the size of the MIME type icon to overlay over the 310 * preview or zero to not overlay an icon. This has no effect if the 311 * preview plugin that will be used doesn't use icon overlays. 312 * @param iconAlpha transparency to use for the icon overlay 313 * @param scale if the image is to be scaled to the requested size or 314 * returned in its original size 315 * @param save if the image should be cached for later use 316 * @param enabledPlugins if non-zero, this points to a list containing 317 * the names of the plugins that may be used. 318 * @return the new PreviewJob 319 * @see PreviewJob::availablePlugins() 320 * @deprecated Since 4.7, use KIO::filePreview(const KFileItemList&, const QSize&, const QStringList*) in combination 321 * with the setter-methods instead. Note that the semantics of 322 * \p enabledPlugins has been slightly changed. 323 */ 324 KIOWIDGETS_EXPORT 325 KIOWIDGETS_DEPRECATED_VERSION(4, 7, "Use KIO::filePreview(const KFileItemList &, const QSize &, const QStringList *") 326 PreviewJob *filePreview(const KFileItemList &items, 327 int width, 328 int height = 0, 329 int iconSize = 0, 330 int iconAlpha = 70, 331 bool scale = true, 332 bool save = true, 333 const QStringList *enabledPlugins = nullptr); // KDE5: use enums instead of bool scale + bool save 334 #endif 335 336 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(4, 7) 337 /** 338 * Creates a PreviewJob to generate or retrieve a preview image 339 * for the given URL. 340 * 341 * @param items files to get previews for 342 * @param width the maximum width to use 343 * @param height the maximum height to use, if this is 0, the same 344 * value as width is used. 345 * @param iconSize the size of the MIME type icon to overlay over the 346 * preview or zero to not overlay an icon. This has no effect if the 347 * preview plugin that will be used doesn't use icon overlays. 348 * @param iconAlpha transparency to use for the icon overlay 349 * @param scale if the image is to be scaled to the requested size or 350 * returned in its original size 351 * @param save if the image should be cached for later use 352 * @param enabledPlugins if non-zero, this points to a list containing 353 * the names of the plugins that may be used. 354 * @return the new PreviewJob 355 * @see PreviewJob::availablePlugins() 356 * @deprecated Since 4.7, use KIO::filePreview(const KFileItemList&, const QSize&, const QStringList*) in combination 357 * with the setter-methods instead. Note that the semantics of 358 * \p enabledPlugins has been slightly changed. 359 */ 360 KIOWIDGETS_EXPORT 361 KIOWIDGETS_DEPRECATED_VERSION(4, 7, "Use KIO::filePreview(const KFileItemList &, const QSize &, const QStringList *") 362 PreviewJob *filePreview(const QList<QUrl> &items, 363 int width, 364 int height = 0, 365 int iconSize = 0, 366 int iconAlpha = 70, 367 bool scale = true, 368 bool save = true, 369 const QStringList *enabledPlugins = nullptr); 370 #endif 371 372 /** 373 * Creates a PreviewJob to generate a preview image for the given items. 374 * @param items List of files to create previews for. 375 * @param size Desired size of the preview. 376 * @param enabledPlugins If non-zero it defines the list of plugins that 377 * are considered for generating the preview. If 378 * enabledPlugins is zero the plugins specified in the 379 * KConfigGroup "PreviewSettings" are used. 380 * @since 4.7 381 */ 382 KIOWIDGETS_EXPORT PreviewJob *filePreview(const KFileItemList &items, const QSize &size, const QStringList *enabledPlugins = nullptr); 383 } 384 385 #endif 386