SUPPLEMENTAL INFORMATION FOR THE MACRO PROGRAMMING LANGUAGE OF JAWS FOR WINDOWS June 23, 1995 This information supplements information in the JAWS Technical Reference manual. It should be read in conjunction with Chapter 2 "JAWS MACRO EDITOR" (disk file "T2M- EDIT.MAN"), and Chapter 3 "JAWS MACRO FUNCTIONS" (disk file "T3M-FUNC.MAN"). 1. WINDOW HANDLES Each application window that is displayed on the desktop (the visible screen display) is made up of several "windows". These "child windows" are used to display many types of information. Examples of child windows within an application window are: document window, status message window, cursor position window, date window, tool bar window, etc. In a database/contact manager program such as ACT, data fields (name, phone, address, etc.,) are individual child windows. Each of these child windows has a "type", a "class", and a "handle". The "type" and the "class" are names that are made up of letters and numbers that usually correspond to a series of words. The "handle" is an integer. Handles identify specific windows and are used by the software to refer to a specific window. You will see that the JAWS macro functions use the window handle extensively. Some macro functions require the window handle in order to return information about that window, some functions provide a handle just for that purpose. If you want to know the class of the current window, you begin by determining the handle of the window, then you request the class that corresponds to the handle. The JAWS macro functions and descriptions, and the examples we provide should clarify this relationship more fully. If you want to determine the name of the class for the current window, by using the keyboard, then you can use the {INSERT+F1} macro. If the class is a commonly used name, then JAWS may tell you that you are using a "list box" and may give you instructions for using the box. In other situations, the class is spoken. 2. KEYS TO USE FOR MACROS Almost any key on your keyboard or combination of keys can be used as a macro key. The letter keys, number keys, punctuation keys, cursor keys, and function keys can be used as macro keys. You also can use these same keys in combination with the CONTROL, SHIFT, ALT, and INSERT to create multiple macros for the same keys of the keyboard. Additionally, you can combine SHIFT, ALT, CONTROL, and INSERT with one another. For example, you can use {ALT+INSERT+RIGHT ARROW} as a macro key. You could also use {ALT+CONTROL+INSERT+RIGHT ARROW}, or {SHIFT+ALT+CONTROL+INSERT+RIGHT ARROW} or {ALT+CONTROL+INSERT+SHIFT+RIGHT ARROW}. The possible combinations are too numerous to list here. If you want to use a key or key combination, try it and test it to see if it works. Please avoid {ALT+CONTROL+DELETE}. The order in which the ALT, CONTROL, SHIFT, or INSERT modifiers appear should not be important, though there may be some isolated situations when it may make a difference. You cannot create a macro key by only using CONTROL, ALT, and SHIFT. For example, {ALT+CONTROL}. You can use CONTROL, ALT, and SHIFT, with INSERT, however, the INSERT must be the last key in the macro key name. For example, {ALT+INSERT}, and {SHIFT+CONTROL+INSERT} are acceptable. The modifier keys must always precede the key being modified, in this case, the INSERT. These rules may change slightly as we continue to enhance and improve our macro language, so if in doubt, try it. How do you represent a name like "[" or "."? Recent versions of the JAWS macro editor/compiler will accept almost any variation of the key name. For example, you can use the symbol itself, like "[" or you can spell it out, like "leftbracket", or "left bracket", or "left-bracket", or "left_bracket", etc. The right-arrow key can be "RightArrow", "Right-Arrow", "Right Arrow", etc. We have tried to cover all the options, but naturally that is not possible. If you try a name and the compiler gives you an error, change it to something else and try again. It must be spelled correctly, and must be a name we recognize. A list of macro key names is presented in Chapter 3 of the Technical Reference. If you want a JAWS macro to "press" a key on the keyboard, i.e. send it along to the application, then include it in braces. For example, the {SHIFT+DOWN ARROW} macro says "select line" then it performs the SHIFT+DOWN ARROW function of Windows. The key or keys being performed by the macro do not have to be the same as the key that is the macro. For example: MacroBegin {Shift+Down Arrow} If(GetVerbosity() == 0) Then SayString ("Select line") EndIf {Shift+Down Arrow} MacroEnd 3. EVENT MACROS In addition to using keyboard commands to trigger macros, JAWS provides several "event macros". An Event is an activity that JAWS monitors so that when the event occurs, the macro is automatically triggered. Event macros have names such as {FOCUS CHANGE}, {HIGHLIGHTEDTEXT}, and {TEXT}. For example, the {HIGHLIGHTEDTEXT} macro is triggered when highlighted text is written to the active application window. The event macro then uses If- Then-Else statements to analyze the situation and to produce an appropriate response. Detailed descriptions of event macros appear below. 3.1 {HighlightedText}(int hwnd,string buffer) This macro gets called or performed anytime highlighted text is written to the screen or desktop. Highlighted text is a different color than the normal text, the color is defined in the Color dialogue of the Control Panel. The macro name {HighLightedText} is followed by a list of parameters and their data types contained in parenthesis. The first parameter is the handle of the window in which the highlighted text appears or is being written to. Its data type is int (integer) and its name is "hwnd", simply an abbreviation for "handle of window". The second parameter is "buffer", its data type is "string", meaning it is a string variable, it contains the text being written to the window. The names of the parameters can change; you can call them whatever you want, but the data types are predefined. This macro knows which window the text is being written to, so it can decide to speak it or not. It can also make that decision based on other switches, like screen echo (see the example in the DEFAULT.JMS file). We could search the string for a certain word or phrase, using the StringContains macro function, and then decide to speak it or not. Currently text is passed to the synthesizer in 240 byte blocks, which is why there may be pauses in unusual places instead of after punctuation and paragraphs. This event macro only gets the highlighted text, other text is received by the Text event macro. 3.2 {Text}(int hwnd,string buffer) The Text event macro has the same parameters as the HighlightedText event macro, only it gets the text that is not highlighted. The window handle and the string buffer can be used to make decisions just like that described above. These two event macros get called in the proper order, so if a sentence is being written to the screen with a highlighted word in the middle of it, JAWS will say the first half of the sentence through the Text event, then the highlighted word through the HighlightedText event, then the rest of the sentence through the Text event. 3.3 {FocusChange}(int hwndCurrent,int hwndPrev) This macro gets called every time the focus changes from one window to another. This happens whenever you switch to an application window, group box, document window; open or close a dialogue box; tab or back-tab between dialog options; etc. Both parameters are of type "int", integers representing the handle of the windows. "HwndCurrent" is the handle of the window to which focus is being switched (the new window). "HwndPrev" is the handle of the window that focus is moving from. Conceivably hwndPrev could be "nothing", i.e. = 0. This could mean that a previous window did not have the focus, no window had the focus for a brief time , or focus was switched twice very quickly. When any of these conditions occur, then this macro is not called. 3.4 {ItemNotFound} (int hwndCurrent) This event macro is called whenever the OSM (Off Screen Model) cannot do what has been requested. It passes the handle of the active child window to the macro for processing, i.e. the window that the active cursor is in. This macro is triggered whenever: a. The JAWS cursor is pointing to blank space and any of the "say" functions are used. b. When you use a "previous" function such as PriorWord and there is no previous item, such as when the cursor is at the top of the window or at the left edge of the window. c. When a "next" function such as NextWord is requested and there is no next item. Currently, the DEFAULT.JMS file defines this macro to "beep" when triggered. It could be split in the future to provide more specific messages such as "bottom of window", "top of window", etc. 3.5 {AutoStart} This event macro gets called whenever a macro file is loaded, which happens whenever you switch to a new application. The Default macros in DEFAULT.JMB get loaded once, at boot time, so the AutoStart macro in this file only gets called once. Application macro files, such as PROGMAN.JMB, get loaded each time the application is started or receives the focus. The name of the macro file must match the executable application name, i.e. PROGMAN.JMS is used with PROGMAN.EXE. 3.6 {MenuActive} (int hwnd) Parameter: Handle of the window containing the menu. The name of this event macro may be changed to "MenuActivated" in the future. This macro gets called each time a menu is activated, such as when you press {ALT+F} to pull down the Files menu. The hard-coded default message for this function says "menu active" if the verbosity is set to beginner or intermediate. If this macro appears in the current application macro file or the default macro file then it will replace the hard-coded default function. 3.7 {MenuDestroyed} (int hwnd) Parameter: handle of window that the menu was in. This macro gets called each time a menu is destroyed. This is the opposite of MenuActivated. The hard-coded default function says "Leaving menus" when verbosity is set to beginner. 3.8 {IconWindowCreated} (int hwnd) Parameter: Handle of the window being minimized. This macro gets called whenever a window is minimized (reduced to an icon). It could test for the window name, then speak a message such as "Word for Windows being minimized". 3.9 {IconWindowDestroyed} (int hwnd) Parameter: Handle of window being destroyed. If a window has been minimized, and then you activate the task list to destroy or close the window or application, then this event macro is triggered. 3.10 {CursorChanged} Parameter: Int CursorID This event macro determines the type of cursor, i.e. hour glass, etc. It will be called each time the cursor changes shape, such as when it changes into an "hour glass" to indicate that the PC user is to wait until an activity has been completed. 3.11 New Event Macros We also plan to implement "MenuBarActive" and "MenuBarDestroyed" event macros, to indicate when the menu bar is active (getting the input) or not active. 4. THE INCLUDE STATEMENT If you put an "Include" statement in a macro file then it will add the macros from the specified file whenever the JMS file is compiled. Use of the include statement makes it possible to combine two or more files into one file, to reduce the size of individual macro source files, and to re-use standard sets of existing macros. As a default, the desktop and laptop macro files use the same include file, preventing duplication. For example, the DEFAULT.JMS macro file has the line: include "def_incl.jms" This file, "def_incl.jms" will be compiled at the same time that DEFAULT.JMS is compiled and the macros will be combined together in the DEFAULT.JMB file, which is loaded at start up. 5. Macro Functions Macro functions are listed in Chapter 3 of the JAWS Technical Reference, which can also be read from within the JAWS on-line help system. The most up to date list of macro functions is in the FUNCTION.JML file, located in the \JFW\SETTINGS\ENU subdirectory. PLEASE NOTE! Do not make changes in the FUNCTIONS.JML file. This file is used by the JAWS macro compiler, and if changes are made in this file, then the macro compiler may not be able to compile your new macro files. Macro functions are the building blocks that produce the finished macros. Please refer to existing macro files such as DEFAULT.JMS (default macro source file), DEF_INCL.JMS (default include file), WINWORD.JMS (Word for Windows), and ACTWIN2.JMS (Act for Windows) for examples of macro functions and how to use them.