LayerPDSEdit_Layer
ObjectPDSElement

PDSElement 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.



Typedef Summary
 Typedef
 PDSElement
Represents PDF structural elements, which are nodes in a tree giving a PDF document's logical structure.
Callback Summary
 Callback
 PDSElementEnumUserPropertiesAsASTextProc
Callback for PDSElementEnumUserPropertiesAsASText().
 PDSElementEnumUserPropertiesAsCosObjProc
A callback for PDSElementEnumUserPropertiesAsCosObj().
Method Summary
 Method
 
void PDSElementAddAttrObj(INPDSElement element, INPDSAttrObj attrObj)
Associates the specified attribute object with an element at the element's current revision value.
 
void PDSElementAddClass(INPDSElement element, INASAtom classAtom)
Adds a class name to the element's list of classes to which it belongs at the element's current revision value.
 
Removes an element's ID, if it exists.
 
void PDSElementCreate(INPDDoc pdDoc, OUTPDSElement* element)
Creates a new (but empty) PDSElement.
 
Enumerates PDSElement objects, beneath the supplied PDSElement, that have user properties attributes/classes.
 
Enumerates the PDSElement object's user properties by traversing the list of attribute objects and class objects, calling the caller-supplied procedure for each entry in the properties array. The enumeration proc receives the property information as a pair of ASText objects, for the property name and the property value. The enumeration continues as long as the callback returns true, and halts when the proc returns false or all properties have been enumerated.
 
Enumerates the PDSElement object's user properties by traversing the list of attribute objects and class objects, calling the caller-supplied procedure for each entry in the properties array. The enumeration proc receives the property information as a Cos Dictionary, with contents as described in the PDF Reference. The enumeration continues as long as the callback returns true, and halts when the proc returns false or all properties have been enumerated.
 
ASErrorCode PDSElementExportUserProperties(PDSElement userPropsElement, ASBool wholeSubtree, ASBool includeHidden, ASBool flattenClasses, PDUserPropertiesXMLLabels xmlLabels, ASStm output)
Exports user properties of the specified PDSElement in XML.
 
Starting at the supplied structure element, this procedure follows the chain of parents (see PDSElementGetParent()) until a structure element is found that has user properties. If no such element is found (for example, the chain ended at the structure tree root), CosNull is returned.
 
ASInt32 PDSElementGetActualText(INPDSElement element, INASUns8* buffer)
Gets the actual text associated with the specified PDSElement. It returns the number of bytes in the text, or 0 if the element has no actual text or has an empty string.
 
Gets the actual text associated with the specified PDSElement as an ASText object.
 
ASInt32 PDSElementGetAlt(INPDSElement element, INASUns8* buffer)
Gets the alternate text associated with an element.
 
Gets the alternate text associated with the specified PDSElement as an ASText object.
 
ASInt32 PDSElementGetAttrObj(INPDSElement element, INASInt32 index, OUTPDSAttrObj* attrObj)
Gets the attribute object at a specified array index in the specified element.
 
ASInt32 PDSElementGetClass(INPDSElement element, INASInt32 index, OUTASAtom* classAtom)
Gets the class name at an array index in the specified element.
 
Gets the Cos object corresponding to the specified element object. This method does not copy the object, but is instead the logical equivalent of a type cast.
 
CosObj PDSElementGetFirstPage(INPDSElement pdsElement, OUTASAtom* firstKidType, OUTCosObj* firstCosObjKidOnAPage, OUTPDEContainer* firstMCKidOnAPage)
Gets the Cos object for the page of the first kid of the element.
 
ASInt32 PDSElementGetID(INPDSElement pdsElement, OUTASUns8* idBuf)
Gets the ID of an element, or CosObjNull if there is no ID set.
 
ASAtom PDSElementGetKid(INPDSElement element, INASInt32 index, OUTCosObj* cosObjKid, OUT void** pointerKid, OUTCosObj* cosPage)
Gets the kid at an array index in the specified element.
 
ASAtom PDSElementGetKidEx(INPDSElement element, INASInt32 index, OUTCosObj* cosObjKid, OUTASInt32* mcid, OUT void** pointerKid, OUTCosObj* cosPage)
Functions identically to PDSElementGetKid(), but for children that are marked contents can return the mcid as well as or instead of the actual object.
 
ASAtom PDSElementGetKidWithMCInfo(PDSElement element, ASInt32 index, CosObj* cosObjKid, PDSMCInfoP mcidInfo, void** pointerKid, CosObj* cosPage)
Functions identically to PDSElementGetKidEx(), but returns additional information about marked content kids that are in streams other than the page content streams.
 
ASInt32 PDSElementGetLanguage(INPDSElement element, INASUns8* buffer)
Gets the language associated with the specified PDSElement.
 
Gets the number of attribute objects directly attached to the specified element.
 
Gets the number of classes to which the specified element belongs.
 
ASInt32 PDSElementGetNumKids(INPDSElement element)
Gets the number of kids of the specified element.
 
void PDSElementGetParent(INPDSElement element, OUTPDSElement* parent, OUTASBool* parentIsTreeRoot)
Gets the immediate ancestor element of the specified element in the tree.
 
Gets the revision number of an element.
 
ASBool PDSElementGetStructTreeRoot(INPDSElement element, OUTPDSTreeRoot* treeRoot)
Gets the structure tree root of the document containing element.
 
ASInt32 PDSElementGetTitle(INPDSElement element, OUTASUns8* buffer)
Gets the title of the specified element, returning the number of bytes in the title.
 
Gets the title associated with the specified PDSElement as an ASText object.
 
ASAtom PDSElementGetType(INPDSElement element)
Gets the element's structural element type. The type corresponds to the Subtype key in the structure element dictionary.
 
Tests whether ActualText is defined for a given PDSElement.
 
ASBool PDSElementHasAlt(INPDSElement element)
Tests whether Alt text is defined for a given PDSElement.
 
Tests whether a language string is defined for a given PDSElement.
 
Returns true if the PDSElement has attribute objects or class objects with an owner of UserProperties.
 
Increments an element's revision count by one.
 
void PDSElementInsertKid(INPDSElement element, INPDSElement kid, INASInt32 insertAfter)
Inserts the specified kid PDSElement object into the specified element after position insertAfter.
 
