Chapter 3 JAWS MACRO FUNCTIONS (Also contained in the disk file "T3M-FUNC.TXT".) CONTENTS OF CHAPTER 3 1. CHAPTER INTRODUCTION 23 2. LIST OF MACRO KEY NAMES 23 3. LIST OF EVENT MACRO NAMES 23 4. LIST OF MACRO OPERATORS 24 5. LIST OF MACRO USER FUNCTIONS 26 1. CHAPTER INTRODUCTION This chapter Lists the keys and functions that can be included in JAWS macros. Please read chapter 2 of this manual for a general description of JAWS macros and the JAWS macro editor. The JAWS macro source file "DEFAULT.JMS" should be consulted for examples whenever additional information about the functions discussed in this chapter is needed. 2. LIST OF MACRO KEY NAMES 3. LIST OF EVENT MACRO NAMES In addition to using keyboard commands to trigger macros, JAWS provides several "event macros". An Event macro is an activity that JAWS monitors so that when the event occurs, the macro is triggered. If you examine the "DEFAULT.JMS" file in your "\JFW\SETTINGS\ENU", subdirectory you will find several event macros. They have names such as {FOCUS CHANGE}, {HIGHLIGHTEDTEXT}, and {TEXT}. For example, the {HIGHLIGHTEDTEXT} macro is triggered when highlighted text appears in the active window. The macro uses If- Then-Else statements to analyze the situation and to produce an appropriate response. 4. LIST OF MACRO OPERATORS Function 1: - Description: subtraction operator Use:Math equations. Function 2: + Description: addition operator Use:Math equations. Function 3: * Description: multiplication operator Use:Math equations. Function 4: / Description: division operator Use:Math equations. Function 5: < Description: less than operator Use:"If" statements. Function 6: <= Description: less than or equal to Use:"If" statements. Function 7: == Description: is equal to Use:"If" statements. Function 8: >= Description: greater than or equal to Use:"If" statements. Function 9: > Description: greater than operator Use:"If" statements. Function 10: != Description: not equal to Use:"If" statements. Function 11: && Description: and operator Use:"If" statements. Function 12: || Description: or operator Use:"If" statements. Function 14: If Description: start of "if-Then-Else" statement Use:Start a conditional decision making process. Function 15: Else Description: optional part of If-Then-Else statement. Use:Precedes actions to be completed when the "If" condition is not met. Function 16: EndIf Description: termination of "If-Then-Else" statement Use:Required at the end of an If-Then-Else statement. Function 17: Not Description: reverses the "If" statement Use:Asks the question "If this is not true, then. . ." Function 18: While Description: start of While loop Function 19: EndWhile Description: end of While loop Function 20: For Description: start of For loop Function 21: Next Description: next Function 22: PushInt Description: Pushes an integer on the stack. Function 24: PushString Description: Pushes a pointer to a string on the stack. 5. LIST OF MACRO USER FUNCTIONS All of the following functions must be followed by a pair of parentheses "( )". If a parameter is to be provided for the function, then it is to be placed within the parentheses. Parameters enclosed in quotation marks are treated as text. Parentheses should always be used even if they are left empty. Please refer to "FUNCTIONS.JML" in \JFW\SETTINGS\ENU for the most current list of macro functions. Please refer to "DEFAULT.JMS" in the same subdirectory for examples of how to use these functions. Function 50: ToggleDebug Description: Toggles debug mode on or off. Use:Returns integer. Function 51: Run Description: Runs another program. Use:State ("program name"). Function 52: GetDate Description: Gets the system date Function 53 SayString Description: Sends string to synthesizer. Use:Provide ("string to speak") Function 54: Beep Description: Does a system beep. Function 55: MessageBox Description: Pops up a message on the desktop. Function 56: Flush Description: Flushes speech synthesizer -- stops speech. Function 57: JAWSCursor Description: Turns on the JAWS cursor. Function 58: PCCursor Description: Turns on the PC cursor. Function 59: SetVoice Description: Sets a voice parameter. Function 60: JAWSHome Description: JAWS cursor Home function Use:If the JAWS cursor is on, then it moves the JAWS cursor to the left side of the window, otherwise it does a Home function for the application. Function 61: JAWSEnd Description: JAWS cursor End function Use:If the JAWS cursor is on, then it moves the JAWS cursor to the right side of the window, otherwise it does an End function for the application. Function 62: JAWSPageUp Description: JAWS cursor Page Up function Use:If the JAWS cursor is on, then it moves the JAWS cursor to the top of the window, otherwise it does a Page UP function for the application. Function 63: JAWSPageDown Description: JAWS cursor Page DOWN Use:If the JAWS cursor is on, then it moves the JAWS cursor to the bottom of the window, otherwise it does a Page Down function for the application. Function 64: ReturnCursorRow Description: Gets the vertical position of the active cursor. Use: Returns integer. Function 65: ReturnCursorCol Description: Gets the horizontal position of the active cursor. Use:Returns integer. Function 66: SayUnit Description: Says the current unit of text. Function 67: SayCharacter Description: Says the current character. Function 68: SayWord Description: Says the current word. Function 69: SayChunk Description: Says the current chunk of text. Function 70: SayLine Description: Says the current line of text. Function 71: NextUnit Description: Moves the active cursor to the next unit of text. Function 72: NextCharacter Description: Moves the active cursor to the next character. Function 73: NextWord Description: Moves the active cursor to the next word. Function 74: NextChunk Description: Moves the active cursor to the next chunk of text. Function 75: NextLine Description: Moves the active cursor to the next line. Function 76: PriorUnit Description: Moves the active cursor to the prior unit of text. Function 77: PriorCharacter Description: Moves the active cursor to the prior character. Function 78: PriorWord Description: Moves the active cursor to the prior word. Function 79: PriorChunk Description: Moves the active cursor to the prior chunk of text. Function 80: PriorLine Description: Moves the active cursor to the prior line. Function 81 SayActiveCursor Description: Says the name of the active cursor, JAWS or PC. Function 82: SayCursorPos Description: Says the position of the cursor. Use:(integer representing cursor to use) Function 83: SayInteger Description: Says the number. Use:(integer to speak) Function 84: GetActiveCursor Description: Determines which cursor is currently active. Use:Returns integer. Function 85: RouteJawsToPc Description: Moves the JAWS cursor to the PC cursor. Function 86: RoutePcToJaws Description: Moves the PC cursor to the JAWS cursor when possible. Function 87: GetWindowTitle Description: Get the title of the window. Use:Returns string. Function 88: ToggleRestriction Description: Toggles JAWS cursor restriction on/off. Use:Returns integer which indicates status: 1=restriction on, 0=off. Function 89: SayAll Description: Reads the entire window. Function 90: GetAppTitle Description: Get the title of the current application program. Use:Returns string. Function 91: GetWindowClass Description: Get the class of the window. Use:(Integer handle of window to check), returns string. Function 92: JawsWindow Description: Invokes the JAWS window, gives JAWS the focus. Function 93: MenusActive Description: TRUE if a menu is currently active, FALSE otherwise. Use:Returns integer. Function 94: DialogActive Description: TRUE if a dialog box is currently active, FALSE otherwise. Use:Returns integer. Function 95: IsJAWSCursor Description: TRUE if the JAWS cursor is currently active. Use:Returns integer. Function 96: ToggleVerbosity Description: Changes the verbosity level. Function 97: GetVerbosity Description: Get the verbosity level. Use:Returns integer. Function 99: CaretVisible Description: Indicates presence of an insertion point or caret. Use:Returns integer. Function 100: SayControl Description: Speaks the contents of the dialog option and its prompt. Use:(integer handle of dialog option to speak) Function 103: UnloadJAWS Description: Stops JAWS and unloads it from memory. Function 104: GraphicWizard Description: Invokes the Graphic Wizard dialog. Function 105: MoveToGraphic Description: Move to specified graphic element in current window. Use:(integer direction) 0=first, 1=next, 2=prior, 3=last. Returns integer. Function 106: GetWindowType Description: returns text string containing the type of the window. Use:Provide (integer Handle of window to check), returns string. Function 107: Pause Description: Pauses the current macro. Function 108: LeftMouseButton Description: Simulates left mouse button. Use:Press once for single click and twice for double click. Function 109: RightMouseButton Description: Simulates right mouse button. Use: Press once for single click and twice for double click. Function 110: HasTitleBar Description: Returns "true" if the passed window has a title bar. Use:(integer handle of window), returns integer. Function 111: GetParent Description: Returns the handle of the passed window's parent. Use:Provide (integer handle of window), returns integer or 0 if none. Function 112: GetFirstChild Description: Returns the handle of the passed window's first child. Use:Provide (integer handle of window), returns integer or 0 if none. Function 113: GetNextWindow Description: Returns the handle of the next window. Use:Provide (integer handle of window), returns integer or 0 if none. Function 114: GetPriorWindow Description: Returns the handle of the prior window. Use:Provide (integer handle of window), returns integer or 0 if none. Function 115: GetFirstWindow Description: Returns the handle of the first window at the same logical level as the passed handle. Use:Provide (integer handle of window), returns integer. Function 116: GetFocus Description: Returns the handle of the window with focus. Use:Return integer or 0 if none. Function 117: GetRealWindow Description: starting with the passed window handle, it traverses upwards through the window list until a window with a title-bar is found. Use:Provide (integer handle of window), returns integer. Function 118: GetAppMainWindow Description: Returns the handle of the application main window associated with the passed handle. Use:Provide (integer handle of window), returns integer. Function 119: GetWindowName Description: Returns the name of the passed window. Use:Provide (integer handle of window), returns string. Function 120: GetCurrentWindow Description: Returns the handle of the current window. Use:If the PC cursor is active, then this is the window containing the caret or highlighted item. If the JAWS cursor is on, this is the window containing the mouse pointer. Returns integer. Function 121: SayWindow Description: Speak the contents of the passed window. Use:Provide (integer handle of window) Function 122: SayWindowTypeAndText Description: Speak window title, type, and checked/unchecked status. Use:Speaks information for passed window, and marks this text as having been spoken, so the {TEXT} and {HIGHLIGHTEDTEXT} events won't speak it again. See section 3 for a description of "event macros" such as {TEXT} and {HIGHLIGHTEDTEXT}. Function 123: ToggleHomeRow Description: Toggles the status of home-row mode. Use:Returns integer. Function 124: ExpandString Description: Inserts a space between adjacent characters of a string. Use:Provide (string text to expand), returns string. Function 125: LeftMouseToggle Description: Toggles the pressed/released state of the left mouse button. Use:Returns 1 when the button is being pressed, and 0 when it is being released. Function 126: ToggleScreenEcho Description: Cycles through the possible screen echo settings. Use:0 = none, 1 = highlighted text, 2 = all text. Function 127: GetScreenEcho Description: Gets the Screen Echo setting. Use:0 = none, 1 = highlighted text, 2 = all text. Function 128: StringContains Description: Checks to see if one string is contained in the other Use:Parameter 1 = string to look in, parameter 2 = string to search for, returns an integer in response. Function 129: SDMSayWindowTypeAndText Description: Speaks the window type and text for SDM windows. Use:Parameter 1 = integer handle of SDM window, parameter 2 = integer ID of item in window. Function 130: SDMGetFocus Use:Parameter 1 = integer handle of current window. Returns integer in response. Function 131: SDMSayStaticText Use:Parameter 1 = integer handle of SDM window Function 132: InvisibleCursor Description: Turns on the invisible cursor. This cursor can read the desktop without moving the mouse pointer as occurs when the JAWS cursor is moved. Function 133: IsInvisibleCursor Description: Determines whether the invisible cursor is on. Use:Returns integer in response. Function 134: RouteInvisibleToJaws Description: Moves the invisible cursor to the JAWS cursor. Function 135: RouteInvisibleToPc Description: Moves the invisible cursor to the PC cursor. Function 136: RouteJawsToInvisible Description: Moves the JAWS cursor to the invisible cursor. Function 137: HasFocusRect Description: Determines if the specified window has a focus rectangle. Use:Parameter 1 = integer Handle of window to check. Returns integer in response. Function 138: SayFocusRect Description: Says the contents of the focus rectangle. Use:Parameter 1 = integer Handle of window. Returns integer in response: true = text was spoken, false = otherwise. Function 139: FindString Description: Searches for a string and moves the JAWS cursor to it when the string is found. Use:Parameter 1 = integer handle of window to search. Parameter 2 = string to search for. Parameter 3 = integer for search direction: 0 = start at the top and 1 = start at the bottom. Parameter 4 = integer for search location: 0 = extend search outside of the current window or control, 1 = search within the current window or control. Returns integer in response: 0 = failure, non-zero = success. Function 140: FindGraphic Description: Searches for a graphic and moves the JAWS cursor to it when it is found. Use:Parameter 1 = integer handle of window to search. Parameter 2 = graphic label to search for. Parameter 3 = integer for search direction: 0 = start at the top and 1 = start at the bottom. Parameter 4 = integer for search location: 0 = extend search outside of the current window or control, 1 = search within the current window or control. Returns integer in response: 0 = failure, non-zero = success. Function 141: IsPCCursor Description: Determines whether the PC cursor is currently on. Use:Returns integer in response: true = on. Function 142: IsSameMacroKey Description: Determines whether a macro key has been pressed twice within half a second. Use:Returns integer in response. Function 143: SpellWord Description: Spells the current word. Function 144: SaveCursor Description: saves the current cursor type, and if the JAWS cursor is active, then it saves the position of the JAWS cursor. Function 145: RestoreCursor Description: Restores the cursor saved by the most recent use of SaveCursor. Function 146: PerformMacroKey Description: Performs the macro assigned to the specified key. Use:Parameter 1 = name of key with macro to be performed. Function 148: SayToCursor Description: Speaks text to the left of the current cursor. Function 149: SayFromCursor Description: Speaks text to the right of the current cursor.