3 * \file EmbeddedFiles.h
4 * This file is part of LyX, the document processor.
5 * Licence details can be found in the file COPYING.
9 * Full author contact details are available in file CREDITS.
13 #ifndef EMBEDDEDFILES_H
14 #define EMBEDDEDFILES_H
16 #include "support/FileName.h"
23 This file, and the embed checkbox in dialogs of InsetGraphics etc, implements
24 an 'Embedded Files' feature of lyx.
28 =========================
30 1. Bundled .lyx file can embed graphics, listings, bib file etc. The bundle
31 format is used when Document->Save in bundled format is selected.
33 2. Embedded file.lyx file is a zip file, with content.lyx and embedded files.
35 3. The embedding status of embedded files are set from individual insets.
37 4. Extra files such as .cls and .layout can be embedded from Document->
38 Settings->Embedded Files->Extra Embedded Files.
40 5. When Document->Save in bundled format is selected, all embedded files
41 become bundled. Changes to the external version of this file does not
42 affect the output of the .lyx file.
44 6. When Document->Save in bundled format is unchecked, all embedded files
45 are copied to their original locations.
47 Overall, this feature allows two ways of editing a .lyx file
49 a. The continuous use of the pure-text .lyx file format with external
50 files. This is the default file format, and allows external editing
51 of .lyx file and better use of version control systems.
53 b. The embedded way. Figures etc are inserted to .lyx file and will
54 be embedded. These embedded files can be viewed or edited through
55 the embedding dialog. This file can be shared with others more
58 Format a and b can be converted easily, by packing/unpacking a .lyx file.
61 ======================
63 1. An EmbeddedFiles class is implemented to keep the embedded files (
64 class EmbeddedFile). (c.f. src/EmbeddedFiles.[h|cpp])
66 2. When a file is saved, it is scanned for embedded files. (c.f.
67 EmbeddedFiles::update(), Inset::registerEmbeddedFiles()).
69 3. When a lyx file file.lyx is saved, it is save to tmppath()/content.lyx
70 first. Embedded files are compressed along with content.lyx.
71 If embedding is disabled, file.lyx is saved in the usual pure-text format.
72 (c.f. Buffer::writeFile(), EmbeddedFiles::writeFile())
74 4. When a lyx file.lyx file is opened, if it is a zip file, it is
75 decompressed to tmppath() and tmppath()/content.lyx is read as usual.
76 (c.f. bool Buffer::readFile())
78 5. A menu item Document -> Save in bundled format is provided to pack/unpack
81 6. If embedding of a .lyx file with embedded files is disabled, all its
82 embedded files are copied to their respective external filenames. This
83 is why external filename will exist even if a file is at "EMBEDDED" status.
94 class EmbeddedFile : public support::DocFileName
98 EmbeddedFile(std::string const & file = std::string(),
99 std::string const & buffer_path = std::string());
101 /// set filename and inzipName.
103 * NOTE: inzip_name_ is not unique across operation systems and is not
104 * guaranteed to be the same across different versions of LyX.
105 * inzip_name_ will be saved to the LyX file, and is used to indicate
106 * whether or not a file is embedded, and where the embedded file is in
107 * the bundled file. When a file is read, the stored inzip names are used
108 * at first. EmbeddedFiles::validate() will then scan these embedded files
109 * and update their inzip name, moving bundled files around if needed.
110 * This scheme has the advantage that it is safe to change how inzip files
111 * are saved in a bundled file.
113 * NOTE that this treatment does not welcome an UUID solution because
114 * all embedded files will have to be renamed when an embedded file is
115 * opened. It is of course possible to use saved inzipname, but that is
116 * not easy. For example, when a new EmbeddedFile is created with the same
117 * file as an old one, it needs to be synced to the old inzipname...
119 void set(std::string const & filename, std::string const & buffer_path);
120 /** Set the inzip name of an EmbeddedFile, which should be the name
121 * of an actual embedded file on disk.
123 void setInzipName(std::string const & name);
125 /// filename in the zip file, which is related to buffer temp directory.
126 std::string inzipName() const { return inzip_name_; }
128 /// embedded file, equals to temppath()/inzipName()
129 std::string embeddedFile() const;
130 /// embeddedFile() or absFilename() depending on embedding status
131 /// and whether or not embedding is enabled.
132 FileName availableFile() const;
133 /// relative file name or inzipName()
134 std::string latexFilename(std::string const & buffer_path) const;
136 /// add an inset that refers to this file
137 void addInset(Inset const * inset);
138 /// clear all isnets that associated with this file.
139 void clearInsets() const { inset_list_.clear(); }
141 /// embedding status of this file
142 bool embedded() const { return embedded_; }
143 /// set embedding status.
144 void setEmbed(bool embed);
146 /// whether or not embedding is enabled for the current file
148 * An embedded file needs to know the temp path of a buffer to know
149 * where its embedded copy is. This has to be stored within EmbeddedFile
150 * because this class is often used when Buffer is unavailable. However,
151 * when an embedded file is copied to another buffer, temp_path_ has
152 * to be updated and file copying may be needed.
154 bool isEnabled() const { return !temp_path_.empty(); }
155 /// enable embedding of this file
156 void enable(bool enabled, Buffer const & buf, bool updateFile);
158 /// extract file, does not change embedding status
159 bool extract() const;
160 /// update embedded file from external file, does not change embedding status
161 bool updateFromExternalFile() const;
162 /// copy an embedded file to another buffer
163 EmbeddedFile copyTo(Buffer const & buf);
165 /// After the embedding status is changed, update all insets related
166 /// to this file item. For example, a graphic inset may need to monitor
167 /// embedded file instead of external file.
168 void updateInsets() const;
170 /// Check readability of availableFile
171 bool isReadableFile() const;
172 /// Calculate checksum of availableFile
173 unsigned long checksum() const;
175 // calculate inzip_name_ from filename
176 std::string calcInzipName(std::string const & buffer_path);
177 // move an embedded disk file with an existing inzip_name_ to
178 // a calculated inzip_name_, if they differ.
179 void syncInzipFile(std::string const & buffer_path);
181 /// filename in zip file
182 std::string inzip_name_;
183 /// the status of this docfile
185 /// Insets that contains this file item. Because a
186 /// file item can be referred by several Insets, a vector is used.
187 mutable std::vector<Inset const *> inset_list_;
188 /// Embedded file needs to know whether enbedding is enabled,
189 /// and where is the lyx temporary directory. Such information can
190 /// be retrived from a buffer, but a buffer is not always available when
191 /// an EmbeddedFile is used.
192 std::string temp_path_;
196 bool operator==(EmbeddedFile const & lhs, EmbeddedFile const & rhs);
197 bool operator!=(EmbeddedFile const & lhs, EmbeddedFile const & rhs);
200 class EmbeddedFileList {
203 typedef std::vector<EmbeddedFile>::iterator iterator;
205 typedef std::vector<EmbeddedFile>::const_iterator const_iterator;
207 iterator begin() { return eflist_.begin(); }
208 iterator end() { return eflist_.end(); }
209 const_iterator begin() const { return eflist_.begin(); }
210 const_iterator end() const { return eflist_.end(); }
212 void push_back(EmbeddedFile const & ef) { eflist_.push_back(ef); }
214 EmbeddedFile const & back() const { return eflist_.back(); }
215 EmbeddedFile & back() { return eflist_.back(); }
217 void clear() { eflist_.clear(); }
219 bool empty() const { return eflist_.empty(); }
221 void insert(iterator position, const_iterator itbeg, const_iterator itend)
222 { eflist_.insert(position, itbeg, itend); }
223 void insert(iterator position, EmbeddedFile const & ef)
224 { eflist_.insert(position, ef); }
226 iterator erase(iterator position) { return eflist_.erase(position); }
229 /// set buffer params embedded flag. Files will be updated or extracted
230 /// if such an operation fails, enable will fail.
231 void enable(bool enabled, Buffer & buffer, bool updateFile);
234 /** \param file Embedded file to add
235 * \param inset Inset pointer
237 void registerFile(EmbeddedFile const & file, Inset const * inset,
238 Buffer const & buffer);
239 /// returns an iterator pointing to the Embedded file representing
240 /// the file with the absolute filename <filename>.
241 const_iterator findFile(std::string const & filename) const;
242 iterator findFile(std::string const & filename);
244 /// validate embedded fies after a file is read.
245 void validate(Buffer const & buffer);
246 /// scan the buffer and get a list of EmbeddedFile
247 void update(Buffer const & buffer);
249 bool writeFile(support::DocFileName const & filename, Buffer const & buffer);
252 std::vector<EmbeddedFile> eflist_;