source: trunk/libdjvu/DjVuDocEditor.h @ 76

Last change on this file since 76 was 17, checked in by Eugene Romanenko, 16 years ago

update makefiles, remove absolute paths, update djvulibre to version 3.5.17

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