Access Issues

An Introduction to JAWS Scripting

Joe Lazzaro

Users of screen readers have long been plagued with the plight of configuring their adaptive equipment to work with mainstream software. If you are a user of JAWS for Windows, you're probably aware that the package contains a built-in scripting language that lets you make mainstream applications appear more speech friendly and accessible. You have probably also heard that scripting is not for the faint of heart or the technologically timid. But, fear not. This article introduces you to the basics of JAWS scripting: why scripts are sometimes necessary, the structure of scripts, the Script Manager, and how to begin to tackle a scripting job. It is intended for beginners to JAWS scripting or those who want a basic overview of its overall utility for making applications appear more accessible.

Because of space limitations, I have tried to cover the main points to get you started quickly. As a consequence, a lot of material has had to be trimmed to its barest bones, and some aspects have been omitted. If sufficient interest arises and time permits, I may write a more advanced article on the subject in the future. For those interested in pursuing the subject further, Freedom Scientific offers beginner and advanced scripting classes at its Florida facility and on site. See AccessWorld News in this issue and visit <www.freedomscientific.com> for information about the costs and dates of the classes.

Definitions

A JAWS script is merely a bridge between the screen reader and the mainstream application. The script does not change the application itself but, rather, helps JAWS extract information from the application that it needs. A script can make an ill-behaved application speak more easily and naturally for the user and can also provide functionality that previously did not exist. For example, you can use scripts to build hot keys to read any part of the screen and to move to parts of an application that are not navigable using keyboard commands. These are only two examples of how scripting can be used to make an application more accessible.

So, What Are Scripts?

A script is a series of instructions that your computer carries out in sequence, similar to a batch file, that are stored in a file. Script files can contain hundreds or thousands of individual statements that are executed by a single keystroke, not unlike a macro. You write your script in a text editor and then save the source code to disk. The script source code resembles most high-level languages, similar to Visual Basic, and is fairly easy to understand as languages go. You then compile the source code into machine-readable language by running it through the compiler program, which enables it to run on your computer. Once the script has been successfully compiled, you can run it by hitting the trigger keystroke or by running the application for which the script was written. Once started, the script extracts the information it needs from the application and can make decisions that are based on that information on how and what to read. JAWS includes a speech-friendly manager for creating, editing, and managing script files.

A script file can contain one or more actual scripts. The JAWS script language includes two fundamental types of scripts: default and application. JAWS Script Source (JSS) files are where the source code for a given script or function is stored. The Default.jss file is the core script file for JAWS and contains all the basic functions that allow the screen reader to interact with Windows-based applications. This default script file is loaded each time JAWS is started and is always in the background. Application script files are loaded on top of the Default.jss file and are started when an application is launched. The application script file bears the same name as the application it is designed for. For example, the Windows Calculator application script file is named Calc.jss, and the script for Notepad is Notepad.jss. When you start the calculator, Calc.jss is loaded automatically, and the scripts for that application become active. When you exit or switch focus away from the calculator, the Calc.jss file is unloaded from memory, and the Default.jss script takes over again.

So how does JAWS keep all this straight? JAWS is constantly monitoring the keyboard, looking for keystrokes that it can process. When you strike a key, JAWS first searches the applications script file for a match. If it doesn't find one there, it then looks in the Default.jss file for a match. If none is found there, it passes the keystroke on to the application. If, however, it finds a match in either file, it executes the script attached to that keystroke.

Binding Keystrokes to Scripts

As I discussed earlier, a keystroke can trigger scripts into operation. So when you create a script, you will be asked if you want to attach it to a keystroke. This is known as binding, or binding the keystroke to the script. When you hit the bound keystroke, the script will run, provided that you did everything correctly.

When you press a key that is bound to a script, JAWS searches the application and default file for a match and executes the script bound to that keystroke. But what if you try to use a keystroke that is already assigned to another script? If the bound key is, by chance, the same in both the application and the default script files, then the script in the applications file takes precedence. The Script Manager will warn you when you are trying to bind a keystroke to a script in the applications file that is already bound to another script in the Default.jss file, helping you to avoid conflicts and rendering scripts in the default file accidentally inoperative.

What's Your Function?

