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() const;
112 /// embeddedFile() or absFilename() depending on embedding status
113 /// and whether or not embedding is enabled.
114 FileName availableFile() const;
116 std::string latexFilename(std::string const & buffer_path) const;
118 /// add an inset that refers to this file
119 void addInset(Inset const * inset);
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);
128 /// whether or not embedding is enabled in the current buffer
129 bool enabled() const { return temp_path_ != ""; }
130 /// enable embedding of this file
131 void enable(bool flag, Buffer const * buf);
133 /// extract file, does not change embedding status
134 bool extract() const;
135 /// update embedded file from external file, does not change embedding status
136 bool updateFromExternalFile() const;
138 /// After the embedding status is changed, update all insets related
139 /// to this file item. For example, a graphic inset may need to monitor
140 /// embedded file instead of external file. To make sure inset pointers
141 /// are up to date, please make sure there is no modification to the
142 /// document between EmbeddedFiles::update() and this function.
143 void updateInsets(Buffer const * buf) const;
145 /// Check readability of availableFile
146 bool isReadableFile() const;
147 /// Calculate checksum of availableFile
148 unsigned long checksum() const;
151 /// filename in zip file
152 std::string inzip_name_;
153 /// the status of this docfile
155 /// Insets that contains this file item. Because a
156 /// file item can be referred by several Insets, a vector is used.
157 std::vector<Inset const *> inset_list_;
158 /// Embedded file needs to know whether enbedding is enabled,
159 /// and where is the lyx temporary directory. Such information can
160 /// be retrived from a buffer, but a buffer is not always available when
161 /// an EmbeddedFile is used.
162 std::string temp_path_;
166 bool operator==(EmbeddedFile const & lhs, EmbeddedFile const & rhs);
167 bool operator!=(EmbeddedFile const & lhs, EmbeddedFile const & rhs);
170 class EmbeddedFiles {
172 typedef std::vector<EmbeddedFile> EmbeddedFileList;
175 EmbeddedFiles(Buffer * buffer = 0) : file_list_(), buffer_(buffer) {}
179 /// return buffer params embedded flag
180 bool enabled() const;
181 /// set buffer params embedded flag. Files will be updated or extracted
182 /// if such an operation fails, enable will fail.
183 void enable(bool flag);
186 /* \param file Embedded file to add
187 * \param inset Inset pointer
189 void registerFile(EmbeddedFile const & file, Inset const * inset = 0);
191 /// scan the buffer and get a list of EmbeddedFile
195 bool writeFile(support::DocFileName const & filename);
197 void clear() { file_list_.clear(); }
200 EmbeddedFileList::iterator begin() { return file_list_.begin(); }
201 EmbeddedFileList::iterator end() { return file_list_.end(); }
202 EmbeddedFileList::const_iterator begin() const { return file_list_.begin(); }
203 EmbeddedFileList::const_iterator end() const { return file_list_.end(); }
206 /// list of embedded files
207 EmbeddedFileList file_list_;