PDFEdit_Layer.PDEElement (Acrobat)

	Typedef
	PDEElement The base class for elements of a page display list (PDEContent) and for clip objects. The general PDEElement methods allow you to get and set general element properties.

	Enumeration
	`PDEElementCopyFlags` A bit field for PDEElementCopy() .

	Callback
	PDEElementEnumProc A callback for PDEEnumElements(). It is called once for each PDEElement in a page's Contents Stream or Resources dictionary.

	Method
	PDEElement PDEElementCopy(INPDEElement pdeElement, INASUns32 flags) Makes a copy of an element. The caller is responsible for releasing the copy with PDERelease().
	ASUns32 PDEElementGetAllVisibilities(PDEElement elem, PDEContent content, PDOCContext ocContext, ASBool* visibilities, ASUns32 capacity) Tests whether all occurrences of the element are visible in a given content and optional-content context. It traverses the content to find each occurrence of the element, in the supplied content and in all nested contents. To find the visibility of a content element without considering its parent, use PDEElementIsCurrentlyVisible().
	void PDEElementGetBBox(INPDEElement pdeElement, OUTASFixedRectP bboxP) Gets the bounding box for an element.
	PDEClip PDEElementGetClip(INPDEElement pdeElement) Gets the current clip for an element. The current clipping path is part of the graphics state. Element types that are not graphics elements (for example, PDEContainer and PDEPlace) do not have an associated gstate and should not be expected to return valid results.
	void PDEElementGetGState(INPDEElement pdeElement, OUTPDEGraphicStateP stateP, INASUns32 stateSize) Gets the graphics state information for an element.
	void PDEElementGetMatrix(INPDEElement pdeElement, OUTASFixedMatrixP matrixP) Superseded by PDEElementGetMatrixEx() in Acrobat 10.0.
	void PDEElementGetMatrixEx(INPDEElement pdeElement, OUTASDoubleMatrixP matrixP) Supersedes PDEElementGetMatrix() in Acrobat 10.0.
	PDOCMD PDEElementGetOCMD(PDEElement elem) Gets an optional-content membership dictionary (OCMD) object associated with the element. The element must be a PDEForm, PDEImage (XObject image), or PDEContainer. If it is not one of these, the method returns NULL. If the element is a PDEForm or PDEImage, the method returns the dictionary attached to the element's Cos XObject dictionary. If the element is a PDEContainer, and it is for optional content, the method returns the dictionary. If it is not for optional content, the method returns NULL.
	ASBool PDEElementHasGState(INPDEElement pdeElement, OUTPDEGraphicStateP stateP, INASUns32 stateSize) Gets the graphics state information for an element.
	ASBool PDEElementIsAtPoint(INPDEElement elem, INASFixedPoint point) Tests whether a point is on an element.
	ASBool PDEElementIsAtRect(INPDEElement elem, INASFixedRect rect) Tests whether any part of a rectangle is on an element.
	ASBool PDEElementIsCurrentlyVisible(PDEElement elem, PDEContent content, PDOCContext ocContext) Tests whether an element is visible in a given content and optional-content context. It traverses the content to find the first occurrence of the element, in the supplied content and in all nested contents. It returns true if the first occurrence of the element is visible in the context, taking into account the context's NonOCDrawing and PDOCDrawEnumType values.
	ASBool PDEElementMakeVisible(PDEElement elem, PDEContent content, PDOCContext ocContext) Makes an element visible in a given content and optional-content context, by manipulating the ON-OFF states of the optional-content groups.
	void PDEElementRemoveOCMD(PDEElement elem) Dissociates an optional-content membership dictionary (OCMD) object from the element. The element must be a PDEForm, a PDEImage (XObject image), or a PDEContainer.
	void PDEElementSetClip(INPDEElement pdeElement, INPDEClip pdeClip) Sets the current clip for an element.
	void PDEElementSetGState(INPDEElement pdeElement, INPDEGraphicStateP stateP, INASUns32 stateSize) Sets the graphics state information for an element.
	void PDEElementSetMatrix(INPDEElement pdeElement, INASFixedMatrixP matrixP) Superseded by PDEElementSetMatrixEx() in Acrobat 10.0.
	void PDEElementSetMatrixEx(INPDEElement pdeElement, INASDoubleMatrixP matrixP) Supersedes PDEElementSetMatrix() in Acrobat 10.0.
	void PDEElementSetOCMD(PDEElement elem, PDOCMD pdOCMD) Associates an optional-content membership dictionary (OCMD) object with the element. The element must be a PDEForm, a PDEImage (XObject image), or a PDEContainer.

