Everything You Always Wanted to Know About Writing JAWS Scripts, But Didn�t Know

Whom to Ask

By Kenneth A. Gould

Copyright 2000 by Freedom Scientific Inc., All Rights Reserved

Preface

The Microsoft Word version of this manual has been set up so you are able to jump
directly to any section shown in the Table of Contents. To do this, you can click
anywhere on the appropriate line in the Table of Contents, either on the entry
itself or on the page number to the right of each entry. One way to accomplish
this with the keyboard is as follows:

Find the section of interest in the Table of Contents by moving there with the PC
cursor.
Route the JAWS cursor to the PC cursor.
Click the left mouse button by pressing NUM PAD SLASH. You will then jump
automatically to the page of interest.

This manual also contains hyperlinked cross-references to sections that are in the
form See Section X, where X is the hyperlinked section number. You can jump
directly to the section by clicking on the section number reference with the JAWS
cursor. After reading the section you have jumped to, you can return to your
original position in the Table of Contents or to your original cross-reference at
any time by pressing ALT+LEFT ARROW.

This manual has been updated for version 3.7 of JAWS.

Table of Contents

1 Introduction 7
1.1 What are Scripts? 7
1.2 Scripts versus Functions 8
1.3 Constants and Variables 10
1.4 Structure of Manual 12
Part I: Getting Started With Scripts
2 Scripts: A Brief Overview 15
2.1 What are Script Files? 15
2.2 What is the Script Manager? 18
2.3 Anatomy of a Script 19
3 Our First Scripts 21
4 The Script Manager 27
4.1 The Menus 27
4.2 Script Manager File Types 27
4.3 Include Statements 28
4.4 The New Script and Script Information Dialogs 29
4.4.1 General Tab 29
4.4.2 Parameters Tab 31
4.5 The Insert Function and Insert PerformScript Dialogs 32
5 Creating Simple Scripts 35
5.1 Script Documentation 35
5.2 Individual Script Structure 35
5.3 Using Script Functions 36
5.3.1 Reading Text 36
5.3.2 Moving Around on the Screen 38
5.3.3 Creating Reading Scripts 42
5.4 Putting It All Together 44
Part II: Creating Advanced Script Files
6 Windows Program Structure 50
6.1 Hierarchy 50
6.2 Identifying Windows 52
6.2.1 Window Classes, Types, Type Codes, and Subtype Codes 52
6.2.2 Control ID's and Window Handles 54
7 Building Blocks of the Script Language 57
7.1 The Script 57
7.2 The Function 58
7.3 Types of Statements 59
7.3.1 Comments 59
7.3.2 Includes 60
7.3.3 Variables 61
7.3.4 Constants 65
7.3.5 Built-in Functions and Operators 65
7.3.5.1 Built-In Functions 66
7.3.5.2 The GetCurrentWindow and GetFocus Functions 67
7.3.5.3 The Pause and Delay Functions 69
7.3.5.4 A Word About SDM Windows 69
7.3.5.5 Arithmetic Operators 71
7.3.5.6 Logical Operators 71
7.3.5.7 Bitwise operators 73
7.3.5.8 Hook Functions 74
7.3.5.9 Introduction to Script Writing With Microsoft Objects 77
7.4 Controlling Flow 85
7.4.1 Sequential 86
7.4.2 Selection (Conditional) 86
7.4.3 Iterative 89
7.5 User-Defined Functions 91
7.5.1 Simple Functions 91
7.5.2 Functions That Require Parameters 94
7.5.3 Functions That Provide Returns 98
7.5.4 Event Functions 100
7.5.4.1 List of Event Functions 105
8 Script Writing Techniques 111
8.1 Exploring the Application With the Utility Functions 111
8.2 Obtaining Window Information With the ScreenSensitiveHelpTechnical Script
114
8.3 Script File Types 114
8.3.1 Source Files 114
8.3.2 Compiled Files 116
8.3.3 Include Files 116
8.4 Using Variables 117
8.4.1 Naming Conventions 117
8.4.2 Declaration Placement 118
8.4.3 Using Global Variables 118
8.5 Using Constants 119
8.6 Using Multiple Functions 123
8.6.1 Using Functions Sequentially 123
8.6.2 Using Nested Functions 124
8.7 Selecting and Manipulating Cursors 125
8.8 Sending a Keystroke 129
8.9 Making Your Scripts Compatible With Custom Verbosity Levels129
8.10 Synchronizing Documentation 130
9 Debugging 132
9.1 The JAWS Script Compiler 132
9.2 Erroneous Activity 133
10 Strategies for Attacking New Applications 136
11 Guidelines for Creating Distribution Script Files 137

12 Converting Macro Files 138

13 Acknowledgments 140
14 Appendix A - Answers to Homework Assignments 141
14.1 Answer to Homework Assignment #1 141
14.2 Answer to Homework Assignment #2 141
14.3 Answer to Homework Assignment #3 142
14.4 Answer to homework Assignment #4 143
14.5 Answer to Homework Assignment #5 143
14.6 Answer to Homework Assignment #6 144
14.7 Answer to Homework Assignment #7 146
14.8 Answer to Homework Assignment #8 146
14.9 Answer to Homework Assignment #9 147
14.10 Answer to Homework Assignment #10 147
15 Appendix B - Description of the Script Manager Menus 150
15.1 File Menu 150
15.2 Edit Menu 150
15.3 Script Menu 151
15.4 View Menu 151
15.5 Window Menu 151
15.6 Help Menu 152
16 Appendix C - The Most Important Built-In Functions 153
17 Appendix D - Important Built-In Functions Arranged by Task 181
17.1 Cursor 181
17.2 Positioning 182
17.3 Conditional Processing and Looping 183
17.4 Say 183
17.5 String and Integer Manipulation 184
17.6 Application 185
17.7 Braille 185
17.8 Mouse 186
17.9 Find 186
17.10 Windows and Objects 186
17.11 Frames 188
17.12 Scripts 189
17.13 SDM 189
17.14 Speaking Level 189
17.15 Options 190
17.16 System Activities 190
17.17 Colors 191
17.18 Control Synthesizer 191
18 Appendix E - How to Scope Out and Customize an Unknown Application 193

Introduction

What are Scripts?

First of all, let�s start out with some definitions. What is a script anyway?
When you perform a job on a computer, it usually involves a number of steps. You
may have to press several keys to get you to the right part of a program to do a
job, or you may even have to press several keys to open the program you want to
use. Then, once you are where you want to be, you may have to press several more
keys to enter the data you want. For example, you might be in a word processor and
want to type your return address at the top of a letter. This could become a
tedious task if you have to do it a lot, so wouldn�t it be nice if you could have
the entire return address typed out for you with one keystroke? That is exactly
the type of thing a script can do. A script is a sort of mini computer program
which combines many steps or keystrokes into one operation that you can activate
quickly and simply. Well, at least that�s one type of script. JAWS and other
computer applications use scripts all of the time, and obviously they aren�t always
being used to type out return addresses. So, more globally, scripts are sequences
of individual steps that can be used to activate and control a wide variety of
computer processes from things as simple as entering repetitive strings of data to
many of the things your computer does on an ongoing basis as part of its operation.
It is this sort of function we are going to be concerned with in this manual.
While you can certainly use what you will learn here to create a return address
script, you will also learn how to control JAWS in ways which will make it behave
more like you would wish.

Many aspects of computer control which we take for granted are actually under the
control of scripts. We don�t actually think of them as scripts since they are
coded as part of the application�s internal programming. For example, when you use
cursor movement keys or call up a dialog box in Microsoft Word with a hot key, you
are actually invoking a part of the program which performs a series of operations
or steps. By our definition, this is a script. JAWS uses many different kinds of
scripts which tell it what to do in certain situations or when you hit certain
keys. What makes JAWS such an immensely powerful program is that the designers
have decided not to hide away those scripts as part of the main program and, thus,
make them inaccessible to the user. If they had done this, then JAWS would be a
far less flexible tool and would be much less adaptable to the needs of unusual
applications. JAWS� designers made the conscious decision to let you write your
own scripts for a particular purpose and to let you see and modify the individual
default scripts that control many aspects of the program's performance. The
modified or newly-written scripts are then organized into individual script files
which have the same name as (but a different extension from) the application for
which they were created. Access to the scripts controlling JAWS' most fundamental
behavior has been provided for two very good reasons. First, every user wants to
be able to personalize the program to behave just as he or she would like. Second,
while the JAWS designers have anticipated many of the screen reading situations
which will occur with different applications, it is impossible to foresee every
weird or nonstandard screen setup which the world�s programmers will come up with.
You have at your disposal a powerful arsenal of script commands which you can apply
to the conquest of these unusually-designed applications. All you have to do is
learn how to use them.

By the way, it is not always necessary to use a script to customize JAWS. For
example, one can cause certain parts of the screen to speak or be silent by using
the frames which can be created with the Frame Manager. As time goes by, there
will surely be more features such as this added to JAWS that will allow you to do
more customization without resorting to scripts. But there will always be
situations too bizarre or convoluted for anything but a well-written script to cope
with. Remember that after you have learned how to use the JAWS script language you
have a very powerful tool that is much more incisive than any simple feature can
be.

So, you�re probably asking yourself now, what�s the difference between a macro and
a script? Well, in a word, there really isn�t any difference. Scripts are macros,
and that�s all there is to it. Don�t let the jargon confuse you. We�ll call them
scripts from now on, but �A rose by any other name," etc., etc.

Scripts versus Functions

JAWS scripts can be divided into two main categories. Those which are activated by
a keystroke are called scripts, and those which are not are called functions.
Let�s first talk about the keystroke scripts. How does JAWS know that it should
read the new line of text when you are in a word processor and hit the DOWN ARROW
key? Well, it knows this because there is a script in the main JAWS script file
(called the Default script file) which is tied or �bound� to the DOWN ARROW key and
tells JAWS to read the new line. This particular script has the name �SayNextLine�
and it is activated when you hit the DOWN ARROW key. This script is fairly
complicated because it has to analyze where you are and what you are doing when you
hit the DOWN ARROW key. It will check to see what kind of window you are in when
you hit the DOWN ARROW key, and, if you are in a word processor text window, it
will speak the line to which you move. There is a line in this script file that
reads �SayLine ()� and it gets activated after your cursor moves on to the next
line. This is the line of the script which actually performs the function which
reads the line. There is a similar script called �SayPriorLine� which gets
activated when you hit the UP ARROW key. This script uses the same �SayLine�
function as part of its coding. When you hit the RIGHT and LEFT ARROW keys, two
other scripts get activated, �SayNextCharacter� and �SayPriorCharacter�. These
scripts use a function called �SayCharacter� as part of their coding to speak the
new character after your cursor moves on to it. There are other key-bound scripts
designed to operate when many of the other keys on your keyboard are pressed.
These scripts analyze the current situation and try to perform an action
appropriate for that situation. If the situation is very unusual and has not been
anticipated by the JAWS designers, then that is when you may have to do some
modifications to make it perform as required.

The scripts that are not bound to or activated by keystrokes are called functions.
Since these functions cannot be activated by a keystroke, they must be utilized in
other ways. Functions also differ from key-bound scripts in that they return some
information after they finish executing, whereas key-bound scripts never do. Once
again, don�t let the jargon snow you. A function is just a script that is not tied
to a particular keystroke and which returns some information when it is done
executing. Why is this done? There are two very good reasons. First, some
functions operate automatically when certain events occur. There is, therefore, no
need to have such functions tied to keystrokes because it is not a keystroke which
activates them. Second, sometimes a set of scripting statements is very generally
applicable to many situations and can be used over and over again. Instead of
writing out this set of statements for every script that needs it, it can be placed
into a function which can be utilized or "called" by any other script that needs
it.

Thus, functions are subdivided into two categories, the ones that trigger
automatically when certain things happen and those which only get triggered when
they are �called� by another script. The first type is called an event function
because it runs automatically when certain system events happen. For example, the
NewTextEvent function gets called when any new text gets written to the screen, and
the BottomEdgeEvent function gets called when the cursor reaches the bottom of a
window. Without the NewTextEvent function, nothing at all would be spoken
automatically by JAWS when information appeared on your screen, and without the
BottomEdgeEvent function, your PC would neither beep nor speak a warning message
when the JAWS cursor reached the bottom of a window. The second type of function,
the type not called automatically by certain Windows situations, has no special
name (believe it or not) so we�ll just call it a function. These plain functions
operate only when they are called by another script or function. This is done by
placing the name of the function within another script or function. If you do
this, then when the script gets to the line which has that function�s name, it will
cause that function to be run. This process is termed �calling� a function. Yeah,
I know, more jargon, but you�ll just have to get used to it. Calling a function
means, quite simply, placing that function�s name into another script so it will
get performed at the appropriate time. For example, the NewTextEvent function
mentioned above has a line in it that reads �SayNonHighlightedText ()�. If the
NewTextEvent function has analyzed the new text written to the screen and decided
that it is properly handled by the SayNonHighlightedText function, it will pass off
the job to that function by calling it and then let it speak the text for you. On
the other hand, if the NewTextEvent function decides that the screen information is
highlighted text, then it will call a different function named �SayHighlightedText�
instead, and it will let that function do the speaking for you. Decisions,
decisions, decisions. Well, that�s what scripts do. They analyze what�s going on
and make a decision about how to handle the screen reading for you. If they don�t
do it right, your job is to modify the relevant script so it does do it right.

By the way, you might have noticed that there was a left and right parenthesis
after the function name SayNonHighlightedText mentioned above. These parentheses
are always required when calling a function within a script. Sometimes information
is placed between these parentheses, but that�s something we�ll talk about later.
(See Chapter 7.5.2.)

The plain-Jane, non-event functions are further divided into two types. The first
type is the list of over two hundred functions which are available for you to use
in the JAWS script language. These functions are called "built-in" functions and
are hard-coded into JAWS. You can call them when creating scripts, but you cannot
change them. The second type of plain function is the type present in the script
files, either created by JAWS� designers or added by a user. These are called
user-defined functions. After these functions have been created, they will also
appear in the function list for you to use within the scripts you create.
Obviously, the main difference between these and the hard-coded functions is that
these can be modified by a user, if necessary.

Constants and Variables

We need to introduce two other terms before actually getting into script writing.
They are �variable� and �constant�. A variable is a word of one or more letters
which can be used to store a value that is determined during the processing of
scripts. This value is often not known in advance and can change one or more times
during script processing. The value that is determined is assigned to the variable
during the course of the script�s operation, and the variable maintains that value
until and unless it is changed by another script operation. The value of this
variable can be used to make decisions by that script or another script. For
example, in the statement Let X = 1, X is the variable, and we are assigning a
value of 1 to it. X has the value of 1 until and unless we change it to something
else or the operation of the script changes it for us. This is, by the way, the
type of script statement we use to assign a value to a variable manually. In the
course of running a particular script, we can have statements that do one thing if
X equals 1, but do something else if X has a different value. Further, the value
being held by X might represent the kind of window we are currently in, say a
button, an edit field, or a list box. X would have a different value for each of
these types of windows, and our script might need to perform different operations
depending on what type of window we were in and, therefore, what value was assigned
to X. If our script had the capability of looking into the Windows operating
system and determining what type of window we were in, the script could then assign
the appropriate value to X and the script could then continue its processing,
deciding which of several courses of action to perform based on the value (i.e.,
type of window) being stored in the variable. JAWS does have this capability to
look into the Windows operating system in this fashion, and this type of decision
based on the current window type is exactly the kind of decision-making continually
being performed by JAWS. The next time that same script runs, we may be in a
different window, and the variable will, therefore, have a different value stored
in it. The script would then decide to do something quite different, the action
appropriate for that type of window. Again, scripts often must make decisions, and
the value stored in a variable is one way they can decide what to do next.

Constants are quite a different matter because, as their name implies, they do not
change their value. Once a value is assigned to a constant, it stays that way.
This may seem to be a rather strange waste of time, but it is really quite
convenient. Constants are a way of using easily-remembered names to store hard-to-
remember strings of letters or numbers. For example, let�s say our friend Joe has
a social security number 589-43-3894. Further, let�s say we have to work with ten
people, each with his or her own social security number. We could make a constant
called JoeSocSecNum and then place Joe�s social security number in that constant by
using the equation JoeSocSecNum = 589433894. We could do something similar with
each of the other persons and his or her social security number. Then, when we
wanted to print out a person's social security number, all we would have to do is
ask the program to print out the value of each person�s social security number
constant. Since JoeSocSecNum is much easier to remember than 589-43-3894, we have
made life much easier on ourselves by using a constant instead of trying to
remember a long number. JAWS does this sort of thing a lot, and that�s what we
mean when we talk about constants in the context of the JAWS scripting language.

In case you are still a little confused about variables and constants, let�s use
another analogy that might help clarify them a little more. We�re all familiar
with touch-tone telephones that use a numeric keypad of buttons that we press to
dial a telephone number. In addition to the numbers zero through nine and a couple
of symbols, some telephones have some additional programmable buttons that can be
used to store whole telephone numbers that we call frequently. One might, for
example, store the sales number of his favorite software vendor in one of those
buttons so he could quickly call to place an order without having to look up the
number. Now, the buttons that contain the numbers zero through nine could be
considered as constants since the numbers they contain never change. The first
button on the top row is always a one, so it is a constant. The programmable
buttons, however, can be changed at will to contain new numbers. You might, for
example, have to change the software vendor button to a new phone number if the
company moved to a new address. Since these programmable buttons can be changed at
will, they are much more like variables, and they can be altered to contain the
information we most need at any given time. Variables in scripts are like that,
too. They can be changed as needed, either by the user or automatically by a
script, depending upon circumstances.

Structure of Manual

As we mentioned above, individual JAWS scripts are arranged in files called script
files. This manual contains all of the information you will need to write your own
scripts and arrange them into files that will be used by your computer every time
you run an application. The following is a list of the remaining chapters of this
manual with a brief description of what each contains.

Part I: Getting Started With Scripts

Chapter 2 - �Scripts: A Brief Overview� provides a broad, general understanding of
how scripts and the JAWS Script Manager function. The difference between the
default and application script files and how they work together is also covered.
�Anatomy of a Script� gives a brief introduction to the form a script takes so you
can better understand the construction of �our First Scripts� in the next chapter.
Chapter 3 - �Our First Scripts� helps you to create two simple scripts, compile
them, and load them so that you can gain a little confidence.
Chapter 4 - �The Script Manager� provides an in depth tour of the Script Manager
and all of its tools for creating scripts and script files.
Chapter 5 - "Creating Simple Scripts" teaches script writing on a small scale. It
is intended for those who want to tweak the existing scripts and create scripts to
read textual information from the screen.
Part II: Creating Advanced Script Files
Chapter 6 - "Windows Program Structure" covers the various identifiers used to
classify and differentiate among the many windows found in Windows programs. It
also covers how windows are arranged in a hierarchical order.
Chapter 7 - "Building Blocks of the Script Language" provides details on the
individual constructs that make up scripts. This is where we start to put things
together that will become scripts. We�ll also look at when and how to use the
various functions.
Chapter 8 - "Script Writing Techniques" starts putting all this information to use.
It provides the techniques used in writing advanced scripts.
Chapter 9 - "Debugging" covers how to work out the bugs in your scripts along with
some tips that help with the process.
Chapter 10 - "Strategies for Attacking New Applications" gives ideas on how to
approach the problem of analyzing and scripting a new application.
Chapter 11 - "Guidelines for Creating Distribution Script Files" lists several
recommended rules to observe for those creating script files.
Chapter 12 - "Converting Macro Files" describes the process of converting macro
files written for versions of JAWS for Windows prior to version 3into script files
that work with the current version.
Part I: Getting Started With Scripts

Scripts: A Brief Overview

Suppose you are using an application program that provides a description of each
menu item at the bottom of its window. A sighted user would just glance down to
see that information whenever the purpose of that particular item was unclear.
Sure, you could turn on the JAWS Cursor, go to the bottom of the window and read
the line, but wouldn�t it be easier if you could just press a hot key to read the
help text? Or even better, how about if JAWS could read it automatically? And, of
course, you�d want to be able to turn that automatic reading on and off. Well, if
this application you are using had a script file written for it, and if this script
file contained a script to do these things for you, you would then be able to have
this sort of convenient access. If no one else had created this special script for
you, you could then create it yourself, provided you have learned how to use the
JAWS script language to build your own scripts. This improved access would help to
bring the efficiency of using this program up to that of a sighted person, and it
would improve your productivity.

What are Script Files?

JAWS is always under the control of scripts. As we discussed above, a script is a

small computer program that modifies the way JAWS performs for a specific
situation. JAWS script files are collections of individual scripts which are
loaded specifically for use with a given Windows application. These script files
are loaded automatically by JAWS whenever you enter a new application. It is
important to understand that there are two types of script files: default and
application . You can think of script files as �stacked� in a sort of pile, with
the default on the bottom of the stack. The default script file is loaded when
JAWS starts and is always active in all sessions. An application script file is
stacked on top of the default when its application loads. JAWS knows to load the
application script file on top of the stack because the main part of the
application script file name (i.e., the part without the extension) is the same as
the application program name. Thus, our default script file is named DEFAULT.JSS,
and an application named SPREADSHEET.EXE would have a script file called
SPREADSHEET.JSS. When you leave this particular application, the specific script
file it uses will be unloaded, and all of the default scripts will again be active
until another application�s script file is loaded.

The default script file that is loaded when you first start JAWS contains hundreds
of scripts. These scripts give JAWS all of the information it needs to provide
proper voice output in most situations. This file tells JAWS what to speak and
when to speak it in most circumstances when running well-behaved applications. In
many applications, however, there are situations which deviate from the normal.
There may also be particular instances when customized reading of the screen is
required. If these occur it may be necessary to create a script file just for this
application. If such a script file has been created and exists in the JAWS
subdirectory which contains the JAWS configuration files, then it will also be
loaded when that application is run. This script file is the first one that is
looked at when a particular keystroke is used or when a situation occurs which
needs to call one of the event functions described earlier. (See Chapter 1.2.) If
the application script file does not contain a script relevant to the situation,
then JAWS will look in the default file. If the script is found in one of these
two places, it will be executed as soon as it is found, and no further processing
is required. IF no script is found in either location, then JAWS will pass the
keystroke off to the application, and that keystroke will be performed just as if
JAWS were not running. This hierarchy is very important. If a particular script
which exists in the default file is not appropriate for the application being used,
the user can place a customized version of that script in the application�s script
file, and that version will be used in preference to the one present in the default
file.

Since scripts higher up in the stack take precedence, a script in the application
script file will be run instead of one in the default script file if they are both
bound to the same keystroke, and a function in the application script file will be
called in preference to one in the default script file if they both have the same
name. For example, that means if you have a script in the application script file
assigned to CTRL+G, and you also have a script in the default script file assigned
to CTRL+G, only the one in the application will be executed when you press CTRL+G.
It doesn�t even matter if the two scripts have different names. It is the
keystroke binding which determines which script will run. If you attempt to assign
a script to a keystroke which is already in use by the default file while using the
JAWS Script Manager (See Chapter 2.2 and 4.), you will be given a warning message,
and you will have the opportunity to continue with the assignment or change it to
another key. This is to prevent you from accidentally disabling a script in the
default file without realizing you are doing so.

There are some important considerations when deciding on the names and keystroke
assignments for your scripts. If, on the one hand, the user gives the customized
script a different name from the one in the default script file, then the user can
also assign the script in the application�s script file to the same keystroke it is
assigned to in the default file with no adverse consequences. If, on the other
hand, the user gives the application script the same name that it has in the
default file, it is not even necessary to assign a keystroke to that application
script. In either case, JAWS will execute the version present in the application�s
script file and will ignore the one present in the default file. This is because
JAWS looks in both the default keymap file, DEFAULT.JKM, and the application keymap
file, APPLICATION.JKM, to find out if a script with a particular name is assigned
to a key when that key is pressed. JAWS will always execute a script in the
application script file in preference to one in the default script file, even if
the key assignment is made in the default keymap file. In other words, if both
script files have a script with the same name and the key assignment is made in the
default script file, JAWS will still know that it's supposed to execute the one in
the application script file.

Functions, since they are not bound to keystrokes, must use a different mechanism.
If the script is a function and, thus, is not bound to a keystroke, then a function
with a particular name in the application script file will be run instead of such a
function in the default script file that has the same name. So in the case of
functions, it is the name that decides the outcome, not the keystroke.

Note that there is a special case which occurs when you have a script in the
default script file and one in the application script file which both have the same
name and which are not bound to a keystroke. In this case, JAWS uses the script
name to determine which is active, and the script in the application script file
will take precedence over the one with the same name in the default script file.
In this special case, therefore, scripts not bound to keystrokes determine
precedence in the same way that functions do. Thus, if a script is run using a
PerformScript statement, the script in the application script file will be utilized
in preference to the one in the default script file. PerformScript statements are
an alternative way of running scripts, and they will be discussed later in this
manual. (See Chapter 4.5.)

It was mentioned above that, if there is an application script file available for a
particular application, it will be loaded automatically when that application is
loaded. JAWS knows to do this because the main part of the script file name is the
same as the name of the application. Starting with version 3.3 of JAWS for
Windows, an additional capability was added which allows a user to load a script
file of his or her choice at any time. This script file can have any name, and
that name does not have to resemble the name of the current application. If such a
script file is loaded, it will replace the regular application script file in the
stack if such a file is present. This special script file will, in turn, be
replaced automatically any time the user switches to a new application that loads
its own script file. This new capability allows a user to load a script file that
is tailor made to cope with unusual situations in an application where the
requirements are very different from the rest of the application. The special
script file could be loaded manually with a keystroke or automatically when certain
windows or items appear on the screen. The function used to load special script
files is called SwitchToScriptFile. It can be called manually or automatically by
techniques which will be described in the remainder of this manual.

Finally, it is important to understand that scripts present in the default script

file are available from any application being run, unless, as discussed above, the
default script is superceded by a script in the application script file. So if you
have a script which you wish to use from more than one application, you may wish to
place it in the default script file rather than in a particular application script
file.

What is the Script Manager?

JAWS provides you with all the tools you need to modify and create scripts. These
tools are present in a program called the Script Manager. The Script Manager is a
full-featured, text editor program. In addition to the usual features contained in
most text editors, it has built in capabilities to help you create scripts, insert
functions into your scripts, display reference information about these functions
and scripts that have already been written, check for errors that violate the rules
of correct script writing, and save and compile your script file. In addition,
there are three hot keys which allow you to look through the scripts in your script
file more efficiently. The function key, F2, can be used to jump forward from
script to script, while SHIFT+F2 can be used to jump backwards from script to
script. The hot key combination CTRL+L can be used to bring up a dialog which
lists all scripts in the current file in alphabetical order in a separate window.
This makes it easier to find a particular script within a large file if you know
its name but do not remember where in the file it resides.

We said in the last paragraph that the Script Manager could be used to save and
compile your script files. What do we mean by the word �Compile�? When you write
scripts for JAWS in the Script Manager, you write them in plain text. JAWS,
however, cannot use them in this form since it cannot understand plain text. When
you save your script file in the Script Manager, it automatically performs an
additional step which other text editors and word processors do not. It creates an
additional file which has been converted from text into a binary format which JAWS
can understand and use. The original text file is saved with a JSS (JAWS Script
Source) file extension, and the compiled or binary version is saved with a JSB
(JAWS Script Binary) file extension. This is why it is important always to create
and save your script files using the Script Manager. If you edit and save your
files using some other text editor such as Notepad, they will not be compiled when
you save them, and JAWS will be totally unaware of the changes you have made.

There are three ways to start the Script Manager. These are (1) from an
application by pressing INSERT+0, (2) pressing INSERT+F2 to invoke the Run JAWS
Manager Dialog, followed by the letter S and the ENTER key, or (3) by choosing
Script Manager from the JAWS Utilities menu. When you start the Script Manager
from within an application with either method 1 or 2, it automatically opens the
script file for that application. If no file exists, the Script Manager creates
one. When you start the Script Manager from the Utilities menu, it does not open
any file.

The Script manager will be discussed in much more detail below in the chapter
titled "The Script Manager".

Anatomy of a Script

Scripts and functions can be divided into three main sections. The first line
starts the script or function and is of the format of one of the following two
lines:

Script ScriptName ()
Function FunctionName ()

If the script is bound to a keystroke, its first line will look like the first line
above. If it is a function and, thus, is not bound to a keystroke, it will look
like the second line. Sometimes there is an additional word before the word
Function, but that will be covered later. (See Chapter 7.5.3.) In either case,
the second word in the line will be the script or function name. This can be
anything you want, but it is very helpful to make the name descriptive of what the
script or function does. If you use several words clumped together, capitalize the
first letter of each word so JAWS can pronounce it properly. Spaces are not
allowed in a script name. Some typical examples of script names are SayNextLine,
SayPriorCharacter, SayWindowTitle, and NextDocumentWindow. Note that it is very
easy to tell from these titles what the scripts are intended to do. Finally, there
will be a left and right parenthesis at the end of the line. Sometimes these
parentheses will contain some information, but that will be discussed later. (See
Chapter 7.5.2.)

Next comes the body of the script. This consists of all the instructions you add
during the script writing, such as variable declarations, comments, flow control
statements, function calls, PerformScript statements, and arithmetic operations.
You will learn what all of these types of instructions are as we proceed through
the manual. For immediate information on the most important of these, See Chapter
7.3.

Finally, the last line of the script will look like one of the next two lines:

EndScript
EndFunction

Obviously, the first line is used to end a script, and the second is used to end a
function. When you use the script creation dialog of the Script Manager, as
discussed below, a blank script will be created with the first and last lines
already present on the screen with several blank lines in between. All you have to
do is fill in the body of the script between these first and last lines.

Our First Scripts

Now let�s write a couple of small scripts. The first will have JAWS speak our name
on demand. We'll place it in the Notepad script file so that we can learn a little
about script writing without messing around in the very important default script
file. Follow these steps exactly and you will see that writing simple scripts is
not all that hard.

If you do not already have JAWS for Windows running, start it.
Open Notepad from the Start Menu/Programs/Accessories group.
Choose Script Manager by pressing INSERT+0 or by pressing INSERT+F2 followed by S
and ENTER. JAWS will tell you that you are in NOTEPAD.JSS, the script source file
for Notepad.
You will note that there are no scripts in this file. Notepad needs no scripts, so
opening the Script Manager from within Notepad started a brand new source file.
Choose New Script from the Script menu or use the accelerator key combination,
CTRL+E.
The New Script dialog appears so we can name our script and write its
documentation. For now, just follow the steps. We�ll cover naming and documenting
scripts in more detail later. (See Chapters 4.4 and 5.1.)
When the New Script dialog appears, the cursor is in the Script Name field. Type
in SayName. Be sure to capitalize both the S and N, and don�t put in a space.
Press TAB to move to the Can be attached to key checkbox, and press SPACEBAR to
check it. This is the step which tells the Script Manager that this is a script
and not a function. By checking this box, we make it possible to attach the script
to a key.
Press TAB to move to the Synopsis field, and type in the words, �Say our Name.�
Press TAB to move to the Description field, and type in the words, �The name of the
person who wrote this script.�
Press TAB to move to the Category field, and type in the word �Test.� The Category
field is an edit combo, so you can pick a category by typing one in or by arrowing
down through the list to find one that is appropriate.
Press TAB to move to the Assign To field, and press CTRL+SHIFT+N to assign this
keystroke to our script.
We won�t need any other fields filled in for our script, so press ENTER to close
the New Script dialog and insert our blank script into the editing area.
We are now back in the main text area of the Script Manager, and we have a blank
script where the first line says �Script SayName ()� and the last line says
�EndScript.� We have been placed between these two lines. Arrow up to the first
blank line after the first line, and you are ready to start writing the body of the
script.
We want JAWS to speak a string of characters, that is, our name. We can do this by
using one of JAWS built-in functions called SayString. Remember that JAWS� built-
in functions are functions that are hard-coded into JAWS to do particular jobs and
cannot be modified by the user. These are the basic building blocks we use to
create scripts. This one is designed to speak messages during script execution.
Note that there is no space in the function name. Computer functions are often
named by putting a couple of words together that describe the function. What we
then need to do is tell the SayString function what we want it to speak. In other
words, the SayString function tells JAWS we want it to say something, and then we
have to tell the function what words we want it to say. We have to pass some
information to the function for it to do its job. This information we are passing
to the function is called a parameter, and that�s one more piece of jargon for you
to remember. In this case, the parameter we want to pass is the string of letters
which comprises our name. Type your code line exactly as it appears on the next
line except that you should substitute your own name for the letters XXX:
SayString (�My name is XXX�)
You should now have the following three lines on your page exactly as they appear
below. Remember that close is not good enough as computers expect us to be precise
and perfect. Also, a few extra blank lines are not important. JAWS ignores blank
lines in scripts.
Script SayName()
SayString (�My name is XXX�)
EndScript
Now we need to save and compile the Notepad script file. Press CTRL+S and you
should hear, "Compile Complete." If not, go back and retrace the steps and try
again.
Close the Script Manager. This should place you back in Notepad. Test your work
by pressing CTRL+SHIFT+N. How about that! Your first script.
Switch to another application and try the same hot key combination. Note that this
time the script does not work. This is because we placed the script in the Notepad
script file, and that file was unloaded when we left Notepad. If we had placed the
script in the default file, it would have worked in any application unless that
application's script file also had a script assigned to the same hot key.

Let's switch back to Notepad and try something else. Press the INSERT+1 key
combination (using the 1 on the number row, not the keypad), and JAWS will say
"keyboard help on." This is the help mode you can use to explore the keyboard
without actually activating any of the keys. (You can leave the keyboard help mode
by pressing INSERT+1 a second time.) Now press your hot key again. Wow! This
time the hot key doesn't say your name, it says what the hot key does. Press the
hot key combination twice very quickly, and you'll hear even more detailed
information about what the hot key does. These pieces of information are the
synopsis and description fields you filled out while creating the script. Now you
can see why it is important to fill these fields out correctly.

For our next script, let's do something a little more practical. Open the WordPad
application from the Start Menu/Programs/Accessories group. Now drop down the file
menu by pressing ALT+F. Press the DOWN ARROW seven times, and you will land on a
line that speaks the name of the last file you opened in WordPad. (If you've never
opened any files in WordPad, do so now so you will have this line in your file
menu.) Wouldn't it be nice if we could read this line and know what the most
recently opened file was without using all of those keystrokes? Let's write a
script to do just that. As before, follow the steps as described below.

Open the Script Manager by pressing INSERT+0, or INSERT+F2 followed by S and ENTER.
As before, you should be placed in a blank script file named WORDPAD.JSS. Start a
new script by selecting New Script from the script menu or by pressing the CTRL+E
accelerator key combination.
You'll be placed in the Script Name field. Type in LastOpenedFile without any
spaces and capitalized as shown.
TAB to the Can Be Attached to Key check box and check it.
TAB to the Synopsis field and type in "Says last opened file." (Do not include the
quotation marks, they are only used here to show you what to type. This comment
applies to all quotation marks used to tell you what to type.)
TAB to the Description field and type in "Says the name of the last file opened in
WordPad."
TAB to the Category edit combo and arrow down until you reach the Say category.
Tab over to the Assign to Hot Key field and press CTRL+SHIFT+L to make this your
hot key.
TAB over to OK, and press ENTER.
We are now back in the main text area of the Script Manager, and we have a blank
script where the first line says �Script LastOpenedFile ()� and the last line says
�EndScript�. We have been placed between these two lines. Arrow up to the first
blank line after the first line, and you are ready to start writing the body of the
script.
This script is quite a bit more complicated than the last one. Shown below is the
completed script, including the first and last lines that were placed in the blank
source file by the Script Manager. Type the second through the next to last lines
into your blank script, and you should end up with something that looks just like
what is shown below

Script LastFile ()
SpeechOff ()
{Alt+F}
Pause ()
NextLine ()
NextLine ()
NextLine ()
NextLine ()
NextLine ()
NextLine ()
NextLine ()
SpeechOn ()
SayLine ()
SpeechOff ()
{escape}
{escape}
Pause ()
SpeechOn ()
EndScript

So, what in the world are all of these statements doing? Well, you may have noted
that when you pressed ALT+F in WordPad to open the file menu, JAWS said "menu
active, file, new, CTRL+N." We don't want to hear all that stuff during our script
execution, so the second line in the script, SpeechOff () turns off speech until
we're ready for it. Then the statement {ALT+F} sends the ALT+F command to WordPad,
just as if we'd typed it in from the keyboard. As you'll learn later (See Chapter
8.8.), we always place keystrokes we want to send to the application between left
and right curly brackets or braces. Then we have a pause statement that gives the
application a chance to drop down the menu before the script proceeds. This is
done a lot when asking applications to perform activities. Without this, our
script might get ahead of the application and do things before the application is
ready. Then we arrow down seven times with the seven NextLine statements. This
brings us to the line where the last opened file is listed. Before we can speak
this line, we must turn the synthesizer back on with the SpeechOn statement. Next
we have a SayLine statement which speaks the contents of the current line. That's
the actual function which gives us the data we want. Now we have to turn the
speech back off with the SpeechOff function so we don't hear all the stuff JAWS
normally speaks when exiting a menu. Now two Escape statements will get us out of
the menu. Note that here, again, these must be between curly brackets. Then we
have another Pause statement to allow the menu time to disappear, and finally we
finish by turning the speech back on with a final SpeechOn statement.

Now you should save and compile your script by pressing CTRL+S.
Return to WordPad, and press your new hot key, CTRL+SHIFT+L. You should be
rewarded by hearing JAWS speak the name of the last file you opened.

If you think this is great, just wait. You are just beginning to experience the
kinds of things you can do with this fabulous scripting language. No longer will
you be at the mercy of some dumb programmer who didn't follow normal rules and
write the application so it could be easily accessed with speech. No longer will
you be forced to execute a dozen keystrokes to get a piece of information off the
screen that your sighted friends can access just by glancing at the screen. No
longer will you have to wait for someone else to configure a new application for
you. It may take some work to learn this language, but you will be rewarded with
the capability of making your applications speak and behave much more like you
wish. Learn this stuff well, and you will be able to access your applications much
better and more efficiently than you would ever have imagined could be possible.

One more word of encouragement is necessary before getting to the real nitty gritty
of the scripting language. Sometimes it's daunting to see a completed script such
as the one above that works just the way it should. The new script writer looks at
such a script and says "How in the world did they figure out which statements to
use and the correct order to put them in?" It must be understood that scripts do
not pop out of thin air as a correctly and completely-finished product. The author
tried many different configurations of the above script before coming to the one
that worked best, the one shown above. The first version did not contain any
SpeechOff or SpeechOn statements, and the resulting script spoke much too much
information. So these statements were added. But several trials were necessary
before the best placement was found. Then the script still did not work correctly
until Pause statements were put in the right places, a process that required more
trial and error. The point is that you will have to make your best guess and try
something. If that doesn't work, try something else. As you gain more experience,
you will get it right more quickly. But the only way to learn this new language is
by the trial and error process which occurs as you make your scripting attempts.
Don't be afraid to try things. The worst that will happen is that the script won't
do what you want it to, and you'll have to try something else. You'll make
mistakes, but that's part of the process. The more experience you gain, the faster
and easier it will become. But if you don't try to write some scripts, you'll
never learn how to do it.

By now you should be getting a mental picture of why we need scripts , how JAWS
uses them to improve your efficiency, and how the default and application script
files work together. The next two chapters of Part 1 are titled �The Script
Manager� and "Creating Simple Scripts." These are followed by Part II, "Creating
Advanced Script Files." Anyone who is not thoroughly familiar with the Script
Manager and all of the tools it contains for creating and documenting scripts
should read the chapter describing the Script Manager. Then, if you want to learn
to create scripts to read textual information from the screen and to perform other
simple functions, continue with the �Creating Simple Scripts� chapter. Those who
want to learn to create advanced scripts that involve dealing with windows
structure, using programming constructs and manipulating JAWS settings and who
already understand how to write simple scripts should skip this chapter and
continue with Part II, "Creating Advanced Script Files."

Homework Assignment #1

Here is your first homework assignment and a chance to get a little more experience
in script writing. You probably noticed during the writing of the last script that
the file menu in WordPad doesn't just show the last file you opened, it shows the
last four files opened. Modify the preceding script so that it reads all four of
these files, not just the first one. One solution to the problem is shown in
Appendix A (See Chapter 0.), but don't look at it until you've had a good try at
making it work yourself.

The Script Manager

The use of the Script Manager, the script creation dialog, and the various other
tools for creating scripts and script files will be discussed in this section. As
briefly described earlier (See Chapter 2.2.), the Script Manager is more than just
a text editor. It provides the user with a suite of tools that make script and
script file creation much easier. We�ll divide the description of the Script
Manager into five parts. These are (1) the menus, (2) the various Script Manager
file types, (3) include statements, (4) the New Script and Script Information
dialogs, and (5) the Insert Function and Insert PerformScript dialogs.

The Menus

A detailed description of the Script Manager menu items can be found in Appendix B.

Script Manager File Types

We have already mentioned that there is more than one type of file which the Script
Manager can generate. Listed below are the five types of files associated with the
Script Manager and what each one is for.
JSS - As discussed above, this is the JAWS Script Source file which the user
creates to make application-specific script files.
JSB - This is the JAWS Script Binary file which is created by the Script Manager
when you save and compile a JSS file. This file is neither directly created nor
edited by the user.
JSM - This is the JAWS Script Message file and contains all of the spoken messages
used by script Say and SayMessage functions. When one creates advanced script
files that are to be distributed internationally, it is preferable to use message
numbers in the Say and SayMessage functions rather than place the actual text
there. This makes it easier to translate the messages into other languages. The
JSM file contains the statements which tell the script file what to speak for a
given message number. These message numbers are actually just constants that are
defined as being equal to the message you want spoken. If you look at the
structure of the DEFAULT.JSM file, you will see that the message numbers are
defined in exactly the same way as all other constants. For example, the default
JSM file, DEFAULT.JSM, contains statements like MSG1_L = �End� and MSG2_L = �home�.
You will note that the statements are placed one to a line and a comma is at the
end of every statement except the last one in the file. If a script in DEFAULT.JSS
encounters the line Say (MSG1_L, OT_JAWS_MESSAGE), it will say �end�, and if it
encounters the line Say (MSG2-L, OT_JAWS_MESSAGE), it will say �Home�. If you are
creating small script files for personal use, you may not wish to bother with JSM
files, but if you encounter message numbers in scripts written by others, you will
know to look in the associated JSM file to find out to what the message number
refers. A discussion of long (-L) and short (-S) messages and their utilization
for customized verbosity settings is presented later. (See Chapter 8.9.)
JSH - This is the JAWS Script Header file, and it contains other information
relevant to the associated JSS file such as definitions of constants and global
variables. We have already briefly discussed constants and variables and will be
talking about them more extensively below. Global variables are simply variables
that can be used by more than one script. It is necessary to tell JAWS what the
value of a constant is, or it will not know that information. Similarly, it is
necessary to tell JAWS that you will be using a certain variable with a certain
name, or JAWS will have no idea that this particular string of letters is to be
considered a variable. This process of telling JAWS about the constants and
variables we will be using is called declaration. If you just have a few constants
and global variables, you can place them directly into the top of the JSS file you
are creating. This procedure will be discussed more fully below. Regular or local
variables are always declared within the script itself. However, if you have large
numbers of constants and global variables, it is better to place them in a JSH
file. Examine the files HJGLOBAL.JSH and HJCONST.JSH for examples of files
containing global variables and constants.
JSD - This is the JAWS Script Documentation file and contains all of the
descriptive information about each script which you enter when you create a new
script by using the New Script Dialog. This information is entered into the JSD
file automatically when you create a script in this fashion. This file can be
edited manually if desired.

Include Statements

Let�s say you decide to use a JSM and/or JSH file as parts of a set of script files
you are writing for a new application. So you go ahead and create these files, but
then what? How does the main script file, the JSS file, know that these other
files exist and are part of the script set? Take a look near the top of
DEFAULT.JSS, and you will see statements like the following:

Include "hjglobal.jsh" ; default HJ global variables

Include "HJCONST.JSH" ; default HJ constants
Include "default.jsm" ; message file
These are called include statements, and their purpose is to tell the JSS file that
all of the information in the included files is part of the set. When you save the
JSS file and create the JSB file, all of the information in the included files will
also be compiled into the resulting JSB file. Thus, the scripts in the JSS file
will know about the definitions contained in the included files. The syntax for
these include statements should be followed exactly as shown. Note that the file
name includes the extension and is enclosed in quotation marks. Everything after
the semicolon is a comment and is simply there to provide the reader with
information. Everything following a semicolon on a given line is ignored by the
compiler. These comments are optional.

The New Script and Script Information Dialogs

The New Script dialog is found under the Script menu, and the Script Information
dialog is found under the View menu as the Documentation option. These two dialogs
are the same, except that the New Script dialog is displayed when one first creates
a script, and the Script Information dialog is displayed when one wishes to review
documentation for a script which already exists. The accelerator keys for these
two dialogs are CTRL+E AND CTRL+D, respectively. Most of the menu options in the
Script Manager have accelerator keys, and the user can easily become familiar with
the ones used frequently by examining the menus.

There are two tabs in these multi-page dialogs, the General tab and the Parameters
tab. Each of these is described below.

General Tab

The entries in the General tab are as follows:

Script Name - This is where you enter the name of your script or function. It is
helpful to use a name descriptive of what the script does. You may use several
words concatenated together. Start each word with a capital letter so JAWS will
pronounce the name as separate words. No spaces are allowed in the name.

Can Be Attached to Key - This is a checkbox. If you check it you will create a
script. If not, you will create a function. Remember that scripts are attached to
keys and functions are not.

Synopsis - This field should contain a brief statement of what the script does.
This is used if you enter the Keyboard help mode (INSERT+1) or Key Word help
(SHIFT+F1) in the Script Manager. The synopsis is accessed by pressing the key
combination you are interested in after turning on Keyboard Help.

Description - This field should contain a more detailed explanation of what the
script does. This description is used if you enter the Keyboard help mode
(INSERT+1) or Key Word help (SHIFT+F1) in the Script Manager. The description is
accessed by quickly pressing the key combination you are interested in twice after
turning on Keyboard Help.

Category - You can type in a category name or choose one from the combo box. This
Category field isn't currently used by any JAWS feature, but it may be implemented
in the future to allow sorting of your scripts by category.

Assign to Hot Key - This field is only available if you checked the �Can Be
Attached to Key� checkbox. Depress the key combination you wish to use for a hot
key to enter your choice. If the choice you make is already assigned to another
script, you will hear a warning message and be given the opportunity to continue
with the assignment or choose a different one.
Function Returns - This choice is only available if you did not check the �Can Be
Attached to Key� checkbox. The five choices are Handle, Int, Object, String, and
Void. Select one of the first four if your function is designed to return one of
these types of data to the calling script. Select Void if you don't need to use
any value returned by the function. Whichever one you choose will appear on the
first line of the script before the word Function. A more detailed discussion of
returns will be given later. (See Chapter 7.5.3.)

Return Description - This choice is only available if you did not check the �Can Be
Attached to Key� checkbox. This field should contain a brief description of what
information is being returned by the function and how the information is meant to
be used.

Parameters Tab

This tab contains information about parameters used by the function, if any. A
parameter is data that the function needs to have in order to do its job. As with
variables, the data can be in the form of an integer, string, handle, or object.
This tab is never used if you are creating a script rather than a function. It is
also not used if the function needs no parameters. Entries for this tab are as
follows:

Existing Parameters - This listbox will show already existing parameters, if any.
It will also show parameters as you add them. You can arrow up and down to select
a parameter for subsequent deletion.

New Parameter - If you wish to add a parameter, type its name in this field.

By Reference -To understand this item, you must understand that parameters are used
to transfer data from the calling script to the function. Normally, this data
transfer is a one way street. This default situation is known as passing the
parameter "by value." Thus, when you call the function from the script, the
current value of the parameter as it exists in the script will be copied and sent
to the function. During the execution of the function, it is possible for the
value of the parameter to change. Since the parameter information exchange is
normally a one way street when the data is passed by value, the script will not be
aware that the parameter's value has changed. When the function is done and
returns control to the script, the script will continue on with its original value
for the parameter. Checking the By Reference checkbox will change the one way
street into a two way street. If this checkbox has been checked, changes in the
value of the parameter that occur during the execution of the function will be
known by the calling script. This makes it possible to change a parameter's value
within a function and then have the script use that changed value. This is because
passing by reference passes the data's memory address rather than the value to the
function. If the function changes the value at this address, the calling script or
function, which uses the data at the same address, will use the changed value.

Description - This field should contain a very brief description of what the
parameter is for.

Available Types - You should choose either Handle, Int, Object, or String from this
listbox, depending on which type of information this parameter is meant to pass.
As will be discussed later, handle refers to a window handle. (See Chapter 6.)

Add - This button will be available if you have filled in the preceding fields.
Use the SPACEBAR or ENTER key to add your new parameter to the Existing Parameters
listbox.
Remove - This button will be available if you have highlighted an entry in the
Existing Parameters listbox. Choosing this button with the SPACEBAR or ENTER key
will delete the highlighted parameter from the list.

The Insert Function and Insert PerformScript Dialogs

Under the Script menu, there are two selections, Insert Function Call and Insert
PerformScript. These are used to insert functions and to call other scripts from
within a script. The use of these two tools is described below.

Insert Function Call - This brings up the Insert Function dialog, which is a list
of over two hundred functions which you can use in your script construction. You
will hear the title �Insert Function 1.� The term Function 1 means you are at the
first level of this dialog. The first field in this dialog is an edit box. The
next tab is an alphabetical list of all the available functions. If you happen to
know the name of your function, you can start typing it in the edit box, and the
highlight in the alphabetical list will automatically move to the function whose
name starts with the same letters you�ve just typed in. You will also notice that
a description of the highlighted function is read to you each time you press
another keystroke. As soon as you�ve typed in enough letters to hear the name of
the function you are searching for, just press ENTER to select that function. If
you don�t remember the exact name of the function, just type in enough of the name
to get you to the right part of the list, then TAB over to the list, and arrow up
and down until you find the function you want. You can also type in function names
while you are in the list, and the Script Manager will move to the function with
the correct name. You will also hear function descriptions as you arrow up or down
in the list. When you hit the ENTER key to select a function, one of two things
will happen. If this function does not require any parameters, you will be
returned to the main Script Manager editing window, and you will see that the
function has been added to your script. However, if the function does require one
or more parameters, another dialog containing an edit field will pop up asking you
to insert the parameter. For example, if you choose SpellString as a function, you
will be placed in an edit field where you can insert the text or message you wish
spelled. This is the parameter required by the SpellString function. If the
function you have chosen requires you to choose another function as the parameter,
you can hit the key combination ALT+I, and a new dialog will open which looks very
much like the Insert Function Dialog. You will hear the title �Insert Function 2�.
The only difference is that the only functions that show up in this list are the
ones the Script Manager thinks are appropriate choices for this parameter.
Therefore, not all of the functions of the main list will appear in this sub list.
You must either choose a function from this list or type the function name directly
into the parameter edit field when it first appears. Then hit Enter. Continue
with this process until all of the required parameters have been entered.
Sometimes you will even have to go to a third or higher level, i.e., �Insert
Function 3�, �Insert Function 4�, etc. by hitting ALT+I again. (This process of
using functions as the parameters for other functions is called "nesting", and it
will be discussed more fully later in the section titled "Using Nested Functions."
See Chapter 8.6.2.) The Script Manager will then return you to the main editing
window, and your function with all of its parameters will be present in the script.
While you are in the Insert Function dialog, you can also TAB over to the
Description and Returns fields to examine information about the function
description and return information, if any, in more detail.

It is also worth noting that the function list in this dialog contains both the
hard coded functions built into JAWS and the functions that have been defined by
any users in the current script file. Thus, if you define a new function for the
script file, you will see it appear in the function list after you compile.

Insert PerformScript - When you select this option, you will be placed in a list
box containing all of the available scripts you can call from the present script
you are writing. You can arrow through this list or start typing the name of the
script to jump to it. Pressing ENTER on one of the names, for example, a script
called �SayMyName,� will cause the line shown below to appear in your script.

PerformScript SayMyName()

This line will cause the script �SayMyName� to be executed, just as if you had hit
the keystroke yourself. This is a way to reuse scripts you have already written
without reproducing the code all over again.

Creating Simple Scripts

An example of a simple script is one in which you might wish to read some text
located somewhere on the screen with a single keystroke. One way to do this would
be to select a cursor, move it to the specific point on the screen where the text
is, and then read the text. In this section, we'll go over how to create scripts
by putting together functions that do those sorts of things.

Script Documentation

Each script has associated documentation. As discussed above, you enter this
documentation as you create a new script. Simple scripts are always assigned to
keys and require only five pieces of documentation. The following is a description
of each field that is required for a simple script.

Script Name - Enter the name for your script.

Can be attached to Key checkbox - Always check this box for key-bound scripts.
Synopsis - Provide a brief description of your script�s purpose.
Description - Provide additional information about your script.
Category - Choose a category for your script. You assign the category names either
by typing them in or choosing them from the edit combo list. Try to choose
meaningful ones so that you can list them by logical category later, in the event
that this capability is added to the Script Manager.

Individual Script Structure

Remember that a script file is made up of one or more scripts. As discussed above,
a script must have the following pieces in this exact order:

First is the script begin keyword. This is simply the word "Script" followed by a
space.
On the same line following the word "Script" is the script name. This is usually
several words concatenated together that describe the action of this script, such
as, CloseDocumentWindow. Note that each of the concatenated words is initial
capped, so JAWS can read the name correctly. () follows the name to complete the
script begin statement. All of this is automatically entered by the Script Manager
when you create a script using the New Script Dialog. (If you find that your copy
of JAWS is not pronouncing concatenated words like this properly, check the Mixed
Case Processing option of the Text Processing section of the Set Options menu in
the Configuration Manager. This checkbox should be checked.)
Next comes the body of the script. This consists of all the instructions you add
during the script writing, such as variable declarations, flow control statements,
function calls, PerformScript statements, arithmetic operations, and comments.
(You will learn what all of these types of instructions are as we proceed through
the manual.) This could be as simple as just saying a string as we did in �Our
First Script� or many functions to perform a complex operation.
The script end keyword , EndScript, is always the last line of a script. This is
automatically entered by the Script Manager when you create a script.
Using Script Functions

Now, let's go over some of the commonly used functions for moving around on the
screen and reading text.

Reading Text

Below are some functions used to read text from the screen.

SayCharacter() - Reads the character at the position of the active cursor.

SayWord() - Reads the word at the position of the active cursor.
SayLine() - Reads the line at the active cursor.
SayToCursor - Reads from the beginning of the line up to the active cursor.
SayFromCursor - Reads from the active cursor to the end of the line.
SayColor - Says the font color at the active cursor.
SayFont - Says the font style and point size at the active cursor.
SayTextBetween - Speaks all text between two column coordinates on the line of the
active cursor.
SayWindow - Reads the window located at the active cursor.
SayToBottom - Reads all text from the position of the active cursor to the bottom
of the window.
SayString - Speaks string data, usually either the contents of a string variable or
a specific message. If actual text is used, it should be placed inside of
quotation marks within the parentheses that follow the function name. If a
variable or constant is used, no quotation marks should be present. It is now
recommended that the SayString function be avoided in favor of the SayMessage
function (see below).
Say - This function speaks a string of text, much like the SayString function, but
it has a second parameter called an output mode. These output modes allow the
message to be spoken with a particular set of speech characteristics. It is
possible to use separate output modes to speak title lines, dialog controls, menu
items, etc, with different voices or at different verbosity levels. By using the
SayMessage function instead, it is possible to assign short and long messages to
many output types for JAWS Help and other information.
SayMessage - This function takes short and long messages supplied as parameters and
speaks the appropriate message based on the specified output type, also supplied as
a parameter. This function is similar to Say, except that it is possible to assign
short and long messages to many output types for JAWS Help and other information.
It is now recommended that the SayMessage function be used in preference to the
SayString function.
SayAll - Says all readable information from the point of the active cursor to the
bottom of the window. If the PC cursor is active, JAWS scrolls the screen by
moving the PC cursor down. If the JAWS cursor is active, the rest of the window is
read by moving the JAWS cursor down a line at a time.
SayCharacterPhonetic - Uses special pronunciation rules to read the character
located at the position of the active cursor. Thus, A is pronounced alpha, B
bravo, etc. The associations between characters and their phonetic pronunciations
are made in the [PhoneticSpell] section of .JCF files. Which words are used can be
changed by the user, if desired.
SayControlInformation - Handles the speaking of controls for which
SayWindowTypeAndText and related functions do not sufficiently describe the
control. This function is designed to speak a control that requires custom
processing (any control for which SayWindowTypeAndText do not properly speak the
name and type of the control). This function is designed to honor the user's
output mode settings for each component of the control's description. This
function takes six parameters, five of which are string parameters. The first
parameter is the window handle of the control that is to be spoken. The next five
parameters include one parameter for each component of a control's description.
Each string parameter has a corresponding Output Mode. The 5 string parameters are
String strControlName = Either OT_DIALOG_NAME, OT_DOCUMENT_NAME, or
OT_CONTROL_NAME, depending on the type of window that is to be spoken, String
strControlType = OT_CONTROL_TYPE, String strControlState = OT_ITEM_STATE, String
strContainerName = OT_CONTROL_GROUP_NAME, and String strContainerType =
OT_CONTROL_TYPE. This function works by building a string based upon the five
components of the control description, adding each component only if the user has
specified that this item should speak in the current verbosity level. Then this
function calls the Say function with the constructed string as the first parameter
and OT_NO_DISABLE as the second parameter.
TsayFocusRect - Says the contents of a focus rectangle. Returns TRUE if any text
was spoken, FALSE otherwise. A TrackFocusRect=1 statement should be added to the
[OSM] section of the application's JCF file for this function to work properly.
SayFocusRects - Says the contents of focus rectangles. If there is only one such
rectangle, this is exactly like SayFocusRect. If there is more than one, this
function says the contents of all of them, while SayFocusRect says only the first
one. A TrackFocusRect=1 statement should be added to the [OSM] section of the
application's JCF file for this function to work properly.
SayChunk - Speaks the chunk of information to which the active cursor is pointing.
A "chunk" is text and graphic information that was written to the screen in a
single operation. SayChunk is similar to SayField, however, the SayField function
uses logic to determine the text that is to be spoken, while SayChunk simply reads
the text that was stored in the Off Screen Model as a single unit.
SayField - Reads the field of text where the active cursor is pointing. A "field
of text" is a section or block of text that has a common attribute, i.e., bold,
underlined, italics, or strikeout. The use of the attribute must be contiguous.
The SayField function uses logic to determine the text that is to be spoken, while
the SayChunk function simply reads the text that was stored in the JAWS Off Screen
Model as a single unit.
SayFrame - Speaks the contents of the specified frame.
SayFrameAtCursor - All text within the boundaries of the frame that contains the
active cursor is spoken.
SayInteger - Speaks numeric, integer data, often the contents of an integer
variable.
SayParagraph - Reads the current paragraph from the beginning
SaySentence - Reads the sentence containing the character on which the active
cursor is positioned.
SayUsingVoice - Speaks a string of text using a specific set of speech
characteristics called voice context.
SayCell - When in a table or spreadsheet, speaks the contents of the current cell.
SayColumnHeader - When in a table or spreadsheet, speaks the contents of the column
header.
SayRowHeader - When in a table or spreadsheet, speaks the contents of the row
header.

Moving Around on the Screen

Before you attempt to read something from the screen with a script, you'll probably
have to move one of the cursors to the location of the item you wish to read.
Therefore, it's important to understand something about cursors. For those using
JAWS without a Braille display, there are four kinds of cursors, the PC cursor, the
JAWS cursor, the Invisible cursor, and the Virtual PC cursor. Those using a
Braille display will have a fifth cursor, the Braille cursor. (This cursor is only
used internally by the Braille scripts and should never be left on after a script
completes its work.) If you are editing or entering text, the PC cursor is where
characters would be placed when you type. (This editing or text insertion form of
the PC cursor is also called a caret.) However, when you are using a menu or
tabbing through some selections such as buttons in a dialog box, there is no caret
on the screen. In these situations, the PC cursor is the focus. If you wish to
read other areas of a window or read a part of the screen where the PC cursor
cannot go, you can switch to the JAWS cursor. The JAWS cursor can be moved
anywhere within the boundaries of the current real window, making it possible to
explore areas of the screen where the PC cursor cannot go. A real window is
defined as a window that has a title. This means that your JAWS cursor is normally
only restricted to movement within the boundaries of the highest level parent
window with a title, starting from the window you are in currently. This is what
we mean when we say the JAWS cursor is restricted by the boundaries of the current
real window. (If you wish to restrict the JAWS cursor to the window you are
currently in, even if it is not a real window, you can do so by using the keystroke
combination, INSERT+R.) Since the JAWS cursor always moves the mouse pointer to
its location, the mouse pointer is always positioned and ready to be clicked at the
location of the JAWS cursor should you decide to do so. The third kind of cursor
is called the Invisible cursor. In one way it is just like the JAWS cursor as its
movement is also only restricted by the boundaries of the real window, but it has
no visible entity on the screen since it does not bring the mouse pointer with it.
The Virtual PC cursor is a special case of the PC cursor which is turned on
automatically in certain applications such as Internet Explorer 5, Outlook/Outlook
Express, and Eudora 4.X where a Microsoft browser or browser style viewer is being
used. The Virtual PC cursor is created within a special JAWS buffer and is
employed to allow the user to have a cursor that can navigate around the viewer
window even though that viewer does not actually have a normal PC or caret. The
user is actually navigating in the virtual buffer created by JAWS and feels as if
navigation were occurring within a word processor type of application. This makes
reading in such applications much easier.

How do we use these cursors? It�s generally impractical and often impossible to go
exploring around the screen with the PC cursor. Therefore, before we go to read
some text from the window, we usually first switch to one of the other two cursors.
One can pretty much use either the JAWS or the Invisible cursor to do the reading
for you, so to some extent it�s just a matter of choice. However, there are some
situations where you will definitely want to use one of these two cursors in
preference to the other. If you plan to click a button or take some other action
with the mouse, it will be necessary to use the JAWS cursor. Since the mouse
pointer accompanies the JAWS cursor in its travels, it is then a simple matter to
click the mouse as it�s already in the correct position. If you do not wish to
move the JAWS cursor from its current position, or there won�t be any need to click
on anything, the Invisible cursor is the best choice. There is one particular
situation which comes to mind when you definitely won't want to move the JAWS
cursor. Sometimes in Windows, information text will appear somewhere on the
screen, usually the status line, when the mouse pointer is at a particular
location. If you move the JAWS cursor to read the text, the mouse pointer will
move with it, and the text will disappear. In this situation, you must use the
Invisible cursor to read such text. In general, it's a good idea to use the
Invisible cursor to read text when no clicking is necessary, unless there is a
particular reason to use the JAWS cursor.

In some cases, it is necessary to move one of the cursors such as the JAWS cursor,
even though you want it to be back in its original location when the script is
finished. For this reason, there are the SaveCursor and RestoreCursor functions
that you can use to put everything back as it was before your script was executed.

Here is a list of the functions that you can use to select and manipulate the
cursors.

PCCursor() - Activates the PC Cursor.

JAWSCursor() - Activates the JAWS Cursor.
InvisibleCursor() - Activates the Invisible Cursor.
BrailleCursor () - Activates the Braille cursor.
RouteBrailleToPc () - Moves the Braille cursor to the PC cursor.
RouteBrailleToJAWS () - Moves the Braille cursor to the JAWS cursor.
RouteJAWSToBraille () - Moves the JAWS cursor to the Braille cursor.
RoutePCToBraille () - Moves the PC cursor to the Braille cursor, if possible.
RoutePCToJAWS() - Moves the PC Cursor to the JAWS Cursor, if possible.
RouteJAWSToPC() - Moves the JAWS Cursor to the PC Cursor.
RouteJAWSToInvisible() - Moves the JAWS Cursor to the Invisible Cursor.
RouteInvisibleToPC() - Moves the Invisible Cursor to the PC Cursor.
RouteInvisibleToJAWS() - Moves the Invisible Cursor to the JAWS Cursor.
SaveCursor() - Saves the active cursor and its position.
RestoreCursor() - Reactivates the saved cursor and restores it to its original
position.

The next group of functions is used to move the cursor.

PriorCharacter() - Moves the active cursor to the prior character.

PriorWord() - Moves the active cursor to the prior word.
PriorLine() - Moves the active cursor to the prior line.
NextCharacter() - Moves the active cursor to the next character.
NextWord() - Moves the active cursor to the next word.
NextLine() - Moves the active cursor to the next line.
NextParagraph - Moves the active cursor to the beginning of the next paragraph. If
the PC cursor is active, and the next paragraph is not already visible, then text
in the window will automatically scroll to bring it into view.
NextSentence - Moves the active cursor to the beginning of the next sentence. If
the PC cursor is active, and the next sentence is not already visible, then text in
the window will automatically scroll to bring it into view.
PriorParagraph - Moves the active cursor to the beginning of the prior paragraph.
If the PC cursor is active, and the prior paragraph is not already visible, then
text in the window will automatically scroll to bring it into view.
PriorSentence - Moves the active cursor to the beginning of the prior sentence. If
the PC cursor is active, and the prior sentence is not already visible, then text
in the window will automatically scroll to bring it into view.
JAWSHome() - Moves the active cursor to the beginning of the line.
JAWSEnd() - Moves the active cursor to the end of the line.
JAWSPageUp() - Moves the active cursor to the top of the window.
JAWSPageDown() - Moves the active cursor to the bottom of the window.
MoveTo - Moves the JAWS or Invisible cursor to the screen coordinates specified by
the user.
MoveToControl - moves the active cursor to a specific control within a window. If
the PC cursor is on when this function is called, the JAWS cursor is turned on
automatically. Otherwise the active cursor is used.
MoveToFrame - Moves the active cursor to the top left corner of the specified
Frame. If the PC cursor is active when this function is used, then the JAWS cursor
is activated and it is moved to the new position, otherwise the active cursor is
moved.
MoveToGraphic - Moves the JAWS cursor, Invisible cursor, or Braille cursor in a
specific direction to find a graphic symbol in the active window.
MoveToWindow - Moves the active cursor to the specified window. If the window
contains text, then the cursor is positioned on the first character. Otherwise, it
is positioned at the window's center. If the PC cursor is active when this
function is used, then the JAWS cursor is activated and it is moved to the new
position.
PriorChunk - Moves the active cursor to the prior chunk of text. A chunk of text
is a section or block of text that is written to the screen at one time
NextChunk - Moves the active cursor to the next chunk of text. A chunk of text is
a section or block of text that is written to the screen at one time
DownCell - When inside a table or spreadsheet, moves the active cursor to the cell
in the same column but the next Row.
UpCell - When inside a table or spreadsheet, moves the active cursor to the cell in
the same column but the previous Row.
PriorCell - When inside a table or spreadsheet, moves the active cursor to the cell
in the same row but the previous column.
NextCell - When inside a table or spreadsheet, moves the active cursor to the cell
in the same row but the next column.

Note that If your purpose is to read something located on the screen, you would
usually follow a move function with one of the say functions. An example of this
is shown below.

JAWSPageDown () ;moves to the bottom of the window

SayLine () ;reads the line moved to

Creating Reading Scripts

Now, let's look at a practical use of what we have learned so far. Before we look
at a real script, here are the steps again:

First, save the status of your current cursor, if necessary. Then activate the
cursor of your choice.
Now move the active cursor to a specific position in the window.
Select the appropriate reading function.
Restore your original cursor if you used the SaveCursor function at the start of
the script.

The following are two variations of a script which can be used to read the bottom
line of a window. There is a comment at the end of each line that describes the
function. (We previously mentioned comments briefly in the section on include
statements, and will discuss them more fully below.) In the first script we will
switch to the JAWS cursor, read the bottom line and then leave the JAWS cursor
active at the bottom of the window.

Script ReadBottomLine() ; Begins the script and assigns it the name, ReadBottomLine
JAWSCursor(); Activate the JAWS cursor
RouteJAWSToPC() ; Move the JAWS cursor to the PC cursor to assure it is in the
window we're working
;in and not in some other window elsewhere on the screen.
JAWSPageDown() ; Move the JAWS cursor to the bottom of the window
JAWSHome() ; Move the JAWS cursor to the beginning of the bottom line
SayLine() ; Speak the bottom line of the window
EndScript ; End of the script

The next variation adds the save and restore cursor functions and uses the
Invisible cursor. This script will read the status line and then restore the
original cursor.

Script ReadBottomLine() ; Begins the script and assigns it the name, ReadBottomLine
SaveCursor() ; Saves the current cursor and its position
InvisibleCursor() ; Activates the Invisible cursor
RouteInvisibleToPC() ; Move the Invisible cursor to the PC cursor so it is in the
correct window.
JAWSPageDown() ; Move the Invisible cursor to the bottom of the window
JAWSHome() ; Move the Invisible cursor to the beginning of the bottom line
SayLine() ; Speak the bottom line of the window
RestoreCursor() ; Reset the cursor and position we saved
EndScript ; End of the script

See how it works? You could use this script to read the status line in Microsoft
Word. The status line tells you the page number, line number, column number and
other information like that. If you only wanted the page number, you would
substitute a SayWord() function followed by a NextWord () and another SayWord ()
for the SayLine() function. Then you would just hear the words: page and the
number.

There is an important subtlety about the SaveCursor and RestoreCursor functions

which needs to be understood. These functions save and then restore the cursor
type of whatever cursor is active when the SaveCursor function is used. In
addition, if the JAWS or Invisible cursor is the active cursor when the SaveCursor
function is used, the cursor position is also saved and then restored by the
RestoreCursor function. Cursors which are activated and moved after the SaveCursor
function is used will not be restored to their original types or positions. Thus,
in the above example, the position of the Invisible cursor would not be restored
unless it happened to be the active cursor at the time the SaveCursor function is
called. However, it is possible to use multiple SaveCursor and RestoreCursor
statements in one script. These statements will "stack" in very much the same way
that the default and application scripts stack. This means that, if you were to
use a second SaveCursor statement, and you were to have a different cursor active
than you did when you used the first SaveCursor statement, it is the position of
the second active cursor which would be saved when the second SaveCursor is
executed. Furthermore, the RestoreCursor statements will undo the SaveCursor
statements in the reverse order. Thus, if you perform two SaveCursor statements
and then perform a RestoreCursor, it is the second SaveCursor that will be
reversed. To undo the first SaveCursor, you would have to perform a second
RestoreCursor. The following example illustrates the stacking of SaveCursor
function calls:

Script ReadBottomLine () ; Begins the script and assigns it the name,

ReadBottomLine
SaveCursor () ; We don�t know what cursor was active, but Saves the current cursor
and its position
InvisibleCursor () ; Activates the invisible cursor
SaveCursor () ; Saves the invisible cursor and its position
RouteInvisibleToPC () ; Move the Invisible cursor to the PC cursor so it is in the
correct window.
JAWSPageDown () ; Move the invisible cursor to the bottom of the window
JAWSHome () ; Move the invisible cursor to the beginning of the bottom line
SayLine () ; Speak the bottom line of the window
RestoreCursor () ; Reset the invisible cursor and position we saved
RestoreCursor () ; Reset the users original cursor and position we saved
EndScript ; End of the script

Finally, if you use a SaveCursor ()in a script, JAWS automatically does a

RestoreCursor () at the end of the script, even if you forget to put one in. JAWS
assumes that you want to restore the cursor if you've put a SaveCursor () in the
script. If you've used multiple SaveCursor statements, JAWS will automatically
undo all of them in reverse order when the script is finished, even if you don't
remember to put in all of the RestoreCursor statements.

Putting It All Together

Now let's look at the process of creating a script, assigning it to a key, and
compiling the script file so we can use it. Here's the plan. We will create a
script for the Script Manager that reads the current line number. We'll need the
Script Manager for this task. Remember that we used this editor in an earlier
section (See Chapter 3.)when we created our first scripts. This time, we'll let
the Script Manager do more of the work for us. Follow these steps exactly:
Start the Script Manager by selecting it from the JAWS Utilities menu.
Press INSERT+Q to verify the Script Manager settings are loaded into the stack
above the default script file and that the program name for the script editor is
JSCRIPT.EXE. This means, of course, that the script file currently controlling
JAWS is JSCRIPT.JSS. To load this file so you can edit it, drop down the file menu
with ALT+F and arrow down to Open and press ENTER. Type in the file name,
JSCRIPT.JSS, and press ENTER. Finally, press CTRL+END to take the caret to the
bottom of the script file, the best place to add a new script.
Before we actually write our script, let's explore the window to see what we want
our script to read. Script Manager has a status line at the bottom that contains a
help message, the current line number and the total number of lines in the file.
We want to read only the current line number with our script. Just to make sure we
know what we want our script to do, let's do it manually first.
Start by activating the JAWS cursor.
Then press PAGE DOWN to move to the bottom line followed by HOME to move to the
beginning of the bottom line.
Now use INSERT+NUM PAD 5 to say the current word and you should hear the word
"For." Use the next word key (INSERT+NUM PAD 6) to read across the line. You now
know that the fifth word on this line is the current line number. We now know what
our script has to do. It must activate a cursor, position it at the proper place,
and then read the word. OK, reactivate the PC cursor and we'll get started.
Select New Script from the Script menu, and the New Script dialog will appear. Now
we have to name our script and write its documentation.
When the New Script dialog appears, the cursor is in the Script Name field. Type
in SayLineNumber. Be sure to cap the S, L, and N and don�t put in any spaces.
Press TAB to move to the Can be attached to key checkbox and press SPACEBAR to
check it. We want to attach our script to a keystroke later.
Press TAB to move to the Synopsis field and type, �Read current line number.�
Press TAB to move to the Description field and type, �The line that contains the PC
cursor.�
Press TAB to move to the Category field and type, "Say," because this script will
say something.
Press TAB to move to the Assign To field and press CTRL+SHIFT+L to assign this
keystroke to SayLineNumber.
We won�t need any other fields filled in for our script, so press ENTER to close
the New Script dialog and insert our blank script into the editing area.
We now have a script begin statement with the script name and an EndScript
statement. There are a few blank lines in between for us to put in our script
statements and the cursor is positioned on one of the blank lines. Use the UP
ARROW key until you reach the first blank line of the script.
This time we will not type our functions as we did when creating our first script.
We will use the Insert Function dialog of the Script Manager.
Choose Insert Function Call from the Script menu, or use the hot key combination,
CTRL+I. The Insert Function dialog box appears and the cursor is placed in the
function name edit field. There is also a list of functions displayed beneath the
function name field. You could tab down to the list and start arrowing through the
functions to find the one you need, but that would not be very efficient as there
are more than two hundred of them. JAWS has a better way, but it does require that
you have some idea of the function name.
Just like in our example earlier, we need to start with saving the cursor and
position. The function is SaveCursor(), but we only need to press the S as the
Insert Function tool starts searching as soon as you start typing. SaveCursor() is
the first function that starts with an S. Notice that as focus moved to
SaveCursor(), a help message was read that explained how this function is used.
Press enter and this function is placed into our script. Easy isn't it? Now let's
activate the Invisible cursor. We use the Invisible cursor here as we just want to
read the line number and return. No sense in dragging the mouse with us, so we
won't use the JAWS cursor.
Press ENTER to insert a new line and then press CTRL + I again.
The function we need this time is InvisibleCursor(). We'll have to type two
characters this time as InvisibleCursor() is not the first function that begins
with an I. Type slowly so that you can hear each function as it is highlighted.
Once you hear InvisibleCursor(), press ENTER to place it in our script.
Use the same procedure to add the rest of our functions in this order:
RouteInvisibleToPC (), JAWSPageDown(), JAWSHome(), NextWord() five times, SayWord()
and RestoreCursor().
Press CTRL + S to compile the script file. If you made no mistakes, you should
hear the "compile complete" message. If not, repeat the previous steps until you
can compile without an error. If you do get an error, the Script Manager will
position the caret near where it thinks the error is so you will have a better
chance of finding it.
Now test your work by pressing CTRL+SHIFT+L to hear the current line number.

Try a few variations like reading the whole line instead of the word. Then add a
message that says "line number" before it actually speaks the number. When you
feel comfortable with this process, either continue with the next part, "Creating
Advanced Script Files, or jump in and write some scripts you been wanting for some
time.

Homework Assignment #2

Here is your second homework assignment. As you probably know, most windows have
three states, minimized, restored, and maximized. In the upper right hand corner
of most windows, there are three buttons. The first is minimize, and the last is
close. The middle one can either be restore or maximize, depending on the current
window state. By moving to and reading the middle button, you can determine the
window state. If it says "restore symbol", then the window is maximized. If it
says "maximize symbol", then the window is restored. Your assignment is to add a
script to the default script file, DEFAULT.JSS, which will read this button.
Obviously, to test your script properly, make sure you are in a window that has
these buttons. The Script Manager window will serve quite nicely. After you have
written this script, you will be able to determine the state of the current window
with one keystroke. For this assignment, we want you to use the JAWS cursor to do
the reading, and you should make sure that the JAWS cursor is returned to its
original position by the time the script ends. Assume that the PC cursor is active
when you start the script, and make sure it is active when the script is done. You
can load the default script file by choosing the Script Manager from the JAWS
window Utility menu and then loading DEFAULT.JSS. An alternative way of doing this
is to press CTRL+SHIFT+0 on the number row. This will automatically open the
Script Manager and load the DEFAULT.JSS file. Add your script to the bottom of
this file. One possible answer can be seen in Appendix A (See Chapter 14.1.), but
don't look at it until you've had a try at writing this script.

Extra credit - If you're really feeling adventuresome, try modifying the above
script to be a little more sophisticated. Instead of just reading the Maximize or
Restore symbols, use If-Then, ElIf, Else, GetWord, and Say functions to decide what
the state of the window is and what message to speak. If the window is showing a
Restore symbol, have the script say "Maximized." If a Maximize symbol is showing,
have the script say "Restored." If it doesn't find either of these two symbols,
have it say "Couldn't find the symbol." Hint - a labeled graphic such as a Restore
or Maximize symbol can be treated as text, and its label can be read and
manipulated with the same functions that are used for pure text. One possible
answer to this problem is also in Appendix A. (See Chapter 14.1.)

Homework Assignment #3

And just for fun, here is your third homework assignment. Windows comes with a
sound recording program called Sound Recorder. This program can usually be found
in the Multimedia folder of the Accessories folder of the Start Menu. Open it, and
explore around the Sound Recorder window with your JAWS cursor if you are not
familiar with this program. You will find that there are several buttons for play,
stop, record, etc. You will also find that the fourth line from the top has a
counter which tells you how many seconds have played and how many seconds long the
file is. Load any file on your computer with a .WAV extension using the Open
Dialog of the File menu. (You can find many .WAV files in the C:\WINDOWS\MEDIA
folder.) Click the play button to start playing the file, then click the stop
button before the file finishes playing. (If you prefer to use the keyboard to do
this, the hot keys for these two functions are CTRL+P and CTRL+S, respectively.)
If you look at the elapsed time counter again, you will see that there are now
numbers indicating how much time is elapsed out of the total time. We want you to
write a script for this application's JSS file (SNDREC32.JSS) which will read this
counter for you with one keystroke. The announcement should be in the form
"Current time is X seconds out of Y seconds". The X and Y values are to be
obtained from the Sound Recorder display, and the rest of the announcement should
be created from Say statements. Use the Invisible cursor to do the reading, and
return the starting cursor to the original state when done. One possible solution
to this problem is shown in Appendix A. (See Chapter 14.2.)
Part II: Creating Advanced Script Files

Windows Program Structure

You've probably heard people use terms like window class and window handle in
discussions about how Windows programs are structured. What do terms like this
mean? In this section, we'll explain window hierarchy, identification, and
structure so you can make use of the script functions that query and compare these
items.

The first question is what is a window? Well, that would seem to be simple.
Programs run inside of windows. Even JAWS has a window. That�s true. The JAWS
window is a window, but it might surprise you to know that every entry field,
button, and other control is also a window. At least it should be. Like all other
rules in computer programs, it is not always followed. A programmer may choose to
create controls, such as entry fields, without making them actual windows.
Programs like this are the most difficult to make accessible because there's no
simple way to identify and speak the various controls. These programs need script
writing even more because the scripts in the default files will not speak these
windows properly. For the moment, we'll assume that the programmer assigns each
control to a window. Sounds complicated doesn�t it? Let's see if we can sort it
out.

Hierarchy

Most people who operate in the Windows environment never really understand what the
word "window" truly means with respect to this environment. Of course they realize
that the big rectangular thing that pops up on the screen when they open a new
application is a window, and they probably also think of the text area of their
word processor as a window, but there is much more to it than that. In most
applications, every dialog box, menu, button, edit field, listbox, etc., is
actually a separate window with one or more identification numbers that can be used
to refer to it. These scores of windows that may be present on your screen at any
one time are not randomly dropped there, they are interrelated with a special
hierarchy that allows the Windows operating system and the programmers who work
within it to keep track of them all. It will all make more sense if we look at the
hierarchy of windows in the system. The metaphor most often used is one of parents
and children. Here�s how it works. Your computer desktop is the parent of all
application windows. That makes the JAWS Window, your word processor�s window and
the Internet browser�s window all children of the desktop. These windows are all
one level down from the desktop, so they are all children of the desktop at the
same logical level. This makes them all peers of each other, and, when you later
encounter terms such as PriorWindow and NextWindow, the reference is to moving
among peer windows at the same level. OK, now let�s go to the next level. The
word processor has several child windows: the text area, the menu bar, the toolbar
and the status line. These are all children of the word processor window and are,
themselves, all children at the same logical level. Are you beginning to get it?
When you ask to open a file in the word processor, a child window appears so that
you can look for the file. It�s often referred to as a dialog box, but in the
grand scheme of things, it is a child window to the word processor, its parent.
Now think of the Open File dialog box as a parent and then you find that the File
Name field is a child window of the dialog. So are all the other fields within the
dialog. These are all children of the parent dialog and are all at the same
logical level. Each window is a child to the window one level up that spawned or
generated it, and each window is a parent to the windows one level down that it
spawns.
Just in case you're having a little trouble visualizing all of this, let's try
using an analogy. Most people are familiar with directory tree structure, either
from working in DOS or Windows Explorer. On your disk drive, say your C drive, C:\
is the parent of all other directories on your drive. All of the subdirectories
one level down from C:\ are children of that parent and are at the same logical
level. Thus, if you have subdirectories named Eudora, JAWS37, MyDocuments,
Recycled, and Windows on your system, they will all be one level down from C:\.
They are all direct children of C:\ and are all one logical level down. For the
purposes of directory tree structure and window hierarchy, you can assume that
being at the same logical level means that all members were spawned or generated by
the same parent. Remember that we said that the PriorWindow and NextWindow command
could be used to move to windows at the same logical level? Well, in a directory
tree, this would be analogous to moving to the prior subdirectory and next
subdirectory of a directory tree. If we open the JAWS37 subdirectory, we will see
four new subdirectories, Help, Manuals, Settings, and Tecnotes. These four
subdirectories are all one level down from JAWS37, are children of JAWS37, and are
at the same logical level as each other, two levels down from C:\. This can, of
course, continue until we reach the lowest logical level of a particular branch.
The parent/child structure of Windows works much the same way as a directory
structure. Each application is a branch of the tree, and child windows are spawned
from it. All windows one level down from the parent application are children at
the same logical level, one level down from the parent. Each of these children can
spawn children of their own, and these children are three levels down from the
parent application. Try moving up and down through the various logical levels of
different branches of your directory tree in Windows Explorer, and you should get a
better feeling for this parent/child hierarchy.

Identifying Windows

The application programmer assigns a number of identifiers to each window. These

identifiers allow the window in question to be referred to unambiguously. For
instance, each has a Window Class, a Type, a Type Code, a Subtype Code, and a
Control ID. The Window Class and Type Code tell us whether it is an edit field, a
button, or some other type of window. The Subtype Code can give more specific
information about the window, differentiating, for example, between a regular
button and a radiobutton. Thus, the window class, Type, Type Code, and Subtype
Code allow us to categorize the window. Listed below are more precise definitions
of these four categories and the JAWS built-in functions that are used during
script writing to obtain them.

Window Classes, Types, Type Codes, and Subtype Codes

Window Class - This is a category which denotes some information about what a
window is and does. For example, a Window Class can be an edit field, a listbox,
or a button. This is already providing some valuable information about the window
since we know that a listbox is something entirely different and will have quite
distinct reading requirements from a button. The problem is that Window Class does
not always provide information which is sufficiently detailed for our purposes.
For example, checking the Window Class will return the same information for a
button, radiobutton, and checkbox, all of which have the Window Class of button.
Obviously, we are going to need more detailed information in some instances. The
other window categories listed below can be used to provide this information.
Furthermore, some programmers use custom window classes which have strange and
unrecognizable names that are not understood by JAWS. We are going to need some
method of telling JAWS how to deal with these custom window classes, and this is
discussed below. The Window Class is obtained with the function, GetWindowClass.
Window Type - As with Window Class, Window Type returns a string or name which is
descriptive of the window. This category can sometimes give more specific
information about certain windows. However, asking for the Window Type will Return
the same information about a window as asking for the Window Class if no more
specific information is available. For example, the Window Class and Window Type
of an edit field will be exactly the same. However, if more specific information
is available, the Window Type can be used to sort this out. Thus, whereas the
Window Class of a button, radiobutton, and checkbox is always "button", the Window
Types of these three windows will be reported as "button", "radiobutton", and
"checkbox". This more specific information will allow us to tell JAWS what to do
for each of these types. If the programmer has used custom window classes, then
asking for the Window Type will return a string that says that the Window Type is
unknown. However, when a custom window type is reclassified to a known window
class (see below), the Window Type will return the name of the reclassified window
and, thus, tell us what the window does. One problem with the Window Type is that
the string returned by this function is always in English and, thus, is not very
useful for those using JAWS in other languages. For this reason, the Window Type
Code was developed. The Window Type is obtained with the function, GetWindowType.
Window Type Code - Asking for the Window Type Code returns a number instead of a
string. This number is translated into a recognizable string by constant
definitions which can be found in the file HJCONST.JSH. For example, in this file
you will see lines such as WT_Button =1, WT_Edit = 3, WT_ListBox = 4, and
WT_ScrollBar = 5. The WT prefix of the constant tells you that this is a constant
that refers to a Window Type. While the Window Type Code does not end up providing
any more information than the Window Type, it does have the advantage of being
language independent. Since the same numbers are always returned for a given type
of window, the numbers can be equated to a string in any language desired. The
Window Type Code is obtained with the function, GetWindowTypeCode.
Window Subtype Code - As with the Window Type Code, the Window Subtype Code also
returns an integer. The Window Subtype Codes are translated into strings using the
same constant definitions as for Window Type Code. The only difference is that the
Window Subtype Code will provide more detailed information, if available. If not,
both functions will return the same information. For example, a RadioButton will
return a Type Code of 1 (WT_Button) but a Subtype Code of 19 (WT_RadioButton). The
Start button located on the task bar will also return a Type Code of 1 (WT_Button)
but will return a Subtype Code of 32 (WT_StartButton). Similarly,
GetWindowTypeCode will return WT_TABCONTROL for the Task Bar whereas
GetWindowSubtypeCode will return WT_TASKBAR. You will want to use
GetWindowTypeCode when you don't wish to have the more specific information which
is returned by GetWindowSubtypeCode. Window Subtype Codes are also language
independent. They can be obtained with the function, GetWindowSubtypeCode.

The reason that these window categories are important to users of JAWS is that JAWS
will behave differently, depending on what category of window has the focus. For
example, if the focus is on an edit field, JAWS tracks the caret or insertion
point. If you hit the DOWN ARROW key, JAWS will speak the line of text to which
your caret moves. On the other hand, if you are in a list box or menu, JAWS tracks
the highlight or lightbar as the arrow keys are used to move it up and down the
list. JAWS knows to do these things because of the scripts that are associated
with the up and down arrow keys in the DEFAULT.JSS script file. These scripts
contain logic that decides what to do based upon the category of the window that
has the focus when you use one of these keys. If you examine the SayPriorLine and
SayNextLine scripts in the DEFAULT.JSS file, you will see that decisions about what
to speak are made based upon the Type Codes and subtype Codes of the windows that
are current when the script is invoked.

As with Window Types, Type Codes, and Subtype Codes, there is a set of standard
window classes that is used by most programmers, and the JAWS default scripts
contain the necessary logic to allow proper speaking of these standard classes most
of the time. However, Window Classes are not always as standard as these other
categories. If you have ever needed to use the Window Classes dialog in the
Configuration Manager to reassign a custom or unknown Window Class, you know that
sometimes a programmer will create custom window classes that we need to inform
JAWS about. Since these custom classes are, by definition, non-standard, JAWS has
no idea what to do with them. Therefore, we have to use the Configuration Manager
to equate the unknown class to one of the standard classes so JAWS will know how to
behave when it encounters it. This process is called reclassifying or reassigning
the Window Class. If you have never used this procedure, use either the key
combination INSERT+7 or the key combination INSERT+F2 followed by W and ENTER to
invoke the Window Class reassignment dialog, and explore the various controls to
become familiar with it. Once you have reclassified a window to equate it with a
standard class, it should speak properly. Sometimes you may have to try more than
one class to figure out which one works best.

Control ID's and Window Handles

The Control ID is an arbitrary number which serves as an identifier that the

programmer uses to mark each window in his program. It is obtained with the
function, GetControlID. The Control ID, unlike the Window Class, has no special
meaning, but it can be used to refer to a particular window. Ideally, no two
windows in a program should have the same Control ID, but they sometimes do anyway.
If you know how to access the Control ID, and, if it is unique within the
application you are writing scripts for, then you can tell JAWS to do certain
things if it finds that you are focused on the window with the particular Control
ID you have identified. One example where this is extremely useful is in
applications where the buttons are labeled with bit map drawings instead of text
labels. Normally, JAWS will speak the text label of a button when you TAB to it,
but if the label is a drawing, there is no name to be spoken. By determining the
Control ID numbers of the various bit map buttons, one can write a script that will
speak the name of a button when the focus moves to a button with a particular
Control ID.

Of course, there is no way to insure that two windows in different programs won't
have the same Control ID. Therefore, to prevent confusion, the system assigns a
unique identifier, called a window handle, to every window when it is accessed
during a given session. Window handles are numbers, but they are not unchanging
values like a Control ID. As long as the handle is actively assigned to a
particular window, it can be used to refer to and identify that window. Once the
handle is assigned, it remains active as long as the window exists. However, when
a window is destroyed, it relinquishes its handle. If the window is reinvoked
later, it will probably have a different handle. Since the system assigns these
handles as windows are used, the handle assigned to a window on this day may not be
the same as it is tomorrow. A good analogy to the window handle would be the
numbered ticket dispenser used in many bakeries and delicatessens. When you walk
in you take a number from the dispenser, and this number becomes your handle.
Today your number might be 31, and when the server at the counter calls 31, you
know it's your turn. If you go in again the next day, your number will probably be
different. It's still your handle, but it's different from what it was the prior
day. The point is, it's an identification system that tells the server who's next
in line.

Use the window' handle to identify it among all of the other windows in the system
at any given time. The window handle can be obtained using the built-in functions,
GetCurrentWindow () and GetFocus (). One way to do this, for example, would be to
use the GetCurrentWindow () function as a parameter for the SayInteger () function.
Thus, SayInteger (GetCurrentWindow ()) would speak the window handle of the window
containing the active cursor. By the way, this is another example of the use of
nested functions which was mentioned earlier.

There are some built-in default scripts that you can use to query these and other
types of information from an application. We'll teach you how to use them in
"Exploring the Application With the Utility Functions". (See Chapter 8.1.) For
now, try the following. Press CTRL+INSERT+F1. You should hear the Control ID,
Window Class, and Window Handle announced for the window you are currently in.
Move around to different windows and different applications to get some idea of the
kind of information this keystroke combination can supply.

Building Blocks of the Script Language

We construct script files from building blocks that make up the JAWS script
language. Think of this part of the book as learning a language because you will
be doing exactly that. Just as our written language has parts of speech that make
sentences that make paragraphs, so also does the JAWS script language have
statements that make up scripts that make up script files. First, we'll learn how
an individual script is assembled, and then we'll learn all the different kinds of
statements in this language. In the next part, "Script Writing Techniques," we'll
learn how to put complete script files together and how to compile and use them.

The Script

As we've said before, a script is a small computer program that controls JAWS
activities. Scripts can be attached to a keystroke. They do not have to be, but
any script can be. A script must have the following pieces in this exact order:

First is the script begin keyword. This is simply the word "Script" followed by a
space.
On the same line following the word "Script" is the script name. This is usually
several words concatenated together that describe the action of this script, such
as, CloseDocumentWindow. Note that each of the concatenated words is initial
capped, so JAWS can read the name correctly. () follows the name to complete the
script begin statement. All of this is automatically entered by Script Manager
when you create a script.
Next are all of the local variable declarations followed by all of the functions,
arithmetic operations, and flow control statements that you need in sequential
order. This could be as simple as just saying a string as we did in Our First
Script or a complex operation.
The script end statement, EndScript, is always the last line of a script. This is
automatically entered by the Script Manager when you create a script.

The Script Manager will create the basic script structure correctly when you choose
New Script from the Script menu or use the accelerator key combination, CTRL+E.
You should always create a script in this fashion as the Script Manager will also
prompt you for the proper script documentation and let you assign a keystroke.

The Function

The biggest difference between scripts and functions is that a function cannot be
attached to a keystroke. It will either be called from a script or another
function or be triggered by a system event. It is important to remind you about
some jargon we discussed earlier. This word function has several slightly
different meanings, and it's important to keep them in mind for the following
discussion. We are about to talk about functions that can be created by you, and
we mean by this a script you write that is not attached to a keystroke. This is a
user-defined function, meaning it is a function written by you, the user. There
are also functions already present in script files you may be modifying, and these
are functions that were written by Henter-Joyce's script writers. These are also
user-defined functions, but they were defined by other users, not you. Finally,
there are the built-in functions that are the building blocks of the JAWS language.
You, the user, cannot modify the built-in functions as you can your own functions
or the ones written by other people. You can use any of these three types of
functions as building blocks when writing scripts or new functions, but the built-
in functions are hard coded into JAWS, and so the following discussion does not
apply to them. (Built-in functions will be discussed later. See Chapter 7.3.5.)
A non-built-in function must have the following pieces in this exact order:

The return type, either handle, Int, Object, String, or Void.

The function begin keyword. This is simply the word "Function" followed by a
space.
On the same line following the word "Function", the function name. This is usually
several words concatenated together that describe the action of this function, such
as, SayFocusedWindow. Note that each of the concatenated words is initial capped.
That way JAWS can speak the name as if it were separate words. The name is
followed by () to complete the function begin statement. Note that all functions
should have return type designations such as those listed under item 1 before the
function begin keyword. These return types were mentioned earlier (See Chapter
4.4.1.) and describe what type of information is returned to the calling script
when the function finishes running. Of course, a function can be designed simply
to be called and complete its task without sending any specific information back to
the calling script or function. In this case, the return is designated as Void.
On the other hand, in addition to completing any other tasks, the function can also
send an integer, string, object, or handle value back to the calling script. If it
does this, you should see the word Int, String, Object, or Handle before the word
Function on the first line. Special function event names such as AutoStartEvent or
NewTextEvent tell you that a function runs automatically when certain things happen
in an application. These functions are not normally called by other scripts or
functions. There can also be parameters in between the ( and ) which are used to
pass information to the function which it will need to perform its purpose. We'll
discuss all of these in more detail later. (See Chapter 7.5.)
Then you have all of the local variable declarations followed by all of the
functions, arithmetic operations, and flow control statements that are needed in
sequential order. This could be as simple as just saying a string with one
function as we did in Our First Script or a complicated operation.
The function end statement, EndFunction, always the last line of a function.

The Script Manager will create the basic function structure correctly when you
choose New Script from the Script menu. You should always create a function in
this fashion as Script Manager will also prompt you for the proper function
documentation and let you assign parameters and returns.

Let's also remember one other piece of jargon. The term "calling a function" means
placing that function's name into a script or function to be executed. You can
call either a user-defined function or a built-in function in this manner.

In many cases, rules and procedures that apply to functions also apply to scripts.
For example, variables are declared the same way in both and functions are called
the same way in both. There are also many differences. If we are describing a
design facet that applies only to a script or only to a function, we will be
careful to point that out. Otherwise, the rule applies equally to both.

Types of Statements

The following is a list of the types of statements that make up scripts. Each
statement is like a part of speech in the JAWS script language, has a specific job
to perform, and has certain rules associated with its use.

Comments

Comments are lines of text in your script file that are not executable statements.
They are usually used to inform those reading the source file how the statements
work. Comments may be placed on a line by themselves or at the end of a line.
Begin a comment with a semicolon. Everything else on the line after it is treated
as a comment. If you need multiple lines for comments, start each line with a
semicolon.

Includes

The include statement tells the compiler to include the contents of another file
along with this file, just as if that information had been typed into the main file
at the point of the include statement. Hence, all of the information in the
included file is accessible by the main file from the point of the include to the
end of the main file. This means that all included files will be compiled along
with the main file into one, large JSB file. Include files are separate files with
common items that may be usable by a number of script files or which you may wish
to keep separate for reasons of clarity or convenience. There are two types of
include files:

Header Files are designated by the extension JSH and contain either variable or
constant declarations.
Message Files are designated with the extension JSM and contain message statements
with their assigned numbers.

In versions of JAWS before 3.0, it was sometimes necessary to break macro files
into pieces to avoid exceeding the maximum size allowed. That is not a concern
with script files as they can be as large as you like.

The include statement has the name of the included file in quotes as follows:
Include �HJGLOBAL.JSH�
If you leave the quotation marks out, the syntax will be incorrect and you will get
an error message when you attempt to compile. It is also assumed that the file to
be included is contained within the language (e.g., ENU) subdirectory of the \
SETTINGS subdirectory of your JAWS directory.

The following is a list of the standard include files provided with JAWS and
included in DEFAULT.JSS:

HJGLOBAL.JSH - Contains the default JAWS global variables.

HJCONST.JSH - Contains the default JAWS constants.
DEFAULT.JSM - Contains the standard message statements referred to by DEFAULT.JSS.

As we covered previously, remember that a message file is a special include file,

which assigns message numbers to common messages. This way the script writer can
use the message number in place of the message and JAWS will look up the actual
text for the message in the message file. Actually, the message number is just a
constant which has the actual text message assigned to it. All of the script files
shipped with JAWS have their own separate message files. Use the same name as your
script file followed by .JSM as an extension when you create your own message file.
Then include it in your script file. Whereas the DEFAULT.JSM file contains
messages useful only to DEFAULT.JSS, HJGLOBAL.JSH and HJCONST.JSH are used in any
script file which refers to the JAWS global variables and constants.

Homework Assignment #4 -

Pretend you are starting to build a script file for an application called
JAWSWINS.EXE. You want to use include statements for a header file of constants
and variables, a message file for messages, and the two JAWS files, HJCONST.JSH and
HJGLOBAL.JSH. Write the include statements required to do this. The answer can be
found in Appendix A. (See Chapter 14.3.)
Variables

A variable, as we discussed earlier (See Chapter 1.3.) and as its name implies, is
an entity that holds a value that can change during code execution. (The term
execution is used by programmers to describe the running of code, i.e., a computer
program such as a script. We use it here just to introduce you to the term.) Each
variable is of a specific type. The contents of a variable are stored in memory by
the JAWS program and can be used by your script code whenever you need it.
Variables must be �declared� or defined to have a name and a type before they can
be used. Each variable must have a distinct name to distinguish it from other
functions and names used in the code. Be careful not to use names that are already
assigned to functions, global variables and constants as this will cause compile or
execution problems.

The following is a description of the types of variables allowed in the JAWS script
language:

Integer - A variable designed to hold an integer value. (An integer is a whole

number without a decimal point.) It is declared like this:

Int MyIntegerVariable

Note that the type (Int) is followed by the distinct name assigned to this variable
(MyIntegerVariable).

An integer variable contains a whole number. We use a variable so that its value
can be changed by actions that take place while our script file is active and so
that we can refer to the number by name in our scripts.

The following rules apply to the use of an integer variable:

An integer variable must be declared before it can be used.

Its default value, that is to say, the value it has before any value is assigned to
it, is always 0.

String - Holds a string of characters. A string is a group of characters including

letters, numbers, punctuation marks, and spaces. It is declared like this:

String MyStringVariable

We use a variable to represent our string because the string it contains may be
changed by actions that take place while our script file is active and so that we
can refer to the current string by name in our scripts.

The following rules apply to the use of a string variable:

A string variable must be declared before it can be used.

Its default is always "null" or no characters.

When you are assigning a value to a string variable, you must put the string
between quotes. For example, the following syntax is correct: Let StringVariable =
"Hello". Note that in versions of JAWS prior to version 3, you had to insert a
space in between the quote marks when you were checking for a null value. That has
been changed. Null is indicated by to quotation marks with no space between them.

Handle - Holds a window handle. A window handle is a unique number assigned by the
system to each window in a currently running program. It is declared like this:
Handle MyHandleVariable

You probably remember from our earlier discussion of window identifiers (See
Chapter 6.) that the window handle is assigned by the system and is unique to a
particular window. While a handle is also a whole number and can, therefore, be
manipulated like other integer variables, the use of a handle variable is reserved
solely for the identification of a window handle. Most of the time we use it to
identify a particular window from which we want information.

The following rules apply to the use of a handle variable:

A handle variable must be declared before it can be used.

Its default value is always 0.

Object - A variable designed to hold an object. An object, for the purposes of the
JAWS script language, refers to the types of objects present in certain Microsoft
applications such as the Office 97 suite. (See Chapter 7.3.5.9.) It is declared
like this:

Object MyObjectVariable

An object variable is used to hold an object which has been returned to a JAWS
script or function. It is employed to obtain certain types of information from
some Microsoft applications which are normally very difficult or impossible to
obtain simply by reading the screen. The following rules apply to the use of an
object variable:

An object variable must be declared before it can be used.

It's default value is always null or empty.

Variables can be local which means they can only be used in the script where they
are declared or global which means that they can be used in any script within the
script file where they are defined. Global variables can be declared at the
beginning of a script file with the group heading, Globals. Place this group right
after the include statements. Global variables can also be declared in an include
file as is done with the default script file and its include header file
HJGLOBAL.JSH. Once it is included, the global variables declared in this file can
be used in any of the default scripts. You should create a header file for
variables that you intend to use in more than one script file. If you create a
global variable that you only intend to use with one application, it's a good idea
to declare that variable directly in the script file rather than the header file
and to include the app name in the variable name. This will serve to tell the user
that this is a global variable meant for use by this one application. The user
should also understand that once a global variable has been created and assigned a
value, that value remains in memory, even after the application that uses it has
been closed. If the application is reopened during the same computer session, the
global variables from that application's script file will have the same values they
had just before the application was closed. The only way to clear a global
variable is to unload and then reload JAWS.

Local variables are declared within a script in the first statement after the
Script start statement. They have the heading, Var.

Here's how each class of variable looks in an example from a standard script file:

The following declaration statements are taken from WINWORD.JSS, the script file
for Microsoft Word for Windows. Notice that most global variable names start with
the word, global, so that they can easily be distinguished from a local variable.
We'll go over naming conventions in more detail later in "Script Writing
Techniques". (See Chapter 8.)

Globals
String GlobalWinwordVersion,
Int GlobalCurrentControl,
Handle GlobalRealWindow,
String GlobalRealWindowName,
Int WinWordFirstTime, ; to say auto start message only first time
Handle WinWordContextHandle, ; read word in context
Int WinwordFontCode ; when font buttons are pushed

There are two things to note about this list of global variables. First,
each line except the last one has a comma after the variable name. Second, some of
the lines have comments after the variable name. The comment is everything which
appears after the semicolon and can serve as a reminder of the purpose of the
variable. Any commas must go before the comment.

The following local variable declaration statements are taken from the HotKeyHelp97
() function in WINWORD.JSS, the script file for Microsoft Word for Windows. As
shown, the variable declarations appear just after the function begin statement.

Function HotKeyHelp97 ()
var
handle WinHandle,
Int verbosity

Here again, all lines except the last have a comma at the end.

Constants

As we discussed earlier (See Chapter 1.3.), constants are a way of using easily-
remembered names to store hard-to-remember strings of letters or numbers. Think of
a constant as a number or group of letters or words that has been given or assigned
a new name. This is done purely for mnemonic reasons since it is easier to
remember a name than a number or long group of letters or words. There are no
restrictions to how many constant names you can assign to a number. For example,
in the standard JAWS constants file, HJCONST.JSH, both of the constants True and On
are assigned the value one. What that means is that you can write a script
statement to check if a condition equals True, on, or 1. They are all considered
to be the same value once the constant declarations have been made. We strongly
recommend using constants because its more difficult to remember that when
something is true, its state is 1, but easy to understand the difference between
true and false. Moreover, when someone else is reading your script file, it's much
easier for them to understand what you were trying to do if they see well-named
constants instead of numbers. Finally, if you need to change the value of a number
that is used in several places, you can change all of them at once if you have used
a constant to represent that number by simply changing the value of the constant
declaration.

Constants are declared at the beginning of a script file with the group heading,
Const, as follows:

Const
True = 1,
False = 0,
On = 1,
Off = 0

Please note that all of these entries except the last has a comma at the end of the
line. Script writers will sometimes define their own constants for a script file,
but they often also use those that are already declared in HJCONST.JSH. If so,
they must remember to include this header file. We'll go over the meanings of the
constants in this file in the next section, "Script Writing Techniques."

Built-in Functions and Operators

There are several types of statements in the JAWS scripting language that can be
used to construct scripts and user-defined functions. These are built-in
functions, arithmetic operators, logical operators, and bitwise operators. There
is also a special type of built-in function called a hook function which will be
discussed separately.

Built-In Functions

The JAWS language provides over 350 pre-defined functions for use in scripts. Each
function performs a specific series of activities. These are the building blocks
or instructions from which we create our scripts. For instance, RouteJAWSToPC
checks the position of the JAWS and PC cursors, makes the necessary calculations
and moves the JAWS cursor to the same point as the PC cursor. All of that activity
is transparent to you as all you need to know is that it moves the JAWS cursor to
the PC cursor.

It would not be practical to discuss all the predefined functions here, so we'll be
content to discuss some of the most important ones. Appendix C lists many of the
most important functions and gives a brief description of each one. These
descriptions are based on information that can be found in a file called
BUILTIN.JSD which can be found in the \settings\enu subdirectory of your main JAWS
directory, assuming you are using the U. S. English version of JAWS. These
BUILTIN.JSD descriptions are similar to the descriptions you hear when viewing the
functions list of the Script Manager, but many of them have been enhanced with
additional information. While all the JAWS functions are important, the ones shown
in Appendix C were deemed to be most important and worthy of inclusion here.
Obtaining a thorough understanding of these will put you well on your way to
becoming a master script writer. These descriptions and the ones for the remaining
functions can be reviewed at any time by invoking the insert function dialog in the
Script Manager or by viewing the BUILTIN.JSD file.

We have also grouped many of the built-in functions by the type of task they
perform. These groupings can be viewed in Appendix D. If you want to do a
particular type of task but don't know the name of the function, you might try
looking in the Appendix D categories instead of looking through the entire
alphabetical list of Appendix C or BUILTIN.JSD.

Before studying Appendix C, there are a couple of concepts about some of the
functions that we should review. The syntax of these built-in functions is very
similar to that already discussed for user-defined functions, but let's take a
moment to remind ourselves.

The syntax of a function is as follows:

FunctionName ([Parameters])

Some built-in functions require parameters. This is indicated by the word

"parameter" in brackets above. A parameter is data that the function needs to have
in order to do its job. If there is more than one parameter, a comma is used to
separate each parameter within the parentheses. The format is exactly the same as
was previously discussed for user-defined functions. When a function which
requires more than one parameter is called, the data must be supplied in the same
order stipulated by the function definition.
Some of the built-in functions provide "returns". Recall that a return is data
that the function returns back to the script for further processing. If a function
provides a return, that information is given in the BUILTIN.JSD file and in the
function list documentation of the Script Manager.

The GetCurrentWindow and GetFocus Functions

There are two built-in functions that are so very important to script writing that
they deserve separate attention here. These two functions are named
GetCurrentWindow and GetFocus. What in the world do these do? We have talked
quite a bit about window handles, but never have we explicitly told you how to get
one or what to do with it if you do get it. This is where you're going to start
learning how to do these two things. This will allow you to obtain detailed
information about a window (which, as we've already said, also means any control)
that is present in your application.

Shown below are the definitions for these two functions which are taken from
BUILTIN.JSD.

GetCurrentWindow - Determines the window handle for the window that contains the
active cursor. In contrast, the GetFocus function uses an analytic process to find
the window that currently has the focus regardless of which cursor is active.
GetFocus - Obtains the window handle for the window that has "the focus". It
always seeks to find the PC cursor or highlighted item that has the focus. It does
not take into account which cursor is active. In contrast, the GetCurrentWindow
function is less sophisticated. It simply obtains the handle for the window in
which the active cursor is located.

So what do these definitions mean? First of all, they both supply a window handle,
so using them allows us to obtain this information about a window in our
application. For example, the statements Let MyHandle = GetCurrentWindow () and
Let MyHandle = GetFocus () would set the handle variable equal to the value of the
handle of the window in question. If you followed these by a statement such as
SayInteger (MyHandle), JAWS would speak the number or window handle of the window
of interest. The difference between these two functions is that GetFocus will
obtain the window handle of whatever window JAWS believes to be the focus. This
might be, for example, the currently highlighted button or edit field in a dialog
box. GetCurrentWindow will check what cursor is active and then get the handle of
the window containing that cursor. So, if you activate the JAWS cursor, for
example, and move it away from the focus to another control, GetCurrentWindow will
get the window handle of that new control while GetFocus will still get the handle
of the window that has focus.

Okay, so now you know how to obtain a window handle. What are you going to do with
it? It's not much use by itself since it's just a number. However, the GetFocus
and GetCurrentWindow functions can be used as parameters by other functions which
do provide much more useful information about the window of interest. Using these
other functions along with GetFocus and GetCurrentWindow to tell the other
functions which window to obtain information about , can provide very useful
information. Some examples are shown below.

GetControlID (GetCurrentWindow ()) - Will provide the Control ID of the window

containing the active cursor.
GetFirstChild (GetFocus ()) - Obtains the handle of the first child window of the
window which has focus. This child handle could then be used to obtain information
about the child window.
GetParent (GetCurrentWindow ()) - Obtains the handle of the parent that spawned the
current child window.
SayControl (GetFocus ()) - Will speak the contents and prompt of the control that
currently has focus.
SayWindowTypeAndText (GetCurrentWindow ()) - Will speak a variety of information
about the window containing the active cursor such as the window title, if any, the
window contents, the window type, and other information.

Thus, you now have an understanding of how to use some JAWS functions to provide
handles that can be used by other JAWS functions to obtain information which will
be needed by your scripts, either to speak that information or to make decisions
about how to continue the script processing. Again, you will find a list of the
most important built-in functions in Appendix C and a complete list of these
functions in BUILTIN.JSD.

The Pause and Delay Functions

There are two functions which will cause the processing of a script to be suspended
temporarily, Pause () and Delay (). This suspension of script processing is often
necessary to prevent a script from getting too far ahead of the application it is
working with. For example, if you use a function that moves the JAWS cursor to a
different part of the screen or which drops down a menu, you may have to suspend
script processing to allow the action to complete before the script continues. The
Pause function simply stops script processing and gives other applications an
opportunity to complete their processing. Then the script resumes. The Delay
function stops for a specified length of time which is indicated by an integer
between the parentheses. The larger the integer, the longer the suspension.
However, if the suspension time chosen is not adequate for other applications to
complete their processing, the script will resume anyway. Sometimes a trial and
error process is necessary to determine the proper amount of delay. In general,
the Delay function is more useful when you want to force the script to stop,
irrespective of whether the application is finished or not. Sometimes a Pause
function simply does not seem to make the script suspend for a long enough period,
and a Delay is called for to achieve the desired affect. In general, it's
worthwhile to try the Pause first. If more suspension time is required, a Delay
can then be used.

A Word About SDM Windows

No sooner do you learn something about Windows when you have to learn about an
exception. We talked earlier (See Chapter 6.) about the interrelationship of
parent and child windows and described how every control (i.e., button, edit field,
checkbox, etc.) is really a window in its own right and is the child window of the
parent which spawned it, usually a dialog box. Well, it turns out that there is
one time when this isn't true. Windows has a type of window which it uses in some
of its applications called an SDM window which stands for standard dialog manager.
In an SDM window, the controls are not child windows of the parent dialog and, in
fact, are not separate windows at all. Thus, they do not have their own handles.
This makes it impossible to write scripts to get information about them using the
standard techniques used for other controls. For example, in a conventional
dialog, if one wanted to get information about the control currently focused on,
one could use a nested function statement such as GetWindowSubtypeCode (GetFocus
()). GetFocus () will feed the window handle of the currently focused control to
the GetWindowSubtypeCode () function, and this function will then return the
SubTypeCode of the currently focused control. In this way you could learn whether
the current control was a button, radiobutton, slider, checkbox, or other type of
control. This simply will not work for an SDM window since its controls do not
have unique handles. Therefore, JAWS incorporates some special functions which you
will see in Appendix C which are used to get information about controls in an SDM
window.
So how do you know if you are dealing with an SDM window? Well, that part, at
least, is easy. You can always use the JAWS hot key combination CTRL+INSERT+F1 to
get some information about the window you're focused on, and one of the items
you'll get is the window class. SDM windows always have the letters SDM in their
name. For example, if you bring up the Open Dialog in Microsoft Word, and use
CTRL+INSERT+F1 on the controls in that dialog, you will find that most of them have
the window class name bosa_sdm_Microsoft Word 8.0. You will also note that all of
the controls with that name also have the same window handle. This is the handle
of the Open Dialog itself, and, thus, will not be useful, all by itself, in
providing information about the individual controls. So how is one to get this
information? The special functions in JAWS which are designed to do this rely on
the fact that the controls in an SDM dialog do have a unique control ID even if
they do not have a unique window handle. By using this unique control ID in
combination with the window handle of the dialog, one can learn information about
the SDM dialog's control. For example, two of the special SDM functions shown in
Appendix C are SDMGetCurrentControl and SDMGetNextControl. The first of these will
return the control ID of the control on which the active cursor is focused, and the
second will get the control ID of the next control in the SDM dialog. Thus, if one
wanted to obtain more detailed information about the current or next control in the
SDM dialog, he could use the Control ID information from either of these two
functions with one of the other special SDM statements to report the advanced
information about that control. For example, such a statement is shown below.

SDMSayControl (GetFocus (), SDMGetCurrentControl ())

The function SDMSayControl will speak a control in an SDM dialog, but we have to
tell it which one. Two parameters are required to do this. The first one,
GetFocus, tells the function to get the window handle of the currently focused SDM
dialog. The second parameter, SDMGetCurrentControl, tells the function we want the
control ID of the SDM control we are focused on right now. Thus, this function
will speak the name and other information about the SDM control we are focused on
right now in an SDM dialog. In other words, we can specify a unique control by
telling JAWS both the handle of the SDM dialog we are referring to and the control
ID of the control we are interested in. These two pieces of information, taken
together, are sufficient to tell JAWS which SDM control we want to know about. The
other SDM functions listed in Appendix C provide other options for control
identification in SDM dialogs.

Arithmetic Operators

Arithmetic operators are used to perform classic arithmetic operations within

scripts. The four operators are a minus sign or dash (-) for subtraction, a plus
sign (+) for addition, a slash (/) for division, and an asterisk (*) for
multiplication. These operators are normally used on integer variables and
integers. Statements such as the examples shown below illustrate how these
operators can be used

Let IntVar = IntVar + 1 (This will increment the integer variable called
IntVar by 1.)
Let IntVar = FirstVar * SecondVar (This sets IntVar equal to FirstVar times
SecondVar.)
Say (MyConstant + YourConstant, OT_NO_DISABLE) (This will speak the contents
of the two constants, MyConstant and YourConstant, as if they were one message.
OT_NO_DISABLE is an output type constant that tells JAWS when to speak the message
with respect to a user�s custom verbosity settings. This topic will be covered in
more detail later. (See Chapter 8.9.)

Logical Operators
Logical operators are used to make comparisons of variables with other variables or
constants. We frequently need to know if one item has the same value, a lesser
value, or a greater value than another item. Sometimes several items or groups of
items must be compared with other items. The logical operators are usually used
within If-Then and While loops to check whether conditions required for logical
decisions are true or false. A list of the JAWS logical operators is shown below.

== - Two equals signs together in this manner ask whether the first condition is
"equal to" the second condition. That is, is the expression to the left of the two
equals signs equivalent to the expression on the right side. For example, the
expression (A == B) asks whether A equals B.
!= - An exclamation point and an equals sign together in this manner ask whether
the first condition is "not equal to" the second condition. That is, is the
expression to the left of the exclamation point and equals sign different from the
expression on the right side. For example, the expression (A != b) is true if A
does not equal B.
< - A < sign asks whether the first condition is "less than" the second condition.
That is, is the expression to the left of the < sign less than the expression to
the right side. Thus, the expression (A < B) is true if A is less than B.
<= - A < sign followed by an equals sign asks whether the first condition is "less
than or equal to" the second condition. That is, is the expression to the left of
the <= signs less than or equal to the expression to the right side. Thus, the
expression (A <= B) is true if A is less than or equal to B.
> - A > sign asks whether the first condition is "greater than" the second
condition. That is, is the expression to the left of the > sign greater than the
expression to the right side. Thus, the expression (A > B) is true if A is greater
than B.
>= - A > sign followed by an equals sign asks whether the first condition is
"greater than or equal to" the second condition. That is, is the expression to the
left of the >= signs greater than or equal to the expression to the right side.
Thus, the expression (A >= B) is true if A is greater than or equal to B.
&& - This operator is placed between two logical comparisons made using logical
operators such as the ones described above. It asks whether the first condition is
true "and additionally" is the second condition true. The total expression is
evaluated as true only if the comparisons on both sides of the && operator are
true. Thus, in the expression (A == B) && (C != D), a value of true is only
returned if A does equal B and C does not equal D.
|| - This operator is placed between two logical comparisons made using logical
operators such as the ones described above. It asks whether either the first
condition is true or whether the second condition is true. The total expression is
evaluated as true if either of the comparisons on either side of the || operator is
true. Thus, in the example (A == B) || (C == D), a value of true is returned if
either A equals B or C equals D. Of course, a value of true would also be returned
if both expressions were true.

This is a good place to introduce you to a convention some programmers employ when
using logical operators. Sometimes you will see a statement such as the one shown
below.

!Expression == True

where Expression can be a variable or function. Please note that there is an

exclamation point at the beginning of the word, Expression. This exclamation point
means, in essence, that we want to use the opposite of Expression and, therefore,
Thus, the above statement would be equivalent to saying Expression == False. Thus,
an exclamation point has the effect of inverting the logic of the statement.

Bitwise operators
Bitwise operators are a tool that allows us to compare two pieces of data in a
rather unusual way. What they allow us to do is compare two pieces of information
bit by bit instead of as a whole value. We all know that computer information is
stored in digital form as a series of ones and zeros. This is, of course, true for
variables and constants. For example, the JAWS constant for highlighted or
selected text is called Attrib_highlight. If you look in the HJCONST.JSH file, you
will find that this constant has a value of 64. 64, what does that mean? Well, 64
is obviously a base 10 or decimal number, not a binary number. We can tell this
because binary numbers only use ones and zeros, so 64 cannot be a binary number.
When we translate 64 into binary we get the number 01000000. (A discussion of
binary arithmetic is beyond the scope of this manual, so if you don't understand
how this conversion was made, you'll just have to accept this as the truth.)
HJCONST.JSH also tells us that the bold attribute, Attrib_Bold is 2 or 00000010 in
binary, the italics attribute, Attrib_Italic, is 4 or 00000100 in binary, and the
underline attribute, Attrib_Underline, is 8 or 00001000 in binary. Remember how we
said early on in this manual that constants were used because they're easier to
remember than numbers? Well, here's an excellent example of that situation. Names
such as ATTRIB_HIGHLIGHT are much easier to remember than long binary numbers.

So what can we do with these numbers, and what do they have to do with bitwise
operators? Let's say we want to know if a certain piece of text is highlighted.
We will use one of the bitwise operators which is designated by a single & sign to
figure this out. This bitwise operator allows us to take a variable and compare
it, bit by bit, with another variable or a constant such as ATTRIB_HIGHLIGHT.
There is an essential difference between a standard comparison and a bitwise
comparison of two pieces of information using the & operator. In the standard
comparison, a value of true or one will only be returned if both pieces of
information are identical in every respect. In a bitwise comparison using the &
operator, a value of true or one will be returned for every pair of bit positions
in the two pieces of information which are identical. Let's say we want to do a
comparison of two binary numbers, 0101 and 0001. In a standard comparison, these
two numbers are not the same. In a bitwise comparison, the rightmost digit is the
same for both numbers, so a value of 0001 would be returned for the bitwise
comparison. This return means that the comparison was true, but only in the first
or rightmost position. If we were to compare the numbers 0111 and 0110, we would
see that the second and third positions from the right are both ones in both
numbers. Therefore, the bitwise comparison would return a value of 0110.
Similarly, 0011 and 0110 would return a value of 0010. Only the second digit from
the right is a one in both numbers. We can do similar comparisons when one of the
numbers is a variable like, for example, the variable that reports the attributes
that are associated with a piece of text in the NewTextEvent script function.
(Recall that the NewTextEvent function runs automatically every time new text is
written to the screen.) The following line is taken from that function.

If (nAttributes & ATTRIB_HIGHLIGHT) Then

This is a pretty strange statement at first glance. The variable nAttributes is

the parameter that brings attribute information into the NewTextEvent function when
new text is written to the screen. So, if this text is highlighted, nAttributes
will have the value 01000000. If the text is bold, it will have the value
00000010. If its italicized and bold, nAttributes will have the value 00000110.
If it is highlighted, bold, and italicized, it will have the value 01000110. You
can think of each position in nAttributes as a toggle switch that turns one of the
possible attributes on or off. Well, we already know that ATTRIB_HIGHLIGHT has the
value 01000000, so the above line of code says take nAttributes and compare it
using the bitwise & operator to the constant Attrib_highlight. If there is a
match, report back a value of one for each bit position that matches. If we
compare, for example, text which is highlighted, bold, and underlined (nAttributes
= 01000110) in a bitwise fashion with ATTRIB_HIGHLIGHT (01000000), we will return a
value of 01000000. This means that the If-Then statement is returning a value of
true or 1 for the seventh position from the right, the one which indicates whether
or not text is highlighted, and the NewTextEvent has figured out that the newly-
written text is, indeed, highlighted. Therefore, the text will be handled as
highlighted text. The fact that this text is also bold and italicized is true, but
irrelevant to this test. The above If-Then statement is only checking to see if
the highlight bit is set to true or 1, and that is the information being sent back
to the NewTextEvent script.

There is also another bitwise operator which performs an or operation instead of an

and operation. This operator is designated by a single | to differentiate it from
the standard or operator which is designated by two of these symbols, ||. When you
use the bitwise or operator, a value of true is returned if either or both of the
bits in the comparison is equal to 1. Thus, a comparison of the two binary numbers
0101 and 0010 would return a value of 0111. Similarly, comparison of the numbers
0100 and 0001 would return a value of 0101. Thus, the bitwise or operator is
satisfied if either of the numbers has a 1 in a particular position.

Hook Functions

Sometimes it is necessary to put JAWS into an altered state where some or all of
the keys on the keyboard do different things from their normal functions. We are
already familiar with this concept to some extent. You can toggle such settings as
screen echo, keyboard echo, and the home row state, the last being a feature which
will be described later. (See Chapter 8.1.) These types of toggles are available
because JAWS has built-in functions that can be called by scripts to toggle these
states in predefined ways. However, JAWS also contains two functions that allow
you to alter the state of the system to suit your own needs. These are the AddHook
() and RemoveHook () functions. In a nutshell, what happens is this. If you
install a hook by calling the AddHook () function from a script, we say that a hook
is in place. When you use the AddHook function, you give it the name of a hook.
This hook is a special user-defined function that you must create which is to be
run instead of the code normally run by JAWS scripts. When a hook is in place, it
is called right before every script is run, and passed the names of the current
script and frame as its two parameters. Since the hook function is actually called
by JAWS once it is in place and not by a script, these parameters are supplied by
JAWS internal code and not by a function call. If the hook returns TRUE, the
script is allowed to execute. If the hook returns FALSE, the script will not be
allowed to run. Thus, if a hook is in place and we have designed the hook to
return a value of false while it is in place, the script assigned to the key we
pressed will not run, and we can have the hook function do something else instead.
You could, if you wanted, design a hook that would make every key which is assigned
to a JAWS script recite "Mary had a little lamb" instead of performing its normal
JAWS function. Now this wouldn't be of much use, but it would be pretty funny if
you had such a hook you could turn on every time you let a friend use your
computer! Let's look at an example of a more useful hook function, the
KeyboardHelpHook.

As you probably know by now, you can turn on keyboard help by pressing INSERT+1.
When you do this, all the keys on the keyboard start reciting their functions if
they are attached to a JAWS script instead of actually performing those functions.
When you press INSERT+1 again, the keyboard returns to performing the functions
instead of reciting the descriptions. Did you ever wonder how this is done? Well,
guess what? It's done with hook functions. Let's look at the KeyboardHelp script
and the KeyboardHelpHook function to see how these tasks are accomplished.

Script KeyboardHelp()
SayMessage (ot_status, msg401_L, msg401_S) ;"Keyboard Help on� ;spoken first time
Insert+1 is pressed.
let nKeyboardHelpSavedTypingEcho = GetJCFOption(OPT_TYPING_ECHO) ;saves your
current keyboard echo setting.
SetJcfOption(OPT_TYPING_ECHO,1) ; echo characters ;Keyboard help needs typing echo
to be in the characters state.
AddHook (HK_SCRIPT, "KeyboardHelpHook") ;Adds the hook named KeyboardHelpHook.
TrapKeys(TRUE) ;When True, this function makes JAWS ignore any keys not attached to
;scripts
EndScript

What's happening here is that a message is spoken telling you keyboard help is on,
your current typing echo is saved, typing echo is set to characters so the help can
function properly, and the KeyboardHelpHook is installed. Additionally, TrapKeys
is set to true so keys not bound to JAWS scripts or frames will be ignored. (You
can't give a help message for a key that has no JAWS script or frame associated
with it.) Please also note that the AddHook function requires two parameters. The
first, HK_SCRIPT, is a constant defined in HJCONST.JSH you must use for every
AddHook. The second is the name of the hook you are installing. So now, any key
that is tied to a JAWS function will not execute its function but will call the
KeyboardHelpHook function shown below.

Void Function KeyboardHelpHook (string ScriptName, string FrameName)

if (ScriptName == "KeyboardHelp") then ;If we press INSERT+1 while the hook is
installed,
;it means we want to turn Keyboard Help off.
SayMessage (ot_status, msg402_L, msg402_S) ; "Keyboard Help off"
RemoveHook (HK_SCRIPT, "KeyboardHelpHook") ;This removes the hook.
TrapKeys(FALSE) ;Now all keys will be recognized again.
SetJcfOption(OPT_TYPING_ECHO,nKeyboardHelpSavedTypingEcho) ;Restore our
;original keyboard echo.
return FALSE ;Even though we're turning the hook off, we'd better return
false one
;more time, or the INSERT+1 script will run again and reinstall the
hook.
EndIf
;The rest of the function, as shown below, decides what to speak depending upon
whether the key is tied to
;a key or a script and whether the key was pressed once or twice.
Study this
;code until you understand it thoroughly as an exercise. If you have
trouble
;understanding all of the If-Then-Else statements, read the next
section on
;Controlling flow, then come back and study this script again.
if IsSameScript () then
if ((FrameName != "") && (GetFrameDescription (FrameName) != "")) then
SayMessage (ot_help, msg420_L, msgSilent) ; "This frame "
Say (GetFrameDescription (FrameName), OT_HELP)
EndIf
if (FrameName == msgNull_L) then
Say (GetScriptDescription(ScriptName), OT_HELP)
EndIf
else
Say (GetCurrentScriptKeyName (), OT_HELP) ; says key name, "INSERT+UP ARROW"
if (FrameName != msgNull_L) then
SayMessage (ot_help, msg421_L + FrameName) ; "says the content of the
frame
Say (GetFrameSynopsis (FrameName), OT_HELP)
else
Say (ScriptName, OT_HELP) ; will say the name of the script, "SayLine"
 Say (GetScriptSynopsis(ScriptName), OT_HELP)
EndIf
EndIf
return FALSE ;Prevent the script from running since we only want the help message.
EndFunction

Introduction to Script Writing With Microsoft Objects

If you happen to have perused some of the scripts in Microsoft PowerPoint or Excel,
you may have come across some pretty strange code that doesn't resemble any of the
script building blocks we've talked about so far. This code includes words like
Selection, Range, Text, and Collapse separated from one another by periods. Unless
you're already familiar with object-oriented programming using languages such as
Visual Basic and C Plus+, this type of code will be completely incomprehensible.
So what is this stuff, and what's it doing in the middle of JAWS scripts? To
explain this, we need to introduce three new concepts, objects, methods, and
properties.

An object is a self-contained construct which possesses within itself a number of

characteristics or attributes which are defined as the properties of the object.
The object also contains a number of techniques or functions which can cause
something to happen to the object or which allow the object to perform some action,
and these are called the methods of the object. The properties can be used to
return information back to the outside world about the object, and they can also be
used to alter the qualities or attributes of the object. This information can be
passed to another method or property for further processing or back to the JAWS
script language to be used for script processing. Thus, the object contains within
itself all of the attributes or properties as well as all of the techniques or
methods that can be used to cause something to happen to the object or return
information from it. Certain properties are read-write which means they can be
looked at as well as changed in certain predefined ways, certain properties are
read only which means you can determine what the property is but not change it, and
some properties are write only, which means you can change them but not look at
them. The methods of an object are specific to that object and are used within the
object. They are not used on other objects. That is what we mean when we say an
object is self-contained. It possesses all the devices needed to change it in all
of the ways it is allowed to be changed and to return information about itself to
the outside world.

So why do we care about these objects? There are certain things which users like
to be able to do such as read and navigate by sentence and paragraph instead of
just by line. Unfortunately, it's rather difficult to do this in most word
processors since they aren't set up to navigate in this fashion. Furthermore, we
must remember that a screen reader, by definition, reads what's visible on the
screen, and if part of the paragraph or sentence we're trying to read is off the
screen, it would normally not be possible to access that material without scrolling
the screen. The user might not wish to do this since, for example, he or she might
be in the process of editing text and not want to move the cursor. Objects provide
us with a way to accomplish these tasks since the object which represents a given
document contains all of the methods and properties needed to report the
information needed back to JAWS. Microsoft has chosen to expose these "automation
objects" to the outside world in certain of its applications such as the Office 97
and 2000 suites, and JAWS, by examining and manipulating these objects, can
accomplish the sorts of desirable tasks described above. In essence, JAWS
temporarily becomes an object reader in addition to being a screen reader. The
term "automation object" is used here to mean an object which is exposed so that
other entities such as JAWS can access them. Applications which do not use the
sort of object model described here for their coding or do not expose these objects
to the outside world cannot be accessed in this fashion. Thus, the use of objects
for enhancing screen reading is limited to certain Microsoft applications or any
application that chooses to expose these automation objects.

Unfortunately, it is beyond the scope of this manual to provide all of the

knowledge and teach all of the techniques necessary to use these objects in
scripting. In fact, for those who are not familiar with object-oriented
programming, that task would probably require a manual longer than this entire
script manual. What we intend to do here is introduce the subject so the objects,
methods, and properties which appear in JAWS scripts will not be completely
mysterious and to provide some references so that those who wish to can continue on
their own to learn this subject. This chapter is intended as an overview only.

Hopefully, it is beginning to become apparent that manipulating these types of

objects is fundamental to the activities that occur in Microsoft Office
applications, and, that by manipulating these objects, JAWS can access desirable
information from the object model. In fact, if you take the time to learn how to
record a macro in Word (which is simply done from the Macro submenu of the Tools
menu), you will see something very interesting. (You can access information on
macro recording from the Windows help system by pressing F1 while in Word. Go to
the Index tab and type in the word macro. You will be presented with several
topics, including macro creation.) Try recording a macro while doing some typical
operation like opening a document, saving a document, or selecting and then
deleting some text. Then, after the macro recording has been turned off, go back
to the Macros submenu and press Enter on the first option which is Macros, ALT+F8.
You will open a list of your existing macros and be given the option to edit them.
Select the edit option, and you will be placed in the Visual Basic editor and shown
a copy of your macro. You will note that the code looks just like the kind of
object programming we have been discussing. This means that all of the things you
do while working in this application are being done by accessing objects and
working with their methods and properties. Thus, studying macros you have recorded
is one way of learning how objects are manipulated in the Office applications.
There is one other useful technique you can use while you are in the Visual Basic
editor. If you press F1 while your insertion point is on any method or property of
the programming code, a help screen will pop up which explains the term and how it
is used. If you do not get this help, it may mean that Visual Basic help is not
installed on your system. You can install it from the Microsoft Office
installation disk by inserting the disk into your CD ROM drive and then bringing up
the Run dialog from the Start menu and typing X:/setup where X is the letter of
your CD-ROM drive. Click the add/remove button when the installation dialog
appears. Then, when the options list appears, choose one of the office
applications such as Word and tab over to the Change Options button. Click this,
and you will be placed in another options list. Select the Help choice and tab to
the Change Options button again. Click this, and you will be in a third list.
Select the Visual Basic Reference option, and then tab over to the OK button and
click it. Keep clicking the OK buttons until you return to the top level selection
list. Repeat the entire procedure until you have selected the Visual Basic
Reference selection for each application in which you are interested. Then click
OK at the top level to finish the installation. You can return to the Visual Basic
editor at any time by selecting it from the Macros submenu of the Tools menu or by
pressing ALT+F11.

Now, let's take a look at one VERSION of a JAWS script which originally appeared in
version 3.2 and which used objects to perform a scripting task. In version 3.2,
pressing CTRL+NUM PAD PLUS while in Microsoft Word 8 read the current paragraph.
The script which was executed is shown below.

Script SayParagraph ()
SaveCursor ()
PCCursor ()
if (GetLine () == "") then
Say (msge18, OT_MESSAGE); "Blank"
else
Say (GetParagraphContent (), OT_TEXT)
EndIf
EndScript

This looks like a perfectly ordinary script which calls a user-defined function
named GetParagraphContent (). Let's take a look at that function.

String Function GetParagraphContent ()

var
object o
let o = oWord.Selection.Paragraphs(1).Range;
return (o.Text);
EndFunction

We can see from the first line of this function that it returns a string and does
not need any parameters. The second line starts our local variables declaration,
and on the third line, we declare an object variable called o. Then the fun
begins. The fourth line reads

let o = oWord.Selection.Paragraphs(1).Range;

Before we analyze this line, we want to mention the semicolons that appear at the
ends of some of these lines. They mean the same thing they've always meant, that
everything afterwards is a comment. Some programmers add these semicolons to
indicate the end of the line's actual code, even if they don't actually put in a
comment afterwards. Now, let's analyze this line from left to right. To the left
of the equals sign, we are saying we are going to assign some value to the variable
o. The first thing to the right of the equals sign is something called oWord.
oWord is a global variable that has been declared in the WINWORD.JSH header file,
and it is an object variable which holds the application object, the application
being Microsoft Word. oWord is defined in the AutoStartEvent function at the
beginning of the script file. Recall that this event function runs automatically
every time Word is loaded or gets the system's focus. The code in the
AutoStartEvent function which was written by the programmers at Henter-Joyce sets a
pointer to Word so JAWS will know where to go looking for application objects. If
there were nothing else on this line except Let o = oWord, we would be setting the
o variable equal to the global object variable oWord, the whole application object.
That wouldn't do us much good if what we wanted to do is read the current
paragraph. So we're going to have to find some way to extract that paragraph's
textual information from the whole application object.

The next item is a period. This is used to separate variables, methods and
properties. Then comes Selection. This is the Selection property and, in essence,
it returns the Selection object which contains information about what is currently
selected in the document. If you have selected some text in the document, that
text will be returned in the Selection object. If nothing is currently selected,
the Selection object will be collapsed to a single point at the insertion point.

This all makes sense if we think about what we know about selecting text. We know
we can only have one block of text selected at a time in a given document, so it
makes sense that there can only be one selection object at a time. If nothing is
selected, then the selection and the selection object have to be collapsed to a
single point, the insertion point.

If a property returns an object, that object will have the same name as the
property which returned it. Please keep this in mind because the alternative is
total confusion. A property returns an object of the same name, but the starting
property is not a property of the newly-returned object. This is true even though
they have the same name. The property belongs to the previous object, the one just
operated on, not the newly-created object. The new object has its own set of
properties and methods, and they do not include the one that created it.

So let's recapitulate what we have so far. We have the whole word application
object represented by the variable oWord, and the Selection property has returned a
Selection object which contains information about what is currently selected in the
document.

Next comes the Paragraph property. Using this property returns a paragraph object.
This object contains information about the paragraph indicated by the index number
in parentheses which is contained within the selection object that was returned by
the Selection property to the left.

After the Paragraph property returns its information, we will have returned an
object with the paragraph that contains the insertion point (assuming no text has
been selected) or the first paragraph which is part of a block of selected text.
(In the first case, there is only one paragraph, and in the second case, the (1)
index of the Paragraph object returns the first paragraph which is part of the
selection.)

Next comes the Range property. The Range property returns a Range object which
represents the portion of a document that's contained in the specified object. In
this case, the specified object is the Paragraph object that was returned by the
Paragraph property to the left. The Range is similar to a pair of bookmarks. One
represents the beginning of the range and the second the end of the range. The
Range object which is returned by the Range property using the information from the
Paragraph object will have the beginning and ending points of the specified
paragraph set as the range. This final object is now set up to allow us to
retrieve the information we need to speak the current paragraph.

We now come to the next line in the GetParagraphContent function, the one which
returns the information to the calling script. That line reads as follows.

return (o.Text);

Here, o is the Range object that was returned at the end of the previous line, and
Text is the Text property which returns the actual text in which we are interested
from the Range object. (Note that in this case, the Text property is returning
actual text and not an object.) As it is being used here, the Text property
returns the plain, unformatted text of the range. At last we've gotten to the
information we've been after. The text which will be returned by the Range
property in this case will be the text of the current paragraph. That, in turn,
will be returned to our calling script by the Return statement of this line of
code. Since the Text property returns a string, we will be returning a string to
our calling script, just as we specified in the first line of our function. The
calling script can then continue its processing and speak the text that has been
returned.

The key to all of these complicated machinations is that each object can only use
certain properties and methods (as we said near the beginning of this section) and
cannot use the properties and methods of other objects. To get the information we
want, we must use the correct method or property for our current object, and we
must use that method or property in a way that will return a new object that is
properly set up to allow us to access the information we need from the next level
down in the hierarchy. If we do this correctly, we will eventually get to the
information we need. Let's perform an experiment to show you how the properties
used in the GetParagraphContent function extract the information we need from the
application object and how altering the way we use those properties alters the
information we ultimately hear. A cautionary note is required before continuing.
The following experiment involves modifying the WINWORD.JSS and WINWORD.JSB files.
It is strongly advised that you make backup copies of these files for safety before
making any of the changes. This will allow you to retrieve undamaged copies of
these files in case you inadvertently break something.

To perform this experiment, open the script file for Word 8 or 9, and move to the
end of the file. Because JAWS versions after 3.2 have changed or eliminated the
SayParagraph script and GetParagraphContent function described above, we are going
to insert special versions of these that should allow someone using any version of
JAWS to try the following experiments. Copy and paste the function and script
shown below into your WINWORD.JSS file, making sure the function appears in the
file before the script:

String Function TestGetParagraphContent ()

var
object o
let o = oWord.Selection.Paragraphs(1).Range;
return (o.Text);
EndFunction

Script TestSayParagraph ()
SaveCursor ()
PCCursor ()
if (GetLine () == "") then
Say ("blank", OT_MESSAGE)
else
Say (TestGetParagraphContent (), OT_TEXT)
EndIf
EndScript

Next, press ALT+F to drop down the File menu and press the letter Y to synchronize
your documentation. You should hear the message, �synchronization complete.� Now,
place your cursor within the TestSayParagraph script and press CTRL+D to open the
Script Information dialog. It�s not necessary to enter any Synopsis or Description
since this script is temporary, and we�ll be deleting it when we�re done. So, tab
over to the Assign Hot Key field and enter a convenient keystroke which will not
interfere with other hot keys you may have defined or any Word accelerator keys.
The author chose ALT+CTRL+F12 as being sufficiently unusual as to qualify for this
purpose. Then press OK. You will be returned to the main Script Manager editing
window.

There is one final step that must be taken before we can start our experiment. You
must add a few lines of code to the script file so the test function and script
will compile and run. Before the AutoStartEvent function, the first function in
the script file, place the following two lines:

Globals
Object oWord

Finally, you must place the following five lines at the end of the AutoStartEvent
function, just before the EndFunction line:

let oWord = MSOGetMenuBarObject ()

let oWord = oWord.Application; initializes a pointer to the Word application
object
if !oWord () then
 let oWord = GetObject ("Word.Application");
EndIf

These additions define a global object variable called oWord and then initialize a
pointer to the Word object. Now, press CTRL+S, and you should hear �compile
complete.� If you do not, and you get some errors, check your work and fix any
errors until the file compiles successfully.

Now, place your cursor in the TestGetParagraphContent function and arrow down to
the first line after the variable o is declared. We will be making some
modifications to this line in a moment, but before we do that, let's return focus
back to Word for a moment and explore what this function is doing in its unmodified
state. You should return to Word and place the cursor on the first word of this
paragraph. Use your TestSayParagraph keyboard command (ALT+CTRL+F12, in the
author�s example), and you should hear this entire paragraph spoken. Now, use the
SHIFT+DOWN ARROW hot key to select the first line of this paragraph. Confirm that
you have done this by reading the selected text with SHIFT+INSERT+DOWN ARROW, and
you should hear the first line of the paragraph spoken. Now, use the
TestSayParagraph hot key again. What you should hear is the entire paragraph
spoken again. Okay, we've confirmed that the GetParagraphContent function is smart
enough to read us the entire paragraph, even though we've selected a portion of it.
That's good, because that's the way we want this function to behave. Now, go back
to the Script Manager and remove the Paragraphs(1) property from the line that
contains it. When you're done, the line should look like the line below.

let o = oWord.Selection.Range;

Save and recompile your script with CTRL+S. Return to Word, and place the
insertion pointat the beginning of the same paragraph you used before. Make sure
no text is selected, and then use the TestSayParagraph hot key again, and observe
what happens. How interesting! Nothing at all is spoken! Why not? Well, since
nothing is selected, the Selection property returns a Selection object which is
equivalent to the insertion point. Since we took out the Paragraphs property, the
Range property will operate directly on this Selection object and return a Range
object which has a beginning and end point at the same location, the location of
the insertion point. Obviously, a range which is zero characters wide cannot
contain any text, so the Text property on the next line of the script returns a
null or empty string, and we hear nothing at all. Now, perform one more
experiment. Select the first line of the paragraph again with SHIFT+DOWN ARROW,
and use the TestSayParagraph hot key again. This time you will hear the selected
text spoken. This is because the Selection object which is returned by the
Selection property includes all of the selected text, and the Range property will
now set a range at the beginning and end of the selected text. The Text property
in the next line will then return this text which will in turn be returned to the
calling script for speaking. Make sure you remember to put the Paragraphs property
back into the function just as it was before and to recompile the script file so
that the function will work properly again. Now the Paragraphs property will, once
again, return a Paragraph object from the Selection object and feed this
information to the Range property. Once again, you will hear the entire paragraph
spoken, whether or not any text is selected. Once you are done experimenting with
the test function and script, you may wish to delete them from the script file.

Controlling Flow

Scripts are not always performed in a linear, top to bottom fashion, with each and
every line being performed in order and only once. Sometimes some statements are
performed many times, and sometimes certain statements are skipped. The types of
statements which control the flow or sequence of events of script statements are
discussed below. There are three types of flow in a script:
Sequential - In this method a group of statements is run in order, starting at the
beginning, and continuing to the end. This linear flow is the simplest format.
Selection (Conditional) - In a selection, the flow of activity comes to a "fork in
the road" and must choose one or the other of two or more paths. Which path is
taken depends on comparisons or conditions which are made by the script statements.
Depending on the values of certain variables, one path or another will be taken.
This process is called branching.
Iterative - An iterative section "loops" (i.e., performs the same statement or
group of statements over and over), either while a certain condition is true or
until a certain condition is met.

A script can contain any or all of these techniques. Let's look at examples of
each of these activities.

Sequential

All of the statements that we have worked with so far are sequential statements.
That means that each of the statements acts in its turn starting at the top of the
script and continuing to the EndScript statement. The following is an example of a
script with only sequential statements:

Script SayTheAValue()
Var
Int A
Let A = 1
SayInteger (A)
EndScript

Selection (Conditional)

The If-Then statement structure provides a means of selecting one path or another.
Three statements are required for an If structure: If, Then and EndIf. Let's start
with a very simple If-Then statement.

If (x == 1)
Then
Say (�You are right�, OT_JAWS_MESSAGE)
EndIf

If, and only if, the variable X is equal to 1, the script will execute the Say
statement and say the words "You are right". Here's a slightly more complex
example.

If GetWindowName (GetCurrentWindow ()) == �Main�

Then
Say (�In the main window.�, OT_JAWS_MESSAGE)
EndIf

The function, GetWindowName, and its parameter, GetCurrentWindow, used in the If

statement returns the title of the current window. So what happens is this. If
and only if the name of the current window is Main, then the Say function is
performed. Otherwise it is ignored. We only take the Then "path" if the condition
of the If statement is true.

While the If and Then statements are actually separate statements, it is often
conventional to put them on the same line. The above group of statements would
then look as follows:
If GetWindowName (GetCurrentWindow ()) == �Main� Then
Say (�In the main window.�, OT_JAWS_MESSAGE)
EndIf

We will show our If-Then statements in this form from now on.

There are two optional statements in an If-Then structure, the Else and ElIf
statements. Each of these statements provides an alternate path, but it does so in
a somewhat different fashion. The Else statement tells the script to do certain
things if, and only if, the preceding If statement is found to be false. For
example,

If GetWindowName (GetCurrentWindow ()) == �Main� Then

Say (�In the main window.�, OT_JAWS_MESSAGE)
Else
Say (�Not in a known window.�, OT_JAWS_MESSAGE)
EndIf

This sequence will say one thing if you are in the main window and something else
if you are not. Here is an example of a three way branch:

If GetWindowName (GetCurrentWindow ()) == �Main� Then

Say (�In the main window.�, OT_JAWS_MESSAGE)
Else
If GetWindowName (GetCurrentWindow ()) == �Alternate� Then
Say (�In the alternate window.�, OT_JAWS_MESSAGE)
EndIf
Else
Say (�Not in a known window.�, OT_JAWS_MESSAGE)
EndIf

Here we say one thing if we are in the main window, we say a second thing if we are
in a window named "alternate", and we say a third thing if we are not in either of
these two windows.

The ElIf statement provides a simpler way of formulating a branch which says "Do
something else if a different condition is true". The above script sequence can be
reformulated to do exactly the same things using an ElIf statement. This is shown
below:

If GetWindowName (GetCurrentWindow ()) == �Main� Then

Say (�In the main window.�, OT_JAWS_MESSAGE)
ElIf GetWindowName (GetCurrentWindow ()) == �Alternate� Then
Say (�In the alternate window.�, OT_JAWS_MESSAGE)
Else
Say (�Not in a known window.�, OT_JAWS_MESSAGE)
EndIf

Here again we have alternative paths to travel. If the window name is Main, we go
down its path. If the window name is Alternate, we go down that path. Otherwise
we go down the Else path. The ElIf statement takes the place of an Else statement
followed by an If statement. You can use as many ElIf statements as you like.

If statements can be nested. This means that an If statement can be placed inside
of another If statement. This allows you to check for a particular condition only
if another condition exists. The second If condition will only be tested if the
first one is true. The sequence of statements within the second If-Then test will,
thus, only be performed if both conditions are found to be true. Don't forget to
use an EndIf statement for each and every If statement you use. Here is an example
of a nested pair of If-Then statements.

If GetWindowName (GetCurrentWindow ()) == �Main� Then

If GetWindowClass (GetCurrentWindow ()) == "Edit" Then
Say (�In the main edit window.�, OT_JAWS_MESSAGE)
Else
Say ("In the main window", OT_ JAWS_MESSAGE)
EndIf ;Is this an edit window?
Else
Say ("Not in a known window", OT_ JAWS_MESSAGE)
EndIf ;Is this the main window?

In this example, first we check to see if we're in the main window. If we are, we
check to see if we're in an edit window. If so, we say that we're in the main edit
window. If it's not an edit window, we just say we're in the main window. The
edit condition will only be checked if the main condition is true. Note that we've
used comments to indicate which If test the EndIf statement is terminating. This
is very helpful in preventing confusion when using nested If-Then statements.

Iterative

As mentioned above, an iteration section provides a looping function. A loop is

used to perform a sequence of statements several times, thus shortening the number
of statements required. Also, one does not always know in advance how many times
the sequence will need to be repeated, so looping provides a way to determine the
number of repetitions automatically, depending on conclusions derived from script
operation. Looping is done with a While-EndWhile sequence.

A While Loop is a statement sequence that repeats or loops itself while a

particular condition is true or until a particular condition becomes true. A While
loop consists of two parts, the While statement which sets the condition to be
tested for, and the EndWhile statement which terminates the loop. All of the
statements within the boundaries of the While and EndWhile statements will be
performed repeatedly until the conditions in the While statement are no longer
satisfied. Here's an example:

Let�s take a fairly common problem. You are working in an editor program that
numbers the lines with five digit numbers. Therefore, line 1 is listed as 00001.
JAWS spends a lot of time reading the zeros. It would be nice to start reading at
the first non-zero wouldn�t it. This is a good place to use a while loop.
Consider the following script:

Script SayEditLine()
SaveCursor ()
JAWSCursor()
RouteJAWSToPC()
JAWSHome()
While (GetCharacter () == �0�)
NextCharacter ()
EndWhile
SayFromCursor()
RestoreCursor ()
EndScript

Using this script to read the line would eliminate the zeros for us. Here's how it
does this. The first four lines save the original cursor, activate the JAWS
cursor, and route it to the beginning of the line we are on. Then the While loop
looks at each character at the beginning of the line in turn and checks to see if
it's a zero. If it is, it just moves on to the next character and checks it as
well. When it finds one that is not a zero, the condition for continuing to loop
(GetCharacter () == 0) is no longer true, and the While loop is terminated. JAWS
then continues to process the remainder of the script after the While loop. This
involves reading the rest of the line from the cursor to the end of the line. That
leaves out all of the zeros.

There is a warning about the use of While loops which must be mentioned here.
Since the loop continues until a condition becomes true or false, one must be
careful not to set up a loop with a condition which will not become satisfied. To
do so would set up a loop which will cycle forever, an infinite loop. The effect
of this would be to lock up the computer until the program is terminated manually.
Think carefully about the condition meant to terminate the loop to be sure it will
become satisfied at some time. If you find that the computer seems to lock up
after you execute a new script with a While loop in it, this is probably what is
happening. One way to avoid this problem while designing While loops is to include
some statements designed to break the loop after a certain number of repetitions.
An example of this is shown below:

While FirstVariable < SecondVariable

Let BreakOutVariable = BreakOutVariable+1
(Rest of loop would be here.)
If (BreakOutVariable > 100) Then
Return
EndIf
EndWhile

This While loop is designed to run until FirstVariable becomes greater than
SecondVariable. Let's say you made a logic error, and FirstVariable never exceeds
SecondVariable. Without the extra statements designed to prevent this, the loop
would try to run forever. However the second line adds 1 to the variable called
BreakOutVariable each time the loop cycles. When the value of BreakOutVariable
exceeds 100, the If-Then statement at the end of the loop will execute a return and
end the cycle. Once you are sure the While loop is running properly, you can
remove the break out logic.

Homework Assignment #5

Let's use the Sound Recorder program again for this assignment. Last time we wrote
a script for this program, we noted that the counter display above the buttons
shows both the elapsed time and the total time of the sound file. Write a script
using If-Then statements and ElIf statements which checks to see if the elapsed
time is zero. If so, have it say the message, "At the beginning of the recording."
If the elapsed time is greater than zero but less than the total time, have it say,
"Playback only partially complete." If the elapsed time is equal to the total
time, have it say, "Playback is complete," and have it click the "Seek to Start" or
rewind button to return the counter to zero. Then, have the script pause to give
the application time to rewind, and then check the counter to see if it's at zero.
If so, have it say the message, "Rewind complete." If the counter is not zero,
have it say the message, "Rewind failed. Please check your batteries." Also, use
local variables to store the values of the elapsed time and total time. One
possible answer can be found in Appendix A. (See Chapter 14.4.)

User-Defined Functions

You can use the script language to write or edit a user-defined function. The
difference between a built-in function and a user-defined function, as was
discussed above, is that user-defined functions can be modified while built-in
functions, which are hard coded into JAWS, cannot. The difference between a user-
defined function and a script is that a script can be attached to a keystroke and
cannot provide a return while a user-defined function cannot be attached to a
keystroke and does provide a return. User-defined functions run whenever they are
called from within a script or another user-defined function.

Simple Functions

User-defined functions are usually created as a self-contained module of scripting

code that has been designed to accomplish a specific purpose. This is particularly
useful when the job which the function accomplishes is to be performed numerous
times and by different scripts. This allows the function's code to be reused
without having to rewrite it multiple times. All the user has to do is call the
function from another script or function, and the job will be performed. Then the
called function relinquishes control back to the calling script or function which,
in turn, continues with its processing. The simplest type of function does not
receive any data (parameters) from or return any data (returns) to the calling
script. Lets look at an example of a user-defined function that comes from the
script file for Microsoft Excel from an early version of JAWS, EXCEL.JSS. This
script is called NextSheet, and its purpose is to move the focus to the next spread
sheet. Here is the code from the script:

Script NextSheet()
;switches to the next sheet and reads the number
{CONTROL+PPAGE DOWN}
Delay (1)
SayWindowPromptAndText()
EndScript

Note that the script calls a function called SayWindowPromptAndText. You will not
find that function among the built-in JAWS functions. It is a user-defined
function that was written by programmers at Henter-Joyce and is included in
EXCEL.JSS. Here is the code for SayWindowPromptAndText from that same version of
JAWS:

Function SayWindowPromptAndText ()
SaveCursor ()
InvisibleCursor ()
RouteInvisibleToPC ()
If (FindLastAttribute (ATTRIB_BOLD)) Then
SayChunk ()
Else
Say (msg121, OT_MESSAGE) ;"bolded sheet tab not found"
EndIf
EndFunction

Let's now go through the procedure of creating a simple, user-defined function.

We'll have as our goal the creation of a function which speaks our name, just as we
did in our first script. As before, we'll place this function in the Notepad
script file. Follow the steps as outlined below.

Open Notepad from the Start Menu/Programs/Accessories group.

Open the Script Manager by pressing INSERT+0 or by pressing INSERT+F2 followed by S
and ENTER. JAWS will tell you that you are in NOTEPAD.JSS, the script source file
for Notepad.
Choose New Script from the Script menu or use the accelerator key combination,
CTRL+E.
The New Script dialog appears, and we can now name our function and write its
documentation. When the New Script dialog appears, the cursor is in the Script
Name field. Type in SayName. Be sure to capitalize both the S and N, and don�t
put in a space.
Press TAB twice to move to the Synopsis field. Type in the words, �Say our Name.�
(By bypassing the Can be attached to key checkbox without checking it, we have told
the Script Manager that we are creating a function, not a script.)
Press TAB to move to the Description field, and type in the words, �The name of the
person who wrote this function.�
Press TAB to move to the Category field, and type in the word �Test.� The Category
field is an edit combo, so you can pick a category by typing one in or by arrowing
down through the list to find one that is appropriate.
Press TAB to move to the Function Returns field, and arrow down to Void. We choose
Void because our function isn't returning any information to the calling script.
We won�t need any other fields filled in for our script, so TAB over to OK and
press ENTER to close the New Script dialog and insert our blank function into the
editing area.
We are now back in the main text area of the Script Manager, and we have a blank
function where the first line says �Void Function SayName ()� and the last line
says �EndFunction�. We have been placed between these two lines. Arrow up to the
first blank line after the first line, and you are ready to start writing the body
of the function.
You will only need one line for this function. We will use the SayMessage
function. This is similar to the Saystring function we used for our first script,
but it is preferred because it allows the user to specify an output type constant
which is used to tell JAWS how and when to speak the message. This line will be
SayMessage (OT_JAWS_MESSAGE, �My name is XXX�) where XXX is your name. To get this
line into your function, press CTRL+I to open the Insert Function dialog. Then
type S, A, Y, AND m. You should hear JAWS say SayMessage, the name of the built-in
function that has been selected. Press Enter to accept this function.
You will next be asked to supply the output type constant. A list of possibilities
is given in the file HJCONST.JSH. We will choose and type in the most appropriate
one, OT_JAWS_MESSAGE. After typing in the constant and pressing the ENTER key, you
will now be asked to supply the string you wish spoken as a long message. Type "My
name is XXX" and don't forget to include the quotation marks. The next parameter
is the short message required by the SayMessage function. We will not be using a
short message here, so just press ENTER again. Long and short messages will be
discussed in a later section. (See Chapter 8.9.) After you press ENTER again, you
will be returned to the editing area where your function is now complete.
You should now have the following three lines on your page exactly as they appear
below. Remember that close is not good enough as computers expect us to be precise
and perfect. Also, a few extra blank lines are not important. JAWS ignores blank
lines in functions.
Void Function SayName()
SayMessage (OT_JAWS_MESSAGE , �My name is XXX� )
EndFunction
Now we need to save and compile the Notepad script file. Press CTRL+S and you
should hear, "Compile Complete." If not, go back and retrace the steps and try
again.

We have now created a function that will perform the same job as our first script.
This function could be called any time we want our name spoken. To call the
function, we would use a script formulated as shown below.

Script SpeakName ()
SayName ()
EndScript

This simple script will call the function which will say our name. Now it might
seem a little silly to go to all of this trouble when we could accomplish the same
task with our first script. Of course, for a simple case like this that would be
true. However, functions can be long and complicated. In the case of such complex
functions, it should be obvious that it is much simpler to create the code once and
then call it any time we need it. Otherwise, we would have to recreate all of the
code for every single script where it was needed.

The user-defined function we discussed a few paragraphs above,

SayWindowPromptAndText, is the simplest kind of user-defined function because it
does not accept any parameters from and does not return any values to the calling
script. However, user-defined functions can do both of these things. Lets look at
examples of those.

Functions That Require Parameters

The first example is a function that accepts parameters. Remember a parameter is

nothing more than a piece of information you send over to the function for it to
use when it runs. The only reason that we send it at run time rather than include
it as part of the code is because the information may be different each time we run
the function. Note the parameter is declared like a variable but is placed between
the parentheses following the function name instead of after the word "Var" near
the beginning of the script.

Void Function ScriptAndAppNames (string sFileName)

var
string theString

let theString = sFileName

If (GetVerbosity() == beginner) Then
let theString = theString + msg374 ;" settings are loaded"
else
let theString = theString + msg374b ; " settings"
endif
Say (theString, ot_help)
If(GetVerbosity() == beginner) Then
Say (msg376, ot_help) ;"The application currently being used is the "
EndIf
Say (GetAppFileName (), ot_help)
SpellString (GetAppFileName ())
EndFunction

You might think of the string parameter, sFileName, as a doorway through which we
can pass the name of the current script file into the function when it is called.
The parameter�sFileName is not equal to the filename, it is more like a variable
which will hold the filename temporarily so the filename can be passed to the
function which will use it. This calling statement would be formulated as follows:

ScriptAndAppNames ("ApplicationName")

Where ApplicationName represents the name of the application you wish to pass to
the function. This function call is saying the string, "ApplicationName", is to be
passed into the function, ScriptAndAppNames, via the parameter, sFileName. The
function then "knows" this information. Therefore, it can be used in the spoken
messages which are contained within the Say statements. Here the parameter's
information is combined with fixed text to complete the messages which will be
spoken during execution.

Let's take the function we wrote before, SayName, and reformulate it to accept our
name as a parameter instead of having our name contained in the function's code.
Follow the steps outlined below.

Open Notepad from the Start Menu/Programs/Accessories group.

Open the Script Manager by pressing INSERT+0 or by pressing INSERT+F2 followed by S
and ENTER. JAWS will tell you you are in NOTEPAD.JSS, the script source file for
Notepad. Choose New Script from the Script menu or use the accelerator key
combination, CTRL+E.
The New Script dialog appears, and we can now name our function and write its
documentation. When the New Script dialog appears, the cursor is in the Script
Name field. Type in SayName. Be sure to capitalize both the S and N, and don�t
put in a space.
Press TAB twice to move to the Synopsis field. Type in the words, �Say our Name.�
(By bypassing the Can be attached to key checkbox without checking it, we have told
the Script Manager that we are creating a function, not a script.)
Press TAB to move to the Description field, and type in the words, �The name of the
person who wrote this function.�
Press TAB to move to the Category field, and type in the word �Test.� The Category
field is an edit combo, so you can pick a category by typing one in or by arrowing
down through the list to find one that is appropriate.
Press TAB to move to the Function Returns field, and arrow down to Void. We choose
Void because our function isn't returning any information to the calling script.
Press CTRL+TAB to go to the Parameters tab. You will be placed in the existing
parameters field. This field is empty since no parameters exist as yet.
TAB over to the New Parameter edit field and type in "UserName."
TAB twice until you get to the Description edit field and type in "The name of the
user."
TAB over to the Available Types listbox and arrow down to String.
TAB over to the Add button and press the Spacebar to add the parameter. You will
be returned to the New Parameter edit field, but we won't use this again since
we're only adding the one parameter. TAB over to the OK button, and press ENTER.
We are now back in the main text area of the Script Manager, and we have a blank
function where the first line says �Void Function SayName (String UserName)� and
the last line says �EndFunction.� We have been placed between these two lines.
Arrow up to the first blank line after the first line, and you are ready to start
writing the body of the function.
You will only need one line for this function, but it will be slightly different
from the one we used in the SayName function we wrote previously. This line will
be SayMessage (OT_JAWS_MESSAGE, "My name is " + UserName ) where UserName is the
parameter which passes your name into the function. To get this line into your
function, press CTRL+I to open the Insert Function dialog. Then type S, A, Y, and
M. You should hear JAWS say SayMessage, the name of the built-in function that has
been selected. Press ENTER to accept this function.
You will next be asked to supply the output type constant. A list of possibilities
is given in the file HJCONST.JSH. We will choose and type in the most appropriate
one, OT_JAWS_MESSAGE. After typing in the constant and pressing the ENTER key, you
will now be asked to supply the string you wish spoken as a long message. Type "My
name is� + UserName, and don't forget to include the quotation marks. The next
parameter is the short message required by the SayMessage function. We will not be
using a short message here, so just press ENTER again. Long and short messages
will be discussed in a later section. (See Chapter 8.9.) After you press ENTER
again, you will be returned to the editing area where your function is now
complete.
You should now have the following three lines on your page exactly as they appear
below. Remember that close is not good enough as computers expect us to be precise
and perfect. Also, a few extra blank lines are not important. JAWS ignores blank
lines in functions.
Void Function SayName(String UserName)
SayMessage (OT_JAWS_MESSAGE, �My name is " + UserName )
EndFunction
Now we need to save and compile the Notepad script file. Press CTRL+S and you
should hear, "Compile Complete." If not, go back and retrace the steps and try
again.
We have now created a function that will perform the same job as our previous
function. However, the name to be spoken isn't coded into the function, it is
passed in as a parameter. This function could be called any time we want our name
spoken. To call the function, we would use a script formulated as shown below.

Script SpeakName ()
SayName ("XXX")
EndScript

When the function SayName is called, the string "XXX" which represents our name is
passed into the function via the parameter, UserName. The function then has this
data and can speak it as part of the Say message.

Functions That Provide Returns

Now let's look at a function that provides a return. A return is information that
is sent back from the function to the calling script or function when it runs.
This returned information can then be used by the calling script or function. Note
the type of the returned information (i.e., string, Int, Object, handle, or Void)
is declared before the function name. The following function comes from EXCEL.JSS,
the script file for Microsoft Excel.

Int Function GetExcelVersion()

var
handle WinHandle
let WinHandle = GetAppMainWindow (GetFocus())
let WinHandle = GetFirstChild (WinHandle)
if (GetWindowClass (WinHandle) == "Excel4") then
return TRUE ;This is Excel 97
else
return FALSE ; this is Excel95 or earlier
EndIf
EndFunction

You might have figured out that the purpose of this function is to determine
whether we are running Excel 97 or not. What happens is that the function performs
a test to find out if we are in Excel 97. If so, the function returns or sends a
value of true back to the calling script. If not, a value of false is returned.
By returning this value, we merely mean that we are informing the calling script of
the result of the determination. The calling script can then go on and do other
things, depending upon whether the value is true or false, i.e., whether we are
really in Excel 97 or not. Here is an example of how this function would be called
in a way that the return information can be used to make a decision:

If GetExcelVersion== true Then

(Block of statements we want to execute if we're in Excel 97)
Else
(Block of statements we want to execute if we're not in Excel 97)
EndIf

In other words, if GetExcelVersionis true (that is to say, returns a value of true

after being called), then we'll execute one set of statements. If it's not true
(that is, it has returned a value of false after being called), then we'll execute
the other set.

By the way, it's time for you to learn a shortcut which script writers often use in
situations such as these. The following statement is a little shorter than If
GetExcelVersion== true Then, but it means the same thing.
If GetExcelVersion Then

When you see statements like this, it is understood that we imply "== true". It's
left out for convenience, but everyone should understand that "== true" or "== 1"
(which, as we now know is an equivalent statement) is always implied in a statement
like this.

Homework Assignment #6

JAWS announces capital letters by speaking them in a different pitch. Some users
would like to hear words that are all capitalized preceded by the words "all caps"
when they are spelled. Write a function called SayAllCaps which does the following
things:

It should accept as a parameter the word the cursor is on, which is the word to be
tested. Use CurrentWord as the string parameter that accepts the data from the
calling script.
It should check the word to see if it contains any letters which are not
capitalized. As soon as it finds one that isn't, it should return a null string,
that is, two quotation marks with nothing between them. If it finds that all of
the letters are capitalized, it should return an "all caps" string.

Hint - This is a fairly complicated job, so we are going to give you a start. You
should use the built-in function, StringContains, to determine if the word contains
any non-capitalized letters. (This is the only JAWS built-in function which is
case sensitive.) As soon as the test determines that a letter is present which is
not capitalized, a return of a null string should be executed since no further
testing is required. If no lower case letters are found, it should return the "all
caps" string. The function should also return a null string if any numbers are
present to prevent it from saying "all caps" when testing a number. Finally, the
function should contain code to prevent it from saying "all caps" if the cursor is
on a blank or a punctuation mark or any other non-alphabetic character. To
accomplish this, you need to know that all such non-alphabetic characters have
values which are less than the letter, a or greater than the letter, z. You should
test to see if your current word meets this criterion and return a null string if
it does.

Finally, to utilize this function, the final part of the problem is to modify the
script called SayWord which can be found in DEFAULT.JSS. You must modify this
script to call the SayAllCaps function at the appropriate time and perform the
test. SayWord is activated when you press the key combination, INSERT+NUM PAD 5.
The SayWord script has an initial section which uses the built-in function
IsSameScript to check if you've pressed INSERT+NUM PAD 5 twice quickly. Pressing
this keystroke combination twice tells JAWS to spell the word instead of saying it.
Place your function call to the SayAllCaps function at the appropriate place and
call it in such a way that it will speak the string returned by the function just
before it spells the word. If the function has found the word is not all upper
case, it will return a null string and, thus, not say anything. If the function
has found the word to be all upper case, it will return the string, "all caps"
which you will then hear before the word is spelled.

Final Hint - You'll have to call the function within a Say statement to hear your
returned string spoken.

One possible answer can be found in Appendix A. (See Chapter 14.5.)

Event Functions

There is also a special category of user-defined functions whose names end with the
word, event. These are called event functions, and they run automatically whenever
their associated events take place. For example, a function called MouseMovedEvent
runs whenever the mouse cursor changes position. The purpose of these event
functions is to allow JAWS to perform specific tasks automatically without waiting
for the user to initiate the action with a keystroke. Some clarification is
required here. We call these event functions user-defined functions because some
user writes or modifies the statements they contain. However, they are different
from other user-defined functions because users can't invent new event functions.
The ones that exist do so because they have been coded into JAWS to exist. Users
can change the code they use but cannot create new ones. There are several of
these specific system events that can trigger a function. When these events occur,
they often pass parameters to the functions used by the event function's code.
Here is an example of this type of function, The AutoStartEvent, that you will find
in most script files.

Function AutoStartEvent()
If (GetWindowName (GetFocus ())== wn292)
&& SDMGetFocus (GetFocus ())== 18 Then ; on check box
SDMSayControl (GetFocus (), 17) ; say the tip of the day
SDMSayControl (GetFocus (), 18) ; say check box
EndIf ; tip of the day
If (WinWordFirstTime == 0) Then
let WinWordFirstTime = 1
let GlobalWinwordVersion = FALSE
if GetVerbosity() == beginner Then
Say (msg293, OT_MESSAGE) ;"Use Insert plus the letter H for help in various dialog
boxes"
EndIf ; verbosity beginner
EndIf ; first time
EndFunction

The AutoStartEvent occurs whenever a script file loads. This one is from one of
the versions of the Microsoft Word script file. It speaks the tip of the day, if
it is visible, sets up a few variables, and then speaks a JAWS help message. It
also checks to see if this is the first time the AutoStartEvent has run during the
current JAWS session. If so, it changes the value of the WinWordFirstTime variable
from 0 to 1. Then, the next time AutoStartEvent runs, it will skip the help
message. This is a useful technique that can be imitated whenever you want a
script to do something the first time an application loads but not on subsequent
loads. If you want something to happen every time an application loads, just put
the code into the AutoStartEvent function without any conditional statements
surrounding it. This function does not get any parameters or return any values.
Now, lets look at a more complex function that gets parameters passed to it. This
is the NewTextEvent function which handles all text newly written to the screen.

Void Function NewTextEvent (handle hwnd, string buffer, Int nAttributes,

Int nTextColor, Int nBackgroundColor, Int nEcho, string sFrameName)
; Handles all newly written text. If the text is contained in a
; frame, then the frame name is passed as a parameter
if (ProcessSelectText(nAttributes, buffer)) then
return
EndIf
if (sFrameName == "") then
; this text is not associated with a frame
if (nAttributes & ATTRIB_HIGHLIGHT) then
SayHighlightedText(hwnd, buffer)
else
SayNonHighlightedText(hwnd, buffer)
EndIf
else
; this text is associated with a frame
if (nEcho == ECHO_NONE) then
return; frame is being silenced
EndIf
if (nEcho == ECHO_ALL ||
(nAttributes & ATTRIB_HIGHLIGHT)) then
; if Frame echo is set to all or the text being written is highlighted
Say(buffer, OT_BUFFER)
EndIf
EndIf
EndFunction

This is the NewTextEvent function from one version of the default script file.
Note that we can tell this function has no returns because the word Void is at the
beginning of the function begin statement. All parameters for this event are
declared in between the left and right parentheses in the function begin statement.
(Remember that parameters such as these are originally defined in the parameters
tab of the New Script Dialog which is used to define and document a new script or
function.) When JAWS calls this event function, it automatically passes a value for
each of the prescribed parameters in between the parentheses of the function call
statement. The user may not add parameters to or remove parameters from those
which have been predefined for each event function. However, since values for each
of these parameters are passed when the function is called, the user may use the
data provided by any of them while customizing the event function. The following
describes each of the parameters for NewTextEvent.

Handle hwnd is the window handle of the window getting the text.
String buffer is the actual text being written to the window.
Int nAttributes is the attribute of the text being written.
Int nTextColor is the color of the text being written.
Int nBackgroundColor is the background color of the text being written.
Int nEcho is the level of echo set for the frame, if any, that is getting the text.
String sFrameName is the name of the frame, if any, that is getting the text.

As we said earlier, this function is called automatically every time new text is
written to the screen. JAWS automatically passes the values of these seven
parameters to the function when it is called. By using logic and performing
comparisons on this data, the function can determine what type of text has been
written, whether or not it is associated with a frame, and what, if anything, JAWS
should say. If this were not an event function, the user would have to call it
from within another function or script and would, in that function call, have to
specify the variables being used to pass the required information. Because this is
an event function, JAWS does that job automatically whenever new text is written.

It is worthwhile to study this event function to learn how JAWS does these sorts of
comparisons and how functions are called within other functions.

The first line after the initial comments in the function is as follows:

if (ProcessSelectText(nAttributes, buffer)) then

This line is an If-Then statement which calls a function named ProcessSelectText.

This function is involved in speaking text as it is selected and unselected. The
syntax of this statement is exactly the same as if it had been written:

if (ProcessSelectText(nAttributes, buffer) == True) then

The part that says "== true" is always implied if it is left out. So if this
function call returns a value of true, then the next line, Return, will be
executed. What's happening here is that the NewTextEvent function hands off the
task of determining whether the text is being selected or unselected to the
ProcessSelectText function. If this function decides that the text is being
selected or unselected, it does the necessary speaking, and it is not necessary for
the NewTextEvent to do anything further. Thus, when control is returned to the
NewTextEvent function with a return of true, the NewTextEvent function will then
terminate via its own return statement, and the job is complete. If the
ProcessSelectText function returns false, then the text is not being selected or
unselected, the If-Then statement is false, and the NewTextEvent function will
continue. The next line in this function is:

if (sFrameName == "") then

Since the parameter sFrameName passes the name of any frame containing newly-
written text to the NewTextEvent function, this parameter will only have a null or
empty value if the text is not associated with a frame. A null value for the frame
name is indicated by the two quotation marks with no text between them. Thus, if
there is no frame associated with the text, there will be no frame name, a null
value, and the If-Then statement will be true. Then the next statement in the
sequence will be executed. If the If-Then statement is false, meaning there really
is a frame, then execution will jump to a different point in the script which
handles frame-associated text. Assuming no frame, the next statements to be
processed are:

if (nAttributes & ATTRIB_HIGHLIGHT) then

SayHighlightedText(hwnd, buffer)

The first of these two lines is the famous bitwise If-Then statement we talked
about in the section on bitwise operators. If this statement is found to be true,
we know the text is highlighted, and processing is passed off to the next line
which is a function call to the SayHighlightedText function. This function handles
the speaking of all newly-highlighted text. If the bitwise If-Then statement is
false, the SayHighlightedText function is not called, and, instead, the next lines
are executed. These are as follows:

else
SayNonHighlightedText(hwnd, buffer)

In other words, if the text is highlighted, call the SayHighlightedText function.

Else, call the SayNonHighlightedText function. You've probably already figured out
that the SayNonHighlightedText function is called to handle the speaking of non-
highlighted text.

So what happens if the script had decided early on that the new text was, indeed,
associated with a frame? In that case, the function processing would have jumped
down to the following line:

if (nEcho == ECHO_NONE) then

This line compares the value of the parameter nEcho with the constant ECHO_NONE.
If they are found to be equal, this means that the frame echo is set to none, and
nothing should be spoken. In that case, a simple return is executed, nothing is
spoken, and we are done. If this If-Then statement returns false, the echo is not
set to none, and more work needs to be done. Then the next line to be processed
is:

if (nEcho == ECHO_ALL ||
(nAttributes & ATTRIB_HIGHLIGHT)) then
The first part of this If-Then statement asks if nEcho is equal to ECHO_ALL. In
other words, is frame echo set to echo all text? The second part of the If-Then
statement is our old, familiar bitwise operation which determines if the text is
highlighted. If either of these statements turns out to be true, (remember that
the || operator is an or statement), then the next line of the function is
executed. This line is as follows:

Say (buffer, OT_BUFFER)

This statement simply says the contents of the buffer variable which is the text
that has been written to the screen. If the frame is not set to echo all or the
text is not highlighted, the function will terminate without having spoken anything
at all.

Wow, what a complicated job! All of this processing is done automatically by JAWS
in the blink of an eye, every time new text is written to the screen. This is a
perfect example of how JAWS is continually monitoring the screen writes and
deciding what you need to hear. This function embodies many of the aspects of the
JAWS script language which we have been talking about, and you should study it
until you understand it thoroughly. When you do, you will be well on the way to an
in-depth understanding of how the script language works and how to create your own
advanced scripts.

List of Event Functions

The following is a list of the special functions triggered by system events. If

you wish to use these functions in your script writing, You must use the name
exactly as listed here and assign all the prescribed parameters in the function
call in the prescribed order. For more detailed information on any of these event
functions, see the script documentation for each one by calling up the script
documentation dialog in the default script file. Note that this list has been
updated to include event functions from JAWS 3.7. If you are using an earlier
version, you will not have all of the items shown below.

ActiveItemChangedEvent - Triggered when the active element in an object changes.

Parameters:
A handle containing the handle of the window in which the active object or child
has changed.
An integer containing the ID of the current object.
An integer containing the ID of the current object child, such as the new item in a
list or tree control.
A handle containing the handle of the previous window in which the object changed.
An integer containing the ID of the previous object.
An Integer containing the ID of the previous object child, such as an item in a
list or tree control.
AppWillNotSpeakEvent - This event function is only used during JAWS installation
and is not meant for general purpose scripting.
AutoStartEvent - Runs when the script file containing this function loads or gets
focus.
Parameters: None
AutoFinishEvent - Runs when the script file containing this function is closed or
loses focus.
Parameters: None
BottomEdgeEvent - Runs when the active cursor encounters the bottom edge of the
window.
Parameters:
A handle containing the window handle of the window whose edge is
reached.
TopEdgeEvent - Runs when the active cursor encounters the top edge of the window.
Parameters:
A handle containing the window handle of the window whose edge is
reached.
ClipboardChangedEvent - This event is called whenever the contents of the clipboard
is replaced.
Parameters
None
CursorShapeChangedEvent - This event occurs when the mouse pointer shape changes.
Parameters:
A string containing the current cursor type.
DocumentLoadedEvent - Performs a SayAll when a new web page or html document is
loaded and the virtual cursor is active.
Parameters: None
FocusChangedEvent - Runs when the visual focus changes.
Parameters:
A handle containing the window handle of the current window.
A handle containing the window handle of the prior window.
FocusPointMovedEvent - Called whenever the PC cursor moves to a different location
on the screen.
Parameters:
An integer specifying the current horizontal position of the PC cursor.
An integer specifying the current vertical position of the PC cursor.
An integer specifying the previous horizontal position of the PC cursor.
An integer specifying the previous vertical position of the PC cursor.
An integer containing the unit of movement as defined in HJConst.jsh.
An integer specifying the direction of movement as defined in HJConst.jsh.
An integer containing the amount of time that has elapsed since the
movement occurred.
ForegroundWindowChangedEvent - This event is triggered every time a real window
gets the focus.
Parameters
A handle containing the window handle of the real window with focus.
FormsModeEvent - Runs when forms mode is turned on or off.
Parameters:
An integer containing the on or off status of forms mode.
ItemNotFoundEvent - Runs when a requested item is not found in the off-screen
model.
Parameters:
An integer containing the window handle of the current window.
KeyPressedEvent - triggered by any keystroke attached to a script before that
script is run.
Parameters:
An integer containing the numeric key code.
A string containing the key name as it would appear in a key map.
An integer defining whether the key is attached to a Braille display.
An integer defining whether the key is attached to a script.
MenuModeEvent - Runs when the focus enters a menu.
Parameters:
A handle containing the window handle of the current window.
An integer containing the menu mode.
MouseMovedEvent - Triggered when the mouse is moved.
Parameters:
An integer specifying the X coordinate.
An integer specifying the Y coordinate.
NewTextEvent - Runs when new text is written anywhere on the screen.
Parameters:
A handle containing the window handle of the current window.
A string containing the text written.
 An integer containing the attribute of the text.
An integer containing the text color.
An integer containing the background color.
An integer containing the echo setting.
A string containing the frame name of the frame where text is written.
SayAllStoppedEvent - This event is triggered when SayAll is terminated.
Parameters
None
TextSelectedEvent - Runs when text is selected or unselected in virtual mode.
Parameters:
A string containing the text which is being selected or unselected.
An integer describing whether the text is being selected or unselected.
TooltipEvent - This event is called if the jcf option OPT_PROCESSTOOLTIPEVENT is
set to one or on. It is also called by the autographics labeler. This event runs
each time a tool tip appears. It currently is used only to store the text of the
last tool tip in the global string variable strLastTooltip.
Parameters:
A handle containing the window handle of the tool tip.
A string containing the tool tip text.
ValueChangedEvent - This function is triggered when a change of value of an MSAA
object occurs. The MSAA flag must be turned on in your application-specific jcf
file to enable this function.
Parameters:
A handle containing the handle of the window in which the object value
has changed.
An integer containing the ID of the object whose value has changed.
An integer containing the ID of the object child whose value has
changed.
An integer containing the object typecode for the object whose value
has changed.
A string containing the name of the object whose value has changed.
A string containing the value of the object whose value has changed.
WindowCreatedEvent - Runs when a new window appears.
Parameters:
A handle containing the window handle of the new window.
An integer containing the coordinate of the left side of the window.
An integer containing the coordinate of the top of the window.
An integer containing the coordinate of the right side of the window.
An integer containing the coordinate of the bottom of the window.
WindowDestroyedEvent - Runs when a window disappears.
Parameters:
A handle containing the window handle of the window being destroyed.
WindowMinMaxEvent - Triggered when the Minimize/Maximize status of a window
changes.
Parameters:
A handle containing the window handle of the window.
An integer describing the general action taking place in the window.
An integer describing the specific action taking place in the window.
WindowResizedEvent - Triggered when a window is about to be resized.
Parameters:
A handle containing the handle of the window being resized.
An integer containing the left edge of the window being resized.
An integer containing the top edge of the window being resized.
An integer containing the right side of the window being resized.
An integer containing the bottom edge of the window being resized.

The following event functions pertain specifically to MAGic:

ActiveItemChangedMagEvent - This event function is called when the selected item

changes in a list view or a tree view to handle all MAGic specific functions that
must occur when the selected item changes.
Parameters: None
FocusChangedMagEvent - This function is triggered when focus moves from one control
to another. Parameters:
A handle for the window which has the focus.
A handle for the previous window which had the focus.
FocusPointMovedMagEvent - This function is called by FocusPointMovedEvent to handle
all MAGic specific functions that must occur when the focus point moves.
Parameters:
An integer containing the X coordinate of the cursor after the change
in focus point.
An integer containing the Y coordinate of the cursor after the change
in focus point.
An integer containing the X coordinate of the cursor before the change
in focus point.
An integer containing the Y coordinate of the cursor before the change
in focus point.
An integer containing the unit of movement as defined in HJConst.JSH.
An integer containing the direction of movement as defined in
HJConst.JSH.
An integer containing the amount of time which has elapsed since the
movement occurred.
MenuModeMagEvent - This event is triggered when the status of a menu changes.
Parameters:
A handle containing the handle of the menu.
An integer containing the mode of the menu which has changed.
NewTextMagEvent - A Function to perform processing that is specific to MAGic
Tracking when new text is written to the screen.
Parameters:
A handle containing the window handle of the current window.
A string containing the text written.
An integer containing the attribute of the text.
An integer containing the text color.
An integer containing the background color.
An integer containing the echo setting.
A string containing the frame name of the frame where text is written.
ScreenMagnifiedEvent - An event function that runs every time magnification is
activated, deactivated, or the magnification level changes.
Parameters:
An integer which indicates whether or not magnification is on.
An integer which indicates the level of magnification.

Script Writing Techniques

Exploring the Application With the Utility Functions

Before we write a script file, we must have some idea of what we want to accomplish
with it. We also often need to explore the windows in our application to find out
what types of things are present and how they should be spoken. We may also need
to have detailed information on the windows such as class, control ID, and handle
as well as parent-child relationships. There is a set of scripts in the default
script file called the Utility Scripts that may be of some benefit here. These
utilities aid in the writing of scripts by allowing the user to explore the parent-
child interrelationships of the various windows in the application and by
presenting detailed information about each window such as class, control ID, etc.
Each of the utilities is described below along with its assigned keystroke. All of
these utilities are used in the Home Row mode (INSERT+SPACEBAR). The Home Row mode
is a shifted state of the keyboard, somewhat analogous to the shifted states
obtained with the Capslock and numlock keys. This means that you access each
function by using the indicated keystroke after you have turned the home row mode
on by simultaneously pressing INSERT+SPACEBAR. To leave this mode, press
INSERT+SPACEBAR a second time.

The utility functions described below have been updated to contain information
about the new capabilities added in JAWS 3.7. Those using older versions of JAWS
will not have all of the keystrokes described in this section. In addition, a new
feature of the home row functions was added in JAWS 3.7. The user will hear a
spoken announcement when entering and leaving the window tree for the currently
active application. Since it is possible to navigate the child and parent windows
not only of the active application but of other applications, JAWS will alert the
user when navigation into and out of the active application occurs.

INSERT+H - This is the hot key help and lists all of the utilities along with their
keystrokes.
F1 - This key is used to speak information about the current window or control.
What information is spoken depends on the output mode you have selected. This
Output Mode is defined by using the F3 key (see below). The F3 key is like a
selector switch that determines what data you will get, and the F1 key actually
gives you the data. When F1 is pressed twice in quick succession, the requested
information is spelled. Spell Mode does not apply to integers.
INSERT+F1 - This key posts the information requested by F1 at the selected Output
Mode to a message box. This is not available on Output Modes that return integers.
CTRL+F1 - This key posts the information requested by F1 at the selected output
mode to the clipboard.
F3 - This key sets the Output Mode which will be spoken by F1. When F3 is pressed
repeatedly, the Output Mode is cycled in the following order: SayTypeAndText,
window focus or handle, control ID, window class, window type, and first real
window name. This means that this is the data you will hear when you press the F1
key.
SHIFT+F3 - This key cycles through the same settings as F3, but in reverse order.
INSERT+NUM PAD HOME - This key sets the output mode back to SayTypeAndText and can
be used to return to this setting instead of toggling through all of the modes.
TAB - This key moves the JAWS Cursor to the next window of the same logical level
as the one you are currently on and speaks the required information according to
the Output Mode you have set with F3.
SHIFT+TAB - This key moves the JAWS Cursor to the prior window of the same logical
level as the one you are currently on in the tab list and speaks the required
information according to the Output Mode you have set with F3.
F2 - This key moves the JAWS Cursor to the first child of the current window and
speaks the required information according to the Output Mode you have set with F3.
SHIFT+F2 - Moves the JAWS Cursor to the Parent of the current window and speaks the
required information according to the Output Mode you have set with F3.
F4 - This key is a selector which sets the Attribute search Mode. The attribute
search mode is the attribute style that will be searched for using the four hot
keys described below. When repeatedly pressing F4, the attributes are cycled in
the following order: bold, italic, underline, highlight, and strikeout.
GRAVE ACCENT - This key moves the JAWS Cursor to the next requested attribute.
Attribute search modes are defined using the F4 key as described above.
SHIFT+GRAVE ACCENT - This key moves the JAWS Cursor to the prior requested
attribute. Attribute search modes are defined using the F4 key as described above.
CTRL+GRAVE ACCENT - This key moves the JAWS Cursor to the first requested
attribute. Attribute search modes are defined using the F4 key as described above.
SHIFT+CTRL+GRAVE ACCENT - This key moves the JAWS Cursor to the last requested
attribute. Attribute search modes are defined using the F4 key as described above.
F5 - This key routes the home-row focus to the currently-active window.
F6 - This key toggles the automatic announcement of window visibility. When turned
on, this feature will automatically tell the user whether the new window just moved
to with other utility keys is visible or not.
F7 - This key announces the visibility state of the window currently referenced by
the home row.
F8 - This key will read the entire contents of the window referenced by the home
row.
F9 - This key is similar to F1 except that instead of returning information about
the currently-referenced window, it returns information about the object which
currently has the focus of the PC or JAWS cursor.
INSERT+F9 - This key posts the information requested by F9 at the selected Output
Mode to a message box.
CTRL+F9 - This key posts the information requested by F9 at the selected output
mode to the clipboard.
F10 - This key sets the Output Mode which will be spoken by F9. When F10 is
pressed repeatedly, the Output Mode is cycled in the following order: Name, Type,
and Subtype. This means that this is the data you will hear when you press the F9
key.
SHIFT+F10 - This key cycles through the same settings as F10, but in reverse order.
F11 - This key speaks the current setting for the F3 key. This allows the user to
check the setting without actually changing it by using F3.
F12 - This key speaks the current setting for the F10 key. This allows the user to
check the setting without actually changing it by using F10.
INSERT+7 - This key opens the window class reassign dialog and places within it the
class for the window currently referenced by the home row utilities. This behavior
is identical to that obtained by INSERT+7 without home row turned on, but when home
row is on, the window class displayed in the reassign dialog is the one referenced
by the home row rather than just the window class at the active cursor.

Using these utilities helps you to get all the information you need about controls,
parent/child relationships, and text attributes to use in your own scripts.

Homework Assignment #7

Open the WordPad application. Then, turn on the Home Row mode. Use F3 and F1 to
obtain all of the information about the parameters of the main edit window and the
filename edit field of the Open Dialog. The answers can be found in Appendix A.
(See Chapter 14.6.)

Obtaining Window Information With the ScreenSensitiveHelpTechnical Script

If you need a quick readout on a window's Control ID, Class, or Handle, this is
easily obtained via a script called ScreenSensitiveHelpTechnical in the default
script file. This script can be accessed with the CTRL+INSERT+F1 key combination
and will speak the Control ID, Class, and Handle of the window containing your
active cursor. This is a quick way of getting this information if you don't need
all of the other data provided by the Utility Scripts.

Script File Types

As was discussed earlier, there are several types of files associated with script
writing. You can tell what the file type is by its extension.

.JSS - Source script files

.JSH - Header files (included in JSS files)
.JSM - Message files (included in JSS files)
.JSB - Compiled script files
.JKM - Key map files which contain the keystrokes assigned to various scripts.
.JSD - Script documentation files which contain the script names with their
associated synopses and descriptions.
Source Files

Source code for script files is very free-form. You can place spaces or blank
lines anywhere you like. Capitalization is not required and is ignored by the
compiler except for certain string comparison functions such as StringContains ().
Having said that there are a number of formatting considerations. While your code
may be very easy for you to understand, others may not be able to make sense of it
because they don�t know what�s in your mind, and they may not organize their work
in the same way. Therefore, we would like to suggest a few rules of thumb that
will make it easier for others to understand your code and will help you to
understand scripts written by others.

Individual scripts should always be separated by a blank line.

Indent any section of code that is subservient to that above and below it. This
helps the user to sort out the logic of the script. Consider the following script:

Script CheckVerbosity()
If GetVerbosity() == BEGINNER Then
SayMessage (OT_JAWS_MESSAGE, �Beginning verbosity is active.� )
Else
SayMessage (OT_JAWS_MESSAGE, �Beginning verbosity is not active.� )
EndIf
EndScript

Note that If, Else and EndIf are all at the same indent level and the statements
within each section are indented farther. How much you indent is up to you, but we
suggest about five characters. Using tabs to do indents works better than spaces
because indents will be consistent even if you are working in a proportional font.
Each function should be on a separate line.
Here are a few capitalization suggestions:
Begin each statement with a capitalized letter.
Many JAWS standard function names are the combination of two or more words that
describe the function. The first character of each word in a function name is
capitalized. In the previous example, we used GetVerbosity. This helps to have
them spoken correctly. When you create variables and functions, you should use the
same convention.
The structure of the script file is also important.
Start each file with a comment that describes what the file contains and how it is
intended to be used. List any specific information that someone reading this file
needs to know. You might also include a list of variables and how each is used.
It is also important to include the date and nature of any changes and improvements
that have been made since the file was first written. Now someone can read the
first few lines of your file and know all about it.
The next section should be any include statements.
Place any global variable declarations in the next section.
Place any constant declarations in the next section.
The next item in your script file should be the AutoStartEvent function if you
intend to use one. Any code associated with this function automatically runs when
your script file is loaded. This function is normally used to speak any
introductory messages or initialize any global variables to values other than zero.
For instance, in the default script file, the JAWS start up messages about how to
access help are in this function.
Your next script should be one entitled ScriptFileName, the script attached to the
INSERT+Q keystroke. This script will announce the name of the currently active
script file and application. You can find an example of how this script should be
formulated by looking in DEFAULT.JSS. You should substitute the name of your
application for the data being passed to the ScriptAndAppNames function.
Next come the scripts and user-defined functions. Try to choose a logical order so
that anyone reading through your script file will be able to make sense of it. For
instance, if you have one script that will perform an action and another to perform
the opposite action, place them one after the other. Place each function above the
first script or other function that calls it. Not doing this could result in an
error condition.
Use comments, comments, and more comments! Comments provide a road map for anyone
trying to work with your code. Place a comment line just after the script begin
line of each Script or Function that describes the purpose of the script or
function. Place a comment in the code describing any complex statement that may
not be intuitive. Think in terms of someone trying to revise your code and always
give them the help they need. You will even be helping yourself as you may forget
the purpose of a particular section.

Compiled Files

When you have finished writing your code, it must be compiled for use by the JAWS
program. Your file will be given the same name as the application along with
a .JSB extension when you compile it so the JAWS program will know when to load it.
The compilation process is performed automatically by the Script Manager when you
choose Save from the file menu. The source or JSS file is saved, and at the same
time, a compiled JSB file is created and saved. This compilation includes all
header and message files that have been included by the appropriate statements at
the beginning of the JSS file.

Include Files

As we have mentioned before, the JAWS script compiler provides for including other
files into our script file at compile time. Once the compilation is complete,
everything in the included files is part of the JSB file and is available whenever
the script file is active. There are two types of include files:

Header Files are designated by the extension JSH and contain either variable or
constant statements.
Message Files are designated with the extension JSM and contain message statements
with their assigned numbers.

Always group your include statements together near the beginning of your script
file.

Putting global variables and constants into a separate header file and messages
into a separate message file helps to organize your work better. Two files are
provided with JAWS that contain all of the standard global variables and constants.
These are HJGLOBAL.JSH and HJCONST.JSH. They are provided this way so that script
developers can use any of the standard variables and constants by simply including
them in their own script files. Message files are also set up as includes. The
standard one is DEFAULT.JSM. It is not necessary to use a message file for your
script file. Henter-Joyce placed the default messages in a separate file for
simpler translation to other languages. If you do use a message file, it should be
named the same as your script file so that you can easily identify it.

Using Variables

Our earlier section on variables (See Chapter 7.3.3.) showed you what kind of
variables the JAWS language allows and how to declare them. In this section we�ll
discuss when to use them, suggest some naming conventions and show you where to
place them in your script files.

Naming Conventions
This is a touchy subject. Everyone has an opinion, and these opinions often
conflict. Regardless of what naming convention you choose, using one will help
prevent time consuming and embarrassing mistakes. By adopting standards and
sticking to them, you�re guaranteeing that you can come back to this code later and
modify or debug with ease. We in the disability community spend a lot of time
talking about adopting standards. Here�s your chance to contribute. Let�s go over
a few suggestions on creating your standard. What�s in a name? It can be a lot.
Choosing a descriptive name makes a lot of sense. The easiest thing to do is to
name your variable by putting descriptive words together. Try not to make it too
long as you have to type the names, sometimes a lot. If you are naming a global
variable, make its name begin with G_ or Global. You should also capitalize the
beginning of each word as you join them together so JAWS can read the words
correctly, assuming you have the Mixed Case option turned on in the Configuration
Manager. You could carry this further and use Int, Str, Obj, and Hnd within the
names to indicate integer, string, object, and handle variables. Thus,
G_Int_VariableName would be a global integer variable and Str_VariableName would be
a local string variable.

Declaration Placement

Global variables that will be used in more than one script in your file should be
declared near the beginning of the file, right after the include statements. You
indicate the start of the global variable declaration section by placing the word
"Globals" on its own line. Then you place each declaration on a separate line.
Place a comma immediately after each variable name, except for the last one in the
list. While you�re at it add a comment at the end of the declaration stating how
this variable is used. Later on you can refer to this area of the file for
information about any variable that you encounter.

The only time you would declare a variable within a script is if it is a local
variable. Recall that a local variable is only used within the script where it is
defined whereas a global variable can be used within any script in the file. A
local variable should be declared on the first line of the script immediately after
the Script begin statement.

Using Global Variables

Remember that variables that you intend to use in more than one script are declared
as global. In addition to the global variables which you define for your own use,
there is a set of standard JAWS global variables that is very useful for the
creation of scripts. These variables are contained in the file HJGLOBAL.JSH, and
you can use them by placing an include statement for this file at the beginning of
your own script file. Spend a little time going over the global variables defined
in HJGLOBAL.JSH as they are used a lot in the default scripts. There are
descriptions of how each is used. Remember the values contained in these variables
are often modified by the default scripts. Therefore, if you include HJGLOBAL.JSH
in your script file, you can call upon these variables to get specific information
as needed. For instance, checking the contents of GlobalMenuMode will tell you if
you are on the menu bar or in a menu. What we are saying here is that these
HJGLOBAL.JSH global variables are used constantly by the default scripts in JAWS,
and if you understand them and learn how to use them and include them in your own
application script files, you can call upon the values they contain during the
execution of your own scripts.

It is also worth mentioning that, once you have defined and assigned a value to a
global variable in one of your applications, that value is maintained in memory,
even after you close that application. If you later reopen the application, the
global variables you defined will still have their values. The only way you can
truly clear these global variables is by closing and then reloading JAWS.

Using Constants

Remember that a constant is just a label which represents a number or a string of

letters so that the script code is easier to read and understand. You should
include the standard constants file, HJCONST.JSH, in each of your script files and
use the constants in it whenever you can. The versions of these files contained in
the latest releases of JAWS contain many, many categories of constants for use in
different situations. Some of these are quite specialized and of minimal relevance
to most users, so we�ll concentrate on the most important categories here. The
file contains the following important groups, roughly in the order they appear:

Clipboard Constants - These constants all begin with CLIPBOARD_ and are for use
with the ClipboardChangedEvent function.
Keyboard Constants - These all start with Key_ and assign easily-remembered names
to keyboard keys. They are for use with the KeyPressedEvent function.
Window Type Codes and Subtype Codes - These codes map to the type of window.
Remember that even the lowliest control is classified as a window. Therefore,
Every window will return a type code if queried. The push button will return a
window type of 1 or its constant name, WT_BUTTON. There are two functions used to
get this information, GetWindowTypeCode and GetWindowSubtypeCode.

Consider the following If-Then statement from the SayPriorCharacter script OF ONE
VERSION OF DEFAULT.JSS. It is the script that runs when the left arrow key is
pushed. The else leg of this If statement is run when there is no visible PC
cursor. This branch is designed to check to see if we are in a menu. We've added
comments after each section of code describing its purpose.

If CaretVisible() Then ; Is a PC cursor visible

SayCharacter() ; Say the character that we land on
Return ; Quit this script
Else ; A PC cursor is not visible
Let TheTypeCode = GetWindowSubtypeCode (GetCurrentWindow())
; Set an integer variable to the current window type code
If (TheTypeCode == WT_MENU) Then ; Is the current window a menu
Say (msg3, OT_MESSAGE) ;"Menu"
SayWindow (GetCurrentWindow(), READ_HIGHLIGHTED) ; Speak the current
item
Return ; Quit this script
EndIf
EndIf

What's happening here is that the script is deciding what to speak depending on the
SubTypeCode of the window we're in. It should be pretty obvious that this set of
constants and associated numeric codes is very important to JAWS users as it is
from these that we find out what type of a control we are dealing with. You may
want to browse this group of constants in HJCONST.JSH. They all start with WT_ for
window type.

Text Attribute Identifiers - These constants are used for text attribute
comparisons. They all start with ATTRIB_ for attribute and identify different text
attribute types.
Control Attribute Identifiers - These constants begin with CTRL_, and are used to
identify control attributes such as checked, grayed, disabled, etc. These
attributes are analogous to the text attributes discussed above but are used to
describe control characteristics. They are used by a function called
GetControlAttributes which returns a value for all of the control attributes. This
value can be compared to the control attribute constants using bitwise operators to
obtain the control�s characteristics. Bitwise operators were discussed in an
earlier section. (See Chapter 7.3.5.7.)
Commonly Used Constants - These include string and graphic search types that start
with S_, as well as True, False, On and Off.
Output Modes - These are constants which begin with OT_ and which are used to
determine when and how JAWS will speak different types of information. These
output types are very important for customization of user verbosity levels and will
be discussed more fully later. (See Chapter 8.9.)
Item Types - These constants, beginning with IT_, are used to describe the items in
the GetItemRect function.
Modes for the Braille Display - These all start with BRL_ and are used to set
different modes for Braille displays.
Braille Marking Types - These also start with BRL_ and are used for setting up
Braille attribute marking options.
Verbosity Settings - These are BEGINNER, INTERMEDIATE AND ADVANCED levels and
MESSAGE_LONG And MESSAGE_SHORT for long and short message type options.
Button Control ID - These all begin with ID_ and are used with the built-in
function called DLGSelectControls, a function used to display the controls of the
active dialog in a list box. The DLGSelectControls function presents the user with
several possible actions to perform on the control selected in the list box, such
as left single click, right single click, etc. and then returns a Control ID for
the action selected. These constants represent the button Control ID numbers for
the various possible actions.
Button Types - These constants all begin with BT_ and are used with the function
DLGSelectControls. They represent the actions, such as left single click, right
single click, etc., to be included as choices in the dialog. In other words, these
represent the buttons the user will see in the dialog for the various possible
actions to be taken on the item selected in the list of controls.
General - These include testing for active and inactive states, success or failure,
cursor types, various reading and highlight settings and options, graphic search
constants, and pointer attachment.
Option Identifiers Used by SetJcfOption and GetJCFOption Functions - These
constants, all beginning with OPT, are used to retrieve and set, on the fly, all of
the various parameters that are set, permanently, by the Configuration Manager.
Restriction Types - These constants, all beginning with RESTRICT, are used to
describe the restriction state for the JAWS and Invisible cursors.
Cursor Types - These are used to describe various shapes of the mouse pointer.
They begin with CT_. For example, CT_Wait corresponds to the hour glass, and
CT_ARROW represents the arrow pointer.
Menu Modes - These constants describe the active versus inactive states of menus
and menu bars.
Default Files - These constants, beginning with DEFAULT_, describe the default
keyboard layouts.
Magic Focus types - These MF_ constants are for setting how Magic magnifies and
displays the screen.
Tracking Engines - These constants, beginning with TE_, refer to whether JAWS or
Magic is being used to track the screen.
Word delimiters - This single constant is used by the IsWordDelimiter function to
determine if a given character is a word delimiter.
for the Adjust JAWS verbosity dialog - These constants are used to describe various
entries for creation of the Adjust JAWS Verbosity dialog.
Format - These constants begin with FORMAT_ and relate to the various format
options available under the settings menu of the Configuration Manager.
Capitalization Types - These constants, beginning with CAPITALIZATION_, are used by
the SayFormatAndText function to describe capitalization state such as undefined,
lower, cap, and all caps.
Voice context names - These constants, beginning with VCTX_, represent the
different JAWS voices such as Global, Message, JAWS, etc.
Voice Parameters - These are used for various voice parameters such as volume,
rate, pitch, etc. and start with V_.
Movement Units - These constants, starting with UNIT_, represent cursor movement by
various units (character, line, page, etc.).
Movement Direction Values - These constants are used to represent movement in the
forward and backward directions and start with MOVE_.
The String to Use Between Items in DLGSelectItemInList - This constant represents
the separator to be used between items when constructing the item list for
DLGSelectItemInList.
Constants for Use With the WindowsMinMaxEvent - These constants, starting with SW_,
are solely for use with the WindowMinMaxEvent function.
Message Box Type Specifiers - These determine the type of message box (e.g., OK,
Yes/No, etc.)which is to be displayed by the ExMessageBox function. They begin
with MB_.
Message Box Return Values - These constants all start with ID and are used to
represent the values (e.g., OK, Cancel, Retry, etc.) returned by the ExMessageBox
function.

All of the constant categories described above refer, as stated, to the HJCONST.JSH
header file that ships with JAWS. We would not want to give the impression that
these are the only constants available to you. Of course, you can and should
create your own constants, either by declaring them near the top of your script
file or by placing them in an included header file. Using constants whenever
possible makes comprehension of the script file easier and makes it possible to
change the value of a constant everywhere in the file by just changing one
declaration. This is much easier than having to change a value at every location
where it appears in the file.
Homework Assignment #8

Let's say you are about to script an application called SPAMKILLER.EXE. You will
be using a header file, a message file, and the two default HJ global variable and
constant files. Also, you will need to define three additional global variables
called GlobalSpamInteger, GlobalSpamString, and GlobalSpamHandle and three
additional constants defined as SpammerOne =1, SpammerTwo = 2, and SpammerThree = 3
within the script file. Show the beginning of the script file with all of the
statements that do these things. The answer can be found in Appendix A. (See
Chapter 14.7.)

Using Multiple Functions

Sometimes you have to "string" a number of functions together to achieve your goal.
Other situations require "nested" functions, where one function becomes the
parameter for another, which is the parameter for yet another. This can look
rather confusing in the code. The trick is to count up the parentheses. They will
show you how the functions are nested within each other. First we'll look at a
group of functions strung together for a single purpose and then we'll look at a
nested function.

Using Functions Sequentially

It�s pretty rare when you can accomplish a task with a single function. Several
functions in the proper order are usually required. The following code is from a
script file for Visual Basic 4.0. It�s job is to check whether the Toolbox is the
focus window and, if not, make it so and then position the JAWS cursor on the first
tool icon. By the way, we used the home row utility scripts to figure out the
window class of the tool box window, ToolsPalette, before we wrote this script.

Script GoToToolBox()
; This script focuses on the tool box and positions the JAWS cursor
; at the first tool of the tool box
Say ("Tool Box", OT_JAWS_MESSAGE) ; Let the user know what's happening
While GetScreenEcho() != 2 ; Loop through the screen echo settings until we set
screen verbosity to all
ToggleScreenEcho () ; Increment screen echo
EndWhile
If GetWindowClass (GetFocus ()) != "ToolsPalette" Then If we are not already in the
tool box
PCCursor();
{ALT+V} ; View Menu
Pause() ; Time for the menu to appear
{x} ; Select Tool Box
EndIf
Delay(10) ; provide time for tool box to appear
RouteJAWSToPC()
JAWSCursor()
JAWSPageUp()
JAWSHome()
PerformScript ({DOWN ARROW}) ; Regular down arrow with special stuff for the tool
box
EndScript

First we make sure we are in say all screen echo mode.

Next we check to see if we are not in the toolbox by getting the window class of
the current focus window and comparing it to the string, ToolsPalette, which is the
known window class of the toolbox window. (This window class would have been
defined in a constant include file for this script file.) If we are not in the
toolbox, then we must make that the focus window by performing several functions
that will guarantee the end result.
We use the PCCursor function to force the PC cursor active.
We use the keyboard simulation to send an ALT+V to the application. This pulls
down the View menu. Remember that anything in curly brackets is passed to the
application, just as if you'd typed it from the keyboard. Note that there is a
comment there to let anyone reading this know that that�s the purpose of {Alt+V}.
The Pause function then gives the system time to pull down the menu before we
continue.
We use the keyboard simulation to send an X to the application which is the
accelerator key for the toolbox menu item. This is also commented.
Then the EndIf terminates our If-Then sequence.
Now we are sure the toolbox is open and has the focus.
Then we activate the JAWS cursor and position it on the first tool icon.

We've used a number of functions sequentially to accomplish our task.

Using Nested Functions

Here is an example of a script with a nested function wherein functions are used as
parameters of other functions.

Script IsJAWSWindow()
If (GetWindowClass (GetAppMainWindow (GetFocus())) == JFWUI2) Then
Say (msg113, OT_JAWS_MESSAGE) ;�This is the JAWS application window�
EndIf
EndScript

We can find out that the window class of the JAWS window is JFWUI2 by going to the
JAWS window and turning on the home row functions. Using SHIFT+F2 will take us to
the parent window, and F3 will cycle through the output modes until we come to
class. Then F1 will speak the class which is JFWUI2. We want to compare our
window class to that, but first we must make sure that our script is looking at the
correct place. We use the function, GetWindowClass to query a window class. Its
parameter is a window handle, so we give it AppMainWindow which is the parent in
the current application. We use this because JAWS is an application, and we want
to check the window class of that application. AppMainWindow requires a window
handle as its parameter so it knows which application to check. In our case we use
the function, GetFocus, which returns the window handle of the focus window.
Simply said it is: get the window class of the application window that has the
focus.

Homework Assignment #9

Let's go back to the WordPad Open Dialog once again. Open this dialog and look
around to refresh your memory. Write a script that will determine, first of all,
if you are in this dialog. If so, have your script say "In the Open Dialog." Then,
determine if the focus is on the filename edit window. If so, have the script also
say "and in the filename field." If, however, focus is on another control, have
the script say, instead of the second message above, "but not in the filename
field." Finally, if the focus is not even in the Open Dialog, have the script say
"Not in the Open Dialog." Hint - The Open Dialog is a real window. Recall that
this means it is a window that has a title. Use this fact to determine if you are
in the Open Dialog. Use the window class of your current control to determine if
you are focused on the filename field. Second Hint - Look up the function called
GetRealWindow in Appendix C. One possible answer can be found in Appendix A. (See
Chapter 14.8.)

Selecting and Manipulating Cursors

Before you attempt to read something from the screen with a script, it's worthwhile
to review some information about cursors which we covered earlier. (See Chapter
5.3.2.) There are four kinds of cursors, the PC cursor, the JAWS cursor, the
Invisible cursor, and the Virtual PC cursor. If you are editing or entering text,
the PC cursor is where characters would be placed when you type. (This editing or
text insertion form of the PC cursor is also called an insertion point or carat.)
However, when you are using a menu or tabbing through some selections such as
buttons in a dialog box, the PC cursor is the focus. If you wish to read other
areas of a window or read a part of the screen where the PC cursor cannot go, you
can switch to the JAWS cursor. The JAWS cursor can be moved anywhere within the
boundaries of the current real window, making it possible to explore areas of the
screen where the PC cursor cannot go. Since the JAWS cursor always moves the mouse
pointer to its location, the mouse pointer is always positioned and ready to be
clicked at the location of the JAWS cursor should you decide to do so. The third
kind of cursor is called the Invisible cursor. In one way it is just like the JAWS
cursor as its movement is also only restricted by the boundaries of the real
window, but it has no visible entity on the screen since it does not bring the
mouse pointer with it. The Virtual PC cursor is a special case of the PC cursor
which is turned on automatically in certain applications such as Internet Explorer
5, Outlook/Outlook Express, and Eudora 4.X where a Microsoft browser or browser
style viewer is being used. The Virtual PC cursor is created within a special JAWS
buffer and is employed to allow the user to have a cursor that can navigate around
the viewer window even though that viewer does not actually have a normal insertion
point. The user is actually navigating in the virtual buffer created by JAWS and
feels as if navigation were occurring within a word processor type of application.
This makes reading in such applications much easier.

How do we use these cursors? It�s generally impractical and often impossible to go
exploring around the screen with the PC cursor. Therefore, before we go to read
some text from the window, we usually first switch to one of the other two cursors.
One can pretty much use either the JAWS or the Invisible cursor to do the reading
for you, so to some extent it�s just a matter of choice. However, if you plan to
click a button or take some other action with the mouse, it will be necessary to
use the JAWS cursor. Since the mouse pointer accompanies the JAWS cursor in its
travels, it is then a simple matter to click the mouse as it�s already in the
correct position. If you do not wish to move the JAWS cursor from its current
position, or there won�t be any need to click on anything, the Invisible cursor is
the best choice. There is one particular situation which comes to mind when you
definitely won't want to move the JAWS cursor. Sometimes in a Windows application,
informational text will appear somewhere on the screen, usually the status line,
when the mouse pointer is at a particular location. If you move the JAWS cursor to
read the text, the mouse pointer will move with it, and the text will disappear.
In this situation, you must use the Invisible cursor to read such text.

In some cases, it is necessary to move one of the cursors such as the JAWS cursor,
even though you want it to be back in its original location when the script is
finished. For this reason, there are save and restore functions that you can use
to put everything back as it was before your script was executed.

Here is a list of the functions that you can use to select and manipulate the
cursors.

PCCursor() - Activates the PC Cursor.

JAWSCursor() - Activates the JAWS Cursor.
InvisibleCursor() - Activates the Invisible Cursor.
BrailleCursor () - Activates the Braille cursor.
RouteBrailleToPc () - Moves the Braille cursor to the PC cursor.
RouteBrailleToJAWS () - Moves the Braille cursor to the JAWS cursor.
RouteJAWSToBraille () - Moves the JAWS cursor to the Braille cursor.
RoutePCToBraille () - Moves the PC cursor to the Braille cursor, if possible.
RoutePCToJAWS() - Moves the PC Cursor to the JAWS Cursor, if possible.
RouteJAWSToPC() - Moves the JAWS Cursor to the PC Cursor.
RouteJAWSToInvisible() - Moves the JAWS Cursor to the Invisible Cursor.
RouteInvisibleToPC() - Moves the Invisible Cursor to the PC Cursor.
RouteInvisibleToJAWS() - Moves the Invisible Cursor to the JAWS Cursor.
SaveCursor() - Saves the active cursor and its position.
RestoreCursor() - Reactivates the saved cursor and restores it to its original
position.

The next group of functions is used to move the cursor.

PriorCharacter() - Moves the active cursor to the prior character.

PriorWord() - Moves the active cursor to the prior word.
PriorLine() - Moves the active cursor to the prior line.
NextCharacter() - Moves the active cursor to the next character.
NextWord() - Moves the active cursor to the next word.
NextLine() - Moves the active cursor to the next line.
JAWSHome() - Moves the active cursor to the beginning of the line.
JAWSEnd() - Moves the active cursor to the end of the line.
JAWSPageUp() - Moves the active cursor to the top of the window.
JAWSPageDown() - Moves the active cursor to the bottom of the window.
MoveTo - Moves the JAWS or Invisible cursor to the screen coordinates specified by
the user.
MoveToControl - moves the active cursor to a specific control within a window. If
the PC cursor is on when this function is called, the JAWS cursor is turned on
automatically. Otherwise the active cursor is used.
MoveToFrame - Moves the active cursor to the top left corner of the specified
Frame. If the PC cursor is active when this function is used, then the JAWS cursor
is activated and it is moved to the new position, otherwise the active cursor is
moved.
MoveToGraphic - Moves the JAWS cursor, Invisible cursor, or Braille cursor in a
specific direction to find a graphic symbol in the active window.
MoveToWindow - Moves the active cursor to the specified window. If the window
contains text, then the cursor is positioned on the first character. Otherwise, it
is positioned at the window's center. If the PC cursor is active when this
function is used, then the JAWS cursor is activated and it is moved to the new
position.
PriorChunk - Moves the active cursor to the prior chunk of text. A chunk of text
is a section or block of text that is written to the screen at one time.
NextChunk - Moves the active cursor to the next chunk of text. A chunk of text is
a section or block of text that is written to the screen at one time.

Note that If your purpose is to read something located on the screen, you would
usually follow a move function with one of the say functions.

Here is an example of saving the current cursor, switching cursors, moving the
cursor, reading some text and then returning to the original position with the
original cursor:

Script ReadBottomLine()
Var ;Declare our local variables
Int TheTypeCode ;We have an integer variable called TheTypeCode
Let TheTypeCode = GetWindowSubtypeCode (GetCurrentWindow()) ;Find out what type of
window
;we're in and assign it to TheTypeCode variable.
SaveCursor() ; Save the current cursor and position
InvisibleCursor() ; Switch to Invisible cursor
RouteInvisibleToPC() ; Bring the Invisible cursor to the PC cursor
If (TheTypeCode == WT_MENU) Then ; If we are in a menu
MoveToWindow (GetAppMainWindow (GetCurrentWindow())) ; Refocus on the main window
JAWSPageDown () ; Go to the bottom
JAWSHome() ; Go to the left most position
NextWord() ; Move one word to the right
SayChunk() ; Says the chunk of text that was written to the screen together
Else
JAWSPageDown() ; Go to the bottom
SayLine() ; Say the line
EndIf
RestoreCursor() ; Go back to the original cursor and position
EndScript

This is the script that reads the bottom line of a window. Usually this is where
the status bar is located. The PC cursor is not allowed to go to this location, so
we must switch to the Invisible cursor and use it to read this line. Notice that
there is a SaveCursor function before taking this action and a RestoreCursor
function after. That way, everything is the same as before and after reading the
status bar. This script uses the subtype Code of the window to determine what type
of window we are in and, therefore, what script statements need to be used to read
it.

Sending a Keystroke

If you need to send a keystroke or keystroke combination from a script (that is to

say, if you want the script to enter that keystroke just as if you were entering it
from the keyboard), place the keystroke name in braces. For example {CONTROL+H}
sends a CTRL+H to the system. This technique can also be used to send alphanumeric
characters. Thus, {h} will send the letter h to the application you are using.
Each letter you need to send must be placed within its own set of braces. If you
need to send more than a couple of letters, you may wish to use the TypeString
function which will send an entire string of characters to the application at one
time.

Making Your Scripts Compatible With Custom Verbosity Levels

Starting with version 3.7, JAWS allows the user to customize the beginner,
intermediate, and advanced verbosity levels to suit personal preferences. This
means that the user can select what type of feedback will be heard from JAWS in a
variety of situations at each verbosity level. These choices are made in the
Configuration Manager under the Set Options menu by choosing the item titled
�Verbosity.� This opens the Verbosity Options dialog. In this dialog, one sees,
in addition to the three radio buttons which allow the user to specify the
preferred verbosity level, three buttons which allow for the customization of each
level. By activating any of these buttons, the user is placed in a new dialog,
either the beginner, intermediate, or advanced preferences dialog, which contains a
list box wherein each item can be checked or unchecked with the SPACEBAR.
Unchecking an item means it will not give feedback at that verbosity level. Then,
one can tab over to a pair of radio buttons which select whether short or long
messages will be heard at that verbosity level.

So, how does JAWS know when to speak a particular type of information and how to
customize that speaking based upon the user preferences described above? To do
this, script writers use a set of constants called output types. These are defined
in the file, HJCONST.JSH. These constants all begin with the letters OT_. For
example, one of the output type constants is OT_APP_START. If you look at the
first entry in the Items to be Spoken list mentioned above, you will see that it is
called �Application Start Message.� This is the JAWS message you frequently hear
when you first start an application. If this item in the list is checked, it means
JAWS is being instructed to speak the messages contained in SayMessage functions
that use the OT_APP_START constant. For example, a SayMessage function formulated
as shown below will speak its message when the Application Start Message item is
checked in the Items to be Spoken list.

SayMessage (OT_APP_START, MESSAGE_L, MESSAGE_S)

If the Application Start Message item is not checked, then SayMessage functions
using this output type will not get spoken. MESSAGE_L AND MESSAGE_S represent
constants defined by the script writer to represent long and short versions of the
particular message and are placed in a JSM header file for the particular
application. Whether the long or short version is spoken depends upon whether the
user has selected the long or short JAWS message radio button in the preferences
dialog.

Other items in the Items to be Spoken list and their corresponding output types are
JAWS Message (OT_JAWS_MESSAGE), Screen Message (OT_SCREEN_MESSAGE), Control Name
(OT_CONTROL_NAME), Control Type (OT_CONTROL_TYPE), Dialog Name (OT_DIALOG_NAME),
Dialog Text (OT_DIALOG_TEXT), Document Name (OT_DOCUMENT_NAME), Selected Item
(OT_SELECTED_ITEM), Item State (OT_ITEM_STATE), Position Information (OT_POSITION),
Error Message (OT_ERROR), Item Number (OT_ITEM_NUMBER), Tool Tip (OT_TOOL_TIP),
Status Information (OT_STATUS), Control Group Name (OT_CONTROL_GROUP), Smart Help
Messages (OT_SMART_HELP), and Select (OT_SELECT). When constructing scripts which
give verbal feedback to the user, care should be taken to use the correct output
type constant so that the user�s verbosity preferences will be honored.

Synchronizing Documentation

After you do any editing of your script file, especially editing that includes
adding or deleting scripts by pasting them in from elsewhere or by highlighting and
deleting, it is wise to synchronize the documentation. Every script should have a
corresponding documentation entry in the JSD file of the same name. You are, of
course, prompted for this information when you create a script, but during the
editing process, there might be scripts without documentation entries and
documentation entries for scripts that no longer exist. That's why we have the
Synchronize Documentation item in the Script Manager File menu. Here are the steps
that Script Manager performs when you choose this menu item:

The Script Manager looks in the JSD file for a documentation entry for each script
in the JSS file and adds a blank entry for each that is missing. (You should go
through any scripts that you think might have blank entries and type in the proper
Synopsis and Description after the synchronization process.) You will note, when
you bring up the documentation dialog, that if you have a script in your
application file with the same name as one in the default file, the documentation
from the Default script has been placed in the fields for your script. You may
need to modify this documentation to match how this script or function works with
your application.
Script Manager checks the JSD file for any documentation entries that no longer
have corresponding scripts in the JSS file and asks if you want to delete the
documentation entry.

The synchronization command is also useful when pasting scripts into a script file
from a different script file. The process will use the same techniques described
above to place blank documentation into the JSD file for the pasted scripts. This
should be filled in with the appropriate information.

Using this synchronization process ensures that your scripts and documentation are
always current. Remember, JAWS uses the Synopsis and Description for Keyboard Help
when the user presses the corresponding key for your script. Therefore, keeping
your documentation current will help all users of your scripts.

Debugging

Volumes have been written about debugging programs. The most important thing to
remember is that it takes a different mind set than normal diagnostics. Diagnosing
a problem usually starts with the assumption that whatever you are working on was
once working and is now broken. Therefore, if you simply follow the logical flow
from start to finish, you will find the errant part. Debugging something that
hasn't worked yet means that you cannot assume that even the flow is correct. How
does this relate to debugging our script file? It's simple. Do not assume that
just because you intended for the flow to be a certain way, that it will be. JAWS
may not always think the same way you do or, heaven forbid, you may have left out
some vital statements. One of the most helpful techniques for finding logical
errors is to go through the script line by line, pretending you are the computer.
Do exactly what the script says to do, not what you think you told the computer to
do. You may find, to your surprise, that you actually gave an instruction that is
quite different from what you intended. Correct these mistakes as you find them,
and then continue on through the script, checking each statement to see if it's
really doing what you thought. Here are some other tools that can help you in the
debugging effort.

The JAWS Script Compiler

The first big help is the script compiler. It checks the syntax of your statements
and also makes sure that you complete each sequence correctly. It displays an
error message when you try to compile a script with a mistake in it. Those of you
who have written macros for JAWS in the past will notice that the compiler errors
for scripts are more descriptive. After you dismiss the error dialog, the cursor
will be placed in the script near the error or what the compiler thinks is the
error. You must understand that the compiler can not always know exactly where the
mistake is. If you use several If-Then statements that are nested, for example,
and you forget to use the correct number of EndIf statements, the compiler will
flag an error, but the cursor may not be located where the missing EndIf statement
should have been. The cursor may be several lines away from that location. The
compiler can only tell you that your If-Then loops are not formulated properly and
that an If statement must be followed by an EndIf statement. It's up to you to
find out where you intended to put that missing statement.

Include files are examined as they are included. Always place the include
statement in your script file before you use anything in the include file. For
instance, you must include HJCONST.JSH before using any of the constants in it. Of
course, if you are laying your script file out properly, all of your includes will
be near the beginning of the script file anyway.

Erroneous Activity

By erroneous activity, we mean the script is working (i.e., it has compiled

properly) but may not be working as intended. Once your script file compiles
without error, it's time to test it in its intended environment. It is not
necessary to restart JAWS before testing, unless you are modifying the default
script file. Just switch to the application and test. Here are a few tips to make
the testing process easier:

Fragments - Whenever possible, compile fragments separately and test to see if they
work by themselves.

Messages may be inserted at crucial points in your code so JAWS tells you what it's
doing. You can put Say messages into crucial parts of a script to see if they're
really executing when you think they should be. A series of these messages that
say slightly different things can be very informative in helping you decipher if
the code is being executed in the order you intended and branching is occurring
correctly. For instance, Say messages in each leg of an If statement will inform
you of which leg was executed. You can also use the SayInteger function to inform
you of the values of integer variables and how these values are changing during
script execution. You may find that these variables do not have the values you
expected at certain points during script execution. The SayInteger function may
also be useful in helping you keep track of integer variable values during the
execution of a While loop.

Many errors of operation can be traced to the failure to save and restore states
properly. This refers to cursor states, screen echo states, verbosity states, etc.
Anytime you have to change a state for your purposes, be sure to return to the
original state. For instance, changing screen echo to All so that you can hear a
help bubble spoken is fine, but don't leave the system set that way as it will be
very confusing to the user.

Debug Scripts - You can create debug scripts that report all sorts of information
like which cursor is active, what's contained in variables, and various window
properties. Here are a couple of scripts you can copy and paste into your script
file and modify to report information back to you.

Script SayVars
Say ( MyVariable, OT_DEBUG) ; Fill in the name of your variable
; Copy the preceding line for each of your variables
EndScript

Script WindowInfo
Say ( GetWindowClass (GetFocus ()), OT_DEBUG) ; Window class of focus control
Say ( GetWindowClass (GetParent (GetFocus ())), OT_DEBUG) ; Window class of the
parent
UtilitySayInfoAccess() ; Control name
EndScript

Interactions of Your Scripts with Event Functions - You must keep in mind that JAWS
has the event functions that are present in the default script file which may
trigger automatically as an application is running. These event functions can
interact in unexpected ways with the scripts you are writing. For example, you may
place reading functions in your script to read certain parts of the screen at
certain times, only to find that the information is being spoken twice. This
probably means that one of the event functions such as the NewTextEvent function or
the Focused Changed Event function is being called to speak the text automatically,
and your script is saying it a second time. You won't find the problem merely by
analyzing your script since it isn't your script which is speaking the information
twice. That's why it's important for you to have an understanding of what the JAWS
event functions do and when they will be called by an application.

Homework Assignment #10

The following script contains an error on each line. Identify those errors and
rewrite the script correctly. The answer can be found in Appendix A. (See Chapter
14.9.)

Script SayDefaultButton (Int Button )

vars
string DefaultButtonName,
if (DialogActive ())
let DefaultButtonName == GetDefaultButtonName
if (DefaultButtonName != " ") then
if (GetVerbosity () = 0) then
Say ("msg70", OT_JAWS_MESSAGE) ;"default button is"
EndIf ()
Say (DefaultButtonName), OT_CONTROL_NAME)
Else ()
Say (msg444, OT_JAWS_MESSAGE) : "Can not determine default button in
this dialog box "
End If
Else ()
Say (msg71, OT_JAWS_MESSAGE ;"not in a dialog box"
EndIf ()
End Script

Strategies for Attacking New Applications

When you first open a new application, especially one which isn't "speech
friendly," it can be very difficult to decide how to go about learning the
application layout and how to customize it for better access. This manual has
introduced you to the scripting tools that will help you do this. One strategy for
approaching these new applications is shown in Appendix E. Here you will find some
ideas on how to approach the problem of analyzing and scripting a new application
in combination with the use of other JAWS features such as the use of frames.

Guidelines for Creating Distribution Script Files

We have suggested numerous guidelines to observe when creating script files, such
as using plentiful comments and filling out the script documentation forms
properly. Of course, these are recommendations, and nobody can force you to follow
these rules.
Variable Names - Use meaningful variable names followed by a comment when the name
is not a sufficient description.
Comments - Place comments immediately after the beginning of each script or
function describing its purpose. Comments should also be placed with in complex
statements where the purpose is not obvious such as complex "If-Then-Else"
statements".
Messages - All spoken or Braille messages should be put into the message file for
the current application where they can be referenced by the script. These messages
should never be placed with in quotes following the Say or SayMessage in the JSS
file itself. Obeying this rule makes translation of the messages to other
languages much simpler.
Script Documentation - Fill in the synopsis and description fields in the new
script dialog. These should be accurately and completely filled in as they are
used in the INSERT+1 keyboard help. For example, in the script
SayTextAndAttributes, you will find the following synopsis and description:
Synopsis - Speaks changes in attributes as it reads the text in the active window.
Description Reads the visible text in the active window without moving the cursor.
As it passes over changes in attributes, they are announced.
Make sure your script file includes customized versions of the HotKeyHelp, the
ScriptFileName, and if necessary, the ScreenSensitiveHelp scripts.

Converting Macro Files

You can use the Script Manager to convert macro files that you created for versions
of JAWS before 3.0. The following describes the steps that Script Manager uses to
convert macro files to script files.
First, Script Manager requires some input from you. When you choose Import Macro
File from the File menu, you must enter the file name of the macro file. Script
Manager uses this information to determine the path and file name of the resulting
script file. You must also choose the environment for which the macro file was
created: Desktop, Laptop, or Both.
Script Manager creates an empty script file based on the target path and file
name.
Include files are processed as follows:
A message file is copied to the target directory, renamed with a JSM extension and
the include statement is added to the JSS file.
Macros in include files are moved to the JSS file and converted. The conversion
procedure is as follows.
If there is a global variable or constant definition section in an include file, a
JSH file is created and these are placed there. An include statement for this
header file is added to the JSS file.
Macros are converted as follows: If a matching keystroke is found in the default
key map file based on the chosen environment, the script is named appropriately.
If a matching keystroke is found in the "Old Keys" section of the default key map
file, the macro is converted to a JAWS function with the appropriate name.
If no match is found, the script is named with the file name followed by a number.
A key map file is created with assignments based on the original macro keystrokes.
Macros that are converted to user-defined functions are not given key assignments,
but a comment is placed after the function name with the original macro keystroke.
Each PerformMacro is converted to a PerformScript, unless the called macro was
converted to a JAWS function. In that case the PerformMacro is converted to a
function call.
The resulting script file is opened in Script Manager.
The previous version of JAWS required a space between quotes to denote a null
value. Nulls in the current version are denoted by just two quotes with no space
in between. If your macro file contained these tests for nulls, you will need to
remove the space between quotes manually.
The last step is for you to go through the scripts, change the names, if necessary,
and write documentation for each. If you had macros which served as functions,
convert them to user-defined functions. Then compile the new script file.
Note: If you are making extensive changes to the scripts and functions, you may
want to compile after each change.

Acknowledgments

I would like to express my sincere appreciation to Glen Gordon, Mike Pedersen,

Joseph Dunn, Sean Murphy, Glen Sepke, James Puzzuoli, Les Kriegler, and Dusty
Vorhees for their tremendously helpful technical information, ideas, and
suggestions. I would also like to acknowledge Frank Dipalermo who originally wrote
the first macro and script manuals which served as the starting point for this
project.

Appendix A

Answers to Homework Assignments

Answer to Homework Assignment #1

Script LastFourFiles ()
SpeechOff ()
{Alt+F}
Pause ()
NextLine ()
NextLine ()
NextLine ()
NextLine ()
NextLine ()
NextLine ()
NextLine ()
SpeechOn ()
SayLine ()
NextLine ()
SayLine ()
NextLine ()
SayLine ()
NextLine ()
SayLine ()
SpeechOff ()
{escape}
{escape}
Pause ()
SpeechOn ()
EndScript

**********

Answer to Homework Assignment #2

Script SpeakWindowState ()
JAWSCursor ()
SaveCursor ()
RouteJAWSToPC ()
JAWSPageUp ()
JAWSEnd ()
PriorWord ()
SayWord ()
RestoreCursor ()
PCCursor ()
EndScript

Note that in this example we activated the JAWS cursor before using the SaveCursor
function. Since the JAWS cursor is the active cursor when the SaveCursor function
is performed, it is the JAWS cursor which will be returned to its original position
by the RestoreCursor function. The PCCursor () function at the end will turn the
PC cursor back on. This is necessary since the script turned on the JAWS cursor
when it was run.

The extra credit answer is shown below:

Script SpeakWindowState ()
InvisibleCursor ()
SaveCursor ()
RouteInvisibleToPC ()
JAWSPageUp ()
JAWSEnd ()
PriorWord ()
If GetWord () == "Restore Symbol" Then
Say ("Maximized", OT_STATUS)
ElIf GetWord () == "Maximize Symbol" Then
Say ("Restored", OT_STATUS)
Else
Say ("Couldn't find the symbol", OT_JAWS_MESSAGE)
EndIf
RestoreCursor ()
PCCursor ()
EndScript

******

Answer to Homework Assignment #3

Script PlaybackPosition ()
SaveCursor ()
RouteInvisibleToPC ()
InvisibleCursor ()
JAWSPageUp ()
NextLine ()
NextLine ()
NextLine ()
JAWSHome ()
SayMessage (OT_JAWS_MESSAGE, "Current time is", �Time is�)
SayWord ()
SayMessage (OT_JAWS_MESSAGE, "seconds out of" )
NextWord ()
NextWord ()
SayWord ()
SayMessage (OT_JAWS_MESSAGE, "seconds" )
RestoreCursor ()
EndScript

******

Answer to homework Assignment #4

Include "JAWSWINS.JSH"
Include "JAWSWINS.JMH"
Include "HJCONST.JSH"
Include "HJGLOBAL.JSH"

******

Answer to Homework Assignment #5

Script CheckAndReset ()
Var
String TotalTime ;Holds the value of the total time of the sound file
SaveCursor ()
RouteInvisibleToPC ()
InvisibleCursor ()
JAWSPageUp ()
NextLine ()
NextLine ()
NextLine ()
JAWSEnd ()
PriorWord ()
Let TotalTime = GetWord ()
JAWSHome ()
If GetWord () == "0.00" Then
SayMessage (OT_JAWS_MESSAGE, "At the beginning of the recording", )
ElIf GetWord () != "0.00" && GetWord () < TotalTime Then
SayMessage (OT_JAWS_MESSAGE, "Playback only partially complete" )
ElIf GetWord () == TotalTime Then
SayMessage (OT_JAWS_MESSAGE, "Playback is complete." )
JAWSCursor ()
RouteJAWSToPC ()
JAWSHome ()
Pause ()
LeftMouseButton ()
Pause ()
InvisibleCursor ()
If GetWord () == "0.00" Then
SayMessage (OT_JAWS_MESSAGE, "Rewind complete" )
Else
SayMessage (OT_JAWS_MESSAGE, "Rewind failed. Please check your batteries." )
EndIf
EndIf
EndScript

Note - You may hear JAWS say some additional phrases like "Seek to Start" or "Seek
to End" when it performs the rewind. This is Okay.

******

Answer to Homework Assignment #6

String Function SayAllCaps (string CurrentWord)

If CurrentWord < "a" || CurrentWord > "zzzzz" Then
Return ""
EndIf
If (StringContains (CurrentWord, "a")) || (StringContains (CurrentWord, "b"))
|| (StringContains (CurrentWord, "c")) || (StringContains (CurrentWord, "d"))
|| (StringContains (CurrentWord, "e")) || (StringContains (CurrentWord, "f"))
|| (StringContains (CurrentWord, "g")) || (StringContains (CurrentWord, "h"))
|| (StringContains (CurrentWord, "i")) || (StringContains (CurrentWord, "j"))
|| (StringContains (CurrentWord, "k")) || (StringContains (CurrentWord, "l"))
|| (StringContains (CurrentWord, "m")) || (StringContains (CurrentWord, "n"))
|| (StringContains (CurrentWord, "o")) || (StringContains (CurrentWord, "p"))
|| (StringContains (CurrentWord, "q")) || (StringContains (CurrentWord, "r"))
|| (StringContains (CurrentWord, "s")) || (StringContains (CurrentWord, "t"))
|| (StringContains (CurrentWord, "u")) || (StringContains (CurrentWord, "v"))
|| (StringContains (CurrentWord, "w")) || (StringContains (CurrentWord, "x"))
|| (StringContains (CurrentWord, "y")) || (StringContains (CurrentWord, "z"))
|| (StringContains (CurrentWord, "1")) || (StringContains (CurrentWord, "2"))
|| (StringContains (CurrentWord, "3")) || (StringContains (CurrentWord, "4"))
|| (StringContains (CurrentWord, "5")) || (StringContains (CurrentWord, "6"))
|| (StringContains (CurrentWord, "7")) || (StringContains (CurrentWord, "8"))
|| (StringContains (CurrentWord, "9")) || (StringContains (CurrentWord, "0")) Then
Return ""
EndIf
Return "All Caps"
EndFunction

Script SayWord()
If (IsSameScript ()) Then
Say (SayAllCaps (GetWord ()), OT_MESSAGE)
SpellWord()
AddHook (HK_SCRIPT, "SpellWordHook")
Else
SayWord ()
EndIf
EndScript

******

Answer to Homework Assignment #7

Edit Window:

SayTypeAndText - Edit
Focus - This is a window handle, so it is always changing
ControlID - 59648
Class - Edit
Type - RichEdit
SubTypeCode - 3
Real Name - Document WordPad (assuming you have not loaded a file)

Filename Window:

SayTypeAndText - Filename Edit

Focus - This is a window handle, so it is always changing
ControlID - 1152
Class - Edit
Type - Edit
SubTypeCode - 3
Real Name Open

Note - If you look in HJCONST.JSH, you will find that a SubTypeCode of 3 is equal
to an edit window. In these cases, the SubTypeCode does not provide any more
information than the class. Also, note that the two windows have different
ControlID numbers, even though they are both edit windows.

******

Answer to Homework Assignment #8

;This is the script file for SPAMKILLER.EXE, created by Michael Glen
;This file was last updated on July 4, 1776.

Include "SPAMKILLER.JSH" ;Header file

Include "SPAMKILLER.JSM" ;Message file
Include "HJCONST.JSH"
Include "HJGLOBAL.JSH"

Globals
Int GlobalSpamInteger,
String GlobalSpamString,
Handle GlobalSpamHandle

Const
SpammerOne = 1
SpammerTwo = 2
SpammerThree =3

******

Answer to Homework Assignment #9

Script IsThisOpenEdit ()
If GetWindowName (GetRealWindow (GetFocus ())) == "Open" Then
Say ("In the Open dialog,", OT_MESSAGE)
If GetWindowClass (GetFocus ()) == "Edit" Then
Say ("and in the filename field.", OT_MESSAGE)
Else
Say ("but not in the filename field.", OT_MESSAGE)
EndIf ;Are we in the edit field?
Else
Say ("Not in the Open dialog", OT_MESSAGE)
EndIf ;Are we in the Open dialog?
EndScript

******

Answer to Homework Assignment #10

Each error is indicated below by a line starting with *** after the line containing
the error.

Script SayDefaultButton (Int Button )

***Scripts do not use parameters, only functions use them.
vars
***It should be Var, not Vars
string DefaultButtonName,
***The last or only variable should not have a comma after it.
if (DialogActive ())
***There should be a "Then" at the end of the line.
let DefaultButtonName == GetDefaultButtonName
***In this type of statement, where you are assigning a value, there should only be
one =.
if (DefaultButtonName != " ") then
***There should not be a space between the quotation marks.
if (GetVerbosity () = 0) then
***There should be two = (i.e., ==) in this statement.
Say ("msg70", OT_MESSAGE) ;"default button is"
***There should not be any quotes inside the parentheses. This would say MSG70
instead of reciting the actual message.
EndIf ()
***No parentheses are used after an EndIf.
Say (DefaultButtonName, OT_CONTROL_NAME))
***There is an extra ) at the end.
Else ()
***There should not be a () after an Else statement.
Say (msg444, OT_MESSAGE) : "Can not determine default button in this
dialog box "
***The comment should begin with a semicolon, not a colon.
End If
***There is a space in the EndIf that shouldn't be there.
Else ()
***No () after an Else statement.
Say (msg71, OT_MESSAGE ;"not in a dialog box"
***There should be a ) after OT_MESSAGE.
EndIf ()
***No () after an EndIf statement.
End Script
***There should not be a space in EndScript.

The script as it should be and as it appears in DEFAULT.JSS is shown below.

Script SayDefaultButton ()
var
string DefaultButtonName
if (DialogActive ()) then
let DefaultButtonName = GetDefaultButtonName ()
if (DefaultButtonName != "") then
if (GetVerbosity () == 0) then
Say (msg70), OT_MESSAGE ;"default button is"
EndIf
Say (DefaultButtonName, OT_CONTROL_NAME)
else
Say (msg444, OT_MESSAGE) ; "Can not determine default button in this
dialog box ")
EndIf
else
Say (msg71, OT_MESSAGE) ;"not in a dialog box"
EndIf
EndScript

Appendix B

Description of the Script Manager Menus

Here is a brief description of the selections available under the various pull down
menus of the menu bar of the Script Manager. Only items which are unique to the
Script Manager or perform unusual functions are described. Others which are
standard to Windows applications are simply noted as �standard function.� Many of
the functions discussed have accelerator keys which are listed in the menus and
which you will probably want to learn.

File Menu

New: standard function

Open: standard function
Open Default File: opens the default JAWS script file, DEFAULT.JSS.
Close: standard function
Save: Saves the file, but also compiles and saves a binary JSB version if saving a
JSS file.
Save As: standard function
Save Without Compile: saves any file and does not compile a JSS file.
Import Macro File: used to import a macro file from earlier versions of JAWS.
Synchronize Documentation: Used to make sure the script and documentation files
concur. Also, when pasting in scripts from another JSS file, it will copy
documentation into the related JSD file. For more information, see "Synchronizing
Documentation" under Script Writing Techniques.
Print: standard function
Print Preview: standard function
Print Setup: standard function
Exit: standard function

Edit Menu

All functions of the edit menu are entirely standard, except the one listed below.

Select Script: Selects the entire script in which the caret is located.

Script Menu

New Script: Opens the New Script dialog for creating a new script.
Delete Script: Deletes the script where the caret is located.
Insert Function Call: Brings up the Insert Function dialog for adding a function to
a script.
Insert Perform Script: Brings up the Insert Perform Script dialog for calling
another script. This is similar to calling a function, but it calls another key-
bound script instead.
Next Script: Moves the caret to the beginning of the next script in the file.
Prior Script: Moves the caret to the beginning of the current script or the prior
script, depending on caret location.
Go To Line: Moves the caret to a specific line number. Line numbers are shown at
the page bottom.
Script List: Brings up the Script List dialog which shows the scripts in the
current file in alphabetical order. Pressing ENTER on a script name takes you to
that script.

View Menu

Documentation: Brings up the Script Information dialog which contains all of the
documentation for the current script.
Toolbar: standard function
Status Bar: standard function
Zoom: standard function

Window Menu

All items in the Window menu perform standard functions.

Help Menu

Help Topics: standard function

keyword Help: Brings up the Keyword Help dialog which contains help for the script
or function on which the caret is located.
About Script Manager: standard function

Appendix C
The Most Important Built-In Functions

Note - Most of the entries in the following list are in alphabetical order. A few
were moved slightly out of order, however, to place them near functions with
similar or related functionality. This list has been updated to reflect new
functions added in JAWS 3.7. Those using earlier versions will not have all of the
functions shown here.

ActivateMenuBar - Activates/deactivates the menu bar for the active program. Same
as pressing and releasing the ALT key.
ActivateStartMenu - Brings up the Start menu in Windows 95/98 or NT. This is the
same as pressing CTRL+ESC.
AddHook - Installs a hook function. When a hook is in place, it is called right
before every script is run, and passed the name of the current script and frame as
its parameters. If the hook returns TRUE, the script is allowed to execute. If
the hook returns FALSE, the script will not be allowed to run. See the
KeyboardHelp script and the KeyboardHelpHook function in DEFAULT.JSS for an example
of a hook function in action. This tool is discussed more fully in the section on
Hook Functions.
AltLeftMouseClick - Unselects all previously selected items. Sends an ALT+LEFT
MOUSE BUTTON to the system.
ControlLeftMouseClick - Simulates a CTRL+Left click of the mouse. This script
provides a method for selecting items non-contiguously. An example is selecting
items non-contiguously in a list view.
ShiftLeftMouseClick - Simulates a SHIFT+Left click of the mouse. This function
provides a method for selecting items contiguously. An example is selecting items
contiguously in a list view or an edit control.
BackspaceKey - If the virtual cursor is not active, this function simply passes the
ENTER key through to the application. If the Virtual Cursor is active, any special
processing required by virtual mode is performed.
BrailleAddFocusItem - Used from within the BrailleBuildLine function to ad the
contents of the current control to the data to be shown on the Braille display.
BrailleAddFocusLine - Used from within the BrailleBuildLine function to ad the
contents of the current line to the data to be shown on the Braille display.
BrailleAddFrame - Used from within the BrailleBuildLine function to add the
contents of a specific frame to the data to be shown on the braille display.
BrailleAddString - Used with in BrailleBuildLine to add text to the Braille display
BrailleCursor - Turns on the Braille cursor. This cursor is only used internally
by the Braille scripts and should never be left on after a script completes its
work.
BrailleG2StringLength - Determines the length of the translation to grade two
Braille of a given string.
BrailleNextLine - If Structured mode is active, The next string in the braille
queue is displayed. If Navigation mode is active, JAWS activates the Invisible
cursor and moves it to the next line. Otherwise, a normal next line function is
performed.
BraillePriorLine - If Structured mode is active, The prior string in the braille
queue is displayed. If Navigation mode is active, JAWS activates the Invisible
cursor and moves it to the prior line. Otherwise, a normal prior line function is
performed.
BrailleRefresh - Used to refresh the braille display and redisplay the appropriate
text.
BrailleSetStatusCells - Puts characters on the status cells of the Braille Display.
This function should only be called from within a BrailleBuildStatus function.
BrailleString - Sends the specified string to the braille display regardless of
whether or not the line is visible.
CaretVisible - Indicates whether an insertion point or a caret is visible in the
active window. The function returns a constant value of "TRUE" to indicate that a
caret is visible and a value of "FALSE" to indicate that it is not visible.
ClipboardHasData - This function checks to see if any data at all is present on the
Windows clipboard. It will return true if there is such data present.
ColorToRGBString - Converts a color value to a string of the form "255255255" where
the first three digits represent the proportion of red, the second three the
proportion of green, and the third three the proportion of blue.
ControlCanBeChecked - Determines whether or not the current control can be checked.
ControlIsChecked - Determines whether or not the current control is checked.
CopyToClipboard - Puts a string of text onto the Windows clipboard erasing any
previous clipboard contents. To copy multiple lines of text, these must be
concatenated together into a single string before calling CopyToClipboard. In the
concatenated string, lines should be separated with \r\n.
CreateObject - For certain applications (e.g., Internet Explorer and Microsoft
Office ) it is possible for JAWS to obtain information directly from that
application rather than relying upon what is displayed on the screen. To do this,
JAWS needs a place to go to get that information and a sort of "road map" to tell
it where to look. The road map is called an object pointer, and the place it
directs JAWS to is called an automation object for that application. There are
several ways of obtaining such an object pointer for this purpose, not all of which
work with all applications. One such method is CreateObject. CreateObject
launches an application under the control of JAWS, with that application being the
automation object. JAWS can then query that automation object to get the
information it needs. The CreateObject function is similar to the GetObject
function, except that GetObject creates a pointer to an automation object which
already exists whereas CreateObject also creates the automation object for the
application.
Delay - Makes a script stand still for a specified period of time. It causes a
script to stop, wait a period of time, and then resume again. It is different than
the Pause function which yields to the processing needs of applications. After the
delay, the script will resume regardless of whether an application is still
processing.
DialogActive - Used to determine whether a dialog box is currently active. It
returns a constant value to indicate the status: "ACTIVE" = a dialog box is
active, and "INACTIVE" = a dialog box is not active. These constants can be used
in If- Then-Else statements.
DLGSelectItemInList - Displays a dialog that contains a listbox of items. The
contents of the list are built by the user who must supply a string containing each
of the list entries separated by a vertical bar (|). This function is normally
used within another script or function which specifies what actions are to follow
when an item is selected and the dialog is okayed. When the dialog is okayed, this
function returns an index that allows the calling script to decide what action to
take next. See the function named ToolBar in BROWSEUI.JSS for an example of how
this function is used.
DLGSelectControls - Displays a list box containing controls that can b activated.
The four possible actions are right single click, left single click, left double
click, and move to. The user can specify which of these four buttons are present
as well as which is the default. The list of controls must be built by the user.
The window title for the dialog can also be specified. This function is similar to
DLGSelectItemInList except that it provides a wider selection of actions that can
be performed on the selected list item.
DLGSelectScriptToRun - Displays a dialog that contains a set of scripts. The list
of scripts is built by the user. See the script titled AdjustJawsVerbosity for an
example of how this is done. Scripts can be performed from this dialog.
DLGSysTray - Displays a list box containing the icons on the system tray.
DownCell - When inside a table or spreadsheet, moves the active cursor to the cell
in the same column but the next Row.
UpCell - When inside a table or spreadsheet, moves the active cursor to the cell in
the same column but the previous Row.
PriorCell - When inside a table or spreadsheet, moves the active cursor to the cell
in the same row but the previous column.
NextCell - When inside a table or spreadsheet, moves the active cursor to the cell
in the same row but the next column.
SayCell - When in a table or spreadsheet, speaks the contents of the current cell.
SayColumnHeader - When in a table or spreadsheet, speaks the contents of the column
header.
SayRowHeader - When in a table or spreadsheet, speaks the contents of the row
header.
DragItemWithMouse - The DragAndDrop function is used to move the contents of one
area of the screen to another area of the screen.
ElIf - Instead of using an Else operator in an If-Then-Else statement, you may want
to use an ElIf operator. The statement could then be reconstructed as an If-Then-
ElIf-Then-Else statement. Every statement must end with an "EndIf" operator. The
script functions that appear between the ElIf and the Then are used to evaluate
whether a certain condition is present.
Else - The Else operator is an optional part of an If-Then- Else statement. If-
Then-Else statements always ask a question about whether something is true or
false, i.e., is a condition present or not present. When the condition is not
present (false), then the actions that follow the "Else" are performed. An If-
Then-Else statement must always include: If, Then, and EndIf -- the Else is
optional.
EndIf - The EndIf operator marks the end of an If-Then- Else statement. A fully
formulated If-Then-Else statement includes "If", "Then", "Else", and "EndIf". The
"EndIf" is always required to terminate the If-Then-Else statement.
EndWhile - The EndWhile operator marks the end of a "While Loop". The script
functions that are to be repeated must be placed between "While" and "EndWhile".
(See description of the While function below.)
EnterKey - If the virtual cursor is not active, this function simply passes the
ENTER key through to the application. If the Virtual Cursor is active and
positioned on a link or button, that control is activated. If the virtual cursor
is on another form control, Forms Mode is activated.
ExMessageBox - This function displays a Windows Standard Message Box wherein the
user can specify the message, title, and buttons which can be activated. It is
very much like the function MessageBox except it allows you to specify the Message
Box title and the type of message box (i.e., the buttons that are used and the icon
that is to be displayed). This function also returns a value that indicates which
button was pressed on the Message Box.
MessageBox - Used to Make a message box pop up on the desktop. It can be included
within an If-Then-Else statement so that when a certain event occurs, the needed
message pops up.
InputBox - This function displays a simple dialog box containing four controls.
One control is an edit box in which you can enter information. Another control is
a Static Text window containing the prompt of the edit box. The other two controls
are the OK and Cancel buttons. If you enter text into the Edit box and press the
OK button, the text you typed in the Edit box is returned to the calling function
by way of the third variable of the function, which is a string variable that is
passed by reference to the calling function.
FileExists - Checks whether the specified path exists.
FindColors - Searches for the occurrence of a specific combination of foreground
and background colors. If the search is successful, the JAWS cursor is placed at
the beginning of the text with the desired combination of colors.
FindDescendentWindow - A descendent window is any child window of some specified
parent window. It can be a child at any level below the parent and in any branch.
This function searches down the branches from the parent to find any child window
(descendent window) with a specified control ID. FindFirstAttribute - Searches for
the first occurrence of text with certain attributes. It begins the search at the
upper left corner of the specified window and moves downward. If the search is
successful, then the active cursor is placed on the first character that has the
desired attributes. Generally, the PC cursor can be successfully moved to
attributes within a text window.
FindNextAttribute - Searches for the next occurrence of text with certain
attributes. The search begins at the location of the active cursor and moves down
through the remainder of the active window. If the search is successful, then the
active cursor is placed on the first character that has the desired attribute.
FindPriorAttribute - Searches for the prior occurrence of text with certain
attributes. It begins the search at the location of the active cursor and moves up
through the remainder of the active window. If the search is successful, then the
active cursor is placed on the first character that has the desired attributes.
FindLastAttribute - Searches for the last occurrence of text with certain
attributes. It begins the search at the lower right corner of the active window
and moves up to the upper left corner of the window. If the search is successful,
then the active cursor is placed on the first character that has the desired
attributes.
FindGraphic - FindGraphic searches for a graphic in the specified window. If the
graphic is found, then the JAWS cursor is placed on it. The graphic must have a
text label associated with it, because the FindGraphic function searches for text
labels. Text labels are assigned by the Graphics Labeler.
FindString - FindString searches for a string of text in a specified window. If
the text is found, then the JAWS cursor is placed at the beginning of the text
string.
FindTopLevelWindow - Find the top level window with the specified window class
and/or window name. If you do not wish to search based on one of the arguments,
use "" for that argument.
FormatString - Formats a string supplied by the user with messages received as
subsequent parameters. That is to say, a user�s string can be modified to contain
new strings at certain specified locations within the original string. The message
to be formatted must contain parameter place holder delimiters such as %1, %2, %3,
%4, %5, etc. The user must supply the various strings which are to be inserted in
the original string at the locations of each place holder.
GetActiveCursor - Determines which cursor is active.
GetAppFileName - Determines the filename of the active application program or an
active component of that program that was subsequently executed. These filenames
are the actual program files that are executed by Windows. The application's
filename is used when naming script files.
GetAppFilePath - Used to get the fully qualified path name of the currently running
application. When used in combination with GetFileDate, the results can be used to
surmise an application version.
GetAppMainWindow - Determines the window handle for the main window of the active
application.
GetAppTitle - Obtains the title of the active application program. To have the
application title spoken, you must use this function as a parameter for the Say
function.
GetBrailleCellColumn - Retrieves the screen column at which the specified Braille
cell is located.
GetBrailleCellRow - Retrieves the screen row at which the specified Braille cell is
located.
GetCell - When in a table or spreadsheet, gets the contents of the current cell.
GetColumnHeader - When in a table or spreadsheet, gets the contents of the column
header.
GetRowHeader - When in a table or spreadsheet, gets the contents of the row header.
GetCharacter - Copies the character or graphic label where the active cursor is
positioned. The copied text can then be used by other script functions.
GetCharacterAttributes - Retrieves the text attributes of the character at the
current cursor location. The returned value is a combination of the same bit
fields used in FindFirstAttribute, FindNextAttribute, etc. To test for the
presence of a particular attribute, use code of the form: if (GetAttributes() &
ATTRIB_UNDERLINE) then ... (See the section on bitwise operators for a more
thorough description.)
GetCharacterFont - Retrieves the name of the font used for the character at the
current cursor location.
GetCharacterPoints - Retrieves the point size of the character at the current
cursor location.
GetCharacterWidth - Retrieves the width of the character or graphic at the active
cursor location.
GetChunk - Obtains the chunk of information to which the active cursor is pointing.
A "chunk" is text and graphic information that was written to the screen in a
single operation. GetChunk is similar to GetField, however, the GetField function
uses logic to determine the text that is to be obtained, while GetChunk simply
obtains the text that was stored in the Off Screen Model as a single unit.
GetField - Obtains the information in the field where the active cursor is
pointing. A "field is a section of information (usually text) that has a common
attribute, i.e., bold, underlined, italics, or strikeout. The use of the attribute
must be contiguous. GetField is similar to GetChunk, however, the GetField
function uses logic to determine the text that is to be obtained, while GetChunk
simply obtains the text that was stored in the Off Screen Model as a unit.
GetColorBackground - Retrieves the background color of the character at the current
cursor location. These colors are normally specified as 9 digit numbers where the
first three specify the red contribution, the next three the green contribution,
and the last three the blue contribution.
GetColorText - Retrieves the text color of the character at the current cursor
location.
GetColorField - Obtains the color field at the position of the active cursor. A
"color field" is a section of information (usually text) that has a common
combination of colors, i.e., white foreground on blue background. The use of the
color combination must be contiguous. GetColorField is similar to GetField,
however, the function GetColorField is based on color changes, while GetField is
based on attribute changes.
GetColorName - Color numbers are equated to color names in a JAWS file called
COLORS.INI. This function retrieves the textual name for the given color number
found in colors.ini.
GetControlAttributes - Returns an integer value indicating the attributes of the
current control.
GetControlID - Determines the Control ID for the specified child window in a dialog
box. The window of interest is specified by passing its window handle to this
function as a parameter. Each list box, edit field, radio button, etc. in a dialog
has a unique control ID number. Child windows that contain static text all have
the same control ID.
GetCurrentControlID - Determines the control ID of the active child window in a
dialog box. Each list box, edit field, radio button, etc. in a dialog has a unique
control ID number. Child windows that contain static text all have the same
control ID. This function performs the same task as GetControlID but it does not
require a window handle as a parameter to tell it which child window is of
interest.
GetControlName - gets the name of the current control.
GetCurrentObject - Uses MSAA to obtain the object with focus at the active cursor
position.
GetFocusObject - Uses MSAA to get the object with focus.
GetObjectAtPoint - Uses MSAA to determine the object at a set of X/Y coordinates.
GetCurrentScriptKeyName - Retrieves the name of the key used to invoke the
currently active script.
GetCurrentWindow - Determines the window handle for the window that contains the
active cursor. In contrast, the GetFocus function uses an analytic process to find
the window that currently has the focus regardless of which cursor is active.
GetFocus - Obtains the window handle for the window that has "the focus". It
always seeks to find the PC cursor or highlighted item that has the focus. It does
not take into account which cursor is active. In contrast, the GetCurrentWindow
function is less sophisticated. It simply obtains the handle for the window in
which the active cursor is located.
GetCursorCol - Determines the horizontal position or column where the active cursor
is located. It returns an integer which can be spoken with the SayInteger script
function.
GetCursorRow - Determines the vertical position or row where the active cursor is
located. It returns an integer which can be spoken by the SayInteger script
function.
GetCursorShape - Gets the current shape of the mouse cursor
GetDefaultButtonName - Identifies the default button in a dialog box. This is the
button that will be chosen when ENTER is pressed.
GetDefaultJcfOption - Determines the value of a specified option in the default
JAWS configuration file. These are values such as user verbosity or typing echo
set in the Configuration Manager.
GetJCFOption - Determines the value of a specified Configuration Manager option in
the JAWS configuration file for the active application, if any.
GetJFWSerialNumber - Retrieves the serial number for the currently-running copy of
JAWS.
GetDialogPageName - If the active cursor is inside a multi-page dialog, retrieves
the name of the current page.
GetDialogStaticText - Gets the static text in a dialog box.
GetFileDate - Used to get the last modified date of a particular file.
GetFirstChild - Determines the first child window that may have been created by a
specific parent window. This function is useful when you wish to move down through
the stack of window handles to find children of your starting window.
GetParent - Moves up through the window stack to find the parent of the specified
child window. It can, thus, be used to Determine which window created a specified
child window. For example, when a dialog box pops up, it could be used to
determine the window handle of the window that created the dialog box. It can be
used to move up through a list of window handles in order to get to a specific
window.
GetFirstWindow - Provides the handle for the first window that is at the same
logical (child) level as a specified window handle. It is used to get to the
beginning point of a series of windows at the same logical level.
GetNextWindow - Similar to GetFirstWindow, but it provides the next window handle
in a series of window handles that are all at the same logical level. It is used
to move across a list of window handles.
GetPriorWindow - Similar to GetFirstWindow, but it provides the prior window handle
in a series of window handles at the same logical level. It is used to move across
a list of window handles.
GetForegroundWindow - Retrieves the handle to the current Foreground window. This
is generally the main window of the active application but can sometimes be the
handle of a dialog box. This function is marginally faster than GetAppMainWindow.
GetFocusRect - Gets all of the coordinates of a focus rectangle.
GetFocusRectBottom - Gets the coordinates of the bottom edge of a focus rectangle.
GetFocusRectLeft -Gets the coordinates of the left edge of a focused rectangle.
GetFocusRectRight - Gets the coordinates of the right edge of a focus rectangle.
GetFocusRectTop - Gets the coordinates of the top edge of a focus rectangle.
GetFromStartOfLine - Retrieves text on the current line that is located to the left
of the active cursor.
GetToEndOfLine - Retrieves text on the current line that is located to the right of
the current cursor.
GetGraphicID - Gets the ID associated with the graphic under the current cursor.
If this function fails, then the pointer is not positioned in a valid location on
the graphic. Moving into the center of the graphic increases the success of this
call.
GetGroupBoxName - Gets the name of the current Group box.
GetHTMLFrameCount - Gets the number of HTML frames present on the current web page.
GetHotKey - Retrieves the first underlined character in the chunk of text on which
the active cursor is positioned. This is especially useful in menus and dialog
boxes where an accelerator key for a particular item has been defined and is
displayed on the screen as an underlined letter in the name of the control.
GetItemRect - Gets the bounding rectangle surrounding the specified item or items.
Items can be combined using the bitwise (|) operator. When two or more items are
combined, the resulting rectangle encloses all of the items.
GetJAWSDirectory - Retrieves the full path to the directory in which JAWS is
running.
GetJAWSHelpDirectory - Retrieves the full path to the JAWS help directory currently
in use. This depends on which language is being used.
GetJAWSSettingsDirectory - Retrieves the full path to the JAWS settings directory
currently in use. This depends on which language is being used.
GetLineTop - Determines the vertical pixel location of the top of the tallest
character of the line on which the current cursor is positioned. Since the cursor
position reported by JAWS is based on the base line of characters, this function is
the only way of determining how high up a line of text extends.
GetLinkCount - Gets the number of links present on the current web page
GetJAWSUserName - Retrieves the name of the user currently logged into JAWS. If
this instance of JAWS is not network aware, then the function will return a nul
string, "".
GetJFWVersion - Used to get the version of the currently running JAWS. It can be
used to insure that a function is only called on versions of JAWS that support it.
GetLine - Copies the text from the line where the active cursor is positioned. The
copied text can then be used by other script functions.
GetObject - For certain applications (e.g., Internet Explorer and Microsoft
Office ) it is possible for JAWS to obtain information directly from that
application rather than relying upon what is displayed on the screen. To do this,
JAWS needs a place to go to get that information and a sort of "road map" to tell
it where to look. The road map is called an object pointer, and the place it
directs JAWS to is called an automation object for that application. There are
several ways of obtaining such an object pointer for this purpose, not all of which
work with all applications. One such method is GetObject. GetObject sets a
pointer to a preexisting automation object. JAWS can then query that automation
object to get the information it needs. The GetObject function is similar to the
CreateObject function, except that GetObject creates a pointer to an automation
object which already exists whereas CreatObject also creates the automation object
for the application.
GetObjectName - Returns the name of the object at the position of the active
cursor. If the Pc Cursor is active, the name of the object with focus is returned.
Otherwise, the name of the object at the position of the active cursor is returned.
The value is returned as a string.
GetObjectRect - Retrieves the focus rectangle surrounding the object at the
position of the active cursor. Will return true if the object has a focus
rectangle, false otherwise. This function takes four integer parameters, Left,
right, top and bottom. Declare, but do not initialize, the integer variables for
these parameters, as they are passed by reference.
GetObjectState - Obtains and returns the state of the given object. If the PC
cursor is active, the state of the object with focus is returned. Otherwise, the
state of the object at the position of the active cursor is returned
GetObjectType - Retrieves the type of the object located at the current cursor's
location. Because the type is a string that differs across languages, this
function should only be used when the objective is to speak the type of the object.
GetObjectTypeCode should instead be used in all conditional statements because it
provides a language independent solution.
GetObjectTypeCode - Retrieves the numeric type code of the object located at the
current cursor's location. Constants for these type codes all begin with WT_ and
are defined in HJCONST.JSH. The numeric values are the same for all languages of
JAWS. Using this function in all conditional statements instead of using
GetObjectType insures that these statements will function without change in
multiple languages.
GetObjectValue - Returns the value of the object at the position of the active
cursor. If the Pc Cursor is active, the value of the object with focus is
returned. Otherwise, the value of the object at the position of the active cursor
is returned. The value is returned as a string.
GetProgramVersion - This function returns the major version of an application. For
example, if the full version was 3.00.62, GetProgramVersion would return 3.
GetRealWindow - Moves up through the list of window handles in search of a "real
window". A real window is one that has a title.
GetRestriction - Gets the restriction value for the current cursor.
GetRestrictionName - Can be used to speak the current level of restriction for the
active cursor. This function must be provided with a parameter which is the
current level of restriction. This value can be obtained with the function,
GetRestriction.
GetScreenEcho - Obtains the current screen echo setting. The screen echo setting
determines the amount of information that is to be read as the information is
displayed on the desktop. The NewTextEvent function often checks the setting for
screen echo before deciding how much information to speak.
GetScriptDescription - Retrieves the description of a specified script.
GetScriptSynopsis - Retrieves the synopsis of a specified script.
GetScriptFileName - Retrieves the name of a currently active default or application
script file. For the application script file, this is the same as the
application's executable file name, except in those cases where the originally
loaded application script file replaced itself with another one by means of
SwitchToScriptFile. Similarly, for the active default script file, this is the
name specified in JFW.INI, except in those cases where the original file replaced
itself by means of SwitchToScriptFile.
GetScriptKeyName - Retrieves the name of the key attached to the specified script.
This function is mainly used to create JAWS hot key help files since they will then
continue to report the correct key even if the hot key is changed.
GetScriptKeyNames - Retrieves the names of all of the keys assigned to the
specified script. These names are placed in a delimited list with the names being
separated (delimited) by \r\n.
GetSelectedText - Retrieves the currently-selected text as a string.
GetSynthPitchRange - Retrieves the minimum and maximum pitch settings for the
current synthesizer and assigns them to parameters taken by reference.
GetSynthRateRange - Retrieves the minimum and maximum rate settings for the current
synthesizer and assigns them to parameters taken by reference.
GetSynthVolumeRange - Retrieves the minimum and maximum volume settings for the
current synthesizer and assigns them to parameters taken by reference.
GetTextBetween - gets the text between two horizontal points on the screen on the
same line where the cursor is located. This function can be used to speak or
capture part of a line.
GetTextInFocusRects - Retrieves the contents of all focus rectangles into a single
buffer.
GetTextInFrame - Retrieves the text inside a specified frame.
GetTextInRect - Gets the text contained within the specified rectangle
GetTopLevelWindow - A top level window is the first or highest level parent window
which spawned the child window from which a search is being started. This function
finds the top level window with the specified window class and/or window name. If
you do not wish to search based on one of the arguments, use "" for that argument.
GetTreeViewLevel - Obtains the indent level of the item in a tree view that has
focus. The root of the tree has the level 0.
GetVerbosity - Used to obtain the current setting for verbosity. It returns a
constant value to indicate the setting: "BEGINNER" means speak maximum
information, "INTERMEDIATE" means speak a moderate amount of information, and
"ADVANCED" means speak a minimum amount of information. These values can be used
in If-Then-Else statements.
GetVoiceParameters - Retrieves the parameters for the specified voice context.
These include Volume, Rate, Pitch, Punctuation and person.
SetVoiceParameters - Sets the parameters for the specified voice context. These
include Volume, Rate, Pitch, Punctuation and person.
GetVoicePerson - Retrieves the person name setting for the specified voice context
name.
SetVoicePerson - Sets the person name of a voice specified by the voice context
name to a specified person setting.
GetVoicePitch - Retrieves the current pitch setting for the specified voice context
name.
SetVoicePitch - Sets the pitch of a voice specified by the voice context name to a
specified value.
GetVoicePunctuation - Retrieves the current punctuation level setting for the
specified voice context name.
SetVoicePunctuation - Sets the punctuation level of a voice specified by the voice
context name to a specified value.
GetVoiceRate - Retrieves the current rate setting for the specified voice context
name.
SetVoiceRate - Sets the rate of a voice specified by the voice context name to a
specified value.
GetVoiceVolume - Retrieves the current volume setting for the specified voice
context name.
SetVoiceVolume - Sets the volume of a voice specified by the voice context name to
a specified value.
GetWindowAtPoint - Gets the handle of the window at the specified point. This can
be used, for example, with MouseMovedEvent to get the handle of the window
containing the Mouse pointer.
GetWindowClass - Obtains the window class name of a window. Most standard windows
(non SDM windows) have a window class name and a window type name. Window class
names are generally unique to specific windows in specific applications.
GetWindowBottom -Gets the screen coordinate for the bottom of the window of
interest.
GetWindowLeft - Gets the screen coordinate for the left edge of the window of
interest.
GetWindowRight - Gets the screen coordinate for the right edge of the window of
interest.
GetWindowTop - Gets the screen coordinate for the top of the window of interest.
GetWindowName - Obtains the title of the specified window, such as for a main
Application window, dialog box, or document window. All windows do not have
titles.
GetWindowsOS - Provides information about which operating system is being used.
GetWindowRect - Gets the bounding rectangle of the window whose handle is
specified.
GetWindowsSystemDirectory - Returns the path to the Windows System directory as a
string.
GetWindowText - Retrieves either all of the text in the specified window or just
the highlighted text.
GetWindowTextEx - As with GetWindowText, retrieves either all of the text in the
specified window or just the highlighted text. However, it can also retrieve or
ignore the text in child windows.
GetWindowType - Obtains the window type name of a window. Most standard windows
(non SDM windows) have a window type name and a window class name. Examples of
window types are: static text, edit field, check box, radio button, etc. The same
Window type names are commonly used in many different Windows applications.
GetWindowTypeCode - Obtains the window type code number for the specified window.
These numbers are the same for English and non English versions of JAWS. Many
window type numbers have constant values assigned to them in the file HJCONST.JSH.
The GetWindowType function returns these constants instead of the window type
number.
GetWindowSubtypeCode - Obtains the window subtype code number for the specified
window. This function is quite similar to GetWindowTypeCode, but attempts to be
even more specific. If there is no more specific information available, returns
the same thing as GetWindowTypeCode. e.g. Calling GetWindowTypeCode using the
window handle for the Taskbar would return WT_TABCONTROL, and calling
GetWindowSubtypeCode would return WT_TASKBAR (a more specific type of tab control).
(See the documentation for GetWindowTypeCode for more details.)
GetWord - Gets the word where the active cursor is positioned. The text so
obtained can then be used by other script functions.
GraphicsEnumerate - Calls a user-specified function for every graphic contained
within a specific window and then passes to this function the coordinates of each
graphic. The function is called for each graphic until all have been enumerated or
until the user-specified function returns that the enumeration should not continue.
GraphicsListHelper - Assists the GraphicsList function in creating a string
delimited list of graphics labels.
HasFocusRect - Determines if the specified window has a focus rectangle. A
TrackFocusRect=1 statement should be added to the [OSM] section of the
application's JCF file for this function to work properly.
HasTitleBar - Determines whether a window has a title bar. If the window has a
title bar, then the function returns a constant value of TRUE. If the window does
not have a title bar, then a constant value of FALSE is returned. Windows that
typically have title bars are dialog boxes and main application windows.
IE4GetCurrentDocument - Returns an object that represents the HTML document in a
given browser window. The document object can be used to retrieve information
about the document, to examine and modify the HTML elements and text within the
document, and to process events. This function obtains the document object of the
document in the current window.
If - The If operator marks the beginning of an If-Then- Else statement. A fully
formulated statement includes: "If", "Then", "Else", and "EndIf". The script
functions that appear between the If and the Then are used to evaluate whether a
certain condition is present. For example, can a certain graphics character be
found in the active window? Every statement must include "If", "Then", and
"EndIf". The "Else" is optional.
IniReadInteger - Reads an integer value from an ini style file. An ini style file
is a file containing sections of keys with their values. JCF files as used in JAWS
are ini files, and the features that are set in the various sections of these files
are the keys. This function is used to obtain the current setting for integer
keys.
IniWriteInteger - Writes an integer value to an ini style file. An ini style file
is a file containing sections of keys with their values. JCF files as used in JAWS
are ini files, and the features that are set in the various sections of these files
are the keys. This function is used to change the current setting for integer
keys.
IniReadString - Reads a string value from an ini style file. An ini style file is
a file containing sections of keys with their values. JCF files as used in JAWS
are ini files, and the features that are set in the various sections of these files
are the keys. This function is used to obtain the current setting for string keys.
IniWriteString - Writes a string value to an ini style file. An ini style file is
a file containing sections of keys with their values. JCF files as used in JAWS
are ini files, and the features that are set in the various sections of these files
are the keys. This function is used to change the current setting for string keys.
IniRemoveKey- Removes a key and its value from an ini style file. An ini style
file is a file containing sections of keys with their values. JCF files as used in
JAWS are ini files, and the features that are set in the various sections of these
files are the keys. This function is used to delete a key and its setting from an
ini file.
IniRemoveSection - removes an entire section from an ini style file. An ini style
file is a file containing sections of keys with their values. JCF files as used in
JAWS are ini files, and the features that are set in the various sections of these
files are the keys. This function is used to delete an entire section from an ini
file.
InHJDialog - Checks to see if one of the dialogs generated by JAWS is active.
These include JAWSFind, GraphicsLabeler, DLGSelectItemInList, and DLGSysTray.
InTable - Used to determine if the active cursor is currently in a table.
IntToString - Converts an integer value to a string and returns the string value.
This might be useful, for example, when one wishes to use an integer as part of a
Say statement. Converting the integer to a string allows the value to be spoken as
part of the Say statement and avoids the need for a separate SayInteger statement.
InvisibleCursor - Activates the Invisible cursor and deactivates other cursors.
The mouse pointer does not move along with the Invisible Cursor, and it can be used
in situations where movements of the JAWS cursor and mouse pointer can cause the
window display to change.
IsBrailleCursor - Determines whether the Braille cursor is active. It can be used
in an If-Then-Else statement to verify the active status of a cursor.
IsInvisibleCursor - Used to determine whether the Invisible cursor is active. It
can be used in an If-Then-Else statement to verify the active status of the
invisible cursor.
IsJAWSCursor - Determines whether the JAWS cursor is active. It can be used in an
If-Then-Else statement to verify the active status of the JAWS cursor.
IsPCCursor - Determines whether the PC cursor is active. It can be used in an If-
Then-Else statement to verify the active status of the PC cursor.
IsVirtualPCCursor - Tests to see if the virtual PC cursor is enabled and whether it
is being used to navigate within the window with focus. It can be used in an If-
Then-Else statement to verify the active status of the virtual cursor.
IsJFWInstall - Checks to see if JAWS is running in Installation mode (with the
/install flag).
IsKeyWaiting - Indicates if there are other keys in the buffer that need to be
processed.
IsLeftButtonDown - Checks to see if the left mouse button is locked down.
IsRightButtonDown - Checks to see if the right mouse button is locked down.
IsMultiPageDialog - Checks to see if the active cursor is positioned inside a
multi-page dialog box.
IsPointInWindow - Compares the specified pixel coordinates with the window
boundaries of the window who's handle is indicated in the parameter hwnd to
determine whether it is within the boundaries of that window.
IsSameScript - Determines if the current script has been called two or more times
in a row without any intervening scripts being called and with no more than 500
milliseconds between each call. Using this function allows a script to act
differently depending upon the number of consecutive times it has been called. (A
script is called whenever a key assigned to it has been pressed.)
IsSpeechOff - Used to determine if the synthesizer is muted.
IsWindowDisabled - Checks the status of the current window or control. Returns
FALSE if the window is active; TRUE if the window is disabled.
IsWindowObscured - Checks to see if this window is covered by any others and
therefore cannot be entirely seen.
IsWindowVisible - Checks the visual status of the window. This function will
return true even if the window is completely covered by other windows. See
function IsWindowObscured for a way to find out if a particular window is covered.
Returns TRUE if the Window is visible on the screen, FALSE if the window is not
visible on the screen.
JAWSCursor - Activates the JAWS cursor and deactivates all other cursors.
JAWSEnd - Moves the JAWS or Invisible cursor, if active, to the end of the line.
If the PC cursor is active, JAWS sends an END to the system. The result is
controlled by the active application.
JAWSHome - Moves the JAWS cursor, if active, to the start of the line. If the PC
cursor is active, JAWS sends a HOME to the system. The result is controlled by the
active application.
JAWSPageDown - Moves the JAWS cursor, if active, to the bottom of the window, but
does not move it left or right. If the PC cursor is active, JAWS sends a PAGE DOWN
to the system. The result is controlled by the active application.
JAWSPageUp - Moves the JAWS cursor, if active, to the top of the window, but does
not move it left or right. If the PC cursor is active, JAWS sends a PAGE UP to the
system. The result is controlled by the active application.
JAWSFind - Invokes the JAWS Find dialog and then Searches the visible screen to
find the text or graphic you enter. The text label of the graphic is used for
searches.
JAWSFindNext - Searches the visible screen for the next occurrence of the text or
graphic last entered in the JAWS Find Dialog.
JAWSWindow - Invokes the JAWS window, from anywhere else in Windows, so you can
read the online help, change synthesizers, or perform any other JAWS window
function.
LeftMouseButton - This function will perform the same action as clicking the left
mouse button on the physical mouse. Invoking it twice will yield a double click.
The position of the JAWS cursor is the same as the mouse pointer.
LeftMouseButtonLock - Locks the left mouse button down to drag items across the
screen or perform any other application-specific function. Invoking it again will
unlock the left mouse button to drop the item.
Max - This function is used to compare to integers and returns the greater of the
two.
Min - This function is used to compare two integers and returns the lesser of the
two.
MenusActive - Determines whether a menu is currently active. It returns a constant
value of "ACTIVE" to indicate a menu is active and a value of "INACTIVE" to
indicate that a menu is not active. These constants can be used in If-Then-Else
statements.
MinimizeAllApps - Minimizes all application windows, so the Desktop gets the focus
and is visually clear.
MouseDown - Moves the mouse downwards by the number of pixels placed between the
parentheses after the function name.
MouseLeft - Moves the mouse left by the number of pixels placed between the
parentheses after the function name.
MouseRight - Moves the mouse right by the number of pixels placed between the
parentheses after the function name.
MouseUp - Moves the mouse upwards by the number of pixels placed between the
parentheses after the function name.
MoveTo - Moves the active cursor to the specified X and Y coordinates on the
screen.
MoveToControl - moves the active cursor to a specific control within a window.
Although primarily useful inside dialog boxes, the function can be used in any
window where child controls have unique identifiers obtained with GetControlID. It
can also be used in SDM windows with the identifiers obtained using
SDMGetFirstControl, SDMGetLastControl, SDMGetFocus, etc. If the PC cursor is on
when this function is called, the JAWS cursor is turned on automatically.
Otherwise the active cursor is used.
MoveToFrame - Moves the active cursor to the top left corner of the specified
Frame. If the PC cursor is active when this function is used, then the JAWS cursor
is activated and it is moved to the new position, otherwise the active cursor is
moved.
MoveToGraphic - Moves the JAWS cursor, Invisible cursor, or Braille cursor in a
specific direction to find a graphic symbol in the active window. The graphic is
searched by its text name.
MoveToWindow - Moves the active cursor to the specified window. If the window
contains text, then the cursor is positioned on the first character. Otherwise, it
is positioned at the window's center. If the PC cursor is active when this
function is used, then the JAWS cursor is activated and it is moved to the new
position.
MSOGetMenuBarObject - Gets the Menu bar object in MS Office 97 applications.
NextCharacter - Performs a special version of` the {RIGHT ARROW} or next character
keyboard command. When the PC cursor is active, JAWS allows the application to
move the cursor. When other cursors are active, then JAWS tries to move the cursor
to the next character or graphic it finds to the right of the cursor's current
location. To speak the character at the new location, place a SayCharacter
function after the NextCharacter function.
NextChunk - Moves the active cursor to the next chunk of text. A chunk of text is
a section or block of text that is written to the screen at one time, i.e., with
one function call. This would typically indicate a phrase or description that
should be spoken as one unit. This is useful in reading blocks of static text,
control prompts, and field names.
NextLine - Moves the active cursor down to the next line. In many situations,
Windows does not display information in perfect horizontal rows, and the cursor may
not move a uniform distance each time this function is used. To speak the
information immediately after the NextLine function is used, place a SayLine
function after the NextLine function.
NextNonLink - Positions the Virtual cursor at the next large block of nonlink text.
This function is often useful for moving passed advertisement text or repeated
links on a web page.
NextParagraph - Moves the active cursor to the beginning of the next paragraph. If
the PC cursor is active, and the next paragraph is not already visible, then text
in the window will automatically scroll to bring it into view.
NextSentence - Moves the active cursor to the beginning of the next sentence. If
the PC cursor is active, and the next sentence is not already visible, then text in
the window will automatically scroll to bring it into view.
NextWord - Performs a special version of the {CONTROL+RIGHT ARROW} or next word
keyboard command. When the PC cursor is active, JAWS allows the application to
move the cursor. When other cursors are active, then JAWS tries to move the cursor
to the next word or graphic it finds to the right of the cursor's current location.
To speak the word at the new cursor location, place a SayWord function after the
NextWord function.
Not - The Not operator reverses the question asked by an If-Then-Else statement.
It is placed immediately after the "If" in the If-Then-Else statement. It says,
"If the specified condition is not present, then perform the following actions."
PassKeyThrough - If this function is invoked, JAWS will not use or process the
following key. It will be sent directly to the application, as if JAWS were not
loaded. This is very useful if you have a key conflict.
Pause - Stops the processing of a script so that other applications can complete
tasks. When a Pause function is placed in a script, JAWS yields to the time needs
of other applications. Once other applications have been given the opportunity to
use processing time, then JAWS resumes the script. The Pause function performs
differently from the Delay Function which stops script processing for a specified
amount of time, irrespective of whether the application is done processing or not.
PCCursor - Activates the PC cursor and deactivates all other cursors.
PlaySound - Plays a wave file through the computer sound system. Requires one
parameter that specifies the wave filename. If a complete path is not specified,
JAWS will search the path for the file.
PriorCharacter - Performs a special version of the {LEFT ARROW} or prior character
keyboard command. When the PC cursor is active, JAWS allows the application to
move the cursor. When other cursors are active, JAWS tries to move the cursor to
the prior character or graphic it finds to the left of the cursor's current
location. To speak the information at the new cursor location, place a
SayCharacter function after the PriorCharacter function.
PriorChunk - Moves the active cursor to the prior chunk. A chunk of text is a
section or block of text that is written to the screen at one time, i.e., with one
function call. This would typically indicate a phrase or description that should
be spoken as one unit. This is useful in reading blocks of static text, control
prompts, and field names.
PriorLine - Performs a special version of the {UP ARROW} keyboard command. When
the PC cursor is active, JAWS allows the application to move the cursor. When
other cursors are active, then JAWS tries to move the cursor up to the line above
its current position. To speak the line of information at the new location, place
a SayLine function after the PriorLine function.
PriorParagraph - Moves the active cursor to the beginning of the prior paragraph.
If the PC cursor is active, and the prior paragraph is not already visible, then
text in the window will automatically scroll to bring it into view.
PriorSentence - Moves the active cursor to the beginning of the prior sentence. If
the PC cursor is active, and the prior sentence is not already visible, then text
in the window will automatically scroll to bring it into view.
PriorWord - Performs a special version of the {CONTROL+LEFT ARROW} or prior word
keyboard command. When the PC cursor is active, JAWS allows the application to
move the cursor. When other cursors are active, JAWS tries to move the cursor to
the prior word or graphic it finds to the left of the cursor's current location.
To speak the word at the new location, place a SayWord function after the PriorWord
function.
ProcessNewText - This function is used to force a NewTextEvent call. The
NewTextEventFunction is normally called only when new text is written to the
screen. ProcessNewText can be useful if you need to call NewTextEvent before
FocusChangedEvent.
Refresh - Refreshes the screen. This rewrites the information to the JAWS off
screen model and can be used to clear leftover data from the screen.
RefreshWindow - Refreshes the contents of a window and all windows contained within
it. This is much faster than refreshing the entire screen.
RemoveHook - Removes a hook function put in place by the AddHook function. See the
section on Hook Functions for more information.
ResetSynth - Reinitializes the synthesizer with the proper volume, rate, and pitch
settings. Used to bring the synthesizer back to normal if it has gotten out of
sync with JAWS.
RestoreCursor - Reactivates the cursor that was saved when the SaveCursor function
was last used. If the cursor being restored is the JAWS cursor, Invisible cursor,
or Braille cursor, then the cursor is also returned to its previous position on the
desktop. If the cursor currently in use is different from the cursor that was in
use when the SaveCursor function was used, then it is deactivated and the previous
cursor is reactivated.
Return - The return operator terminates execution of the function in which it
appears and returns control (and the value of expression if given) to the calling
function. To define return values, the name of the function is preceded by the
return type. Since a Script cannot return a value, a Return operator that is used
from within a script should never be followed by a value.
RGBStringToColor - Converts a 9-digit String of the form "255255255" to a color
value. The 9-digit string must be enclosed in quotation marks. (in this case, the
color would be white.) Color equivalents are found in the file COLORS.INI.
RightMouseButton - This function will perform the same action as clicking the right
mouse button on the physical mouse. Invoking it twice will yield a double click.
The position of the JAWS cursor is the same as the mouse pointer.
RightMouseButtonLock - This function will lock the right mouse button and allow the
user to perform any such function required by an application. Invoking it again
will unlock the button.
RouteBrailleToJAWS - Repositions the Braille cursor to the same position as the
JAWS Cursor.
RouteBrailleToPC - Repositions the Braille cursor to the same position as the PC
cursor.
RouteInvisibleToJAWS - Moves the Invisible cursor to the location of the JAWS
cursor and activates the Invisible cursor.
RouteInvisibleToPC - Moves the Invisible cursor to the location of the PC cursor
and activates the Invisible cursor.
RouteJAWSToBraille - Repositions the JAWS cursor so that it is in the same position
as the Braille cursor.
RouteJAWSToInvisible - Moves the JAWS cursor to the location of the Invisible
cursor and activates the JAWS cursor.
RouteJAWSToPC - Repositions the JAWS cursor so that it is in the same position as
the PC cursor. The JAWS cursor is usually connected to the mouse pointer, thus,
when this function is used, it places the mouse pointer on top of the caret or the
highlighted selection cursor, or on whatever other type of pointer that is
currently being used.
RoutePCToBraille - Repositions the PC cursor so that it is in the same position as
the Braille cursor.
RoutePcToInvisible - Repositions the PC cursor so that it is in the same position
as the Invisible cursor.
RoutePCToJAWS - Attempts to move the PC cursor to the position of the JAWS cursor.
This function is the same as a single click of the left mouse button, which
instructs Windows to move its insertion point to the position of the mouse pointer.
The successful use of this function is related to the Windows operating system;
there are often situations where Windows cannot move the PC cursor to the mouse
pointer.
SaveCursor - Saves the name of the active cursor. If the JAWS cursor, Invisible
cursor, or Braille cursor is being used, then the position of the cursor is also
saved. Scripts that use the SaveCursor function usually use the RestoreCursor
function later in the script. If a RestoreCursor is not used, JAWS will execute
one automatically when the script terminates.
Say - This function speaks a string of text, much like the SayString function, but
it has a second parameter called an output mode. These output modes allow the
message to be spoken with a particular set of speech characteristics. It is
possible to use separate output modes to speak title lines, dialog controls, menu
items, etc, with different voices or at different verbosity levels. By using the
SayMessage function instead, it is possible to assign short and long messages to
many output types for JAWS Help and other information.
SayActiveCursor - Says the name of the active cursor and its position by pixel
location.
SayAll - Says all readable information from the point of the active cursor to the
bottom of the window. If the PC cursor is active, JAWS scrolls the screen by
moving the PC cursor down. If the JAWS cursor is active, the rest of the window is
read by moving the JAWS cursor down a line at a time.
SayCharacter - Reads the character or graphic symbol at the active cursor. If the
PC cursor is active, JAWS looks for the visible caret or the light bar. If the
JAWS cursor is active, it speaks the character or graphic at the mouse pointer.
SayCharacterPhonetic - Uses special pronunciation rules to read the character
located at the position of the active cursor. Thus, A is pronounced alpha, B
bravo, etc. The associations between characters and their phonetic pronunciations
are made in the [PhoneticSpell] section of .JCF files. Which words are used can be
changed by the user, if desired.
SayChunk - Speaks the chunk of information to which the active cursor is pointing.
A "chunk" is text and graphic information that was written to the screen in a
single operation. SayChunk is similar to SayField, however, the SayField function
uses logic to determine the text that is to be spoken, while SayChunk simply reads
the text that was stored in the Off Screen Model as a single unit.
SayColor - Says the color at the active cursor. Uses the COLORS.INI to define the
colors from the 9 digit numerical RGB values. If you hear numbers instead of a
color name, add that entry to the colors.ini file and define its color.
SayControl - Used in dialog boxes to speak the contents of a child window along
with its prompt. It reads edit fields, list boxes, check boxes, radio buttons,
etc.
SayCurrentScriptKeyLabel - Speaks the Key Name attached to the current script,
honoring both the typing echo setting and the label as defined in default.jcf.
SayCursorPos - Speaks the row and column position of a cursor.
SayField - Reads the field of text where the active cursor is pointing. A "field
of text" is a section or block of text that has a common attribute, i.e., bold,
underlined, italics, or strikeout. The use of the attribute must be contiguous.
The SayField function uses logic to determine the text that is to be spoken, while
the SayChunk function simply reads the text that was stored in the JAWS Off Screen
Model as a single unit.
SayFocusRect - Says the contents of a focus rectangle. Returns TRUE if any text
was spoken, FALSE otherwise. A TrackFocusRect=1 statement should be added to the
[OSM] section of the application's JCF file for this function to work properly.
SayFocusRects - Says the contents of focus rectangles. If there is only one such
rectangle, this is exactly like SayFocusRect. If there is more than one, this
function says the contents of all of them, while SayFocusRect says only the first
one. A TrackFocusRect=1 statement should be added to the [OSM] section of the
application's JCF file for this function to work properly.
SayFont - Speaks the font name and size at the active cursor.
SayFrame - Speaks the contents of the specified frame.
SayFrameAtCursor - All text within the boundaries of the frame that contains the
active cursor is spoken.
SayFromCursor - Reads the text from the cursor to the end of the line, including
the current character.
SayToCursor - Reads the text from the start of the line up to the cursor, not
including the current character.
SayInteger - Speaks numeric, integer data, often the contents of an integer
variable.
SayString - Speaks string data, usually either the contents of a string variable or
a specific message. If actual text is used, it should be placed inside of
quotation marks within the parentheses that follow the function name. If a
variable or constant is used, no quotation marks should be present. It is now
recommended that the SayString function be avoided in favor of the SayMessage
function (see below).
SayLine - Speaks the current line. If the PC cursor is active, reading will be
restricted to the current item or window. Otherwise reading will include all the
text on approximately the same line, even if it is outside the current item or
window, unless JAWS cursor Restriction is on.
SayMessage - This function takes short and long messages supplied as parameters and
speaks the appropriate message based on the specified output type, also supplied as
a parameter. This function is similar to Say, except that it is possible to assign
short and long messages to many output types for JAWS Help and other information.
It is now recommended that the SayMessage function be used in preference to the
SayString function.
SayObjectActiveItem - Says the active element in certain controls. For example, in
a list view, it will say the selected item. In a menu, it will say the active menu
item. In a dialog box, it will say the selected tab.
SayObjectTypeAndText - Speaks the name and type of the object located at the
current cursor's location. This function is similar to SayWindowTypeAndText except
that it is more specific. If a particular window contains multiple objects, this
function will speak information about the one at the cursor, while
SayWindowTypeAndText will speak information about the enclosing window. If the
window does not contain multiple objects, then the functions operate identically.
When this function is used, it marks the text it reads so that the
SayNonHighlightedText and SayHighlightedText functions do not repeat the same
information when they are triggered.
SayParagraph - Reads the current paragraph from the beginning.
SaySentence - Reads the sentence containing the character on which the active
cursor is positioned.
SayTextBetween - Says the text between two horizontal points on the screen on the
same line as the active cursor.
SayToBottom - Reads the active window from the position of the active cursor to the
bottom of the window. The cursors do not move as text is read, the window will not
scroll to display additional text.
SayUsingVoice - Speaks a string of text using a specific set of speech
characteristics called voice context.
SayWindow - Reads the specified window. It either reads highlighted text or all
text in the window, depending on the parameters entered by the user.
SayWindowTypeAndText - Reads a specified series of information from a window. It
reads the window title (when one is present), the window type, the contents in the
window, and provides related information about the current dialog option. When
this function is used, it marks the text it reads so that the SayNonHighlightedText
and SayHighlightedText functions do not repeat the same information when they are
triggered.
SayWord - Reads the word or graphic symbol at the active cursor. If the PC cursor
is active, JAWS looks for the visible caret or the light bar. If the JAWS cursor
is active, it speaks the word or graphic at the mouse pointer.
ScheduleFunction - Runs a user defined function in a set period of time. This
Function is useful when you want to perform a task and then check on the results at
a later time. Once this function is used, you can call UnscheduleFunction to cause
the user defined event not to run.
UnscheduleFunction - Used to cancel a ScheduleFunction call.
ScreenEcho - Toggles the screen echo among the three possible states. The default
is Highlighted, which speaks only highlighted text when it appears on the screen.
All speaks all the text that gets written to the screen, and None speaks none of
the text.
ScreenGetHeight - Gets the height of the screen in pixels.
ScreenGetWidth - Gets the width of the screen in pixels.
SDMGetCurrentControl - Retrieves the ID of the control on which the active cursor
is positioned inside an SDM dialog box.
SDMGetFirstControl - Obtains the control ID of the first dialog option in an SDM
dialog box. It can provide the control ID that is needed by the SDMSayControl
function.
SDMGetLastControl - Provides the control ID for the last option in an SDM dialog
box. It can provide the control ID that is needed by the SDMSayControl function.
SDMGetFocus - Used to get the Control ID of the active dialog option or control in
an SDM dialog box. This function is most often used as a parameter for the
SDMSayWindowTypeAndText function to provide it with a control ID.
SDMGetNextControl - Obtains the control ID for the next option in an SDM dialog
box. It can provide the control ID that is needed by the SDMSayControl function.
SDMGetPrevControl - Provides the control ID for the previous option in an SDM
dialog box. It can provide the control ID that is needed by the SDMSayControl
function.
SDMSayControl - Speaks the contents of a child window along with its prompt in an
SDM dialog box. It reads edit fields, list boxes, check boxes, radio buttons, etc.
This function is equivalent to SayControl, but is exclusively designed for SDM
dialog boxes. All child windows in an SDM dialog box have the same window handle,
and the control ID is used to distinguish among the various options in the dialog
box.
SDMSayStaticText - Reads a type of text called "static text" that may be displayed
in an SDM dialog box. It does not read the text in edit fields, check boxes, etc.,
or the titles or prompts that are often associated with dialog options.
SDMSayWindowTypeAndText - Used with SDM windows to read the window title (when one
is present), the window type, the contents in the window, and related information
about the current dialog box option. When this function is used, it marks the text
it reads so that the SayNonHighlightedText and SayHighlightedText functions do not
repeat the same information when they are triggered. This function is only used
with SDM windows and not with regular dialog windows.
SelectFromStartOfLine - Sends a SHIFT+HOME to the system. The result is controlled
by the application. In word Pad , all text from the start of the line to the PC
cursor is selected. (Used primarily by MAGic)
SelectToEndOfLine - Sends a SHIFT+END to the system. The result is controlled by
the application. In Word Pad , all text from the PC cursor to the end of the line
is selected. (Used primarily by MAGic)
SelectFromTop - Sends a CTRL+SHIFT+HOME to the system. The result is controlled by
the application. In Word Pad , all text from the top of the document to the PC
cursor is selected. (Used primarily by MAGic)
SelectToBottom - Sends a CTRL+SHIFT+END to the system. The result is controlled by
the application. In Word Pad , all text from the PC cursor to the bottom of the
document is selected. (Used primarily by MAGic)
SelectNextCharacter - Sends a SHIFT+RIGHT ARROW to the system. The result is
controlled by the application. In Word Pad , the character to the right of the PC
cursor is selected. (Used primarily by MAGic)
SelectPriorCharacter - Sends a SHIFT+LEFT ARROW to the system. The result is
controlled by the application. In Word Pad , the character to the left of the PC
cursor is selected. (Used primarily by MAGic)
SelectNextLine - Sends a SHIFT+DOWN ARROW to the system. The result is controlled
by the application. In Word Pad , the line below the PC cursor is selected. (Used
primarily by MAGic)
SelectPriorLine - Sends a SHIFT+UP ARROW to the system. The result is controlled
by the application. In Word Pad , the line above the PC cursor is selected. (Used
primarily by MAGic)
SelectNextScreen - Sends a SHIFT+PAGE DOWN to the system. The result is controlled
by the application. In Word Pad , The next screen of text is selected. (Used
primarily by MAGic)
SelectPriorScreen - Sends a SHIFT+PAGE UP to the system. The result is controlled
by the application. In Word Pad , the prior screen of text is selected. (Used
primarily by MAGic)
SelectNextWord - Sends a CTRL+SHIFT+RIGHT ARROW to the system. The result is
controlled by the application. In Word Pad , the word to the right of the PC
cursor is selected. (Used primarily by MAGic)
SelectPriorWord - Sends a CTRL+SHIFT+LEFT ARROW to the system. The result is
controlled by the application. In Word Pad , the word to the left of the PC cursor
is selected. (Used primarily by MAGic)
SetDefaultJCFOption - Changes the default value for an option in the default JAWS
configuration file. Settings in DEFAULT.JCF are used until a JCF is loaded for an
application. When a JCF is not available for the application, then settings in the
default JCF continue to be used. The function SetJCFOption is used to set a value
in the JCF for an active application.
SetJCFOption - Changes a value in the JAWS configuration file for the active
application. A new JCF file is loaded each time a different application is used.
When a JCF is not available for the application, then the settings in the
DEFAULT.JCF are used. The SetDefaultJCFOption is used to change a default JCF
option.
SetJAWSLanguage - In the international versions of JAWS, changes the JAWS operating
environment to the specified language.
SetFocus - moves the focus to a specified window.
SetGraphicLabel - Adds a graphic label to the specified graphics file (jgf).
SetRestriction - For all cursors except the PC cursor, this function sets the area
within which the current cursor is free to move.
SetRestrictionToFrame - For any active cursor except the PC cursor, this function
restricts that cursor's movement to within the specified frame.
SetRestrictionToRect - For any active cursor except the PC cursor, this function
restricts that cursor's movement to within the specified rectangle.
SetSynth - Causes JAWS to switch to the specified synthesizer.
SetSynthLanguage - For synthesizers that support multiple languages, changes the
synthesizer to the specified language.
ShiftTabKey - If the virtual cursor is not active, this function simply passes the
SHIFT+TAB key combination through to the application. If the Virtual Cursor is
active, it is moved to the previous link or control in the tab order.
TabKey - If the virtual cursor is not active, this function simply passes the TAB
key through to the application. If the Virtual Cursor is active, it is moved to
the next link or control in the tab order.
ShouldItemSpeak - This function is used to determine whether or not the user has
specified that items spoken with a given Output Mode should be spoken in the
current verbosity level.
ShowHelpByID - Opens up winhelp using a specified file and topic ID.
ShowHelpByName - Opens up winhelp using a specified file and index topic.
ShutDownJAWS - Terminates the JAWS application.
SpeechInUse - Checks to see if speech output is being used.
SpeechOff - Causes the synthesizer to be muted. This is particularly useful when
you need to free the synthesizer so that a wave file can be played or if you wish
to mute speech during script or function playback. You can reverse this action
with SpeechOn.
SpeechOn - UnMutes the synthesizer. Reverses the action of SpeechOff.
SpellString - Spells a string of text. This is similar to the SayString function,
however it spells the string letter by letter instead of speaking words.
SpellWord - Spells the word at the active cursor.
StartJawsTaskList - The JTL allows the user to minimize, maximize, close, start,
and switch to applications.
StringContains - Determines whether a specified text string is contained within
another text string. You must specify both the string to be searched and the text
to be searched for. The latter is case sensitive. This is the only way to check
strings in a case sensitive fashion since logical operator comparisons are not case
sensitive.
StringLength - Used to find the length of a string.
StringLower - Converts a mixed case string to all lower case. This might be
useful, for example, in combination with the StringContains function when one does
not wish the check to be case sensitive.
StringUpper - Converts a mixed case string to all upper case.
StringLeft - Extracts a specified number of leftmost characters from a string.
StringRight - Extracts a specified number of rightmost characters from a string.
StringSegment - When a string contains delimiters, StringSegment can be called to
extract a segment of the string. One is the index of the first string.
StringToInt - Converts a string value to an integer and returns the integer value.
This is used on string names which are comprised of numbers.
SubString - Extracts part of a string from another string. It could be used to
read a portion of the information that appears on a status line or obtain a part of
a string for logical comparison to another string.
StopSpeech - Silences the synthesizer. This is identical to pressing the CTRL key.
SwitchToScriptFile - Removes the currently running script and loads a new one in
it's place.
SysGetDate - Obtains the current system date.
SysGetTime - Obtains the current system time.
SysTrayGetItemCount - Obtains the number of items in the system tray.
SysTrayGetItemToolTip - Used in ListTaskTrayIcons to obtain the tool tip that
corresponds to a specific task tray icon. This function takes a single parameter,
the index of the task tray icon for which the tool tip is desired. It returns a
string value that is the text of the tool tip in question.
SysTrayMoveToItem - Moves the JAWS cursor to the location of an item in the system
tray.
TrapKeys - Turns Trap key mode On or Off. When Trap Key mode is on, any keys not
attached to scripts are simply ignored and not passed on to the current
application. The primary use for this feature is in the Keyboard Help, where keys
not attached to scripts should be ignored.
TurnOffFormsMode - Used to exit from forms mode and turn the virtual PC cursor back
on.
ToggleHomeRow - Toggles Home Row mode on and off. Home Row mode is a shifted state
for the keyboard; it is analogous to the numlock on the numeric keypad. When it is
on, the alphabet keys and number keys can be used to perform script functions. A
suite of special window functions is also available in this mode. (See the section
on Utility Functions later in this manual.) When Home Row mode is turned back off,
then the keys perform their standard functions.
ToggleRestriction - Toggles JAWS between restricted and unrestricted mode. These
modes do not affect the movement of the PC cursor. When Unrestricted mode is used,
the other cursors can be freely moved within the active application window. When
Restricted mode is used, the movement of these cursors is limited to a child
window. When the function is used, it returns a constant value representing the
new setting. "ON" = restriction on, and "OFF" = restriction off.
TypeCurrentScriptKey - Passes the key attached to the current script directly
through to the application.
TypeString - Used to simulate the typing of a string of characters. For Example,
to send a group of characters through to the application simulating the string
"test," you could either enter the line {t}{e}{s}{t}, or you could use TypeString
("test").
VerbosityLevel - Controls how much JAWS will say when the focus changes or other
events occur on the screen or in response to key strokes.
While - The While operator marks the beginning of a "While Loop, the end of which
is indicated by an EndWhile statement". While loops can be constructed to perform
a series of script statements repeatedly until a condition becomes true or false.
Thus, while Loops can be used to perform repeated actions and save space or to
perform a series of activities repeatedly when the user does not know in advance
how many times the repetition will be required.

Appendix D

Important Built-In Functions Arranged by Task

Note - This list has been updated to reflect new functions added in JAWS 3.7.
Those using earlier versions will not have all of the functions shown here.

Cursor

Use the following functions to activate and position the four cursors available in
JAWS: PC, JAWS, Invisible, and Virtual.

GetActiveCursor
SayActiveCursor
GetCursorCol
GetCursorRow
SayCursorPos
CaretVisible
SaveCursor
RestoreCursor
InvisibleCursor
RouteInvisibleToJAWS
RouteInvisibleToPC
IsInvisibleCursor
JAWSCursor
RouteJAWSToPC
RouteJAWSToInvisible
IsJAWSCursor
ToggleRestriction
SetRestriction
SetRestrictionToFrame
SetRestrictionToRect
GetRestriction
GetRestrictionName
PCCursor
RoutePCToJAWS
IsPCCursor
RouteBrailleToJAWS
RouteBrailleToPC
RouteJAWSToBraille
RoutePCToBraille
IsVirtualPCCursor
TurnOffFormsMode

Positioning

Use the following functions to position a cursor, get information at the desired
location, and select text.

MoveTo
MoveToControl
MoveToGraphic
MoveToWindow
MoveToFrame
JAWSEnd
JAWSHome
JAWSPageDown
JAWSPageUp
PriorCharacter
GetCharacter
GetCharacterPoints
GetCharacterFont
NextCharacter
PriorChunk
GetChunk
NextChunk
PriorLine
GetLine
GetLineTop
NextLine
PriorWord
GetWord
NextWord
GetField
GetCharacterAttributes
GetCharacterWidth
NextParagraph
PriorParagraph
NextSentence
PriorSentence
NextNonLink
GetSelectedText
SelectNextCharacter (Used primarily by MAGic)
SelectPriorCharacter (Used primarily by MAGic)
SelectNextWord (Used primarily by MAGic)
SelectPriorWord (Used primarily by MAGic)
SelectNextLine (Used primarily by MAGic)
SelectPriorLine (Used primarily by MAGic)
SelectToEndOfLine (Used primarily by MAGic)
SelectFromStartOfLine (Used primarily by MAGic)
SelectNextScreen (Used primarily by MAGic)
SelectPriorScreen (Used primarily by MAGic)
SelectToBottom (Used primarily by MAGic)
SelectFromTop (Used primarily by MAGic)
TabKey
ShiftTabKey
BackspaceKey
EnterKey
NextCell
PriorCell
UpCell
DownCell
GetCell
GetColumnHeader
GetRowHeader
InTable

Conditional Processing and Looping

Use the following functions to perform conditional processing and looping.

If-Then
EndIf
Else
ElIf
Not
While
EndWhile

Say

Use the following functions to speak information, either from the screen or using
messages within a script.

Say
SayAll
SayInteger
SayCharacter
SayCharacterPhonetic
SayWord
SpellWord
SayChunk
SayControl
SayField
SayLine
SayToCursor
SayFromCursor
SayTextBetween
SayToBottom
SayFont
SayString
SpellString
SayParagraph
SaySentence
SayUsingVoice
SayCell
SayColumnHeader
SayRowHeader
SayMessage
SayControlInformation

String and Integer Manipulation

Use the following functions to obtain data about and manipulate strings.

StringContains
SubString
StringToInt
IntToString
StringLength
StringLower
StringUpper
StringSegment
StringLeft
StringRight
ProcessNewText
FormatString
Min
Max

Application

Use the following functions to acquire information about an application.

GetAppFileName
GetAppTitle
GetAppFilePath
GetTreeViewLevel
GetProgramVersion
GetWindowAtPoint
IsPointInWindow

Braille

Use the following functions to query Braille conditions and display lines on the
Braille display.

BrailleInUse
PriorBrailleString
BrailleString
NextBrailleString
BraillePanLeft
BraillePanRight
BrailleLine
SixDotBraille
EightDotBraille
GetBrailleCellColumn
GetBrailleCellRow
GetBrailleMode
SetBrailleMode
GetLastBrailleRoutingKey
BraillePriorLine
BrailleNextLine
BrailleG2StringLength
BrailleRefresh
BrailleString
IsBrailleCursor
BrailleAddFocusItem
BrailleAddFocusLine
BrailleAddFrame
BrailleAddString

Mouse

Use the following functions to move, click, and get information about the mouse
pointer.
MouseUp
MouseDown
MouseLeft
MouseRight
LeftMouseButton
LeftMouseButtonLock
ShiftLeftMouseClick
AltLeftMouseClick
ControlLeftMouseClick
IsLeftButtonDown
RightMouseButton
IsRightButtonDown
GetCursorShape
DragItemWithMouse

Find

Use the following functions to find specific information on the screen.

FindFirstAttribute
FindPriorAttribute
FindNextAttribute
FindLastAttribute
FindGraphic
FindString
JAWSFind
JAWSFindNext
FindColors
FindDescendentWindow
FindTopLevelWindow

Windows and Objects

Use the following functions to acquire information about windows and objects and to
move from window to window.

GetForegroundWindow
GetCurrentWindow
HasTitleBar
GetRealWindow
GetAppMainWindow
GetFirstWindow
GetPriorWindow
GetNextWindow
GetWindowLeft
GetWindowRight
GetParent
IsWindowDisabled
IsWindowObscured
IsWindowVisible
GetFirstChild
GetWindowClass
GetWindowName
GetWindowsOS
GetWindowSubtypeCode
GetWindowType
GetWindowTypeCode
GetWindowText
GetWindowTextEx
JAWSWindow
MinimizeAllApps
SayWindow
SayWindowTypeAndText
GetFocus
SetFocus
HasFocusRect
SayFocusRect
SayFocusRects
GetFocusRect
GetFocusRectBottom
GetFocusRectLeft
GetFocusRectRight
GetFocusRectTop
GetTextInFocusRects
ActivateMenuBar
DialogActive
GetDialogPageName
GetDialogStaticText
IsMultiPageDialog
GetControlID
GetCurrentControlID
GetDefaultButtonName
MenusActive
GetObject
GetObjectAtPoint
GetObjectType
GetObjectTypeCode
SayObjectTypeAndText
GetCurrentObject
GetFocusObject
GetObjectName
GetObjectValue
GetObjectRect
GetObjectState
GetLineTop
GetWindowBottom
GetWindowTop
RefreshWindow
ToggleHomeRow
ControlCanBeChecked
ControlIsChecked
GetGroupBoxName
GetControlAttributes
SayObjectActiveItem
IE4GetCurrentDocument
GetHTMLFrameCount
GetLinkCount
MSOGetMenuBarObject
GetItemRect
GetWindowRect

Frames

Use the following functions to read and manipulate frames.

GetFrameDescription
GetFrameNameAtCursor
GetFrameSynopsis
SayFrame
SayFrameAtCursor
GetTextInFrame

Scripts

Use the following functions to get information about scripts and script files and
control their operation.

GetCurrentScriptKeyName
GetScriptDescription
GetScriptKeyName
GetScriptKeyNames
GetScriptSynopsis
IsSameScript
PerformScript
AddHook
RemoveHook
TrapKeys
SwitchToScriptFile
GetScriptFileName

SDM

The following functions are used to get information about SDM Dialogs only.

SDMGetFocus
SDMGetFirstControl
SDMGetPrevControl
SDMGetNextControl
SDMGetLastControl
SDMSayControl
SDMSayWindowTypeAndText
SDMGetCurrentControl

Speaking Level

The following functions query verbosity settings and/or reset them.

GetScreenEcho
ScreenEcho
GetVerbosity
VerbosityLevel
ShouldItemSpeak

Options

Use the following functions to get JAWS settings information and change them.

SetJAWSLanguage
GetJCFOption
SetJcfOption
GetDefaultJcfOption
SetDefaultJcfOption
GetJAWSDirectory
GetJAWSSettingsDirectory
GetJAWSHelpDirectory
GetJAWSUserName
GetJFWVersion
GetJFWSerialNumber
InHJDialog
IsJFWInstall

System Activities

Use the following functions to interact with the system.

MessageBox
ExMessageBox
InputBox
GetHotKey
PassKeyThrough
PlaySound
Pause
Delay
Refresh
Run
FileExists
GetFileDate
DLGSelectItemInList
DLGSelectScriptToRun
DLGSysTray
DLGSelectControls
ScheduleFunction
UnscheduleFunction
ActivateStartMenu
Beep
CopyToClipboard
ClipboardHasData
GraphicsLabeler
SetGraphicLabel
GetGraphicID
GraphicsEnumerate
GraphicsListHelper
ShutDownJAWS
ScreenGetWidth
ScreenGetHeight
SysTrayGetItemCount
SysTrayGetItemToolTip
SysTrayMoveToItem
SysGetDate
SysGetTime
StartJawsTaskList
GetWindowsSystemDirectory
ShowHelpByName
ShowHelpByID
IsKeyWaiting
IniReadInteger
IniWriteInteger
IniReadString
IniWriteString
IniRemoveKey
IniRemoveSection

Colors

The following functions can be used to learn about and manipulate screen colors.
GetColorBackground
GetColorText
GetColorName
ColorToRGBString
RGBStringToColor
GetColorField

Control Synthesizer

The following functions are used to control synthesizer activity.

ResetSynth
SpeechOn
SpeechOff
IsSpeechOff
StopSpeech
SpeechInUse
SetSynth
SetSynthLanguage
GetVoiceVolume
SetVoiceVolume
GetVoiceRate
SetVoiceRate
GetVoicePitch
SetVoicePitch
GetVoicePunctuation
SetVoicePunctuation
GetVoicePerson
SetVoicePerson
GetSynthVolumeRange
GetSynthRateRange
GetSynthPitchRange
GetVoiceParameters
SetVoiceParameters

Appendix E

How to Scope Out and Customize an Unknown Application

(courtesy of Glen Gordon)

I. Determine how well the app works with no customizations

A. Do dialog boxes speak properly?
B. Can the user quickly locate important information on the screen?
C. Can the keyboard be used to accomplish all tasks?
D. What information should be combined on the Braille display for quick access?
II. investigating dialog boxes
A. The Utility scripts on the Home Row keys (See Chapter 8.1) and the
ScreenSensitiveHelpTechnical script (CONTROL+INSERT+F1) (See Chapter 8.2) can help
with the following:
1. Determine if each control is its own window.
2. if controls have nonstandard window classes, try reassigning them. Does this
cause the right window types to be spoken when tabbing to them? (Unknown window
classes can be reassigned to known classes using the Window Class Dialog accessed
with INSERT+7 or with INSERT+F2 followed by the letter W and ENTER.)
Reclassification of edit fields in Internet Explorer in this way results in proper
reading of these fields.
If the PC cursor doesn't track the proper item in a nonstandard control:
1. Try setting TrackFocusRect=1 in the application JCF file. This is done by
adding this line to the [OSM] section of the appropriate JCF file. This should
allow the PC cursor to track the focus if it is a focus rectangle. (Some
spreadsheets like Microsoft Excel use a variant of the focus rectangle which can
only be tracked by checking the Include Lines checkbox found in the Advanced
Options dialog of the Configuration Manager's Set Options menu.) If either of
these cause the focus to track, automatic speaking can be scripted by adding
SayFocusRect function calls to the scripts bound to the cursor and Tab keys.
2. Modify the FocusChangedEvent or SayFocusedWindow function to do custom
processing for troublesome dialogs. See the EUDORA.JSS FocusChangedEvent function
for examples.
3. Write a custom function for each dialog, and have the FocusChangedEvent call
that function when that dialog is active. For an example, see the
FocusChangedEvent function in the WINWORD.JSS which has been modified to handle SDM
windows and two versions of Microsoft Word.
4. When tabbing between controls, does the FocusChangedEvent get called? If not,
add the line ForceFocusChange=1 to the [OSM] section of the application's JCF file,
and try again. The FocusChangedEvent function is normally only called when the new
focus has a different window handle from the prior focus. In some applications
like certain parts of MS Access, an edit field can have the same handle as the
prior field. Enabling the ForceFocusChange option forces the FocusChangedEvent to
run if the new window has different pixel coordinates from the old.
5. Do controls have unique control IDs? If so, use them to identify which control
is active. Thus, one could use an If-Then statement to check the value of the
window's Control ID and then perform certain operations or speak certain messages
for each unique Control ID.
6. Use pixel coordinates to identify which control is active. (Coordinates should
be window, not screen relative.) Thus, one could use an If-Then statement to check
the value of the current pixel location and then perform certain operations or
speak certain messages for each unique set of coordinates.
7. write custom code for each problematic control.
a. if the dialog is just one big window (i.e., controls do not have unique Control
Ids), by setting TrackFocusRect=1, the PC cursor may move as you TAB among
controls.
b. write a script to say the proper information based on pixel location, and attach
it to the TAB and SHIFT+TAB keys.
III. Locating important information on the screen:
A. Create frames around areas of interest. Assign them to hot keys or make them
speak automatically. (An example of where this could be done is the status line
page numbers in Microsoft Word. One could read the current page number with a hot
key set to read the frame or create a frame to echo all changes in the page number
automatically.)
B. Traverse the window hierarchy to find information of interest. That is, move up
or down to parent and child windows or among windows at the same logical level to
find a control or text field of interest.
C. Search for text or a graphic on the screen. An example of this would be to
search for the toolbar buttons in Microsoft Office to check their pressed or non-
pressed status. This is not as reliable as traversing the hierarchy.
IV. Providing enhanced keyboard access
A. write scripts to move to and click on particular locations and attach them to
keys. This simulates keyboard access and increases efficiency.
1. Use the function, MoveToFrame, to position to important locations within user-
defined frames.
2. Use the function, MoveTo, to position to important locations anywhere on the
screen.
3. Use the function, FindGraphic, to position to important locations associated
with graphics.
4. Use the function, FindString, to position to important locations that contain
specific text.
V. Customizing information for Braille
A. Modify BrailleBuildLine to combine relevant information in different
circumstances Such as braille build dialog, menu, and other in the default scripts.
B. Modify BrailleBuildStatus to use BrailleSetStatusCells to provide context
dependent information such as attribute information.
C. Add informational messages.
1. Provide custom versions of HotKeyHelp (INSERT+H).
2. Provide custom versions of ScreenSensitiveHelp (INSERT+F1).
VI. Naming application-specific scripts and functions:
A. If it has a similar purpose as a script or function in the default file, give it
the same name, and don't make an application specific key assignment. The
assignment in the default keymap will invoke it.
B. Use the application specific keymap to assign keys to scripts that are unique
(and uniquely named) to that application. For example, see the use of F7 for Spell
Check in Microsoft Word.
C. If a script handles both normal and special case situations, then have that
script call the default version from the DEFAULT.JSS for all normal situations
rather than duplicating the default code in the application script file. The
application script should contain the special code needed for the special
situations.
1. Use scripts to create actions that can be attached to keys.
2. Use functions for creating subroutines that will not need to be attached to
keys.
Make use of the Synopsis and Description fields when creating scripts and
functions. They provide the text spoken when in Keyboard Help mode.