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 embedding dialog implemented in src/frontends, 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 can be set at the inset level,
36 or from Document->Settings->Embedded Files.
38 4. Extra files such as .cls and .layout can be embedded from Document->
39 Settings->Embedded Files->Extra Files.
41 5. When Document->Save in bundled format is selected, all embedded files
42 become bundled. Changes to the external version of this file does not
43 affect the output of the .lyx file.
45 6. When Document->Save in bundled format is unchecked, all embedded files
46 are copied to their original locations.
48 Overall, this feature allows two ways of editing a .lyx file
50 a. The continuous use of the pure-text .lyx file format with external
51 files. This is the default file format, and allows external editing
52 of .lyx file and better use of version control systems.
54 b. The embedded way. Figures etc are inserted to .lyx file and will
55 be embedded. These embedded files can be viewed or edited through
56 the embedding dialog. This file can be shared with others more
59 Format a and b can be converted easily, by packing/unpacking a .lyx file.
61 NOTE: With current implementation, files with absolute filenames (not in
62 or deeper under the current document directory) can not be embedded.
65 ======================
67 1. An EmbeddedFiles class is implemented to keep the embedded files (
68 class EmbeddedFile). (c.f. src/EmbeddedFiles.[h|cpp])
70 2. When a file is saved, it is scanned for embedded files. (c.f.
71 EmbeddedFiles::update(), Inset::registerEmbeddedFiles()).
73 3. When a lyx file file.lyx is saved, it is save to tmppath()/content.lyx
74 first. Embedded files are compressed along with content.lyx.
75 If embedding is disabled, file.lyx is saved in the usual pure-text form.
76 (c.f. Buffer::writeFile(), EmbeddedFiles::writeFile())
78 4. When a lyx file.lyx file is opened, if it is a zip file, it is
79 decompressed to tmppath() and tmppath()/content.lyx is read as usual.
80 (c.f. bool Buffer::readFile())
82 5. A menu item Document -> Save in bundled format is provided to pack/unpack
85 6. If embedding of a .lyx file with embedded files is disabled, all its
86 embedded files are copied to their respective external filenames. This
87 is why external filename will exist even if a file is at "EMBEDDED" status.
98 class EmbeddedFile : public support::DocFileName
101 EmbeddedFile(std::string const & file = std::string(),
102 std::string const & buffer_path = std::string());
104 /// set filename and inzipName.
106 * NOTE: inzip_name_ is not unique across operation systems and is not
107 * guaranteed to be the same across different versions of lyx.
108 * inzip_name_ will be saved to the lyx file, and is used to indicate
109 * whether or not a file is embedded, and where the embedded file is in
110 * the bundled file. However, the embedded file will be renamed to the
111 * name set here when an EmbeddedFile is enabled. It is therefore
112 * safe to change the naming scheme here.
114 * NOTE that this treatment does not welcome an UUID solution because
115 * all embedded files will have to be renamed when an embedded file is
116 * opened. It is of course possible to use saved inzipname, but that is
117 * not easy. For example, when a new EmbeddedFile is created with the same
118 * file as an old one, it needs to be synced to the old inzipname...
120 void set(std::string const & filename, std::string const & buffer_path);
121 /** Set the inzip name of an EmbeddedFile, which should be the name
122 * of an actual embedded file on disk. When an EmbeddedFile is enabled,
123 * this file will be renamed to the default inzipName if needed.
125 void setInzipName(std::string const & name);
127 /// filename in the zip file, which is the relative path
128 std::string inzipName() const { return inzip_name_; }
130 /// embedded file, equals to temppath()/inzipName()
131 std::string embeddedFile() const;
132 /// embeddedFile() or absFilename() depending on embedding status
133 /// and whether or not embedding is enabled.
134 FileName availableFile() const;
136 std::string latexFilename(std::string const & buffer_path) const;
138 /// add an inset that refers to this file
139 void addInset(Inset const * inset);
140 int refCount() const { return inset_list_.size(); }
142 /// embedding status of this file
143 bool embedded() const { return embedded_; }
144 /// set embedding status. updateFromExternal() should be called before this
145 /// to copy or sync the embedded file with external one.
146 void setEmbed(bool embed);
148 /// whether or not embedding is enabled in the current buffer
149 bool enabled() const { return temp_path_ != ""; }
150 /// enable embedding of this file
151 void enable(bool flag, Buffer const * buf);
153 /// extract file, does not change embedding status
154 bool extract() const;
155 /// update embedded file from external file, does not change embedding status
156 bool updateFromExternalFile() const;
158 /// After the embedding status is changed, update all insets related
159 /// to this file item. For example, a graphic inset may need to monitor
160 /// embedded file instead of external file. To make sure inset pointers
161 /// are up to date, please make sure there is no modification to the
162 /// document between EmbeddedFiles::update() and this function.
163 void updateInsets(Buffer const * buf) const;
165 /// Check readability of availableFile
166 bool isReadableFile() const;
167 /// Calculate checksum of availableFile
168 unsigned long checksum() const;
171 // calculate inzip_name_ from filename
172 std::string calcInzipName(std::string const & buffer_path);
173 // move an embedded disk file with an existing inzip_name_ to
174 // an calculated inzip_name_
175 void syncInzipFile(std::string const & buffer_path);
178 /// filename in zip file
179 std::string inzip_name_;
180 /// the status of this docfile
182 /// Insets that contains this file item. Because a
183 /// file item can be referred by several Insets, a vector is used.
184 std::vector<Inset const *> inset_list_;
185 /// Embedded file needs to know whether enbedding is enabled,
186 /// and where is the lyx temporary directory. Such information can
187 /// be retrived from a buffer, but a buffer is not always available when
188 /// an EmbeddedFile is used.
189 std::string temp_path_;
193 bool operator==(EmbeddedFile const & lhs, EmbeddedFile const & rhs);
194 bool operator!=(EmbeddedFile const & lhs, EmbeddedFile const & rhs);
197 class EmbeddedFileList : public std::vector<EmbeddedFile> {
199 /// set buffer params embedded flag. Files will be updated or extracted
200 /// if such an operation fails, enable will fail.
201 void enable(bool flag, Buffer & buffer);
204 /* \param file Embedded file to add
205 * \param inset Inset pointer
207 void registerFile(EmbeddedFile const & file, Inset const * inset, Buffer const & buffer);
209 /// scan the buffer and get a list of EmbeddedFile
210 void update(Buffer const & buffer);
213 bool writeFile(support::DocFileName const & filename, Buffer const & buffer);