Technical Overview of Scripts

Introduction

You can think of a script as a block of code that contains sequences of individual steps used to activate and control a wide variety of computer processes. A script is like a mini computer program that combines a number of steps into one operation. The action a script performs ranges from tasks as simple as entering repetitive strings of data to many of the standard routines your computer does on an ongoing basis as part of its operation.

Scripts or combinations of scripts and functions control most JAWS facilities. Scripts analyze what actions are taking place in an application and determine how to handle the screen reading for you.

Script files also contain a second block of code called a function. Like a script, a function is also a sequence of statements that perform a given task. However, functions differ from scripts in that you cannot activate them with a keystroke.

You create scripts and functions with the Script Manager. You use a standard set of programming codes, formats, and rules to create your scripts and functions. After you have written your script or function, you compile your script or function into machine-readable language, so that the computer can understand the instructions. Once you compile your scripts or functions, they are ready for your use.

JAWS Scripts and Script Files

A script file is a file that contains multiple scripts and functions. You can find a number of script files in the JAWS shared settings folder. These script files all have the extension of .jss for JAWS script source. For example, the Default.jss script file contains all the scripts and functions JAWS uses to interface with Windows applications. JAWS also uses application-specific script files. These files contain all the scripts and functions needed to access information in a given application. JAWS loads the application script file on top of the default script file when you start the corresponding application.

