PD_Layer.PDAction (Acrobat)

	Typedef
	PDAction 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.
	PDActionClipboardData
	PDActionHandler
	PDActionHandlerData Used to store PDAction data for copy and paste operations.
	PDActionHandlerRec

	Structure
	_t_PDActionHandler A data structure containing callbacks that implement an action manager. The callbacks provide copy-and-paste functionality for a particular type of action.

	Callback
	PDActionHandlerCanCopyProc (Optional) A callback for PDActionHandler. It returns true if the copy operation is expected to succeed. It tests, for example, whether copying is allowed by document permissions.
	PDActionHandlerCanPasteProc (Optional) A callback for PDActionHandler. It returns true if the paste operation is expected to succeed. It tests, for example, whether pasting is allowed by document permissions.
	PDActionHandlerCopyProc (Optional) A callback for PDActionHandler. It copies data from an action object to a new data structure, from which it can be pasted to a new document. The PDActionHandlerData does not store any information related to a Next action. Rebuilding the action chain is the responsibility of the caller and can be ignored by the PDActionHandler.
	PDActionHandlerDestroyDataProc A callback for PDActionHandler. It destroys data copied into an action clipboard data structure after it has been successfully pasted to a new document.
	PDActionHandlerDestroyProc (Optional) A callback for PDActionHandler. It destroys the action handler structure when the application no longer requires it. The handler should destroy any dynamic memory stored in the userData field.
	PDActionHandlerGetTypeProc A callback for PDActionHandler. It returns an ASAtom indicating the action type for which the handler is responsible. Types are defined by the client when registering the action handler.
	PDActionHandlerPasteProc (Optional) A callback for PDActionHandler. It creates a new PDAction in the destination document using data that was placed in a PDActionClipboardA data structure using the PDActionCopy() function, and returns the new action object.

	Method
	ASBool PDActionCanCopy(PDAction action) 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.
	ASBool PDActionCanPaste(PDDoc dest, PDActionClipboardData data) 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.
	PDActionClipboardData PDActionCopy(PDAction action) 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().
	void PDActionDestroy(PDAction action) Destroys an action object.
	void PDActionDestroyClipboardData(PDActionClipboardData data) Destroys data that has been copied from an action object into a clipboard. Use this method when the clipboard data is no longer needed.
	ASBool PDActionEqual(PDAction action, PDAction action2) Compares two actions for equality. Two actions are equal only if their Cos objects are equal (see CosObjEqual()).
	PDAction PDActionFromCosObj(CosObj obj) 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.
	CosObj PDActionGetCosObj(PDAction action) 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.
	PDViewDestination PDActionGetDest(PDAction action) Gets an action's destination view. This only works for actions that contain a view destination; that is, actions whose subtype is GoTo.
	PDFileSpec PDActionGetFileSpec(PDAction action) Gets a file specification from an action.
	ASAtom PDActionGetSubtype(PDAction action) Gets an action's subtype.
	ASBool PDActionIsValid(PDAction action) Tests whether an action is valid. This method can be used in the following cases: 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.
	PDAction PDActionNew(PDDoc doc, ASAtom type) Creates a new action object.
	PDAction PDActionNewFromDest(PDDoc doc, PDViewDestination dest, PDDoc destDoc) 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 as described in Section 8.5.3 in the PDF Reference.
	PDAction PDActionNewFromFileSpec(PDDoc containingDoc, ASAtom type, PDFileSpec fileSpec) Creates an action of the specified type from a file specification.
	PDAction PDActionPaste(PDDoc dest, PDActionClipboardData data) 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.
	void PDRegisterActionHandler(PDActionHandler handler) Registers a handler for PDAction operations.

Typedefs Detail

PDAction

Product availability: All

Platform availability: All

Syntax

typedef OPAQUE_64_BITS PDAction;

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.

File: PDExpT.h

Line: 124

PDActionClipboardData

Product availability: All

Platform availability: All

Syntax

typedef struct _t_PDActionClipboardData* PDActionClipboardData;

File: PDExpT.h

Line: 127

PDActionHandler

Product availability: All

Platform availability: All

Syntax

typedef _t_PDActionHandler PDActionHandler;

