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. The routines here can be used to
12 * load the graphics file into memory at which point (status() == grfx::Loaded).
13 * The user is then free to access image() in order to transform the image
14 * (rotate, scale, clip) and to generate the pixmap.
16 * The graphics cache supports fully asynchronous:
17 * file conversion to a loadable format;
20 * Whether you get that, of course, depends on grfx::GConverter and on the
21 * grfx::GImage-derived image class.
24 #ifndef GRAPHICSCACHEITEM_H
25 #define GRAPHICSCACHEITEM_H
31 #include "GraphicsTypes.h"
34 #include <boost/utility.hpp>
35 #include <boost/shared_ptr.hpp>
37 #include <boost/signals/signal0.hpp>
38 #include <boost/signals/signal1.hpp>
39 #include <boost/signals/connection.hpp>
40 #include <boost/signals/trackable.hpp>
46 /// A grfx::GCache item holder.
47 class GCacheItem : boost::noncopyable, public boost::signals::trackable {
50 GCacheItem(string const & file);
52 /// It's in the cache. Now start the loading process.
55 /** Get the image associated with filename_.
56 If the image is not yet loaded, return a null pointer.
58 ImagePtr const image() const { return image_; }
60 /// How far have we got in loading the image?
61 ImageStatus status() const { return status_; }
63 /// This signal is emitted when the image loading status changes.
64 boost::signal0<void> statusChanged;
67 string const & filename() const { return filename_; }
70 /** Start the image conversion process, checking first that it is
71 * necessary. If it is necessary, then a conversion task is started.
72 * GCacheItem asumes that the conversion is asynchronous and so
73 * passes a Signal to the converting routine. When the conversion
74 * is finished, this Signal is emitted, returning the converted
75 * file to this->imageConverted.
77 * If no file conversion is needed, then convertToDisplayFormat() calls
78 * loadImage() directly.
80 * convertToDisplayFormat() will set the loading status flag as
81 * approriate through calls to setStatus().
83 void convertToDisplayFormat();
85 /** Load the image into memory. This is called either from
86 * convertToDisplayFormat() direct or from imageConverted().
90 /** Get a notification when the image conversion is done.
91 * Connected to a signal on_finish_ which is passed to
92 * GConverter::convert.
94 void imageConverted(string const & file_to_load);
96 /** Get a notification when the image loading is done.
97 * Connected to a signal on_finish_ which is passed to
100 void imageLoaded(bool);
102 /** Sets the status of the loading process. Also notifies
103 * listeners that the status has chacnged.
105 void setStatus(ImageStatus new_status);
107 /// The filename we refer too.
109 /// Is the file compressed?
111 /// If so, store the uncompressed file in this temporary file.
112 string unzipped_filename_;
113 /// What file are we trying to load?
114 string file_to_load_;
115 /** Should we delete the file after loading? True if the file is
116 * the result of a conversion process.
118 bool remove_loaded_file_;
120 /// The image and its loading status.
125 /** A SignalLoadTypePtr is connected to this->imageLoaded and
126 * then passed to ImagePtr::load.
127 * When the image has been loaded, the signal is emitted.
129 * We pass a shared_ptr because it is eminently possible for the
130 * GCacheItem to be destructed before the loading is complete and
131 * the signal must remain in scope. It doesn't matter if the slot
132 * disappears, SigC takes care of that.
134 typedef boost::signal1<void, bool> SignalLoadType;
136 typedef boost::shared_ptr<SignalLoadType> SignalLoadTypePtr;
138 /// The connection of the signal passed to ImagePtr::loadImage.
139 boost::signals::connection cl_;
141 /** A SignalConvertTypePtr is connected to this->imageConverted and
142 * then passed to GConverter::convert.
143 * When the image has been converted to a loadable format, the signal
144 * is emitted, returning the name of the loadable file to
147 typedef boost::signal1<void, string const &> SignalConvertType;
149 typedef boost::shared_ptr<SignalConvertType> SignalConvertTypePtr;
151 /// The connection of the signal passed to GConverter::convert.
152 boost::signals::connection cc_;
157 #endif // GRAPHICSCACHEITEM_H