Another type of script does not require a bound keystroke to operate. These scripts are called functions and can run automatically when Windows events take place. Some of these events are when an application starts, when new text appears on the screen, when an application exits, and when the focus changes. Thus, you can do lots of cool stuff seemingly automatically. The JAWS scripting language includes over 600 built-in functions that can be used to construct new scripts. These functions include commands like SayString, SayWord, SayLine, NextWord, PreviousWord, SayFont, SayFromCursor, SayWindowTitle, SayRowHeader, and SayHighlightedText. You can browse the list of script functions from within Script Manager and insert them in your creations.

Command Central

JAWS includes a built-in Script Manager that lets you create, edit, and manage script files. The Script Manager is command central when it comes to scripts. You can use the manager to create new scripts, to compile scripts that you have written, and to modify existing scripts that are stored on the system. You can bring up the Script Manager by hitting Insert-F2 for the JAWS Manager Menu, scrolling down to the Script Manager item, and then pressing Enter. If you have an application open when you run Script Manager, the Script Manager will be launched with the application script for that particular program loaded. You can then examine the script bound to this application, modify the script if you wish, and recompile it to run. A word of caution: It's not a good idea to fool around with modifying existing scripts because doing so can have unpredictable results, especially for those who are not familiar with the language. Be sure to make backup copies of your Settings directory before you play around with editing and recompiling any scripts that are stored in your system.

For Example

You can get an idea of how Script Manager works by starting an application and then running the JAWS Script Manager to examine its application-specific script file. Let's start with an example that is relatively safe. First, start the Windows Calculator program by hitting Control-Escape to go to the Start Menu. Then use the Down Arrow until you hear Programs, then use the Down Arrow until you hear Accessories, and press Enter. Continue to use the Down Arrow key until you hear Calculator, and then press Enter to launch the calculator. If you've done everything correctly, the Windows Calculator program should now be loaded and should have the focus (that is, it will be in the foreground of all the programs running, and you can issue it commands). Now, with Calculator holding the focus, press Insert-F2 to bring up the Run JAWS Manager menu. Use the Down Arrow to get to Script Manager and press Enter. The Script Manager will start up with the Calc.jss script file loaded, ready for you to examine.

At this point, simply use your arrow keys to read through the Calc.jss script file. This file actually contains many individual scripts. You can move forward and backward from one script to another by using the F2 and Shift-F2 key commands, respectively. You can also use the Control-L command to list all the script names that are stored in the Calc.jss file. Once you've browsed through the Calc.jss file sufficiently by using the Arrow keys, try using the F2 and Shift-F2 commands to move through the file one script at a time. Now you can create and compile your first simple script.

The Hello World Script

In learning any computer language, from Pascal to Visual Basic, I've always found it immensely helpful to create a Hello World program first. This program lets you create a new program, compile it, and run it, just to get an overview of the entire creation process from beginning to end. The Hello World script or program is simple. When it is run, the Hello World script prints the message "Hello World" to the screen and speaks it aloud. This may not appear complex on the surface, but it allows you to learn exactly how a script is created, compiled, saved, and finally run. To create a Hello World script within the Notepad.jss file, do the following:

Start Notepad and make sure it has the focus.

Start the Script Manager. Simply hit Insert-F2 and then arrow down to the Script Manager and hit Enter. This will open the Notepad.jss script file and place you at the beginning. You can use your arrow keys to read through this file. It may or may not contain any scripts, depending on your JAWS version.

In either case, press Control-End to move to the end of the file and press Enter to make a blank line. It is standard practice to put all new scripts at the end of any existing script file. Now that you're at the end of Notepad.jss, press Control-E to bring up the New Script dialogue box and start composing your first script.

The first field in the New Script dialogue box asks for a name for the new script. Type in a name and press the Tab key to go to the next field. It's important to name scripts appropriately, as you will soon see.

The next field is a check box, which asks if you want to attach the new script to a keystroke. If you want your script to be bound to a key, and you do in this example, make sure that this box is checked.

The next field in the New Script dialogue box asks for a synopsis of the script. Go ahead and type a short description. It's good practice to type in the bound keystroke, as well as the name of the script here. Type "Control-1 Hello World Script." The synopsis text you just typed will be useful later when you use the built-in JAWS keyboard Help, which can be turned on by hitting Insert-1 and turned off by again pressing Insert-1.