void PDSElementInsertMCAsKid(INPDSElement element, INCosObj cosPage, INPDSMC mc, INASInt32 insertAfter)
Inserts a reference to the specified PDSMC (marked content) in the specified element after position insertAfter.
 
void PDSElementInsertMCAsKidEx(INPDSElement element, INCosObj cosPage, INPDSMC mc, INASInt32 insertAfter, INCosObj cosStream, INCosObj streamOwner)
Extends PDSElementInsertMCAsKid(), inserting content that is in a stream other than a page content stream. This function is the same as PDSElementInsertStmMCAsKid().
 
ASBool PDSElementInsertMCRefAsKid(INPDSElement element, INPDSMCRef ref, INASInt32 insertAfter)
Takes a marked content reference and places the content that it identifies in the structure as a child of the element.
 
void PDSElementInsertOBJAsKid(INPDSElement element, INCosObj cosPage, INCosObj obj, INASInt32 insertAfter)
Inserts a reference to the specified PDF object as a kid into the specified element.
 
void PDSElementInsertStmMCAsKid(PDSElement element, CosObj cosPage, CosObj containingStm, CosObj stmOwner, PDSMC mc, ASInt32 insertAfter)
Inserts a marked content sequence from a non-page-content stream as a kid of the specified element.
 
Removes all attribute objects directly associated with the specified element.
 
Removes all classes from the specified element.
 
void PDSElementRemoveAttrObj(INPDSElement element, INPDSAttrObj attrObj)
Removes the specified attribute object from an element. If element does not have an attrObj attribute, this method does nothing.
 
void PDSElementRemoveClass(INPDSElement element, INASAtom classAtom)
Removes the specified class name from the element's list of classes to which it belongs.
 
void PDSElementRemoveKid(INPDSElement element, INCosObj kid)
Removes the specified kid from an element.
 
void PDSElementRemoveKidMC(INPDSElement element, INCosObj cosPage, INPDSMC mc)
Removes the specified PDSMC (marked content) from an element's kids, if it has any.
 
Removes an OBJ from among the kids of a given element. It does nothing if the given OBJ is not a kid of the given element.
 
void PDSElementReplaceKid(INPDSElement element, INCosObj oldKid, INCosObj newKid)
Replaces the specified kid in the specified element.
 
void PDSElementReplaceKidMC(INPDSElement element, INCosObj oldCosPage, INPDSMC oldMC, INCosObj newCosPage, INPDSMC newMC)
Replaces the specified PDSMC (on oldCosPage) with a new PDSMC (on newCosPage) in the specified element.
 
void PDSElementReplaceKidOBJ(INPDSElement element, INCosObj oldObj, INCosObj newObj, INCosObj newPage)
Replaces oldObj with newObj on the specified page in the specified element.
 
void PDSElementSetActualText(INPDSElement element, const ASUns8* buffer, INASInt32 nBytes)
Sets the actual text representation of the specified PDSElement object's contents to buffer (from 0 to nBytes).
 
Sets an element's actual text.
 
void PDSElementSetAlt(INPDSElement element, const ASUns8* buffer, INASInt32 nBytes)
Sets the alternate text representation of an element's contents.
 
void PDSElementSetAltASText(PDSElement element, const ASText text)
Sets the alternate text representation of an element's contents (ASText version of PDSElementSetAlt).
 
void PDSElementSetID(INPDSElement element, const ASUns8* buffer, INASInt32 nBytes)
Sets the ID of an element to the given Cos string.
 
void PDSElementSetLanguage(INPDSElement element, const ASUns8* buffer, INASInt32 nBytes)
Sets the language field associated with the PDSElement to the buffer parameter's contents (from 0 to nBytes).
 
void PDSElementSetTitle(INPDSElement element, const ASUns8* buffer, INASInt32 nBytes)
Sets an element's title.
 
void PDSElementSetTitleASText(PDSElement element, const ASText title)
Sets an element's title.
 
void PDSElementSetType(INPDSElement element, INASAtom type)
Sets an element's type value to the specified type. The type corresponds to the Subtype key in the structure element dictionary.

Typedefs Detail
PDSElement 
Product availability: All
Platform availability: All

Syntax

typedef CosObj PDSElement;

Represents PDF structural elements, which are nodes in a tree giving a PDF document's logical structure.

See Also


File: PDSExpT.h
Line: 84


Callbacks Detail
PDSElementEnumUserPropertiesAsASTextProc 
Product availability: All
Platform availability: All

Syntax

ASBool (*PDSElementEnumUserPropertiesAsASTextProc)(ASText propName, ASText propVal, void *clientData)

Callback for PDSElementEnumUserPropertiesAsASText().


File: PDSExpT.h
Line: 242
PDSElementEnumUserPropertiesAsCosObjProc 
Product availability: All
Platform availability: All

Syntax

ASBool (*PDSElementEnumUserPropertiesAsCosObjProc)(CosObj propDict, void *clientData)

A callback for PDSElementEnumUserPropertiesAsCosObj().


File: PDSExpT.h
Line: 252

Method Detail
PDSElementAddAttrObj()
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementAddAttrObj(INPDSElement element, INPDSAttrObj attrObj)

Associates the specified attribute object with an element at the element's current revision value.

This may raise various exceptions.

Parameters

element — 

The element with which attrObj is associated.

 
attrObj — 

The attribute object to associate with element.

See Also

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h
Line: 273
PDSElementAddClass() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementAddClass(INPDSElement element, INASAtom classAtom)

Adds a class name to the element's list of classes to which it belongs at the element's current revision value.

This may raise various exceptions.

Parameters

element — 

IN/OUT The element to which a class is added.

 
classAtom — 

IN/OUT The ASAtom representing the class to add to element. If classAtom is already present among the element parameter's classes, it will not be added again.

See Also

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h
Line: 326
PDSElementClearID() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementClearID(INPDSElement element)

Removes an element's ID, if it exists.

Parameters

element — 

The element whose ID is removed.

See Also

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.
pdsErrBadPDF is raised if an error is found in the PDF file.

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h
Line: 584
PDSElementCreate() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementCreate(INPDDoc pdDoc, OUTPDSElement* element)

