File indexing completed on 2025-02-02 11:02:01
0001 // -*- c++ -*- 0002 /* 0003 This file is part of the KDE libraries 0004 SPDX-FileCopyrightText: 2000 David Faure <faure@kde.org> 0005 SPDX-FileCopyrightText: 2000 Carsten Pfeiffer <pfeiffer@kde.org> 0006 SPDX-FileCopyrightText: 2001 Malte Starostik <malte.starostik@t-online.de> 0007 0008 SPDX-License-Identifier: LGPL-2.0-or-later 0009 */ 0010 0011 #ifndef KIO_PREVIEWJOB_H 0012 #define KIO_PREVIEWJOB_H 0013 0014 #include "kiowidgets_export.h" 0015 #include <kfileitem.h> 0016 #include <kio/job.h> 0017 0018 class QPixmap; 0019 class KPluginMetaData; 0020 0021 namespace KIO 0022 { 0023 class PreviewJobPrivate; 0024 /*! 0025 * @class KIO::PreviewJob previewjob.h <KIO/PreviewJob> 0026 * 0027 * This class catches a preview (thumbnail) for files. 0028 * @short KIO Job to get a thumbnail picture 0029 */ 0030 class KIOWIDGETS_EXPORT PreviewJob : public KIO::Job 0031 { 0032 Q_OBJECT 0033 public: 0034 /** 0035 * Specifies the type of scaling that is applied to the generated preview. 0036 * For HiDPI, pixel density scaling, @see setDevicePixelRatio 0037 * 0038 * @since 4.7 0039 */ 0040 enum ScaleType { 0041 /** 0042 * The original size of the preview will be returned. Most previews 0043 * will return a size of 256 x 256 pixels. 0044 */ 0045 Unscaled, 0046 /** 0047 * The preview will be scaled to the size specified when constructing 0048 * the PreviewJob. The aspect ratio will be kept. 0049 */ 0050 Scaled, 0051 /** 0052 * The preview will be scaled to the size specified when constructing 0053 * the PreviewJob. The result will be cached for later use. Per default 0054 * ScaledAndCached is set. 0055 */ 0056 ScaledAndCached, 0057 }; 0058 0059 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(4, 7) 0060 /** 0061 * Creates a new PreviewJob. 0062 * @param items a list of files to create previews for 0063 * @param width the desired width 0064 * @param height the desired height, 0 to use the @p width 0065 * @param iconSize the size of the MIME type icon to overlay over the 0066 * preview or zero to not overlay an icon. This has no effect if the 0067 * preview plugin that will be used doesn't use icon overlays. 0068 * @param iconAlpha transparency to use for the icon overlay 0069 * @param scale if the image is to be scaled to the requested size or 0070 * returned in its original size 0071 * @param save if the image should be cached for later use 0072 * @param enabledPlugins If non-zero, this points to a list containing 0073 * the names of the plugins that may be used. If enabledPlugins is zero 0074 * all available plugins are used. 0075 * 0076 * @deprecated Since 4.7, use PreviewJob(const KFileItemList&, const QSize&, const QStringList*) in combination 0077 * with the setter-methods instead. Note that the semantics of 0078 * \p enabledPlugins has been slightly changed. 0079 */ 0080 KIOWIDGETS_DEPRECATED_VERSION(4, 7, "Use PreviewJob(const KFileItemList&, const QSize&, const QStringList*)") 0081 PreviewJob(const KFileItemList &items, int width, int height, int iconSize, int iconAlpha, bool scale, bool save, const QStringList *enabledPlugins); 0082 #endif 0083 0084 /** 0085 * @param items List of files to create previews for. 0086 * @param size Desired size of the preview. 0087 * @param enabledPlugins If non-zero it defines the list of plugins that 0088 * are considered for generating the preview. If 0089 * enabledPlugins is zero the plugins specified in the 0090 * KConfigGroup "PreviewSettings" are used. 0091 * @since 4.7 0092 */ 0093 PreviewJob(const KFileItemList &items, const QSize &size, const QStringList *enabledPlugins = nullptr); 0094 0095 ~PreviewJob() override; 0096 0097 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 102) 0098 /** 0099 * Sets the size of the MIME-type icon which overlays the preview. If zero 0100 * is passed no overlay will be shown at all. The setting has no effect if 0101 * the preview plugin that will be used does not use icon overlays. Per 0102 * default the size is set to 0. 0103 * @since 4.7 0104 * 0105 * @deprecated since 5.102, not implemented. 0106 */ 0107 KIOWIDGETS_DEPRECATED_VERSION(5, 102, "Not implemented") 0108 void setOverlayIconSize(int size); 0109 #endif 0110 0111 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 102) 0112 /** 0113 * @return The size of the MIME-type icon which overlays the preview. 0114 * @see PreviewJob::setOverlayIconSize() 0115 * @since 4.7 0116 * 0117 * @deprecated since 5.102, not implemented. 0118 */ 0119 KIOWIDGETS_DEPRECATED_VERSION(5, 102, "Not implemented") 0120 int overlayIconSize() const; 0121 #endif 0122 0123 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 102) 0124 /** 0125 * Sets the alpha-value for the MIME-type icon which overlays the preview. 0126 * The alpha-value may range from 0 (= fully transparent) to 255 (= opaque). 0127 * Per default the value is set to 70. 0128 * @see PreviewJob::setOverlayIconSize() 0129 * @since 4.7 0130 * 0131 * @deprecated since 5.102, not implemented. 0132 */ 0133 KIOWIDGETS_DEPRECATED_VERSION(5, 102, "Not implemented") 0134 void setOverlayIconAlpha(int alpha); 0135 #endif 0136 0137 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 102) 0138 /** 0139 * @return The alpha-value for the MIME-type icon which overlays the preview. 0140 * Per default 70 is returned. 0141 * @see PreviewJob::setOverlayIconAlpha() 0142 * @since 4.7 0143 * 0144 * @deprecated since 5.102, not implemented. 0145 */ 0146 KIOWIDGETS_DEPRECATED_VERSION(5, 102, "Not implemented") 0147 int overlayIconAlpha() const; 0148 #endif 0149 0150 /** 0151 * Sets the scale type for the generated preview. Per default 0152 * PreviewJob::ScaledAndCached is set. 0153 * @see PreviewJob::ScaleType 0154 * @since 4.7 0155 */ 0156 void setScaleType(ScaleType type); 0157 0158 /** 0159 * @return The scale type for the generated preview. 0160 * @see PreviewJob::ScaleType 0161 * @since 4.7 0162 */ 0163 ScaleType scaleType() const; 0164 0165 /** 0166 * Removes an item from preview processing. Use this if you passed 0167 * an item to filePreview and want to delete it now. 0168 * 0169 * @param url the url of the item that should be removed from the preview queue 0170 */ 0171 void removeItem(const QUrl &url); 0172 0173 /** 0174 * If @p ignoreSize is true, then the preview is always 0175 * generated regardless of the settings 0176 **/ 0177 void setIgnoreMaximumSize(bool ignoreSize = true); 0178 0179 /** 0180 * Sets the sequence index given to the thumb creators. 0181 * Use the sequence index, it is possible to create alternative 0182 * icons for the same item. For example it may allow iterating through 0183 * the items of a directory, or the frames of a video. 0184 * 0185 * @since 4.3 0186 **/ 0187 void setSequenceIndex(int index); 0188 0189 /** 0190 * Returns the currently set sequence index 0191 * 0192 * @since 4.3 0193 **/ 0194 int sequenceIndex() const; 0195 0196 /** 0197 * Returns the index at which the thumbs of a ThumbSequenceCreator start 0198 * wrapping around ("looping"). Fractional values may be returned if the 0199 * ThumbSequenceCreator supports sub-integer precision, but frontends 0200 * supporting only integer sequence indices may choose to round it down. 0201 * 0202 * @see ThumbSequenceCreator::sequenceIndexWraparoundPoint() 0203 * @since 5.80 0204 */ 0205 float sequenceIndexWraparoundPoint() const; 0206 0207 /** 0208 * Determines whether the ThumbCreator in use is a ThumbSequenceCreator. 0209 * 0210 * @since 5.80 0211 */ 0212 bool handlesSequences() const; 0213 0214 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 86) 0215 /** 0216 * Request preview to use the device pixel ratio @p dpr. 0217 * The returned thumbnail may not respect the device pixel ratio requested. 0218 * Use QPixmap::devicePixelRatio to check, or paint as necessary. 0219 * 0220 * @since 5.80 0221 * @deprecated Since 5.86, use setDevicePixelRatio(qreal dpr) instead 0222 */ 0223 KIOWIDGETS_DEPRECATED_VERSION(5, 86, "Use setDevicePixelRatio(qreal dpr)") 0224 void setDevicePixelRatio(int dpr); 0225 #endif 0226 0227 /** 0228 * Request preview to use the device pixel ratio @p dpr. 0229 * The returned thumbnail may not respect the device pixel ratio requested. 0230 * Use QPixmap::devicePixelRatio to check, or paint as necessary. 0231 * 0232 * @since 5.84 0233 */ 0234 void setDevicePixelRatio(qreal dpr); 0235 0236 /** 0237 * Returns a list of all available preview plugins. The list 0238 * contains the basenames of the plugins' .desktop files (no path, 0239 * no .desktop). 0240 * @return the list of all available plugins 0241 */ 0242 static QStringList availablePlugins(); 0243 0244 /** 0245 * Returns all plugins that are considered when a preview is generated 0246 * The result is internally cached, meaning any further method call will not reload the plugins 0247 * @since 5.90 0248 */ 0249 static QVector<KPluginMetaData> availableThumbnailerPlugins(); 0250 0251 /** 0252 * Returns a list of plugins that should be enabled by default, which is all plugins 0253 * Minus the plugins specified in an internal blacklist 0254 * @return the list of plugins that should be enabled by default 0255 * @since 5.40 0256 */ 0257 static QStringList defaultPlugins(); 0258 0259 /** 0260 * Returns a list of all supported MIME types. The list can 0261 * contain entries like text/ * (without the space). 0262 * @return the list of MIME types 0263 */ 0264 static QStringList supportedMimeTypes(); 0265 0266 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(4, 5) 0267 /** 0268 * Returns the default "maximum file size", in bytes, used by PreviewJob. 0269 * This is useful for applications providing a GUI for letting the user change the size. 0270 * @since 4.1 0271 * @deprecated Since 4.5, PreviewJob uses different maximum file sizes dependent on the URL. 0272 * The returned file size is only valid for local URLs. 0273 */ 0274 KIOWIDGETS_DEPRECATED_VERSION(4, 5, "See API dox") 0275 static KIO::filesize_t maximumFileSize(); 0276 #endif 0277 0278 Q_SIGNALS: 0279 /** 0280 * Emitted when a thumbnail picture for @p item has been successfully 0281 * retrieved. 0282 * @param item the file of the preview 0283 * @param preview the preview image 0284 */ 0285 void gotPreview(const KFileItem &item, const QPixmap &preview); 0286 /** 0287 * Emitted when a thumbnail for @p item could not be created, 0288 * either because a ThumbCreator for its MIME type does not 0289 * exist, or because something went wrong. 0290 * @param item the file that failed 0291 */ 0292 void failed(const KFileItem &item); 0293 0294 protected Q_SLOTS: 0295 void slotResult(KJob *job) override; 0296 0297 private: 0298 Q_DECLARE_PRIVATE(PreviewJob) 0299 0300 public: 0301 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 86) 0302 /** 0303 * Sets a default device Pixel Ratio used for Previews 0304 * @see setDevicePixelRatio 0305 * 0306 * Defaults to 1 0307 * 0308 * @since 5.80 0309 * @deprecated Since 5.86, use setDefaultDevicePixelRatio(qreal dpr) instead 0310 */ 0311 KIOWIDGETS_DEPRECATED_VERSION(5, 86, "Use setDefaultDevicePixelRatio(qreal dpr)") 0312 static void setDefaultDevicePixelRatio(int devicePixelRatio); 0313 #endif 0314 0315 /** 0316 * Sets a default device Pixel Ratio used for Previews 0317 * @see setDevicePixelRatio 0318 * 0319 * Defaults to 1 0320 * 0321 * @since 5.84 0322 */ 0323 static void setDefaultDevicePixelRatio(qreal devicePixelRatio); 0324 }; 0325 0326 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(4, 7) 0327 /** 0328 * Creates a PreviewJob to generate or retrieve a preview image 0329 * for the given URL. 0330 * 0331 * @param items files to get previews for 0332 * @param width the maximum width to use 0333 * @param height the maximum height to use, if this is 0, the same 0334 * value as width is used. 0335 * @param iconSize the size of the MIME type icon to overlay over the 0336 * preview or zero to not overlay an icon. This has no effect if the 0337 * preview plugin that will be used doesn't use icon overlays. 0338 * @param iconAlpha transparency to use for the icon overlay 0339 * @param scale if the image is to be scaled to the requested size or 0340 * returned in its original size 0341 * @param save if the image should be cached for later use 0342 * @param enabledPlugins if non-zero, this points to a list containing 0343 * the names of the plugins that may be used. 0344 * @return the new PreviewJob 0345 * @see PreviewJob::availablePlugins() 0346 * @deprecated Since 4.7, use KIO::filePreview(const KFileItemList&, const QSize&, const QStringList*) in combination 0347 * with the setter-methods instead. Note that the semantics of 0348 * \p enabledPlugins has been slightly changed. 0349 */ 0350 KIOWIDGETS_EXPORT 0351 KIOWIDGETS_DEPRECATED_VERSION(4, 7, "Use KIO::filePreview(const KFileItemList &, const QSize &, const QStringList *") 0352 PreviewJob *filePreview(const KFileItemList &items, 0353 int width, 0354 int height = 0, 0355 int iconSize = 0, 0356 int iconAlpha = 70, 0357 bool scale = true, 0358 bool save = true, 0359 const QStringList *enabledPlugins = nullptr); // KDE5: use enums instead of bool scale + bool save 0360 #endif 0361 0362 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(4, 7) 0363 /** 0364 * Creates a PreviewJob to generate or retrieve a preview image 0365 * for the given URL. 0366 * 0367 * @param items files to get previews for 0368 * @param width the maximum width to use 0369 * @param height the maximum height to use, if this is 0, the same 0370 * value as width is used. 0371 * @param iconSize the size of the MIME type icon to overlay over the 0372 * preview or zero to not overlay an icon. This has no effect if the 0373 * preview plugin that will be used doesn't use icon overlays. 0374 * @param iconAlpha transparency to use for the icon overlay 0375 * @param scale if the image is to be scaled to the requested size or 0376 * returned in its original size 0377 * @param save if the image should be cached for later use 0378 * @param enabledPlugins if non-zero, this points to a list containing 0379 * the names of the plugins that may be used. 0380 * @return the new PreviewJob 0381 * @see PreviewJob::availablePlugins() 0382 * @deprecated Since 4.7, use KIO::filePreview(const KFileItemList&, const QSize&, const QStringList*) in combination 0383 * with the setter-methods instead. Note that the semantics of 0384 * \p enabledPlugins has been slightly changed. 0385 */ 0386 KIOWIDGETS_EXPORT 0387 KIOWIDGETS_DEPRECATED_VERSION(4, 7, "Use KIO::filePreview(const KFileItemList &, const QSize &, const QStringList *") 0388 PreviewJob *filePreview(const QList<QUrl> &items, 0389 int width, 0390 int height = 0, 0391 int iconSize = 0, 0392 int iconAlpha = 70, 0393 bool scale = true, 0394 bool save = true, 0395 const QStringList *enabledPlugins = nullptr); 0396 #endif 0397 0398 /** 0399 * Creates a PreviewJob to generate a preview image for the given items. 0400 * @param items List of files to create previews for. 0401 * @param size Desired size of the preview. 0402 * @param enabledPlugins If non-zero it defines the list of plugins that 0403 * are considered for generating the preview. If 0404 * enabledPlugins is zero the plugins specified in the 0405 * KConfigGroup "PreviewSettings" are used. 0406 * @since 4.7 0407 */ 0408 KIOWIDGETS_EXPORT PreviewJob *filePreview(const KFileItemList &items, const QSize &size, const QStringList *enabledPlugins = nullptr); 0409 } 0410 0411 #endif