Automator Framework
Bug Fixes and Enhancements
Backward Compatibility for Revised Actions
The Automator framework introduces three new classes for Leopard that will enable developers to load, edit, and execute Automator workflows in their applications. These classes follow the MVC (model, view, and controller) paradigm, and are called “AMWorkflow”, “AMWorkflowController”, and “AMWorkflowView”. There are also API additions for “AMAction”. (These and other Automator classes are also described in Automator Framework Reference.)
The Automator framework is now 64-bit and GC (Garbage Collection) ready.
The Automator plug-in for Interface Builder 3.0 has been updated to include AMWorkflowController and AMWorkflowView objects.
AMWorkflow is a class that represents an Automator workflow in memory. Workflows can be loaded from disk using the -[AMWorkflow initWithContentsOfURL:error:] method. If the workflow fails to load, an NSError will be returned in the error parameter. See AutomatorErrors.h or Automator Constants Reference for error descriptions.
Once the workflow is loaded, you can obtain the actions it contains from the -[AMWorkflow actions] method. You can also add, remove, and reorder actions. To save the workflow to disk, you invoke -[AMWorkflow writeToURL:error:]. If the workflow fails to save, an NSError is returned in the error parameter. See AutomatorErrors.h for error descriptions.
You can execute a workflow by invoking the +[AMWorkflow runWorkflowAtURL:withInput:error:] class method. This method returns the results of the workflow. If an error occurs, the result is nil and an error is returned in the error parameter. If you use this method, you do not have to pre-load the workflow, but you have less control than is offered by “AMWorkflowController”.
Another new Leopard feature in Automator is workflow variables, and the AMWorkflow class has methods that allow you to get and set values of variables. Simply invoke -[AMWorkflow valueForVariableWithName:] to get the value of a variable in the workflow, or -[AMWorkflow setValue:forVariableWithName:] to set the value of a variable.
AMWorkflowController is the controller class for Automator workflows. It provides a link between AMWorkflow and AMWorkflowView, provides feedback about a running workflow, and contains methods to run and stop a workflow.
To use an AMWorkflowController to run a workflow, allocate an AMWorkflowController object and set its workflow by invoking -[AMWorkflowController setWorkflow:]. You can then run the workflow by invoking -[AMWorkflowController run:]. To stop the workflow, invoke -[AMWorkflowController stop:]. There are two methods that will let you get the state of the running workflow, -[AMWorkflowController canRun] and -[AMWorkflowController isRunning]. Both of these properties are key-value observable.
AMWorkflowController provides a handful of optional delegate methods. When a running workflow reaches a certain progress point, if the AMWorkflowController has a delegate and it implements the appropriate delegate method, the delegate will be invoked. The delegate methods are:
- (void)workflowControllerWillRun:(AMWorkflowController *)controller;
- (void)workflowControllerWillStop:(AMWorkflowController *)controller;
- (void)workflowControllerDidRun:(AMWorkflowController *)controller;
- (void)workflowControllerDidStop:(AMWorkflowController *)controller;
- (void)workflowController:(AMWorkflowController *)controller willRunAction:(AMAction *)action;
- (void)workflowController:(AMWorkflowController *)controller didRunAction:(AMAction *)action;
- (void)workflowController:(AMWorkflowController *)controller didError:(NSError *)error;
To set a delegate, invoke -[AMWorkflowController setDelegate:]. The delegate can be any object.
AMWorkflowView is an NSView subclass that developers can add to any window to view and edit an Automator workflow.
To use AMWorkflowView to view an Automator workflow, you set it as the workflow view of an AMWorkflowController by calling -[AMWorkflowController setWorkflowView:]. When an AMWorkflow object is set as the workflow of the associated AMWorkflowController, that workflow is automatically displayed in the AMWorkflowView.
To disable editing of a workflow displayed in an AMWorkflowView, call -[AMWorkflowView setEditable:NO] (the default is YES). Users will still be able to edit the properties of any actions in the workflow, but will not be able to add, remove, disable, change input, or move them.
There are several new APIs for AMAction in Leopard. The method -[AMAction initWithContentsOfURL:error:] allows developers to load Automator actions from disk, possibly for addition to an AMWorkflow. If the action fails to load an error is returned. See AutomatorErrors.h for error descriptions.
There is a new API, -[AMAction runAsynchronouslyWithInput:], for developers who need to write actions that implement asynchronous callbacks or must wait for notifications before returning. Automator will call this method (if implemented, otherwise it will call -[AMAction runWithInput:fromAction:error:]) when the action is run, and it will continue to run until the action calls -[AMAction didFinishRunningWithError:] on itself. The error parameter should be a dictionary utilizing the same keys as the one returned from -[AMAction runWithInput:fromAction:error:].
To get the output of any action, call -[AMAction output]. This method was documented in Tiger but was private until Leopard.
To add support for workflow variables, action developers should replace instances of NSTextField with AMTokenField, where appropriate. An AMTokenField object is supplied by the Automator plug-in for Interface Builder 3.0. It is up to the action developer to determine which text fields should be replaced, as token fields may not make sense for every situation. AMTokenFields do not currently support formatters.
A new key, AMDWebsite, has been added to the Info.plist for actions. This optional key should be placed in the AMDescription block of the Info.plist and the value should contain a URL. This key-value pair has been added to the user visible action description, and the URL is represented by a clickable link.
In Tiger, the value for the AMCategory key could be an arbitrary string, but for Leopard the accepted values have been replaced with category keywords. For backwards compatibility, Automator will attempt to match Tiger values to Leopard keywords, and any actions that fail will be placed in the "Other" category. The categories keywords that are supported in Leopard are:
AMCategoryCalendar
AMCategoryChat
AMCategoryContacts
AMCategoryDeveloper
AMCategoryDocuments
AMCategoryFilesAndFolders
AMCategoryFonts
AMCategoryInternet
AMCategoryMail
AMCategoryMovies
AMCategoryMusic
AMCategoryPDFs
AMCategoryPhotos
AMCategoryPresentations
AMCategorySystem
AMCategoryText
AMCategoryUtilities
There are several Automator bug fixes and enhancements for Leopard. Among them:
Error handling has been improved substantially, especially when loading actions and workflows. A list of common errors is located in AutomatorErrors.h and described in Automator Constants Reference.
The Automator framework and many of the Automator actions that ship with Leopard now support relative paths. Any actions that accept path data (such as com.apple.cocoa.path) should be updated to support relative paths (such as ~/Desktop/foo).
Any image type that is supported by NSImage can now be used as an action's icon. In Tiger, only .tiff files were supported.
Automator now supports actions that change the size of their user interface dynamically. Specifically, Automator will respond appropriately to any action that calls -setFrame or -setFrameSize on its view.
In Tiger, if a workflow uses an action, and the user replaces that action on disk with a newer version in which the developer has changed the value of the NSPrincipalClass entry in the action’s Info.plist, the action won't load when the user executes the workflow.
This problem has been fixed in Leopard, but if you need to ensure backward compatibility in Tiger for revised actions, you should avoid changing the value of the NSPrincipalClass entry.
© 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-10-31)
|