src/graphics/GraphicsCacheItem.h

   1 // -*- C++ -*-
   2 /*
   3  * \file GraphicsCacheItem.h
   4  * Copyright 2002 the LyX Team
   5  * Read the file COPYING
   6  *
   7  * \author Baruch Even <baruch.even@writeme.com>
   8  * \author Angus Leeming <a.leeming@ic.ac.uk>
   9  *
  10  * The graphics cache is a container of GCacheItems. Each GCacheItem, defined
  11  * here represents a separate image file. However, each file can be viewed in
  12  * different ways (different sizes, rotations etc), so each GCacheItem itself
  13  * contains a list of ModifiedItems, also defined here. Each ModifiedItem
  14  * has a GParams variable that defines the way it will be viewed. It also
  15  * contains a list of the graphics insets that refer to it, so calls through
  16  * the GCache to GCacheItem ultimately return the loading status and image
  17  * for that particular graphics inset.
  18  *
  19  * The graphics cache supports fully asynchronous:
  20  * file conversion to a loadable format;
  21  * file loading.
  22  *
  23  * Whether you get that, of course, depends on grfx::GConverter and on the
  24  * grfx::GImage-derived image class.
  25  *
  26  * Image modification (scaling, rotation etc) is blocking.
  27  */
  28
  29 #ifndef GRAPHICSCACHEITEM_H
  30 #define GRAPHICSCACHEITEM_H
  31
  32 #ifdef __GNUG__
  33 #pragma interface
  34 #endif
  35
  36 #include "GraphicsTypes.h"
  37 #include <list>
  38 #include "LString.h"
  39 #include <boost/utility.hpp>
  40 #include <boost/smart_ptr.hpp>
  41 #include <sigc++/signal_system.h>
  42
  43 class InsetGraphics;
  44
  45 namespace grfx {
  46
  47 class GParams;
  48 class ModifiedItem;
  49
  50 /// A grfx::GCache item holder.
  51 class GCacheItem : boost::noncopyable, public SigC::Object {
  52 public:
  53         /// the GCacheItem contains data of this type.
  54         typedef boost::shared_ptr<ModifiedItem> ModifiedItemPtr;
  55
  56         ///
  57         GCacheItem(InsetGraphics const &, GParams const &);
  58
  59         /// The params have changed (but still refer to this file).
  60         void modify(InsetGraphics const &, GParams const &);
  61
  62         /// Remove the reference to this inset.
  63         void remove(InsetGraphics const &);
  64
  65         /// It's in the cache. Now start the loading process.
  66         void startLoading(InsetGraphics const &);
  67
  68         /// Is the cache item referenced by any insets at all?
  69         bool empty() const;
  70
  71         /// The name of the original image file.
  72         string const & filename() const;
  73
  74         /// Is this image file referenced by this inset?
  75         bool referencedBy(InsetGraphics const &) const;
  76
  77         /** Returns the image referenced by this inset (or an empty container
  78          *  if it's not yet loaded.
  79          */
  80         ImagePtr const image(InsetGraphics const &) const;
  81
  82         /// The loading status of the image referenced by this inset.
  83         ImageStatus status(InsetGraphics const &) const;
  84
  85         /** If (changed_background == true), then the background color of the
  86          *  graphics inset has changed. Update all images.
  87          *  Else, the preferred display type has changed.
  88          *  Update the view of all insets whose display type is DEFAULT.
  89          */
  90         void changeDisplay(bool changed_background);
  91
  92 private:
  93         /** Start the image conversion process, checking first that it is
  94          *  necessary. If it is necessary, then a conversion task is started.
  95          *  GCacheItem asumes that the conversion is asynchronous and so
  96          *  passes a Signal to the converting routine. When the conversion
  97          *  is finished, this Signal is emitted, returning the converted
  98          *  file to this->imageConverted.
  99          *
 100          *  If no file conversion is needed, then convertToDisplayFormat() calls
 101          *  loadImage() directly.
 102          *
 103          *  convertToDisplayFormat() will set the loading status flag as
 104          *  approriate through calls to setStatus().
 105          */
 106         void convertToDisplayFormat();
 107
 108         /** Load the image into memory. This is called either from
 109          *  convertToDisplayFormat() direct or from imageConverted().
 110          */
 111         void loadImage();
 112
 113         /** Get a notification when the image conversion is done.
 114          *  Connected to a signal on_finish_ which is passed to
 115          *  GConverter::convert.
 116          */
 117         void imageConverted(string const & file_to_load);
 118
 119         /** Get a notification when the image loading is done.
 120          *  Connected to a signal on_finish_ which is passed to
 121          *  GImage::loadImage.
 122          */
 123         void imageLoaded(bool);
 124
 125         /// How far have we got in loading the original, unmodified image?
 126         ImageStatus status() const;
 127
 128         /** Sets the status of the loading process. Also notifies
 129          *  listeners that the status has chacnged.
 130          */
 131         void setStatus(ImageStatus new_status);
 132
 133         /// The filename we refer too.
 134         string filename_;
 135         /// Is the file compressed?
 136         bool zipped_;
 137         /// If so, store the uncompressed file in this temporary file.
 138         string unzipped_filename_;
 139         /// What file are we trying to load?
 140         string file_to_load_;
 141         /** Should we delete the file after loading? True if the file is
 142          *  the result of a conversion process.
 143          */
 144         bool remove_loaded_file_;
 145
 146         /// The original, unmodified image and its loading status.
 147         ImagePtr image_;
 148         ///
 149         ImageStatus status_;
 150
 151         /** A SignalLoadTypePtr is connected to this->imageLoaded and
 152          *  then passed to ImagePtr::load.
 153          *  When the image has been loaded, the signal is emitted.
 154          *
 155          *  We pass a shared_ptr because it is eminently possible for the
 156          *  ModifiedItem to be destructed before the loading is complete and
 157          *  the signal must remain in scope. It doesn't matter if the slot
 158          *  disappears, SigC takes care of that.
 159          */
 160         typedef SigC::Signal1<void, bool> SignalLoadType;
 161         ///
 162         typedef boost::shared_ptr<SignalLoadType> SignalLoadTypePtr;
 163
 164         /// The connection of the signal passed to ImagePtr::loadImage.
 165         SigC::Connection cl_;
 166
 167         /** A SignalConvertTypePtr is connected to this->imageConverted and
 168          *  then passed to GConverter::convert.
 169          *  When the image has been converted to a loadable format, the signal
 170          *  is emitted, returning the name of the loadable file to
 171          *  imageConverted.
 172          */
 173         typedef SigC::Signal1<void, string const &> SignalConvertType;
 174         ///
 175         typedef boost::shared_ptr<SignalConvertType> SignalConvertTypePtr;
 176
 177         /// The connection of the signal passed to GConverter::convert.
 178         SigC::Connection cc_;
 179
 180         /// The list of all modified images.
 181         typedef std::list<ModifiedItemPtr> ListType;
 182         ///
 183         ListType modified_images;
 184 };
 185
 186
 187 ///
 188 class ModifiedItem {
 189 public:
 190         ///
 191         ModifiedItem(InsetGraphics const &, GParams const &, ImagePtr const &);
 192
 193         ///
 194         GParams const & params() { return *p_.get(); }
 195
 196         /// Add inset to the list of insets.
 197         void add(InsetGraphics const & inset);
 198
 199         /// Remove inset from the list of insets.
 200         void remove(InsetGraphics const & inset);
 201
 202         ///
 203         bool empty() const { return insets.empty(); }
 204
 205         /// Is this ModifiedItem referenced by inset?
 206         bool referencedBy(InsetGraphics const & inset) const;
 207
 208         ///
 209         ImagePtr const image() const;
 210
 211         /// How far have we got in loading the modified image?
 212         ImageStatus status() const { return status_; }
 213
 214         /** Called from GCacheItem once the raw image is loaded.
 215          *  Modifies the image in accord with p_.
 216          */
 217         void modify(ImagePtr const &);
 218
 219         /// Updates the pixmap.
 220         void setPixmap();
 221
 222         /** changeDisplay returns a full ModifiedItemPtr if any of the
 223          *  insets have display=DEFAULT and if that DEFAULT value has
 224          *  changed.
 225          *  If this occurs, then this has these insets removed.
 226          */
 227         boost::shared_ptr<ModifiedItem> changeDisplay();
 228
 229         ///
 230         typedef std::list<InsetGraphics const *> ListType;
 231
 232         /// Make these accessible for changeDisplay.
 233         ListType insets;
 234
 235 private:
 236         /** Sets the status of the loading process. Also notifies
 237          *  listeners that the status has changed.
 238          */
 239         void setStatus(ImageStatus new_status);
 240
 241         /// The original and modified images and its loading status.
 242         ImagePtr original_image_;
 243         ///
 244         ImagePtr modified_image_;
 245         ///
 246         ImageStatus status_;
 247         ///
 248         boost::shared_ptr<GParams> p_;
 249 };
 250
 251 } // namespace grfx
 252
 253 #endif // GRAPHICSCACHEITEM_H