PdsStructElement class. More...

#include <pdfix.h>

Public Member Functions
virtual int	GetType (bool mapped, wchar_t *buffer, int len) const =0
virtual bool	SetType (const wchar_t *type)=0
	Sets the struct element type.
virtual int	GetActualText (wchar_t *buffer, int len) const =0
virtual bool	SetActualText (const wchar_t *text)=0
virtual int	GetAlt (wchar_t *buffer, int len) const =0
virtual bool	SetAlt (const wchar_t *alt)=0
virtual int	GetTitle (wchar_t *buffer, int len) const =0
	Gets the title of the specified element, returning the number of bytes in the title.
virtual bool	SetTitle (const wchar_t *title)=0
	Sets the title associated with an element.
virtual int	GetText (int max, wchar_t *buffer, int len) const =0
	Gets the page content of the specified element, returning the number of bytes in the content.
virtual int	GetAbbreviation (wchar_t *buffer, int len) const =0
	Gets the expanded form of an abbreviation.
virtual int	GetNumPages ()=0
	Returns the number of pages on which the content items designated by the K entry are rendered.
virtual int	GetPageNumber (int index)=0
	Returns the n-th page number on which the content items designated by the K entry are rendered.
virtual void	GetBBox (int page_num, PdfRect *bbox)=0
virtual PdsObject *	GetAttrObject (int index)=0
virtual bool	AddAttrObj (PdsObject *object)=0
	Associates the specified attribute object with an element.
virtual bool	RemoveAttrObj ()=0
virtual PdsObject *	GetObject ()=0
virtual PdsObject *	GetChildObject (int index)=0
virtual PdfStructElementType	GetChildType (int index)=0
virtual int	GetChildPageNumber (int index) const =0
	Returns a page number representing a page on which the child is rendered.
virtual int	GetChildMcid (int index) const =0
virtual int	GetNumAttrObjects () const =0
	Gets the number of attribute objects directly attached to the specified element.
virtual int	GetNumChildren () const =0
	Gets the number of childs of the specified element.
virtual PdsObject *	GetParentObject ()=0
virtual bool	HasContent ()=0
virtual bool	HasAnnot ()=0
virtual int	GetId (wchar_t *buffer, int len) const =0
virtual bool	SetId (const wchar_t *id)=0
	Sets the id associated with an element.
virtual int	GetLang (wchar_t *buffer, int len) const =0
virtual bool	SetLang (const wchar_t *alt)=0
	Sets the Lang entry of a struct element.
virtual bool	RemoveChild (int index)=0
	Removes the specified child from an element.
virtual bool	MoveChild (int index, PdsStructElement *dest_element, int dest_index)=0
	Modes the specified child to specified index in another element.
virtual bool	AddChild (PdsStructElement *element, int index)=0
	Adds the new PdsStructElement.
virtual PdsStructElement *	AddNewChild (const wchar_t *type, int index)=0
	Adds a new (but empty) PdsStructElement of specific type.
virtual bool	AddPageObject (PdsPageObject *object, int index)=0
virtual PdsStructElement *	AddAnnot (PdfAnnot *annot, int index)=0
virtual PdsStructTree *	GetStructTree ()=0
	Get pointer to the parent struct tree object.
virtual PdsStructTableError	RecognizeTable ()=0
	Recreates a Table structure from the Table structure element.
virtual int	GetNumRow () const =0
	Gets the number of table row.
virtual int	GetNumCol () const =0
	Gets the number of table column.
virtual PdsStructElement *	GetCell (int row, int col)=0
	Returns the table cell.
virtual bool	GetCellParams (int row, int col, PdfCellParams *params)=0
	Gets the cell's parameters.
virtual bool	GetCellElemParams (PdsStructElement cell, PdfCellParams params)=0
	Gets the cell's parameters.
virtual int	GetNumAssociatedHeaders ()=0
	Gets the number of associated headers for a cell.
