PD Layer: PDAction

PDAction Typedefs

PDAction

Header: PDExpT.h:133

Description

Actions are what happens when a user clicks on a link or bookmark. In addition, the Acrobat viewer allows a document to have an action that is executed automatically when the document is opened. Applications can also support actions in custom annotation types they add.

Syntax

typedef OPAQUE_64_BITS PDAction;

Returned From

Used By

PDActionClipboardData

Header: PDExpT.h:136

Syntax

typedef struct _t_PDActionClipboardData *PDActionClipboardData;

Returned From

Used By

PDAction Functions

PDActionCanCopy: - Tests whether the data from an action object can be copied to a clipboard for pasting.
PDActionCanPaste: - Tests whether data from an action object that has been copied to a clipboard can be pasted into a destination document.
PDActionCopy: - Copies action object data to a clipboard structure, from which it can be pasted.
PDActionDestroy: - Destroys an action object.
PDActionDestroyClipboardData: - Destroys data that has been copied from an action object into a clipboard.
PDActionEqual: - Compares two actions for equality.
PDActionFromCosObj: - Converts a dictionary Cos object to an action and verifies that the action is valid.
PDActionGetCosObj: - Gets the Cos object corresponding to an action.
PDActionGetDest: - Gets an action's destination view.
PDActionGetFileSpec: - Gets a file specification from an action.
PDActionGetSubtype: - Gets an action's subtype.
PDActionIsValid: - Tests whether an action is valid.
PDActionNew: - Creates a new action object.
PDActionNewFromDest: - Creates a new action that takes the user to the specified destination view.
PDActionNewFromFileSpec: - Creates an action of the specified type from a file specification.
PDActionPaste: - Creates a new PDAction in the destination document, using clipboard data generated by PDActionCopy().

PDActionCanCopy

Header: PDProcs.h:8758

Description

Tests whether the data from an action object can be copied to a clipboard for pasting. If the action is part of an action chain, the method tests all actions in the chain, and returns true only if all actions in the chain can be copied.

Syntax

ASBool PDActionCanCopy(PDAction action);

Parameters

action

The action to test.

Returns

true if the action object or all actions in the action chain can be copied, false otherwise.

PDActionCanPaste

Header: PDProcs.h:8790

Description

Tests whether data from an action object that has been copied to a clipboard can be pasted into a destination document. It tests, for example, whether pasting is allowed by document permissions.

Syntax

ASBool PDActionCanPaste(PDDoc dest, PDActionClipboardData data);

Parameters

`dest`	The destination document.
`data`	The action data to test.

Returns

true if the action data can be pasted to the document, false otherwise.

PDActionCopy

Header: PDProcs.h:8773

Description

Copies action object data to a clipboard structure, from which it can be pasted. When the PDActionClipboardData is no longer required, it must be explicitly freed using PDActionDestroyClipboardData().

Syntax

PDActionClipboardData PDActionCopy(PDAction action);

Parameters

action

The action to copy.

Returns

The action clipboard data object.

PDActionDestroy

Header: PDProcs.h:122

Description

Destroys an action object.

Syntax

void PDActionDestroy(PDAction action);

Parameters

action

IN/OUT The action to destroy.

PDActionDestroyClipboardData

Header: PDProcs.h:8828

Description

Destroys data that has been copied from an action object into a clipboard. Use this method when the clipboard data is no longer needed.

Syntax

void PDActionDestroyClipboardData(PDActionClipboardData data);

Parameters

data

The clipboard action data to destroy.

PDActionEqual

Header: PDProcs.h:162

Description

Compares two actions for equality. Two actions are equal only if their Cos objects are equal (see CosObjEqual()).

Related Methods

CosObjEqual

Syntax

ASBool PDActionEqual(PDAction action, PDAction action2);

Parameters

`action`	The first actions to be compared.
`action2`	The second action to be compared.

Returns

true if the actions are equal, false otherwise.

PDActionFromCosObj

Header: PDProcs.h:222

Description

Converts a dictionary Cos object to an action and verifies that the action is valid. This method does not copy the object, but is instead the logical equivalent of a type cast.

Syntax

PDAction PDActionFromCosObj(CosObj obj);

Parameters

obj

The dictionary Cos object whose action is obtained.

Returns

The PDAction corresponding to obj.

Exceptions

pdErrBadAction

is raised if the action is invalid as determined by PDActionIsValid().

PDActionGetCosObj

Header: PDProcs.h:205

Description

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

