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. The routines here can be used to
  12  * load the graphics file into memory at which point (status() == grfx::Loaded).
  13  * The user is then free to access image() in order to transform the image
  14  * (rotate, scale, clip) and to generate the pixmap.
  15  *
  16  * The graphics cache supports fully asynchronous:
  17  * file conversion to a loadable format;
  18  * file loading.
  19  *
  20  * Whether you get that, of course, depends on grfx::GConverter and on the
  21  * grfx::GImage-derived image class.
  22  */
  23
  24 #ifndef GRAPHICSCACHEITEM_H
  25 #define GRAPHICSCACHEITEM_H
  26
  27 #ifdef __GNUG__
  28 #pragma interface
  29 #endif
  30
  31 #include "GraphicsTypes.h"
  32 #include "LString.h"
  33
  34 #include <boost/utility.hpp>
  35 #include <boost/shared_ptr.hpp>
  36
  37 #include <boost/signals/signal0.hpp>
  38 #include <boost/signals/signal1.hpp>
  39 #include <boost/signals/connection.hpp>
  40 #include <boost/signals/trackable.hpp>
  41
  42 class InsetGraphics;
  43
  44 namespace grfx {
  45
  46 /// A grfx::GCache item holder.
  47 class GCacheItem : boost::noncopyable, public boost::signals::trackable {
  48 public:
  49         ///
  50         GCacheItem(string const & file);
  51
  52         /// It's in the cache. Now start the loading process.
  53         void startLoading();
  54
  55         /** Get the image associated with filename_.
  56             If the image is not yet loaded, return a null pointer.
  57          */
  58         ImagePtr const image() const { return image_; }
  59
  60         /// How far have we got in loading the image?
  61         ImageStatus status() const { return status_; }
  62
  63         /// This signal is emitted when the image loading status changes.
  64         boost::signal0<void> statusChanged;
  65
  66         ///
  67         string const & filename() const { return filename_; }
  68
  69 private:
  70         /** Start the image conversion process, checking first that it is
  71          *  necessary. If it is necessary, then a conversion task is started.
  72          *  GCacheItem asumes that the conversion is asynchronous and so
  73          *  passes a Signal to the converting routine. When the conversion
  74          *  is finished, this Signal is emitted, returning the converted
  75          *  file to this->imageConverted.
  76          *
  77          *  If no file conversion is needed, then convertToDisplayFormat() calls
  78          *  loadImage() directly.
  79          *
  80          *  convertToDisplayFormat() will set the loading status flag as
  81          *  approriate through calls to setStatus().
  82          */
  83         void convertToDisplayFormat();
  84
  85         /** Load the image into memory. This is called either from
  86          *  convertToDisplayFormat() direct or from imageConverted().
  87          */
  88         void loadImage();
  89
  90         /** Get a notification when the image conversion is done.
  91          *  Connected to a signal on_finish_ which is passed to
  92          *  GConverter::convert.
  93          */
  94         void imageConverted(string const & file_to_load);
  95
  96         /** Get a notification when the image loading is done.
  97          *  Connected to a signal on_finish_ which is passed to
  98          *  GImage::loadImage.
  99          */
 100         void imageLoaded(bool);
 101
 102         /** Sets the status of the loading process. Also notifies
 103          *  listeners that the status has chacnged.
 104          */
 105         void setStatus(ImageStatus new_status);
 106
 107         /// The filename we refer too.
 108         string filename_;
 109         /// Is the file compressed?
 110         bool zipped_;
 111         /// If so, store the uncompressed file in this temporary file.
 112         string unzipped_filename_;
 113         /// What file are we trying to load?
 114         string file_to_load_;
 115         /** Should we delete the file after loading? True if the file is
 116          *  the result of a conversion process.
 117          */
 118         bool remove_loaded_file_;
 119
 120         /// The image and its loading status.
 121         ImagePtr image_;
 122         ///
 123         ImageStatus status_;
 124
 125         /** A SignalLoadTypePtr is connected to this->imageLoaded and
 126          *  then passed to ImagePtr::load.
 127          *  When the image has been loaded, the signal is emitted.
 128          *
 129          *  We pass a shared_ptr because it is eminently possible for the
 130          *  GCacheItem to be destructed before the loading is complete and
 131          *  the signal must remain in scope. It doesn't matter if the slot
 132          *  disappears, SigC takes care of that.
 133          */
 134         typedef boost::signal1<void, bool> SignalLoadType;
 135         ///
 136         typedef boost::shared_ptr<SignalLoadType> SignalLoadTypePtr;
 137
 138         /// The connection of the signal passed to ImagePtr::loadImage.
 139         boost::signals::connection cl_;
 140
 141         /** A SignalConvertTypePtr is connected to this->imageConverted and
 142          *  then passed to GConverter::convert.
 143          *  When the image has been converted to a loadable format, the signal
 144          *  is emitted, returning the name of the loadable file to
 145          *  imageConverted.
 146          */
 147         typedef boost::signal1<void, string const &> SignalConvertType;
 148         ///
 149         typedef boost::shared_ptr<SignalConvertType> SignalConvertTypePtr;
 150
 151         /// The connection of the signal passed to GConverter::convert.
 152         boost::signals::connection cc_;
 153 };
 154
 155 } // namespace grfx
 156
 157 #endif // GRAPHICSCACHEITEM_H