virtual PdsStructElement *	GetAssociatedHeader (int index)=0
	Gets the requested child associated header.
virtual bool	AddAssociatedHeader (int index, PdsStructElement *header, bool create)=0
	Adds the associated header to cell.
virtual bool	RemoveAssociatedHeader (int index)=0
	Removes the specified child froma an action.
virtual bool	AddAssociatedFile (PdsFileSpec *file_spec, int index)=0
	Add associated file to the structure elmement.
virtual int	GetNumAssociatedFiles ()=0
	Get the number of associated files of the structure elmement in the AF array.
virtual PdsFileSpec *	GetAssociatedFile (int index)=0
	Get the associated file to the structure elmement by index in the AF array.
virtual int	ValidChild (int version, PdsStructElement *child)=0
	Returns the permitted number of child type occurrences in the structure element.

Detailed Description

PdsStructElement class.

PdsStructElement is the basic building block of the structure tree. It represents PDF structural elements, which are nodes in a tree, defining a PDF document's logical structure.

Member Function Documentation

◆ AddAnnot()

virtual PdsStructElement * PdsStructElement::AddAnnot	(	PdfAnnot *	annot,
		int	index )

pure virtual

Inserts a reference to the specified annotation as a child into the specified element. This method automatically creates OBJR object.

Parameters

object	The annotation to insert.
index	Position where the annotation object is inserted.

Returns: Created PdsStructElement.

◆ AddAssociatedFile()

virtual bool PdsStructElement::AddAssociatedFile	(	PdsFileSpec *	file_spec,
		int	index )

pure virtual

Add associated file to the structure elmement.

Parameters

file_spec	The file specification object.
index	The index of the associated file in the AF array.

Returns: True if successfull, false otherwise.

See also: PdfDoc::CreateFileSpec; PdsStructElement::GetNumAssociatedFiles; PdsStructElement::GetAssociatedFile

◆ AddAssociatedHeader()

virtual bool PdsStructElement::AddAssociatedHeader	(	int	index,
		PdsStructElement *	header,
		bool	create )

pure virtual

Adds the associated header to cell.

Parameters

cell	Cell structure element.
index	Position where the header is inserted.
header	The associated header to add.
create	If true, TD cell will be changed to TH.

Returns: true if the header was successfully added. false otherwise

See also: PdsStructTable::GetNumAssociatedHeaders

◆ AddAttrObj()

virtual bool PdsStructElement::AddAttrObj ( PdsObject * object )

pure virtual

Associates the specified attribute object with an element.

Parameters

object Attribute object to associate with element.

◆ AddChild()

virtual bool PdsStructElement::AddChild	(	PdsStructElement *	element,
		int	index )

pure virtual

Adds the new PdsStructElement.

Parameters

element	The element to add.
index	Position where the child is inserted. If element currently has no children, index is ignored.

Returns: Created PdsStructElement.

◆ AddNewChild()

virtual PdsStructElement * PdsStructElement::AddNewChild	(	const wchar_t *	type,
		int	index )

pure virtual

Adds a new (but empty) PdsStructElement of specific type.

Parameters

type	The name representing the element's type.
index	Position where the child is inserted to parents children. If element currently has no children, index is ignored.

Returns: Created PdsStructElement.

◆ AddPageObject()

virtual bool PdsStructElement::AddPageObject	(	PdsPageObject *	object,
		int	index )

pure virtual

Inserts a reference to the specified page object as a child into the specified element. This method automatically creates MCR objects if needed.

Parameters

object	The page object to insert.
index	Position where the page object is inserted.

Returns: true if element was successfully added, false otherwise.

◆ GetAbbreviation()

virtual int PdsStructElement::GetAbbreviation	(	wchar_t *	buffer,
		int	len ) const

pure virtual

Gets the expanded form of an abbreviation.

Parameters

