src/graphics/GraphicsCacheItem.h

   1 // -*- C++ -*-
   2 /**
   3  * \file GraphicsCacheItem.h
   4  * Read the file COPYING
   5  *
   6  * \author Baruch Even
   7  * \author Angus Leeming
   8  *
   9  * Full author contact details available in file CREDITS
  10  *
  11  * The graphics cache is a container of grfx::CacheItems.
  12  * Each grfx::CacheItem, defined here represents a separate image file.
  13  *
  14  * The routines here can be used to load the graphics file into memory at
  15  * which point (status() == grfx::Loaded).
  16  * The user is then free to access image() in order to copy it and to then
  17  * transform the copy (rotate, scale, clip) and to generate the pixmap.
  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::Converter and on the
  24  * grfx::Image-derived image class.
  25  */
  26
  27 #ifndef GRAPHICSCACHEITEM_H
  28 #define GRAPHICSCACHEITEM_H
  29
  30 #ifdef __GNUG__
  31 #pragma interface
  32 #endif
  33
  34 #include "GraphicsTypes.h"
  35 #include "LString.h"
  36
  37 #include <boost/utility.hpp>
  38 #include <boost/scoped_ptr.hpp>
  39 #include <boost/signals/signal0.hpp>
  40
  41 class InsetGraphics;
  42
  43 namespace grfx {
  44
  45 class Image;
  46 class Converter;
  47
  48 /// A grfx::Cache item holder.
  49 class CacheItem : boost::noncopyable {
  50 public:
  51         ///
  52         CacheItem(string const & file);
  53
  54         /// Define an empty d-tor out-of-line to keep boost::scoped_ptr happy.
  55         ~CacheItem();
  56
  57         ///
  58         string const & filename() const;
  59
  60         /// It's in the cache. Now start the loading process.
  61         void startLoading() const;
  62
  63         /** Monitor any changes to the file.
  64          *  There is no point monitoring the file before startLoading() is
  65          *  invoked.
  66          */
  67         void startMonitoring() const;
  68         ///
  69         bool monitoring() const;
  70         /** Returns the check sum of filename() so that, for example, you can
  71          *  ascertain whether to output a new PostScript version of the file
  72          *  for a LaTeX run.
  73          */
  74         unsigned long checksum() const;
  75
  76         /** Get the image associated with filename().
  77          *  If the image is not yet loaded, returns 0.
  78          *  This routine returns a pointer to const; if you want to modify it,
  79          *  create a copy and modify that.
  80          */
  81         Image const * image() const;
  82
  83         /// How far have we got in loading the image?
  84         ImageStatus status() const;
  85
  86         /** Connect and you'll be informed when the loading status of the image
  87          *  changes.
  88          */
  89         typedef boost::signal0<void>::slot_type slot_type;
  90         ///
  91         boost::signals::connection connect(slot_type const &) const;
  92
  93 private:
  94         /// Use the Pimpl idiom to hide the internals.
  95         class Impl;
  96
  97         /// The pointer never changes although *pimpl_'s contents may.
  98         boost::scoped_ptr<Impl> const pimpl_;
  99 };
 100
 101 } // namespace grfx
 102
 103 #endif // GRAPHICSCACHEITEM_H