src/graphics/GraphicsLoader.h

   1 // -*- C++ -*-
   2 /**
   3  *  \file GraphicsLoader.h
   4  *  Read the file COPYING
   5  *
   6  *  \author Angus Leeming
   7  *
   8  * Full author contact details are available in file CREDITS
   9  *
  10  *  The public face of the graphics cache.
  11  *
  12  *  * The user supplies an image file and the display parameters.
  13  *  * He can change the file or the display parameters through a reset() method.
  14  *  * He must start the loading process explicitly with startLoading().
  15  *  * If he is connected through the connect() method, then he'll be informed
  16  *    when the loading status changes.
  17  *  * When (status() == Ready), he can use image() to access the loaded image
  18  *    and pass it to the Painter.
  19  *
  20  *  What could be simpler?
  21  */
  22
  23 #ifndef GRAPHICSLOADER_H
  24 #define GRAPHICSLOADER_H
  25
  26 #ifdef __GNUG__
  27 #pragma interface
  28 #endif
  29
  30 #include "GraphicsTypes.h"
  31 #include "LString.h"
  32
  33 #include <boost/signals/signal0.hpp>
  34 #include <boost/scoped_ptr.hpp>
  35
  36 class Inset;
  37 class BufferView;
  38
  39 namespace grfx {
  40
  41 class Image;
  42 class Params;
  43
  44 class Loader {
  45 public:
  46         /// Must use the reset methods to make this instance usable.
  47         Loader();
  48         /// The image is not transformed, just displayed as-is.
  49         Loader(string const & file_with_path, DisplayType = ColorDisplay);
  50         /// The image is transformed before display.
  51         Loader(string const & file_with_path, Params const &);
  52
  53         /// Define an empty d-tor out-of-line to keep boost::scoped_ptr happy.
  54         ~Loader();
  55
  56         /// The file can be changed, or the display params, or both.
  57         void reset(string const & file_with_path,
  58                    DisplayType = ColorDisplay) const;
  59         ///
  60         void reset(string const & file_with_path, Params const &) const;
  61         ///
  62         void reset(Params const &) const;
  63
  64         /// Returns the absolute path of the loaded (loading?) file.
  65         string const & filename() const;
  66         ///
  67         bool empty() const { return filename().empty(); }
  68
  69         /// We are explicit about when we begin the loading process.
  70         void startLoading() const;
  71
  72         /** starting loading of the image is conditional upon the
  73          *  inset being visible or not.
  74          */
  75         void startLoading(Inset const &, BufferView const &) const;
  76
  77         /** Monitor any changes to the file.
  78          *  There is no point monitoring the file before startLoading() is
  79          *  invoked.
  80          */
  81         void startMonitoring() const;
  82         ///
  83         bool monitoring() const;
  84         /** Returns the check sum of filename() so that, for example, you can
  85          *  ascertain whether to output a new PostScript version of the file
  86          *  for a LaTeX run.
  87          */
  88         unsigned long checksum() const;
  89
  90         /// How far have we got in loading the image?
  91         ImageStatus status() const;
  92
  93         /** Connect and you'll be informed when the loading status of the image
  94          *  changes.
  95          */
  96         typedef boost::signal0<void>::slot_type slot_type;
  97         ///
  98         boost::signals::connection connect(slot_type const &) const;
  99
 100         /** The loaded image with Pixmap set.
 101          *  If the Pixmap is not yet set (see status() for why...), returns 0.
 102          */
 103         Image const * image() const;
 104
 105 private:
 106         /// Use the Pimpl idiom to hide the internals.
 107         class Impl;
 108         /// The pointer never changes although *pimpl_'s contents may.
 109         boost::scoped_ptr<Impl> const pimpl_;
 110 };
 111
 112 } // namespace grfx
 113
 114 #endif // GRAPHICSLOADER_H