Typedefs Detail

PDEElement

Product availability: All

Platform availability: All

Syntax

typedef struct _t_PDEElement* PDEElement;

The base class for elements of a page display list (PDEContent) and for clip objects. The general PDEElement methods allow you to get and set general element properties.

See Also

PDEContainer (subclass)
PDEForm (subclass)
PDEGroup (subclass)
PDEImage (subclass)
PDEPath (subclass)
PDEPlace (subclass)
PDEPS (subclass)
PDEShading (subclass)
PDEText (subclass)
PDEUnknown (subclass)
PDEXObject (subclass)
PDEClipGetElem (subclass)
PDEContentGetElem (subclass)
PDEElementCopy (subclass)
PDERelease

File: PEExpT.h

Line: 140

Enumeration Detail

PDEElementCopyFlags

Product availability: All

Platform availability: All

Syntax

enum PDEElementCopyFlags {

  kPDEElementCopyForClip = 0x0001,


 


  kPDEElementCopyClipping = 0x0002

}

See Also

PDEElementCopy

File: PEExpT.h

Line: 1719

Elements

	kPDEElementCopyForClip	The copied element does not need `gstate` or `clip`.

	kPDEElementCopyClipping	Acquire the clip path and put it in the copied object.

Callbacks Detail

PDEElementEnumProc

Product availability: All

Platform availability: All

Syntax

ASBool (*PDEElementEnumProc)(IN PDEElement elem, IN void *clientData)

A callback for PDEEnumElements(). It is called once for each PDEElement in a page's Contents Stream or Resources dictionary.

See Also

PDEEnumElements

File: PEExpT.h

Line: 1850

Method Detail

PDEElementCopy

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





PDEElement PDEElementCopy(INPDEElement pdeElement, INASUns32 flags)

Makes a copy of an element. The caller is responsible for releasing the copy with PDERelease().

Parameters

	`pdeElement` —	IN/OUT The element to copy.

	`flags` —	IN/OUT A bit field of PDEElementCopyFlags.

Returns

A copy of pdeElement.

See Also

PDEContentGetElem

Exceptions

peErrWrongPDEObjectType
genErrBadParm

Since

PI_PDFEDIT_WRITE_VERSION >= 0x00040000

File: PEWProcs.h

Line: 237

PDEElementGetAllVisibilities

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





ASUns32 PDEElementGetAllVisibilities(PDEElement elem, PDEContent content, PDOCContext ocContext, ASBool* visibilities, ASUns32 capacity)

Tests whether all occurrences of the element are visible in a given content and optional-content context. It traverses the content to find each occurrence of the element, in the supplied content and in all nested contents. To find the visibility of a content element without considering its parent, use PDEElementIsCurrentlyVisible().

It returns the number of occurrences and an array of boolean values containing true for each occurrence of the element that is visible in the context, taking into account the context's NonOCDrawing and PDOCDrawEnumType values.

Parameters

	`elem` —	The element for which to obtain visibilities.

	`content` —	The content containing the element.

	`ocContext` —	The optional-content context in which the element is tested.

	`visibilities` —	(Filled by the method) An array of boolean values containing `true` for each occurrence of the element that is visible in the context.

	`capacity` —	The size of the visibilities array.

Returns

The number of occurrences of the element in the content.

Since

PI_PDFEDIT_READ_VERSION >= 0x00060000

File: PERProcs.h

Line: 2664

PDEElementGetBBox

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





void PDEElementGetBBox(INPDEElement pdeElement, OUTASFixedRectP bboxP)

Gets the bounding box for an element.

The returned bounding box is guaranteed to encompass the element, but is not guaranteed to be the smallest box that could contain the element. For example, for an arc, bboxP encloses the bezier control points, and not just the curve itself.

Parameters

	`pdeElement` —	IN/OUT An element whose bounding box is obtained.

	`bboxP` —	IN/OUT (Filled by the method) A pointer to a ASFixedRect structure specifying the bounding box of `pdeElement`, specified in user space coordinates.

Exceptions

peErrWrongPDEObjectType
genErrBadParm

Notifications

PDEElementGetClip
PDEElementGetGState
PDEElementGetMatrix

Since

PI_PDFEDIT_READ_VERSION >= 0x00040000

File: PERProcs.h

Line: 212

PDEElementGetClip

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





PDEClip PDEElementGetClip(INPDEElement pdeElement)

