Chapter 2
JAWS MACRO EDITOR
(Also contained in the disk file "T2M-EDIT.TXT".)
 
 
 
 
 
 
CONTENTS OF CHAPTER 2
  
     1.   CHAPTER INTRODUCTION                              11
     2.   WHAT IS A MACRO?                                  11
     3.   STRUCTURE OF A JAWS MACRO                         13
     4.   TYPES OF MACRO FILES                              15
     5.   USING THE MACRO EDITOR                            16
     6.   MACRO EDITOR MENU BAR                             17
          6.1 Files Menu                                    18
          6.2 Edit Menu                                     19
          6.3 Search Menu                                   19
          6.4 Options Menu                                  20
          6.5 Help Menu                                     20
     7.   TEXT SELECTION AND EDITING KEYS                   20
     8.   DEVELOPING NEW MACROS                             21

 1.   CHAPTER INTRODUCTION 
 
     This chapter introduces JAWS macros and describes the
use of the JAWS macro editor.  It describes the parts of a macro
and offers general suggestions for developing new macros.  JAWS
macro functions are described in the next chapter.
 
 
2.   WHAT IS A MACRO?
 
     Before talking about how to use macros, it will be useful to
define the term "macro".  A Macro is simply a sequence of
actions that are grouped together into a single operation.  The
purpose of a macro is to save time by automating tasks that you
could do manually.  A macro, for example, can reduce thirty key
strokes into one key stroke.
 
     A macro completes the same kind of activities you perform
when you are using your keyboard, however, the macro can
perform the activities almost instantaneously.  A macro can enter
key strokes, activate functions, and even make simple decisions.
 
     The concept of a macro can be demonstrated by looking at
a common human activity.  The human "tooth brush" macro is
performed every morning by millions of people and contains
concepts that are quite similar to those used in computer macros. 
The toothbrush macro begins as you start to look for your tooth
brush, and then continues through the following steps. 
 
a.   Pick up toothbrush.
 
b.   Pick up toothpaste.
 
c.   Remove the cap from the toothpaste tube.
 
d.   Squeeze toothpaste tube and deposit toothpaste on
     toothbrush.
 
e.   Replace the cap on the toothpaste tube and set the tube down.
 
f.   Brush teeth, as instructed by your dentist.
 
g.   After completing the brushing sequence, rinse mouth and
     toothbrush with water.
 
h.   Place tooth brush back in its proper location.
 
     You can think of each of the above steps as a set of
individual activities, or you can consider them to be one activity,
i.e. brushing your teeth.  If you put the individual steps together
and give them a name, then you are doing the same thing that is
done when you create a macro.  The toothbrush macro is also like
a computer macro in one additional way.  Most of the time, when
you perform the toothbrush macro, you do so without thinking
about the steps.  Similarly, when you use a computer macro you
don't have to give much thought to the steps that are being
performed, you just need to think about what the macro can do
for you.
 
     A macro can be divided into two parts:  the "macro key"
and the "macro definition".  The key or combination of keys that
you press to start a macro is called the Macro Key.  The set of
key strokes and related activities that are executed when the
macro key is pressed is called the Macro Definition.  We may,
from time to time, simply use the term "macro" in a general way
to refer to both the macro key and its definition.
 
     Almost any key on your keyboard or combination of keys
can be used for 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+LEFT ARROW} as a macro key.
 
     Based on the preceding information, it becomes clear that
many of the keys that are used to move the PC cursor and the
JAWS cursor, and to read the desktop are actually macro keys. 
As a result, the functions performed by the standard JAWS
keyboard layout can be modified to meet specific needs and
preferences, and it is even possible to create a completely
different keyboard layout.
 
 
3.   STRUCTURE OF A JAWS MACRO
 
     When you create or edit macros, you are working with text
files.  The Macro Text Files are automatically converted into binary
files when you save your work with the JAWS macro editor.  The
example that follows is taken from the default set of JAWS
macros.  It shows the proper Structure of a JAWS Macro.  The
macro text is displayed in the same way that it would appear
when being read with the JAWS macro editor.  Information about
using the JAWS macro editor is presented later in this chapter.
 
# This is for the PAGE DOWN key of the speech pad
MacroBegin
{Page Down}
SayString("page down")
JAWSPageDown()
MacroEnd
 
     Macros make sense when they are broken down into their
