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. Embedding of certain files are automatic (graphics, bib etc), and
37 other files can be embedded manually.
39 3. Embedded file.lyx file is a zip file, with file.lyx, manifest.txt
42 4. Embedded files can be "EMBEDDED", "EXTERNAL", or "AUTO". In the
43 "AUTO" mode, external files will be used if available; otherwise the
44 embedded version will be used. In this way, users can work as usual by
45 modifying external listings, graphics, and do not have to worry about
46 embedding. "EMBEDDED" and "EXTERNAL" modes ignore or use external files
49 5. An embedding dialog is provided to change embedding status (buffer
50 level or individual embedded files), manually embed, extract, view
53 Overall, this feature allows two ways of editing a .lyx file
55 a. The continuous use of the pure-text .lyx file format with external
56 files. This is the default file format, and allows external editing
57 of .lyx file and better use of version control systems.
59 b. The embedded way. Figures etc are inserted to .lyx file and will
60 be embedded. These embedded files can be viewed or edited through
61 the embedding dialog. This file can be shared with others more
62 easily. The advantage of lyx' embedding approach is that external files
63 will be automatically used and embedded if the file is in "AUTO" mode.
67 ======================
69 1. An EmbeddedFiles class is implemented to keep the embedded files (
70 class EmbeddedFile). (c.f. src/EmbeddedFiles.[h|cpp])
71 This class keeps a manifest that has
72 a. external relative filename
73 b. inzip filename. It is the relative path name if the embedded file is
74 in or under the document directory, or file name otherwise. Name aliasing
75 is used if two external files share the same name.
77 It also provides functions to
78 a. manipulate manifest
79 b. scan a buffer for embeddable files
80 c. look up inzipname from external filename
81 d. look up external filename from inzipname
83 2. When a file is saved, it is scanned for embedded files. (c.f.
84 EmbeddedFiles::update(), Inset::registerEmbeddedFiles()).
86 3. When a lyx file file.lyx is saved, it is save to tmppath() first.
87 Embedded files are compressed along with file.lyx and a manifest.txt.
88 If embedding is disabled, file.lyx is saved in the usual pure-text form.
89 (c.f. Buffer::writeFile(), EmbeddedFiles::write())
91 4. When a lyx file.lyx file is opened, if it is a zip file, it is
92 decompressed to tmppath(). If manifest.txt and file.lyx exists in
93 tmppath(), the manifest is read to buffer, and tmppath()/file.lyx is
94 read as usual. If file.lyx is not a zip file, it is read as usual.
95 (c.f. bool Buffer::readFile())
97 5. A menu item Document -> Embedded Files is provided to open
98 a embedding dialog. It handles a EmbddedFiles point directly.
99 From this dialog, a user can disable embedding, change embedding status,
100 or embed other files, extract, view, edit files.
102 6. When a lyx file is loaded, Embedded files can have
103 a. both external and internal copy
104 b. only external copy (filename())
105 c. only embedded copy (temppath()/inzipname)
106 And each can have "AUTO", "EXTERNAL", "EMBEDDED" status. Proper
107 handling of each case is required.
109 7. If embedding of a .lyx file with embedded files is disabled, all its
110 embedded files are copied to their respective external filenames. This
111 is why external filename will exist even if a file is at "EMBEDDED" status.
113 8. Individual embeddable insets should find ways to handle embedded files.
114 InsetGraphics replace params().filename with its temppath()/inzipname version
115 when the inset is created. The filename appears as /tmp/..../inzipname
116 when lyx runs. When params().filename is saved, lyx checks if this is an
117 embedded file (check path == temppath()), if so, save filename() instead.
118 (c.f. InsetGraphic::read(), InsetGraphics::edit(), InsetGraphicsParams::write())
127 class EmbeddedFile : public support::DocFileName
131 Embedding status of this DocFileName.
134 // uninitialized/invalid status
136 // If the external version of the file is available, it will be used
137 // to generate output, and be embedded to the saved lyx file.
138 // Otherwise, embedded version will be used.
140 // Always use embedded version. The file will be embedded even
141 // if the file is no longer referred by the document.
143 // Do not embed this file, always use external version.
147 EmbeddedFile(std::string const & file, std::string const & inzip_name,
148 STATUS status, ParConstIterator const & pit);
150 /// filename in the zip file, usually the relative path
151 std::string inzipName() const { return inzip_name_; }
152 /// embedded file, equals to temppath()/inzipName()
153 std::string embeddedFile(Buffer const * buf) const;
154 /// embeddedFile() or absFilename() depending on status_ and
155 /// file availability
156 std::string availableFile(Buffer const * buf) const;
159 void setParIter(ParConstIterator const & pit);
160 int const parID() const;
162 /// embedding status of this file
163 bool embedded() const { return status_ != EXTERNAL; }
164 STATUS status() const { return status_; }
165 void setStatus(STATUS status) { status_ = status; }
167 // A flag indicating whether or not this filename is valid.
168 // When lyx runs, InsetGraphics etc may be added or removed so filename
169 // maybe obsolete. In Buffer::updateEmbeddedFiles, the EmbeddedFiles is first
170 // invalidated (c.f. invalidate()), and all insets are asked to register
171 // embedded files. In this way, EmbeddedFileList will be refreshed, with
172 // status setting untouched.
173 bool valid() const { return valid_; }
174 void validate() { valid_ = true; }
175 void invalidate() { valid_ = false; }
177 bool extract(Buffer const * buf) const;
180 /// filename in zip file
181 std::string inzip_name_;
182 /// the status of this docfile
186 /// Current position of the item, used to locate the files
187 /// A figure may be referred by several items. In this case
188 /// only the last location is recorded.
189 ParConstIterator par_it_;
193 class EmbeddedFiles {
195 typedef std::vector<EmbeddedFile> EmbeddedFileList;
198 EmbeddedFiles(Buffer * buffer = NULL): file_list_(), buffer_(buffer) {}
202 /// return buffer params embedded flag
203 bool enabled() const;
204 /// set buffer params embedded flag
205 void enable(bool flag);
208 void registerFile(std::string const & filename,
209 EmbeddedFile::STATUS status = EmbeddedFile::AUTO,
210 ParConstIterator const & pit = ParConstIterator());
212 /// scan the buffer and get a list of EmbeddedFile
216 bool write(support::DocFileName const & filename);
218 void clear() { file_list_.clear(); }
221 EmbeddedFile & operator[](size_t idx) { return *(file_list_.begin() + idx); }
222 EmbeddedFile const & operator[](size_t idx) const { return *(file_list_.begin() + idx); }
224 EmbeddedFileList::iterator begin() { return file_list_.begin(); }
225 EmbeddedFileList::iterator end() { return file_list_.end(); }
226 EmbeddedFileList::const_iterator begin() const { return file_list_.begin(); }
227 EmbeddedFileList::const_iterator end() const { return file_list_.end(); }
229 bool extractAll() const;
231 friend std::istream & operator>> (std::istream & is, EmbeddedFiles &);
233 friend std::ostream & operator<< (std::ostream & os, EmbeddedFiles const &);
235 /// get a unique inzip name
236 std::string const getInzipName(std::string const & name);
237 /// list of embedded files
238 EmbeddedFileList file_list_;
244 std::istream & operator>> (std::istream & is, EmbeddedFiles &);
246 std::ostream & operator<< (std::ostream & os, EmbeddedFiles const &);