Foxit PDF SDK
foxit::pdf::GraphicsObjects Class Reference
Inheritance diagram for foxit::pdf::GraphicsObjects:
foxit::Base foxit::pdf::PDFPage

Public Types

enum  TextMergeOption { e_TextMergeNone = 0, e_TextMergeTJY = 1, e_TextMergeBTET = 2 }
 Enumeration for text merge. More...
 

Public Member Functions

 GraphicsObjects (const GraphicsObjects &other)
 Constructor, with another GraphicsObjects object. More...
 
virtual ~GraphicsObjects ()
 Destructor.
 
bool GenerateContent ()
 Generate contents of current graphics objects. More...
 
bool GenerateContent (TextMergeOption text_merge_option)
 Generate contents of current graphics objects. More...
 
POSITION GetFirstGraphicsObjectPosition (graphics::GraphicsObject::Type filter=graphics::GraphicsObject::e_TypeAll) const
 Get the position of first graphics object in graphics object list, based on type filter. More...
 
graphics::GraphicsObjectGetGraphicsObject (int index) const
 Get a graphics object by index. More...
 
graphics::GraphicsObjectGetGraphicsObject (POSITION position) const
 Get the graphics object by position in graphics object list. More...
 
int GetGraphicsObjectCount () const
 Get the count of graphics objects in graphics object list. More...
 
int GetGraphicsObjectIndex (graphics::GraphicsObject *graphics_object) const
 Get the index of a specified graphics object in graphics object list. More...
 
POSITION GetGraphicsObjectPosition (graphics::GraphicsObject *graphics_object)
 Get the position of the specified graphics object. More...
 
POSITION GetLastGraphicsObjectPosition (graphics::GraphicsObject::Type filter=graphics::GraphicsObject::e_TypeAll) const
 Get the position of last graphics object in graphics object list, based on type filter. More...
 
POSITION GetNextGraphicsObjectPosition (POSITION position, graphics::GraphicsObject::Type filter=graphics::GraphicsObject::e_TypeAll) const
 Get the position of next graphics object in graphics object list, based on type filter and specified current position. More...
 
POSITION GetPrevGraphicsObjectPosition (POSITION position, graphics::GraphicsObject::Type filter=graphics::GraphicsObject::e_TypeAll) const
 Get the position of previous graphics object in graphics object list, based on type filter and specified current position. More...
 
POSITION InsertGraphicsObject (POSITION position_insert_after, graphics::GraphicsObject *graphics_object)
 Insert a graphics object after the specified position. More...
 
bool IsEmpty () const
 Check whether current object is empty or not. More...
 
POSITION MoveGraphicsObjectByPosition (POSITION current_position, POSITION position_move_after)
 Move a graphics object from a position to another position. More...
 
bool operator!= (const GraphicsObjects &other) const
 Not equal operator. More...
 
GraphicsObjectsoperator= (const GraphicsObjects &other)
 Assign operator. More...
 
bool operator== (const GraphicsObjects &other) const
 Equal operator. More...
 
bool RemoveGraphicsObject (graphics::GraphicsObject *graphics_object)
 Remove a graphics object. More...
 
bool RemoveGraphicsObjectByPosition (POSITION position)
 Remove a graphics object by position. More...
 
- Public Member Functions inherited from foxit::Base
FS_HANDLE Handle () const
 Get the handle of current object. More...
 

Detailed Description

This class is used as a manager for graphics objects. It stores all its graphics objects in a graphics list, and use POSITION object to enumerate them. A valid POSITION object can be used to get one graphics object, insert new graphics object and even remove one.
If any graphics object is changed, or graphics object is inserted/removed, function GraphicsObjects::GenerateContent should be called to ensure that all these changes would be stored to PDF document. Please refer to function GraphicsObjects::GenerateContent for more details.
A PDF page's content usually consists of a sequence of graphics objects, that means PDF page is used like a manager for graphics objects as well. So class pdf::PDFPage is derived from class GraphicsObjects in order that class PDFPage can retrieve its graphics object.
A form XObject, a kind of graphics object, is a self-contained description of any sequence of graphics objects, so function graphics::FormXObject::GetGraphicsObjects can be used to retrieve a GraphicsObjects object from a form XObject in order to manage graphics objects which are contained in a form XObject.

