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"
21 #include "ParIterator.h"
22 #include "Paragraph.h"
26 This file, and the embedding dialog implemented in src/frontends, implements
27 an 'Embedded Files' feature of lyx.
31 =========================
33 1. With embedding enabled (disabled by default), .lyx file can embed graphics,
34 listings, bib file etc.
36 2. Embedded file.lyx file is a zip file, with file.lyx, manifest.txt
39 3. An embedding dialog is provided to change embedding status (buffer
40 level or individual embedded files), manually embed, extract, view
43 Overall, this feature allows two ways of editing a .lyx file
45 a. The continuous use of the pure-text .lyx file format with external
46 files. This is the default file format, and allows external editing
47 of .lyx file and better use of version control systems.
49 b. The embedded way. Figures etc are inserted to .lyx file and will
50 be embedded. These embedded files can be viewed or edited through
51 the embedding dialog. This file can be shared with others more
54 Format a anb b can be converted easily, by enable/disable embedding. Diabling
55 embedding is also called unpacking because all embedded files will be copied
56 to their original locations.
59 ======================
61 1. An EmbeddedFiles class is implemented to keep the embedded files (
62 class EmbeddedFile). (c.f. src/EmbeddedFiles.[h|cpp])
63 This class keeps a manifest that has
64 a. external relative filename
65 b. inzip filename. It is the relative path name if the embedded file is
66 in or under the document directory, or file name otherwise. Name aliasing
67 is used if two external files share the same name.
69 It also provides functions to
70 a. manipulate manifest
71 b. scan a buffer for embeddable files
72 c. determine which file to use according to embedding status
74 2. When a file is saved, it is scanned for embedded files. (c.f.
75 EmbeddedFiles::update(), Inset::registerEmbeddedFiles()).
77 3. When a lyx file file.lyx is saved, it is save to tmppath() first.
78 Embedded files are compressed along with file.lyx and a manifest.txt.
79 If embedding is disabled, file.lyx is saved in the usual pure-text form.
80 (c.f. Buffer::writeFile(), EmbeddedFiles::writeFile())
82 4. When a lyx file.lyx file is opened, if it is a zip file, it is
83 decompressed to tmppath(). If manifest.txt and file.lyx exists in
84 tmppath(), the manifest is read to buffer, and tmppath()/file.lyx is
85 read as usual. If file.lyx is not a zip file, it is read as usual.
86 (c.f. bool Buffer::readFile())
88 5. A menu item Document -> Embedded Files is provided to open
89 a embedding dialog. It handles a EmbddedFiles point directly.
90 From this dialog, a user can disable embedding, change embedding status,
91 or embed other files, extract, view, edit files.
93 6. If embedding of a .lyx file with embedded files is disabled, all its
94 embedded files are copied to their respective external filenames. This
95 is why external filename will exist even if a file is at "EMBEDDED" status.
97 7. Individual embeddable insets should find ways to handle embedded files.
98 InsetGraphics replace params().filename with its temppath()/inzipname version
99 when the inset is created. The filename appears as /tmp/..../inzipname
100 when lyx runs. When params().filename is saved, lyx checks if this is an
101 embedded file (check path == temppath()), if so, save filename() instead.
102 (c.f. InsetGraphic::read(), InsetGraphics::edit(), InsetGraphicsParams::write())
113 class EmbeddedFile : public support::DocFileName
116 EmbeddedFile(std::string const & file, std::string const & inzip_name,
117 bool embedded, Inset const * inset);
119 /// filename in the zip file, usually the relative path
120 std::string inzipName() const { return inzip_name_; }
121 /// embedded file, equals to temppath()/inzipName()
122 std::string embeddedFile(Buffer const * buf) const;
123 /// embeddedFile() or absFilename() depending on embedding status
124 std::string availableFile(Buffer const * buf) const;
126 /// add an inset that refers to this file
127 void addInset(Inset const * inset);
128 Inset const * inset(int idx) const;
129 /// save the location of this inset as bookmark so that
130 /// it can be located using LFUN_BOOKMARK_GOTO
131 void saveBookmark(Buffer const * buf, int idx) const;
132 /// Number of Insets this file item is referred
133 /// If refCount() == 0, this file must be manually inserted.
134 /// This fact is used by the update() function to skip updating
136 int refCount() const { return inset_list_.size(); }
138 /// embedding status of this file
139 bool embedded() const { return embedded_; }
140 /// set embedding status. updateFromExternal() should be called before this
141 /// to copy or sync the embedded file with external one.
142 void setEmbed(bool embed) { embedded_ = embed; }
144 // A flag indicating whether or not this filename is valid.
145 // When lyx runs, InsetGraphics etc may be added or removed so filename
146 // maybe obsolete. In Buffer::updateEmbeddedFiles, the EmbeddedFiles is first
147 // invalidated (c.f. invalidate()), and all insets are asked to register
148 // embedded files. In this way, EmbeddedFileList will be refreshed, with
149 // status setting untouched.
150 bool valid() const { return valid_; }
151 void validate() { valid_ = true; }
154 /// extract file, does not change embedding status
155 bool extract(Buffer const * buf) const;
156 /// update embedded file from external file, does not change embedding status
157 bool updateFromExternalFile(Buffer const * buf) const;
159 /// After the embedding status is changed, update all insets related
160 /// to this file item.
161 /// Because inset pointers may not be up to date, EmbeddedFiles::update()
162 /// would better be called before this function is called.
163 void updateInsets(Buffer const * buf) const;
166 /// filename in zip file
167 std::string inzip_name_;
168 /// the status of this docfile
172 /// Current position of the item, used to locate the files. Because one
173 /// file item can be referred by several Insets, a vector is used.
174 std::vector<Inset const *> inset_list_;
178 class EmbeddedFiles {
180 typedef std::vector<EmbeddedFile> EmbeddedFileList;
183 EmbeddedFiles(Buffer * buffer = 0) : file_list_(), buffer_(buffer) {}
187 /// return buffer params embedded flag
188 bool enabled() const;
189 /// set buffer params embedded flag. Files will be updated or extracted
190 /// if such an operation fails, enable will fail.
191 void enable(bool flag);
194 /* \param filename filename to add
195 * \param embed embedding status. For a new file item, this is always true.
196 * If the file already exists, this parameter is ignored.
197 * \param inset Inset pointer
198 * \param inzipName suggested inzipname
200 void registerFile(std::string const & filename, bool embed = false,
201 Inset const * inset = 0,
202 std::string const & inzipName = std::string());
204 /// scan the buffer and get a list of EmbeddedFile
208 bool writeFile(support::DocFileName const & filename);
210 void clear() { file_list_.clear(); }
213 EmbeddedFile & operator[](size_t idx) { return *(file_list_.begin() + idx); }
214 EmbeddedFile const & operator[](size_t idx) const { return *(file_list_.begin() + idx); }
216 EmbeddedFileList::iterator begin() { return file_list_.begin(); }
217 EmbeddedFileList::iterator end() { return file_list_.end(); }
218 EmbeddedFileList::const_iterator begin() const { return file_list_.begin(); }
219 EmbeddedFileList::const_iterator end() const { return file_list_.end(); }
220 // try to locate filename, using either absFilename() or embeddedFile()
221 EmbeddedFileList::const_iterator find(std::string filename) const;
222 /// extract all file items, used when disable embedding
223 bool extract() const;
224 /// update all files from external, used when enable embedding
225 bool updateFromExternalFile() const;
227 bool readManifest(Lexer & lex, ErrorList & errorList);
228 void writeManifest(std::ostream & os) const;
229 /// update all insets to use embedded files when embedding status is changed
230 void updateInsets() const;
232 /// get a unique inzip name, a suggestion can be given.
233 std::string const getInzipName(std::string const & name, std::string const & inzipName);
234 /// list of embedded files
235 EmbeddedFileList file_list_;