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.
The Player Menu
Player includes a Frontier suite (PlayerExtras) with a custom menu to help you compose scripts. The menu gives access to on-line help, example scripts, lists of available verbs, tools to extract information about an application, and submenus containing nearly all verbs and constants to automatically insert into your script.
From Frontier's Suites menu, select PreFab Player .
This section describes Player's "long" menu. Frontier 4.1 and later include a much-improved menubar, but with the unfortunate side effect of requiring us to default to Player's "short" menu (a subset of the commands described below). Please see the note at the end of this section if you want to switch to the "long" menu.
Help
Key sections of this manual are referenced here. This submenu also takes you directly to the examples table, and the oneLiners outline. Please review the example scripts; they are an important part of the documentation.
Verb Lists
To help you learn what is available and find exactly what you need, Player's verbs are listed and cross-referenced 4 different ways: by Keyword (where a single verb can appear under multiple keywords), by Category (including a one-line description), Alphabetical (like Frontier's verb list), and Verb Summary (which includes parameters and description).
App Info
Player has various tools for extracting information about an application that you want to control. This submenu provides a simple front-end for PlayerExtras verbs that outline menus and dialog items, and allows you to disable Player's balloon help. For details, select the About item.
The Constant Menus
These submenus list nearly all of Player's constants (pre-defined values) by category: Modifiers, Keys, Attributes and Misc. Each category includes an overview (About ), and possibly a separate item to see a complete list. When you are writing a script, just select any constant from the menu; Player will insert it into the frontmost script or outline window.
The Verb Menus
For convenience, Player's verbs have been organized by category. Each category includes an overview (About ), and may contain additional help text items. Selecting a verb will insert it with the correct parameters into the frontmost script or outline window. The first parameter will be highlighted so that you can directly type the value appropriate for your script. To see the DocServer entry instead of inserting the verb, hold down the control key while selecting the verb from the menu.
Notes
- Player includes many redundant verbs and constants to suit various preferences. In most cases, only the "standard" form is available from the menu.
- In Frontier, holding down the option key while selecting a menu will bring up the menubar editor with the cursor positioned on that item. We don't mind if you edit the menus -- but if you contact us with a related tech support question, please tell us that you've done so!
To switch to Player's long menus (containing all the items described above), you first have to delete some of the menus and submenus from your existing Frontier menubar. Then, from the Player menu select "Long Menu". Save your root file, then close it and reopen it. From now on, selecting Player will bring up the long menu -- unless you have exceeded the Macintosh limit (described below). Note that menus from other suites and the "modal" menus associated with different types of Frontier windows (tables, scripts, outlines, text) will reduce the amount available to Player if they have appeared after you opened the root file.
If the long menu doesn't appear and you want to switch back to short menus, run PlayerExtras.swapMenus().
What's the problem anyway? The Macintosh limits the total number of menus and/or submenus that can be in memory. Frontier 4.1 includes a new menubar that has many more submenus. That, combined with the submenus in the Player menubar, exceeds the limit. Because the modal menus and other suite menus play a role, it will probably take some trial and error before you determine how many submenus you need to delete from the Frontier menubar or Player's long menu for them to work together.
If you are close to the limit, you may find that when you select a new suite or switch to a Frontier window that normally has an associated modal menu, the menu doesn't appear. The solution: save, close and reopen your root file -- that purges all the temporary suite & modal menus. We have discussed this issue with UserLand, but at present there are many higher-priority features on their list. One final point: the Player menu does not take up any memory until you specifically select it.
DocServer
The DocServer applet is an invaluable reference tool. Each of Player's verbs has a DocServer page -- though these have not been updated for Player 1.5. Complete documentation is in Chapter 5.
Tip: In Frontier, control-double-clicking on a verb will look it up in DocServer, and option-control-double-click
will add the parameters without switching to DocServer.
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.From the Player menu, select Examples. In the table, select + SimpleText Examples and click Zoom to open the table. (If you sort the table by name, the "+" brings this subtable near the top.) Select Driving SimpleText and click Zoom to open the script window. 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.
with Player
typeText("Magical control via PreFab Player." + cr + cr)
typeText("Now for some dialogs...")
chooseMenu("File", "Page Setup")
choosePopup("Page Size", "A4 Letter")
clickButton("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 UserTalk, you have the full power of the language at every
step.
theFileName = "Ain't it great!"
while file.exists(targetFolder + theFileName)
theFileName = theFileName + "!"
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 table. 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 disableUserInput() 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.
To create the appropriate verb for the item shown in the balloon, click the mouse. If Frontier is running, Player will add the verb to the frontmost script, outline or Quick Script window, and click softly for confirmation. If the frontmost window is a different type (e.g. table or menubar), Player will open and log to the scratchpad.PlayerBalloonLog outline, creating it if necessary.
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, run PlayerExtras.setBalloonHelp(false). To enable again, run PlayerExtras.setBalloonHelp(true). If you need to change the hotkey, see Appendix 3, Advanced Topics.
Notes
- For dialog items that do not have names (e.g. icons), Player will create the generic clickItem verb. If the unnamed item is actually a pop-up menu, the script writer must manually correct the verb.- If Player doesn't see either a name or an ID#, it will create the generic clickMouse verb. If the "non-item" is a pop-up menu, the script writer must manually correct the verb. If it is supposed to be a button or radio, the script can be made more "self-documenting" by calling clickButton or selectRadio To further improve readability, the XY location could be defined in a local variable using a sensible name.
- 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 setCompleteMatch 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.
PasswordBox = 10 « got the ID via Balloon help
« later in the script:
clickItem(PasswordBox) « set the focus
typeText("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