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.
105 void set(std::string const & filename, std::string const & buffer_path);
107 /// filename in the zip file, which is the relative path
108 std::string inzipName() const { return inzip_name_; }
110 /// embedded file, equals to temppath()/inzipName()
111 std::string embeddedFile(Buffer const * buf) const;
112 /// embeddedFile() or absFilename() depending on embedding status
113 std::string availableFile(Buffer const * buf) const;
115 /// add an inset that refers to this file
116 void addInset(Inset const * inset);
117 Inset const * inset(int idx) const;
118 /// Number of Insets this file item is referred
119 /// If refCount() == 0, this file must be manually inserted.
120 /// This fact is used by the update() function to skip updating
122 int refCount() const { return inset_list_.size(); }
124 /// embedding status of this file
125 bool embedded() const { return embedded_; }
126 /// set embedding status. updateFromExternal() should be called before this
127 /// to copy or sync the embedded file with external one.
128 void setEmbed(bool embed);
129 /// Only files in or under current document path is embeddable
130 bool embeddable() const { return inzip_name_ != ""; }
132 /// extract file, does not change embedding status
133 bool extract(Buffer const * buf) const;
134 /// update embedded file from external file, does not change embedding status
135 bool updateFromExternalFile(Buffer const * buf) const;
137 /// After the embedding status is changed, update all insets related
138 /// to this file item. For example, a graphic inset may need to monitor
139 /// embedded file instead of external file. To make sure inset pointers
140 /// are up to date, please make sure there is no modification to the
141 /// document between EmbeddedFiles::update() and this function.
142 void updateInsets(Buffer const * buf) const;
145 /// filename in zip file
146 std::string inzip_name_;
147 /// the status of this docfile
149 /// Insets that contains this file item. Because a
150 /// file item can be referred by several Insets, a vector is used.
151 std::vector<Inset const *> inset_list_;
155 bool operator==(EmbeddedFile const & lhs, EmbeddedFile const & rhs);
156 bool operator!=(EmbeddedFile const & lhs, EmbeddedFile const & rhs);
159 class EmbeddedFiles {
161 typedef std::vector<EmbeddedFile> EmbeddedFileList;
164 EmbeddedFiles(Buffer * buffer = 0) : file_list_(), buffer_(buffer) {}
168 /// return buffer params embedded flag
169 bool enabled() const;
170 /// set buffer params embedded flag. Files will be updated or extracted
171 /// if such an operation fails, enable will fail.
172 void enable(bool flag);
175 /* \param file Embedded file to add
176 * \param inset Inset pointer
178 EmbeddedFile & registerFile(EmbeddedFile const & file, Inset const * inset = 0);
180 /// scan the buffer and get a list of EmbeddedFile
184 bool writeFile(support::DocFileName const & filename);
186 void clear() { file_list_.clear(); }
189 EmbeddedFile & operator[](size_t idx) { return *(file_list_.begin() + idx); }
190 EmbeddedFile const & operator[](size_t idx) const { return *(file_list_.begin() + idx); }
192 EmbeddedFileList::iterator begin() { return file_list_.begin(); }
193 EmbeddedFileList::iterator end() { return file_list_.end(); }
194 EmbeddedFileList::const_iterator begin() const { return file_list_.begin(); }
195 EmbeddedFileList::const_iterator end() const { return file_list_.end(); }
196 // try to locate filename, using either absFilename() or embeddedFile()
197 EmbeddedFileList::const_iterator find(std::string filename) const;
198 /// extract all file items, used when disable embedding
199 bool extractAll() const;
200 /// update all files from external, used when enable embedding
201 bool updateFromExternalFile() const;
203 /// update all insets to use embedded files when embedding status is changed
204 void updateInsets() const;
206 /// list of embedded files
207 EmbeddedFileList file_list_;