File: PDExpT.h

Line: 126

PDActionHandlerData

Product availability: All

Platform availability: All

Syntax

typedef void* PDActionHandlerData;

Used to store PDAction data for copy and paste operations.

File: PDExpT.h

Line: 137

PDActionHandlerRec

Product availability: All

Platform availability: All

Syntax

typedef _t_PDActionHandler PDActionHandlerRec;

File: PDExpT.h

Line: 292

Structure Detail

_t_PDActionHandler

Product availability: All

Platform availability: All

Syntax

struct _t_PDActionHandler {

  ASSize_t size;  


 


  void* userData;  


 


  PDActionHandlerGetTypeProc GetType;  


 


  PDActionHandlerCanCopyProc CanCopy;  


 


  PDActionHandlerCopyProc Copy;  


 


  PDActionHandlerCanPasteProc CanPaste;  


 


  PDActionHandlerPasteProc Paste;  


 


  PDActionHandlerDestroyDataProc DestroyData;  


 


  PDActionHandlerDestroyProc Destroy;  

}

A data structure containing callbacks that implement an action manager. The callbacks provide copy-and-paste functionality for a particular type of action.

See Also

PDRegisterActionHandler

File: PDExpT.h

Line: 264

Elements

	size	The size of the data structure. It must be set to `sizeof(PDAnnotHandlerRec)`.

	userData	A pointer to a block of user-supplied data.

Callbacks Detail

PDActionHandlerCanCopyProc

Product availability: All

Platform availability: All

Syntax

ASBool (*PDActionHandlerCanCopyProc)(PDActionHandler pdah, PDAction action)

(Optional) A callback for PDActionHandler. It returns true if the copy operation is expected to succeed. It tests, for example, whether copying is allowed by document permissions.

File: PDExpT.h

Line: 168

PDActionHandlerCanPasteProc

Product availability: All

Platform availability: All

Syntax

ASBool (*PDActionHandlerCanPasteProc)(PDActionHandler pdah, PDDoc dest, PDActionHandlerData data)

(Optional) A callback for PDActionHandler. It returns true if the paste operation is expected to succeed. It tests, for example, whether pasting is allowed by document permissions.

File: PDExpT.h

Line: 209

PDActionHandlerCopyProc

Product availability: All

Platform availability: All

Syntax

PDActionHandlerData (*PDActionHandlerCopyProc)(PDActionHandler pdah, PDAction action)

(Optional) A callback for PDActionHandler. It copies data from an action object to a new data structure, from which it can be pasted to a new document. The PDActionHandlerData does not store any information related to a Next action. Rebuilding the action chain is the responsibility of the caller and can be ignored by the PDActionHandler.

File: PDExpT.h

Line: 188

PDActionHandlerDestroyDataProc

Product availability: All

Platform availability: All

Syntax

void (*PDActionHandlerDestroyDataProc)(PDActionHandler pdah, PDActionHandlerData data)

A callback for PDActionHandler. It destroys data copied into an action clipboard data structure after it has been successfully pasted to a new document.

File: PDExpT.h

Line: 245

PDActionHandlerDestroyProc

Product availability: All

Platform availability: All

Syntax

void (*PDActionHandlerDestroyProc)(PDActionHandler pdah)

(Optional) A callback for PDActionHandler. It destroys the action handler structure when the application no longer requires it. The handler should destroy any dynamic memory stored in the userData field.

See Also

PDRegisterActionHandler

File: PDExpT.h

Line: 256

PDActionHandlerGetTypeProc

Product availability: All

Platform availability: All

Syntax

ASAtom (*PDActionHandlerGetTypeProc)(PDActionHandler pdah)

A callback for PDActionHandler. It returns an ASAtom indicating the action type for which the handler is responsible. Types are defined by the client when registering the action handler.

See Also

PDRegisterActionHandler

File: PDExpT.h

Line: 148

PDActionHandlerPasteProc

Product availability: All

Platform availability: All

Syntax

PDAction (*PDActionHandlerPasteProc)(PDActionHandler pdah, PDDoc dest, PDActionHandlerData data)