Creates a new (but empty) PDSElement.

This may raise various exceptions.

Parameters

pdDoc — 

The PDDoc in which the PDSElement is created.

 
element — 

(Filled by the method) The newly created PDSElement.

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h
Line: 214
PDSElementEnumKidsWithUserProperties() 
Product availability: All
Platform availability: All

Syntax

ASBool PDSElementEnumKidsWithUserProperties(PDSElement elem, EnumElementsWithUserPropertiesProc proc, void* clientData)

Enumerates PDSElement objects, beneath the supplied PDSElement, that have user properties attributes/classes.

The elements in a structure tree that have user properties form a virtual tree themselves; this procedure enumerates the children of the given structure element in this virtual tree. In other words, this procedure enumerates all the descendents(d) of the supplied structure element(e) such that PDSElementFindAncestorWithUserProperties(d) would return (e). The enumeration continues as long as the callback returns true, and halts when the proc returns false or all virtual children have been enumerated.

Parameters

elem — 

The PDSElement below which to search for elements with user properties.

 
proc — 

The client-supplied callback to call for each element found.

 
clientData — 

Client-supplied data to be passed to the client callback.

Returns

true if the enumeration completes, false if the enumeration callback returns false.

See Also

Since

PI_PDS_READ_VERSION >= 0x00070000

File: PDSReadProcs.h
Line: 996
PDSElementEnumUserPropertiesAsASText() 
Product availability: All
Platform availability: All

Syntax

ASBool PDSElementEnumUserPropertiesAsASText(PDSElement elem, PDSElementEnumUserPropertiesAsASTextProc proc, void* clientData, ASBool includeHidden)

Enumerates the PDSElement object's user properties by traversing the list of attribute objects and class objects, calling the caller-supplied procedure for each entry in the properties array. The enumeration proc receives the property information as a pair of ASText objects, for the property name and the property value. The enumeration continues as long as the callback returns true, and halts when the proc returns false or all properties have been enumerated.

Parameters

elem — 

The PDSElement whose user properties will be enumerated.

 
proc — 

The callback that is called for each user property item.

 
clientData — 

Client-supplied data to be passed to the client callback.

 
includeHidden — 

A boolean value indicating whether the client wants to be given property items that are marked as hidden.

Returns

true if the enumeration completes, false if the enumeration callback returns false.

See Also

Since

PI_PDS_READ_VERSION >= 0x00070000

File: PDSReadProcs.h
Line: 932
PDSElementEnumUserPropertiesAsCosObj() 
Product availability: All
Platform availability: All

Syntax

ASBool PDSElementEnumUserPropertiesAsCosObj(PDSElement elem, PDSElementEnumUserPropertiesAsCosObjProc proc, void* clientData, ASBool includeHidden)

Enumerates the PDSElement object's user properties by traversing the list of attribute objects and class objects, calling the caller-supplied procedure for each entry in the properties array. The enumeration proc receives the property information as a Cos Dictionary, with contents as described in the PDF Reference. The enumeration continues as long as the callback returns true, and halts when the proc returns false or all properties have been enumerated.

Parameters

elem — 

The PDSElement whose user properties will be enumerated.

 
proc — 

The callback that is called for each user property item.

 
clientData — 

Client-supplied data to be passed to the client callback.

 
includeHidden — 

A boolean value indicating whether the client wants to be given property items that are marked as hidden.

Returns

true if the enumeration completes, false if the enumeration callback returns false.

See Also

Since

PI_PDS_READ_VERSION >= 0x00070000

File: PDSReadProcs.h
Line: 956
PDSElementExportUserProperties() 
Product availability: All
Platform availability: All

Syntax

ASErrorCode PDSElementExportUserProperties(PDSElement userPropsElement, ASBool wholeSubtree, ASBool includeHidden, ASBool flattenClasses, PDUserPropertiesXMLLabels xmlLabels, ASStm output)

Exports user properties of the specified PDSElement in XML.

Parameters

userPropsElement — 

The element whose user properties are to be exported in XML format.

 
wholeSubtree — 

A boolean value indicating whether to export user properties of the whole structure tree which contains userPropsElement, or just the subtree which starts from userPropsElement.

 
includeHidden — 

A boolean value indicating whether the client wants to be given property items that are marked as hidden.

 
flattenClasses — 

A boolean value indicating whether to flatten the attribute classes for each structure element. If true, the user properties for that class will be listed as properties for that stucture element. If false, the class will be listed for that structure element, and a list of classes and their properties will be listed near the end of the XML.

 
xmlLabels — 

The XML tag/label information for exporting user properties. These labels are output as is. There is no XML escaping done. It is the caller's responsibility to make sure they conform to the XML standard.

 
output — 

The output stream to which user properties are written. The encoding of the characters is UTF-8.

Returns

An ASErrorCode to indicate the success of exporting user properties in XML format. If ASErrorCode is 0, it indicates success in exporting user properties; non-zero value indicates otherwise.

See Also

Since

PI_PDS_READ_VERSION >= 0x00080000

File: PDSReadProcs.h
Line: 1072
PDSElementFindAncestorWithUserProperties() 
Product availability: All
Platform availability: All

Syntax

PDSElement PDSElementFindAncestorWithUserProperties(PDSElement elem)

Starting at the supplied structure element, this procedure follows the chain of parents (see PDSElementGetParent()) until a structure element is found that has user properties. If no such element is found (for example, the chain ended at the structure tree root), CosNull is returned.

Parameters

elem — 

The PDSElement at which to start searching upwards through the tree.

Returns

The first ancestor of elem that contains UserProperties attributes or class information, or CosNull if none is found.

See Also

Since

PI_PDS_READ_VERSION >= 0x00070000

File: PDSReadProcs.h
Line: 970
PDSElementGetActualText() 
Product availability: All
Platform availability: All

Syntax

ASInt32 PDSElementGetActualText(INPDSElement element, INASUns8* buffer)

Gets the actual text associated with the specified PDSElement. It 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. To get the needed size of buffer, call this method with a NULL buffer.

Parameters

element — 

The structural element whose actual text is sought.

 
buffer — 

If not NULL, buffer contains the element's actual text. The string is NULL-terminated (but not correctly for Unicode). This is not a C-style string, so normal string handling functions may not work; the buffer may contain a Unicode string.