component parts.  To understand this macro, you need to
understand the purpose and function of each part of the macro. 
Each line of the macro is described below. 
 
Line 1:
# This is for the PAGE DOWN key of the speech pad
     Any line in a macro file that begins with a "#" (number
     sign) is a Remark Line. It is written for the use of the
     person editing the macro.  The preceding line simply
     indicates that this macro is executed when the {PAGE
     DOWN} on the speech pad is pressed.  Macros also should
     be separated by blank lines, and a blank line should precede
     this line.
 
Line 2:
MacroBegin
     This line indicates the actual Beginning Point of the Macro. 
     It is required in every macro.
 
Line 3:
{Page Down}
     This line identifies the Macro Key.  The name of the key
     must be surrounded by braces "{  }" as is shown here.  If
     you want to use a combination of keys for the macro key
     on this line, for example, the {INSERT} with the {PAGE
     DOWN}, then it would be written as:  {INSERT+PAGE
     DOWN}.  A macro key such as
     {INSERT+CONTROL+PAGE DOWN} could also be used. 
     This macro key means that you must hold down both the
     {INSERT} and the {CONTROL} before pressing the {PAGE
     DOWN}.  In addition to using a macro key, you can also
     indicate a macro event, i.e. if a certain condition occurs on
     the desktop, then the macro will respond.  Chapter 3 of
     this manual lists valid macro keys and event macro names. 
     Text in a macro can be either uppercase or lowercase.
 
Line 4:
SayString("page down")
     The expression "SayString" is a Macro Function.  This
     specific macro function performs the task of sending a
     string of text to the speech synthesizer so it can be spoken. 
     Macro functions often must be followed by a Parameter
     that is enclosed within parentheses "(  )" as shown above. 
     In many cases, a parameter is not indicated, however the
     parentheses are still required.  In this specific case the text
     string must also be enclosed by quotation marks since this
     is text that is to be spoken.
 
Line 5:
JAWSPageDown()
     This is a macro function that initiates the page down
     command.  Since this is a "JAWS Page Down" function, it
     performs different activities depending on cursor status. 
     When the JAWS cursor is active, it will move the JAWS
     cursor to the bottom of the active window.  When the PC
     cursor is active, it will send a standard page down
     command to the Windows application. 
 
Line 6:
MacroEnd
     This required line indicates the Ending Point of the Macro. 
     This line should be followed by a blank line to separate it
     from the next macro.
 
     The concept of macros is universal.  Many software
programs have a facility for creating macros, however, their
potential uses are not identical.  For example, a JAWS macro can
read the title of a window or announce the status of a check box
in a dialog, but a WordPerfect macro cannot perform these
functions.  A JAWS macro, however, could be used to execute
most any function of Microsoft Word, WordPerfect, or most any
other application software program.  JAWS macros actually offer
greater versatility than other types of macros, because they can
blend screen reading functions with application software functions
to create powerful tools.
 
 
4.   TYPES OF MACRO FILES
 
     When you edit macros, you are working with a specific type
of text file called a JAWS Macro Source file.  These files have the
file name extension of ".JMS".  When you use the macro editor
to save a file with the extension of ".JMS", it saves the text file
and automatically compiles it into the binary file that is use by
JAWS.  JAWS Macro Binary files have filename extensions of
".JMB".  If you use the macro editor with files that do not have
the filename extension of "JMS", then the files are not compiled
when they are saved.
 
     The file "DEFAULT.JMS" is the Default JAWS Macro
Source file that is compiled by the macro editor to create
"DEFAULT.JMB".  The "DEFAULT.JMB" is always in use
regardless of the Windows application you are using.  Other
application "JMB" files are automatically loaded when you start
Windows applications.  
 
     Application "JMB" files are used concurrently with the
"DEFAULT.JMB" file.  When you press a macro key, JAWS first
looks at the application ".JMB" file (if there is one) to find a
corresponding macro. If a macro is not present, then JAWS looks
at the "DEFAULT.JMB".  If a macro is not present in the default
macro file, then JAWS passes the key stroke to the Windows
application for processing. 
 
     You can use any text editor to edit a ".JMS" file, however