buffer	(filled by method) If the buffer is null function returns required length of string
len	Length of a buffer to be filled in.

Returns: Number of characters written into buffer of required length.

◆ GetActualText()

virtual int PdsStructElement::GetActualText	(	wchar_t *	buffer,
		int	len ) const

pure virtual

Gets the actual text associated with the specified element. Returns the number of bytes in the text or 0 if the element has no actual text or has an empty string. To check for the existence of alternate text, check for a non-zero return value.

Parameters

buffer	(filled by method) If the buffer is null function returns required length of string
len	Length of a buffer to be filled in.

Returns: Number of characters written into buffer of required length.

◆ GetAlt()

virtual int PdsStructElement::GetAlt	(	wchar_t *	buffer,
		int	len ) const

pure virtual

Gets the alternate text associated with an element. NOTE: The Alt text can be legally defined as an empty string. To differentiate between an Alt text string of zero length and no Alt text being defined, call HasAlt first.

Parameters

buffer	(filled by method) If the buffer is null function returns required length of string
len	Length of a buffer to be filled in.

Returns: Number of characters written into buffer of required length.

◆ GetAssociatedFile()

virtual PdsFileSpec * PdsStructElement::GetAssociatedFile ( int index )

pure virtual

Get the associated file to the structure elmement by index in the AF array.

Parameters

index The index of the associated file to obtain.

Returns: The FileSpec of an associated file object if successfull, nullptr otherwise.

See also: PdfDoc::CreateFileSpec; PdsStructElement::AddAssociatedFile; PdsStructElement::GetNumAssociatedFiles

◆ GetAssociatedHeader()

virtual PdsStructElement * PdsStructElement::GetAssociatedHeader ( int index )

pure virtual

Gets the requested child associated header.

Parameters

cell	Cell structure element.
index	The index of associated header to obtain.

Returns: Requested associated header.

See also: PdsStructTable::GetNumAssociatedHeaders

◆ GetAttrObject()

virtual PdsObject * PdsStructElement::GetAttrObject ( int index )

pure virtual

Gets the attribute object at a specified array index in the specified element. If there is only one attribute object(that is, there is no array of attributes), and index is zero, that attribute object is obtained.

Parameters

index Index of the attribute object to obtain.

Returns: Attribute object at index.

◆ GetBBox()

virtual void PdsStructElement::GetBBox	(	int	page_num,
		PdfRect *	bbox )

pure virtual

Returns the union bounding boxes on the page number on which the content items designated by the K entry are rendered.

Returns: The number of pages.

◆ GetCell()

virtual PdsStructElement * PdsStructElement::GetCell	(	int	row,
		int	col )

pure virtual

Returns the table cell.

Returns: Table cell.

Parameters

row	Cell row index.
col	Cell column index.

◆ GetCellElemParams()

virtual bool PdsStructElement::GetCellElemParams	(	PdsStructElement *	cell,
		PdfCellParams *	params )

pure virtual

Gets the cell's parameters.

Parameters

cell	Cell structure element.
params	(filled by method) Pointer to a PdfCellParams structure.

Returns: true if the params was successfully retrieved. false otherwise

◆ GetCellParams()

virtual bool PdsStructElement::GetCellParams	(	int	row,
		int	col,
		PdfCellParams *	params )

pure virtual

Gets the cell's parameters.

Parameters

row	Cell row index.
col	Cell column index.
params	(filled by method) Pointer to a PdfCellParams structure.

Returns: true if the params was successfully retrieved. false otherwise

◆ GetChildMcid()

virtual int PdsStructElement::GetChildMcid ( int index ) const

pure virtual

Returns a child's MCID. Note: Call this method only in a case that PdfStructElement::GetChildType returns kPdsStructChildPageContent type. Otherwise this method it returns -1.

Parameters

index The index of the child.

Returns: The child's MCID if presented, -1 otherwise.

◆ GetChildObject()

