AV_Layer.AVActionHandler (Acrobat)

	Typedef
	AVActionContext
	AVActionContextRec
	AVActionHandler Carries out an action. When the Acrobat viewer executes an action, it looks for the action handler with a type matching that of the action it is trying to execute. The Acrobat viewer invokes the matching handler to perform the action. If no match is found, the Acrobat viewer ignores the user action.
	AVActionHandlerProcs
	AVActionHandlerProcsRec

	Structure
	_AVActionContextRec This structure gives the action handler some context in terms of its execution. It specifies the " parent" object, which initiated the action, and the trigger type of the action. Trigger names should correspond to the key used in the AA dictionary of the file.
	_t_AVActionHandlerProcs A data structure containing callbacks that implement an action handler. The callbacks implement the action handler functions. For example, they can display user interface text, request the action's properties from the user, and perform the action.

	Callback
	AVActionCopyProc (Optional) A callback for AVActionHandlerProcs(). It is called upon to copy an action, possibly to another document. Action handlers should provide this callback to allow for copying their actions. It is called by AVDocCopyAction().
	AVActionDoPropertiesExProc A callback for AVActionHandlerProcs. If defined, it is called instead of DoProperties().
	AVActionDoPropertiesProc A callback for AVActionHandlerProcs(). It displays a user interface that allows a user to set the action's properties. For example, for a Launch action, set the file to launch; for a GoTo action, select the destination page/zoom coordinates).
	AVActionEnumProc A callback used by AVAppEnumActionHandlers(). It is called once for each action handler.
	AVActionFillActionDictProc (Required) A callback for AVActionHandlerProcs(). This required function is called as soon as the user selects the action from the action types popup menu. It allows an action handler to populate a newly created action's actionDict. At the time this method is called, the information needed to completely specify an action is often not yet available. As a result, this method is generally a good place to populate the actionDict with default values.
	AVActionGetButtonTextProc A callback for AVActionHandlerProcs. This optional function should store into buffer a NULL-terminated C string that is a localized string for the edit action button in the action dialog box.
	AVActionGetDetailsProc Optional callback for AVActionHandlerProcs(). It is called to get informational details to present to the user. The handler can provide one or more ASText strings which are added to the ASCab provided by the caller. Generally, each string should form a single informational item, often provided in a "key: value" format. The caller will organize the strings into a list that is presented in the user interface.
	AVActionGetInstructionsProc A callback for AVActionHandlerProcs(). This optional function should store into buffer a NULL-terminated C string that contains localized instructions for the action creation/properties dialog box.
	AVActionGetStringOneTextProc (Optional) A callback for AVActionHandlerProcs(). This function should store into buffer a NULL-terminated C string that is a localized string placed above the edit action button in the action dialog box. A NULL proc will cause the button to hide.
	AVActionGetStringTwoTextProc A callback for AVActionHandlerProcs(). This optional function should store into buffer a NULL-terminated C string which is a localized string placed below the edit action button in the action dialog box.
	AVActionPerformExProc A callback for AVActionHandlerProcs(). If defined, it is called instead of AVActionPerformProc(). It is passed the context of an action, which provides information on what triggered the action.
	AVActionPerformProc A callback for AVActionHandlerProcs(). It performs the action.

	Method
	AVActionHandlerProcs AVActionHandlerGetProcs(AVActionHandler handler) Gets a structure containing pointers to the action handler's procedures.
	ASAtom AVActionHandlerGetType(AVActionHandler handler) Gets the ASAtom specifying what type of actions an action handler services. This is the same as the name used when the action handler was registered using AVAppRegisterActionHandler().
	const char* AVActionHandlerGetUIName(AVActionHandler handler) Gets the string that was passed as the user friendly when the action handler was registered using AVAppRegisterActionHandler().

Typedefs Detail

AVActionContext

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _AVActionContextRec AVActionContext;

File: AVExpT.h

Line: 5748

AVActionContextRec

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _AVActionContextRec AVActionContextRec;

File: AVExpT.h

Line: 5748

AVActionHandler

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

typedef struct _t_AVActionHandler* AVActionHandler;

Carries out an action. When the Acrobat viewer executes an action, it looks for the action handler with a type matching that of the action it is trying to execute. The Acrobat viewer invokes the matching handler to perform the action. If no match is found, the Acrobat viewer ignores the user action.

File: AVExpT.h

Line: 5520

AVActionHandlerProcs

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _t_AVActionHandlerProcs AVActionHandlerProcs;

File: AVExpT.h

Line: 5525

AVActionHandlerProcsRec

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _t_AVActionHandlerProcs AVActionHandlerProcsRec;

File: AVExpT.h

Line: 5849

Structure Detail

_AVActionContextRec

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

struct _AVActionContextRec {

  ASSize_t size;  


 


  CosObj co;  


 


  ASAtom asaType;  


 


  ASAtom asaKey;  

}

This structure gives the action handler some context in terms of its execution. It specifies the " parent" object, which initiated the action, and the trigger type of the action. Trigger names should correspond to the key used in the AA dictionary of the file.

