PreFab logo
Overview Details Screenshots Comparison Store Press Releases Support About

 

Known Issues in GUI Scripting

AppleScript scripts generated using UI Browser's AppleScript menu sometimes fail to work. As far as we know, UI Browser generates valid GUI Scripting statements using correct syntax as defined by Apple. However, some applications do not fully or correctly implement Apple's Accessibility technology, on which GUI Scripting depends, and valid scripts targeted to them therefore don't work. In addition, we have attempted to keep UI Browser on the cutting edge of new Accessibility features implemented by Apple, but some applications have not caught up and thus don't implement some of GUI Scripting's newest features. Finally, even Apple's technology sometimes needs a little time before it works correctly in all cases. For example, in Mac OS X 10.3 Panther, the statement 'get attribute "AXParent" of scroll area 1 of window 1' returned no result, when it should have returned the UI element object representing window 1. Mac OS X 10.4 Tiger resolved this and all similar UI element navigation issues.

Tech Support notes

Don't forget to read the manual! There's a wealth of information available from UI Browser's Help menu.

PreFab UI Browser and Apple's GUI Scripting both depend on Apple's Accessibility technology to access an application's user interface. Accessibility has greatly matured in Mac OS X 10.3 Panther and Mac OS X 10.4 Tiger, but there are still some gaps and problems. For example, custom user interface elements require that developers update their products to support accessibility.

A number of well-established Mac OS X applications were originally written using older toolbox code for buttons, menus and other UI elements. As a result, they can be unresponsive to UI Browser and GUI Scripting. As time goes by, these applications are likely to be updated to incorporate more modern Carbon and Cocoa UI element code, which incorporates full Accessibility support, or to add custom Accessibility support of their own. If you encounter an application that does not appear to work well with UI Browser or the AppleScript scripts that it generates, this may be the reason.

If you have particular needs, take advantage of UI Browser's free 30-day trial period to verify that UI Browser and GUI Scripting will work with your target applications.



GUI Scripting tips

Here are some general tips on GUI Scripting, not necessarily related to UI Browser.


Where can I find example scripts for GUI Scripting?

UI Browser now comes with a collection of advanced example scripts that showcase new GUI Scripting features introduced in Mac OS X 10.4 Tiger. These include, for example, scripts showing how to script the commands in Dock items and in menu extras (menu extras are the buttons at the right end of the menu bar). These UI Browser example scripts are in the UI Element Scripts (PreFab) folder on the UI Browser installation disk image.

In addition, Apple provides example GUI Scripting scripts on Mac OS X, both in the UI Element Scripts subfolder of the Scripts folder in your local Library folder and link_outon the Web.


Will my GUI Scripts work in Mac OS X 10.2 "Jaguar" or older?

No, unless the computer includes some special beta supporting software that Apple made available for testing under Jaguar.

The scripts generated by UI Browser require Apple's GUI Scripting technology for AppleScript. Starting with Mac OS X 10.3 Panther, the required supporting software is installed automatically, by default, on every Macintosh computer. Apple successfully concluded the GUI Scripting public beta test for Jaguar, and the beta version of the underlying GUI Scripting software for Jaguar is no longer available.

If you have the Jaguar beta software and want to write scripts for it, you need to be aware that the AppleScript dictionary for GUI Scripting, in the System Events application, was somewhat different then. For example, the beta dictionary defined 'check box' with a space for Jaguar, but in the final version for Panther it defines 'checkbox' without a space. Since the Jaguar version was beta software and it is no longer officially available from Apple, UI Browser 1.4 generates scripts for a 'checkbox' using the Panther terminology. If you are still using Jaguar with Apple's beta GUI Scripting software, edit generated 'checkbox' scripts to add a space by hand. Bear in mind that such a script may not work when it is run under Panther.

Another example is the 'keystroke' command when it is used with modifier keys. The correct form for Jaguar is 'keystroke "n" with {command down}'; for Panther and newer, this is changed to 'keystroke "n" using {command down}'.


My script seems to get ahead of the UI. Any suggestions?

Try the "delay" command. For examples, see Apple's link_outsample scripts. Under Mac OS X 10.3 Panther and newer, however, GUI Scripting is so much faster that you probably won't need to do this very often.


How can I use GUI Scripting to save a file to a specific folder?

In theory, you can navigate the "Save As" dialog using GUI Scripting commands to mimic exactly how you would navigate by hand -- i.e. issue commands to click on folders, etc. However, even in the most recent release of Mac OS X some of the required steps don't work with GUI Scripting. A good solution is to buy link_outDefault Folder X. (No, we don't get a commission.)

Bring your application to the front, then run something like:

   tell application "Default Folder X" to SwitchToFolder alias "MacOSX:Users:me:whatever:"

Even independent of scripting, Default Folder is a great utility for making your interaction with file dialogs much more efficient.


How do I script an Application's palettes?

Scripts that read or manipulate UI elements in a target application's palette require special design, because a palette window automatically becomes invisible when another application is activated. If you switch to Script Editor to run a script, the target application's preferences window becomes invisible and thus inaccessible to your script. Your script should therefore be written so that it activates the target application and opens the palette before attempting to read or manipulate its UI elements. In this way, the target application remains active and visible, and UI elements in the dialog can be scripted.

