AutoSample

Overview

This sample displays a single window containing a list of workflows and a read only AMWorkflowView. The workflows listed are the ones found in the Application’s resources in the folder:

/AutoSample.app/Contents/Resources/workflows/

When the application starts up it scans the workflows folder and loads each Automator workflow found there as an instance of AMWorkflow. It then stores these AMWorkflow instances in an array along with the file names. That array is used as the backing store for the NSTableView in the window.

When a click is received on the name of a workflow in the NSTableView, the workflow is displayed in the AMWorkflowView on the right hand side of the window.

When a double-click is received on the name of a workflow in the NSTableView (or, when the “run” button is pressed), the selected workflow is displayed in the AMWorkflowView on the right hand side of the window and it is run.

Initialization Details

All of the setup for this sample is performed in the -awakeFromNib method. The important features to note there are as follows:

  1. The AMWorkflowView is being used for display purposes only. As such, we mark the view as read only by turning off it’s editing features with the following method call:

    workflowView.setEditable_(False)

  2. We don’t actually manage the AMWorkflowView ourselves. Rather, we use an AMWorkflowController to take care of that. In this sample, we have added an AMWorkflowController to our .nib file and we have set the AMWorkflowView displayed in the main window as it’s workFlowView.

With this arrangement, our Controller object does not have to worry about the details of operating the AMWorkflowView's user interface, as the AMWorkflowController will take care of that.

So methods in the Controller object can receive information about the status of the view we have set our Controller object as the AMWorkflowController's delegate. With our controller object set as the AMWorkflowController delegate, the AMWorkflowController will call back to our Controller object to provide status information about the AMWorkflow it is displaying in the AMWorkflowView.

To run and display specific AMWorkflows, we will want to call methods on the AMWorkflowController. So we can do that from methods implemented in the Controller object, we have added an instance variable to the Controller object where we store a reference to the AMWorkflowController object.

All of these relationships have been set up by control-dragging between objects in the Interface Builder interface. You can use the connections inspector in Interface Builder to examine these connections.

  1. We allocate and initialize all of the AMWorkflow instances for the workflows found in our Resources folder and we store them in a NSArray. It’s worth noting that we populate the NSArray with NSDictionary records that include the AMWorkflow instance, the file name, and the path.

  2. we have set up an array controller to manage the contents of the NSTableView. To do that, we have bound the content array of the array controller to the workflows value stored in our Controller object. In the column of the table we have bound the value to the arrangedObjects controller key on the Array Controller. Back in our controller object, we have stored a reference to the Array Controller in the tableContent outlet so we can access its arrangedObjects value (to allow us to access the values displayed in the table no matter how the user has sorted the list by clicking on the table header).

AMWorkflowController delegate methods

We implement two AMWorkflowController delegate methods in this sample. Namely, workflowControllerWillRun: and workflowControllerDidRun:. The first method is called just before a workflow being managed by the AMWorkflowController is run and the second is called just after it finishes running.

We use these methods to display the progress bar and to set the internal runningWorkflow flag. We use bindings based on the runningWorkflow flag to display the progress bar, enable the stop button while a workflow is running, and disable the run button while a workflow is running. Also, we use the runningWorkflow flag to prevent certain user actions, such as switching the AMWorkflowController to another workflow, while a workflow is still running.

Running a workflow

We have set the run method on the AMWorkflowController as the target action for the run button. Bindings based on the runningWorkflow flag control the availability of this button (by controlling its enabled state) for starting a new workflow.

We have set the stop method on the AMWorkflowController as the target action for the stop button. Bindings based on the runningWorkflow flag control the availability of this button (by controlling its enabled state) for stopping a new workflow.

Where to next?

Documentation for Automator AMWorkflowController and AMWorkflow can be found in the developer documentation.

Sources

Controller.py

import objc
from Automator import AMWorkflow
from Cocoa import (
    NSURL,
    NSBeginInformationalAlertSheet,
    NSBundle,
    NSIndexSet,
    NSMutableArray,
    NSObject,
)