See Also

AVActionPerformExProc

File: AVExpT.h

Line: 5720

Elements

	size	The size of this record. It must be set to `sizeof(AVActionContextRec)`.

	co	The object that is performing the action, such as a bookmark or annotation.

	asaType	The type of the object, using these defines: `define AVTRIGGERTYPE_DOC ASAtomFromString("Doc")` `define AVTRIGGERTYPE_DEST ASAtomFromString("Dest")` `define AVTRIGGERTYPE_PAGE ASAtomFromString("Page")` `define AVTRIGGERTYPE_LINK ASAtomFromString("Link")` `define AVTRIGGERTYPE_ANNOT ASAtomFromString("Annot")` `define AVTRIGGERTYPE_BOOKMARK ASAtomFromString("Bookmark")`

	asaKey	The trigger name for the object, using these defines: `define AVTRIGGER_MOUSEUP ASAtomFromString("Mouse Up")` `define AVTRIGGER_OPEN ASAtomFromString("Open")` `define AVTRIGGER_CLOSE ASAtomFromString("Close")`

_t_AVActionHandlerProcs

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

struct _t_AVActionHandlerProcs {

  ASSize_t size;  


 


  AVActionPerformProc Perform;  


 


  AVActionDoPropertiesProc DoProperties;  


 


  AVActionFillActionDictProc FillActionDict;  


 


  AVActionGetInstructionsProc GetInstructions;  


 


  AVActionGetButtonTextProc GetButtonText;  


 


  AVActionGetStringOneTextProc GetStringOneText;  


 


  AVActionGetStringTwoTextProc GetStringTwoText;  


 


  AVActionCopyProc Copy;  


 


  AVActionPerformExProc PerformEx;  


 


  AVActionDoPropertiesExProc DoPropertiesEx;  


 


  AVActionGetDetailsProc GetDetails;  

}

A data structure containing callbacks that implement an action handler. The callbacks implement the action handler functions. For example, they can display user interface text, request the action's properties from the user, and perform the action.

File: AVExpT.h

Line: 5811

Elements

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

Callbacks Detail

AVActionCopyProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

PDAction (*AVActionCopyProc)(void *actionHandlerObj, AVDoc fromDoc, PDAction anAction, AVDoc toDoc)

(Optional) A callback for AVActionHandlerProcs(). It is called upon to copy an action, possibly to another document. Action handlers should provide this callback to allow for copying their actions. It is called by AVDocCopyAction().

See Also

AVDocCopyAction
AVActionHandlerGetProcs

File: AVExpT.h

Line: 5692

AVActionDoPropertiesExProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool (*AVActionDoPropertiesExProc)(void *actionHandlerObj, AVDoc doc, PDAction *actions, ASArraySize numActions)

A callback for AVActionHandlerProcs. If defined, it is called instead of DoProperties().

It is called to allow the user to view or edit the properties for an array of actions. Typically this presents a modal OK/Cancel dialog box to the user. The dialog box should graphically denote properties that do not have the same value for every action in the array by using an indeterminant state. For example, if the action has a flag property that is set to true for one action and false for another, instead of "true" or "false", the dialog box could show the string "<varies>" for that property. The user will still be able to change the "<varies>" string to either true or false, which would apply the new value to every action in the array.

See Also

AVActionHandlerGetProcs

File: AVExpT.h

Line: 5802

AVActionDoPropertiesProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

void (*AVActionDoPropertiesProc)(void *actionHandlerObj, PDAction action, AVDoc doc)

A callback for AVActionHandlerProcs(). It displays a user interface that allows a user to set the action's properties. For example, for a Launch action, set the file to launch; for a GoTo action, select the destination page/zoom coordinates).

See Also

AVActionHandlerGetProcs
AVActionDoPropertiesEx

File: AVExpT.h

Line: 5572

AVActionEnumProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool (*AVActionEnumProc)(ASAtom type, char *userName, void *clientData)

A callback used by AVAppEnumActionHandlers(). It is called once for each action handler.

File: AVExpT.h

Line: 5540

AVActionFillActionDictProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

void (*AVActionFillActionDictProc)(void *actionHandlerObj, CosObj actionDict, AVDoc doc)

(Required) A callback for AVActionHandlerProcs(). This required function is called as soon as the user selects the action from the action types popup menu. It allows an action handler to populate a newly created action's actionDict. At the time this method is called, the information needed to completely specify an action is often not yet available. As a result, this method is generally a good place to populate the actionDict with default values.

See Also

AVActionHandlerGetProcs

File: AVExpT.h

Line: 5590

AVActionGetButtonTextProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

AVTArraySize (*AVActionGetButtonTextProc)(void *actionHandlerObj, PDAction action, char *buffer, AVTArraySize bufLen, AVDoc doc)

A callback for AVActionHandlerProcs. This optional function should store into buffer a NULL-terminated C string that is a localized string for the edit action button in the action dialog box.

For example, the Acrobat viewer's built-in OpenFile action returns "Select File" for this string.

File: AVExpT.h

Line: 5630

AVActionGetDetailsProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

void (*AVActionGetDetailsProc)(void *actionHandlerObj, AVDoc doc, PDAction action, ASCab details)

Optional callback for AVActionHandlerProcs(). It is called to get informational details to present to the user. The handler can provide one or more ASText strings which are added to the ASCab provided by the caller. Generally, each string should form a single informational item, often provided in a "key: value" format. The caller will organize the strings into a list that is presented in the user interface.

See Also

AVActionHandlerGetProcs

File: AVExpT.h

Line: 5710

AVActionGetInstructionsProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

AVTArraySize (*AVActionGetInstructionsProc)(void *actionHandlerObj, PDAction action, char *buffer, AVTArraySize bufLen, AVDoc doc)

A callback for AVActionHandlerProcs(). This optional function should store into buffer a NULL-terminated C string that contains localized instructions for the action creation/properties dialog box.

File: AVExpT.h

Line: 5609

AVActionGetStringOneTextProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

AVTArraySize (*AVActionGetStringOneTextProc)(void *actionHandlerObj, PDAction action, char *buffer, AVTArraySize bufLen, AVDoc doc)

(Optional) A callback for AVActionHandlerProcs(). This function should store into buffer a NULL-terminated C string that is a localized string placed above the edit action button in the action dialog box. A NULL proc will cause the button to hide.

For example, the Acrobat viewer's built-in OpenFile action returns "File N: \<the current filename\>" for this string.

File: AVExpT.h

Line: 5653

AVActionGetStringTwoTextProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

AVTArraySize (*AVActionGetStringTwoTextProc)(void *actionHandlerObj, PDAction action, char *buffer, AVTArraySize bufLen, AVDoc doc)

A callback for AVActionHandlerProcs(). This optional function should store into buffer a NULL-terminated C string which is a localized string placed below the edit action button in the action dialog box.

For example, the Acrobat viewer's built-in OpenFile action returns nothing for this string, but the built-in GoToView action returns a description of the current zoom type.

File: AVExpT.h

Line: 5676

AVActionPerformExProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

void (*AVActionPerformExProc)(void *actionHandlerObj, PDAction action, AVDoc doc, AVActionContext context)

A callback for AVActionHandlerProcs(). If defined, it is called instead of AVActionPerformProc(). It is passed the context of an action, which provides information on what triggered the action.

File: AVExpT.h

Line: 5776

AVActionPerformProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

void (*AVActionPerformProc)(void *actionHandlerObj, PDAction action, AVDoc doc)

A callback for AVActionHandlerProcs(). It performs the action.

File: AVExpT.h

Line: 5558

Method Detail

AVActionHandlerGetProcs

()

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax





AVActionHandlerProcs AVActionHandlerGetProcs(AVActionHandler handler)

Gets a structure containing pointers to the action handler's procedures.

This method is useful when you want to subclass a previously registered action handler. Acrobat releases the previously registered action handler when you call AVAppRegisterActionHandler(), so you must copy the previously registered action handler to a new action handler structure, which you use in the call to AVAppRegisterActionHandler().

Parameters

handler —

IN The action handler whose procedures are obtained.

Returns

A pointer to a structure that contains the action handler's callbacks.

See Also

AVAppRegisterActionHandler

Since

PI_ACROVIEW_VERSION >= 0x00020000

File: AVProcs.h

Line: 84

AVActionHandlerGetType

()

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax





ASAtom AVActionHandlerGetType(AVActionHandler handler)

Gets the ASAtom specifying what type of actions an action handler services. This is the same as the name used when the action handler was registered using AVAppRegisterActionHandler().

Parameters

handler —

IN The action handler whose type is obtained.

Returns

The ASAtom specifying what action types handler services.

Since

PI_ACROVIEW_VERSION >= 0x00020000

File: AVProcs.h

Line: 57

AVActionHandlerGetUIName

()

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax





const char* AVActionHandlerGetUIName(AVActionHandler handler)

Gets the string that was passed as the user friendly when the action handler was registered using AVAppRegisterActionHandler().

Parameters

handler —

IN The action handler whose user interface name is obtained.

Returns

The user interface name of handler.

See Also

AVAppRegisterActionHandler

Since

PI_ACROVIEW_VERSION >= 0x00020000

File: AVProcs.h

Line: 68

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

	ASSize_t size;

	CosObj co;

	ASAtom asaType;

	ASAtom asaKey;

	ASSize_t size;

	AVActionPerformProc Perform;

	AVActionDoPropertiesProc DoProperties;

	AVActionFillActionDictProc FillActionDict;

	AVActionGetInstructionsProc GetInstructions;

	AVActionGetButtonTextProc GetButtonText;

	AVActionGetStringOneTextProc GetStringOneText;

	AVActionGetStringTwoTextProc GetStringTwoText;

	AVActionCopyProc Copy;

	AVActionPerformExProc PerformEx;

	AVActionDoPropertiesExProc DoPropertiesEx;

	AVActionGetDetailsProc GetDetails;

Layer	AV_Layer
Object	AVActionHandler