Chapter 6, Constants

Misc. Constants, Modifier Keys, Special Keys, Attributes

In addition to verbs, Player defines many "nouns" or constants. (A constant is sort of like a variable that doesn't vary, i.e. whose value remains fixed rather than changing or being changed by a script.)

Player's constants can be divided up into 4 categories:
- Misc. Constants
- Modifier Keys
- Special Keys
- Properties

Each category is described on a separate page for easy reference.

---

Misc. Constants

As an alternative to the screenCoordinates verb, Player provides a screenCoords constant (abbreviated to prevent a conflict).

To make it easy to set the mouse or typing delay back to the default, Player includes defaultMouseDelay and defaultTypingDelay.

For the new disableUserInput verb, Player 1.5 includes mouseOnly and keyboardOnly.

Note: the "checked" constant is obsolete in Player 1.1 and later since all constants have been moved to the top-level of the table where there's already a "checked" attribute with a different value.

Examples

with Player   « ", constants" was required in 1.0x but is optional in 1.1 and later
   clickMouse( {4, 27, screenCoords} )   « abbreviated to prevent conflict with verb

with Player
   clickMouse( {4, 27, 1} )     « screenCoords' value is 1
   clickMouse( Player.screenCoordinates( {4, 27} ) )     « the verb form


with Player   « ", options" was required in 1.0x but is optional in 1.1 and later
   setMouseDelay(defaultMouseDelay)     « reset
   setTypingDelay(defaultTypingDelay)     « reset


with Player   « new in 1.5
   disableUserInput(keyboardOnly)     « allow mouse activity
   ...
   enableUserInput()     « back to normal

Notes

• Constants are not case sensitive (and not affected by the setCaseSensitive( ) verb).

---

Modifier Keys

"Modifier keys are those that alter the way other keystrokes are interpreted. These keys sometimes affect the way the mouse-button actions are interpreted as well. They are the Shift, Caps Lock, Option, Command, and Control keys." Macintosh Human Interface Guidelines , p. 278

One or more modifier keys can be held down while performing some other action on the Macintosh. Player adds an optional holding parameter to most verbs.

Examples

with Player   « ", modifiers" was required in 1.0x but is optional in 1.1
   typeCombination(command, "a")     « often for Select All
   typeCombination(command + option, "3")     « screen shot
   typeCombination(cmd + opt, "3")     « abbreviations are allowed
   chooseMenu("File", "Print", holding: option)     « send a FAX
   clickMouse( {1,1}, holding: shift )     « select to corner of window

with Player
   typeCombination(option, rightArrow)     « move to end of word
   typeCombination(cmd + opt, rightArrow + downArrow)     « see note

Notes

• Supported abbreviations are: cmd, shft, opt, ctrl, caps.
• Use the "+" operator to "hold down" multiple keys simultaneously. (In contrast, when "+" is applied to standard keys, it means to type them one after another.)
• Modifiers are not case sensitive (and not affected by the setCaseSensitive( ) verb).
• Optional and labelled parameters (like holding) are not common in UserTalk, and can be confusing. Since modifier keys can apply to most user interface actions on the Macintosh, we thought an optional parameter was logical, and much simpler than nearly doubling the number of Player verbs.

---

Special Keys

Many useful keys on the Macintosh keyboard have no real text equivalent. Player lets you specify these keys by name, including alternate names to suit a variety of individual preferences.

List of Supported Keys

standard

lspaceKey, tabKey, returnKey, enterKey, escapeKey, deleteKey

arrows

leftArrow, rightArrow, upArrow, downArrow

misc.

help, forwardDelete, home, end, pageUpKey, pageDownKey

function

F1 ... F15

keypad

keypadPlus, keypadMinus, keypadTimes, keypadDivide, keypadEquals, keypadDecimal, keypad0 ... keypad9

Examples

with Player   « ", keys" was required in 1.0x but is optional in 1.1
   typeKeys(deleteKey)
   typeKeys(F1 + pageUpKey + downArrow + downArrow)     « many keys
   typeKeys("One" + downArrow + "Two")     « mix keys & text
   typeText("One" + downArrow + "Two")     « ... using either verb

with Player
   typeCombination(command, rightArrow)
   typeCombination(cmd + opt, rightArrow + downArrow)     « see note

Notes

• The names of some keys have "key" as a suffix to avoid conflict (or just confusion) with built-in Frontier constants (cr, tab, pageUp, pageDown). For consistency, all the keys in the "standard" category end with "key" even though only some conflict with Frontier.
• The numbers on the keypad are actually different keystrokes than the numbers across the top of a keyboard. Nevertheless, most applications interpret them the same way.
• To type special characters that are not on the keyboard, use typeText( ) and Frontier's char verb, e.g. typeText(char(28)) will enter the "Field Separator" character. (However, char(31) is reserved by Player and cannot be typed.)
• Key names are not case sensitive (and not affected by setCaseSensitive).
• Use the "+" operator to type multiple keys one after another, or type both keys and text. (In contrast, when "+" is applied to modifiers, it means to "hold them down" simultaneously.) Multiple keys (and text) can also be specified as a list:

     typeKeys( {leftArrow, downArrow} )
     typeKeys( {F1, "any text"} )
  

---

Attributes

Player's query verbs provide useful information about an object. Many attributes are common to all objects, others are specific to certain kinds. Because these attributes pertain to objects in other applications, they are all "read-only" and their values cannot be changed.

List of Attributes

Dialog and window items share 5 basic properties: kind, location, height, width, bounds. Each kind has the following additional properties.

Button

name, visible, enabled

Radio Button

name, visible, enabled, value

Checkbox

name, visible, enabled, value

Pop-up Menu

name, visible, enabled

Scroll Bar

name, visible, enabled, value, minimum, maximum

Custom Control

name, visible, enabled, value, minimum, maximum

Text Entry Box

item text

Static Text

item text

Icon

[just the 5 basic]

Picture

[just the 5 basic]

User Item

[just the 5 basic]

Menus have fewer properties:

Menu

name, kind, enabled, quantity

Submenu

name, kind, enabled, quantity

Menu Item

name, kind, enabled, checked, mark

Independent of kind, windows or dialogs have the following properties:

any

name, kind, active, visible, location, height, width, bounds

Examples

with Player   « ", attributes" was required in 1.0x but is optional in 1.1
   getItemAttribute(14, kind)
   getMenuAttribute(checked, "Font", "Geneva")
   getWindowAttribute("Untitled", height)

Notes

• A "User Item" in a dialog or window could be almost anything, from a pop-up to a scrollable list to a simple graphic line.
• A "Static Text" dialog item is often used to identify for the user an item such as a text entry box that does not actually have an internal name.
• The window kind is a number that represents the window type according to the Macintosh Toolbox, as documented in Inside Macintosh. Unfortunately, there is enough variation in the way that windows are implemented that the number is not very useful to script writers. Some numbers you might encounter: 2 for a standard dialog or alert, 8 for a typical custom dialog, and negative numbers for a Desk Accessory.
• Attribute names are not case sensitive (and not affected by setCaseSensitive).

Attribute Descriptions

active: whether or not a window is active (frontmost)
bounds: rectangle coordinates (top, left, bottom, right)
checked: whether or not a menu item is checked
enabled: whether or not an item is enabled
height: height in pixels
item text: text contents
kind: the kind of item
location: XY coordinates of upper left corner
mark: the kind of mark on a menu item
maximum: maximum value (for a control)
minimum: minimum value (for a control)
name: item name
quantity: number of items
value: item value
visible: whether or not item is visible
width: width in pixels

Chapter 5, Verbs Appendix 1, Questions & Answers

Copyright 1993-99, PreFab Software, Inc. All Rights Reserved.

This site built and maintained using Stage Three, a set of custom Frontier scripts.