the macros can only be converted into a ".JMB" file by the JAWS
macro editor.  If you use an editor such as Windows Notepad
when editing macros, then you still need to use the JAWS macro
editor to compile the file.  Thus, you must activate the JAWS
macro editor, open your file, and then save it with the macro
editor.
 
 
5.   USING THE MACRO EDITOR
 
     The JAWS macro editor is a full function Windows text
editor that is used whenever you need to create new macros or to
modify the functioning of existing macros.  Use the following
steps when creating or editing macros.
 
a.   Switch to the JAWS application window with {ALT+TAB}
     or by using the Windows Task Manager.
 
b.   Press {ALT+M} to select the Macro menu and press
     {ENTER} to Start the Macro Editor.
 
c.   At this point the edit field is empty and you can begin
     writing macros.  If you wish to edit an existing macro file,
     then press {ALT+F} to select the Files menu, and then
     choose the Open dialog.  The dialog will display all files in
     the \JFW\SETTINGS\ENU subdirectory that have the
     filename extension of ".JMS".  These files are JAWS macro
     source files.  Use your {TAB} to move to the list box that
     lists the filenames and choose the file you wish to edit.
 
 
6.   MACRO EDITOR MENU BAR
 
     The Macro Editor Menu Bar uses a standard Windows
structure.  Its menus and dialogs use standard menu bar keys.
 
Activate the Menu Bar = {ALT} or {F10}
 
Cancel the Use of the Menu Bar = {ALT}, {F10} or {ESCAPE}
 
Move Between Menu Names on the Menu Bar 
= {LEFT ARROW} or {RIGHT ARROW}
 
Choose the Selected Menu Name from the Menu Bar = {ENTER}
     You can also press a selection character to select and
     choose a menu in one step, such as {ALT+F} for the Files
     menu.
 
Move Between Menu Items in a Menu 
= {UP ARROW} or {DOWN ARROW}
 
Choose the Selected Dialog Name or Command from a Menu =
{ENTER}
     You can also press a selection character to select and
     choose a menu item from the menu in one step.  Selection
     characters are usually the first letter of menu items.
 
Cancel the Use of a Menu = {ESCAPE} or {ALT}
 
Identify All Dialog Options in a Dialog = {INSERT+B}
     This JAWS command reads the dialog options in the order
     in which they would be encountered when the {TAB} key
     is used.  The selection cursor does not move from its
     current location when this command is used.
 
Move to the Next Dialog Option = {TAB}
 
Move to the Previous Dialog Option = {SHIFT+TAB}
 
Desktop Help for Using Commands in a Dialog = {INSERT+F1}
     JAWS describes the current dialog option and explains how
     it is to be used.
 
Context Help for the Function of Dialog Options = {F1}
 
Cancel the Use of a Dialog = {ESCAPE}
 
6.1  Files Menu
 
     The menu items in the files menu are very similar to those
in Windows Notepad and other text applications.
 
New = Clear the document window.
 
Open = Open an existing file.
     This item displays a standard Windows dialog for opening
     files.
 
Save = Save the current file under its current name.
     When you save a JAWS macro file with the filename
     extension of ".JMS", the text is compiled and saved in a
     ".JMB" file.  If errors are found in the ".JMS" file, then you
     are informed of the error type, and your insertion point is
     placed on the line where the error was found.  Binary files
     are compiled even when errors are identified in ".JMS"
     files.
 
Save As = Save the current document under a new name.
     Your text is simultaneously compiled and saved in a ".JMB"
     file when the filename has a ".JMS" filename extension. 
     Files with other filename extensions are not compiled.
 
Exit = Quit the editor.
 
6.2  Edit Menu
 
Undo = Restore the last editing action.
 
Cut = Remove the selected text from the document.
     You must first use the standard Windows text selection
     keys to select text before it can be cut.  These keys are
     listed in a later section.  Information that is cut can be
     pasted into a new location.
 
Copy = Make a copy of the selected text.
     You must select the text that is to be copied with the
     standard text selection keys of Windows.  These keys are
     listed in a later section of this chapter.  Information that is
     copied can be pasted into a new location.
 
Paste = Insert previously cut or copied text into a document.
     Be sure your insertion point is at the exact location where
     text is to be inserted before you choose paste.
 
Delete = Delete selected text from the document.
     Deleted text cannot be pasted back into the document. 
     Deleted text, however, can be restored with the Undo
     function if it is used before another editing function has
     been used.
 
