kio/kio/previewjob.h

   1 // -*- c++ -*-
   2 // vim: ts=4 sw=4 et
   3 /*  This file is part of the KDE libraries
   4     Copyright (C) 2000 David Faure <faure@kde.org>
   5                   2000 Carsten Pfeiffer <pfeiffer@kde.org>
   6                   2001 Malte Starostik <malte.starostik@t-online.de>
   7
   8     This library is free software; you can redistribute it and/or
   9     modify it under the terms of the GNU Library General Public
  10     License as published by the Free Software Foundation; either
  11     version 2 of the License, or (at your option) any later version.
  12
  13     This library is distributed in the hope that it will be useful,
  14     but WITHOUT ANY WARRANTY; without even the implied warranty of
  15     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16     Library General Public License for more details.
  17
  18     You should have received a copy of the GNU Library General Public License
  19     along with this library; see the file COPYING.LIB.  If not, write to
  20     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  21     Boston, MA 02110-1301, USA.
  22 */
  23
  24 #ifndef KIO_PREVIEWJOB_H
  25 #define KIO_PREVIEWJOB_H
  26
  27 #include <kfileitem.h>
  28 #include <kio/job.h>
  29
  30 class QPixmap;
  31
  32 namespace KIO {
  33     class PreviewJobPrivate;
  34     /*!
  35      * This class catches a preview (thumbnail) for files.
  36      * @short KIO Job to get a thumbnail picture
  37      */
  38     class KIO_EXPORT PreviewJob : public KIO::Job
  39     {
  40         Q_OBJECT
  41     public:
  42         /**
  43          * Creates a new PreviewJob.
  44          * @param items a list of files to create previews for
  45          * @param width the desired width
  46          * @param height the desired height, 0 to use the @p width
  47          * @param iconSize the size of the mimetype icon to overlay over the
  48          * preview or zero to not overlay an icon. This has no effect if the
  49          * preview plugin that will be used doesn't use icon overlays.
  50          * @param iconAlpha transparency to use for the icon overlay
  51          * @param scale if the image is to be scaled to the requested size or
  52          * returned in its original size
  53          * @param save if the image should be cached for later use
  54          * @param enabledPlugins if non-zero, this points to a list containing
  55          * the names of the plugins that may be used.
  56          */
  57         PreviewJob( const KFileItemList& items, int width, int height,
  58             int iconSize, int iconAlpha, bool scale, bool save,
  59             const QStringList *enabledPlugins );
  60         virtual ~PreviewJob();
  61
  62         /**
  63          * Removes an item from preview processing. Use this if you passed
  64          * an item to filePreview and want to delete it now.
  65          *
  66          * @param url the url of the item that should be removed from the preview queue
  67          */
  68         void removeItem( const KUrl& url );
  69
  70         /**
  71          * If @p ignoreSize is true, then the preview is always
  72          * generated regardless of the settings
  73          **/
  74         void setIgnoreMaximumSize(bool ignoreSize = true);
  75
  76         /**
  77          * Returns a list of all available preview plugins. The list
  78          * contains the basenames of the plugins' .desktop files (no path,
  79          * no .desktop).
  80          * @return the list of plugins
  81          */
  82         static QStringList availablePlugins();
  83
  84         /**
  85          * Returns a list of all supported MIME types. The list can
  86          * contain entries like text/ * (without the space).
  87          * @return the list of mime types
  88          */
  89         static QStringList supportedMimeTypes();
  90
  91         /**
  92          * Returns the default "maximum file size", in bytes, used by PreviewJob.
  93          * This is useful for applications providing a GUI for letting the user change the size.
  94          * @since 4.1
  95          */
  96         static KIO::filesize_t maximumFileSize();
  97
  98
  99     Q_SIGNALS:
 100         /**
 101          * Emitted when a thumbnail picture for @p item has been successfully
 102          * retrieved.
 103          * @param item the file of the preview
 104          * @param preview the preview image
 105          */
 106         void gotPreview( const KFileItem& item, const QPixmap &preview );
 107         /**
 108          * Emitted when a thumbnail for @p item could not be created,
 109          * either because a ThumbCreator for its MIME type does not
 110          * exist, or because something went wrong.
 111          * @param item the file that failed
 112          */
 113         void failed( const KFileItem& item );
 114
 115     protected Q_SLOTS:
 116         virtual void slotResult( KJob *job );
 117
 118     private:
 119         Q_PRIVATE_SLOT(d_func(), void startPreview())
 120         Q_PRIVATE_SLOT(d_func(), void slotThumbData(KIO::Job *, const QByteArray &))
 121         Q_DECLARE_PRIVATE(PreviewJob)
 122     };
 123
 124     /**
 125      * Creates a PreviewJob to generate or retrieve a preview image
 126      * for the given URL.
 127      *
 128      * @param items files to get previews for
 129      * @param width the maximum width to use
 130      * @param height the maximum height to use, if this is 0, the same
 131      * value as width is used.
 132      * @param iconSize the size of the mimetype icon to overlay over the
 133      * preview or zero to not overlay an icon. This has no effect if the
 134      * preview plugin that will be used doesn't use icon overlays.
 135      * @param iconAlpha transparency to use for the icon overlay
 136      * @param scale if the image is to be scaled to the requested size or
 137      * returned in its original size
 138      * @param save if the image should be cached for later use
 139      * @param enabledPlugins if non-zero, this points to a list containing
 140      * the names of the plugins that may be used.
 141      * @return the new PreviewJob
 142      * @see PreviewJob::availablePlugins()
 143      */
 144     KIO_EXPORT PreviewJob *filePreview( const KFileItemList &items, int width, int height = 0, int iconSize = 0, int iconAlpha = 70, bool scale = true, bool save = true, const QStringList *enabledPlugins = 0 );
 145
 146     /**
 147      * Creates a PreviewJob to generate or retrieve a preview image
 148      * for the given URL.
 149      *
 150      * @param items files to get previews for
 151      * @param width the maximum width to use
 152      * @param height the maximum height to use, if this is 0, the same
 153      * value as width is used.
 154      * @param iconSize the size of the mimetype icon to overlay over the
 155      * preview or zero to not overlay an icon. This has no effect if the
 156      * preview plugin that will be used doesn't use icon overlays.
 157      * @param iconAlpha transparency to use for the icon overlay
 158      * @param scale if the image is to be scaled to the requested size or
 159      * returned in its original size
 160      * @param save if the image should be cached for later use
 161      * @param enabledPlugins if non-zero, this points to a list containing
 162      * the names of the plugins that may be used.
 163      * @return the new PreviewJob
 164      * @see PreviewJob::availablePlugins()
 165      */
 166     KIO_EXPORT PreviewJob *filePreview( const KUrl::List &items, int width, int height = 0, int iconSize = 0, int iconAlpha = 70, bool scale = true, bool save = true, const QStringList *enabledPlugins = 0 );
 167 }
 168
 169 #endif