DjVuDocument Class Reference
#include <DjVuDocument.h>
Inheritance diagram for DjVuDocument:
Detailed Description
DjVuDocument# provides convenient interface for opening, decoding and saving back DjVu documents in single page and multi page formats.{ Input formats} It can read multi page DjVu documents in either of the 4 formats: 2 obsolete ({old bundled} and {old indexed}) and two new ({new bundled} and {new indirect}).
{ Output formats} To encourage users to switch to the new formats, the DjVuDocument# can save documents back only in the new formats: {bundled} and {indirect}.
{ Conversion.} Since DjVuDocument# can open DjVu documents in an obsolete format and save it in any of the two new formats ({new bundled} and {new indirect}), this class can be used for conversion from obsolete formats to the new ones. Although it can also do conversion between the new two formats, it's not the best way to do it. Please refer to DjVmDoc} for details.
{ Decoding.} DjVuDocument# provides convenient interface for obtaining DjVuImage} corresponding to any page of the document. It uses DjVuFileCache} to do caching thus avoiding unnecessary multiple decoding of the same page. The real decoding though is accomplished by DjVuFile}.
{ Messenging.} Being derived from DjVuPort}, DjVuDocument# takes an active part in exchanging messages (requests and notifications) between different parties involved in decoding. It reports (relays) errors, progress information and even handles some requests for data (when these requests deal with local files).
Typical usage of DjVuDocument# class in a threadless command line program would be the following: {verbatim} static const char file_name[]="/tmp/document.djvu"; GP<DjVuDocument> doc=DjVuDocumentcreate_wait(file_name); const int pages=doc->get_pages_num(); for(int page=0;page<pages;page++) { GP<DjVuImage> dimg=doc->get_page(page); Do something }; {verbatim}
{ Comments for the code above} {enumerate} Since the document is assumed to be stored on the hard drive, we don't have to cope with DjVuPort}s and can pass ZERO# pointer to the init}() function. DjVuDocument# can access local data itself. In the case of a plugin though, one would have to implement his own DjVuPort}, which would handle requests for data arising when the document is being decoded. In a threaded program instead of calling the init}() function one can call start_init}() and stop_init}() to initiate and interrupt initialization carried out in another thread. This possibility of initializing the document in another thread has been added specially for the plugin because the initialization itself requires data, which is not immediately available in the plugin. Thus, to prevent the main thread from blocking, we perform initialization in a separate thread. To check if the class is completely and successfully initialized, use is_init_ok}(). To see if there was an error, use is_init_failed}(). To know when initialization is over (whether successfully or not), use is_init_complete}(). To wait for this to happen use wait_for_complete_init}(). Once again, all these things are not required for single-threaded program.
Another difference between single-threaded and multi-threaded environments is that in a single-threaded program, the image is fully decoded before it's returned. In a multi-threaded application decoding starts in a separate thread, and the pointer to the DjVuImage} being decoded is returned immediately. This has been done to enable progressive redisplay in the DjVu plugin. Use communication mechanism provided by DjVuPort} and DjVuPortcaster} to learn about progress of decoding. Or try dimg->wait_for_complete_decode()# to wait until the decoding ends. See Also: DjVuFile}, DjVuImage}, GOS}. {enumerate}
{ Initialization} As mentioned above, the DjVuDocument# can go through several stages of initialization. The functionality is gradually added while it passes one stage after another: {enumerate} First of all, immediately after the object is created init}() or start_init}() functions must be called. { Nothing} will work until this is done. init}() function will not return until the initialization is complete. You need to make sure, that enough data is available. { Do not call init}() in the plugin}. start_init}() will start initialization in another thread. Use stop_init}() to interrupt it. Use is_init_complete}() to check the initialization progress. Use wait_for_complete_init}() to wait for init to finish. The first thing the initializing code learns about the document is its type (BUNDLED#, INDIRECT#, OLD_BUNDLED# or OLD_INDEXED#). As soon as it happens, document flags are changed and notify_doc_flags_changed()# request is sent through the communication mechanism provided by DjVuPortcaster}. After the document type becomes known, the initializing code proceeds with learning the document structure. Gradually the flags are updated with values: {itemize} DOC_DIR_KNOWN#: Contents of the document became known. This is meaningful for BUNDLED#, OLD_BUNDLED# and INDIRECT# documents only. DOC_NDIR_KNOWN#: Contents of the document navigation directory became known. This is meaningful for old-style documents (OLD_BUNDLED# and OLD_INDEXED#) only DOC_INIT_OK# or DOC_INIT_FAILED#: The initializating code finished. {itemize} {enumerate}
Definition at line 214 of file DjVuDocument.h.
DjVuDocument.h | |
| Files #"DjVuDocument.h"# and #"DjVuDocument.cpp"# contain implementation of the DjVuDocument} class - the ideal tool for opening, decoding and saving DjVu single page and multi page documents. DjVu document class.
| |
| void | init (const GURL &url, GP< DjVuPort > port=0, DjVuFileCache *cache=0) |
| bool | is_init_complete (void) const |
| bool | is_init_ok (void) const |
| void | set_needs_compression (void) |
| bool | needs_compression (void) const |
| bool | needs_rename (void) const |
| bool | can_compress (void) const |
| bool | is_init_failed (void) const |
| int | get_doc_type (void) const |
| long | get_doc_flags (void) const |
| bool | is_bundled (void) const |
| GURL | get_init_url (void) const |
| GP< DataPool > | get_init_data_pool (void) const |
| DjVuFileCache * | get_cache (void) const |
| GP< DjVmDir > | get_djvm_dir (void) const |
| GP< DjVmNav > | get_djvm_nav (void) const |
| GP< DjVmDir0 > | get_djvm_dir0 (void) const |
| GP< DjVuNavDir > | get_nav_dir (void) const |
| virtual bool | inherits (const GUTF8String &class_name) const |
| virtual void | set_recover_errors (ErrorRecoveryAction=ABORT) |
| virtual void | set_verbose_eof (bool=true) |
| static GP< DjVuDocument > | create (const GURL &url, GP< DjVuPort > xport=0, DjVuFileCache *const xcache=0) |
Public Types | |
| DOC_TYPE_KNOWN = 1 | |
| DOC_DIR_KNOWN = 2 | |
| DOC_NDIR_KNOWN = 4 | |
| DOC_INIT_OK = 8 | |
| DOC_INIT_FAILED = 16 | |
| OLD_BUNDLED = 1 | |
| OLD_INDEXED | |
| BUNDLED | |
| INDIRECT | |
| SINGLE_PAGE | |
| UNKNOWN_TYPE | |
| STARTED = 1 | |
| FINISHED = 2 | |
| enum | DOC_FLAGS { DOC_TYPE_KNOWN = 1, DOC_DIR_KNOWN = 2, DOC_NDIR_KNOWN = 4, DOC_INIT_OK = 8, DOC_INIT_FAILED = 16 } |
| enum | DOC_TYPE { OLD_BUNDLED = 1, OLD_INDEXED, BUNDLED, INDIRECT, SINGLE_PAGE, UNKNOWN_TYPE } |
| enum | THREAD_FLAGS { STARTED = 1, FINISHED = 2 } |
Public Member Functions | |
| virtual | ~DjVuDocument (void) |
| void | start_init (const GURL &url, GP< DjVuPort > port=0, DjVuFileCache *cache=0) |
| void | stop_init (void) |
| GList< GUTF8String > | get_id_list (void) |
| void | map_ids (GMap< GUTF8String, void * > &map) |
| bool | wait_for_complete_init (void) |
| int | wait_get_pages_num (void) const |
| void | writeDjVuXML (const GP< ByteStream > &gstr_out, int flags) const |
| virtual GURL | id_to_url (const DjVuPort *source, const GUTF8String &id) |
| virtual GP< DjVuFile > | id_to_file (const DjVuPort *source, const GUTF8String &id) |
| virtual GP< DataPool > | request_data (const DjVuPort *source, const GURL &url) |
| virtual void | notify_file_flags_changed (const DjVuFile *source, long set_mask, long clr_mask) |
| virtual GList< GURL > | get_url_names (void) |
Accessing pages | |
| int | get_pages_num (void) const |
| GURL | page_to_url (int page_num) const |
| GUTF8String | page_to_id (int page_num) const |
| int | url_to_page (const GURL &url) const |
| GUTF8String | url_to_id (const GURL &url) const |
| GURL | id_to_url (const GUTF8String &id) const |
| int | id_to_page (const GUTF8String &id) const |
| GP< DjVuImage > | get_page (int page_num, bool sync=true, DjVuPort *port=0) const |
| GP< DjVuImage > | get_page (int page_num, bool sync=true, DjVuPort *port=0) |
| GP< DjVuImage > | get_page (const GUTF8String &id, bool sync=true, DjVuPort *port=0) |
| GP< DjVuFile > | get_djvu_file (int page_num, bool dont_create=false) const |
| GP< DjVuFile > | get_djvu_file (int page_num, bool dont_create=false) |
| GP< DjVuFile > | get_djvu_file (const GUTF8String &id, bool dont_create=false) |
| GP< DjVuFile > | get_djvu_file (const GURL &url, bool dont_create=false) |
| virtual GP< DataPool > | get_thumbnail (int page_num, bool dont_decode) |
| float | get_thumbnails_gamma (void) const |
Saving document to disk | |
| GP< DjVmDoc > | get_djvm_doc (void) |
| virtual void | write (const GP< ByteStream > &str, bool force_djvm=false) |
| virtual void | write (const GP< ByteStream > &str, const GMap< GUTF8String, void * > &reserved) |
| void | expand (const GURL &codebase, const GUTF8String &idx_name) |
| virtual void | save_as (const GURL &where, const bool bundled=0) |
Static Public Member Functions | |
| static GP< DjVuDocument > | create_noinit (void) |
| static GP< DjVuDocument > | create_wait (const GURL &url, GP< DjVuPort > xport=0, DjVuFileCache *const xcache=0) |
| static GP< DjVuDocument > | create (GP< DataPool > pool, GP< DjVuPort > xport=0, DjVuFileCache *const xcache=0) |
| static GP< DjVuDocument > | create (const GP< ByteStream > &bs, GP< DjVuPort > xport=0, DjVuFileCache *const xcache=0) |
| static void | set_compress_codec (void(*codec)(GP< ByteStream > &, const GURL &where, bool bundled)) |
| static void | set_import_codec (void(*codec)(GP< DataPool > &, const GURL &url, bool &, bool &)) |
Protected Member Functions | |
| DjVuDocument (void) | |
| virtual GP< DjVuFile > | url_to_file (const GURL &url, bool dont_create=false) const |
| void | init_thread (void) |
| void | check () const |
| void | process_threqs (void) |
| GP< ThumbReq > | add_thumb_req (const GP< ThumbReq > &thumb_req) |
| void | add_to_cache (const GP< DjVuFile > &f) |
| void | check_unnamed_files (void) |
| GUTF8String | get_int_prefix (void) const |
| void | set_file_aliases (const DjVuFile *file) |
| GURL | invent_url (const GUTF8String &name) const |
Static Protected Member Functions | |
| static void | static_init_thread (void *) |
Protected Attributes | |
| GURL | init_url |
| GP< DataPool > | init_data_pool |
| GP< DjVmDir > | djvm_dir |
| GP< DjVmNav > | djvm_nav |
| int | doc_type |
| bool | needs_compression_flag |
| bool | can_compress_flag |
| bool | needs_rename_flag |
| bool | has_url_names |
| GCriticalSection | url_names_lock |
| GList< GURL > | url_names |
| ErrorRecoveryAction | recover_errors |
| bool | verbose_eof |
| bool | init_started |
| GSafeFlags | flags |
| GSafeFlags | init_thread_flags |
| DjVuFileCache * | cache |
| GP< DjVuSimplePort > | simple_port |
| GP< DjVmDir0 > | djvm_dir0 |
| GP< DjVuNavDir > | ndir |
| GUTF8String | first_page_name |
| GP< DjVuFile > | ndir_file |
| GPList< UnnamedFile > | ufiles_list |
| GCriticalSection | ufiles_lock |
| GPList< ThumbReq > | threqs_list |
| GCriticalSection | threqs_lock |
| GP< DjVuDocument > | init_life_saver |
| GThread | init_thr |
Static Protected Attributes | |
| static void(* | djvu_import_codec )(GP< DataPool > &pool, const GURL &url, bool &needs_compression, bool &needs_rename) |
| static void(* | djvu_compress_codec )(GP< ByteStream > &bs, const GURL &where, bool bundled) |
| static const float | thumb_gamma = (float)2.20 |
Classes | |
| class | ThumbReq |
| class | UnnamedFile |
Member Enumeration Documentation
Flags describing the document initialization state.
{itemize} DOC_TYPE_KNOWN#: The type of the document has been learnt. DOC_DIR_KNOWN#: Contents of the document became known. This is meaningful for BUNDLED#, OLD_BUNDLED# and INDIRECT# documents only. DOC_NDIR_KNOWN#: Contents of the document navigation directory became known. This is meaningful for old-style documents (OLD_BUNDLED# and OLD_INDEXED#) only DOC_INIT_OK#: The initialization has completed successfully. DOC_INIT_FAILED#: The initialization failed. {itemize}
Definition at line 229 of file DjVuDocument.h.
Specifies the format of DjVuDocument#.
There are currently 4 DjVu multipage formats recognized by the library. Two of them are obsolete and should not be used. {enumerate} OLD_BUNDLED# - Obsolete bundled format OLD_INDEXED# - Obsolete multipage format where every page is stored in a separate file and "includes" (by means of an INCL# chunk) the file with the document directory. SINGLE_PAGE# - Single page document. Basically a file with either FORM:DJVU# or FORM:IW44# and no multipage information. For example, OLD_INDEXED# documents with document directory do not qualify even if they contain only one page. BUNDLED# - Currently supported bundled format INDIRECT# - Currently supported "expanded" format, where every page and component is stored in a separate file. There is also a {top-level} file with the document directory. {enumerate}
Definition at line 250 of file DjVuDocument.h.
Constructor & Destructor Documentation
| DjVuDocument::DjVuDocument | ( | void | ) | [protected] |
Default creator.
Please call functions init}() or start_init}() before you start working with the DjVuDocument#.
Definition at line 114 of file DjVuDocument.cpp.
| DjVuDocument::~DjVuDocument | ( | void | ) | [virtual] |
Member Function Documentation
| bool DjVuDocument::can_compress | ( | void | ) | const [inline] |
Returns TRUE# if this file must be renamed before saving.
Definition at line 967 of file DjVuDocument.h.
| GP< DjVuDocument > DjVuDocument::create | ( | const GP< ByteStream > & | bs, | |
| GP< DjVuPort > | xport = 0, |
|||
| DjVuFileCache *const | xcache = 0 | |||
| ) | [static] |
Create a version of DjVuDocument which has begun initializing.
Definition at line 139 of file DjVuDocument.cpp.
| GP< DjVuDocument > DjVuDocument::create | ( | GP< DataPool > | pool, | |
| GP< DjVuPort > | xport = 0, |
|||
| DjVuFileCache *const | xcache = 0 | |||
| ) | [static] |
Create a version of DjVuDocument which has begun initializing.
Definition at line 128 of file DjVuDocument.cpp.
| GP< DjVuDocument > DjVuDocument::create | ( | const GURL & | url, | |
| GP< DjVuPort > | xport = 0, |
|||
| DjVuFileCache *const | xcache = 0 | |||
| ) | [inline, static] |
Create a version of DjVuDocument which has begun initializing.
Definition at line 927 of file DjVuDocument.h.
| static GP<DjVuDocument> DjVuDocument::create_noinit | ( | void | ) | [inline, static] |
| GP< DjVuDocument > DjVuDocument::create_wait | ( | const GURL & | url, | |
| GP< DjVuPort > | xport = 0, |
|||
| DjVuFileCache *const | xcache = 0 | |||
| ) | [static] |
Create a version of DjVuDocument which has finished initializing.
Definition at line 146 of file DjVuDocument.cpp.
| void DjVuDocument::expand | ( | const GURL & | codebase, | |
| const GUTF8String & | idx_name | |||
| ) |
Saves the document in the {new indirect} format when every page and component are stored in separate files.
This format is ideal for web publishing because it allows direct access to any page and component. In addition to it, a top-level file containing the list of all components will be created. To view the document later in the plugin or in the viewer one should load the top-level file.
{ Plugin Warning}. This function will read contents of the whole document. Thus, if you call it from the main thread (the thread, which transfers data from Netscape), the plugin will block.
- Parameters:
-
codebase - Name of the directory which the document should be expanded into. idx_name - Name of the top-level file containing the document directory (basically, list of all files composing the document).
Definition at line 1778 of file DjVuDocument.cpp.
| DjVuFileCache * DjVuDocument::get_cache | ( | void | ) | const [inline] |
Returns pointer to the internal directory of the document, if it is in one of the new formats: BUNDLED# or INDIRECT#.
Otherwise (if the format of the input document is obsolete), ZERO# is returned.
ZERO# will also be returned if the initializing thread has not learnt enough information about the document (DOC_DIR_KNOWN# has not been set yet). Check is_init_complete}() and init}() for details.
Definition at line 1019 of file DjVuDocument.h.
Returns pointer to the internal directory of the document, if it is in obsolete OLD_BUNDLED# format.
ZERO# will also be returned if the initializing thread has not learnt enough information about the document (DOC_DIR_KNOWN# has not been set yet). Check is_init_complete}() and init}() for details.
Definition at line 1037 of file DjVuDocument.h.
Returns pointer to the DjVmDoc} class, which can save the document contents on the hard disk in one of the two new formats: {bundled} and {indirect}.
You may also want to look at write}() and expand}() if you are interested in how to save the document.
{ Plugin Warning}. This function will read contents of the whole document. Thus, if you call it from the main thread (the thread, which transfers data from Netscape), the plugin will block.
Definition at line 1665 of file DjVuDocument.cpp.
Returns pointer to the document bookmarks.
This applies to BUNDLED# and INDIRECT# documents.
ZERO# will also be returned if the initializing thread has not learnt enough information about the document (DOC_DIR_KNOWN# has not been set yet). Check is_init_complete}() and init}() for details.
Definition at line 1029 of file DjVuDocument.h.
| GP< DjVuFile > DjVuDocument::get_djvu_file | ( | const GUTF8String & | id, | |
| bool | dont_create = false | |||
| ) |
Returns DjVuFile} corresponding to the specified ID.
This function behaves exactly as the get_djvu_file()# function above. The only thing worth mentioning here is how the ID# parameter is treated.
First off, id_to_url}() is called. If not successfull, the function checks, if the ID contains a number. If so, it just calls the get_djvu_file()# function above. If ID is ZERO# or just empty, page number #-1# is assumed.
If dont_create# is FALSE# the function will return the file only if it already exists.
Definition at line 958 of file DjVuDocument.cpp.
Returns DjVuFile} corresponding to the specified page.
Normally it translates the page number to the URL using page_to_url}() and then creates DjVuFile} initializing it with data from the URL.
The behavior becomes different, though in the case when the document structure is unknown at the moment this function is called. In this situations it invents a temporary URL, creates a DjVuFile}, initializes it with this URL and returns immediately. The caller may start decoding the file right away (if necessary). The decoding will block but will automatically continue as soon as enough information is collected about the document. This trick should be quite transparent to the user and helps to prevent the main thread from blocking. The decoding will unblock and this function will stop using this "trick" as soon as DjVuDocument# passes some given stages of initialization and page_to_url}(), id_to_url}() functions start working properly.
If dont_create# is FALSE# the function will return the file only if it already exists.
{ Note:} To wait for the initialization to complete use wait_for_complete_init}(). For single threaded applications the initialization completes before the init}() function returns.
Definition at line 879 of file DjVuDocument.cpp.
| long DjVuDocument::get_doc_flags | ( | void | ) | const [inline] |
Returns the document flags.
The flags describe the degree in which the DjVuDocument# object is initialized. Every time the flags are changed, a notify_doc_flags_changed()# notification is distributed using the DjVuPortcaster} communication mechanism.
{ Note:} To wait for the initialization to complete use wait_for_complete_init}(). For single threaded applications the initialization completes before the init}() function returns.
Definition at line 982 of file DjVuDocument.h.
| int DjVuDocument::get_doc_type | ( | void | ) | const [inline] |
If the document has already learnt its type, the function will returns it: DjVuDocument::OLD_BUNDLED# or DjVuDocument::OLD_INDEXED# or DjVuDocument::SINGLE_PAGE# or DjVuDocument:BUNDLED# or DjVuDocument::INDIRECT#.
The first two formats are obsolete. Otherwise (if the type is unknown yet), UNKNOWN_TYPE# will be returned.
{ Note:} To check the stage of the document initialization use get_flags}() or is_init_complete}() functions. To wait for the initialization to complete use wait_for_complete_init}(). For single threaded applications the initialization completes before the init}() function returns.
Definition at line 979 of file DjVuDocument.h.
| GList< GUTF8String > DjVuDocument::get_id_list | ( | void | ) |
Returns data corresponding to the URL passed to the init}() function.
{ Note:} The pointer returned is guaranteed to be non-ZERO# only after the DjVuDocument# learns its type (passes through the first stage of initialization process). Please refer to init}() for details.
Definition at line 994 of file DjVuDocument.h.
| GURL DjVuDocument::get_init_url | ( | void | ) | const [inline] |
| GP< DjVuNavDir > DjVuDocument::get_nav_dir | ( | void | ) | const [inline] |
Returns pointer to {navigation directory} of the document.
The navigation directory is a DjVu file containing only one chunk NDIR# inside a FORM:DJVI# with the list of all document pages.
Definition at line 1045 of file DjVuDocument.h.
| GP< DjVuImage > DjVuDocument::get_page | ( | const GUTF8String & | id, | |
| bool | sync = true, |
|||
| DjVuPort * | port = 0 | |||
| ) |
Returns GP} pointer to DjVuImage} corresponding to the specified ID.
This function behaves exactly as the get_page()# function above. The only thing worth mentioning here is how the ID# parameter is treated.
First of all the function checks, if the ID contains a number. If so, it just calls the get_page()# function above. If ID is ZERO# or just empty, page number #-1# is assumed. Otherwise the ID is translated to the URL using id_to_url}().
Definition at line 1058 of file DjVuDocument.cpp.
| GP< DjVuImage > DjVuDocument::get_page | ( | int | page_num, | |
| bool | sync = true, |
|||
| DjVuPort * | port = 0 | |||
| ) | const |
Returns GP} pointer to DjVuImage} corresponding to page page_num#.
If caching is enabled, and there is a {fully decoded} DjVuFile} in the cache, the image will be reused and will be returned fully decoded. Otherwise, if multi-threaded behavior is allowed, and sync# is set to FALSE#, the decoding will be started in a separate thread, which enables to do progressive redisplay. Thus, in this case the image returned may be partially decoded.
Negative page_num# has a special meaning for the {old indexed} multipage documents: the DjVuDocument# will start decoding of the URL with which it has been initialized. For other formats page #-1# is the same as page #0#.
DjVuDocument# can also connect the created page to the specified port# {before starting decoding}. This option will allow the future owner of DjVuImage} to receive all messages and requests generated during its decoding.
If this function is called before the document's structure becomes known (the initialization process completes), the DjVuFile}, which the returned image will be attached to, will be assigned a temporary artificial URL, which will be corrected as soon as enough information becomes available. The trick prevents the main thread from blocking and in some cases helps to start decoding earlier. The URL is corrected and decoding will start as soon as DjVuDocument# passes some given stages of initialization and page_to_url}(), id_to_url}() functions start working properly. Please look through their description for details.
{ Note:} To wait for the initialization to complete use wait_for_complete_init}(). For single threaded applications the initialization completes before the init}() function returns.
- Parameters:
-
page_num Number of the page to be decoded sync When set to TRUE# the function will not return until the page is completely decoded. Otherwise, in a multi-threaded program, this function will start decoding in a new thread and will return a partially decoded image. Refer to DjVuImage::wait_for_complete_decode}() and DjVuFile::is_decode_ok}(). port A pointer to DjVuPort}, that the created image will be connected to.
Definition at line 1036 of file DjVuDocument.cpp.
| int DjVuDocument::get_pages_num | ( | void | ) | const |
Returns the number of pages in the document.
If there is still insufficient information about the document structure (initialization has not finished yet), #1# will be returned. Please refer to init}() for details.
Definition at line 658 of file DjVuDocument.cpp.
Returns a DataPool} containing one chunk TH44# with the encoded thumbnail for the specified page.
The function first looks for thumbnails enclosed into the document and if it fails to find one, it decodes the required page and creates the thumbnail on the fly (unless dont_decode# is true).
{ Note:} It may happen that the returned DataPool} will not contain all the data you need. In this case you will need to install a trigger into the DataPool} to learn when the data actually arrives.
Reimplemented in DjVuDocEditor.
Definition at line 1278 of file DjVuDocument.cpp.
| GP< DjVuFile > DjVuDocument::id_to_file | ( | const DjVuPort * | source, | |
| const GUTF8String & | id | |||
| ) | [virtual] |
This request is used to get a file corresponding to the given ID.
DjVuDocument} is supposed to intercept it and either create a new instance of DjVuFile} or reuse an existing one from the cache.
Reimplemented from DjVuPort.
Definition at line 1422 of file DjVuDocument.cpp.
| int DjVuDocument::id_to_page | ( | const GUTF8String & | id | ) | const [inline] |
| GURL DjVuDocument::id_to_url | ( | const DjVuPort * | source, | |
| const GUTF8String & | id | |||
| ) | [virtual] |
Converts the specified id to a URL.
Reimplemented from DjVuPort.
Definition at line 829 of file DjVuDocument.cpp.
| GURL DjVuDocument::id_to_url | ( | const GUTF8String & | id | ) | const |
Translates the textual ID to the complete URL if possible.
Depending on the document format the translation is done in the following way: {itemize} For BUNDLED# and INDIRECT# documents the function scans the DjVmDir} (the document directory) and matches the ID against: {enumerate} File ID from the DjVmDir} File name from the DjVmDir} File title from the DjVmDir} {enumerate} Then for BUNDLED# document the URL is obtained by appending the name# of the found file to the document's URL.
For INDIRECT# documents the URL is obtained by appending the name# of the found file to the URL of the directory containing the document. For OLD_BUNDLED# documents the function compares the ID with internal name of every file inside the bundle and composes an artificial URL by appending the file name to the document's URL. For OLD_INDEXED# or SINGLE_PAGE# documents the function composes the URL by appending the ID to the URL of the directory containing the document. {itemize}
If information obtained by the initialization thread is not sufficient yet, the id_to_url()# may return an empty URL. Depending on the document type, the information is sufficient when {itemize} BUNDLED# and INDIRECT#: DOC_DIR_KNOWN# flag is set. OLD_BUNDLED# and OLD_INDEXED# and SINGLE_PAGE#: DOC_TYPE_KNOWN# flag is set. {itemize}
Definition at line 775 of file DjVuDocument.cpp.
| bool DjVuDocument::inherits | ( | const GUTF8String & | class_name | ) | const [inline, virtual] |
Returns TRUE if class_name# is #"DjVuDocument"# or #"DjVuPort"#.
Reimplemented from DjVuPort.
Reimplemented in DjVuDocEditor.
Definition at line 997 of file DjVuDocument.h.
| void DjVuDocument::init | ( | const GURL & | url, | |
| GP< DjVuPort > | port = 0, |
|||
| DjVuFileCache * | cache = 0 | |||
| ) | [inline] |
Initializes the document.
Contrary to start_init}(), which just starts the initialization thread in a multi-threaded environment, this function does not return until the initialization completes (either successfully or not). Basically, it calls start_init}() and then wait_for_complete_init}().
Definition at line 920 of file DjVuDocument.h.
| bool DjVuDocument::is_bundled | ( | void | ) | const [inline] |
Returns TRUE# if the document is in bundled format (either in DjVuDocument::OLD_BUNDLED# or DjVuDocument::BUNDLED# formats).
Definition at line 985 of file DjVuDocument.h.
| bool DjVuDocument::is_init_complete | ( | void | ) | const [inline] |
Returns TRUE# if the initialization thread finished (does not matter successfully or not).
As soon as it happens, the document becomes completely initialized and its every function should work properly. Please refer to the description of init}() function and of the DjVuDocument# class to learn about the initializing stages.
To wait for the initialization to complete use wait_for_complete_init}() function.
To query the initialization stage use get_flags}() function.
To learn whether initialization was successful or not, use is_init_ok}() and is_init_failed}().
{ Note:} In a single threaded application the initialization completes before the init}() function returns.
Definition at line 937 of file DjVuDocument.h.
| bool DjVuDocument::is_init_failed | ( | void | ) | const [inline] |
Returns TRUE# is the initialization thread failed.
See is_init_complete}() and wait_for_complete_init}() for more details.
Definition at line 973 of file DjVuDocument.h.
| bool DjVuDocument::is_init_ok | ( | void | ) | const [inline] |
Returns TRUE# is the initialization thread finished successfully.
See is_init_complete}() and wait_for_complete_init}() for more details.
Definition at line 943 of file DjVuDocument.h.
| void DjVuDocument::map_ids | ( | GMap< GUTF8String, void * > & | map | ) |
| bool DjVuDocument::needs_compression | ( | void | ) | const [inline] |
Returns TRUE# if there are uncompressed pages in this document.
Definition at line 955 of file DjVuDocument.h.
| bool DjVuDocument::needs_rename | ( | void | ) | const [inline] |
Returns TRUE# if this file must be renamed before saving.
Definition at line 961 of file DjVuDocument.h.
| GUTF8String DjVuDocument::page_to_id | ( | int | page_num | ) | const [inline] |
Tranlate the page number to id...
Reimplemented in DjVuDocEditor.
Definition at line 500 of file DjVuDocument.h.
| GURL DjVuDocument::page_to_url | ( | int | page_num | ) | const |
Translates the page number to the full URL of the page.
This URL is "artificial" for the {bundled} formats and is obtained by appending the page name to the document's URL honoring possible #;# and #?# in it. Negative page number has a special meaning for OLD_INDEXED# documents: it points to the URL, which the DjVuDocument# has been initialized with. For other formats this is the same as page #0#.
The function tries it best to map the page number to the URL. Although, if the document structure has not been fully discovered yet, an empty URL will be returned. Use wait_for_complete_init}() to wait until the document initialization completes. Refer to init}() for details.
Depending on the document format, the function assumes, that there is enough information to complete the request when: {itemize} OLD_INDEXED#: If page_num<0#, DOC_TYPE_KNOWN# flag must be set. Otherwise DOC_NDIR_KNOWN# must be set. OLD_BUNDLED#: If page_num=0#, DOC_DIR_KNOWN# flag must be set. Otherwise DOC_NDIR_KNOWN# flag must be set. INDIRECT# and BUNDLED#: DOC_DIR_KNOWN# flag must be set. {itemize}
Definition at line 670 of file DjVuDocument.cpp.
This request is issued when decoder needs additional data for decoding.
Both DjVuFile} and DjVuDocument} are initialized with a URL, not the document data. As soon as they need the data, they call this function, whose responsibility is to locate the source of the data basing on the URL# passed and return it back in the form of the DataPool}. If this particular receiver is unable to fullfil the request, it should return #0#.
Reimplemented from DjVuPort.
Reimplemented in DjVuDocEditor.
Definition at line 1428 of file DjVuDocument.cpp.
| void DjVuDocument::save_as | ( | const GURL & | where, | |
| const bool | bundled = 0 | |||
| ) | [virtual] |
This function can be used instead of write}() and expand}().
It allows to save the document either in the new BUNDLED# format or in the new INDIRECT# format depending on the value of parameter bundled#.
Depending on the document's type, the meaning of where# is: {itemize} For BUNDLED# documents this is the name of the file For INDIRECT# documents this is the name of top-level index file. All document files will be saved into the save directory where the index file will resize.
Reimplemented in DjVuDocEditor.
Definition at line 1788 of file DjVuDocument.cpp.
| void DjVuDocument::set_needs_compression | ( | void | ) | [inline] |
| void DjVuDocument::start_init | ( | const GURL & | url, | |
| GP< DjVuPort > | port = 0, |
|||
| DjVuFileCache * | cache = 0 | |||
| ) |
Initializes the DjVuDocument# object using an existing document.
This function should be called once after creating the object. The url# should point to the real data, and the creator of the document should be ready to return this data to the document if it's not stored locally (in which case DjVuDocument# can access it itself).
{ Initializing thread} In a single-threaded application, the start_init()# function performs the complete initialization of the DjVuDocument</