Introduction to JAWS Scripting

Introduction

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 might not be aware that JAWS 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.

This manual will:

• Introduce JAWS script writing.

• Explain why scripts are sometimes necessary.

• Explain the structure of scripts.

• Demonstrate how the Script Manager functions.

• Teach you how to script an application for the first time.

This manual is intended for beginners to JAWS scripting or those who want a basic overview of its overall utility for making applications appear more accessible.

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 program that it needs. A script can make a poorly 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 the standard keyboard commands. These are only two examples of how scripting can be used to make an application more accessible and usable.

::: {#overview-of-jaws-scripting-language}

Overview of JAWS scripting language

:::

The JAWS scripting language, just like any other programming language, has its own conventions, syntax and rules that a programmer has to follow. It is in a way comparable to "rules of the road" that each car driver and pedestrians have to follow when crossing or driving through the streets.

The programs, written in JAWS scripting language, are called scripts and are stored in script files with an extension .jss. However, before these programs can be used, they have to be compiled into a format that the computer can understand. The format is called JAWS Script Binary and the files will have an extension of .jsb. Please remember that it is the binary (.jsb) file that JAWS will use to execute (perform) instructions that you will have written in your script source (.jss) file.

For the purpose of being clear on terminology, we will call the file that contains scripts, functions and statements a script file. Very often though you will hear people calling the script file a script. Be sure you understand the difference or there can be misunderstandings when describing your process to others. We will thoroughly explain the difference between the terms "Script" and "Function" a little later.

JAWS script files are associated with an application for which the script is written. For example, if the application name is "Microsoft Word" and the application's main executable file is WinWord.exe, the name of the JAWS script file for this application will by default be Word.jss¹

A JAWS script file will contain one or more sections and instructions to tell JAWS what to do in certain situations, for example what to speak when something happens on the screen or when a user presses a shortcut key. The instructions are called statements and the sections are called scripts or functions.

::: {#file-types-and-their-meanings}

File Types and Their Meanings

File Types and Their Meanings :::

::: {#overview}

Overview

:::

JAWS stores all the information, pertaining to the scripts and functions, into multiple files with different extensions. For example, you know that the script source goes into the file with an extension .jss and the compiled binary script file goes into the file with an extension of .jsb. You will be interested to know that the keyboard keystrokes, associated with our scripts, are saved into the file with an extension of .jkm.

Have you ever wondered how JAWS remembers your settings that you save with Keyboard Manager or Configuration Manager? If you run Graphic Autolabeler -- a feature that allows JAWS to automatically label graphics if the tooltips are present for them (JAWSKEY + CONTROL + G), JAWS remembers those labels next time you open the application. In the same way, if you change an option in a Configuration Manager, for example punctuation speaking level, and save the file, your settings will also be remembered. JAWS has this wonderful memory of your actions because the information you modify is saved into the files with different extensions. All of them, with the exception of the JSB files, are regular text files which you can open in any text editor. The JSB files are binary files and cannot be read in the same way that text files can.

Not all 15 file types have to be present for a given script file, however, most of the time you will see the most important ones, such as .jss, .jsb, .jsd, .jsh, .jsm, and .jcf. Of course, you do not have to memorize any of these extensions, but it would be useful for you, as a "Scripter", to know what they stand for.

::: {#practical-usage}

Practical Usage

:::

As stated previously, most of the JAWS script files can be opened and edited in remarkpad (or any other text editor), except for the ones with an extension of .jsb. However, this is only recommended for advanced users because they will know the format that these files have to follow in order to be understood by JAWS.

It is, therefore, suggested that you use dedicated programs to open these files, i.e., use Configuration Manager to open .jcf files or Keyboard Manager to open .jkm files. A convenient place to access these tools is from the "Run JAWS Manager" dialog box accessed by pressing JAWSKEY + F2. This will display a list of available tools, like Script Manager or Configuration Manager.

::: {#configuration-manager}

Configuration Manager

:::

Through the Configuration Manager tool you can modify the behavior of JAWS. For example, you can change what is spoken, when and how the punctuation is handled and how the text is processed by JAWS. The Configuration Manager can also be accessed via "Run JAWS Manager" dialog box or by pressing JAWSKEY + 6 (on the number row).

Once the Configuration Manager opens, you will have to use the menus in order to review/modify a particular section in the configuration file. Remember to save your changes with CONTROL + S and close the "Configuration Manager" window when you have finished working with it.

::: {#dictionary-manager}

Dictionary Manager

:::

Another useful JAWS utility is JAWS Dictionary Manager. It can either be accessed through the "Run JAWS Manager" dialog box or by pressing an JAWSKEY + D shortcut key.

The concept of the Dictionary Manager is to enable users to change the way JAWS pronounces certain words and phrases. Let's say you don't like the way in which JAWS speaks your name. You can easily change that by adding a new word to the Dictionary Manager. With JAWS 5.0² or later, you can even replace certain words and phrases with sounds. So for example, rather than saying United Kingdom, JAWS can play an anthem of that country. For more information on this interesting and exciting feature, please check the "Speech and Sounds Manager" in the JAWS Help topics.

Once you open the Dictionary Manager, you will be presented with a dialog window containing the list of already-changed words, buttons to add/remove them and search for an existing word. The interface should be fairly straightforward from there on.

::: {#other-jaws-tools}

Other JAWS Tools

:::

Apart from the tools mentioned, JAWS has other useful utilities, such as Graphics Labeler. With a help of this application you can have JAWS attach a text description to a graphic or an icon. You can do this either manually by placing your cursor on a graphic, then pressing JAWSKEY + G and typing in a text label, or automatically by letting JAWS scan the current window and attempt to attach the label by using tooltips (for information on Tooltips search JAWS Help topics or Windows Online Help). You can activate Graphics Autolabeler by pressing CONTROL + JAWSKEY + G.

The Keyboard Manager will be discussed in the next chapter. However for more information about JAWS utilities, please refer to JAWS Help, topic "Using JAWS", subtopic "Overview of JAWS Utilities".

JAWS Hierarchy

One of the most powerful features of JAWS is that settings can be applied globally or on an application specific basis. Application specific settings are saved using the application name with the appropriate configuration file extension. Global settings are saved in the default versions of the various configuration files.

Application specific settings can override global settings; so if you change a setting in the specific default configuration file and some of your programs do not reflect this change, make the change in the configuration files for those programs as well.

graph LR
    subgraph USER["🟠 User Settings"]
        US["User Settings"]
        USC["User Scripts<br/>(jsb, jsm, jsh)"]
        UAP1["Word<br/>Word.jsb"]
        UAP2["Vivaldi Browser<br/>Vivaldi.jsb"]
        UAP3["Firefox Browser<br/>Firefox.jsb"]
        UAP4["Teams<br/>Teams.jsb"]
        US --> USC
        USC --> UAP1
        USC --> UAP2
        USC --> UAP3
        USC --> UAP4
    end
    
    subgraph DEFAULT["🔵 Default/Shared Scripts"]
        DG["Default/Shared<br/>Global Settings"]
        DSF["Default Script Files<br/>.jsb, .jss, .jsm<br/>.jsh, .jkm, .jsd"]
        DSHS["Shared/Default Settings<br/>.chr, .json, .xml<br/>.sbl, .vpf, .ini<br/>.jgf, .smf, .jdf<br/>.qs, .qsm"]
        DG --> DSF
        DG --> DSHS
    end
    
    subgraph APPS["🟢 Applications"]
        APP["Applications"]
        AW["Word<br/>Word.jsb"]
        AE["Edge Browser<br/>Edge.jsb"]
        AF["Firefox Browser<br/>Firefox.jsb"]
        AC["Chrome Browser<br/>Chrome.jsb"]
        AX["Excel<br/>Excel.jsb"]
        AZ["Zoom<br/>Zoom.jsb"]
        APP --> AW
        APP --> AE
        APP --> AF
        APP --> AC
        APP --> AX
        APP --> AZ
    end
    
    %% Default Script Files to Applications (blue arrows)
    DSF -->|scripts| AW
    DSF -->|scripts| AE
    DSF -->|scripts| AF
    DSF -->|scripts| AC
    DSF -->|scripts| AX
    DSF -->|scripts| AZ
    
    %% Shared Settings to Applications (teal arrows)
    DSHS -->|settings| AW
    DSHS -->|settings| AE
    DSHS -->|settings| AF
    DSHS -->|settings| AC
    DSHS -->|settings| AX
    DSHS -->|settings| AZ
    
    %% User overrides (red arrows)
    UAP1 -->|overrides| DSF
    UAP2 -->|overrides| DSF
    UAP3 -->|overrides| DSF
    UAP4 -->|overrides| DSF
    US -->|overrides| DSHS
    
    %% Styling
    classDef userStyle fill:#FFE4B5,stroke:#FF8C00,stroke-width:2px
    classDef defaultStyle fill:#ADD8E6,stroke:#4169E1,stroke-width:2px
    classDef appStyle fill:#90EE90,stroke:#228B22,stroke-width:2px
    
    class USER userStyle
    class DEFAULT defaultStyle
    class APPS appStyle

::: {#script-manager-files}

Script Manager Files

Script Manager Files :::

Unlike the other managers used by JAWS, the Script Manager has a number of files associated with it. All files follow the same naming convention as the files used by the other JAWS managers.