AMAction Class Reference

Inherits from
NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/Automator.framework
Availability
Available in OS X v10.4 and later.
Companion guide
Automator Programming Guide
Declared in
AMAction.h
Related sample code

Overview

AMAction is an abstract class that defines the interface and general characteristics of Automator actions. Automator is an Apple-provided application that allows users to construct and execute workflows consisting of a sequence of discrete modules called actions. An action performs a specific task, such as copying a file or cropping an image, and passes its output to Automator to give to the next action in the workflow. Actions are currently implemented as loadable bundles owned by objects of the AMBundleAction class, a subclass of AMAction.

The critically important method declared by AMAction is runWithInput:fromAction:error:. When Automator executes a workflow, it sends this message to each action object in the workflow (in workflow sequence), in most cases passing in the output of the previous action as input. The action object performs its task in this method and ends by returning an output object for the next action in the workflow.

Subclassing Notes

Subclassing AMAction is not recommended. For most situations requiring an enhancement to the Automator framework, it is sufficient to subclass AMBundleAction or one of its public subclasses, AMAppleScriptAction or AMShellScriptAction.

Tasks

Initialization and Encoding

Controlling the Action

Initializing and Synchronizing the Action User Interface

Updating Action Parameters

Getting Information About the Action

Instance Methods

activated

Invoked when the window of the Automator workflow to which the receiver belongs becomes the main window. This allows the receiver to synchronize its information with settings in another application.

- (void)activated
Discussion

Be sure to invoke the superclass implementation of this method as the last thing in your implementation.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
AMAction.h

closed

Invoked by Automator when the receiving action is removed from a workflow, allowing it to perform cleanup operations.

- (void)closed
Discussion

This method is intended to be overridden, so that your action can perform its specific cleanup operations.

Availability
  • Available in OS X v10.5 and later.
Declared In
AMAction.h

ignoresInput

Returns a Boolean value that indicates whether the action acts upon its input or the input is ignored.

- (BOOL)ignoresInput
Return Value

YES if the action acts upon its input, otherwise NO.

Discussion

Many actions act upon their input, but an action may merely pass on its input or, rarely, ignore it.

Special Considerations

Although this method was documented in OS X version 10.4, and an action would respond to this message, the method was not made public, and using it would generate a warning in Xcode.

Availability
  • Available in OS X v10.5 and later.
Declared In
AMAction.h

initWithContentsOfURL:error:

Loads an Automator action from a file URL.

- (id)initWithContentsOfURL:(NSURL *)fileURL error:(NSError **)outError
Parameters
fileURL

URL that specifies the location of an action file.

outError

If no action is found or if an error occurs in initializing or running it, upon return contains an instance of NSError that describes the problem. For keys and error constants used with action errors, see Automator Constants Reference.

Return Value

The initialized action.

Discussion

This method is typically invoked by applications that use the AMWorkflow class to embed Automator workflows. It is used to allow creation of actions for a workflow.

Availability
  • Available in OS X v10.5 and later.
Declared In
AMAction.h

initWithDefinition:fromArchive:

Initializes the receiver with the specified definition.

- (id)initWithDefinition:(NSDictionary *)dict fromArchive:(BOOL)archived
Parameters
dict

Describes the action, including any custom definition properties.

archived

If the receiver is being unarchived, YES, otherwise NO.

Return Value

The initialized action.

Discussion

This is the primary initializer for all Automator classes. The Automator application sends this message to instances of AMAction both when it loads actions bundles and when it unarchives them.

The AMAction object being instantiated should perform whatever initializations are necessary after invoking super’s implementation of this method. It can then examine the values in dict, particularly if the receiver had been archived with custom definition properties.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
AMAction.h

name

Returns the name of the action.

- (NSString *)name
Return Value

The name of the receiving action.

Availability
  • Available in OS X v10.5 and later.
Declared In
AMAction.h

opened

Invoked when the receiver is first added to a workflow, allowing it to initialize its user interface.

- (void)opened
Discussion

You should perform all initializations of an action’s user interface in this method and not in awakeFromNib. Be sure to invoke the superclass implementation of this method as the final step of your implementation.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
AMAction.h

output

Returns the receiver’s output.

- (id)output
Return Value

The receiving action’s output, or nil if called before the action is run.

Discussion

This method is used in conjunction with the AMWorkflow class, which allows access to the actions in a workflow.  Within a workflow, for example, you might iteratively inspect the output of each action. Or, on completion of a workflow, you might examine the output of the last action, to determine the output of the workflow.

Availability
  • Available in OS X v10.5 and later.
Related Sample Code
Declared In
AMAction.h

parametersUpdated

Requests the receiver to update its user interface from its stored parameters, which have changed.

- (void)parametersUpdated
Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
AMAction.h

reset

Resets the receiver to its initial state.

- (void)reset
Discussion

Resetting causes the action to release its output generated from the current execution of the workflow.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
AMAction.h

runAsynchronouslyWithInput:

Causes Automator to wait for notification that the receiver has completed execution, which allows the receiver to perform an asynchronous operation.

- (void)runAsynchronouslyWithInput:(id)input
Parameters
input

The input for the action. Should contain one or more objects compatible with one of the types specified in the action’s AMAccepts property.

Discussion

This method should be overridden only by actions that need to make asynchronous calls. After runAsynchronouslyWithInput: is invoked, Automator does not continue until the action invokes didFinishRunningWithError:. So in your override of this method, you can make an asynchronous call, wait to be notified of its completion, then invoke didFinishRunningWithError: to signal to Automator that the action has completed.

For actions that do not need to make asynchronous calls, the preferred method is runWithInput:fromAction:error:.

Availability
  • Available in OS X v10.5 and later.
Declared In
AMAction.h

stop

Stops the receiver from running.

- (void)stop
Discussion

The output acquired by the action during execution of the current workflow is still accessible to Automator.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
AMAction.h

updateParameters

Requests the receiver to update its stored set of parameters from the settings in the action’s user interface.

- (void)updateParameters
Discussion

This message is sent just before an action is saved, copied, or run. Preferably, an action’s settings should not solely reside in the controls of its view, but if they do, the action can fetch and save them in this method.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
AMAction.h

willFinishRunning

Invoked by Automator when the receiver has essentially completed its run phase.

- (void)willFinishRunning
Discussion

This method is intended to be overridden. An action can use this method to perform cleanup operations, such as closing windows and deallocating memory.

Availability
  • Available in OS X v10.5 and later.
Declared In
AMAction.h

writeToDictionary:

Examines the parameters and other configuration information specified in the passed dictionary and add its own information to it if appropriate.

- (void)writeToDictionary:(NSMutableDictionary *)dictionary
Parameters
dictionary

Possibly contains parameter and other configuration information about the receiver.

Discussion

Automator sends this message to an action object prior to archiving it. In its implementation of this method, the action object should first invoke the superclass implementation.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
AMAction.h


© 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-03-01)

Did this document help you? Yes It's good, but... Not helpful...