3 * \file GraphicsCacheItem.h
4 * Copyright 2002 the LyX Team
5 * Read the file COPYING
7 * \author Baruch Even <baruch.even@writeme.com>
8 * \author Angus Leeming <a.leeming@ic.ac.uk>
10 * The graphics cache is a container of GCacheItems. Each GCacheItem, defined
11 * here represents a separate image file. However, each file can be viewed in
12 * different ways (different sizes, rotations etc), so each GCacheItem itself
13 * contains a list of ModifiedItems, also defined here. Each ModifiedItem
14 * has a GParams variable that defines the way it will be viewed. It also
15 * contains a list of the graphics insets that refer to it, so calls through
16 * the GCache to GCacheItem ultimately return the loading status and image
17 * for that particular graphics inset.
19 * The graphics cache supports fully asynchronous:
20 * file conversion to a loadable format;
23 * Whether you get that, of course, depends on grfx::GConverter and on the
24 * grfx::GImage-derived image class.
26 * Image modification (scaling, rotation etc) is blocking.
29 #ifndef GRAPHICSCACHEITEM_H
30 #define GRAPHICSCACHEITEM_H
36 #include "GraphicsTypes.h"
39 #include <boost/utility.hpp>
40 #include <boost/shared_ptr.hpp>
42 #include <boost/signals/signal1.hpp>
43 #include <boost/signals/connection.hpp>
44 #include <boost/signals/trackable.hpp>
55 /// A grfx::GCache item holder.
56 class GCacheItem : boost::noncopyable, public boost::signals::trackable {
58 /// the GCacheItem contains data of this type.
59 typedef boost::shared_ptr<ModifiedItem> ModifiedItemPtr;
62 GCacheItem(InsetGraphics const &, GParams const &);
64 /// The params have changed (but still refer to this file).
65 void modify(InsetGraphics const &, GParams const &);
67 /// Remove the reference to this inset.
68 void remove(InsetGraphics const &);
70 /// It's in the cache. Now start the loading process.
71 void startLoading(InsetGraphics const &);
73 /// Is the cache item referenced by any insets at all?
76 /// The name of the original image file.
77 string const & filename() const;
79 /// Is this image file referenced by this inset?
80 bool referencedBy(InsetGraphics const &) const;
82 /** Returns the image referenced by this inset (or an empty container
83 * if it's not yet loaded.
85 ImagePtr const image(InsetGraphics const &) const;
87 /// The loading status of the image referenced by this inset.
88 ImageStatus status(InsetGraphics const &) const;
90 /** If (changed_background == true), then the background color of the
91 * graphics inset has changed. Update all images.
92 * Else, the preferred display type has changed.
93 * Update the view of all insets whose display type is DEFAULT.
95 void changeDisplay(bool changed_background);
97 /// Used to ascertain the Bounding Box of non (e)ps files.
98 unsigned int raw_width() const;
100 unsigned int raw_height() const;
103 /** Start the image conversion process, checking first that it is
104 * necessary. If it is necessary, then a conversion task is started.
105 * GCacheItem asumes that the conversion is asynchronous and so
106 * passes a Signal to the converting routine. When the conversion
107 * is finished, this Signal is emitted, returning the converted
108 * file to this->imageConverted.
110 * If no file conversion is needed, then convertToDisplayFormat() calls
111 * loadImage() directly.
113 * convertToDisplayFormat() will set the loading status flag as
114 * approriate through calls to setStatus().
116 void convertToDisplayFormat();
118 /** Load the image into memory. This is called either from
119 * convertToDisplayFormat() direct or from imageConverted().
123 /** Get a notification when the image conversion is done.
124 * Connected to a signal on_finish_ which is passed to
125 * GConverter::convert.
127 void imageConverted(string const & file_to_load);
129 /** Get a notification when the image loading is done.
130 * Connected to a signal on_finish_ which is passed to
133 void imageLoaded(bool);
135 /// How far have we got in loading the original, unmodified image?
136 ImageStatus status() const;
138 /** Sets the status of the loading process. Also notifies
139 * listeners that the status has chacnged.
141 void setStatus(ImageStatus new_status);
143 /// The filename we refer too.
145 /// Is the file compressed?
147 /// If so, store the uncompressed file in this temporary file.
148 string unzipped_filename_;
149 /// What file are we trying to load?
150 string file_to_load_;
151 /** Should we delete the file after loading? True if the file is
152 * the result of a conversion process.
154 bool remove_loaded_file_;
156 /// The original, unmodified image and its loading status.
161 /** A SignalLoadTypePtr is connected to this->imageLoaded and
162 * then passed to ImagePtr::load.
163 * When the image has been loaded, the signal is emitted.
165 * We pass a shared_ptr because it is eminently possible for the
166 * ModifiedItem to be destructed before the loading is complete and
167 * the signal must remain in scope. It doesn't matter if the slot
168 * disappears, SigC takes care of that.
170 typedef boost::signal1<void, bool> SignalLoadType;
172 typedef boost::shared_ptr<SignalLoadType> SignalLoadTypePtr;
174 /// The connection of the signal passed to ImagePtr::loadImage.
175 boost::signals::connection cl_;
177 /** A SignalConvertTypePtr is connected to this->imageConverted and
178 * then passed to GConverter::convert.
179 * When the image has been converted to a loadable format, the signal
180 * is emitted, returning the name of the loadable file to
183 typedef boost::signal1<void, string const &> SignalConvertType;
185 typedef boost::shared_ptr<SignalConvertType> SignalConvertTypePtr;
187 /// The connection of the signal passed to GConverter::convert.
188 boost::signals::connection cc_;
190 /// The list of all modified images.
191 typedef std::list<ModifiedItemPtr> ListType;
193 ListType modified_images;
201 ModifiedItem(InsetGraphics const &, GParams const &, ImagePtr const &);
204 GParams const & params() { return *p_.get(); }
206 /// Add inset to the list of insets.
207 void add(InsetGraphics const & inset);
209 /// Remove inset from the list of insets.
210 void remove(InsetGraphics const & inset);
213 bool empty() const { return insets.empty(); }
215 /// Is this ModifiedItem referenced by inset?
216 bool referencedBy(InsetGraphics const & inset) const;
219 ImagePtr const image() const;
221 /// How far have we got in loading the modified image?
222 ImageStatus status() const { return status_; }
224 /** Called from GCacheItem once the raw image is loaded.
225 * Modifies the image in accord with p_.
227 void modify(ImagePtr const &);
229 /// Updates the pixmap.
232 /** changeDisplay returns a full ModifiedItemPtr if any of the
233 * insets have display=DEFAULT and if that DEFAULT value has
235 * If this occurs, then this has these insets removed.
237 boost::shared_ptr<ModifiedItem> changeDisplay();
240 typedef std::list<InsetGraphics const *> ListType;
242 /// Make these accessible for changeDisplay.
246 /** Sets the status of the loading process. Also notifies
247 * listeners that the status has changed.
249 void setStatus(ImageStatus new_status);
251 /// The original and modified images and its loading status.
252 ImagePtr original_image_;
254 ImagePtr modified_image_;
258 boost::shared_ptr<GParams> p_;
263 #endif // GRAPHICSCACHEITEM_H