File indexing completed on 2024-05-12 11:54:54

0001 /*
0002     This file is part of the KDE libraries
0003     SPDX-FileCopyrightText: 2000 Malte Starostik <malte@kde.org>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-or-later
0006 */
0007 
0008 #ifndef _THUMBCREATOR_H_
0009 #define _THUMBCREATOR_H_
0010 
0011 #include "kiowidgets_export.h"
0012 
0013 class QString;
0014 class QImage;
0015 class QWidget;
0016 
0017 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 101)
0018 /**
0019  * @class ThumbCreator thumbcreator.h <KIO/ThumbCreator>
0020  *
0021  * Base class for thumbnail generator plugins.
0022  *
0023  * KIO::PreviewJob, via the "thumbnail" KIO worker, uses instances of this class
0024  * to generate the thumbnail previews.
0025  *
0026  * To add support for a new document type, subclass ThumbCreator and implement
0027  * create() to generate a thumbnail for a given path.  Then create a factory
0028  * method called "new_creator" to return instances of your subclass:
0029  * \code
0030  * extern "C"
0031  * {
0032  *   Q_DECL_EXPORT ThumbCreator *new_creator()
0033  *   {
0034  *     return new FooThumbCreator();
0035  *   }
0036  * };
0037  * \endcode
0038  *
0039  * Compile your ThumbCreator as a module; for example, the relevant CMake code
0040  * for a thumbnailer for the "foo" filetype might look like
0041  * \code
0042  * add_library(foothumbnail MODULE foothumbnail.cpp)
0043  * target_link_libraries(foothumbnail PRIVATE KF5::KIOWidgets)
0044  *
0045  * install(TARGETS foothumbnail DESTINATION ${KDE_INSTALL_PLUGINDIR})
0046  * \endcode
0047  *
0048  * You also need to create a desktop file describing the thumbnailer.  For
0049  * example:
0050  * \code
0051  * [Desktop Entry]
0052  * Type=Service
0053  * Name=Foo Documents
0054  * X-KDE-ServiceTypes=ThumbCreator
0055  * MimeType=application/x-foo;
0056  * CacheThumbnail=true
0057  * X-KDE-Library=foothumbcreator
0058  * \endcode
0059  *
0060  * Of course, you will need to install it:
0061  * \code
0062  * install(FILES foothumbcreator.desktop DESTINATION ${KDE_INSTALL_KSERVICESDIR})
0063  * \endcode
0064  *
0065  * Note that you can supply a comma-separated list of MIME types to the MimeTypes
0066  * entry, naming all MIME types your ThumbCreator supports. You can also use
0067  * simple wildcards, like
0068  * \htmlonly "text/&#42;".\endhtmlonly\latexonly text/$\ast$.\endlatexonly
0069  *
0070  * If the thumbnail creation is cheap (such as text previews), you can set
0071  * \code
0072  * CacheThumbnail=false
0073  * \endcode
0074  * in the desktop file to prevent your thumbnails from being cached on disk.
0075  *
0076  * You can also use the "ThumbnailerVersion" optional property in the .desktop
0077  * file, like
0078  * \code
0079  * ThumbnailerVersion=5
0080  * \endcode
0081  * When this is incremented (or defined when it previously was not), all the
0082  * previously-cached thumbnails for this creator will be discarded.  You should
0083  * increase the version if and only if old thumbnails need to be regenerated.
0084  *
0085  * @deprecated since 5.101, use KIO::ThumbnailCreator instead
0086  */
0087 class KIOWIDGETS_EXPORT ThumbCreator
0088 {
0089 public:
0090     /**
0091      * Flags to provide hints to the user of this plugin.
0092      * @see flags()
0093      */
0094     enum Flags {
0095         None = 0, /**< No hints. */
0096 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 32)
0097         DrawFrame KIOWIDGETS_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 32, "See API dox") =
0098             1, /**< \deprecated since 5.32. Used to paint a frame around the preview, but applications take care of that nowadays. */
0099 #endif
0100         BlendIcon = 2, /**< The MIME type icon should be blended over the preview. */
0101     };
0102 
0103     /**
0104      * Destructor.
0105      */
0106     virtual ~ThumbCreator();
0107 
0108     /**
0109      * Creates a thumbnail.
0110      *
0111      * Note that this method should not do any scaling.  The @p width and @p
0112      * height parameters are provided as hints for images that are generated
0113      * from non-image data (like text).
0114      *
0115      * @param path    The path of the file to create a preview for.  This is
0116      *                always a local path.
0117      * @param width   The requested preview width (see the note on scaling
0118      *                above).
0119      * @param height  The requested preview height (see the note on scaling
0120      *                above).
0121      * @param img     The QImage to store the preview in.
0122      *
0123      * @return @c true if a preview was successfully generated and store in @p
0124      *         img, @c false otherwise.
0125      * @deprecated since 5.101, use KIO::ThumbnailCreator instead.
0126      */
0127     KIOWIDGETS_DEPRECATED_VERSION(5, 101, "Use KIO::ThumbnailCreator instead")
0128     virtual bool create(const QString &path, int width, int height, QImage &img) = 0; // KF6 TODO: turn first arg into QUrl (see thumbnail/htmlcreator.cpp)
0129 
0130     /**
0131      * Returns the flags for this plugin.
0132      *
0133      * @return XOR'd flags values.
0134      * @see Flags
0135      */
0136     virtual Flags flags() const;
0137 
0138 #if KIOWIDGETS_BUILD_DEPRECATED_SINCE(5, 87)
0139     /**
0140      * Create a widget for configuring the thumb creator.
0141      *
0142      * The caller will take ownership of the returned instance and must ensure
0143      * its deletion.
0144      *
0145      * The default implementation returns @c nullptr.
0146      *
0147      * The following key in the thumbcreator .desktop file must be set to
0148      * mark the plugin as configurable:
0149      * \code
0150      * Configurable=true
0151      * \endcode
0152      *
0153      * @return A QWidget instance, which the caller takes ownership of, or @c nullptr.
0154      * @deprecated Since 5.87, deprecated for lack of usage and only being used for niche usecases.
0155      * Instead use sane defaults and keep reading the config if it exists.
0156      */
0157     KIOWIDGETS_DEPRECATED_VERSION(5, 87, "See API docs")
0158     virtual QWidget *createConfigurationWidget();
0159 #endif
0160 
0161 #if KIOWIDGETS_BUILD_DEPRECATED_SINCE(5, 87)
0162     /**
0163      * Write the updated configuration.
0164      *
0165      * @param configurationWidget  An object returned by
0166      *                             createConfigurationWidget().
0167      * @deprecated Since 5.87, see API docs of @p createConfigurationWidget
0168      */
0169     KIOWIDGETS_DEPRECATED_VERSION(5, 87, "See API docs of createConfigurationWidget")
0170     virtual void writeConfiguration(const QWidget *configurationWidget);
0171 #endif
0172 };
0173 
0174 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 0)
0175 /**
0176  * @class ThumbCreatorV2 thumbcreator.h <KIO/ThumbCreator>
0177  * @since 4.7
0178  * @deprecated since 5.0, use ThumbCreator
0179  */
0180 class KIOWIDGETS_EXPORT KIOWIDGETS_DEPRECATED_VERSION(5, 0, "Use ThumbCreator") ThumbCreatorV2 : public ThumbCreator
0181 {
0182 public:
0183     ~ThumbCreatorV2() override;
0184 };
0185 #endif
0186 
0187 // KF6 TODO: rename this to something less generic
0188 typedef ThumbCreator *(*newCreator)();
0189 
0190 #endif
0191 
0192 #endif