Gets the current clip for an element. The current clipping path is part of the graphics state. Element types that are not graphics elements (for example, PDEContainer and PDEPlace) do not have an associated gstate and should not be expected to return valid results.

Parameters

pdeElement —

IN/OUT An element whose clip is obtained. Note that a clip may be shared by many elements. Use care when modifying a clip. Copy it first if you want to modify the clip for a specific element.

Returns

The clip object for pdeElement.

Exceptions

peErrWrongPDEObjectType

Since

PI_PDFEDIT_READ_VERSION >= 0x00040000

File: PERProcs.h

Line: 296

PDEElementGetGState

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





void PDEElementGetGState(INPDEElement pdeElement, OUTPDEGraphicStateP stateP, INASUns32 stateSize)

Gets the graphics state information for an element.

This method is only valid for PDEForm, PDEImage, PDEPath, and PDEShading elements.

Parameters

	`pdeElement` —	An element whose graphics state is obtained.

	`stateP` —	(Filled by the method) A pointer to a PDEGraphicStateP structure that contains graphics state information for `pdeElement`. This PDEGraphicStateP may contain PDEObjects for color spaces or an ExtGState. They are not acquired by this method. Note that for a PDEImage, only the ExtGState value is used for images. For indexed images, the fill color space and values are categorized in the PDEImage object.

	`stateSize` —	The size of the `stateP` buffer in bytes.

Exceptions

peErrWrongPDEObjectType
genErrBadParm

Since

PI_PDFEDIT_READ_VERSION >= 0x00040000

File: PERProcs.h

Line: 241

PDEElementGetMatrix

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





void PDEElementGetMatrix(INPDEElement pdeElement, OUTASFixedMatrixP matrixP)

Superseded by PDEElementGetMatrixEx() in Acrobat 10.0.

Gets the transformation matrix for an element.

This matrix provides the transformation from user space to device space for the element. If there is no cm (concatmatrix) operator in the page stream, the matrix is the identity matrix.

For the Adobe PDF Library v1, the element may not be a PDEContainer, a PDEGroup, a PDEPlace, or a PDEText.

For the Adobe PDF Library v4, the element may not be a PDEText.

Parameters

	`pdeElement` —	An element whose transformation matrix is obtained.

	`matrixP` —	(Filled by the method) A pointer to ASFixedMatrix that holds a transformation matrix for `pdeElement`. If `pdeElement` is a text object, it returns the identity matrix.

Exceptions

peErrWrongPDEObjectType
genErrBadParm

Since

PI_PDFEDIT_READ_VERSION >= 0x00040000

File: PERProcs.h

Line: 273

PDEElementGetMatrixEx

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





void PDEElementGetMatrixEx(INPDEElement pdeElement, OUTASDoubleMatrixP matrixP)

Supersedes PDEElementGetMatrix() in Acrobat 10.0.

Gets the transformation matrix for an element.

This matrix provides the transformation from user space to device space for the element. If there is no cm (concatmatrix) operator in the page stream, the matrix is the identity matrix.

For the Adobe PDF Library v1, the element may not be a PDEContainer, a PDEGroup, a PDEPlace, or a PDEText.

For the Adobe PDF Library v4, the element may not be a PDEText.

Parameters

	`pdeElement` —	An element whose transformation matrix is obtained.

	`matrixP` —	(Filled by the method) A pointer to ASDoubleMatrix that holds a transformation matrix for `pdeElement`. If `pdeElement` is a text object, it returns the identity matrix.

Exceptions

peErrWrongPDEObjectType
genErrBadParm

Since

PI_PDFEDIT_READ_VERSION >= 0x000A0000

File: PERProcs.h

Line: 3349

PDEElementGetOCMD

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





PDOCMD PDEElementGetOCMD(PDEElement elem)

Gets an optional-content membership dictionary (OCMD) object associated with the element. The element must be a PDEForm, PDEImage (XObject image), or PDEContainer. If it is not one of these, the method returns NULL.

If the element is a PDEForm or PDEImage, the method returns the dictionary attached to the element's Cos XObject dictionary.
If the element is a PDEContainer, and it is for optional content, the method returns the dictionary. If it is not for optional content, the method returns NULL.

Parameters

elem —

The element from which the dictionary is obtained.

Returns

The dictionary object, or NULL if the element is not a PDEForm, PDEImage (XObject image), or PDEContainer, or if it is a container that is not for optional content.

Since

PI_PDFEDIT_READ_VERSION >= 0x00060000

File: PERProcs.h

