DL Logo

PDEElement Enumerations

PDEElementCopyFlags

Header: PEExpT.h:1933

Description

A bit field for PDEElementCopy().

Related Methods

Enum Constants

kPDEElementCopyForClip=0x0001
The copied element does not need gstate or clip.
kPDEElementCopyClipping=0x0002
Acquire the clip path and put it in the copied object.

PDEElement Typedefs

PDEElement

Header: PEExpT.h:143

Description

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.

Related Methods

Syntax

typedef struct _t_PDEElement *PDEElement;

Returned From

Used By

PDEElement Callback Signatures

PDEElementEnumProc

Header: PEExpT.h:2075

Description

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

Syntax

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

Parameters

elem
clientData
User-supplied data that was specified in the call to PDEEnumElements().

Returns

true to continue enumeration, false to halt enumeration.

Used By

PDEElement Functions

PDEElementCopy

Header: PEWProcs.h:227

Description

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

Related Methods

Syntax

PDEElement PDEElementCopy(IN PDEElement pdeElement, IN ASUns32 flags);

Parameters

pdeElement
IN/OUT The element to copy.
flags
IN/OUT A bit field of PDEElementCopyFlags.

Returns

A copy of pdeElement.

Exceptions

PDEElementGetAllVisibilities

Header: PERProcs.h:2442

Description

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.

Syntax

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

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.

PDEElementGetBBox

Header: PERProcs.h:197

Description

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.

Syntax

void PDEElementGetBBox(IN PDEElement pdeElement, OUT ASFixedRectP bboxP);

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

PDEElementGetClip

Header: PERProcs.h:271

Description

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.

Note: This method does not change the reference count of the clip object.

Syntax

PDEClip PDEElementGetClip(IN PDEElement pdeElement);

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

PDEElementGetGState

Header: PERProcs.h:224

Description

Gets the graphics state information for an element.

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

Syntax

void PDEElementGetGState(IN PDEElement pdeElement, OUT PDEGraphicStateP stateP, IN ASUns32 stateSize);

Parameters

pdeElement
An element whose graphics state is obtained.
stateP
(Filled by the method) A pointer to a PDEGraphicState 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

PDEElementGetGStateEx

Header: PERProcs.h:3258

Description

Gets the graphics state information for an element. This method fills PDEGraphicStateEx as output which is higher precision alternative of PDEGraphicState structure.

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

Syntax

void PDEElementGetGStateEx(IN PDEElement pdeElement, OUT PDEGraphicStateExP stateP, IN ASUns32 stateSize);

Parameters

pdeElement
An element whose graphics state is obtained.
stateP
(Filled by the method) A pointer to a PDEGraphicStateEx structure that contains graphics state information for pdeElement. This PDEGraphicStateExP 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

PDEElementGetMatrix

Header: PERProcs.h:249

Description

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.

Syntax

void PDEElementGetMatrix(IN PDEElement pdeElement, OUT ASFixedMatrixP matrixP);

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

PDEElementGetMatrixEx

Header: PERProcs.h:3046

Description

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.

Syntax

void PDEElementGetMatrixEx(IN PDEElement pdeElement, OUT ASDoubleMatrixP matrixP);

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

PDEElementGetOCMD

Header: PERProcs.h:2382

Description

    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.

Syntax

PDOCMD PDEElementGetOCMD(PDEElement elem);

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.

PDEElementHasGState

Header: PERProcs.h:2041

Description

Gets the graphics state information for an element.

Related Methods

Syntax

ASBool PDEElementHasGState(IN PDEElement pdeElement, OUT PDEGraphicStateP stateP, IN ASUns32 stateSize);

Parameters

pdeElement
The PDEElement whose graphics state is to be obtained.
stateP
(Filled by the method) A pointer to a PDEGraphicState 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

PDEElementHasGStateEx

Header: PERProcs.h:3279

Description

Gets the graphics state information for an element. This method fills PDEGraphicStateEx as output which is higher precision alternative of PDEGraphicState structure.

Related Methods

Syntax

ASBool PDEElementHasGStateEx(IN PDEElement pdeElement, OUT PDEGraphicStateExP stateP, IN ASUns32 stateSize);

Parameters

pdeElement
The PDEElement whose graphics state is to be obtained.
stateP
(Filled by the method) A pointer to a PDEGraphicStateEx structure that contains graphics state information for pdeElement.
stateSize
The size of the stateP buffer. Set it to sizeof(PDEGraphicStateEx).

Returns

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

Exceptions

PDEElementIsAtPoint

Header: PERProcs.h:1691

Description

Tests whether a point is on an element.

Syntax

ASBool PDEElementIsAtPoint(IN PDEElement elem, IN ASFixedPoint point);

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

PDEElementIsAtRect

Header: PERProcs.h:1715

Description

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

Syntax

ASBool PDEElementIsAtRect(IN PDEElement elem, IN ASFixedRect rect);

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

PDEElementIsCurrentlyVisible

Header: PERProcs.h:2412

Description

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.

Syntax

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

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.

PDEElementMakeVisible

Header: PERProcs.h:2461

Description

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

Syntax

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

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.

PDEElementRemoveOCMD

Header: PEWProcs.h:2326

Description

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.

Syntax

void PDEElementRemoveOCMD(PDEElement elem);

Parameters

elem
The element for which to remove the dictionary.

PDEElementSetClip

Header: PEWProcs.h:213

Description

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.

Related Methods

Syntax

void PDEElementSetClip(IN PDEElement pdeElement, IN PDEClip pdeClip);

Parameters

pdeElement
IN/OUT An element whose clip is set.
pdeClip
IN/OUT The clip to set for pdeContent.

Exceptions

PDEElementSetGState

Header: PEWProcs.h:176

Description

Sets the graphics state information for an element.

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

Note: This method causes any of the stateP parameter's color space or ExtGState objects to have their reference count incremented, and previous graphic state objects to be decremented.

Syntax

void PDEElementSetGState(IN PDEElement pdeElement, IN PDEGraphicStateP stateP, IN ASUns32 stateSize);

Parameters

pdeElement
An element whose graphics state is set.
stateP
A pointer to a PDEGraphicState 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.

Exceptions

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

PDEElementSetGStateEx

Header: PEWProcs.h:3779

Description

Sets the graphics state information for an element. This method takes pointer to PDEGraphicStateEx as input which is higher precision alternative of PDEGraphicState structure.

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

Note: This method causes any of the stateP parameter's color space or ExtGState objects to have their reference count incremented, and previous graphic state objects to be decremented.

Syntax

void PDEElementSetGStateEx(IN PDEElement pdeElement, IN PDEGraphicStateExP stateP, IN ASUns32 stateSize);

Parameters

pdeElement
An element whose graphics state is set.
stateP
A pointer to a PDEGraphicStateEx 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.

Exceptions

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

PDEElementSetMatrix

Header: PEWProcs.h:197

Description

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.

Syntax

void PDEElementSetMatrix(IN PDEElement pdeElement, IN ASFixedMatrixP matrixP);

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

PDEElementSetMatrixEx

Header: PEWProcs.h:3675

Description

Sets the transformation matrix for an element. Supersedes PDEElementSetMatrix() in Acrobat 10.0.

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

Syntax

void PDEElementSetMatrixEx(IN PDEElement pdeElement, IN ASDoubleMatrixP matrixP);

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

PDEElementSetOCMD

Header: PEWProcs.h:2303

Description

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.

Syntax

void PDEElementSetOCMD(PDEElement elem, PDOCMD pdOCMD);

Parameters

elem
The element for which to set the dictionary.
pdOCMD
The new dictionary.