AutoSample
==========

* :download:`Download example <PyObjCExample-AutoSample.zip>`

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:

(a) 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)

(b) 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.


(c) 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.


(d) 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.


.. rst-class:: tabber

Sources
-------

.. rst-class:: tabbertab

Controller.py
.............

.. sourcecode:: python

    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

.. rst-class:: tabbertab

main.py
.......

.. sourcecode:: python

    import Controller  # noqa: F401
    from PyObjCTools import AppHelper
    
    AppHelper.runEventLoop()

.. rst-class:: tabbertab

setup.py
........

.. sourcecode:: python

    """
    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"],
    )