Line: 2604

PDEElementHasGState

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





ASBool PDEElementHasGState(INPDEElement pdeElement, OUTPDEGraphicStateP stateP, INASUns32 stateSize)

Gets the graphics state information for an element.

Parameters

	`pdeElement` —	The PDEElement whose graphics state is to be obtained.

	`stateP` —	(Filled by the method) A pointer to a PDEGraphicStateP structure that contains graphics state information for `pdeElement`.

	`stateSize` —	The size of the `stateP` buffer. Set it to `sizeof(PDEGraphicState)`.

Returns

true if the element has a graphics state, false otherwise.

Exceptions

genErrBadParm

Since

PI_PDFEDIT_READ_VERSION >= 0x00050000

File: PERProcs.h

Line: 2238

PDEElementIsAtPoint

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





ASBool PDEElementIsAtPoint(INPDEElement elem, INASFixedPoint point)

Tests whether a point is on an element.

Parameters

	`elem` —	IN/OUT The element to test. If PDEElement is a PDEText or PDEImage, it uses the bounding box of the PDEElement to make the check. If the PDEElement is a PDEPath and it is stroked, it checks if the point is on the path. If the PDEElement is a PDEPath and it is filled, it checks if the point is in the fill area, taking into consideration whether it is filled using the non-zero winding number rule or the even-odd rule.

	`point` —	IN/OUT The point, specified in user space coordinates.

Returns

true if the point is on the element, false otherwise.

Exceptions

peErrWrongPDEObjectType

Since

PI_PDFEDIT_READ_VERSION >= 0x00040000

File: PERProcs.h

Line: 1859

PDEElementIsAtRect

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





ASBool PDEElementIsAtRect(INPDEElement elem, INASFixedRect rect)

Tests whether any part of a rectangle is on an element.

Parameters

	`elem` —	IN/OUT The element to test. If PDEElement is a PDEText or PDEImage, it uses the bounding box of the PDEElement to make the check. If the PDEElement is a PDEPath and it is stroked, it checks if the rectangle is on the path. If the PDEElement is a PDEPath and it is filled, it checks if the rectangle is in the fill area, taking into consideration whether it is filled using the non-zero winding number rule or the even-odd rule.

	`rect` —	IN/OUT The rectangle, specified in user space coordinates.

Returns

true if any part of the rectangle is on the element, false otherwise.

Exceptions

peErrWrongPDEObjectType

Since

PI_PDFEDIT_READ_VERSION >= 0x00040000

File: PERProcs.h

Line: 1885

PDEElementIsCurrentlyVisible

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





ASBool PDEElementIsCurrentlyVisible(PDEElement elem, PDEContent content, PDOCContext ocContext)

Tests whether an element is visible in a given content and optional-content context. It traverses the content to find the first occurrence of the element, in the supplied content and in all nested contents. It returns true if the first occurrence of the element is visible in the context, taking into account the context's NonOCDrawing and PDOCDrawEnumType values.

The content can be NULL. In this case:

If the element is a PDEForm, PDEImage, or PDEContainer, the method checks the object to see if it has an optional-content membership dictionary (OCMD) attached to it. If so, the method returns true if the object is visible, without considering whether the PDEContent that the element belongs to is visible.
If the element is not one of these types, the method returns true.

Parameters

	`elem` —	The element to test.

	`content` —	The content containing the element.

	`ocContext` —	The optional-content context in which the element is tested.

Returns

Returns true if the element is visible in the given content and context, false if it is hidden.

Since

PI_PDFEDIT_READ_VERSION >= 0x00060000

File: PERProcs.h

Line: 2634

PDEElementMakeVisible

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





ASBool PDEElementMakeVisible(PDEElement elem, PDEContent content, PDOCContext ocContext)

Makes an element visible in a given content and optional-content context, by manipulating the ON-OFF states of the optional-content groups.

Parameters

	`elem` —	The element for which to set the visibility state.

	`content` —	The content containing the element.

	`ocContext` —	The optional-content context in which the element is made visible.

Returns

true if the element is successfully made visible in the given content and context, false otherwise.

Since

PI_PDFEDIT_WRITE_VERSION >= 0x00060000

File: PERProcs.h

Line: 2682

PDEElementRemoveOCMD

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





void PDEElementRemoveOCMD(PDEElement elem)

Dissociates an optional-content membership dictionary (OCMD) object from the element. The element must be a PDEForm, a PDEImage (XObject image), or a PDEContainer.

If it is not one of these, nothing happens:

