PDSEdit_Layer.PDSElement (PDFL)

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

	Callback
	PDSElementEnumUserPropertiesAsASTextProc Callback for PDSElementEnumUserPropertiesAsASText().
	PDSElementEnumUserPropertiesAsCosObjProc A callback for PDSElementEnumUserPropertiesAsCosObj().

	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.
	void PDSElementClearID(INPDSElement element) Removes an element's ID, if it exists.
	void PDSElementCreate(INPDDoc pdDoc, OUTPDSElement* element) Creates a new (but empty) PDSElement.
	ASBool PDSElementEnumKidsWithUserProperties(PDSElement elem, EnumElementsWithUserPropertiesProc proc, void* clientData) Enumerates PDSElement objects, beneath the supplied PDSElement, that have user properties attributes/classes.
	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.
	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.
	ASErrorCode PDSElementExportUserProperties(PDSElement userPropsElement, ASBool wholeSubtree, ASBool includeHidden, ASBool flattenClasses, PDUserPropertiesXMLLabels xmlLabels, ASStm output) Exports user properties of the specified PDSElement in XML.
	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.
	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.
	void PDSElementGetActualTextASText(PDSElement element, ASText text) 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.
	void PDSElementGetAltASText(PDSElement element, ASText text) 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.
	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.
	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.
	ASInt32 PDSElementGetNumAttrObjs(INPDSElement element) Gets the number of attribute objects directly attached to the specified element.
	ASInt32 PDSElementGetNumClasses(INPDSElement 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.
	ASInt32 PDSElementGetRevision(INPDSElement element) 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.
	void PDSElementGetTitleASText(PDSElement element, ASText 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.
	ASBool PDSElementHasActualText(INPDSElement element) Tests whether ActualText is defined for a given PDSElement.
	ASBool PDSElementHasAlt(INPDSElement element) Tests whether Alt text is defined for a given PDSElement.
	ASBool PDSElementHasLanguage(INPDSElement element) Tests whether a language string is defined for a given PDSElement.
	ASBool PDSElementHasUserProperties(PDSElement elem) Returns true if the PDSElement has attribute objects or class objects with an owner of UserProperties.
	void PDSElementIncrementRevision(INPDSElement element) 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.
	void PDSElementRemoveAllAttrObjs(INPDSElement element) Removes all attribute objects directly associated with the specified element.
	void PDSElementRemoveAllClasses(INPDSElement 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.
	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.
	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).
	void PDSElementSetActualTextASText(PDSElement element, const ASText text) 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: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax

typedef CosObj PDSElement;

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

File: PDSExpT.h

Line: 84

Callbacks Detail

PDSElementEnumUserPropertiesAsASTextProc

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax

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

Callback for PDSElementEnumUserPropertiesAsASText().

File: PDSExpT.h

Line: 242

PDSElementEnumUserPropertiesAsCosObjProc

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax

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

A callback for PDSElementEnumUserPropertiesAsCosObj().

File: PDSExpT.h

Line: 252

Method Detail

PDSElementAddAttrObj

()

Product availability: 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`.

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h

Line: 273

PDSElementAddClass

()

Product availability: 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.

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h

Line: 326

PDSElementClearID

()

Product availability: 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

PDSElementGetID
PDSElementSetID

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

Platform availability: Macintosh, Windows, UNIX

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.

Since

PI_PDS_READ_VERSION >= 0x00070000

File: PDSReadProcs.h

Line: 996

PDSElementEnumUserPropertiesAsASText

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

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

PDSElementEnumUserPropertiesAsCosObj

Since

PI_PDS_READ_VERSION >= 0x00070000

File: PDSReadProcs.h

Line: 932

PDSElementEnumUserPropertiesAsCosObj

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

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

PDSElementEnumUserPropertiesAsASText

Since

PI_PDS_READ_VERSION >= 0x00070000

File: PDSReadProcs.h

Line: 956

PDSElementExportUserProperties

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

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

PDUserPropertiesXMLLabels

Since

PI_PDS_READ_VERSION >= 0x00080000

File: PDSReadProcs.h

Line: 1072

PDSElementFindAncestorWithUserProperties

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

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

PDSElementEnumKidsWithUserProperties

Since

PI_PDS_READ_VERSION >= 0x00070000

File: PDSReadProcs.h

Line: 970

PDSElementGetActualText

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

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

PDSElementSetActualText

Since

PI_PDS_READ_VERSION >= 0x00050000

Note

Due to implementation issues, make the buffer one byte larger than the required size. Code will not NULL-terminate the string correctly in the case of Unicode strings.

File: PDSReadProcs.h

Line: 698

PDSElementGetActualTextASText

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

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.

Since

PI_PDS_READ_VERSION >= 0x00080000

File: PDSReadProcs.h

Line: 1026

PDSElementGetAlt

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

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

PDSElementSetAlt
PDSElementHasAlt

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.

Since

PI_PDS_READ_VERSION >= 0x00040000

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 PDSElementHasAlt() first.
Due to implementation issues, make the buffer one byte larger than the required size. The code will not NULL-terminate the string correctly in the case of Unicode strings.

File: PDSReadProcs.h

Line: 345

PDSElementGetAltASText

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

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.

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

Platform availability: Macintosh, Windows, UNIX

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.

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

Platform availability: Macintosh, Windows, UNIX

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.

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

Platform availability: Macintosh, Windows, UNIX

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

Platform availability: Macintosh, Windows, UNIX

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

PDSElementGetKid

Since

PI_PDS_READ_VERSION >= 0x00040000

Note

The order in which the returned page is first is the order of kids, not the order of pages. That is, the first descendant with page content determines which page is returned.

File: PDSReadProcs.h

Line: 450

PDSElementGetID

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

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.

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

Platform availability: Macintosh, Windows, UNIX

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.

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

Note

When the kid is an MC, it is actually a pointer of the type PDEContainer. As with all PDFEdit objects, you must be careful to manage the reference count of the object by calling PDEAcquire() and PDERelease(). PDSElementGetKid() does not call PDEAcquire() for you.
This method cannot access marked content inside a Form XObject.

File: PDSReadProcs.h

Line: 414

PDSElementGetKidEx

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

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.

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

Note

This method cannot access marked content inside a Form XObject.

File: PDSReadProcs.h

Line: 671

PDSElementGetKidWithMCInfo

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

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

PDSElementGetKid
PDSElementGetKidEx

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

Platform availability: Macintosh, Windows, UNIX

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.

Since

PI_PDS_READ_VERSION >= 0x00050000

Note

Due to implementation issues, make the buffer one byte larger than the required size. Code will not NULL-terminate the string correctly in the case of Unicode strings.

File: PDSReadProcs.h

Line: 729

PDSElementGetNumAttrObjs

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

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

PDSElementGetAttrObj

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

Platform availability: Macintosh, Windows, UNIX

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

PDSElementGetClass

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

Platform availability: Macintosh, Windows, UNIX

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

PDSElementGetKid

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

Platform availability: Macintosh, Windows, UNIX

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.

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

Platform availability: Macintosh, Windows, UNIX

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

PDSElementIncrementRevision

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

Platform availability: Macintosh, Windows, UNIX

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

PDSTreeRootGetKid

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

Platform availability: Macintosh, Windows, UNIX

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

PDSElementSetTitle

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.

Since

PI_PDS_READ_VERSION >= 0x00040000

Note

Due to implementation issues, make the buffer one byte larger than the required size.

File: PDSReadProcs.h

Line: 221

PDSElementGetTitleASText

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

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.

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

Platform availability: Macintosh, Windows, UNIX

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

PDSElementSetType

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

Platform availability: Macintosh, Windows, UNIX

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

Platform availability: Macintosh, Windows, UNIX

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

PDSElementGetAlt

Since

PI_PDS_READ_VERSION >= 0x00050000

File: PDSReadProcs.h

Line: 740

PDSElementHasLanguage

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

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

Platform availability: Macintosh, Windows, UNIX

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

Exceptions

pdsErrWrongTypeParameter

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h

Line: 404

PDSElementInsertMCAsKid

()

Product availability: 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.

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h

Line: 431

PDSElementInsertMCAsKidEx

()

Product availability: 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.

Since

PI_PDS_WRITE_VERSION >= 0x00060000

File: PDSWriteProcs.h

Line: 833

PDSElementInsertMCRefAsKid

()

Product availability: 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

PDSMCRefCreate

Since

PI_PDS_WRITE_VERSION >= 0x00070000

Note

the content reference handle will be filled out automatically if PDPageSetPDEContent(), PDEFormSetContent(), or PDEGroupSetContent() is called. Otherwise, PDEContentSetPage() or PDEContentSetContainingStmAndOwner() must be called explicitly.

File: PDSWriteProcs.h

Line: 953

PDSElementInsertOBJAsKid

()

Product availability: 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

PDSElementReplaceKidOBJ

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h

Line: 453

PDSElementInsertStmMCAsKid

()

Product availability: 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.

Since

PI_PDS_WRITE_VERSION >= 0x00060000

File: PDSWriteProcs.h

Line: 866

PDSElementRemoveAllAttrObjs

()

Product availability: 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

PDSElementRemoveAttrObj

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

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

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

Note

Calling PDSElementRemoveAttrObj() while iterating over the attribute objects of an element will change the relationship between the attribute object indices and attribute objects. Although it is possible to track this change in indices in a single loop, it is more straightforward to accumulate a list of attribute objects to remove during one pass over the attribute objects and to carry out the actual removals during a subsequent iteration over the accumulated list.

File: PDSWriteProcs.h

Line: 297

PDSElementRemoveClass

()

Product availability: 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.

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.

Since

PI_PDS_WRITE_VERSION >= 0x00040000

Note

Calling PDSElementRemoveClass() while iterating over the classes of an element will change the relationship between class indices and classes. Although it is possible to track this change in indices in a single loop, it is more straightforward to accumulate a list of classes to remove during one pass over the classes and to carry out the actual removals during a subsequent iteration over the accumulated list.

File: PDSWriteProcs.h

Line: 351

PDSElementRemoveKid

()

Product availability: 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.

Since

PI_PDS_WRITE_VERSION >= 0x00040000

Note

The approved method of removing OBJ kids is PDSElementRemoveKidOBJ().

File: PDSWriteProcs.h

Line: 470

PDSElementRemoveKidMC

()

Product availability: 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.

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h

Line: 490

PDSElementRemoveKidOBJ

()

Product availability: 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.

Since

PI_PDS_WRITE_VERSION >= 0x00050000

File: PDSWriteProcs.h

Line: 800

PDSElementReplaceKid

()

Product availability: 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`.

Since

PI_PDS_WRITE_VERSION >= 0x00040000

Note

The approved method of replacing OBJ kids is PDSElementReplaceKidOBJ().

File: PDSWriteProcs.h

Line: 510

PDSElementReplaceKidMC

()

Product availability: 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`.

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h

Line: 530

PDSElementReplaceKidOBJ

()

Product availability: 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`.

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h

Line: 551

PDSElementSetActualText

()

Product availability: 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

PDSElementGetActualText

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: PDSWriteProcs.h

Line: 762

PDSElementSetActualTextASText

()

Product availability: 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.

Since

PI_PDS_WRITE_VERSION >= 0x00080000

File: PDSWriteProcs.h

Line: 983

PDSElementSetAlt

()

Product availability: 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

PDSElementGetAlt
PDSElementHasAlt

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

Exceptions

Raises pdsErrWrongTypeParameter if element is not a valid PDSElement.

Since

PI_PDS_WRITE_VERSION >= 0x00080000

File: PDSWriteProcs.h

Line: 999

PDSElementSetID

()

Product availability: 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

PDSElementGetID
PDSElementClearID

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

Since

PI_PDS_WRITE_VERSION >= 0x00050000

Note

IANA registered language codes can be found at
The IETF Standard for Language Element Values (RFC 1766) can be found at

File: PDSWriteProcs.h

Line: 784

PDSElementSetTitle

()

Product availability: 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

PDSElementGetTitle

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

Exceptions

Raises pdsErrWrongTypeParameter if element is not a valid PDSElement.

Since

PI_PDS_WRITE_VERSION >= 0x00080000

File: PDSWriteProcs.h

Line: 969

PDSElementSetType

()

Product availability: 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

PDSElementGetType

Exceptions

pdsErrWrongTypeParameter is raised if element is not a valid PDSElement.

Since

PI_PDS_WRITE_VERSION >= 0x00040000

File: PDSWriteProcs.h

Line: 232

Copyright 2020 Adobe Systems Incorporated and its licensors. All rights reserved. Adobe and the Adobe logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. This product contains either BSAFE and/or TIPEM software by RSA Security, Inc. Portions utilize Microsoft Windows Media Technologies. Copyright © 2006 Microsoft Corporation. All Rights Reserved. Notices, terms and conditions pertaining to other third party software are located at http://www.adobe.com/go/thirdparty/ and incorporated herein by reference.
Tue Jun 23 2020, 12:30 AM GMT+05:30

Acrobat API Reference	All Layers \| All Objects \| Index \| Samples \| Frames No Frames
PDSElement	Typedefs \| Callbacks \| Methods

Layer	PDSEdit_Layer
Object	PDSElement