See also
PDFPage
graphics::FormXObject
graphics::GraphicsObject

Member Enumeration Documentation

◆ TextMergeOption

Enumeration for text merge.

Values of this enumeration should be used alone.

Enumerator
e_TextMergeNone 

No text merge.

e_TextMergeTJY 

Merge consecutive text-showing operators with equal y coordinates.

e_TextMergeBTET 

Merge consecutive BTETs as a new one.

'/BT' is an operator in the content stream that indicates the start of a text object. '/ET' is an operator in the content stream that indicates the end of a text object. If the merge option is used, it will merge multiple consecutive '/BT' and '/ET' as a new one.

Constructor & Destructor Documentation

◆ GraphicsObjects()

foxit::pdf::GraphicsObjects::GraphicsObjects ( const GraphicsObjects other)

Constructor, with another GraphicsObjects object.

Parameters
[in]otherAnother GraphicsObjects object.

Member Function Documentation

◆ GenerateContent() [1/2]

bool foxit::pdf::GraphicsObjects::GenerateContent ( )

Generate contents of current graphics objects.

If any graphics object is changed, or graphics object is inserted/removed/moved, this function should be called before saving related PDF document to ensure that all these changes would be stored to PDF document. Since it may take a long time to generate content, user is not recommended to call this function frequently, but only call this function when necessary, for example, just before the related PDF document is to be saved.
When this function succeeds, and current graphics object represents a PDF page, user is recommended to re-parse the PDF page by function PDFPage::StartParse with parameter is_reparse true before doing some operation on page content; otherwise the result of the operation may be unexpected. For example, if render the PDF page without re-parsing PDF page after this function succeeds, the page content may not be rendered as expected or unexpected error may occur. Please refer to function PDFPage::StartParse for more details about re-parsing a PDF page.

Returns
true means success, while false means failure.

◆ GenerateContent() [2/2]

bool foxit::pdf::GraphicsObjects::GenerateContent ( TextMergeOption  text_merge_option)

Generate contents of current graphics objects.

If any graphics object is changed, or graphics object is inserted/removed/moved, this function should be called before saving related PDF document to ensure that all these changes would be stored to PDF document. Since it may take a long time to generate content, user is not recommended to call this function frequently, but only call this function when necessary, for example, just before the related PDF document is to be saved.
When this function succeeds, and current graphics objects represent a PDF page, user is recommended to re-parse the PDF page by function PDFPage::StartParse with parameter is_reparse true before doing some operation on page content; otherwise the result of the operation may be unexpected. For example, if render the PDF page without re-parsing PDF page after this function succeeds, the page content may not be rendered as expected or unexpected error may occur. Please refer to function PDFPage::StartParse for more details about re-parsing a PDF page.

Parameters
[in]text_merge_optionThe merge option for text object. Please refer to values starting from GraphicsObjects::e_TextMergeNone and this should be one of these values.
Returns
true means success, while false means failure.

◆ GetFirstGraphicsObjectPosition()

POSITION foxit::pdf::GraphicsObjects::GetFirstGraphicsObjectPosition ( graphics::GraphicsObject::Type  filter = graphics::GraphicsObject::e_TypeAll) const

Get the position of first graphics object in graphics object list, based on type filter.

After getting a position in the graphics object list, then user can call function GraphicsObjects::GetGraphicsObject to get the graphics object with this position.

Parameters
[in]filterType filter that specifies which kind of graphics object is to be gotten. Please refer to values starting from graphics::GraphicsObject::e_TypeAll and this should be one of these values. graphics::GraphicsObject::e_TypeAll means for all kinds of graphics objects. Default value: graphics::GraphicsObject::e_TypeAll.
Returns
A POSITION object that represents the position of first graphics object in graphics object list. NULL or 0 means there is no graphics object.

◆ GetGraphicsObject() [1/2]

graphics::GraphicsObject* foxit::pdf::GraphicsObjects::GetGraphicsObject ( int  index) const

Get a graphics object by index.

Parameters
[in]indexIndex of a graphics object to be retrieved. Valid range: from 0 to (count-1). count is returned by function GraphicsObjects::GetGraphicsObjectCount.
Returns
A graphics object. If there is any error, this function will return NULL.

