File indexing completed on 2024-06-16 10:06:23

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