PlayerChapter 4, Composing Scripts
In general, Player automates a task by mimicking the exact sequence that a user would
perform. To compose a script, just determine this step-by-step procedure, then translate
each step into the equivalent Player verb.
Dictionary
For an overview of Player's verbs, select Open Dictionary from Script Editor's File menu. Navigate to the Extensions folder and open PreFab Player. You can select one, many or all verbs, to view, print, save or even copy to the clipboard.Example Scripts
When writing any sort of script, the best approach is often to start with an example that does something similar and modify it to handle your specific task. This technique is not just for beginners; some of the best professional programmers do the same.In the Player for AppleScript folder, open the Example Scripts folder and then the + SimpleText Examples folder. (If you select by Name from the Finder's View menu, the "+" in the folder name causes it to sort as the first item.) Double-click on Driving SimpleText to open it into your script editor. Click AppleScript's Check Syntax button to make sure everything is ok. Then, click Run and sit back to watch. Cool!
Here is the essence of the first part of the script. Each verb corresponds to an
action that a user would perform: type, choose from a menu, select a radio button, click Cancel.
tell application "PreFab Player™"
type "Magical control via PreFab Player." & return & return
type "Now for some dialogs..."
do menu menu item "Page Setup" of menu "File"
do menu popup item "A4 Letter" of popup "Page Size"
click button "Cancel" -- just an example; let's cancel
Now, run the script again. What is it going to do about the filename? Because Player
adds verbs directly to AppleScript, you have the full power of the language at every
step.
set theFileName to "Ain't it great!"
tell application "Finder"
repeat while exists file (targetFolder & theFileName)
set theFileName to theFileName & "!"
end repeat
end tell
Here, the script creates a "base" filename. As long as (while) a file by that name exists in the target folder, the script will append a character to the end of the filename and check again.
There are many more example scripts in the folder. Even if you don't have all of the applications that they "play", you might want to look through them to get some ideas. If you modify any of the scripts to work with other applications, or write some simple, cool examples of your own, please send them to us so we can share them with others.
Caution
While Player is driving an application, the mouse and keyboard remain active. A real user can cause problems by clicking in the wrong window, holding the mouse button down, or switching to another application. To prevent interference, use the new "disable user input" verb.
Tip: To abort a script that is making repeated calls to Player, press and hold command-period.
Player checks before executing each command, it will not abort in the middle.
Obstacles
The genius of the Macintosh user interface is its consistency. Learn the difference between a checkbox and radio button in one application, and use that knowledge in every other software package. However, some applications do not follow all of Apple's human interface guidelines. Or, they implement the behavior that a user expects, but do it in a non-standard way. These problems present a number of obstacles that you may encounter when trying to translate user actions into Player scripts.No name
Items such as iconic buttons and text entry boxes almost never have a name, e.g. the portrait & landscape icons in the Page Setup dialog. Text entry boxes may appear to have a name, but behind the scenes, the label is actually a separate item. Finally, some item types that usually have an associated name don't in a particular instance. The Stationery radio button in SimpleText's Save dialog is a good example.Wrong name
Some dialog or window items have an internal name (seen by Player) that is different than the displayed name. The Options sub-dialog to Excel's Save dialog has numerous examples.Wrong item type
Some dialog items have the behavior of one type of item, but implement it with another type of object -- or with the generic "user item" type. This situation is quite common with pop-up menus, which were not part of the original Macintosh user interface.Invisible
Finally, some dialogs (and most palettes) are implemented such that none of the items are visible to Player. See Appendix 1, Questions & Answers for further details.Balloon Help
To work around these obstacles, Player includes universal balloon help that displays pertinent information about an individual dialog or window item, including XY coordinates for "invisible" items.Switch to the target application and call up the dialog of interest. To enable Player's balloons, type control-option-? (i.e. hold down the control and option keys and hit the key labelled with both ? and /).
Tip: When typing control-option-?, do not also hold down the shift key. Also, make sure to use the control key (labelled control) not the command key (labelled with the Open Apple and the "propeller").
For international users: the actual key combination is control-option-/. On the U.S. keyboard, the "/" (forward slash) and the "?" are on the same key, so it's easy to remember ctrl-opt-?. On other keyboards, you will have to find the "/" key -- it may require you to also press shift. If you tell us where it is on your keyboard, we'll add it to the "International Notes" document on our web site to save others the trouble.
Tip: Player's balloon help is not affected by the System 7 balloon help menu. "Show" is not required, and "Hide" will not hinder the balloons. (However, it will probably be less confusing if they are hidden.)
When the cursor is positioned over a specific item, Player's help balloon will show the item name (if any), type, unique ID number and XY location. To get information for a different item, simply move the mouse. When you pause briefly at a new location, Player will display a new balloon.
If no dialog item is seen under the cursor, only the XY coordinates (relative to the upper left corner of the dialog or window) are displayed. Moving more than about a dozen pixels will display a new balloon at that location.
Type control-option-? again to turn off Player's balloon help.
To temporarily disable Player's balloon help and free up the hotkey for use elsewhere, double-click the "Disable Player Balloons" script, or execute the corresponding verb. To enable again, run the "Enable Player Balloons" script. If you need to change the hotkey, see Appendix 3, Advanced Topics.
Notes
- All XY coordinates are relative to the frontmost dialog or window.Partial Name Matching
When looking for an object by name, Player matches only the number of characters that you provide -- unless you specify otherwise. For example, if you ask for the menu item "Open", Player will look for any menu item whose name begins with those four characters, rather than insisting on an item whose name is exactly those characters -- and nothing more.There are many benefits to accepting a partial match. It is usually easier to type a name without trailing punctuation. It can also be more reliable: e.g. for menu items that incorrectly end with three period characters instead of a single ellipsis (option-; on the U.S. keyboard). In addition, some names (especially of checkboxes) can be so long that it is just easier not to have to type the entire, exact string.
Partial name matching does carry the risk that Player will find a match where none was intended. At present, Player targets the first match that it finds, without checking for additional matches. To force a complete match, use the "set complete match" verb.
Unique ID
In a standard Macintosh dialog, every item has a unique identification (ID) number. (Programmers and others familiar with Macintosh resources will recognize it as the DITL number. Player 1.1 and later can also see MacApp controls despite that they are not created using resources.) The numbering of items is essentially arbitrary; there is no way to determine the number just by looking, or by counting items of a specific type. Instead, use Player's balloon help to determine the ID.
To make your scripts more readable, consider hiding ID numbers in variables with meaningful
names, e.g.
set PasswordBox to 10 -- got the ID via Balloon help
-- later in the script:
click dialog item PasswordBox -- set the focus
type "anonymous"
XY Location
Even if Player cannot see the dialog items and is dependent on mouse locations, scripts will still be quite robust: Player uses the location relative to the frontmost window or dialog. Moving to a larger screen or having the dialog appear in a different position should have no effect.To make your scripts more readable, consider hiding the XY location in variables with meaningful names, as shown above for unique ID.
Chapter 5, Verbs