The same design principle applies to sheets, utility windows, inspectors, and some other kinds of windows that disappear when the application is not frontmost on the screen.

UI Browser is particularly helpful in these situations, because its hot keys allow you to select UI elements in a window while the target application is in front, and its new ability to navigate UI elements that have been "destroyed" lets you bring UI Browser to the front and generate scripts for them even after the preferences window has disappared. In addition, almost every control in UI Browser can be used while you hold the Command key down to keep UI Browser in the background so that a palette will remain visible.


How do I script the menu bar using GUI Scripting?

Apple changed the way the menu hierarchy is exposed in Mac OS X 10.3 Panther. Furthermore, the terminology in Panther differs from that in Jaguar, and, to confuse matters still further, in Panther the terminology differs as between the Accessibility API and GUI Scripting.

In Jaguar, the children of 'menu bar 1' were 'menu' elements, and each 'menu' element was conceptually a submenu having one or more 'menu item' elements as children. Each 'menu item' element represents a command on which you can click. Some 'menu item' elements have a single child element of the same name that is a 'menu' element, that is to say, an hierarchical submenu containing one or more 'menu item' elements. The 'menu item'/'menu' pairings continue down the hierarchy if there are submenus.

In Panther, a new level in the hierarchy has been introduced immediately below the menu bar, called 'menu title' in the Accessibility API and 'menu bar item' in GUI Scripting. Apple did this to make the hierarchy that is exposed in the Accessibility API and in GUI Scripting correspond exactly to the underlying reality in the system. Thus, in Panther, the children of 'menu bar 1' are now 'menu title' elements (addressed as 'menu bar item' elements in GUI Scripting). Conceptually, the 'menu bar' is actually a 'menu' containing one or more menu items, each of which is known as a 'menu title' or 'menu bar item' element. Each 'menu title' ('menu bar item') element has a single 'menu' element child of the same name, which is the submenu holding 'menu item' elements at the next level down the hierarchy. If there are submenus below that, they follow the same 'menu item'/'menu' pairings as in Jaguar.


How do I create scripts to send keyboard shortcuts?

Choose a target application in UI Browser, select its application element (or any other element) in UI Browser's main browser view, open the Keystrokes drawer, type the desired key (taking care to use a lower-case character instead of an upper-case character, in the case of alphabetic characters), and check the Command key checkbox. Then open the AppleScript menu and scroll down to see the 'Send Defined Keystroke' command highlighted. This will open the Edit AppleScript window with the desired GUI Scripting statement selected and ready to copy or drag to a script editor. If you select appropriate UI Browser preferences, the generated script will already be on the clipboard, or it will be sent directly to your chosen script editor and inserted at the insertion point.

There is also a 'Send Defined Key Code' command in the AppleScript menu, which enables you to send function keys as well as character keys. The appropriate key code is displayed in the Keystrokes drawer when you press the desired function key (or any other key).

Keystroke commands are always sent to the active UI element in the target application. In the case of keyboard shortcuts, they are always sent to the target application itself, if it recognizes that Command-key equivalent.

The 'keystroke' command should be sent with a 'command down' parameter in a list created using AppleScript's curly braces syntax, like this: 'keystroke "n" using {command down}'. You can send the 'keystroke' command with multiple modifier keys separated by commas in the list, for keyboard shortcuts that take multiple modifier keys, like this: 'keystroke "n" using {shift down, command down}'. The character should always be lower case; if you use an upper case letter, GUI Scripting will think that the Shift key is down and the application will not respond as you intend.

In GUI Scripting, you can use the 'keystroke' command to send a string of characters, as long as they are all lowercase or all uppercase. UI Browser's Keystroke drawer only lets you send one character at a time, because this is the way the Accessibility API works.


Why are the names of some UI elements different in a script than they are in UI Browser?

The names of some UI elements as they appear in UI Browser's main browser view differ from their AppleScript names as they appear in scripts generated using UI Browser's AppleScript menu. This is because the AppleScript terminology used in Apple's System Events dictionary for GUI Scripting is not identical to the terminology used by the Accessibility API. In UI Browser, we use the Accessibility names except when generating AppleScript statements, because UI Browser is a developer tool for the Accessibility API as well as a tool for GUI Scripting.


Why do some applications require a process name that is different from the application name?

In GUI Scripting, you usually first 'activate' the target application, then use nested 'tell' blocks to tell the System Events application to send commands to the target application's process. The 'activate' application is sent to the application itself, as in 'activate application "Adobe Photoshop CS2.app"'. In the inner 'tell' block of the nested 'tell' blocks, you tell System Events to tell the application's process to perform a command. In the case of a few applications, the name of the process is not the same as the name of application; for example, 'tell process "Photoshop"'.

UI Browser knows which applications have different application and process names. For this reason, the safest course is to use UI Browser's AppleScript menu to generate 'tell' blocks for GUI Scripting. UI Browser always gets the names right.


Updated on December 22, 2006. Send questions or comments to emailsupport@prefabsoftware.com.

link_out identifies links that will take you out of the PreFab site.