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.