class Controller(NSObject):
    # interface builder variables
    myWindow = objc.IBOutlet()
    workflowView = objc.IBOutlet()
    workflowTable = objc.IBOutlet()
    workflowController = objc.IBOutlet()
    tableContent = objc.IBOutlet()

    # instance variables
    _workflows = objc.ivar()
    _runningWorkflow = objc.ivar.bool()

    def workflows(self):
        return self._workflows

    def setWorkflows_(self, value):
        self._workflows = value

    def runningWorkflow(self):
        return self._runningWorkflow

    def setRunningWorkflow_(self, value):
        self._runningWorkflow = value

    # display the selected workflow.
    def displaySelectedWorkflow(self):
        # get the selected row from the workflow table.
        theRow = self.workflowTable.selectedRow()

        # if there is a selection and we are not running
        # the selected workflow, then we can display the
        # workflow selected in the list.
        if theRow != -1 and not self._.runningWorkflow:
            # retrieve the first item in the selection
            selectedEntry = self.tableContent.arrangedObjects()[theRow]

            # retrieve the selected application from our list of applications.
            selectedWorkflow = selectedEntry["workflow"]

            # ask the AMWorkflowController to display the selected workflow
            self.workflowController.setWorkflow_(selectedWorkflow)

            # set the window title
            self.myWindow.setTitle_(selectedEntry["name"])

            return True

        else:
            return False

    # awakeFromNib is called after our MainMenu.nib file has been loaded
    # and the main window is ready for use.  Here, we finish initializing
    # our content for display in the window.
    def awakeFromNib(self):
        # we're only using the AMWorkflowView for display
        self.workflowView.setEditable_(False)

        # set up the data for NSTableView.  We'll store a list of
        # NSDictonary records each containing some information about the
        # workflow.  We'll display the name of the workflow's file in the
        # window.

        # set up an array for storing the table information
        theWorkflows = NSMutableArray.alloc().initWithCapacity_(20)

        # retrieve a list of all of the workflows stored in the application's
        # resourced folder.
        workflowPaths = NSBundle.mainBundle().pathsForResourcesOfType_inDirectory_(
            "workflow", "workflows"
        )

        # iterate through the paths, adding them to our table information
        # as we go.
        for nthWorkflowPath in workflowPaths:
            wfError = None

            # convert the path into an URL
            nthWorkflowURL = NSURL.fileURLWithPath_isDirectory_(nthWorkflowPath, False)

            # allocate and initialize the workflow
            nthWorkflow, wfError = AMWorkflow.alloc().initWithContentsOfURL_error_(
                nthWorkflowURL, None
            )

            if nthWorkflow:
                # calculate the file name without path or extension
                nthFileName = nthWorkflowPath.componentsSeparatedByString_("/")[-1]
                nthDisplayName = nthFileName[:-9]

                # add the workflow to the list
                theWorkflows.append(
                    {
                        "name": nthDisplayName,
                        "path": nthWorkflowPath,
                        "workflow": nthWorkflow,
                    }
                )

        # set the workflows
        self._.workflows = theWorkflows

        # if there are any workflows in the list, then select and display the first one */
        if len(self._.workflows):
            self.workflowTable.selectRowIndexes_byExtendingSelection_(
                NSIndexSet.indexSetWithIndex_(0), False
            )
            self.displaySelectedWorkflow()

    # NSApplication delegate method - for convenience. We have set the
    # File's Owner's delegate to our Controller object in the MainMenu.nib file.
    def applicationShouldTerminateAfterLastWindowClosed_(self, sender):
        return True

    # NSTableView delegate methods.
    # We have set our controller object as the NSTableView's delegate in the MainMenu.nib file.

    # selectionShouldChangeInTableView: is called when the user has clicked in the
    # table view in a way that will cause the selection to change.  This method allows us
    # to decide if we would like to allow the selection to change and the response
    # we return depends on if we are running a selection - we don't allow the selection
    # to change while a workflow is running.
    def selectionShouldChangeInTableView_(self, tableView):
        # if the current selected workflow is running, don't change the selection.
        if self._.runningWorkflow:
            # display an alert explaining why the selection cannot be changed.

            # get the name of the action that is running now.
            selectedWorkflow = self.tableContent.arrangedObjects()[
                self.workflowTable.selectedRow()
            ]["name"]

            # display a modal sheet explaining why the selection cannot be changed.
            NSBeginInformationalAlertSheet(
                f"The '{selectedWorkflow}' action is running.",
                "OK",
                None,
                None,
                self.myWindow,
                None,
                None,
                None,
                None,
                "You cannot select another action until the '%s' action has finished running."
                % (selectedWorkflow),
            )

        # return true only if we are not in the middle of running an action.
        return not self._.runningWorkflow

    # tableViewSelectionIsChanging: is called after the selection has changed.  All there
    # is to do here is update the workflow displayed in the AMWorkflowView to show the newly
    # selected workflow.
    def tableViewSelectionIsChanging_(self, notification):
        self.displaySelectedWorkflow()

    # AMWorkflowController delegate methods.  In these routines we adjust the
    # value of our runningWorkflow property.  Key value bindings to this property
    # defined in our interface file take care of enabling/disabling the run/stop buttons,
    # and displaying the progress bar.
    def workflowControllerWillRun_(self, controller):
        self._.runningWorkflow = True

    def workflowControllerDidRun_(self, controller):
        self._.runningWorkflow = False

    def workflowControllerDidStop_(self, controller):
        self._.runningWorkflow = False

main.py

import Controller  # noqa: F401
from PyObjCTools import AppHelper

AppHelper.runEventLoop()

setup.py

"""
Script for building the example.

Usage:
    python3 setup.py py2app
"""

from setuptools import setup

setup(
    name="AutoSample",
    app=["main.py"],
    data_files=["English.lproj", "workflows"],
    setup_requires=["pyobjc-framework-Automator", "pyobjc-framework-Cocoa"],
)