#include <DLPage.h>
Public Types | |
typedef std::list< DLZone * >::iterator | DLZonePtrIterator |
Public Member Functions | |
DLZonePtrIterator | begin () |
DLZonePtrIterator | end () |
bool | dlIsZoneIteratorValid (DLZonePtrIterator zoneIter) |
DLPage () | |
DLPage (const DLImage &pageImage, const string &pageID) | |
DLPage (const DLPage &right) | |
virtual | ~DLPage () |
bool | operator== (const DLPage &right) |
DLPage & | operator= (const DLPage &right) |
string | dlGetPageID () const |
void | dlSetPageID (const string &pgID) |
int | dlGetPageWidth () const |
int | dlGetPageHeight () const |
int | dlGetNumZones () const |
bool | dlHasZones () const |
void | dlAppendZone (DLZone *pageZone) |
void | dlAppendZoneCopy (const DLZone &pageZone) |
void | dlAppendZoneList (list< DLZone * > zoneList) |
void | dlInsertZone (DLZonePtrIterator zoneIter, DLZone *pageZone) |
void | dlInsertZone (int cursorPosition, DLZone *pageZone) |
void | dlInsertZoneCopy (DLZonePtrIterator zoneIter, const DLZone &pageZone) |
void | dlInsertZoneCopy (int cursorPosition, const DLZone &pageZone) |
void | dlInsertZoneList (DLZonePtrIterator zoneIter, list< DLZone * > zoneList) |
void | dlInsertZoneList (int cursorPosition, list< DLZone * > zoneList) |
void | dlDeleteZone (DLZonePtrIterator zoneIter) |
void | dlDeleteZone (int cursorPosition) |
void | dlDeleteZone (DLZone *deletedZone) |
void | dlClearZones () |
DLImage | dlGetImage () |
bool | dlCheckPageImageData () |
Tag List Functions | |
string | dlGetTag (string tagKey) const |
void | dlSetTag (string tagKey, string tagValue, bool overwriteEnabled=false) |
void | dlDeleteTag (string tagKey) |
void | dlClearTags () |
bool | dlIsTagSet (string tagKey) const |
bool | dlIsTagListEmpty () const |
DLTagList::iterator | dlFindTag (string tagKey) |
Protected Member Functions | |
DLPage * | dlClone () |
void | dlSetDocumentPointer (DLDocument *pgDocument) |
Protected Attributes | |
string | pageID |
DLImage | pageImage |
DLDocument * | pageDocument |
DLTagList | pageTags |
list< DLZone * > | pageZones |
list< DLZone * > | zoneBackPointers |
In the DOCLIB document hierarchy, the DLPage class is below DLDocument and above DLZone. Its main purpose is to accommodate information specific to pages rather than whole documents. The structure of DLPage, however, is similar to DLDocument. It also contains a page ID and a dynamic tag list the developer can use to store self-defined attributes. The main difference from the DLDocument class is a list of DLZones, which are basically bounding boxes defining specific regions on a page. Following the implementation of DLDocument, DLPage provides different functions for appending, inserting, or deleting zones on a page. In addition, it provides methods for accessing page information, e.g. width, height, or number of zones. In particular, each page object provides a method for returning its image as a DLImage object.
Each DLPage object keeps track of two kinds of DLZone objects associated with it -- zones on the DLPage, and zones that point to the DLPage (which get created when copies of DLZones are made). Programmers can traverse through the zones on a page using DLZonePtrIterator as below:
// ... pgPointer is a DLPage* to a page already populated with zones DLPage::DLZonePtrIterator zoneIterator; for (zoneIterator = pgPointer->begin(); zoneIterator != pgPointer->end(); zoneIterator++) { cout << (*zoneIterator)->dlGetZoneID() << endl; }
Upon its destruction, the DLPage deletes all zones on the DLPage. Furthermore, if there exist dangling zones that still point to the DLPage, the DLPage* on these zones will be set to NULL
, as the DLPage does not exist any more.
It is advisable for programmers to use new
operator to dynamically allocate memory space when constructing DLPages and DLZones. The object destructors of DLDocument, DLPage, and DLZone will release the allocated memory space of associated objects (i.e. all objects below the current object in the DLDocument hierarchy.) However, if you use the new
operator to dynamically create an stand-alone object, you will need to use the delete
operator to reclaim the memory space it occupies.
Definition at line 61 of file DLPage.h.
typedef std::list<DLZone*>::iterator DLPage::DLZonePtrIterator |
DLPage::DLPage | ( | ) |
DLPage Constructor
DLPage::DLPage | ( | const DLImage & | pageImage, | |
const string & | pageID | |||
) |
DLPage::DLPage | ( | const DLPage & | right | ) |
DLPage Copy Constructor: all the DLZones on the page will also be copied over to the DLPage copy. The DLPage copy points to the same DLDocument as the source DLPage. The parent DLDocument does not include this DLPage copy in the list of DLPages that it owns; however, it maintains a reference to the new DLPage in its list of backpointers so that it can notify the new DLPage to remove its parent DLDocument reference when it is destroyed.
The DLPage copy has a zone hierarchy identical to the source DLPage, in which each zone is a new object. As DLPage copy is NOT simply the default member-wise copy; it will not result in the accidental destruction of page zones when the destructor of the DLPage copy is invoked.
virtual DLPage::~DLPage | ( | ) | [virtual] |
Default DLPage Destructor
DLZonePtrIterator DLPage::begin | ( | ) | [inline] |
DLZonePtrIterator DLPage::end | ( | ) | [inline] |
Obtain an iterator that addresses the location succeeding the last DLZone* in the page. The end() iterator is typically used in a for
loop for bounds checking (see the example in the class introduction above). Warning: dereferencing the end() iterator is undefined, and will likely cause your program to crash.
Definition at line 90 of file DLPage.h.
References pageZones.
bool DLPage::dlIsZoneIteratorValid | ( | DLZonePtrIterator | zoneIter | ) |
bool DLPage::operator== | ( | const DLPage & | right | ) |
Equality operator.
DLPage Copy Assignment operator: all the DLZones on the page will be copied over to the DLPage copy. The parent DLDocument does not include this DLPage copy in the list of DLPages that it owns; however, it maintains a reference to the new DLPage in its list of backpointers so that it can notify the new DLPage to remove its parent DLDocument reference when it is destroyed.
The DLPage copy has a zone hierarchy identical to the source DLPage, in which each zone is a new object. As DLPage copy is NOT simply the default member-wise copy, it will not result in the accidental destruction of page zones when the destructor of the DLPage copy is invoked
string DLPage::dlGetPageID | ( | ) | const [inline] |
void DLPage::dlSetPageID | ( | const string & | pgID | ) | [inline] |
int DLPage::dlGetPageWidth | ( | ) | const [inline] |
Get page width
Definition at line 168 of file DLPage.h.
References DLImage::dlGetWidth(), and pageImage.
int DLPage::dlGetPageHeight | ( | ) | const [inline] |
Get page height
Definition at line 174 of file DLPage.h.
References DLImage::dlGetHeight(), and pageImage.
int DLPage::dlGetNumZones | ( | ) | const [inline] |
bool DLPage::dlHasZones | ( | ) | const [inline] |
void DLPage::dlAppendZone | ( | DLZone * | pageZone | ) |
Append a new zone to the page at the end of the current list of zones. The DLPage object takes responsibility for freeing the memory occupied by pageZone. Therefore, typically pageZone should have been allocated on the heap using new
. Taking the address of a DLZone stack object for appending should be done with care, since the object is automatically destroyed when it goes out of scope, potentially causing a dangling pointer within the document. In this situation, consider using dlAppendZoneCopy() instead.
pageZone | new zone to be appended |
void DLPage::dlAppendZoneCopy | ( | const DLZone & | pageZone | ) |
Append a copy of the new zone to the page at the end of the current list of zones.
pageZone | new zone to be appended |
void DLPage::dlAppendZoneList | ( | list< DLZone * > | zoneList | ) |
void DLPage::dlInsertZone | ( | DLZonePtrIterator | zoneIter, | |
DLZone * | pageZone | |||
) |
Insert a new zone to the page at the specified iterator position of the current list. The DLPage object takes responsibility for freeing the memory occupied by pageZone. See dlInsertZoneCopy() for inserting a stack DLZone object as a child zone.
zoneIter | iterator position in the current zone list where the new zone is to be inserted | |
pageZone | new DLZone to be inserted |
void DLPage::dlInsertZone | ( | int | cursorPosition, | |
DLZone * | pageZone | |||
) |
Insert a new zone to the page at the specified position of the current list. The DLPage object takes responsibility for freeing the memory occupied by pageZone. See dlInsertZoneCopy() for inserting a stack DLZone object as a child zone.
cursorPosition | cursor position in the current zone list where the new zone is to be inserted. cursorPosition must be between 0 (beginning of the list) and the number of zones currently on the list (end of the list) | |
pageZone | new DLZone to be inserted |
void DLPage::dlInsertZoneCopy | ( | DLZonePtrIterator | zoneIter, | |
const DLZone & | pageZone | |||
) |
Insert a copy of the new zone to the page at the specified iterator position of the current list.
zoneIter | iterator position in the current zone list where the new zone is to be inserted | |
pageZone | DLZone to be copied and inserted |
void DLPage::dlInsertZoneCopy | ( | int | cursorPosition, | |
const DLZone & | pageZone | |||
) |
Insert a copy of the new zone to the page at the specified position of the current list.
cursorPosition | cursor position in the current zone list where the new zone is to be inserted. cursorPosition must be between 0 (beginning of the list) and the number of zones currently on the list (end of the list) | |
pageZone | DLZone to be copied and inserted |
void DLPage::dlInsertZoneList | ( | DLZonePtrIterator | zoneIter, | |
list< DLZone * > | zoneList | |||
) |
Insert a list of new zones into the page starting from the specified position in the current list. The DLPage object takes responsibility for freeing the memory occupied by the DLZones in zoneList.
zoneIter | iterator position in the current zone list where the new zones are to be inserted | |
zoneList | list of new DLZones to be inserted at the specified cursor position in the current list |
void DLPage::dlInsertZoneList | ( | int | cursorPosition, | |
list< DLZone * > | zoneList | |||
) |
Insert a list of new zones to the page starting from the specified position in the current list. The DLPage object takes responsibility for freeing the memory occupied by the DLZones in zoneList.
cursorPosition | position in the current zone list where the new zones are to be inserted. cursorPosition must be between 0 (beginning of the list) and the number of zones currently on the list (end of the list) | |
zoneList | list of new DLZones to be inserted at the specified cursor position in the current list |
void DLPage::dlDeleteZone | ( | DLZonePtrIterator | zoneIter | ) |
Delete a specific zone from the page at the given iterator position
zoneIter | DLZonePtrIterator of the zone to be deleted |
void DLPage::dlDeleteZone | ( | int | cursorPosition | ) |
Delete a zone at a given position from the page
cursorPosition | position of the zone to be removed from the zone list; 0 indicates the first zone, 1 indicates the second zone, and so on. |
void DLPage::dlDeleteZone | ( | DLZone * | deletedZone | ) |
Delete a specific zone from the page
deletedZone | zone to be deleted |
void DLPage::dlClearZones | ( | ) |
Clear the list of zones in the page
DLImage DLPage::dlGetImage | ( | ) | [inline] |
bool DLPage::dlCheckPageImageData | ( | ) |
Check whether the page image has been initialized
string DLPage::dlGetTag | ( | string | tagKey | ) | const |
Get the field value of a specified page tag
tagKey | key of the specified page tag |
void DLPage::dlSetTag | ( | string | tagKey, | |
string | tagValue, | |||
bool | overwriteEnabled = false | |||
) |
Set a page tag. If a tag with the specified key already exists in this page, it will not be overwritten unless the optional parameter overwriteEnabled is set to true
. Will throw a DLException if overwriteEnabled is set to false
and tagKey exists.
tagKey | key of the document tag | |
tagValue | value of the document tag | |
overwriteEnabled | option for overwriting existing field (default is false ) |
DL_Exception | DL_UNKNOWN_TAG_EXCEPTION |
void DLPage::dlDeleteTag | ( | string | tagKey | ) |
Remove the tag with the specified key from the list of page tags.
tagKey | key of the page tag |
void DLPage::dlClearTags | ( | ) | [inline] |
Erase all the existing page tags
Definition at line 340 of file DLPage.h.
References pageTags, and DLTagList::tagMap.
bool DLPage::dlIsTagSet | ( | string | tagKey | ) | const |
Check whether a document tag with the given key exists
tagKey | key of the document tag |
bool DLPage::dlIsTagListEmpty | ( | ) | const [inline] |
Check whether the whole page tag list is empty
Definition at line 353 of file DLPage.h.
References pageTags, and DLTagList::tagMap.
DLTagList::iterator DLPage::dlFindTag | ( | string | tagKey | ) | [inline] |
Get an iterator pointing to the location of tagKey
in the map
Definition at line 359 of file DLPage.h.
References pageTags, and DLTagList::tagMap.
DLPage* DLPage::dlClone | ( | ) | [protected] |
Create a copy of the current DLPage object and return the pointer of this new copy as precisely DLPage* type This is a utility member function solely used by the copy constructor and assignment operator to ensure that the correct derived type of DLPages on the document is recognized when a copy of the document is created. In order to fully support derived classes of DLPage, each derived class of DLPage must have a similar member function that returns a copy of the current derived object in its correct derived type.
void DLPage::dlSetDocumentPointer | ( | DLDocument * | pgDocument | ) | [protected] |
Set the DLDocument* of the current page without adding the page to the document if the DLDocument* of the current page has been set to another existing document, the page will be removed from the pageBackPointers of that document before being added to the new document
string DLPage::pageID [protected] |
DLImage DLPage::pageImage [protected] |
Definition at line 367 of file DLPage.h.
Referenced by dlGetImage(), dlGetPageHeight(), and dlGetPageWidth().
DLDocument* DLPage::pageDocument [protected] |
DLTagList DLPage::pageTags [protected] |
Definition at line 372 of file DLPage.h.
Referenced by dlClearTags(), dlFindTag(), and dlIsTagListEmpty().
list<DLZone*> DLPage::pageZones [protected] |
Definition at line 375 of file DLPage.h.
Referenced by begin(), dlGetNumZones(), dlHasZones(), and end().
list<DLZone*> DLPage::zoneBackPointers [protected] |