For detailed instructions and more information, launch UI Actions Setup and choose Help > UI Actions Setup Help. In addition, review the contents of the UI Actions Folder that is installed in your home Documents folder for a tutorial, example scripts and UI Actions, and extensive documentation.
If you have questions that aren't answered in the Help book, in the UI Actions Folder, or on this website, send email to us at firstname.lastname@example.org.
Notes for Users Running Mac OS X 10.7 Lion or 10.8 Mountain Lion
If you are running UI Actions 2.3.0 under Mac OS X 10.7 Lion, some of the example scripts in the UI Actions Folder will not run out of the box. Specifically, all of the example script applications or "applets" will crash with an alert telling you that the script "quit unexpectedly." To work around this problem, open the scripts in AppleScript Editor and run them there by clicking the Run button. Alternatively, use AppleScript Editor to recompile and save them to the UI Actions Folder as Lion script applications.
If you are running UI Actions 2.3.0 under Mac OS X 10.7 Lion or 10.8 Mountain Lion, scripts will not be triggered by actions if access is enabled only for "UI Actions alone." You must enable access for "all applications."
Tips for Writing UI Action Scripts
You can use any script editor to write and compile UI Action scripts. They are ordinary AppleScript scripts.
Here are some general tips for writing UI Actions scripts.
Scripts used with UI Actions fall into three categories:
- UI Action scripts. These are the scripts that UI Actions runs when it receives a notification from a target application.
- Setup and Detach scripts. These scripts attach a UI Action script to an application for a notification with an optional filter, or they detach one or more UI Action scripts. Setup and Detach scripts are useful when you need to automate the process of attaching and detaching UI Action scripts. When you don't need to automate this process, it is easier to use UI Actions Setup to attach and detach UI Action scripts. There is "live" interaction between UI Actions and UI Actions Setup. A change made in UI Actions Setup is instantly recognized by UI Actions, and a change made in UI Actions using AppleScript commands is instantly reflected in UI Actions Setup.
- Import and Export scripts. Import scripts import one or more UI Actions from a file and attach them. The file extension for files containing UI Actions sets is .uiactions. To create these files, first attach a set of scripts, then export them to a file. Scripts are attached when they are imported, but they are not detached when they are exported. UI Actions sets are particularly useful when switching from one project to another.
Limitations of UI Action Scripts
An attached UI Action script cannot intercept, modify, or supersede whatever action the target application normally performs when, for example, a menu item is chosen. Instead, the UI Action script runs after the application performs its normal action. In some respects, this means that UI Actions is less powerful than attachability implemented in a specific application, because scripts attached to an attachable application typically can change what the application normally does. At the same time, UI Action scripts can respond to user actions that an attachable application cannot. Very few applications implement attachability.
Interactive UI Action Scripts
Care must be taken when writing UI Action scripts that interact with users or take a long time to complete their tasks. It is possible to use the 'display dialog' command in a UI Action script, for example, but it will block other UI Action scripts until the user dismisses the dialog. Similarly, a slow UI Action script will block other UI Action scripts until it finishes. In Mac OS X 10.3 and newer, AppleScript scripts are queued up and run in first-in, first-out order, so you will not miss any UI Action scripts that are triggered, but they may not be triggered in a timely fashion unless you keep these issues in mind.
You should consider carefully what application is responsible for presenting dialogs in interactive UI Action scripts. Normally, it is best to tell the target application to display the dialog. This will minimize application switching and, as expected, the user will be prevented from clicking in other windows of the target application until the dialog is dismissed.
Presenting dialogs in the target application can cause problems under some circumstances. For example, if your UI Action script tells the target application to present a dialog whenever a menu item is selected, the dialog may appear as soon as you pull down the menu, causing the menu to close before you have a chance to select one of its menu items.
In cases like this, the best alternative is to activate UI Actions and tell it to present the dialog, because you can be confident that UI Actions is present and running (it is running the UI Action script). This works even though UI Actions is a faceless background application, because it is designed to present information to the user directly when told to do so. The menu bar will remain that of the target application, thus minimizing distraction and confusion for the user, because UI Actions does not have a menu bar. Be aware, however, that the user will be able to click in a target application window without dismissing the dialog, because the dialog and the application window are in separate applications.
You should not use UI Actions to display a dialog if the UI Action script is triggered by the "AXWindowCreated" notification. If the user clicks in a target application window while the dialog is open, the UI Action script will run again and a second dialog will be displayed on top of the first dialog. An alternative is to tell the Finder to present the dialog, because you can normally count on the Finder to be available and running. In some cases, your script can activate the Finder first so the user can see the dialog immediately. In other cases, it is better to leave the Finder in the background; when the dialog is presented, the Finder's icon will start bouncing in the dock to signal that the Finder needs attention.
Circular UI Action Scripts and Side Effects
You must be careful to avoid putting statements in a UI Action script that will trigger the UI Action script again, because UI Actions will go into an infinite loop. For example, a script that is triggered by the "AXApplicationActivated" notification should not tell the target application to activate itself. When it activates the target application, the script will run again and activate the target application, and this cycle will repeat endlessly. You can work around this issue by telling the UI Actions utility to temporarily disable and re-enable the UI Action script. See the "Show Manual on Activate" script in the Script Debugger subfolder of the UI Action Scripts folder for an example.
Another example of an infinite loop is a UI Action script that tells a target application to display a dialog when the UI Action script responds to the AXWindowCreated notification. When the application opens the dialog, it will issue another AXWindowCreated notification, triggering the UI Action script again, and this will repeat over and over again. A useful technique in this situation is to save the UI Action script as an application (or applet) and tell the UI Action script itself to display the dialog.
You will undoubtedly discover other situations where UI Action scripts have unintended side effects. The best preventative is to think through the logic and effect of the UI Action script and the notification that triggers it. Real-world UI Action scripts often require experimentation to achieve the desired result. The scripts in the UI Action Scripts folder are not only useful, but they illustrate advanced techniques for working around application-specific issues. Read the Read Me - UI Action Scripts document in the UI Action Scripts folder for more information.
Our UI Browser product can be a very helpful tool when writing and debugging UI Action scripts. UI Browser's Notifications drawer allows you to register notifications and observe them when they are triggered, without writing scripts. Using UI Browser in this manner can show you exactly how specific notifications behave in specific applications and to confirm that they work, to help you select the best notification to use in your UI Action scripts.
This page was first published by PFiddlesoft on May 25, 2010. Last updated October 25, 2014.
Copyright © 2003-2010 Bill Cheeseman. Used by permission. All Rights Reserved.
PFiddlesoft, PFiddle Software, pfiddle, pfiddles, the PFiddlesoft logo, Wheel of Access, and Applidude are trademarks of PreForm Assistive Technologies, LLC.