Returns

An ASInt32 representing the number of bytes in the text, or 0 if the element has no actual text.

See Also

Since

PI_PDS_READ_VERSION >= 0x00050000

File: PDSReadProcs.h
Line: 698
PDSElementGetActualTextASText() 
Product availability: All
Platform availability: All

Syntax

void PDSElementGetActualTextASText(PDSElement element, ASText text)

Gets the actual text associated with the specified PDSElement as an ASText object.

Parameters

element — 

The element whose actual text is sought.

 
text — 

(Filled by the method) The text object containing the element's actual text. The client must pass a valid ASText object. The routine does not allocate it.

See Also

Since

PI_PDS_READ_VERSION >= 0x00080000

File: PDSReadProcs.h
Line: 1026
PDSElementGetAlt() 
Product availability: All
Platform availability: All

Syntax

ASInt32 PDSElementGetAlt(INPDSElement element, INASUns8* buffer)

Gets the alternate text associated with an element.

It can first be called with a NULL buffer to find the size, so that buffer can then be appropriately sized.

Parameters

element — 

The element whose alternate text is obtained.

 
buffer — 

(Filled by the method) A buffer into which the alternate text is placed. It may be NULL, if the method is called only to find the length of the element's alternate text. If it is not NULL, buffer contains the element's actual text. The string is NULL-terminated (but not correctly for Unicode). This is not a C-style string, so normal string handling functions may not work; the buffer may contain a Unicode string.

Returns

The number of bytes in the element parameter's alternate text.

See Also

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.

Since

PI_PDS_READ_VERSION >= 0x00040000

File: PDSReadProcs.h
Line: 345
PDSElementGetAltASText() 
Product availability: All
Platform availability: All

Syntax

void PDSElementGetAltASText(PDSElement element, ASText text)

Gets the alternate text associated with the specified PDSElement as an ASText object.

Parameters

element — 

The element whose alternate text is sought.

 
text — 

(Filled by the method) The text object containing the element's alternate text. The client must pass a valid ASText object. The routine does not allocate it.

See Also

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.

Since

PI_PDS_READ_VERSION >= 0x00080000

File: PDSReadProcs.h
Line: 1044
PDSElementGetAttrObj() 
Product availability: All
Platform availability: All

Syntax

ASInt32 PDSElementGetAttrObj(INPDSElement element, INASInt32 index, OUTPDSAttrObj* attrObj)

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

element — 

IN/OUT The element whose attribute is obtained.

 
index — 

IN/OUT The index of the attribute object to obtain.

 
attrObj — 

IN/OUT (Filled by the method) The attribute object at index.

Returns

The revision number of element at time of last association.

See Also

Exceptions

pdsErrRequiredMissing
pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.

Since

PI_PDS_READ_VERSION >= 0x00040000

File: PDSReadProcs.h
Line: 274
PDSElementGetClass() 
Product availability: All
Platform availability: All

Syntax

ASInt32 PDSElementGetClass(INPDSElement element, INASInt32 index, OUTASAtom* classAtom)

Gets the class name at an array index in the specified element.

If there is only one attribute object (that is, there is no array), and index is zero, that class name is obtained.

Parameters

element — 

The element whose class is obtained.

 
index — 

The index of the class to obtain.

 
classAtom — 

(Filled by the method) The ASAtom describing the class.

Returns

The revision number of element at the time of the last association.

See Also

Exceptions

pdsErrRequiredMissing
pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.

Since

PI_PDS_READ_VERSION >= 0x00040000

File: PDSReadProcs.h
Line: 312
PDSElementGetCosObj() 
Product availability: All
Platform availability: All

Syntax

CosObj PDSElementGetCosObj(PDSElement element)

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

Parameters

element — 

The element object whose Cos object is obtained.

Returns

The dictionary Cos object for the element object.

Since

PI_PDS_READ_VERSION >= 0x00060000

File: PDSReadProcs.h
Line: 855
PDSElementGetFirstPage() 
Product availability: All
Platform availability: All

Syntax

CosObj PDSElementGetFirstPage(INPDSElement pdsElement, OUTASAtom* firstKidType, OUTCosObj* firstCosObjKidOnAPage, OUTPDEContainer* firstMCKidOnAPage)

Gets the Cos object for the page of the first kid of the element.

This may throw various exceptions.

Parameters

pdsElement — 

IN/OUT The element whose kid's first page is found.

 
firstKidType — 

IN/OUT (Filled by the method) A pointer to an ASAtom for the name that appears as the Type entry of the actual first kid of element. Possible values are the values that PDSElementGetKid() can return. Pass NULL to inhibit setting firstKidType.

 
firstCosObjKidOnAPage — 

IN/OUT (Filled by the method) The kid whose content determined that the page returned was the first page with content, if that kid is a CosObj. Pass NULL to inhibit setting firstCosObjKidOnAPage.

 
firstMCKidOnAPage — 

IN/OUT (Filled by the method) The kid whose content determined that the page returned was the first page with content, if that kid is marked content that is not a CosObj. Pass NULL to inhibit setting firstMCKidOnAPage.

Returns

The CosObj of the page found, CosObjNull if the element has no page content.

See Also

Since

PI_PDS_READ_VERSION >= 0x00040000

File: PDSReadProcs.h
Line: 450
PDSElementGetID() 
Product availability: All
Platform availability: All

Syntax

ASInt32 PDSElementGetID(INPDSElement pdsElement, OUTASUns8* idBuf)

Gets the ID of an element, or CosObjNull if there is no ID set.

Parameters

pdsElement — 

The element whose ID is obtained.

 
idBuf — 

(Filled by the method) A pointer to the buffer containing the element's ID.

Returns

The number of bytes in the ID, or zero if the element has no ID.

See Also

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.
pdsErrBadPDF is raised if an error is found in the PDF file.

Since

PI_PDS_READ_VERSION >= 0x00040000

File: PDSReadProcs.h
Line: 470
PDSElementGetKid() 
Product availability: All
Platform availability: All

Syntax

ASAtom PDSElementGetKid(INPDSElement element, INASInt32 index, OUTCosObj* cosObjKid, OUT void** pointerKid, OUTCosObj* cosPage)