virtual PdsObject * PdsStructElement::GetChildObject ( int index )

pure virtual

Gets the child's object at an array index for the structure element. A PDF structural elements unlike the structure tree root can have several different kinds of children : marked content ID, another structural element, or an object reference.

Parameters

index The index of the child.

Returns: The child's object being accessed.

See also: PdsStructTree::GetStructElementFromObject

◆ GetChildPageNumber()

virtual int PdsStructElement::GetChildPageNumber ( int index ) const

pure virtual

Returns a page number representing a page on which the child is rendered.

Parameters

index The index of the child.

Returns: The page number if presented, -1 otherwise.

◆ GetChildType()

virtual PdfStructElementType PdsStructElement::GetChildType ( int index )

pure virtual

Gets the child's type at an array index for the structure element. A PDF structural elements unlike the structure tree root can have several different kinds of children : marked content ID, another structure element, or an object object reference dictionary denoting a PdsObject.

Parameters

index The index of the child.

Returns: The type of the child.

◆ GetId()

virtual int PdsStructElement::GetId	(	wchar_t *	buffer,
		int	len ) const

pure virtual

Gets the ID of an element. The element identifier, a string designating this structure element. The string must be unique among all elements in the document's structure hierarchy. The IDTree entry in the structure tree root defines the correspondence between element identifiers and the structure elements they denote.

Parameters

buffer	(filled by method) If the buffer is null function returns required length of string
len	Length of a buffer to be filled in.

Returns: Number of characters written into buffer of required length.

◆ GetLang()

virtual int PdsStructElement::GetLang	(	wchar_t *	buffer,
		int	len ) const

pure virtual

Gets the Lang entry of a struct element. A language identifier specifying the natural language for all text in the structure element except where overridden by language specifications for nested structure elements or marked content

Parameters

buffer	(filled by method) If the buffer is null function returns required length of string
len	Length of a buffer to be filled in.

Returns: Number of characters written into buffer of required length.

◆ GetNumAssociatedFiles()

virtual int PdsStructElement::GetNumAssociatedFiles ( )

pure virtual

Get the number of associated files of the structure elmement in the AF array.

Returns: The number of associated files.

See also: PdsStructElement::AddAssociatedFile; PdsStructElement::GetAssociatedFile

◆ GetNumAssociatedHeaders()

virtual int PdsStructElement::GetNumAssociatedHeaders ( )

pure virtual

Gets the number of associated headers for a cell.

Parameters

cell	Cell structure element.

Returns: The number of associated headers.

See also: PdsStructTable::GetAssociatedHeader

◆ GetNumAttrObjects()

virtual int PdsStructElement::GetNumAttrObjects ( ) const

pure virtual

Gets the number of attribute objects directly attached to the specified element.

Returns: Number of attribute objects directly attached to element.

◆ GetNumChildren()

virtual int PdsStructElement::GetNumChildren ( ) const

pure virtual

Gets the number of childs of the specified element.

Returns: Number of direct childs of element.

◆ GetNumCol()

virtual int PdsStructElement::GetNumCol ( ) const

pure virtual

Gets the number of table column.

Returns: The number of column.

◆ GetNumPages()

virtual int PdsStructElement::GetNumPages ( )

pure virtual

Returns the number of pages on which the content items designated by the K entry are rendered.

Returns: The number of pages.

◆ GetNumRow()

virtual int PdsStructElement::GetNumRow ( ) const

pure virtual

Gets the number of table row.

Returns: The number of row.

◆ GetObject()

virtual PdsObject * PdsStructElement::GetObject ( )

pure virtual

Gets the object corresponding to the specified element object. This method does not copy the object, but is instead the logical equivalent of a type cast

Returns: The dictionary object for the element object.

◆ GetPageNumber()

virtual int PdsStructElement::GetPageNumber ( int index )

pure virtual

Returns the n-th page number on which the content items designated by the K entry are rendered.