◆ GetGraphicsObject() [2/2]

graphics::GraphicsObject* foxit::pdf::GraphicsObjects::GetGraphicsObject ( POSITION  position) const

Get the graphics object by position in graphics object list.

Parameters
[in]positionA POSITION object that indicates the position in the graphics object list. It should not be NULL or 0.
Returns
A graphics::GraphicsObject object. If there is any error, this function will return NULL.

◆ GetGraphicsObjectCount()

int foxit::pdf::GraphicsObjects::GetGraphicsObjectCount ( ) const

Get the count of graphics objects in graphics object list.

Returns
Count of graphics objects in graphics object list.

◆ GetGraphicsObjectIndex()

int foxit::pdf::GraphicsObjects::GetGraphicsObjectIndex ( graphics::GraphicsObject graphics_object) const

Get the index of a specified graphics object in graphics object list.

Parameters
[in]graphics_objectA graphics object whose index is to be retrieved. Please ensure that input graphics object belongs to current graphics objects.
Returns
Index of specified graphics object in graphics object list. -1 means parameter graphics_object does not belong to current graphics object list.

◆ GetGraphicsObjectPosition()

POSITION foxit::pdf::GraphicsObjects::GetGraphicsObjectPosition ( graphics::GraphicsObject graphics_object)

Get the position of the specified graphics object.

Parameters
[in]graphics_objectA graphics object whose position is to be retrieved.
Returns
Position of the specified graphics object. NULL means input graphics object does not belong to current graphics objects.

◆ GetLastGraphicsObjectPosition()

POSITION foxit::pdf::GraphicsObjects::GetLastGraphicsObjectPosition ( graphics::GraphicsObject::Type  filter = graphics::GraphicsObject::e_TypeAll) const

Get the position of last graphics object in graphics object list, based on type filter.

After getting a position in the graphics object list, then user can call function GraphicsObjects::GetGraphicsObject to get the graphics object with this position.

Parameters
[in]filterType filter that specifies which kind of graphics object is to be gotten. Please refer to values starting from graphics::GraphicsObject::e_TypeAll and this should be one of these values. graphics::GraphicsObject::e_TypeAll means for all kinds of graphics objects. Default value: graphics::GraphicsObject::e_TypeAll.
Returns
A POSITION object that represents the position of last graphics object in graphics object list. NULL or 0 means there is no graphics object.

◆ GetNextGraphicsObjectPosition()

POSITION foxit::pdf::GraphicsObjects::GetNextGraphicsObjectPosition ( POSITION  position,
graphics::GraphicsObject::Type  filter = graphics::GraphicsObject::e_TypeAll 
) const

Get the position of next graphics object in graphics object list, based on type filter and specified current position.

After getting a position in the graphics object list, then user can call function GraphicsObjects::GetGraphicsObject to get the graphics object with this position.

Parameters
[in]positionA POSITION object that indicates a position in the graphics object list, whose next position is to be gotten. It should not be NULL or 0.
[in]filterType filter that specifies which kind of graphics object is to be gotten. Please refer to values starting from graphics::GraphicsObject::e_TypeAll and this should be one of these values. graphics::GraphicsObject::e_TypeAll means for all kinds of graphics objects. Default value: graphics::GraphicsObject::e_TypeAll.
Returns
A POSITION object that represents the position of next graphics object in graphics object list. NULL or 0 means parameter position is the last position in graphics object list.

◆ GetPrevGraphicsObjectPosition()

POSITION foxit::pdf::GraphicsObjects::GetPrevGraphicsObjectPosition ( POSITION  position,
graphics::GraphicsObject::Type  filter = graphics::GraphicsObject::e_TypeAll 
) const

Get the position of previous graphics object in graphics object list, based on type filter and specified current position.

After getting a position in the graphics object list, then user can call function GraphicsObjects::GetGraphicsObject to get the graphics object with this position.

