#include <DLZone.h>
Public Types | |
typedef std::list< DLZone * >::iterator | DLChildZonePtrIterator |
Public Member Functions | |
DLChildZonePtrIterator | begin () |
DLChildZonePtrIterator | end () |
bool | dlIsZoneIteratorValid (DLChildZonePtrIterator zoneIter) |
DLZone () | |
DLZone (int x, int y, int w, int h) | |
DLZone (const DLPoint &upperleft, const DLPoint &lowerright) | |
DLZone (const string &zoneID, int x, int y, int w, int h) | |
DLZone (DLPage *parentPage, DLZone *parentZone, const string &zoneID, int x, int y, int w, int h) | |
DLZone (const DLZone &right) | |
virtual | ~DLZone () |
virtual bool | operator== (const DLZone &right) const |
virtual bool | operator< (const DLZone &right) const |
virtual DLZone & | operator= (const DLZone &right) |
string | dlGetZoneID () const |
void | dlSetZoneID (const string &ID) |
int | dlGetZoneWidth () const |
int | dlGetZoneHeight () const |
int | dlGetPageWidth () const |
int | dlGetPageHeight () const |
int | dlGetNumChildZones () const |
bool | dlHasChildZones () const |
DLPoint | dlGetZoneOrigin () const |
void | dlSetZoneOrigin (int x, int y) |
void | dlSetZoneOrigin (const DLPoint &origin) |
void | dlSetZoneWidth (int w) |
void | dlSetZoneHeight (int h) |
virtual void | dlAppendChildZone (DLZone *childZone) |
virtual void | dlAppendChildZoneCopy (const DLZone &childZone) |
virtual void | dlAppendChildZoneList (list< DLZone * > childZoneList) |
virtual void | dlInsertChildZone (DLChildZonePtrIterator childIter, DLZone *childZone) |
virtual void | dlInsertChildZone (int cursorPosition, DLZone *childZone) |
virtual void | dlInsertChildZoneCopy (DLChildZonePtrIterator childIter, const DLZone &childZone) |
virtual void | dlInsertChildZoneCopy (int cursorPosition, const DLZone &childZone) |
virtual void | dlInsertChildZoneList (DLChildZonePtrIterator childIter, list< DLZone * > childZoneList) |
virtual void | dlInsertChildZoneList (int cursorPosition, list< DLZone * > childZoneList) |
virtual void | dlDeleteChildZone (DLChildZonePtrIterator childIter) |
virtual void | dlDeleteChildZone (int cursorPosition) |
virtual void | dlDeleteChildZone (DLZone *deletedChildZone) |
virtual void | dlClearChildZones () |
virtual DLZone * | dlMergeZones (DLZone *Zone1, const string &newZoneID) |
virtual void | dlMergeChildZones (DLZone *childZone1, DLZone *childZone2, const string &newZoneID) |
virtual void | dlSplitZone (int offset, int direction, const string &childZoneID1, const string &childZoneID2) |
DLImage | dlGetPageImage () const |
DLImage | dlGetZoneImage () const |
DLZone *const | dlGetParentZonePointer () const |
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 | |
DLZone * | dlClone () |
void | dlSetPagePointer (DLPage *parentPage) |
bool | dlCheckZoneBoundaries (DLPoint zOrigin, int zWidth, int zHeight) const |
bool | dlCheckPagePointer () const |
bool | dlIsWithinPageBoundaries (int pageWidth, int pageHeight) const |
Protected Attributes | |
string | zoneID |
DLPoint | origin |
int | width |
int | height |
DLTagList | zoneTags |
DLPage * | zonePage |
DLZone * | parentZone |
list< DLZone * > | childZones |
list< DLZone * > | childZoneBackPointers |
DLZone offers a general bounding box concept that allows bounding boxes to have sub-boxes. These child zones are stored in a list structure similar to DLPage and DLDocument, with methods for appending, inserting, and deleting child zones. In addition, DLZone provides methods for merging and splitting zones. Accordingly, a zone and its sub-zones span a dynamic tree structure. Similar to methods in DLPage, DLZone offers access methods for information specific to zones, e.g. width, height etc. A DLZone object is basically defined by its origin, width and height. It allows developers to dynamically change this information. Each DLZone object automatically does a consistency check whenever the developer tries to do so, and denies the operation when it would lead to an inconsistent state, for instance when a zone would extend past the boundaries of its parent.
This example shows DLZones used as simple bounding boxes:
// create some zones to represent lines of text DLZone z1("line1", 50, 50, 1000, 75); DLZone z2 = z1; // copies origin and dimensions of first zone z2.dlSetZoneOrigin(50, 150); // shift second zone's origin
Developers can subclass DLZone and adapt it to their needs. For instance, a typical user-defined subclass of DLZone could be DLCharacter.
Programmers can traverse through the child zones on a zone using DLChildZonePtrIterator as below:
// ... zonePointer is a DLZone* to a zone already populated with child zones DLZone::DLChildZonePtrIterator childZoneIterator; for (childZoneIterator = zonePointer->begin(); childZoneIterator != zonePointer->end(); childZoneIterator++) { cout << (*childZoneIterator)->dlGetZoneID() << endl; }
Upon its destruction, the DLZone deletes all its child zones, and notifies any additional DLZone copies which may refer to it that it is being destroyed.
When making a copy of a DLZone, all of its child zones will automatically be copied over to the new DLZone object. However, this is NOT simply a member-wise copy, since each of its child zones is a newly created object. This ensures when the destructor of a DLZone copy is invoked, it will not result in accidental destruction of the child zones owned by the original DLZone.
It is advisable for programmers to use the 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 74 of file DLZone.h.
typedef std::list<DLZone*>::iterator DLZone::DLChildZonePtrIterator |
DLZone::DLZone | ( | ) |
DLZone Constructor: Leaves bounding box coordinates undefined.
DLZone::DLZone | ( | int | x, | |
int | y, | |||
int | w, | |||
int | h | |||
) |
DLZone Constructor
x | x-coordinate, or column, of the zone's origin (upper-left corner) | |
y | y-coordinate, or row, of the zone's origin | |
w | width of the zone | |
h | height of the zone |
DLZone::DLZone | ( | const string & | zoneID, | |
int | x, | |||
int | y, | |||
int | w, | |||
int | h | |||
) |
DLZone Constructor
zoneID | ID tag for this zone | |
x | x-coordinate, or column, of the zone's origin (upper-left corner) | |
y | y-coordinate, or row, of the zone's origin | |
w | width of the zone | |
h | height of the zone |
DLZone::DLZone | ( | DLPage * | parentPage, | |
DLZone * | parentZone, | |||
const string & | zoneID, | |||
int | x, | |||
int | y, | |||
int | w, | |||
int | h | |||
) |
DLZone Constructor: Contructs a new DLZone as a child zone of the given DLPage and/or DLZone. To associate the new DLZone with a parent DLZone, but not with a parent DLPage, set the parentPage parameter to NULL
. To associate the new DLZone with a parent DLPage, but not with a parent DLZone, set the parentZone parameter to NULL
. If either the parent DLZone or DLPage is destroyed, it will notify the DLZone object to set the appropriate backpointer to NULL
.
DLZone::DLZone | ( | const DLZone & | right | ) |
DLZone Copy Constructor: All the child DLZones will also be copied over to the new DLZone object. The DLZone copy points to the same parent DLPage as the source DLZone, and its parentZone is always set to NULL. A DLZone copy is a real image of the DLZone source. It has identical child zone hierarchy as the source DLZone, in which each child zone is newly created. As DLZone copy is NOT simply the default member-wise copy, it will not result in the accidental destruction of child zones of the original DLZone when the destructor of the DLZone copy is invoked.
virtual DLZone::~DLZone | ( | ) | [virtual] |
Default DLZone Destructor
DLChildZonePtrIterator DLZone::begin | ( | ) | [inline] |
Obtain an iterator pointing to the first of all the child DLZone*s
Definition at line 92 of file DLZone.h.
References childZones.
DLChildZonePtrIterator DLZone::end | ( | ) | [inline] |
Obtain an iterator that addresses the location succeeding the last DLZone* in childZones. 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 101 of file DLZone.h.
References childZones.
bool DLZone::dlIsZoneIteratorValid | ( | DLChildZonePtrIterator | zoneIter | ) |
virtual bool DLZone::operator== | ( | const DLZone & | right | ) | const [virtual] |
virtual bool DLZone::operator< | ( | const DLZone & | right | ) | const [virtual] |
DLZone Copy Assignment operator: All the child DLZones will also be copied over to the new DLZone object. The DLZone copy points to the same DLPage as the source DLZone and its parentZone is always set to NULL. A DLZone copy is a real image of the DLZone source. It has identical child zone hierarchy as the source DLZone, in which each child zone is newly created. As DLZone copy is NOT simply the default member-wise copy, it will not result in the accidental destruction of child zones of the original DLZone object when the destructor of the DLZone copy is invoked. it is not allowed to reset an existing zone via copy assignment
string DLZone::dlGetZoneID | ( | ) | const [inline] |
void DLZone::dlSetZoneID | ( | const string & | ID | ) | [inline] |
int DLZone::dlGetZoneWidth | ( | ) | const [inline] |
Get the width of the zone
Definition at line 220 of file DLZone.h.
References width.
Referenced by DLRectShape::DLRectShape().
int DLZone::dlGetZoneHeight | ( | ) | const [inline] |
Get the height of the zone
Definition at line 226 of file DLZone.h.
References height.
Referenced by DLRectShape::DLRectShape().
int DLZone::dlGetPageWidth | ( | ) | const |
Get page width
int DLZone::dlGetPageHeight | ( | ) | const |
Get page height
int DLZone::dlGetNumChildZones | ( | ) | const [inline] |
Get the number of direct child zones of this zone; i.e., does not count any of the current DLZone's children's children.
Definition at line 245 of file DLZone.h.
References childZones.
bool DLZone::dlHasChildZones | ( | ) | const [inline] |
Check whether the current zone has child zones
Definition at line 251 of file DLZone.h.
References childZones.
DLPoint DLZone::dlGetZoneOrigin | ( | ) | const [inline] |
Get the upper left corner of the zone
Definition at line 256 of file DLZone.h.
References origin.
Referenced by DLRectShape::DLRectShape().
void DLZone::dlSetZoneOrigin | ( | int | x, | |
int | y | |||
) |
Set the upper left corner of the zone
x | x-coordinate, or column, of zone's origin | |
y | y-coordinate, or row, of zone's origin |
void DLZone::dlSetZoneOrigin | ( | const DLPoint & | origin | ) |
Set the upper left corner of the zone
origin | DLPoint containing x-coordinate, or column, and y-coordinate, or row, of zone's origin |
void DLZone::dlSetZoneWidth | ( | int | w | ) |
Set the width of the zone
w | zone width |
void DLZone::dlSetZoneHeight | ( | int | h | ) |
Set the height of the zone
h | zone height |
virtual void DLZone::dlAppendChildZone | ( | DLZone * | childZone | ) | [virtual] |
Append a new child zone to this zone at the end of the current list of child zones. If this zone points to a valid DLPage as its parent, the appended zone and all its child zones will be added to the list of zone backpointers on that page, so that if that DLPage is destroyed, the new child zones will be notified as well to set their parent DLPage pointers to NULL
.
The current DLZone then takes responsibility for freeing the memory occupied by childZone. Therefore, typically childZone 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 parent DLZone. In this situation, consider using dlAppendChildZoneCopy() instead.
childZone | new child zone to be appended |
virtual void DLZone::dlAppendChildZoneCopy | ( | const DLZone & | childZone | ) | [virtual] |
Append a copy of the given child zone to this zone at the end of the current list of child zones. If the zone points to a valid page, the appended zone and all its child zones will be added to the list of zone backpointers on that page.
childZone | new child zone to be appended |
virtual void DLZone::dlAppendChildZoneList | ( | list< DLZone * > | childZoneList | ) | [virtual] |
Append a list of new child zones to this zone at the end of the current list. If the zone points to a valid page, the appended zone and all its child zones will be added to the list of zone backpointers on that page.i The current DLZone object takes responsibility for freeing the memory occupied by the DLZones in childZoneList.
childZoneList | list of new child zones to be appended to the zone at the end of the current list |
virtual void DLZone::dlInsertChildZone | ( | DLChildZonePtrIterator | childIter, | |
DLZone * | childZone | |||
) | [virtual] |
Insert a new child zone to the zone at the specified iterator position of the current list. The current DLZone object takes responsibility for freeing the memory occupied by childZone. See dlInsertChildZoneCopy() for inserting a stack DLZone object as a child zone.
childIter | iterator position in the current child zone list where the new child zone is to be inserted. | |
childZone | new DLZone to be inserted |
virtual void DLZone::dlInsertChildZone | ( | int | cursorPosition, | |
DLZone * | childZone | |||
) | [virtual] |
Insert a new child zone to the zone at the specified position of the current list. The current DLZone object takes responsibility for freeing the memory occupied by childZone. See dlInsertChildZoneCopy() for inserting a stack DLZone object as a child zone.
cursorPosition | cursor position in the current child zone list where the new child zone is to be inserted. cursorPosition must be between 0 (beginning of the list) and the size of the child zone (end of the list) | |
childZone | new DLZone to be inserted |
virtual void DLZone::dlInsertChildZoneCopy | ( | DLChildZonePtrIterator | childIter, | |
const DLZone & | childZone | |||
) | [virtual] |
Insert a copy of a child zone to the zone at the specified iterator position of the current list.
childIter | position in the current child zone list where the new child zone is to be inserted. | |
childZone | new DLZone to be copied and inserted |
virtual void DLZone::dlInsertChildZoneCopy | ( | int | cursorPosition, | |
const DLZone & | childZone | |||
) | [virtual] |
Insert a copy of the given child zone to the zone at the specified position of the current list.
cursorPosition | cursor position in the current child zone list where the new child zone is to be inserted. cursorPosition must be between 0 (beginning of the list) and the size of the child zone (end of the list) | |
childZone | new DLZone to be copied and inserted |
virtual void DLZone::dlInsertChildZoneList | ( | DLChildZonePtrIterator | childIter, | |
list< DLZone * > | childZoneList | |||
) | [virtual] |
Insert a list of new child zones to the zone starting from the specified iterator position in the current list.
childIter | iterator position in the current child zone list where the new child zones are to be inserted | |
childZoneList | list of new DLZones to be inserted at the specified cursor position in the current list |
virtual void DLZone::dlInsertChildZoneList | ( | int | cursorPosition, | |
list< DLZone * > | childZoneList | |||
) | [virtual] |
Insert a list of new child zones to the zone starting from the specified position in the current list. The current DLZone object takes responsibility for freeing the memory occupied by the DLZones in childZoneList.
cursorPosition | position in the current child zone list where the new child zones are to be inserted. cursorPosition must be between 0 (beginning of the list) and the size of the child zone (end of the list). | |
childZoneList | list of new DLZones to be inserted at the specified cursor position in the current list |
virtual void DLZone::dlDeleteChildZone | ( | DLChildZonePtrIterator | childIter | ) | [virtual] |
Delete a child zone at a given iterator position from the current zone.
childIter | iterator position of the child zone to be removed from the child zone list |
virtual void DLZone::dlDeleteChildZone | ( | int | cursorPosition | ) | [virtual] |
Delete a child zone at a given position from the current zone.
cursorPosition | position of the child zone to be removed from the child zone list |
virtual void DLZone::dlDeleteChildZone | ( | DLZone * | deletedChildZone | ) | [virtual] |
Delete a specific child zone from the zone. The child zone will be removed together with any child zones of its own.
deletedChildZone | child zone to be deleted |
virtual void DLZone::dlClearChildZones | ( | ) | [virtual] |
Clear the list of child zones of the zone
Construct a new parent zone with the current zone and another zone as its child zones. The new DLZone will have dimensions spanning those of the two children. None of the zones to be merged can have parent zones and they must not have conflicting parent DLPage pointers.
Warning: The code calling this function is responsible for freeing the memory occupied by the returned DLZone.
Zone1 | another zone to be merged | |
newZoneID | zoneID for the new parent zone |
virtual void DLZone::dlMergeChildZones | ( | DLZone * | childZone1, | |
DLZone * | childZone2, | |||
const string & | newZoneID | |||
) | [virtual] |
Merge two child zones into a single child zone childZone1 and delete childZone2. The child zones to be merged may have their own child zone hierarchy.
[in,out] | childZone1 | first child zone to be merged |
[in] | childZone2 | second child zone to be merged |
[in] | newZoneID | string zoneID for the merged zone |
virtual void DLZone::dlSplitZone | ( | int | offset, | |
int | direction, | |||
const string & | childZoneID1, | |||
const string & | childZoneID2 | |||
) | [virtual] |
Split a zone leaf (i.e. without its own child zones) into two neighboring child zones. The current zone will become the parent of the two new DLZones.
offset | The horizontal or vertical offset point to split. For example, if the split is to be into two zones side-by-side, the left zone will be of width offset - 1 and the right zone will start at offset. | |
direction | indicating the orientation of the split
| |
childZoneID1 | zoneID for the first (left or upper) child zone after split | |
childZoneID2 | zoneID for the second (right or lower) child zone after split |
DLImage DLZone::dlGetPageImage | ( | ) | const |
Get a copy of the image of the page that the zone is on, if the current zone is associated with a DLPage as its parent.
DLImage DLZone::dlGetZoneImage | ( | ) | const |
Get an image corresponding to the zone (i.e. a cropped region on the page image), if the current zone is associated with a DLPage as its parent.
DLZone* const DLZone::dlGetParentZonePointer | ( | ) | const [inline] |
Get the parent zone pointer in DLZone* (base zone class) form, which can be used to check the pointer to its parent zone when derived classes of DLZone are present.
Definition at line 457 of file DLZone.h.
References parentZone.
string DLZone::dlGetTag | ( | string | tagKey | ) | const |
Get the field value of a specified zone tag
tagKey | key of the specified zone tag |
void DLZone::dlSetTag | ( | string | tagKey, | |
string | tagValue, | |||
bool | overwriteEnabled = false | |||
) |
Set a zone tag. If a tag with the specified key already exists in this zone, 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 DLZone::dlDeleteTag | ( | string | tagKey | ) |
Remove the tag with the specified key from the list of zone tags.
tagKey | key of the zone tag |
void DLZone::dlClearTags | ( | ) | [inline] |
Erase all the existing zone tags
Definition at line 490 of file DLZone.h.
References DLTagList::tagMap, and zoneTags.
bool DLZone::dlIsTagSet | ( | string | tagKey | ) | const |
Check whether a document tag with the given key exists
tagKey | key of the document tag |
bool DLZone::dlIsTagListEmpty | ( | ) | const [inline] |
Check whether the whole zone tag list is empty
Definition at line 502 of file DLZone.h.
References DLTagList::tagMap, and zoneTags.
DLTagList::iterator DLZone::dlFindTag | ( | string | tagKey | ) | [inline] |
Get an iterator pointing to the location of tagKey
in the map
Definition at line 508 of file DLZone.h.
References DLTagList::tagMap, and zoneTags.
DLZone* DLZone::dlClone | ( | ) | [protected] |
Create a copy of the current DLZone object and return the pointer of this new copy as precisely DLZone* type This is a utility member function solely used by the copy constructor and assignment operator to ensure that the correct derived type of DLZones is recognized when a copy of the page or parent zone is created. In order to fully support derived classes of DLZone, each derived class of DLZone must have a similar member function that returns a copy of the current object in its correct derived type.
void DLZone::dlSetPagePointer | ( | DLPage * | parentPage | ) | [protected] |
Set the DLPage* of the current zone and all its child zones without adding them to the page. This function appends this zone and all its child zones to the list of zone back pointers on the DLPage. This enables this zone to be notified if the DLPage it will refer to as its parent is destroyed. If the DLPage* of these zones has been set to another existing page, the current zone and all its child zones will be first removed from the back pointer notification list of that page before being added to the new page.
parentPage | pointer to the parent page to be set |
bool DLZone::dlCheckZoneBoundaries | ( | DLPoint | zOrigin, | |
int | zWidth, | |||
int | zHeight | |||
) | const [protected] |
Check whether each child zone in the hierarchy below the current zone is contained within the test zone specified by the parameters.
zOrigin | origin of the test zone | |
zWidth | width of the test zone | |
zHeight | height of the test zone |
bool DLZone::dlCheckPagePointer | ( | ) | const [protected] |
Check whether each child zone below has the same parent DLPage pointer as the current zone. The parent page pointer of the current zone must be set (i.e. not NULL
).
bool DLZone::dlIsWithinPageBoundaries | ( | int | pageWidth, | |
int | pageHeight | |||
) | const [protected] |
Test whether a zone lies within given page image dimensions.
pageWidth | width of the page image | |
pageHeight | height of the page image |
string DLZone::zoneID [protected] |
DLPoint DLZone::origin [protected] |
int DLZone::width [protected] |
int DLZone::height [protected] |
DLTagList DLZone::zoneTags [protected] |
Definition at line 520 of file DLZone.h.
Referenced by dlClearTags(), dlFindTag(), and dlIsTagListEmpty().
DLPage* DLZone::zonePage [protected] |
DLZone* DLZone::parentZone [protected] |
list<DLZone*> DLZone::childZones [protected] |
Definition at line 529 of file DLZone.h.
Referenced by begin(), dlGetNumChildZones(), dlHasChildZones(), and end().
list<DLZone*> DLZone::childZoneBackPointers [protected] |