src/EmbeddedFiles.h

   1 // -*- C++ -*-
   2 /**
   3  * \file EmbeddedFiles.h
   4  * This file is part of LyX, the document processor.
   5  * Licence details can be found in the file COPYING.
   6  *
   7  * \author Bo Peng
   8  *
   9  * Full author contact details are available in file CREDITS.
  10  *
  11  */
  12
  13 #ifndef EMBEDDEDFILES_H
  14 #define EMBEDDEDFILES_H
  15
  16 #include "support/FileName.h"
  17
  18 #include <vector>
  19 #include <utility>
  20
  21 #include "ParIterator.h"
  22 #include "Paragraph.h"
  23
  24 /**
  25
  26 This file, and the embedding dialog implemented in src/frontends, implements
  27 an 'Embedded Files' feature of lyx.
  28
  29
  30 Expected features:
  31 =========================
  32
  33 1. Bundled .lyx file can embed graphics, listings, bib file etc. The bundle
  34 format is used when Document->Save in bundled format is selected.
  35
  36 2. Embedded file.lyx file is a zip file, with content.lyx and embedded files.
  37
  38 3. The embedding status of embedded files can be set at the inset level,
  39 or from Document->Settings->Embedded Files.
  40
  41 4. Extra files such as .cls and .layout can be embedded from Document->
  42 Settings->Embedded Files->Extra Files.
  43
  44 5. When Document->Save in bundled format is selected, all embedded files
  45 become bundled. Changes to the external version of this file does not
  46 affect the output of the .lyx file.
  47
  48 6. When Document->Save in bundled format is unchecked, all embedded files
  49 are copied to their original locations.
  50
  51 Overall, this feature allows two ways of editing a .lyx file
  52
  53 a. The continuous use of the pure-text .lyx file format with external
  54 files. This is the default file format, and allows external editing
  55 of .lyx file and better use of version control systems.
  56
  57 b. The embedded way. Figures etc are inserted to .lyx file and will
  58 be embedded. These embedded files can be viewed or edited through
  59 the embedding dialog. This file can be shared with others more
  60 easily.
  61
  62 Format a anb b can be converted easily, by packing/unpacking a .lyx file.
  63
  64 Implementation:
  65 ======================
  66
  67 1. An EmbeddedFiles class is implemented to keep the embedded files (
  68 class EmbeddedFile). (c.f. src/EmbeddedFiles.[h|cpp])
  69
  70 2. When a file is saved, it is scanned for embedded files. (c.f.
  71 EmbeddedFiles::update(), Inset::registerEmbeddedFiles()).
  72
  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())
  77
  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())
  81
  82 5. A menu item Document -> Save in bundled format is provided to pack/unpack
  83 a .lyx file.
  84
  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.
  88
  89 */
  90
  91 namespace lyx {
  92
  93 class Buffer;
  94 class Lexer;
  95 class ErrorList;
  96
  97 class EmbeddedFile : public support::DocFileName
  98 {
  99 public:
 100         EmbeddedFile() {};
 101
 102         EmbeddedFile(std::string const & file, std::string const & inzip_name,
 103                 bool embedded, Inset const * inset);
 104
 105         /// filename in the zip file, usually the relative path
 106         std::string inzipName() const { return inzip_name_; }
 107         void setInzipName(std::string name) { inzip_name_ = name; }
 108         /// embedded file, equals to temppath()/inzipName()
 109         std::string embeddedFile(Buffer const * buf) const;
 110         /// embeddedFile() or absFilename() depending on embedding status
 111         std::string availableFile(Buffer const * buf) const;
 112
 113         /// add an inset that refers to this file
 114         void addInset(Inset const * inset);
 115         Inset const * inset(int idx) const;
 116         /// save the location of this inset as bookmark so that
 117         /// it can be located using LFUN_BOOKMARK_GOTO
 118         void saveBookmark(Buffer const * buf, int idx) const;
 119         /// Number of Insets this file item is referred
 120         /// If refCount() == 0, this file must be manually inserted.
 121         /// This fact is used by the update() function to skip updating
 122         /// such items.
 123         int refCount() const { return inset_list_.size(); }
 124
 125         /// embedding status of this file
 126         bool embedded() const { return embedded_; }
 127         /// set embedding status. updateFromExternal() should be called before this
 128         /// to copy or sync the embedded file with external one.
 129         void setEmbed(bool embed) { embedded_ = embed; }
 130
 131         /// extract file, does not change embedding status
 132         bool extract(Buffer const * buf) const;
 133         /// update embedded file from external file, does not change embedding status
 134         bool updateFromExternalFile(Buffer const * buf) const;
 135         ///
 136         /// After the embedding status is changed, update all insets related
 137         /// to this file item.
 138         /// Because inset pointers may not be up to date, EmbeddedFiles::update()
 139         /// would better be called before this function is called.
 140         void updateInsets(Buffer const * buf) const;
 141
 142 private:
 143         /// filename in zip file
 144         std::string inzip_name_;
 145         /// the status of this docfile
 146         bool embedded_;
 147         /// Insets that contains this file item. Because a
 148         /// file item can be referred by several Insets, a vector is used.
 149         std::vector<Inset const *> inset_list_;
 150 };
 151
 152
 153 class EmbeddedFiles {
 154 public:
 155         typedef std::vector<EmbeddedFile> EmbeddedFileList;
 156 public:
 157         ///
 158         EmbeddedFiles(Buffer * buffer = 0) : file_list_(), buffer_(buffer) {}
 159         ///
 160         ~EmbeddedFiles() {}
 161
 162         /// return buffer params embedded flag
 163         bool enabled() const;
 164         /// set buffer params embedded flag. Files will be updated or extracted
 165         /// if such an operation fails, enable will fail.
 166         void enable(bool flag);
 167
 168         /// add a file item.
 169         /* \param filename filename to add
 170          * \param embed embedding status. For a new file item, this is always true.
 171          *    If the file already exists, this parameter is ignored.
 172          * \param inset Inset pointer
 173          * \param inzipName suggested inzipname
 174          */
 175         EmbeddedFile & registerFile(std::string const & filename, bool embed = false,
 176                 Inset const * inset = 0,
 177                 std::string const & inzipName = std::string());
 178
 179         /// scan the buffer and get a list of EmbeddedFile
 180         void update();
 181
 182         /// write a zip file
 183         bool writeFile(support::DocFileName const & filename);
 184
 185         void clear() { file_list_.clear(); }
 186
 187         ///
 188         EmbeddedFile & operator[](size_t idx) { return *(file_list_.begin() + idx); }
 189         EmbeddedFile const & operator[](size_t idx) const { return *(file_list_.begin() + idx); }
 190         ///
 191         EmbeddedFileList::iterator begin() { return file_list_.begin(); }
 192         EmbeddedFileList::iterator end() { return file_list_.end(); }
 193         EmbeddedFileList::const_iterator begin() const { return file_list_.begin(); }
 194         EmbeddedFileList::const_iterator end() const { return file_list_.end(); }
 195         // try to locate filename, using either absFilename() or embeddedFile()
 196         EmbeddedFileList::const_iterator find(std::string filename) const;
 197         /// extract all file items, used when disable embedding
 198         bool extract() const;
 199         /// update all files from external, used when enable embedding
 200         bool updateFromExternalFile() const;
 201         ///
 202         /// update all insets to use embedded files when embedding status is changed
 203         void updateInsets() const;
 204 private:
 205         /// get a unique inzip name, a suggestion can be given.
 206         std::string const getInzipName(std::string const & name, std::string const & inzipName);
 207         /// list of embedded files
 208         EmbeddedFileList file_list_;
 209         ///
 210         Buffer * buffer_;
 211 };
 212
 213 } // namespace lyx
 214
 215 #endif