Gets the kid at an array index in the specified element.

A PDF structural element, unlike the structure tree root, can have several different kinds of children: marked content, another element, or an entire PDF object. The parameter in which the kid is placed depends on the type of kid. If the kid is a structural element or an object reference, PDSElementGetKid() places the result in cosObjKid; if the kid is page content, it is placed in pointerKid.

Any or all of cosObjKid, pointerKid, and cosPage can be NULL to get the kid's type without setting that parameter.

Parameters

element — 

The element whose specified kid is found.

 
index — 

The index of the kid to obtain.

 
cosObjKid — 

(Filled by the method) The CosObj of the specified kid, if that kid is a PDSElement or an OBJR. If cosObjKid is NULL, it is not filled in, but the type of the kid is returned regardless. Note that this CosObj can be treated as a PDSElement or a PDSObjR. Use the return type to decide which to use.

 
pointerKid — 

(Filled by the method) A pointer to the kid at index, if that kid is an MC. If pointerKid is NULL, it is not filled in, but the type of the kid is returned regardless.

 
cosPage — 

(Filled by the method) A pointer to the CosObj of the page containing the kid. If cosPage is NULL, it is not filled in, but the type of the kid is returned regardless.

Returns

The ASAtom representing the kid's Type value: StructElem, MC, or OBJR. MCR is never returned.

See Also

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.
pdsErrBadPDF is raised if an error is found in the PDF file.

Since

PI_PDS_READ_VERSION >= 0x00040000

File: PDSReadProcs.h
Line: 414
PDSElementGetKidEx() 
Product availability: All
Platform availability: All

Syntax

ASAtom PDSElementGetKidEx(INPDSElement element, INASInt32 index, OUTCosObj* cosObjKid, OUTASInt32* mcid, OUT void** pointerKid, OUTCosObj* cosPage)

Functions identically to PDSElementGetKid(), but for children that are marked contents can return the mcid as well as or instead of the actual object.

Parameters

element — 

The PDSElement containing the kid that is retrieved.

 
index — 

The index of the kid.

 
cosObjKid — 

