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"
22 This file, and the embedding dialog implemented in src/frontends, implements
23 an 'Embedded Files' feature of lyx.
27 =========================
29 1. Bundled .lyx file can embed graphics, listings, bib file etc. The bundle
30 format is used when Document->Save in bundled format is selected.
32 2. Embedded file.lyx file is a zip file, with content.lyx and embedded files.
34 3. The embedding status of embedded files can be set at the inset level,
35 or from Document->Settings->Embedded Files.
37 4. Extra files such as .cls and .layout can be embedded from Document->
38 Settings->Embedded Files->Extra 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 anb 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 form.
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
99 EmbeddedFile(std::string const & file, std::string const & inzip_name,
100 bool embedded, Inset const * inset);
102 /// filename in the zip file, usually the relative path
103 std::string inzipName() const { return inzip_name_; }
104 void setInzipName(std::string name) { inzip_name_ = name; }
105 /// embedded file, equals to temppath()/inzipName()
106 std::string embeddedFile(Buffer const * buf) const;
107 /// embeddedFile() or absFilename() depending on embedding status
108 std::string availableFile(Buffer const * buf) const;
110 /// add an inset that refers to this file
111 void addInset(Inset const * inset);
112 Inset const * inset(int idx) const;
113 /// save the location of this inset as bookmark so that
114 /// it can be located using LFUN_BOOKMARK_GOTO
115 void saveBookmark(Buffer const * buf, int idx) const;
116 /// Number of Insets this file item is referred
117 /// If refCount() == 0, this file must be manually inserted.
118 /// This fact is used by the update() function to skip updating
120 int refCount() const { return inset_list_.size(); }
122 /// embedding status of this file
123 bool embedded() const { return embedded_; }
124 /// set embedding status. updateFromExternal() should be called before this
125 /// to copy or sync the embedded file with external one.
126 void setEmbed(bool embed) { embedded_ = embed; }
128 /// extract file, does not change embedding status
129 bool extract(Buffer const * buf) const;
130 /// update embedded file from external file, does not change embedding status
131 bool updateFromExternalFile(Buffer const * buf) const;
133 /// After the embedding status is changed, update all insets related
134 /// to this file item.
135 /// Because inset pointers may not be up to date, EmbeddedFiles::update()
136 /// would better be called before this function is called.
137 void updateInsets(Buffer const * buf) const;
140 /// filename in zip file
141 std::string inzip_name_;
142 /// the status of this docfile
144 /// Insets that contains this file item. Because a
145 /// file item can be referred by several Insets, a vector is used.
146 std::vector<Inset const *> inset_list_;
150 class EmbeddedFiles {
152 typedef std::vector<EmbeddedFile> EmbeddedFileList;
155 EmbeddedFiles(Buffer * buffer = 0) : file_list_(), buffer_(buffer) {}
159 /// return buffer params embedded flag
160 bool enabled() const;
161 /// set buffer params embedded flag. Files will be updated or extracted
162 /// if such an operation fails, enable will fail.
163 void enable(bool flag);
166 /* \param filename filename to add
167 * \param embed embedding status. For a new file item, this is always true.
168 * If the file already exists, this parameter is ignored.
169 * \param inset Inset pointer
170 * \param inzipName suggested inzipname
172 EmbeddedFile & registerFile(std::string const & filename, bool embed = false,
173 Inset const * inset = 0,
174 std::string const & inzipName = std::string());
176 /// scan the buffer and get a list of EmbeddedFile
180 bool writeFile(support::DocFileName const & filename);
182 void clear() { file_list_.clear(); }
185 EmbeddedFile & operator[](size_t idx) { return *(file_list_.begin() + idx); }
186 EmbeddedFile const & operator[](size_t idx) const { return *(file_list_.begin() + idx); }
188 EmbeddedFileList::iterator begin() { return file_list_.begin(); }
189 EmbeddedFileList::iterator end() { return file_list_.end(); }
190 EmbeddedFileList::const_iterator begin() const { return file_list_.begin(); }
191 EmbeddedFileList::const_iterator end() const { return file_list_.end(); }
192 // try to locate filename, using either absFilename() or embeddedFile()
193 EmbeddedFileList::const_iterator find(std::string filename) const;
194 /// extract all file items, used when disable embedding
195 bool extract() const;
196 /// update all files from external, used when enable embedding
197 bool updateFromExternalFile() const;
199 /// update all insets to use embedded files when embedding status is changed
200 void updateInsets() const;
202 /// get a unique inzip name, a suggestion can be given.
203 std::string const getInzipName(std::string const & name, std::string const & inzipName);
204 /// list of embedded files
205 EmbeddedFileList file_list_;