Select All = Selects all text in the document.
     The selected text then can be copied or cut.
 
6.3  Search Menu
 
Find = Use dialog to set up a text search.
 
Find Next = Use previously stated search criteria to locate the
next occurrence of text. 
 
Replace = Search for text and replace it with new text.
 
6.4  Options Menu
 
Color = Use dialog to set screen color for the macro editor.
 
Font = Use dialog to set font type and size for the macro editor.
 
6.5  Help Menu
 
Quick Reference = Display help text.
     Use {PAGE UP}, {PAGE DOWN}, {UP ARROW}, and
     {DOWN ARROW} to read through the text file.
 
 
7.   TEXT SELECTION AND EDITING KEYS
 
     These Text Selection Keys can be used with the JAWS
macro editor.  These are standard Windows text selection keys.
 
     When you begin to select text with one of these
commands, the text you select begins at the location of the
insertion point.  If text is already selected, then the use of the
command cancels the previous selection.  Selecting text means
that you are highlighting it (or blocking it) in preparation for doing
something with the text.
 
Examples:
 
          To delete a word, place your cursor at the beginning
     of the word and press {SHIFT+CONTROL+RIGHT
     ARROW} to select the word.  Then choose one of the
     delete commands.
 
          To copy three lines of text, place your cursor at the
     beginning of the first line to be copied, then hold down
     {SHIFT} while you press {DOWN ARROW} four times.  Do
     not release the SHIFT key until you are finished selecting
     text.  Release the {SHIFT} when the cursor is at the proper
     location, and choose one of the copy commands.  If you
     select the wrong text it is easy to start over, because the
     previously selected text is cancelled as soon as you press
     {SHIFT} with another text selection key.
 
Select One Line of Text Up or Down
= {SHIFT+UP ARROW} or {SHIFT+DOWN ARROW}
 
Select Text from the Insertion Point to the Beginning of the Line
= {SHIFT+HOME}
 
Select Text from the Insertion Point to the End of the Line 
= {SHIFT+END}
 
Select the Previous Word = {CONTROL+SHIFT+LEFT ARROW}
 
Select the Next Word = {CONTROL+SHIFT+RIGHT ARROW}
 
Select Text from the Insertion Point to the Beginning of the
Document 
= {CONTROL+SHIFT+HOME}
 
Select Text from the Insertion Point to the End of the Document 
= {CONTROL+SHIFT+END}
 
Delete the Character to the Left of the Insertion Point or Delete
Selected Text = {BACKSPACE}
 
Delete the Character to the Right of the Insertion Point or Delete
Selected Text = {ALT+DELETE}
 
 
8.   DEVELOPING NEW MACROS
 
     The best way to learn about the techniques that are used
in JAWS macro programming is to spend some time studying the
macros in the "DEFAULT. JMS" file.  Read the macros and follow
the steps they contain from beginning to end.  If you do not
understand a macro function, then you can look it up in the next
chapter or you can review the file "FUNCTIONS.JML" located in
\JFW\SETTINGS\ENU.  This file contains the most up to date list
of macro functions that are available in the JAWS Macro
Language.  The sample macros in the next chapter also can
stimulate your thinking about macro programming.
 
     Once you understand the purpose of the macro functions
and you understand how they can be put together to perform
tasks, then the next step is to study your application programs. 
When you find a situation where your productivity can be
enhanced with a new macro, then you need to analyze the
activity.  You need to breakdown the activity into its individual
steps.  You need to answer the types of questions presented
below in order to create effective macros.
 
a.   What is the exact task you are trying to complete?  Be as
     specific as possible.
 
b.   What specific keys do you need to press and in what order
     must they be pressed to accomplish the specific task?
 
c.   Do you want JAWS to speak?  If so, then do you want
     JAWS to speak a string of text that is built into the macro
     or to read something from the desktop?
 
d.   If the macro must make a decision based on the status of
     your application program, then what information on the
     desktop can JAWS check in order to decide which
     response is appropriate?
 
     The preceding list of questions is not comprehensive, but
it can help point you in the proper direction.  A certain amount of
creativity is also helpful when creating macros.  Don't be afraid to
try a new macro.  If it doesn't work, then you can always remove
it from the macro file. 

