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
97 EmbeddedFile(std::string const & file = std::string(),
98 std::string const & buffer_path = std::string());
100 /// set filename and inzipName.
102 * NOTE: inzip_name_ is not unique across operation systems and is not
103 * guaranteed to be the same across different versions of LyX.
104 * inzip_name_ will be saved to the LyX file, and is used to indicate
105 * whether or not a file is embedded, and where the embedded file is in
106 * the bundled file. When a file is read, the stored inzip names are used
107 * at first. EmbeddedFiles::validate() will then scan these embedded files
108 * and update their inzip name, moving bundled files around if needed.
109 * This scheme has the advantage that it is safe to change how inzip files
110 * are saved in a bundled file.
112 * NOTE that this treatment does not welcome an UUID solution because
113 * all embedded files will have to be renamed when an embedded file is
114 * opened. It is of course possible to use saved inzipname, but that is
115 * not easy. For example, when a new EmbeddedFile is created with the same
116 * file as an old one, it needs to be synced to the old inzipname...
118 void set(std::string const & filename, std::string const & buffer_path);
119 /** Set the inzip name of an EmbeddedFile, which should be the name
120 * of an actual embedded file on disk.
122 void setInzipName(std::string const & name);
124 /// filename in the zip file, which is related to buffer temp directory.
125 std::string inzipName() const { return inzip_name_; }
127 /// embedded file, equals to temppath()/inzipName()
128 std::string embeddedFile() const;
129 /// embeddedFile() or absFilename() depending on embedding status
130 /// and whether or not embedding is enabled.
131 FileName availableFile() const;
132 /// relative file name or inzipName()
133 std::string latexFilename(std::string const & buffer_path) const;
135 /// add an inset that refers to this file
136 void addInset(Inset const * inset);
137 /// clear all isnets that associated with this file.
138 void clearInsets() const { inset_list_.clear(); }
140 /// embedding status of this file
141 bool embedded() const { return embedded_; }
142 /// set embedding status.
143 void setEmbed(bool embed);
145 /// whether or not embedding is enabled in the current buffer
147 * An embedded file needs to know the temp path of a buffer to know
148 * where its embedded copy is. This has to be stored within EmbeddedFile
149 * because this class is often used when Buffer is unavailable. However,
150 * when an embedded file is copied to another buffer, temp_path_ has
151 * to be updated and file copying may be needed.
153 bool enabled() const { return !temp_path_.empty(); }
154 /// enable embedding of this file
155 void enable(bool flag, Buffer const * buf, bool updateFile);
157 /// extract file, does not change embedding status
158 bool extract() const;
159 /// update embedded file from external file, does not change embedding status
160 bool updateFromExternalFile() const;
161 /// copy an embedded file to another buffer
162 EmbeddedFile copyTo(Buffer const * buf);
164 /// After the embedding status is changed, update all insets related
165 /// to this file item. For example, a graphic inset may need to monitor
166 /// embedded file instead of external file.
167 void updateInsets() const;
169 /// Check readability of availableFile
170 bool isReadableFile() const;
171 /// Calculate checksum of availableFile
172 unsigned long checksum() const;
174 // calculate inzip_name_ from filename
175 std::string calcInzipName(std::string const & buffer_path);
176 // move an embedded disk file with an existing inzip_name_ to
177 // a calculated inzip_name_, if they differ.
178 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 : public std::vector<EmbeddedFile> {
202 /// set buffer params embedded flag. Files will be updated or extracted
203 /// if such an operation fails, enable will fail.
204 void enable(bool flag, Buffer & buffer, bool updateFile);
207 /* \param file Embedded file to add
208 * \param inset Inset pointer
210 void registerFile(EmbeddedFile const & file, Inset const * inset,
211 Buffer const & buffer);
213 /// validate embedded fies after a file is read.
214 void validate(Buffer const & buffer);
216 /// scan the buffer and get a list of EmbeddedFile
217 void update(Buffer const & buffer);
220 bool writeFile(support::DocFileName const & filename, Buffer const & buffer);