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