Parameters
[in]positionA POSITION object that indicates a position in the graphics object list, whose previous position is to be gotten. It should not be NULL or 0.
[in]filterType filter that specifies which kind of graphics object is to be gotten. Please refer to values starting from graphics::GraphicsObject::e_TypeAll and this should be one of these values. graphics::GraphicsObject::e_TypeAll means for all kinds of graphics objects. Default value: graphics::GraphicsObject::e_TypeAll.
Returns
A POSITION object that represents the position of previous graphics object in graphics object list. NULL or 0 means parameter position is already in the first position in graphics object list.

◆ InsertGraphicsObject()

POSITION foxit::pdf::GraphicsObjects::InsertGraphicsObject ( POSITION  position_insert_after,
graphics::GraphicsObject graphics_object 
)

Insert a graphics object after the specified position.

Parameters
[in]position_insert_afterUsed to specify the position, in order to insert parameter graphics_object after this position. NULL means that parameter graphics_object will be inserted before all graphics objects.
[in]graphics_objectA graphics object to be inserted. User should ensure that parameter graphics_object belongs to the same PDF document as current graphics objects.
Returns
The new position of the inserted graphics object.
Note
When this function succeeds, function GraphicsObjects::GenerateContent should be called. Please refer to function GraphicsObjects::GenerateContent for more details.

◆ IsEmpty()

bool foxit::pdf::GraphicsObjects::IsEmpty ( ) const

Check whether current object is empty or not.

When the current object is empty, that means current object is useless.

Returns
true means current object is empty, while false means not.

◆ MoveGraphicsObjectByPosition()

POSITION foxit::pdf::GraphicsObjects::MoveGraphicsObjectByPosition ( POSITION  current_position,
POSITION  position_move_after 
)

Move a graphics object from a position to another position.

Parameters
[in]current_positionCurrent position of the graphics object which is to be moved to new position.
[in]position_move_afterUsed to specify the position, in order to move the graphics object specified by parameter current_position after this position. NULL means that the graphics object specified by parameter current_positionwill be moved before all graphics objects.
Returns
New position of the moved graphics object.
Note
When this function succeeds, function GraphicsObjects::GenerateContent should be called. Please refer to function GraphicsObjects::GenerateContent for more details.

◆ operator!=()

bool foxit::pdf::GraphicsObjects::operator!= ( const GraphicsObjects other) const

Not equal operator.

Parameters
[in]otherAnother GraphicsObjects object. This function will check if current object is not equal to this one.
Returns
true means not equal, while false means equal.

◆ operator=()

GraphicsObjects& foxit::pdf::GraphicsObjects::operator= ( const GraphicsObjects other)

Assign operator.

Parameters
[in]otherAnother GraphicsObjects object, whose value would be assigned to current object.
Returns
Reference to current object itself.

◆ operator==()

bool foxit::pdf::GraphicsObjects::operator== ( const GraphicsObjects other) const

Equal operator.

Parameters
[in]otherAnother GraphicsObjects object. This function will check if current object is equal to this one.
Returns
true means equal, while false means not equal.

◆ RemoveGraphicsObject()

bool foxit::pdf::GraphicsObjects::RemoveGraphicsObject ( graphics::GraphicsObject graphics_object)

Remove a graphics object.

To remove a graphics object by position (function GraphicsObjects::RemoveGraphicsObjectByPosition) is more direct and effective than to remove a graphics object directly (function GraphicsObjects::RemoveGraphicsObject).

Parameters
[in]graphics_objectA graphics object to be removed. Please ensure this graphics object belongs to current graphics objects.
Returns
true means success, while false means failure.
Note
When this function succeeds, function GraphicsObjects::GenerateContent should be called. Please refer to function GraphicsObjects::GenerateContent for more details.

◆ RemoveGraphicsObjectByPosition()

bool foxit::pdf::GraphicsObjects::RemoveGraphicsObjectByPosition ( POSITION  position)

Remove a graphics object by position.

To remove a graphics object by position (function GraphicsObjects::RemoveGraphicsObjectByPosition) is more direct and effective than to remove a graphics object directly (function GraphicsObjects::RemoveGraphicsObject).

Parameters
[in]positionUsed to specify the position of a graphics object, to be removed. It should not be NULL or 0.
Returns
true means success, while false means failure.
Note
When this function succeeds, function GraphicsObjects::GenerateContent should be called. Please refer to function GraphicsObjects::GenerateContent for more details.