(Optional) A callback for PDActionHandler. It creates a new PDAction in the destination document using data that was placed in a PDActionClipboardA data structure using the PDActionCopy() function, and returns the new action object.

File: PDExpT.h

Line: 229

Method Detail

PDActionCanCopy

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





ASBool PDActionCanCopy(PDAction action)

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.

Parameters

action —

The action to test.

Returns

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

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h

Line: 8589

PDActionCanPaste

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





ASBool PDActionCanPaste(PDDoc dest, PDActionClipboardData data)

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.

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.

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h

Line: 8621

PDActionCopy

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





PDActionClipboardData PDActionCopy(PDAction action)

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().

Parameters

action —

The action to copy.

Returns

The action clipboard data object.

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h

Line: 8604

PDActionDestroy

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





void PDActionDestroy(PDAction action)

Destroys an action object.

Parameters

action —

IN/OUT The action to destroy.

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 116

PDActionDestroyClipboardData

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





void PDActionDestroyClipboardData(PDActionClipboardData data)

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

Parameters

data —

The clipboard action data to destroy.

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h

Line: 8659

PDActionEqual

()

Product availability: All

Platform availability: All

Syntax





ASBool PDActionEqual(PDAction action, PDAction action2)

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

Parameters

	`action` —	The first actions to be compared.

	`action2` —	The second action to be compared.

Returns

true if the actions are equal, false otherwise.

See Also

CosObjEqual

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 156

PDActionFromCosObj

()

Product availability: All

Platform availability: All

Syntax





PDAction PDActionFromCosObj(CosObj obj)

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.

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().

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 211

PDActionGetCosObj

()

Product availability: All

Platform availability: All

Syntax





CosObj PDActionGetCosObj(PDAction action)

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.

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().

See Also

PDActionFromCosObj

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 194

PDActionGetDest

()

Product availability: All

Platform availability: All

Syntax





PDViewDestination PDActionGetDest(PDAction action)

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 Section 8.2.1 in the PDF Reference for more information on named destinations.

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.

See Also

PDActionGetFileSpec
PDViewDestResolve

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 181

PDActionGetFileSpec

()

Product availability: All

Platform availability: All

Syntax





PDFileSpec PDActionGetFileSpec(PDAction action)

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 Section 8.5 in the PDF Reference for more information on the contents of various types of actions.

Parameters

action —

The action whose file specification is obtained.

Returns

The action's file specification.

See Also

PDActionGetDest

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 226

PDActionGetSubtype

()

Product availability: All

Platform availability: All

Syntax





ASAtom PDActionGetSubtype(PDAction action)

Gets an action's subtype.

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().

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 143

PDActionIsValid

()

Product availability: All

Platform availability: All

Syntax





ASBool PDActionIsValid(PDAction action)

Tests whether an action is valid. This method can be used in the following cases:

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.

Parameters

action —

The action whose validity is determined.

Returns

true if the action is valid, false otherwise.

See Also

PDActionEqual

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 134

PDActionNew

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





PDAction PDActionNew(PDDoc doc, ASAtom type)

Creates a new action object.

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.

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 67

PDActionNewFromDest

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





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

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 as described in Section 8.5.3 in the PDF Reference.

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.

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 88

PDActionNewFromFileSpec

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





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

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

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.

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 105

PDActionPaste

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





PDAction PDActionPaste(PDDoc dest, PDActionClipboardData data)

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.

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.

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h

Line: 8646

PDRegisterActionHandler

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





void PDRegisterActionHandler(PDActionHandler handler)

Registers a handler for PDAction operations.

Parameters

handler —

A pointer to a structure containing the action handler's callbacks. This structure must not be freed after this call, but must be retained.

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h

Line: 8572

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

	ASSize_t size;

	void* userData;

	PDActionHandlerGetTypeProc GetType;

	PDActionHandlerCanCopyProc CanCopy;

	PDActionHandlerCopyProc Copy;

	PDActionHandlerCanPasteProc CanPaste;

	PDActionHandlerPasteProc Paste;

	PDActionHandlerDestroyDataProc DestroyData;

	PDActionHandlerDestroyProc Destroy;

Layer	PD_Layer
Object	PDAction