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.
142 // Do not embed this file, always use external version.
146 EmbeddedFile(std::string const & file, std::string const & inzip_name,
147 STATUS status, ParConstIterator const & pit);
149 /// filename in the zip file, usually the relative path
150 std::string inzipName() const { return inzip_name_; }
151 /// embedded file, equals to temppath()/inzipName()
152 std::string embeddedFile(Buffer const * buf) const;
155 void setParIter(ParConstIterator const & pit);
156 int const parID() const { return par_it_->id(); }
158 /// embedding status of this file
159 bool embedded() const { return status_ != EXTERNAL; }
160 STATUS status() const { return status_; }
161 void setStatus(STATUS status) { status_ = status; }
163 // A flag indicating whether or not this filename is valid.
164 // When lyx runs, InsetGraphics etc may be added or removed so filename
165 // maybe obsolete. In Buffer::updateEmbeddedFiles, the EmbeddedFiles is first
166 // invalidated (c.f. invalidate()), and all insets are asked to register
167 // embedded files. In this way, EmbeddedFileList will be refreshed, with
168 // status setting untouched.
169 bool valid() const { return valid_; }
170 void validate() { valid_ = true; }
171 void invalidate() { valid_ = false; }
174 /// filename in zip file
175 std::string inzip_name_;
176 /// the status of this docfile
180 /// Current position of the item, used to locate the files
181 /// A figure may be referred by several items. In this case
182 /// only the last location is recorded.
183 ParConstIterator par_it_;
187 class EmbeddedFiles {
189 typedef std::vector<EmbeddedFile> EmbeddedFileList;
192 EmbeddedFiles(Buffer * buffer = NULL): file_list_(), buffer_(buffer) {}
196 /// return buffer params embedded flag
197 bool enabled() const;
198 /// set buffer params embedded flag
199 void enable(bool flag);
202 void registerFile(std::string const & filename,
203 EmbeddedFile::STATUS status = EmbeddedFile::AUTO,
204 ParConstIterator const & pit = ParConstIterator());
206 /// scan the buffer and get a list of EmbeddedFile
210 bool write(support::DocFileName const & filename);
212 void clear() { file_list_.clear(); }
215 EmbeddedFile & operator[](size_t idx) { return *(file_list_.begin() + idx); }
216 EmbeddedFile const & operator[](size_t idx) const { return *(file_list_.begin() + idx); }
218 EmbeddedFileList::iterator begin() { return file_list_.begin(); }
219 EmbeddedFileList::iterator end() { return file_list_.end(); }
220 EmbeddedFileList::const_iterator begin() const { return file_list_.begin(); }
221 EmbeddedFileList::const_iterator end() const { return file_list_.end(); }
224 friend std::istream & operator>> (std::istream & is, EmbeddedFiles &);
226 friend std::ostream & operator<< (std::ostream & os, EmbeddedFiles const &);
228 /// if a inzip name already exists
229 bool validInzipName(std::string const & name);
230 /// list of embedded files
231 EmbeddedFileList file_list_;
237 std::istream & operator>> (std::istream & is, EmbeddedFiles &);
239 std::ostream & operator<< (std::ostream & os, EmbeddedFiles const &);