src/backgroundmanager.h

   1 /***************************************************************************
   2  *   Copyright (C) 2003 by S�astien Laot                                 *
   3  *   slaout@linux62.org                                                    *
   4  *                                                                         *
   5  *   This program is free software; you can redistribute it and/or modify  *
   6  *   it under the terms of the GNU General Public License as published by  *
   7  *   the Free Software Foundation; either version 2 of the License, or     *
   8  *   (at your option) any later version.                                   *
   9  *                                                                         *
  10  *   This program is distributed in the hope that it will be useful,       *
  11  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  12  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  13  *   GNU General Public License for more details.                          *
  14  *                                                                         *
  15  *   You should have received a copy of the GNU General Public License     *
  16  *   along with this program; if not, write to the                         *
  17  *   Free Software Foundation, Inc.,                                       *
  18  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  19  ***************************************************************************/
  20
  21 #ifndef BACKGROUNDMANAGER_H
  22 #define BACKGROUNDMANAGER_H
  23
  24 #include <qobject.h>
  25 #include <q3valuelist.h>
  26 #include <qstring.h>
  27 #include <qpixmap.h>
  28 #include <qcolor.h>
  29 #include <qtimer.h>
  30
  31 /** A node in the list of background images of BackgroundManager.
  32   * It can only be used by BackgroundManager because it is an internal structure of this manager.
  33   * @author S�astien Laot
  34   */
  35 class BackgroundEntry
  36 {
  37         friend class BackgroundManager;
  38
  39   protected:
  40         BackgroundEntry(const QString &location);
  41         ~BackgroundEntry();
  42
  43         QString  name;
  44         QString  location;
  45         bool     tiled;    /// << Only valid after some object subscribed to this image! Because it's only read at this time.
  46         QPixmap *pixmap;   /// << Only valid (non-null) after some object subscribed to this image! Because it's only read at this time.
  47         QPixmap *preview;  /// << Only valid (non-null) after some object requested the preview.
  48         int      customersCount;
  49 };
  50
  51 /** A node in the list of opaque background images (with a background color applyed to an image) of BackgroundManager.
  52   * It can only be used by BackgroundManager because it is an internal structure of this manager.
  53   * @author S�astien Laot
  54   */
  55 class OpaqueBackgroundEntry
  56 {
  57         friend class BackgroundManager;
  58
  59   protected:
  60         OpaqueBackgroundEntry(const QString &name, const QColor &color);
  61         ~OpaqueBackgroundEntry();
  62
  63         QString  name;
  64         QColor   color;
  65         QPixmap *pixmap;
  66         int      customersCount;
  67 };
  68
  69 /** Manage the list of background images.
  70   * BASIC FUNCTIONNING OF A BACKGROUND CHOOSER:
  71   *   It get all image names with imageNames() to put them in eg. a QComboBox and then,
  72   *   when it's time to get the preview of an image it call preview() with the image name to get it.
  73   *   Preview are only computed on demand and then cached to fast the next demands (only the pointer will have to be returned).
  74   *   Previews are scalled to fit in a rectangle of 100 by 75 pixels, and with a white background color.
  75   *   They are also saved to files, so that the scalling/opaquification has not to be done later (they will be directly loaded from file).
  76   *   Previews are saved in Global::backgroundsFolder()+"previews/", so that emptying the folder is sufficient to remove them.
  77   * BASIC FUNCTIONNING OF AN IMAGE REQUESTER:
  78   *   When eg. a basket is assigned an image name, it register it with subscribe().
  79   *   The full pixmap is then loaded from file and cached (if it was not already loaded) and the "tiled" property is read from the image configuration file.
  80   *   If this object want to have the pixmap applyed on a background color (for no transparency => really faster drawing),
  81   *   it should register for the couple (imageName,color) with suscribe(): the pixmap will be created in the cache.
  82   *   Then, the object can get the subscribed images with pixmap() or opaquePixmap() and know if it's tiled with tiled().
  83   *   When the user removed the object background image (or when the object/basket/... is removed), the object should call unsubscribe() for
  84   *   EVERY subscribed image and image couples. Usage count is decreased for those images and a garbage collector will remove the cached images
  85   *   if nothing is subscribed to them (to free memory).
  86   * @author S�astien Laot
  87   */
  88 class BackgroundManager : private QObject
  89 {
  90   Q_OBJECT
  91   private:
  92         /// LIST OF IMAGES:
  93         typedef Q3ValueList<BackgroundEntry*>       BackgroundsList;
  94         typedef Q3ValueList<OpaqueBackgroundEntry*> OpaqueBackgroundsList;
  95
  96   public:
  97         /// CONTRUCTOR AND DESTRUCTOR:
  98         BackgroundManager();
  99         ~BackgroundManager();
 100         /// SUBSCRIPTION TO IMAGES:
 101         bool subscribe(const QString &image); /// << @Return true if the loading is a success. In the counter-case, calling methods below is unsafe with this @p image name.
 102         bool subscribe(const QString &image, const QColor &color); /// << Idem.
 103         void unsubscribe(const QString &image);
 104         void unsubscribe(const QString &image, const QColor &color);
 105         /// GETTING THE IMAGES AND PROPERTIES:
 106         QPixmap* pixmap(const QString &image);
 107         QPixmap* opaquePixmap(const QString &image, const QColor &color);
 108         bool tiled(const QString &image);
 109         /// LIST OF IMAGES AND PREVIEWS:
 110         bool exists(const QString &image);
 111         QStringList imageNames();
 112         QPixmap* preview(const QString &image);
 113         /// USED FOR EXPORTATION:
 114         QString pathForImageName(const QString &image); /// << It is STRONGLY advised to not use those two methods unless it's to copy (export) the images or something like that...
 115         QString previewPathForImageName(const QString &image);
 116         /// USED FOR IMPORTATION:
 117         void addImage(const QString &fullPath);
 118
 119   private:
 120         BackgroundEntry*       backgroundEntryFor(const QString &image);
 121         OpaqueBackgroundEntry* opaqueBackgroundEntryFor(const QString &image, const QColor &color);
 122
 123   private:
 124         BackgroundsList       m_backgroundsList;
 125         OpaqueBackgroundsList m_opaqueBackgroundsList;
 126         QTimer                m_garbageTimer;
 127   private slots:
 128         void requestDelayedGarbage();
 129         void doGarbage();
 130 };
 131
 132 #endif // BACKGROUNDMANAGER_H