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 #include "GraphicsTypes.h"
  28
  29 #include "support/signals.h"
  30
  31 namespace lyx {
  32
  33 namespace support { class FileName; }
  34
  35 namespace graphics {
  36
  37 class Image;
  38 class Params;
  39
  40 class Loader {
  41 public:
  42         /// Must use the reset methods to make this instance usable.
  43         Loader(support::FileName const & doc_file);
  44         /// The image is not transformed, just displayed as-is.
  45         Loader(support::FileName const & doc_file, support::FileName const & file_with_path, bool display = true);
  46         /// The image is transformed before display.
  47         Loader(support::FileName const & doc_file, support::FileName const & file_with_path, Params const &);
  48         ///
  49         Loader(support::FileName const & doc_file, Loader const &);
  50         ///
  51         Loader(Loader const & other);
  52         /// Needed for the pimpl
  53         ~Loader();
  54
  55         Loader & operator=(Loader const &);
  56
  57         /// The file can be changed, or the display params, or both.
  58         void reset(support::FileName const & file_with_path, bool display = true) const;
  59         ///
  60         void reset(support::FileName 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         support::FileName const & filename() const;
  66         ///
  67
  68         /** starting loading of the image is done by a urgency-based
  69          *  decision. Here we only call LoaderQueue::touch to request it.
  70          */
  71         void startLoading() const;
  72
  73         /** Tries to reload the image.
  74          */
  75         void reload() 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         ///
  85         void checkModifiedAsync() const;
  86
  87         /// How far have we got in loading the image?
  88         ImageStatus status() const;
  89
  90         /** Connect and you'll be informed when the loading status of the image
  91          *  changes.
  92          */
  93         typedef signals2::signal<void()> sig;
  94         typedef sig::slot_type slot;
  95         ///
  96         signals2::connection connect(slot const &) const;
  97
  98         /** The loaded image with Pixmap set.
  99          *  If the Pixmap is not yet set (see status() for why...), returns 0.
 100          */
 101         Image const * image() const;
 102
 103         double displayPixelRatio() const;
 104         void setDisplayPixelRatio(double scale);
 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         Impl * pimpl_;
 111 };
 112
 113 } // namespace graphics
 114 } // namespace lyx
 115
 116 #endif // GRAPHICSLOADER_H