The next field in the New Script dialogue box asks for a description of your new creation. You can use this field to provide a more comprehensive description of the new script and its exact function.

The next field in the New Script dialogue box is called Category and is not used at this time. Simply use the Tab key to skip over this field.

The next field is much more important. It asks for the key that you want to bind to the new script. This is the hot key that will run your script. You should not use any standard Windows keyboard shortcuts or reserved JAWS keystrokes in this field to avoid potential conflicts. But if you do so by mistake, Script Manager will warn you before it accepts the bound keystroke. In this example, bind the Control-1 keystroke to this script, since it is not reserved for other purposes. Simply press Control-1 to bind the keystroke. (Do not type the dash character.) Tab to the OK field, and you're almost done. Once you press OK, you will be placed in the editor, where you can start writing your new script. Be aware that Script Manager inserts some boiler-plate code to make your job easier. It should read something like this:
Script HelloWorld ()
EndScript
If you examine these two lines of code, you will see that the Script Manager has inserted the header and footer for your new script. (Script Manager also inserts several blank lines between the header and footer, but these lines have been removed here to save space.) All you have to do is insert the SayString command and its parameters to make the script complete. Simply type the SayString command and its parameters in between the header and footer as shown next:
Script HelloWorld ()
SayString ("Hello World!")
EndScript

Now try to compile your Hello World script and see if it will run. Simply hit the Control-S key command to compile your script and save your new script at the same time. If you've done everything correctly, you should receive the message "Compile Complete." This message means that the Script Manager detected no syntax errors in your script, and it should run when you hit the bound keystroke.

Now run your script. You can't run the script from within Script Manager because the script was written for Notepad and will work only if and when Notepad has the focus. So, bring Notepad to the focus by hitting Alt-Tab. Then hit the Control-1 key command that you bound to your new script. You should hear JAWS announce "Hello World."

If the compiler gave you an error message when you tried to compile your script, then you have to debug the code. Be sure that the code looks exactly like the example given here and that you have typed all the punctuation marks, including quotes and parentheses. Writing code is unforgiving, and you must spell all the commands correctly and include any necessary punctuation. To help you do so, the JAWS Script Manager includes a pull-down list of all functions that you can use for your scripts. To use it, just begin a new script with Control-E and fill out the New Script dialogue box, which will place you in the code window with the header and footer of your new script. Put your cursor between the header and footer lines and press Control-I, which will bring up the Insert Function list. You can use your arrow keys to scroll through this list and get a quick overview of the building-block functions available to construct your scripts.

A word about documentation. It's important to document your source code fully to make it easier for you and others to read it. You do so by adding explanatory lines to the script and beginning these lines of documentation with a semicolon ";" character, as follows:
;Hello World Script
Script HelloWorld ()
;Speaks Hello World when Control-1 is pressed
SayString ("Hello World!")
EndScript

Conclusion

Scripting is a recognized and accepted tool in many aspects of the computer world. Microsoft Windows itself has a built-in script language that can be used to run and control applications. The JAWS Script language is not greatly dissimilar, except that it has been specialized for speech and braille output. The JAWS script language can extract and expose information from within application programs and spoon-feed that information to your synthesizer or braille display.

Learning how to script is not for those who consider themselves timid, but it can most definitely be done if the right approach is taken. The Hello World example will allow you to create, save, compile, and run a script. You can do it. You can write scripts, starting out small and working your way up. Not only that, but people who can write JAWS scripts can earn good wages for their work, and organizations are seeking competent scripters to make their information technology infrastructure more accessible. The web site <www.BlindProgramming.com> offers resources for JAWS scripters and computer programmers and is a good place to meet like-minded people. The web site is comprehensive and includes several electronic discussion groups to discuss various aspects of programming. Now that you've gotten your feet wet, maybe it's time to dive into scripting for fun and profit!

Related Links

Our Mission

AccessWorld® keeps people with vision loss and their
families, teachers, rehabilitation counselors, product
developers, and manufacturers up-to-date about the
technologies that can transform their lives.