Returns: The number of pages.

◆ GetParentObject()

virtual PdsObject * PdsStructElement::GetParentObject ( )

pure virtual

Gets the immediate ancestor element of the specified element in the tree. If the element's parent is another element, parent is set to that parent's object.

Parameters

parent (filled by method) The element parent's object.

Returns: Element's parent object. If the element's parent is the structure tree root, return value is nullptr.

◆ GetStructTree()

virtual PdsStructTree * PdsStructElement::GetStructTree ( )

pure virtual

Get pointer to the parent struct tree object.

◆ GetText()

virtual int PdsStructElement::GetText	(	int	max,
		wchar_t *	buffer,
		int	len ) const

pure virtual

Gets the page content of the specified element, returning the number of bytes in the content.

Parameters

buffer	(filled by method) If the buffer is null function returns required length of string
len	Length of a buffer to be filled in.
max	Maximum length of the content.

Returns: Number of characters written into buffer of required length.

◆ GetTitle()

virtual int PdsStructElement::GetTitle	(	wchar_t *	buffer,
		int	len ) const

pure virtual

Gets the title of the specified element, returning the number of bytes in the title.

Parameters

buffer	(filled by method) If the buffer is null function returns required length of string
len	Length of a buffer to be filled in.

Returns: Number of characters written into buffer of required length.

◆ GetType()

virtual int PdsStructElement::GetType	(	bool	mapped,
		wchar_t *	buffer,
		int	len ) const

pure virtual

Gets the element's structural element type. It maps an element type to another element type if the specified element type has role mapping.

Parameters

buffer	(filled by method) If the buffer is null function returns required length of string
len	Length of a buffer to be filled in.

Returns: Number of characters written into buffer of required length.

◆ HasAnnot()

virtual bool PdsStructElement::HasAnnot ( )

pure virtual

Checks whether the structure element contains an annotation reference (OBJR). This function returns true if the element directly or indirectly contains an OBJR (Object Reference) to an annotation (for example a Link, Widget, etc.). This is a separate check from HasContent(): annotation-only tags may have OBJR but no MCID/MCR.

Returns: True if the structure element contains (or references) at least one annotation object via OBJR, false otherwise.

◆ HasContent()

virtual bool PdsStructElement::HasContent ( )

pure virtual

Check wheather the structure element is empty, has no conection with page content. The element is considered to "have content" if it directly or indirectly references at least one marked-content item on a page (MCID/MCR). In other words, the tag is not empty from the tagging perspective and is associated with real page content.

Returns: True if the structure element contains (or references) any page content via MCID/MCR, false if it has no such connection (empty/unreferenced tag)

◆ MoveChild()

virtual bool PdsStructElement::MoveChild	(	int	index,
		PdsStructElement *	dest_element,
		int	dest_index )

pure virtual

Modes the specified child to specified index in another element.

Parameters

index The index of the child.

Returns: True if successfull, falsw otherwise.

◆ RecognizeTable()

virtual PdsStructTableError PdsStructElement::RecognizeTable ( )

pure virtual

Recreates a Table structure from the Table structure element.

Returns: true if pagemap was generated successfuly, false otherwise.

◆ RemoveAssociatedHeader()

virtual bool PdsStructElement::RemoveAssociatedHeader ( int index )

pure virtual

Removes the specified child froma an action.

Parameters

cell	Cell structure element.
index	The index of the associated header to remove.

Returns: true if header was removed sucessfully, false otherwise.

See also: PdsStructTable::GetNumAssociatedHeaders

◆ RemoveAttrObj()

virtual bool PdsStructElement::RemoveAttrObj ( )

pure virtual

Removes the specified attribute object from an element. If element does not have an attrObj attribute, this method does nothing.

Returns: true if remove operation was successfull, false otherwise

◆ RemoveChild()

virtual bool PdsStructElement::RemoveChild ( int index )

pure virtual

