source: trunk/libdjvu/DjVuDocEditor.h @ 426

Last change on this file since 426 was 280, checked in by rbri, 12 years ago

DJVU plugin: djvulibre updated to version 3.5.22

File size: 19.6 KB
Line 
1//C-  -*- C++ -*-
2//C- -------------------------------------------------------------------
3//C- DjVuLibre-3.5
4//C- Copyright (c) 2002  Leon Bottou and Yann Le Cun.
5//C- Copyright (c) 2001  AT&T
6//C-
7//C- This software is subject to, and may be distributed under, the
8//C- GNU General Public License, either Version 2 of the license,
9//C- or (at your option) any later version. The license should have
10//C- accompanied the software or you may obtain a copy of the license
11//C- from the Free Software Foundation at http://www.fsf.org .
12//C-
13//C- This program is distributed in the hope that it will be useful,
14//C- but WITHOUT ANY WARRANTY; without even the implied warranty of
15//C- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16//C- GNU General Public License for more details.
17//C-
18//C- DjVuLibre-3.5 is derived from the DjVu(r) Reference Library from
19//C- Lizardtech Software.  Lizardtech Software has authorized us to
20//C- replace the original DjVu(r) Reference Library notice by the following
21//C- text (see doc/lizard2002.djvu and doc/lizardtech2007.djvu):
22//C-
23//C-  ------------------------------------------------------------------
24//C- | DjVu (r) Reference Library (v. 3.5)
25//C- | Copyright (c) 1999-2001 LizardTech, Inc. All Rights Reserved.
26//C- | The DjVu Reference Library is protected by U.S. Pat. No.
27//C- | 6,058,214 and patents pending.
28//C- |
29//C- | This software is subject to, and may be distributed under, the
30//C- | GNU General Public License, either Version 2 of the license,
31//C- | or (at your option) any later version. The license should have
32//C- | accompanied the software or you may obtain a copy of the license
33//C- | from the Free Software Foundation at http://www.fsf.org .
34//C- |
35//C- | The computer code originally released by LizardTech under this
36//C- | license and unmodified by other parties is deemed "the LIZARDTECH
37//C- | ORIGINAL CODE."  Subject to any third party intellectual property
38//C- | claims, LizardTech grants recipient a worldwide, royalty-free,
39//C- | non-exclusive license to make, use, sell, or otherwise dispose of
40//C- | the LIZARDTECH ORIGINAL CODE or of programs derived from the
41//C- | LIZARDTECH ORIGINAL CODE in compliance with the terms of the GNU
42//C- | General Public License.   This grant only confers the right to
43//C- | infringe patent claims underlying the LIZARDTECH ORIGINAL CODE to
44//C- | the extent such infringement is reasonably necessary to enable
45//C- | recipient to make, have made, practice, sell, or otherwise dispose
46//C- | of the LIZARDTECH ORIGINAL CODE (or portions thereof) and not to
47//C- | any greater extent that may be necessary to utilize further
48//C- | modifications or combinations.
49//C- |
50//C- | The LIZARDTECH ORIGINAL CODE is provided "AS IS" WITHOUT WARRANTY
51//C- | OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
52//C- | TO ANY WARRANTY OF NON-INFRINGEMENT, OR ANY IMPLIED WARRANTY OF
53//C- | MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
54//C- +------------------------------------------------------------------
55//
56// $Id: DjVuDocEditor.h,v 1.12 2008/09/28 12:46:14 leonb Exp $
57// $Name: release_3_5_22 $
58
59#ifndef _DJVUDOCEDITOR_H
60#define _DJVUDOCEDITOR_H
61#ifdef HAVE_CONFIG_H
62#include "config.h"
63#endif
64#if NEED_GNUG_PRAGMAS
65# pragma interface
66#endif
67
68
69#include "DjVuDocument.h"
70#include "DjVmDoc.h"
71
72#ifdef HAVE_NAMESPACES
73namespace DJVU {
74# ifdef NOT_DEFINED // Just to fool emacs c++ mode
75}
76#endif
77#endif
78
79/** @name DjVuDocEditor.h
80    Files #"DjVuDocEditor.h"# and #"DjVuDocEditor.cpp"# contain extension
81    of \Ref{DjVuDocument} class, which can create and modify existing
82    DjVu document, generate thumbnails, etc. It does {\bf not} do
83    compression though.
84
85    @memo DjVu document editor class.
86    @author Andrei Erofeev <eaf@geocities.com>
87    @version #$Id: DjVuDocEditor.h,v 1.12 2008/09/28 12:46:14 leonb Exp $#
88*/
89
90//@{
91
92/** #DjVuDocEditor# is an extension of \Ref{DjVuDocument} class with
93    additional capabilities for editing the document contents.
94
95    It can be used to:
96    \begin{enumerate}
97       \item Create (compose) new multipage DjVu documents using single
98             page DjVu documents. The class does {\bf not} do compression.
99       \item Insert and remove different pages of multipage DjVu documents.
100       \item Change attributes ({\em names}, {\em IDs} and {\em titles})
101             of files composing the DjVu document.
102       \item Generate thumbnail images and integrate them into the document.
103    \end{enumerate}
104*/
105
106class DJVUAPI DjVuDocEditor : public DjVuDocument
107{
108public:
109   static int   thumbnails_per_file;
110
111protected:
112      /// Default constructor
113   DjVuDocEditor(void);
114
115      /** Initialization function. Initializes an empty document.
116
117          {\bf Note}: You must call either of the two
118          available \Ref{init}() function before you start doing
119          anything else with the #DjVuDocEditor#. */
120   void         init(void);
121
122      /** Initialization function. Opens document with name #filename#.
123
124          {\bf Note}: You must call either of the two
125          available \Ref{init}() function before you start doing
126          anything else with the #DjVuDocEditor#. */
127   void         init(const GURL &url);
128
129public:
130     /** Creates a DjVuDocEditor class and initializes with #fname#. */
131   static GP<DjVuDocEditor> create_wait(const GURL &url);
132
133     /** Creates a DjVuDocEditor class and initializes an empty document. */
134   static GP<DjVuDocEditor> create_wait(void);
135
136
137      /// Destructor
138   virtual ~DjVuDocEditor(void);
139
140      /** Returns type of open document. #DjVuDocEditor# silently
141          converts any open DjVu document to #BUNDLED# format (see
142          \Ref{DjVuDocument}. Thus, \Ref{DjVuDocument::get_doc_type}()
143          will always be returning #BUNDLED#. Use this function to
144          learn the original format of the document being edited. */
145   int          get_orig_doc_type(void) const;
146
147      /** Returns #TRUE# if the document can be "saved" (sometimes
148          the only possibility is to do a "save as"). The reason why
149          we have this function is that #DjVuDocEditor# can save
150          documents in new formats only (#BUNDLED# and #INDIRECT#).
151          At the same time it recognizes all DjVu formats (#OLD_BUNDLED#,
152          #OLD_INDEXED#, #BUNDLED#, and #INDIRECT#).
153
154          #OLD_BUNDLED# and #BUNDLED# documents occupy only one file,
155          so in this case "saving" involves the automatic conversion
156          to #BUNDLED# format and storing data into the same file.
157
158          #OLD_INDEXED# documents, on the other hand, occupy more
159          than one file. They could be converted to #INDIRECT# format
160          if these two formats had the same set of files. Unfortunately,
161          these formats are too different, and the best thing to do
162          is to use "save as" capability. */
163   bool         can_be_saved(void) const;
164
165      /** Returns type of the document, which can be created by
166          \Ref{save}() function. Can be #INDIRECT#, #BUNDLED#,
167          #SINGLE_PAGE#, or #UNKNOWN_TYPE#. The latter indicates,
168          that \Ref{save}() will fail, and that \Ref{save_as}()
169          should be used instead */
170   int          get_save_doc_type(void) const;
171
172      /** Saves the document. May generate exception if the document
173          can not be saved, and \Ref{save_as}() should be used.
174          See \Ref{can_be_saved}() for details. */
175   void         save(void);
176
177      /** Saves the document. */
178   virtual void save_as(const GURL &where, bool bundled);
179
180      /** Saves the document in the {\em new bundled} format. All the data
181          is "bundled" into one file and this file is written into the
182          passed stream.
183
184          If #force_djvm# is #TRUE# then even one page documents will be
185          saved in the #DJVM BUNDLED# format (inside a #FORM:DJVM#);
186
187          {\bf Plugin Warning}. This function will read contents of the whole
188          document. Thus, if you call it from the main thread (the thread,
189          which transfers data from Netscape), the plugin will block. */
190   virtual void write(const GP<ByteStream> &str, bool force_djvm=false);
191     /** Always save as bundled, renaming any files conflicting with the
192         the names in the supplied GMap. */
193   virtual void write(const GP<ByteStream> &str,
194     const GMap<GUTF8String,void *> &reserved);
195
196      /** Saves the specified pages in DjVu #BUNDLED# multipage document. */
197   void         save_pages_as(
198     const GP<ByteStream> &str, const GList<int> & page_list);
199
200      /** Translates page number #page_num# to ID. If #page_num# is invalid,
201          an exception is thrown. */
202   GUTF8String  page_to_id(int page_num) const;
203   
204   GUTF8String  insert_file(const GURL &url, const GUTF8String &parent_id,
205                            int chunk_num=1, DjVuPort *source=0);
206      /** Inserts the referenced file into this DjVu document.
207
208          @param fname Name of the top-level file containing the image of
209                 the page to be inserted. This file must be a DjVu file and
210                 may include one or more other DjVu files.
211
212                 If it include other DjVu files, the function will try to
213                 insert them into the document too. Should this attempt fail,
214                 the corresponding #INCL# chunk will be removed from the
215                 referencing file and an exception will be thrown.
216
217                 When inserting a file, the function may modify its name
218                 to be unique in the DjVu document.
219          @param page_num Position where the new page should be inserted at.
220                 Negative value means "append" */
221   void insert_page(const GURL &fname, int page_num=-1);
222   /** Inserts a new page with data inside the #data_pool# as page
223       number #page_num.
224
225          @param data_pool \Ref{DataPool} with data for this page.
226          @param file_name Name, which will be assigned to this page.
227                 If you try to save the document in #INDIRECT# format,
228                 a file with this name will be created to hold the
229                 page's data. If there is already a file in the document
230                 with the same name, the function will derive a new
231                 unique name from file_name, which will be assigned
232                 to the page.
233          @param page_num Describes where the page should be inserted.
234                 Negative number means "append". */
235   void         insert_page(GP<DataPool> & file_pool,
236                            const GURL &fname, int page_num=-1);
237      /** Inserts a group of pages into this DjVu document.
238         
239          Like \Ref{insert_page}() it will insert every page into the document.
240          The main advantage of calling this function once for the whole
241          group instead of calling \Ref{insert_page}() for every page is
242          the processing of included files:
243
244          The group of files may include one or more files, which are thus
245          shared by them. If you call \Ref{insert_page}() for every page,
246          this shared file will be inserted into the document more than once
247          though under different names. This is how \Ref{insert_page}() works:
248          whenever it inserts something, it checks for duplicate names with
249          only one purpose: invent a new name if a given one is already in
250          use.
251
252          On the other hand, if you call #insert_group#(), it will insert
253          shared included files only once. This is because it can analyze
254          the group of files before inserting them and figure out what files
255          are shared and thus should be inserted only once.
256
257          @param fname_list List of top-level files for the pages to be inserted
258          @param page_num Position where the new pages should be inserted at.
259                 Negative value means "append" */
260   void         insert_group(const GList<GURL> & furl_list, int page_num=-1,
261                             void (* refresh_cb)(void *)=0, void * cl_data=0);
262      /** Removes the specified page from the document. If #remove_unref#
263          is #TRUE#, the function will also remove from the document any file,
264          which became unreferenced due to the page's removal */
265   void         remove_page(int page_num, bool remove_unref=true);
266      /** Removes the specified pages from the document. If #remove_unref#
267          is #TRUE#, the function will also remove from the document any file,
268          which became unreferenced due to the pages' removal */
269   void         remove_pages(const GList<int> & page_list, bool remove_unref=true);
270      /** Removes a DjVu file with the specified #id#.
271
272          If some other files include this file, the corresponding #INCL#
273          chunks will be removed to avoid dead links.
274
275          If #remove_unref# is #TRUE#, the function will also remove every
276          file, which will become unreferenced after the removal of this file. */
277   void         remove_file(const GUTF8String &id, bool remove_unref=true);
278      /** Makes page number #page_num# to be #new_page_num#. If #new_page_num#
279          is negative or too big, the function will move page #page_num# to
280          the end of the document. */
281   void         move_page(int page_num, int new_page_num);
282      /** Shifts all pags from the #page_list# according to the #shift#.
283          The #shift# can be positive (shift toward the end of the document)
284          or negative (shift toward the beginning of the document).
285
286          It is OK to make #shift# too big in value. Pages will just be
287          moved to the end (or to the beginning, depending on the #shift#
288          sign) of the document. */
289   void         move_pages(const GList<int> & page_list, int shift);
290   
291      /** Changes the name of the file with ID #id# to #name#.
292          Refer to \Ref{DjVmDir} for the explanation of {\em IDs},
293          {\em names} and {\em titles}. */
294   void         set_file_name(const GUTF8String &id, const GUTF8String &name);
295      /** Changes the name of the page #page_num# to #name#.
296          Refer to \Ref{DjVmDir} for the explanation of {\em IDs},
297          {\em names} and {\em titles}. */
298   void         set_page_name(int page_num, const GUTF8String &name);
299      /** Changes the title of the file with ID #id# to #title#.
300          Refer to \Ref{DjVmDir} for the explanation of {\em IDs},
301          {\em names} and {\em titles}. */
302   void         set_file_title(const GUTF8String &id, const GUTF8String &title);
303      /** Changes the title of the page #page_num# to #title#.
304          Refer to \Ref{DjVmDir} for the explanation of {\em IDs},
305          {\em names} and {\em titles}. */
306   void         set_page_title(int page_num, const GUTF8String &title);
307
308      /** @name Thumbnails */
309      //@{
310      /** Returns the number of thumbnails stored inside this document.
311
312          It may be #ZERO#, which means, that there are no thumbnails at all.
313
314          It may be equal to the number of pages, which is what should
315          normally be.
316
317          Finally, it may be greater than #ZERO# and less than the number
318          of pages, in which case thumbnails should be regenerated before
319          the document can be saved. */
320   int          get_thumbnails_num(void) const;
321
322      /** Returns the size of the first encountered thumbnail image. Since
323          thumbnails can currently be generated by \Ref{generate_thumbnails}()
324          only, all thumbnail images should be of the same size. Thus,
325          the number returned is actually the size of {\em all}
326          document thumbnails.
327
328          The function will return #-1# if there are no thumbnails. */
329   int          get_thumbnails_size(void) const;
330
331      /** Removes all thumbnails from the document */
332   void         remove_thumbnails(void);
333
334      /** Generates thumbnails for the specified page, if and only if
335          it does not have a thumbnail yet.  If you want to regenerate
336          thumbnails for all pages, call \Ref{remove_thumbnails}() prior
337          to calling this function.
338
339          @param thumb_size The size of the thumbnails in pixels. DjVu viewer
340                 is able to rescale the thumbnail images if necessary, so this
341                 parameter affects thumbnails quality only. 128 is a good number.
342          @param page_num The page number to genate the thumbnail for.  */
343   int          generate_thumbnails(int thumb_size, int page_num);
344
345      /** Generates thumbnails for those pages, which do not have them yet.
346          If you want to regenerate thumbnails for all pages, call
347          \Ref{remove_thumbnails}() prior to calling this function.
348
349          @param thumb_size The size of the thumbnails in pixels. DjVu viewer
350                 is able to rescale the thumbnail images if necessary, so this
351                 parameter affects thumbnails quality only. 128 is a good number.
352          @param cb The callback, which will be called after thumbnail image
353                 for the next page has been generated. Regardless of if
354                 the document already has thumbnail images for some of its
355                 pages, the callback will be called #pages_num# times, where
356                 #pages_num# is the total number of pages in the document.
357                 The callback should return #FALSE# if thumbnails generating
358                 should proceed. #TRUE# will stop it. */
359   void generate_thumbnails(int thumb_size,
360                            bool (* cb)(int page_num, void *)=0,
361                            void * cl_data=0);
362      //@}
363      /** Use this function to simplify annotations in the document.
364        The "simplified" format is when annotations are only allowed
365        either in top-level page files or in a special file with
366        #SHARED_ANNO# flag on. This file is supposed to be included into
367        every page. */
368   void simplify_anno(void (* progress_cb)(float progress, void *)=0,
369                      void * cl_data=0);
370
371      /** Will create a file that will be included into every page and
372        marked with the #SHARED_ANNO# flag. This file can be used
373        to store global annotations (annotations applicable to every page).
374
375        {\bf Note:} There may be only one #SHARED_ANNO# file in any
376        DjVu multipage document. */
377   void create_shared_anno_file(void (* progress_cb)(float progress, void *)=0,
378                                void * cl_data=0);
379
380      /** Sets bookmark data */
381   void set_djvm_nav(GP<DjVmNav> nav);
382
383      /** Returns a pointer to the file with #SHARED_ANNO# flag on.
384        This file should be used for storing document-wide annotations.
385
386        {\bf Note:} There may be only one #SHARED_ANNO# file in any
387        DjVu multipage document. */
388   GP<DjVuFile>       get_shared_anno_file(void);
389
390   GURL               get_doc_url(void) const;
391                                                                             
392      /** Returns TRUE if #class_name# is #"DjVuDocEditor"#,
393          #"DjVuDocument"# or #"DjVuPort"# */
394   virtual bool         inherits(const GUTF8String &class_name) const;
395   virtual GP<DataPool> request_data(const DjVuPort * source, const GURL & url);
396protected:
397   virtual GP<DjVuFile> url_to_file(const GURL & url, bool dont_create) const;
398   virtual GP<DataPool> get_thumbnail(int page_num, bool dont_decode);
399   friend class CThumbNails;
400public:
401   class File;
402private:
403   bool         initialized;
404   GURL         doc_url;
405   GP<DataPool> doc_pool;
406   int          orig_doc_type;
407   int          orig_doc_pages;
408
409   GPMap<GUTF8String, File>     files_map;      // files_map[id]=GP<File>
410   GCriticalSection     files_lock;
411
412   GPMap<GUTF8String,DataPool> thumb_map;
413   GCriticalSection     thumb_lock;
414
415   void         (* refresh_cb)(void *);
416   void         * refresh_cl_data;
417
418   void         check(void);
419   GUTF8String  find_unique_id(GUTF8String id);
420   GP<DataPool> strip_incl_chunks(const GP<DataPool> & pool);
421   void         clean_files_map(void);
422   bool         insert_file_type(const GURL &file_url,
423                  DjVmDir::File::FILE_TYPE page_type,
424                  int & file_pos,
425                  GMap<GUTF8String, GUTF8String> & name2id);
426   bool         insert_file( const GP<DataPool> &pool,
427                  const GURL &file_url, bool is_page,
428                  int & file_pos,
429                  GMap<GUTF8String,GUTF8String> & name2id,
430                  DjVuPort *source=0 );
431   bool         insert_file(
432                  const GURL &file_url, bool is_page,
433                  int & file_pos,
434                  GMap<GUTF8String,GUTF8String> & name2id,
435                  DjVuPort *source=0 );
436   void         remove_file(const GUTF8String &id, bool remove_unref,
437                            GMap<GUTF8String, void *> & ref_map);
438   void         generate_ref_map(const GP<DjVuFile> & file,
439                                 GMap<GUTF8String, void *> & ref_map,
440                                 GMap<GURL, void *> & visit_map);
441   void         move_file(const GUTF8String &id, int & file_pos,
442                          GMap<GUTF8String, void *> & map);
443   void         unfile_thumbnails(void);
444   void         file_thumbnails(void);
445   void save_file(const GUTF8String &id, const GURL &codebase,
446     const bool only_modified, GMap<GUTF8String, GUTF8String> & map);
447   void save_file(const GUTF8String &id, const GURL &codebase,
448     GMap<GUTF8String, GUTF8String> & map);
449};
450
451//@}
452
453
454#ifdef HAVE_NAMESPACES
455}
456# ifndef NOT_USING_DJVU_NAMESPACE
457using namespace DJVU;
458# endif
459#endif
460#endif
461
Note: See TracBrowser for help on using the repository browser.