src/graphics/GraphicsCacheItem.h

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