Removes the specified child from an element.

Parameters

index The index of the child.

Returns: True if successfull, falsw otherwise.

◆ SetActualText()

virtual bool PdsStructElement::SetActualText ( const wchar_t * text )

pure virtual

Sets the Actual Text text associated with an element. Text that is an exact replacement for the structure element and its children. This replacement text (which should apply to as small a piece of content as possible) is useful when extracting the document’s contents in support of accessibility to users with disabilities or for other purposes

Parameters

title String value to be set for the ActualText.

Returns: true if optaining the font state was succsessfull, false otherwise.

◆ SetAlt()

virtual bool PdsStructElement::SetAlt ( const wchar_t * alt )

pure virtual

Sets the alternate text associated with an element. NOTE: The Alt text can be legally defined as an empty string. To differentiate between an Alt text string of zero length and no Alt text being defined, call HasAlt first.

Parameters

alt	String value to be set for the alt text.

Returns: true if optaining the font state was succsessfull, false otherwise.

◆ SetId()

virtual bool PdsStructElement::SetId ( const wchar_t * id )

pure virtual

Sets the id associated with an element.

Parameters

alt	String value to be set for the struct element id.

Returns: true if optaining the font state was succsessfull, false otherwise.

◆ SetLang()

virtual bool PdsStructElement::SetLang ( const wchar_t * alt )

pure virtual

Sets the Lang entry of a struct element.

Parameters

alt	String value to be set for the struct element Lang.

Returns: true if optaining the font state was succsessfull, false otherwise.

◆ SetTitle()

virtual bool PdsStructElement::SetTitle ( const wchar_t * title )

pure virtual

Sets the title associated with an element.

Parameters

title String value to be set for the specific Info dictionary entry.

Returns: true if optaining the font state was succsessfull, false otherwise.

◆ SetType()

virtual bool PdsStructElement::SetType ( const wchar_t * type )

pure virtual

Sets the struct element type.

Parameters

type	The name representing the element's type.

Returns: true if optaining the font state was succsessfull, false otherwise.

◆ ValidChild()

virtual int PdsStructElement::ValidChild	(	int	version,
		PdsStructElement *	child )

pure virtual

Returns the permitted number of child type occurrences in the structure element.

Parameters

the	PDF version
parent	The child structure element.

Returns: The number of child's occurrences. 0 for not permitted relationship, 2 for any number of children.

Public Member Functions

Detailed Description

Member Function Documentation

◆ AddAnnot()

◆ AddAssociatedFile()

◆ AddAssociatedHeader()

◆ AddAttrObj()

◆ AddChild()

◆ AddNewChild()

◆ AddPageObject()

◆ GetAbbreviation()

◆ GetActualText()

◆ GetAlt()

◆ GetAssociatedFile()

◆ GetAssociatedHeader()

◆ GetAttrObject()

◆ GetBBox()

◆ GetCell()

◆ GetCellElemParams()

◆ GetCellParams()

◆ GetChildMcid()

◆ GetChildObject()

◆ GetChildPageNumber()

◆ GetChildType()

◆ GetId()

◆ GetLang()

◆ GetNumAssociatedFiles()

◆ GetNumAssociatedHeaders()

◆ GetNumAttrObjects()

◆ GetNumChildren()

◆ GetNumCol()

◆ GetNumPages()

◆ GetNumRow()

◆ GetObject()

◆ GetPageNumber()

◆ GetParentObject()

◆ GetStructTree()

◆ GetText()

◆ GetTitle()

◆ GetType()

◆ HasAnnot()

◆ HasContent()

◆ MoveChild()

◆ RecognizeTable()

◆ RemoveAssociatedHeader()

◆ RemoveAttrObj()

◆ RemoveChild()

◆ SetActualText()

◆ SetAlt()

◆ SetId()

◆ SetLang()

◆ SetTitle()

◆ SetType()

◆ ValidChild()