::: {#default-script-file}

Default Script File

Default Script File :::

JAWS loads the default script file each time it starts. The scripts and functions contained in this file are active in all applications. JAWS receives all the information from the scripts contained in the default script file it needs to provide proper voice output. The scripts within this file tell JAWS what to speak and when to speak it in most circumstances. The default script file is named Default.jss.

::: {#application-specific-script-files}

Application Specific Script Files

:::

The second type of script file JAWS uses is specific to a Windows application. You create an application-specific script file when you encounter situations that require customized reading of the screen. JAWS loads the application-specific script file when the application is started or becomes active. For example, an application named spreadsheet.exe has a script file called spreadsheet.jss. The application script file must exist in either the JAWS shared or user settings folder in order to be loaded with the application at run-time.

When the spreadsheet application is no longer active, JAWS unloads the Spreadsheet.jss script file. All of the default scripts then become active until JAWS loads another application's script file.

::: {#processing-keystrokes}

Processing Keystrokes

Processing Keystrokes :::

Each time you press a keystroke, JAWS goes through a series of steps to determine what action to perform. Even though your scripts may have different names, it is the keystroke binding that determines which script is performed. JAWS must first determine where the keystroke is assigned.

::: {#application-specific-key-map-file}

Application-Specific Key MapFile

:::

JAWS first looks for the keystroke assignment within the application-specific key map file. If JAWS finds the keystroke assignment in this file, then the name of the script associated with the keystroke is noted.

::: {#application-specific-script-file}

Application-Specific Script File

:::

JAWS then looks for the name of the script in the Application-specific Script file. If JAWS finds the script, then JAWS performs the script and no further processing is done.

::: {#default-key-map-file}

Default Key Map File

:::

If JAWS does not find the keystroke assignment in the application-specific key map file, then the default key map file is searched. If JAWS finds the keystroke assignment in this file, JAWS notes the name of the script activated by the keystroke.

Before JAWS executes the script, JAWS must determine if the script is contained in the application-specific script file.

::: {#application-specific-script-file-1}

Application-Specific Script File

:::

JAWS searches the application-specific script file for the script name found in the default key map file. If JAWS finds the script, then JAWS performs the script and no further processing is necessary.

If JAWS does not find the script within the application-specific script file, then JAWS searches the default file. If JAWS finds the script in the default file, then JAWS performs the script and no further processing is required.

Unknown Script Call

When JAWS does not find the name of the script attached to the keystroke in either the application specific or default script files, then an unknown script call error message occurs. JAWS speaks "unknown script call to" followed by the name of the script and then it is spelled. An unknown script call can occur when either the script has been deleted from the application-specific or default script file or when the name of the script is misspelled in the key map or script file.

To keep these types of errors from occurring, you should use the Script Manager to remove a script and its associated key map and documentation entries.

Passing the keystroke Through

If JAWS does not find the keystroke assignment in either key map file, then JAWS passes the keystroke through to the application. The application performs the keystroke just as if JAWS were not running. JAWS always performs a script in the application script file rather than a script found in the default script file even when you make the key assignment in the default key map file.

Assigning keystrokes

You can assign a keystroke to a customized script in an application-specific script file even though it is assigned in the default key map file. In doing so, you will not encounter any adverse consequences.

When you use a keystroke that is already defined in the default key map file, the default functionality is lost for only that application. For example, when you assign CONTROL + JAWSKEY + V to a script contained in the Notepad script file, the default script SayAppVersion, is no longer performed. JAWS recognizes the fact that you have used the default keystroke for an application-specific script.

So, JAWS does not perform the SayAppVersion script when you are using Notepad.

If you give the script in the application file the same name as the script in the default script file, you do not need to assign a keystroke to the application-specific script. JAWS performs the script in the application script file instead of the script found in the default file if they are both bound to the same keystroke. For example, you can find the AdjustJAWSOptions script in both the default script file and the Internet Explorer script file. The keystroke is assigned only in the default key map file. When you press JAWSKEY + V while you are in Internet Explorer, JAWS finds and performs the application-specific version of the AdjustJAWSOptions script. However, when you are using Notepad and press JAWSKEY + V, JAWS performs the AdjustJAWSOptions script from the default script file.

If you attempt to assign a script to a keystroke which is already in use by the default file, then JAWS displays a warning dialog. This warning dialog gives you 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. :::

Scripts vs. Functions

To this point we have discussed scripts as the primary way you interact with JAWS. A script is generally an entry point you invoke directly (for example, by pressing a keystroke or choosing a menu item). A function, by contrast, is a reusable block of code stored in a script file that is intended to be called by other code or the runtime. Functions let you encapsulate behavior, accept input, and optionally return a result when they finish executing.

In the JAWS Scripting Language (JSL) functions have several important properties worth understanding:

- Parameters and return values: A function may accept zero or more parameters supplied by its caller and may return a single result. Typical parameter types are numbers, strings, booleans, or runtime handles provided by the JAWS API. If you need to pass complex state, prefer passing compact identifiers or using clearly documented global objects.

- Side effects and purity: Some functions are written as "pure" helpers (they only compute and return a value), while many JSL functions produce side effects such as speaking text, moving the cursor, or changing settings. Minimize unexpected side effects and document them clearly so callers can rely on your function's behavior.

- Scope and visibility: User-defined functions live in script files and are visible to other code loaded together. Application-specific script files are loaded on top of the default script file, so an application script can override a function from the default file. To avoid accidental conflicts, choose descriptive, namespaced names for functions.

- Calling conventions: Functions are invoked by name from scripts or other functions. Event handler functions are invoked automatically by the JAWS runtime when matching events occur (see the next subsection). Built-in functions are called the same way as user functions but are supplied by the JAWS core.

- Compilation and runtime: Script files are compiled by the Script Manager before use. Syntax errors are reported at compile time or when a function is first executed; logical or runtime errors surface during execution and should be handled or documented.

There are three broad categories of functions used in JAWS scripting:

Event functions: Handler functions that the JAWS runtime invokes in response to UI or system events (for example, focus changes, new text on the screen, or cursor movement). These functions follow specific naming or registration conventions so the runtime can find and call them automatically. You usually do not create new event types, but you can implement or override existing event handlers in application-specific script files to customize how JAWS responds to those events.
Built-in functions: Functions provided by JAWS itself (the runtime and default scripts). These implement low-level operations---navigation helpers, speech primitives, cursor operations---and form the standard library available to all scripts. Built-in functions cannot be modified, but they can be called from your code.
User-defined functions: Functions you write to encapsulate reusable, application-specific logic. Use these to factor repeated behavior out of scripts, to expose small internal APIs, and to make scripts easier to test and maintain. Keep user-defined functions focused, give them descriptive names, document expected parameters/returns, and avoid relying on undocumented global state.

Best practices when designing functions in JSL:

Prefer small, single-purpose functions that are easy to read and test.
Document parameter meanings, return values, and any side effects (speaking, cursor movement, global changes).
Use clear naming to avoid collisions with default or application-specific functions.
Minimize and isolate side effects where practical; if a function must change global state, make that explicit in its name and documentation.
When overriding default behavior in an application script, call through to the default implementation only when appropriate and well understood.

Event Functions

JAWS performs event functions automatically when windows events occur. Without these event functions, JAWS does not speak system changes automatically.

You cannot create new event functions. However, you can modify existing event functions. You can also create application-specific versions of the event functions found in the default script file.

Some of the event functions within JAWS include:

AutoStartEvent () BottomEdgeEvent () FocusChangedEvent () NewTextEvent ()

JAWS performs the AutoStartEvent function each time an application is started or becomes active. JAWS performs the BottomEdgeEvent each time the active cursor reaches the bottom edge of a window. JAWS performs the FocusChangedEvent function when focus moves between applications, dialogs, and dialog controls. JAWS performs the NewTextEvent function each time any new text is written to the screen.

Built-in Functions

There are over 1300 built-in functions that are available for use in creating new or modifying existing JAWS scripts. You can think of the built-in functions as the building blocks of your scripts and functions. Some built-in functions include: SayLine, JawsCursor, NextWord, and PriorWord. You cannot modify existing built-in functions.

Built-in functions are performed when they are called by another script or function. These functions are performed by placing the name of the function within the coded lines of another script or function. When the script gets to the line that includes the name of the function, the function is performed. This process is known as "calling" a function.

User-defined Functions

You can find user-defined functions in script files. These functions are developed by either Freedom Scientific script developers or by a script developer outside of Freedom Scientific. These user-defined functions have been created for some special purpose and can also be modified. Like built-in functions, user-defined functions are called from a script or another function.

What are Scripts Exercises

.exercise

Performing Scripts

The objective of this exercise is to show how a single keystroke can activate either an application-specific script, or a script found in the default script file.

Press WINDOWSKEY + M to minimize all of your running applications.
Start Notepad from the start menu. You can find the Notepad application in your Programs | Accessories group within your Start Menu.
After Notepad starts make sure it is the active application by pressing JAWSKEY + T. You should hear JAWS speak "Untitled - Notepad".
Press JAWSKEY + V to activate the Adjust JAWS Options dialog. Note how many items are found within this dialog. How many are there? What was the first item in the tree view?
Press ESC to close the Adjust JAWS Options dialog and return to Notepad.
Press WINDOWSKEY + M to minimize all of your running applications and make the Desktop active.
Press I until you locate the Internet Explorer icon on your desktop. When you find the icon, press ENTER to start Internet Explorer.
Press JAWSKEY + T to read the title of the active window. Internet Explorer should be the active application.
Press JAWSKEY + V to display the Adjust JAWS Options dialog. How many items are in this tree view? Is the tree view different from the tree view you saw while in Notepad? Why?

Additional Practice: Open multiple different applications (such as Word, Excel, Firefox, and your email client) and examine how the Adjust JAWS Options dialog differs in each application. Pay special attention to which options appear in some applications but not others. Create a brief note documenting how JAWS adapts its available options based on the active application. This demonstrates how JAWS uses both default and application-specific scripts.

:::

Creating Scripts Exercises

The objective of this exercise is to give you some practice adding comments and include statements to your script file. Before you begin this exercise, make sure you only have JAWS and Notepad running. You can press JAWSKEY + F10 to list all of your running applications.

Press JAWSKEY + F2 followed by S and ENTER while Notepad is the active application. This opens The Script Manager with the Notepad.jss file in the edit window.

Unless you have written any scripts in the Notepad script source file, this file will be empty.
Press CONTROL + HOME to move to the top of the file. This ensures the insertion point is at the top of the script file.

If the insertion point is already at the top of the file, you may hear a windows system sound.
Type a semicolon (;). This starts a comment line in the script file.
Type the text "JAWS [ version ] Script file for Notepad in Windows X" where X denotes the operating system you are using and version denotes the version of JAWS you are writing scripts for. At the end of this line, press ENTER to move the insertion point to the next line.
Type a semicolon (;) to begin a second comment line in your script file.
Type the text of "Written By" followed by your name and the current date. At the end of this line press ENTER to complete the line and move the insertion point to a new blank line.
Press ENTER twice. This will create a blank line and then move the insertion point to a second blank line after your comment section. This will help separate the comment section from the area where include statements are placed.
Type include "HJConst.jsh" This adds an include statement telling JAWS to include the contents of the HJConst.jsh file within the Notepad script file. Press ENTER to complete the line and move the insertion point to a new blank line.

When you type the include statement, the file name must be surrounded by quotation marks.
Press CONTROL + W to save your script file without compiling.

After completing the steps above, your Notepad script file should start with the following lines:

; JAWS [ version ] Script file For Notepad in Windows X
; Written by your name On mm/dd/yy
Include "hjconst.jsh"

The text of your name should be replaced with your actual name. The date should also be filled in for the date you are doing this exercise.

Additional Practice: Add a third include statement to your Notepad script file that references a header file. Examine the Script Manager's documentation to understand what HJConst.jsh, common.jsm, and other commonly included files contain. Write comments in your script explaining why you included each file and what major constants or functions you plan to use from each one. This demonstrates understanding of code organization best practices.

The HelloWorld Script

The objective of this exercise is to use the New Script dialog to create your first script. If you have just completed the previous exercise, make sure that Script Manager is the active application. If you have closed the Script Manager, make sure Notepad is still running, switch to Notepad, and follow step 1 in the previous exercise to start the manager.

Press CONTROL + END to move to the bottom of the Notepad script file. This will ensure your new script is created at the bottom of the file below the comments you added in the previous exercise.
Press ENTER twice to create a blank line between the Include statement and your new script.
Press CONTROL + E to display the New Script dialog. The Script Name edit box is active.

Script names cannot contain spaces or any punctuation marks such as dashes or underlines. The Script Manager will cause a system beep to occur any time you attempt to add any of these characters to your new script name. You should also capitalize the first letter of each word in a multiple word script name.
Press TAB to move to the Can be Attached to Key check box and press SPACEBAR. This step tells JAWS you want to create a script and not a function.
Press TAB to move to the Synopsis edit box. Type "Speaks a message in Notepad" into this edit box without the quotation marks. This text is spoken by JAWS when you ENTER Keyboard Help and press the keystroke that activates this script.
Press TAB to move to the Description edit box. Type "Speaks a hello world message in Notepad." without the quotation marks. The description is heard when you ENTER keyboard help and press the keystroke that activates this script twice in succession.
Press TAB to move to the Category list box. Since this is not used, you do not need to select an item from this list.
Press TAB to move to the Assign To edit box. Be careful as any keystroke you press while in this edit box will be used as the keystroke that activates this script. Press CONTROL + 1 in the numbers row, not the number pad. Since the Ok button is the default button in this dialog, you can press ENTER to close the New Script dialog and return to the Notepad script file.
Press UP ARROW once to move the insertion point to the first blank line in the body of the script. Type the following text:
```
SayString ("Hello World!")
```
The SayString function is no longer used to speak messages with JAWS. This function is obsolete and should only be used for debugging scripts and functions.
After you have typed the line of text above, the insertion point is at the end of the line. Press DOWN ARROW once to move to the next line. You can press DELETE twice to remove the remaining blank lines.

After you have followed the steps above, you should have the following script in your script file:

Script HelloWorld ()
    SayString ("Hello World!")
    EndScript

If your script does not look like the one above, make corrections as needed. You can edit the text of any script just as you would in a word processor or text editor.

Additional Practice: Modify the HelloWorld script to use different JAWS functions. Instead of SayString, try using SayFormattedMessage with different output type constants (such as OT_MESSAGE, OT_STATUS, or OT_ICON). Create several variations of this script, each assigned to different keystrokes, and test each one to observe how JAWS handles different output types and how they affect the user experience.

Compiling and testing the HelloWorld Script

The objective of this exercise is to compile and test the HelloWorld script created in exercise 5.2.

Press CONTROL + S to save and compile the Notepad.jss script file. Did you hear the "Compile Complete" message? If not, go back to the script and check it against the script shown in the previous exercise.
After you have successfully compiled your script file, you are ready to test your new script. Press ALT + TAB to move back to Notepad.
Press CONTROL + 1. Did you hear the message spoken by JAWS?
Press JAWSKEY + 1 to turn on Keyboard Help. You should hear JAWS speak "Keyboard help on" when you are using beginner verbosity. Otherwise, you should hear , "On."
Press the keystroke that activates your script, CONTROL + 1. Did JAWS speak the synopsis of your script?
Press the keystroke, CONTROL + 1, twice in succession. Did JAWS speak the description of your script?
Press JAWSKEY + 1 a second time. You will hear JAWS say "Keyboard help off" when you are using beginner verbosity. Otherwise, you should hear , "Off."

Additional Practice: Create a new script called "TestDifferentOutputTypes" that tests at least three different output type constants with the SayFormattedMessage function. Assign each test to a different keystroke and test them in Notepad. Document your observations about the differences in behavior and when each output type would be most appropriate to use in real-world scripts.

Using the InsertFunction dialog.

The objective of this exercise is to create a new script and insert a function in the body of the script using the InsertFunction dialog. If you are still in Notepad, press ALT + TAB to move back to the Script Manager.

Press CONTROL + END to move to the bottom of the file.
Press ENTER twice to create a new blank line. This blank line separates the new script from the previous HelloWorld script.
Press CONTROL + E to activate the New Script dialog. Your cursor should be located in the Script Name edit box.
Type "SayGreeting" without spaces. Capitalize the S in say and the G in Greeting.
Press TAB to move to the Can be Attached to Key check box and press SPACEBAR to check it. This tells JAWS you are creating a script not a function.
Press TAB to move to the synopsis edit box. Type "Speaks a greeting in Notepad".
Press TAB to move to the description edit box. Type "Speaks a greeting in Notepad using the Say function."
Press TAB to move to the category combo box. As the category is not used, you do not need to make a selection.
Press TAB to move to the Assign To edit box. Press CONTROL simultaneously with the 2 on your numbers row, not the num pad. You should hear JAWS speak "CONTROL + 2." Since the Ok button is the default button in this dialog, press ENTER to close the New Script dialog.
Press UP ARROW once to move to the first blank line in the body of your new script.
Press CONTROL + I to activate the InsertFunction dialog box. The cursor should be located in the Function Name edit box.
Type "Say." JAWS moves the highlight in the Function Name list box of this dialog to the location of the Say function and speaks its description.
Press ENTER to tell JAWS this is the function you want to add to your script. You will then be prompted for the first parameter of the function. This parameter is the string of text that is spoken by JAWS each time you press CONTROL + 2.

A parameter is information a function uses to perform its task.
Type "Hello world, this is my second script." including the quotation marks. This is the actual message JAWS speaks each time you press CONTROL + 2.
Press ENTER to add the first parameter. You will then be prompted for the second parameter of the Say function.
Type "OT_MESSAGE" in all capital letters. This is a constant value contained within the HJConst.jsh script header file. This parameter tells JAWS what type of message this is and when to speak it.
Press ENTER to accept the second parameter. Press ENTER again to leave the third parameter empty and close the InsertFunction dialog box. You are returned to the script file and the insertion point is at the end of the line containing the function you just inserted.
Press the LEFT ARROW to move the cursor back into the text of the function and you will find a blank space and a comma in between the OT_MESSAGE and the right parenthesis at the end of the function. This happened because we chose to leave the third parameter of the Say function blank. In order for the script to compile properly, you must DELETE. the blank space and the comma in between the OT_MESSAGE and the right parenthesis.
Press DOWN ARROW once to move to the next blank line. Press DELETE. twice to remove the two remaining blank lines. After following the steps above, your script should look like the following:
```
Script SayGreeting ()
Say ("Hello world, this is my second Script", OT\_MESSAGE)
EndScript
```
Now you are ready to compile the script. Press CONTROL + S to compile the script file. If you don't hear "compile complete", then you may have an error in your script. Go back and review the script. You should make sure your script matches the script shown above. After you have corrected any errors, try compiling the script again.
Once you save and compile your script without any errors, return to Notepad and test your script. Press CONTROL + 2. Did JAWS speak the message?

Additional Practice: Create a new variation of the SayGreeting script that accepts parameters. Use the InsertFunction dialog to add functions that you haven't explored yet, such as InputBox to prompt the user for information, or FormatString to build dynamic messages. Combine multiple functions to create a more complex script that demonstrates your growing understanding of function composition and script logic.

JAWS Scripting Language Manual