(Filled in by method) The kid being accessed (depending on the kid's type) or NULL.

 
mcid — 

(Filled in by method) The kid's mcid or NULL.

 
pointerKid — 

(Filled in by method) A pointer to the kid, or NULL.

 
cosPage — 

(Filled in by method) The CosObj of the page containing the kid, or NULL.

Returns

An ASAtom representing the Type value of the kid. See above.

See Also

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.
pdsErrBadPDF is raised if an error is found in the PDF file.

Since

PI_PDS_READ_VERSION >= 0x00050000

File: PDSReadProcs.h
Line: 671
PDSElementGetKidWithMCInfo() 
Product availability: All
Platform availability: All

Syntax

ASAtom PDSElementGetKidWithMCInfo(PDSElement element, ASInt32 index, CosObj* cosObjKid, PDSMCInfoP mcidInfo, void** pointerKid, CosObj* cosPage)

Functions identically to PDSElementGetKidEx(), but returns additional information about marked content kids that are in streams other than the page content streams.

Parameters

element — 

The PDSElement containing the kid that is retrieved.

 
index — 

The index of the kid.

 
cosObjKid — 

(Filled in by method) The kid being accessed (depending on the kid's type), or NULL.

 
mcidInfo — 

(Filled in by method) The kid's information object, or NULL.

 
pointerKid — 

(Filled in by method) A pointer to the kid, or NULL.

 
cosPage — 

(Filled in by method) The CosObj of the page containing the kid, or NULL.

Returns

An ASAtom representing the Type value of the kid.

See Also

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.
pdsErrBadPDF is raised if an error is found in the PDF file.

Since

PI_PDS_READ_VERSION >= 0x00060000

File: PDSReadProcs.h
Line: 791
PDSElementGetLanguage() 
Product availability: All
Platform availability: All

Syntax

ASInt32 PDSElementGetLanguage(INPDSElement element, INASUns8* buffer)

Gets the language associated with the specified PDSElement.

It returns the number of bytes in the language string, or 0 if the element has no language or has an empty string.

To check for the existence of expansion text, call PDSElementHasLanguage(). To get the needed buffer size, call this method with a NULL buffer.

Parameters

element — 

The structural element whose expansion text is sought.

 
buffer — 

(Filled by the method) A buffer containing the element's expansion text, or NULL. See PDSElementSetLanguage() for format and languages. If not NULL, buffer contains the element's expansion text. The string is NULL-terminated (but not correctly for Unicode). This is not a C-style string, so normal string handling functions may not work; the buffer may contain a Unicode string.

Returns

An ASInt32 representing the number of bytes in the language string.

See Also

Since

PI_PDS_READ_VERSION >= 0x00050000

File: PDSReadProcs.h
Line: 729
PDSElementGetNumAttrObjs() 
Product availability: All
Platform availability: All

Syntax

ASInt32 PDSElementGetNumAttrObjs(INPDSElement element)

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

Parameters

element — 

IN/OUT The element whose number of attributes is obtained.

Returns

The number of attribute objects directly attached to element.

See Also

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.

Since

PI_PDS_READ_VERSION >= 0x00040000

File: PDSReadProcs.h
Line: 247
PDSElementGetNumClasses() 
Product availability: All
Platform availability: All

Syntax

ASInt32 PDSElementGetNumClasses(INPDSElement element)

Gets the number of classes to which the specified element belongs.

Parameters

element — 

The element whose number of classes is obtained.

Returns

The number of classes to which element belongs.

See Also

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.

Since

PI_PDS_READ_VERSION >= 0x00040000

File: PDSReadProcs.h
Line: 287
PDSElementGetNumKids() 
Product availability: All
Platform availability: All

Syntax

ASInt32 PDSElementGetNumKids(INPDSElement element)

Gets the number of kids of the specified element.

Parameters

element — 

IN/OUT The element whose number of kids is obtained.

Returns

The number of direct kids of element.

See Also

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.

Since

PI_PDS_READ_VERSION >= 0x00040000

File: PDSReadProcs.h
Line: 357
PDSElementGetParent() 
Product availability: All
Platform availability: All

Syntax

void PDSElementGetParent(INPDSElement element, OUTPDSElement* parent, OUTASBool* parentIsTreeRoot)

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 and parentIsTreeRoot is set to false. If the element's parent is the structure tree root, parent is set to CosNull and parentIsTreeRoot is set to true. If parentIsTreeRoot is NULL, it is not set.

Parameters

element — 

The element whose parent is obtained.

 
parent — 

(Filled by the method) The element's parent.

 
parentIsTreeRoot — 

(Filled by the method) The element's parent is the structure tree root.

See Also

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.

Since

PI_PDS_READ_VERSION >= 0x00040000

File: PDSReadProcs.h
Line: 197
PDSElementGetRevision() 
Product availability: All
Platform availability: All

Syntax

ASInt32 PDSElementGetRevision(INPDSElement element)

Gets the revision number of an element.

Parameters

element — 

IN/OUT The element whose revision is obtained.

Returns

The revision number of element.

See Also

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.

Since

PI_PDS_READ_VERSION >= 0x00040000

File: PDSReadProcs.h
Line: 233
PDSElementGetStructTreeRoot() 
Product availability: All
Platform availability: All

Syntax

ASBool PDSElementGetStructTreeRoot(INPDSElement element, OUTPDSTreeRoot* treeRoot)

Gets the structure tree root of the document containing element.

Parameters

element — 

The element whose title is obtained.

 
treeRoot — 

(Filled by the method) The structure tree root.

Returns

true if the document has a structure tree root, false otherwise. If there is a structure tree root, it sets treeRoot to be the structure tree root.

See Also

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.

Since

PI_PDS_READ_VERSION >= 0x00040000

File: PDSReadProcs.h
Line: 487
PDSElementGetTitle() 
Product availability: All
Platform availability: All

Syntax

ASInt32 PDSElementGetTitle(INPDSElement element, OUTASUns8* buffer)

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

It can first be called with a NULL buffer to find the title size, so that buffer can be appropriately sized as one greater than the title's length.

Parameters

element — 

IN/OUT The element whose title is obtained.

 
buffer — 

IN/OUT (Filled by the method) A buffer into which the title text is placed. It may be NULL, in which case the number of bytes in the title is returned.

Returns

The number of bytes in the element parameter's title, or zero if element has no title.

See Also

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.

Since

PI_PDS_READ_VERSION >= 0x00040000

File: PDSReadProcs.h
Line: 221
PDSElementGetTitleASText() 
Product availability: All
Platform availability: All

Syntax

void PDSElementGetTitleASText(PDSElement element, ASText title)

Gets the title associated with the specified PDSElement as an ASText object.

Parameters

element — 

The element whose title is sought.

 
title — 

(Filled by the method) The text object containing the title. The client must pass a valid ASText object. The routine does not allocate it.

See Also

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.

Since

PI_PDS_READ_VERSION >= 0x00080000

File: PDSReadProcs.h
Line: 1012
PDSElementGetType() 
Product availability: All
Platform availability: All

Syntax

ASAtom PDSElementGetType(INPDSElement element)

Gets the element's structural element type. The type corresponds to the Subtype key in the structure element dictionary.

PDSElementGetType() gets the value of the Subtype key (not the Type key) in the structure element dictionary. All PDSElement objects have a Type value of StructElem.

Parameters

element — 

The element whose structural element type is obtained.

Returns

The ASAtom representing element's type.

See Also

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.

Since

PI_PDS_READ_VERSION >= 0x00040000

File: PDSReadProcs.h
Line: 170
PDSElementHasActualText() 
Product availability: All
Platform availability: All

Syntax

ASBool PDSElementHasActualText(INPDSElement element)

Tests whether ActualText is defined for a given PDSElement.

Parameters

element — 

The PDSElement being tested.

Returns

true if text exists (including the empty string); false otherwise.

Since

PI_PDS_READ_VERSION >= 0x00050000

File: PDSReadProcs.h
Line: 750
PDSElementHasAlt() 
Product availability: All
Platform availability: All

Syntax

ASBool PDSElementHasAlt(INPDSElement element)

Tests whether Alt text is defined for a given PDSElement.

Parameters

element — 

The PDSElement being tested.

Returns

true if text exists (including the empty string); false otherwise.

See Also

Since

PI_PDS_READ_VERSION >= 0x00050000

File: PDSReadProcs.h
Line: 740
PDSElementHasLanguage() 
Product availability: All
Platform availability: All

Syntax

ASBool PDSElementHasLanguage(INPDSElement element)

Tests whether a language string is defined for a given PDSElement.

Parameters

element — 

The PDSElement being tested.

Returns

true if text exists (including the empty string); false otherwise.

Since

PI_PDS_READ_VERSION >= 0x00050000

File: PDSReadProcs.h
Line: 760
PDSElementHasUserProperties() 
Product availability: All
Platform availability: All

Syntax

ASBool PDSElementHasUserProperties(PDSElement elem)

Returns true if the PDSElement has attribute objects or class objects with an owner of UserProperties.

Parameters

elem — 

The PDSElement to examine.

Returns

ASBool indicating that some attribute objects or class objects have an owner of UserProperties.

Since

PI_PDS_READ_VERSION >= 0x00070000

File: PDSReadProcs.h
Line: 908
PDSElementIncrementRevision() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementIncrementRevision(INPDSElement element)

Increments an element's revision count by one.

This may raise various exceptions.

Parameters

element — 

The element whose revision count is incremented.

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h
Line: 258
PDSElementInsertKid() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementInsertKid(INPDSElement element, INPDSElement kid, INASInt32 insertAfter)

Inserts the specified kid PDSElement object into the specified element after position insertAfter.

Parameters

element — 

The element in which the specified kid is inserted.

 
kid — 

The kid to insert.

 
insertAfter — 

The position after which the kid is inserted. If element currently has no kids, insertAfter is ignored.

See Also

Exceptions

pdsErrWrongTypeParameter

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h
Line: 404
PDSElementInsertMCAsKid() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementInsertMCAsKid(INPDSElement element, INCosObj cosPage, INPDSMC mc, INASInt32 insertAfter)

Inserts a reference to the specified PDSMC (marked content) in the specified element after position insertAfter.

This method automatically creates MCR objects if needed.

This may raise various exceptions.

Parameters

element — 

The element in which the reference is inserted.

 
cosPage — 

The CosObj for the page containing the reference to insert.

 
mc — 

The marked content to insert.

 
insertAfter — 

The position after which the reference is inserted. If element currently has no kids, insertAfter is ignored.

See Also

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h
Line: 431
PDSElementInsertMCAsKidEx() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementInsertMCAsKidEx(INPDSElement element, INCosObj cosPage, INPDSMC mc, INASInt32 insertAfter, INCosObj cosStream, INCosObj streamOwner)

Extends PDSElementInsertMCAsKid(), inserting content that is in a stream other than a page content stream. This function is the same as PDSElementInsertStmMCAsKid().

This may raise various exceptions.

Parameters

element — 

The element in which the reference is inserted.

 
cosPage — 

The CosObj for the page containing the reference to insert.

 
mc — 

The marked content to insert.

 
insertAfter — 

The position after which the reference is inserted. If element currently has no kids, insertAfter is ignored.

 
cosStream — 

The stream containing the content given by mc.

 
streamOwner — 

A Cos object to record as the owner of the content. It can be CosNull if the owner is not important.

See Also

Since

PI_PDS_WRITE_VERSION >= 0x00060000

File: PDSWriteProcs.h
Line: 833
PDSElementInsertMCRefAsKid() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool PDSElementInsertMCRefAsKid(INPDSElement element, INPDSMCRef ref, INASInt32 insertAfter)

Takes a marked content reference and places the content that it identifies in the structure as a child of the element.

This may raise various exceptions.

Parameters

element — 

The structure element with which to associate marked content.

 
ref — 

The marked content reference describing the content on the page. It must have had a valid MCID, and must have been completed by subsequent content stream processing calls.

 
insertAfter — 

The position after which the marked content is inserted into the element's kids. If the element has no children, insertAfter is ignored.

Returns

See Also

Since

PI_PDS_WRITE_VERSION >= 0x00070000

File: PDSWriteProcs.h
Line: 953
PDSElementInsertOBJAsKid() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementInsertOBJAsKid(INPDSElement element, INCosObj cosPage, INCosObj obj, INASInt32 insertAfter)

Inserts a reference to the specified PDF object as a kid into the specified element.

This may raise various exceptions.

Parameters

element — 

IN/OUT The element in which the reference is inserted.

 
cosPage — 

IN/OUT The CosObj for the page containing the reference to insert.

 
obj — 

IN/OUT The CosObj to insert.

 
insertAfter — 

IN/OUT The position after which the reference is inserted in element. If element currently has no kids, insertAfter is ignored.

See Also

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h
Line: 453
PDSElementInsertStmMCAsKid() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementInsertStmMCAsKid(PDSElement element, CosObj cosPage, CosObj containingStm, CosObj stmOwner, PDSMC mc, ASInt32 insertAfter)

Inserts a marked content sequence from a non-page-content stream as a kid of the specified element.

This may raise various exceptions.

Parameters

element — 

The element in which the reference is inserted.

 
cosPage — 

The CosObj for the page containing the reference to insert.

 
containingStm — 

The stream containing the content given by mc.

 
stmOwner — 

The PDF object owning the stream given in cosStream (for example, the annotation to which an appearance stream belongs). It can be CosNull if the owner is not important.

 
mc — 

The marked content to insert.

 
insertAfter — 

The position after which the reference is inserted. If element currently has no kids, insertAfter is ignored.

See Also

Since

PI_PDS_WRITE_VERSION >= 0x00060000

File: PDSWriteProcs.h
Line: 866
PDSElementRemoveAllAttrObjs() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementRemoveAllAttrObjs(INPDSElement element)

Removes all attribute objects directly associated with the specified element.

Parameters

element — 

The element whose attributes are removed.

See Also

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h
Line: 308
PDSElementRemoveAllClasses() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementRemoveAllClasses(INPDSElement element)

Removes all classes from the specified element.

Parameters

element — 

IN/OUT The element whose classes are removed.

See Also

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h
Line: 364
PDSElementRemoveAttrObj() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementRemoveAttrObj(INPDSElement element, INPDSAttrObj attrObj)

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

Parameters

element — 

The element whose attribute is removed.

 
attrObj — 

The attribute object to remove.

See Also

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement or attrObj is not a valid attribute object.

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h
Line: 297
PDSElementRemoveClass() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementRemoveClass(INPDSElement element, INASAtom classAtom)

Removes the specified class name from the element's list of classes to which it belongs.

Parameters

element — 

The element from which the specified class is removed.

 
classAtom — 

The ASAtom representing the class to remove.

See Also

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h
Line: 351
PDSElementRemoveKid() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementRemoveKid(INPDSElement element, INCosObj kid)

Removes the specified kid from an element.

This may raise various exceptions.

Parameters

element — 

The element whose kid is removed.

 
kid — 

The kid to remove.

See Also

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h
Line: 470
PDSElementRemoveKidMC() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementRemoveKidMC(INPDSElement element, INCosObj cosPage, INPDSMC mc)

Removes the specified PDSMC (marked content) from an element's kids, if it has any.

After calling this method, use PDPageSetPDEContent() to commit any changes that have been made to the page contents.

This may raise various exceptions.

Parameters

element — 

The element whose reference is removed.

 
cosPage — 

The CosObj for the page containing the reference to remove.

 
mc — 

The marked content to remove.

See Also

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h
Line: 490
PDSElementRemoveKidOBJ() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementRemoveKidOBJ(INPDSElement element, INCosObj kid)

Removes an OBJ from among the kids of a given element. It does nothing if the given OBJ is not a kid of the given element.

This may raise various exceptions.

Parameters

element — 

The element whose kid is having an OBJ removed.

 
kid — 

The kid whose OBJ is removed.

See Also

Since

PI_PDS_WRITE_VERSION >= 0x00050000

File: PDSWriteProcs.h
Line: 800
PDSElementReplaceKid() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementReplaceKid(INPDSElement element, INCosObj oldKid, INCosObj newKid)

Replaces the specified kid in the specified element.

This may raise various exceptions.

Parameters

element — 

IN/OUT The element whose kid is replaced.

 
oldKid — 

IN/OUT The kid to replace.

 
newKid — 

IN/OUT The kid that is replacing oldKid.

See Also

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h
Line: 510
PDSElementReplaceKidMC() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementReplaceKidMC(INPDSElement element, INCosObj oldCosPage, INPDSMC oldMC, INCosObj newCosPage, INPDSMC newMC)

Replaces the specified PDSMC (on oldCosPage) with a new PDSMC (on newCosPage) in the specified element.

This may raise various exceptions.

Parameters

element — 

The element whose reference is replaced.

 
oldCosPage — 

The CosObj for the page holding the reference to replace.

 
oldMC — 

The marked content to replace.

 
newCosPage — 

The CosObj for the page holding the reference that is replacing oldMC.

 
newMC — 

The marked content that is replacing oldMC.

See Also

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h
Line: 530
PDSElementReplaceKidOBJ() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementReplaceKidOBJ(INPDSElement element, INCosObj oldObj, INCosObj newObj, INCosObj newPage)

Replaces oldObj with newObj on the specified page in the specified element.

This may raise various exceptions.

Parameters

element — 

IN/OUT The element whose object is replaced.

 
oldObj — 

IN/OUT The object to replace.

 
newObj — 

IN/OUT The object that is replacing oldObj.

 
newPage — 

IN/OUT The CosObj for the page holding the reference that is replacing oldObj.

See Also

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h
Line: 551
PDSElementSetActualText() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementSetActualText(INPDSElement element, const ASUns8* buffer, INASInt32 nBytes)

Sets the actual text representation of the specified PDSElement object's contents to buffer (from 0 to nBytes).

Parameters

element — 

The PDSElement whose contents are being set to buffer.

 
buffer — 

The buffer to which the PDSElement object's contents are being set.

 
nBytes — 

The number of bytes in the text representation.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: PDSWriteProcs.h
Line: 762
PDSElementSetActualTextASText() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementSetActualTextASText(PDSElement element, const ASText text)

Sets an element's actual text.

Parameters

element — 

The element whose content is being set.

 
text — 

The text object containing the string to be made the element's actual text.

See Also

Since

PI_PDS_WRITE_VERSION >= 0x00080000

File: PDSWriteProcs.h
Line: 983
PDSElementSetAlt() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementSetAlt(INPDSElement element, const ASUns8* buffer, INASInt32 nBytes)

Sets the alternate text representation of an element's contents.

Parameters

element — 

IN/OUT The element whose alternate text representation is set.

 
buffer — 

IN/OUT A pointer to a buffer containing a string to be made the element's alternate text representation.

 
nBytes — 

IN/OUT The number of bytes in buffer to use as the element parameter's new alternate text representation. It may be zero. It sets an Alt string even if the buffer length is zero, but such an Alt string looks like no Alt string according to PDSElementGetAlt().

See Also

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h
Line: 384
PDSElementSetAltASText() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementSetAltASText(PDSElement element, const ASText text)

Sets the alternate text representation of an element's contents (ASText version of PDSElementSetAlt).

Parameters

element — 

The element whose alternate text representation is being set.

 
text — 

The text object containing the string to be set as the element's alternate text representation.

See Also

Exceptions

Raises pdsErrWrongTypeParameter if element is not a valid PDSElement.

Since

PI_PDS_WRITE_VERSION >= 0x00080000

File: PDSWriteProcs.h
Line: 999
PDSElementSetID() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementSetID(INPDSElement element, const ASUns8* buffer, INASInt32 nBytes)

Sets the ID of an element to the given Cos string.

Parameters

element — 

The element whose ID is set.

 
buffer — 

A pointer to a buffer containing a string to be made the element's ID.

 
nBytes — 

The number of bytes in buffer to use as the element parameter's new ID. It may be zero. It sets an ID even if the buffer length is zero, but such an ID looks like no ID according to PDSElementGetID().

See Also

Exceptions

ErrSysPDSEdit is raised if another element already has the ID as its ID.
pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h
Line: 571
PDSElementSetLanguage() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementSetLanguage(INPDSElement element, const ASUns8* buffer, INASInt32 nBytes)

Sets the language field associated with the PDSElement to the buffer parameter's contents (from 0 to nBytes).

Parameters

element — 

The PDSElement whose language field is set to buffer.

 
buffer — 

A pointer to a buffer containing a string to be made the element's language field. The empty string indicates that the language is unknown. The string should be in the format <IETF RFC-1766-language-code>. Note that the ISO 639 language codes can be found at

 
nBytes — 

The size of buffer. It may be zero. It sets the language even if the buffer length is zero, but such a language setting looks like no language according to PDSElementGetLanguage.

See Also

Since

PI_PDS_WRITE_VERSION >= 0x00050000

File: PDSWriteProcs.h
Line: 784
PDSElementSetTitle() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementSetTitle(INPDSElement element, const ASUns8* buffer, INASInt32 nBytes)

Sets an element's title.

Parameters

element — 

IN/OUT The element whose title is set.

 
buffer — 

IN/OUT A pointer to a buffer containing a string to be made the element's title.

 
nBytes — 

IN/OUT The number of bytes in buffer to use as the element parameter's new title. It may be zero. It sets a title even if the buffer length is zero, but such a title looks like no title according to PDSElementGetTitle().

See Also

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h
Line: 248
PDSElementSetTitleASText() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementSetTitleASText(PDSElement element, const ASText title)

Sets an element's title.

Parameters

element — 

The element whose title is being set.

 
title — 

The text object containing the string to be made the element's title.

See Also

Exceptions

Raises pdsErrWrongTypeParameter if element is not a valid PDSElement.

Since

PI_PDS_WRITE_VERSION >= 0x00080000

File: PDSWriteProcs.h
Line: 969
PDSElementSetType() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDSElementSetType(INPDSElement element, INASAtom type)

Sets an element's type value to the specified type. The type corresponds to the Subtype key in the structure element dictionary.

PDSElementSetType() sets the value of the Subtype key, not the Type key, in the structure element dictionary. All PDSElement objects have a Type value of StructElem.

Parameters

element — 

The element whose type is set.

 
type — 

The ASAtom representing the element's type.

See Also

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h
Line: 232