PSActionControlProcs Struct Reference
[Action Control Suite]

The set of routines available in the Action Control Suite. More...

#include <PIActions.h>


Data Fields

SPAPI OSErr(* Play )(PIActionDescriptor *result, DescriptorEventID event, PIActionDescriptor descriptor, PIDialogPlayOptions options)
 Dispatches an event into the actions mechanism.
SPAPI OSErr(* Get )(PIActionDescriptor *result, PIActionReference reference)
 Gets a property from the host.
SPAPI OSErr(* StringIDToTypeID )(const char *stringID, DescriptorTypeID *typeID)
 Returns the runtime ID for a string.
SPAPI OSErr(* TypeIDToStringID )(DescriptorTypeID typeID, char *stringID, uint32 stringLength)
 Returns the string for an ID.
SPAPI OSErr(* AddNotify )(SPPluginRef ref, DescriptorEventID event, PIEventNotifier notifier, void *data)
 Allows the plug-in to provide a notification routine for specific events.
SPAPI OSErr(* RemoveNotify )(SPPluginRef ref, DescriptorEventID event)
 Removes a notifier for an event.
SPAPI OSErr(* SuspendHistory )(PIActionReference reference, PISuspendProc proc, void *procData, ASZString operationName)
 Suspends recording of events to the History Palette for a given document, then invokes a plug-in callback function.
SPAPI OSErr(* MakeStringAlias )(const char *newStringID, const char *existingStringID)
 Creates a new string with the same runtime ID as an existing string.

Detailed Description

The set of routines available in the Action Control Suite.


Field Documentation

Dispatches an event into the actions mechanism.

Parameters:
result [OUT] Descriptor containing the result of the event. If Play returns an error, this may contain keyMessage, a string with the error message. Caller needs to free this descriptor if not NULL.
event Event to play.
descriptor Descriptor describing any specific parameters for that event (if any),
options Dialog play options. See dialogPlayEnum.
Returns:
Non-zero error if failure.

Gets a property from the host.

The actions system also serves as a database for properties; use the Get routine as a quick way to get properties from the host.

Parameters:
reference The property to get. The reference provides the class from which the properties are retrieved, and may also provide a specific key, enumeration, index, etc. to pull. The plug-in must build this reference to the object and the property by using the Action Reference Suite.
result [OUT] A descriptor with the pertinent information. The plug-in is responsible for freeing this memory, when it has finished using result.
Returns:
Non-zero error if failure.

SPAPI OSErr(* PSActionControlProcs::StringIDToTypeID)(const char *stringID, DescriptorTypeID *typeID)

Returns the runtime ID for a string.

Parameters:
stringID string value to convert
typeID [OUT] Four character runtime ID.
Returns:
Non-zero error if failure.

SPAPI OSErr(* PSActionControlProcs::TypeIDToStringID)(DescriptorTypeID typeID, char *stringID, uint32 stringLength)

Returns the string for an ID.

Parameters:
typeID ID value to convert
stringID {OUT} string value representing ID
stringLength Maximum string length.
Returns:
Non-zero error if failure.

SPAPI OSErr(* PSActionControlProcs::AddNotify)(SPPluginRef ref, DescriptorEventID event, PIEventNotifier notifier, void *data)

Allows the plug-in to provide a notification routine for specific events.

Any one event can only dispatch to one notifier routine, but one notifier routine can receive multiple events. Use eventAll to dispatch all events to a single notifier routine.

Note:
The plug-in is responsible for removing any notifiers it adds. See RemoveNotify.
Parameters:
ref Plug-in reference to calling plug-in. The host passes this reference to the plug-in through the message data. See the Adobe PICA API.
event Any event. Use eventAll for all events.
notifier Routine to evoke when the event occurs.
data Any local data; passed through to the event notification routine.
Returns:
Non-zero error if failure.

SPAPI OSErr(* PSActionControlProcs::RemoveNotify)(SPPluginRef ref, DescriptorEventID event)

Removes a notifier for an event.

Use eventAll to remove notifiers for all events.

Parameters:
ref Plug-in reference to calling plug-in. The host passes this reference to the plug-in through the message data. See the PICA Reference Manual.
event The event to remove notifier for.
Returns:
Non-zero error if failure.

SPAPI OSErr(* PSActionControlProcs::SuspendHistory)(PIActionReference reference, PISuspendProc proc, void *procData, ASZString operationName)

Suspends recording of events to the History Palette for a given document, then invokes a plug-in callback function.

Once the callback function returns, history recording is re-enabled, and a final state is added to the History Palette with the label provided in operationName.

Parameters:
reference Reference to a document, or something contained in one. The plug-in must build the reference by using the Action Reference Suite.
proc The plug-in callback function, which plays actions that are not recorded.
procData Data passed through to proc.
operationName Final state added to the History Palette once proc completes, and history recording is resumed.
Returns:
Non-zero error if failure.

SPAPI OSErr(* PSActionControlProcs::MakeStringAlias)(const char *newStringID, const char *existingStringID)

Creates a new string with the same runtime ID as an existing string.

This is useful when the original string contains characters that aren't legal in C identifiers and thus can't be used in the various string- based descriptor calls.

Parameters:
newStringID The new string to create.
existingStringID The string whose runtime ID the new string will share.
Returns:
Non-zero error if failure.


The documentation for this struct was generated from the following file: