DLPage Class Reference

Representation of a page within a DLDocument. More...

#include <DLPage.h>

List of all members.

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)
DLPageoperator= (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

DLPagedlClone ()
void dlSetDocumentPointer (DLDocument *pgDocument)

Protected Attributes

string pageID
DLImage pageImage
DLDocumentpageDocument
DLTagList pageTags
list< DLZone * > pageZones
list< DLZone * > zoneBackPointers


Detailed Description

Representation of a page within a DLDocument.

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.


Member Typedef Documentation

typedef std::list<DLZone*>::iterator DLPage::DLZonePtrIterator

Iterator which iterates over all the DLZone*s in the page, contained in the list pageZones. Note that dereferencing this iterator gives a DLZone*, which must be dereferenced again to give an actual DLZone object reference. (See the code example in the class introduction above.)

Definition at line 75 of file DLPage.h.


Constructor & Destructor Documentation

DLPage::DLPage (  ) 

DLPage Constructor

DLPage::DLPage ( const DLImage pageImage,
const string &  pageID 
)

DLPage Constructor

Parameters:
pageImage input image to initialize the protected DLImage member of the DLPage
pageID ID of the DLPage

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


Member Function Documentation

DLZonePtrIterator DLPage::begin (  )  [inline]

Obtain an iterator pointing to the first of all the DLZone*s in the page.

Returns:
an iterator pointing to the first of all the DLZone*s in pageZones

Definition at line 81 of file DLPage.h.

References pageZones.

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.

Returns:
an iterator that addresses the location succeeding the last DLZone* in pageZones

Definition at line 90 of file DLPage.h.

References pageZones.

bool DLPage::dlIsZoneIteratorValid ( DLZonePtrIterator  zoneIter  ) 

Check whether the given iterator is in the valid range

Returns:
true if begin() <= zoneIter < end(), return false otherwise

bool DLPage::operator== ( const DLPage right  ) 

Equality operator.

Returns:
true if the two pages' ID and parent document are equal

DLPage& DLPage::operator= ( const DLPage right  ) 

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]

Get the unique ID of the page

Returns:
the unique ID of the page

Definition at line 156 of file DLPage.h.

References pageID.

void DLPage::dlSetPageID ( const string &  pgID  )  [inline]

Set the ID string of the page

Parameters:
pgID new page ID

Definition at line 162 of file DLPage.h.

References pageID.

int DLPage::dlGetPageWidth (  )  const [inline]

Get page width

Returns:
page width

Definition at line 168 of file DLPage.h.

References DLImage::dlGetWidth(), and pageImage.

int DLPage::dlGetPageHeight (  )  const [inline]

Get page height

Returns:
page height

Definition at line 174 of file DLPage.h.

References DLImage::dlGetHeight(), and pageImage.

int DLPage::dlGetNumZones (  )  const [inline]

Get the number of zones in the page

Returns:
the number of zones in the page

Definition at line 180 of file DLPage.h.

References pageZones.

bool DLPage::dlHasZones (  )  const [inline]

Check whether the current list of zones in the page is empty

Returns:
true if page contains zones

Definition at line 186 of file DLPage.h.

References pageZones.

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.

Parameters:
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.

Parameters:
pageZone new zone to be appended

void DLPage::dlAppendZoneList ( list< DLZone * >  zoneList  ) 

Append a list of new zones to the page at the end of the current list. The DLPage object takes responsibility for freeing the memory occupied by the DLZones in zoneList.

Parameters:
zoneList list of new zones to be appended to the page at the end of the current list

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.

Parameters:
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.

Parameters:
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.

Parameters:
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.

Parameters:
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.

Parameters:
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.

Parameters:
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

Parameters:
zoneIter DLZonePtrIterator of the zone to be deleted

void DLPage::dlDeleteZone ( int  cursorPosition  ) 

Delete a zone at a given position from the page

Parameters:
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

Parameters:
deletedZone zone to be deleted

void DLPage::dlClearZones (  ) 

Clear the list of zones in the page

DLImage DLPage::dlGetImage (  )  [inline]

Get a copy of the page image

Returns:
page image

Definition at line 301 of file DLPage.h.

References pageImage.

bool DLPage::dlCheckPageImageData (  ) 

Check whether the page image has been initialized

Returns:
true if the page image has been initialized

string DLPage::dlGetTag ( string  tagKey  )  const

Get the field value of a specified page tag

Parameters:
tagKey key of the specified page tag
Returns:
the field value 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.

Parameters:
tagKey key of the document tag
tagValue value of the document tag
overwriteEnabled option for overwriting existing field (default is false)
Exceptions:
DL_Exception DL_UNKNOWN_TAG_EXCEPTION

void DLPage::dlDeleteTag ( string  tagKey  ) 

Remove the tag with the specified key from the list of page tags.

Parameters:
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

Parameters:
tagKey key of the document tag
Returns:
true if a tag exists with that key

bool DLPage::dlIsTagListEmpty (  )  const [inline]

Check whether the whole page tag list is empty

Returns:
true if the 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

Returns:
iterator

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


Member Data Documentation

string DLPage::pageID [protected]

Definition at line 365 of file DLPage.h.

Referenced by dlGetPageID(), and dlSetPageID().

DLImage DLPage::pageImage [protected]

Definition at line 367 of file DLPage.h.

Referenced by dlGetImage(), dlGetPageHeight(), and dlGetPageWidth().

DLDocument* DLPage::pageDocument [protected]

Definition at line 369 of file DLPage.h.

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]

Definition at line 379 of file DLPage.h.


The documentation for this class was generated from the following file:

DOCLIB is being developed under contract by a collaboration between:
The Laboratory for Language and Media Processing
Unviersity of Maryland, College Park
and
Booz | Allen | Hamilton

All Rights Reserved, 2003-2007