src/graphics/GraphicsLoader.h

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