Related Methods

PDActionFromCosObj

Syntax

CosObj PDActionGetCosObj(PDAction action);

Parameters

action

IN/OUT The action whose Cos object is obtained.

Returns

The dictionary Cos object for the action. The contents of the dictionary can be enumerated using CosObjEnum().

PDActionGetDest

Header: PDProcs.h:192

Description

Gets an action's destination view. This only works for actions that contain a view destination; that is, actions whose subtype is GoTo.

For named destinations, this method may return a Cos string object or a Cos name object.

See the description of the Named Destinations in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 12.3.2, page 365.

You can find this document on the web store of the International Standards Organization (ISO).

Note: Since this method may not return a PDViewDestination, use the PDViewDestResolve() method on the returned value to obtain a PDViewDestination.

Syntax

PDViewDestination PDActionGetDest(PDAction action);

Parameters

action

The action whose destination is obtained.

Returns

The action's destination, which may be a PDViewDestination, or for named destinations, a Cos string object or a Cos name object. Use the PDViewDestResolve() method on this returned value to obtain a PDViewDestination.

PDActionGetFileSpec

Header: PDProcs.h:241

Description

Gets a file specification from an action.

Not all types of actions have file specifications; this method only works for actions that contain a file specification.

See the description of Actions in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 12.6, page 414.

You can find this document on the web store of the International Standards Organization (ISO).

Related Methods

PDActionGetDest

Syntax

PDFileSpec PDActionGetFileSpec(PDAction action);

Parameters

action

The action whose file specification is obtained.

Returns

The action's file specification.

PDActionGetSubtype

Header: PDProcs.h:149

Description

Gets an action's subtype.

Syntax

ASAtom PDActionGetSubtype(PDAction action);

Parameters

action

IN/OUT The action whose subtype is obtained.

Returns

The ASAtom corresponding to the action's subtype. The ASAtom can be converted to a string using ASAtomGetString().

PDActionIsValid

Header: PDProcs.h:140

Description

To determine whether a PDAction returned from a method is really an action. For example, calling PDLinkAnnotGetAction() returns an invalid action if no action is associated with the link annotation.
To ensure that an action has not been deleted.

Related Methods

PDActionEqual

Syntax

ASBool PDActionIsValid(PDAction action);

Parameters

action

The action whose validity is determined.

Returns

true if the action is valid, false otherwise.

PDActionNew

Header: PDProcs.h:67

Description

Creates a new action object.

Syntax

PDAction PDActionNew(PDDoc doc, ASAtom type);

Parameters

`doc`	The document in which the action is created.
`type`	The ASAtom corresponding to the action's subtype. The ASAtom can be obtained from a string using ASAtomFromString().

Returns

The newly created PDAction.

PDActionNewFromDest

Header: PDProcs.h:94

Description

Creates a new action that takes the user to the specified destination view. This method can only be used for destinations in the same document as the source document. Cross-document links must be built up from the Cos level, populating the Action dictionary for the GotoR action.

See the description of the GoToR Action in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 12.6.4, page 417.

You can find this document on the web store of the International Standards Organization (ISO).

Syntax

PDAction PDActionNewFromDest(PDDoc doc, PDViewDestination dest, PDDoc destDoc);

Parameters

`doc`	The document in which the action is created and used.
`dest`	The destination view.
`destDoc`	The destination document. `destDoc` must be the same as `doc`.

Returns

The newly created action.

PDActionNewFromFileSpec

Header: PDProcs.h:111

Description

Creates an action of the specified type from a file specification.

Syntax

PDAction PDActionNewFromFileSpec(PDDoc containingDoc, ASAtom type, PDFileSpec fileSpec);

Parameters

`containingDoc`	The document in which the action is created and used.
`type`	The type of action to create.
`fileSpec`	The file specification that is made part of an action.

Returns

The newly created PDAction.

PDActionPaste

Header: PDProcs.h:8815

Description

Creates a new PDAction in the destination document, using clipboard data generated by PDActionCopy(). If the original PDAction was an action chain, the entire action chain is recreated. The returned PDAction is the first item in the chain.

When the data is no longer needed, use PDActionDestroyClipboardData() to free the structure.

Syntax

PDAction PDActionPaste(PDDoc dest, PDActionClipboardData data);

Parameters

`dest`	The destination document for the paste operation.
`data`	The clipboard structure holding the copied action data.

Returns

A newly created action object (or the first such object in the action chain) associated with the specified document, containing the same data as the copied action.