If the element is a PDEForm or PDEImage, the method removes the dictionary from the element's Cos XObject dictionary.
If the element is a PDEContainer for optional content, the method removes the dictionary, but does not destroy the container.

Parameters

elem —

The element for which to remove the dictionary.

Since

PI_PDFEDIT_WRITE_VERSION >= 0x00060000

File: PEWProcs.h

Line: 2556

PDEElementSetClip

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





void PDEElementSetClip(INPDEElement pdeElement, INPDEClip pdeClip)

Sets the current clip for an element.

The pdeElement parameter's previous clip's reference count is decremented (if it had one), and the pdeClip parameter's reference count is incremented.

Parameters

	`pdeElement` —	IN/OUT An element whose clip is set.

	`pdeClip` —	IN/OUT The clip to set for `pdeContent`.

See Also

PDEElementGetClip

Exceptions

peErrWrongPDEObjectType
genErrBadParm

Since

PI_PDFEDIT_WRITE_VERSION >= 0x00040000

File: PEWProcs.h

Line: 221

PDEElementSetGState

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





void PDEElementSetGState(INPDEElement pdeElement, INPDEGraphicStateP stateP, INASUns32 stateSize)

Sets the graphics state information for an element.

This method is valid only for PDEForm, PDEImage, PDEPath, and PDEShading elements.

Parameters

	`pdeElement` —	An element whose graphics state is set.

	`stateP` —	A pointer to a PDEGraphicStateP structure with graphics state information to set for `pdeContent`. Any of the `stateP` parameter's color space or ExtGState objects have their reference count incremented.

	`stateSize` —	The size of the `stateP` buffer in bytes.

See Also

PDEElementGetGState

Exceptions

peErrWrongPDEObjectType
genErrBadParm will be raised if the first parameter, pdeElement, does not have a graphics state associated with it.

Since

PI_PDFEDIT_WRITE_VERSION >= 0x00040000

File: PEWProcs.h

Line: 180

PDEElementSetMatrix

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





void PDEElementSetMatrix(INPDEElement pdeElement, INASFixedMatrixP matrixP)

Superseded by PDEElementSetMatrixEx() in Acrobat 10.0.

Sets the transformation matrix for an element.

The element may not be a PDEContainer, a PDEGroup, a PDEPlace, or a PDEText.

Parameters

	`pdeElement` —	IN/OUT An element whose transformation matrix is set.

	`matrixP` —	IN/OUT A pointer to an ASFixedMatrix that holds the transformation matrix to set for `pdeContent`.

Exceptions

peErrWrongPDEObjectType
genErrBadParm

Since

PI_PDFEDIT_WRITE_VERSION >= 0x00040000

File: PEWProcs.h

Line: 203

PDEElementSetMatrixEx

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





void PDEElementSetMatrixEx(INPDEElement pdeElement, INASDoubleMatrixP matrixP)

Supersedes PDEElementSetMatrix() in Acrobat 10.0.

Sets the transformation matrix for an element.

The element may not be a PDEContainer, a PDEGroup, a PDEPlace, or a PDEText.

Parameters

	`pdeElement` —	IN/OUT An element whose transformation matrix is set.

	`matrixP` —	IN/OUT A pointer to an ASDoubleMatrix that holds the transformation matrix to set for `pdeContent`.

Exceptions

peErrWrongPDEObjectType
genErrBadParm

Since

PI_PDFEDIT_WRITE_VERSION >= 0x000A0000

File: PEWProcs.h

Line: 4083

PDEElementSetOCMD

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





void PDEElementSetOCMD(PDEElement elem, PDOCMD pdOCMD)

Associates an optional-content membership dictionary (OCMD) object with the element. The element must be a PDEForm, a PDEImage (XObject image), or a PDEContainer.

If it is not one of these, nothing happens:

If the element is a PDEForm or PDEImage, the method attaches the dictionary to the element's Cos XObject dictionary.
If the element is a PDEContainer, and it is already for optional content, the optional-content information is replaced.
If it is not already for optional content, a new PDEContainer for optional content is created and nested inside the specified container.

Parameters

	`elem` —	The element for which to set the dictionary.

	`pdOCMD` —	The new dictionary.

Since

PI_PDFEDIT_WRITE_VERSION >= 0x00060000

File: PEWProcs.h

Line: 2533

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

	kPDEElementCopyForClip = 0x0001,

	kPDEElementCopyClipping = 0x0002

Layer	PDFEdit_Layer
Object	PDEElement