Common Script Elements
Doug Lee
Last Revised October, 2022

This document describes some elements of this author's scripts that are common across many projects. Specific user guides for scripts will likely link to this document and/or to various sections within it.

Document revision history:

October 24, 2022
Slightly improved the .ini Directive documentation to include how to handle pre-existing instances of a .ini file key in the target file. Also updated the .chain Directive documentation to improve the explanation of where to put a custom script Use line.
June 15, 2020
Added a warning against uninstalling or re-installing scripts if the scripts use a Command key and the key has been locally changed.
May 31, 2020
Updates to the directives file format and manual installation procedure documentation. The June, 2020 zip of directives files also arrived at this time.
May 30, 2020
Added the rather significant Script Installers and Installation Alternatives section to cover script installers and manual script installation procedures, including how to apply directives files.
April 28, 2020
Minor note added to the "Changing the Command Key" section.
April 22, 2020
Initial publication.

Table of Contents

Accessing the Script User Guide

The way to open a users guide for the active scripts by this author is to type Insert+F1 or JAWSKey+F1 twice in quick succession. This will open the scripts' users guide in the default browser. Though usually the guide will also take focus, this may sometimes not happen based on the application in focus, the default browser, whether the browser has open tabs, or due to other factors. If you hear nothing for several seconds after requesting that the guide be opened, use Alt+Tab to find the browser window that contains it.

Users guides will of course vary in content, but there are sections common to most by this author:

System Requirements
A short description of what is required in order for the scripts to run. This often includes restrictions or expectations on JAWS version, Windows version, application version, application interface (web or desktop app for example), etc. This section may also list exact versions and combinations that were tested during script development. See also Revision History.
Installation Instructions
How to install the scripts on a system. This also applies to installing updates over a previous installation.
Script Commands and Features
A usually detailed list of the commands and features provided by the scripts. This is often the primary documentation on a script set, though more complex script sets will likely have further sections describing features in more depth.
Known Issues
A list of the issues or problems already known by the script and/or application author. This section is good to check if you encounter trouble, and it will sometimes offer workarounds to specific issues.
Revision History
A detailed list of which features arrived in the scripts when; i.e., release notes. Typically, each entry will bear a "revision number," which identifies exactly which script version is installed. Entries may also indicate specific JAWS and/or application versions tested during the corresponding development period.

Checking the Script Revision Number

To facilitate identification of exactly what features are active on a particular computer, this author makes the standard JAWS Insert+q (or JAWSKey+q) command start with a revision number. When seeking technical support or when looking up features in the user guide's Revision History section, it will be helpful to know this revision number.

For the curious: The revision number often, but not always indicates how many times the scripts were edited since their inception. However, it is safe to say that the number will increase as scripts are changed, which means that a higher number is a pretty reliable indicator of newness.

Multi-Key Command Sequences

Many of this author's scripts incorporate commands that consist of sequences of keystrokes, all beginning with a common prefix, or "Command key." Script documentation typically calls these "command key sequences" or just "key sequences" and will refer to a single "key sequence" to distinguish it from a key combination. This approach allows many script commands without the risk of conflicting with application keystrokes.

By default, the Command key for most scripts is the left bracket ([) key; see below for how to change it if necessary. Script user guides may refer to this key as [ or Command; so, for example, [ Tab and Command Tab both refer to typing the prefix key, then separately the Tab key. Some sequences may consist of more than two keys, or "levels"; for example, [ d r would refer to typing [, then d, then finally r.

Exploring Available Script Command Sequences

Script user guides will document the key sequences supported by the specific scripts. In addition to those, and common to all scripts that incorporate this system, the following sequences are available for exploring what is supported:

It is often very instructive, when trying a new set of scripts that uses this system, to type the Command key and then start tabbing through the available commands to find out what commands exist. This is much like exploring the menu system of a new application.

Changing the Command Key

Due to personal preference, or sometimes due to conflicts on non-English keyboards, users may wish or need to change the Command key from its [ default. Nearly any key or combination of keys is permitted, though of course some (like Alt+F4 perhaps) may not be wise. In most cases though, typing the Command key or combination twice in a row will simply pass one instance of the keystroke through to the application. For example, typing [ twice will type one left bracket character into the application. Key combinations like Shift+2 may not do this, however.

If you need to change the command key, type the current command key followed by either JAWSKey+c or Insert+c. An edit box will appear into which you may type your desired command key. The current key will initially appear in the box. How to proceed from here depends on the age of your scripts.

Warning: If you change the Command key and then uninstall the scripts, even as part of an update or re-install, the changed key mappings will not be removed and will need to be removed manually. A way to avoid this problem is to change the Command key back to its default before running the uninstall or re-install. Failure to remove these key assignments after uninstall, or to reset the key back to its default before uninstall, can result in any or all of the following symptoms:

The New Way

For scripts released on or after April 22, 2020, you may simply type the key or key combination you want as a Command key. If you mistype or change your mind, just type the correct key or combination and it will replace what you already typed. Press Enter to exit this hotkey-style mode and land in a regular edit box, where you can manually adjust the keystroke that landed in it. Alternatively, pressing Esc any time will cancel the Command key update and return you to your application. You may also use the JAWS SayLine command to check what is currently in the box.

It will often be important to adjust what is found in this box after pressing Enter to end the key entry mode. As an example, if you type Shift+], the key that actually appears in the box will likely indicate exactly which Shift key you used. If you don't remove the "Left" or "Right," only that specific Shift key will be considered part of your new Command key. (In fact, it is even permitted to use both: LeftShift+RightShift+D is a valid key combination for a Command key.)

Once you have reviewed and/or corrected your new Command keystroke, press Enter to accept it. Press Esc at any time to cancel the Command key update.

A little fine print on this newer system:

The Old Way

Those with scripts released on or after April 22, 2020 should skip this section.

The older method of key entry works much like the new, except that keystrokes must be typed out rather than first being entered automatically by you simply typing your desired key or combination. For this method, it is necessary to type out the key or key combination. This requires knowing exactly what JAWS calls speciffic keys. This may not always be intuitive; for example, the equal sign (=) is called "equals," whereas the left bracket is just itself, [. If the keystroke requires modifiers like Shift or Ctrl, spell those out; do not simply type, for example, A when you mean shift+a. Example keystrokes exactly as they should be typed:

Warning: If you accidentally set the command key to something you cannot type, you will need to edit it in the scripts' .jcf file in the JAWS user folder under the MKCSOptions section.

Script Installers and Installation Alternatives

This author's scripts are packaged in installers generated by the Nullsoft Installation System (NSIS). The script installers are designed deliberately to allow users to install scripts manually where preferred or required by policy, though running the installers is recommended when possible. The installers, also by design, do not require administrative rights to run.

Installer Features

Features of the installers shared among scripts include

Migrating Installed Scripts To a New JAWS Version

In general, the JAWS migration utility should successfully migrate this author's scripts to a new JAWS version along with other scripts and settings. Please contact this author if this proves not to be the case for a particular setof scripts.

Manual Script Installation

For those users who prefer or are required by policy to avoid running executable installers, this section may help guide a manual script installation.

Warning: This author does not support circumvention of corporate or local system policies; these instructions are intended to help those who wish legally to install scripts in locations where installers are either blocked or discouraged but where the scripts themselves are permitted. At this writing (May, 2020), this author finds such conditions fairly common due to corporate blocking of Internet-based executable programs.

Important notes on the following instructions:

To install a set of this author's scripts manually into one JAWS version and language folder:

  1. Using 7Zip or a compatible archive handler, unpack the installer files into a folder of your choosing; or examine them directly within the archive manager for now if you prefer. If it is difficult to open the installer as an archive, try copying or renaming it to end with .zip instead of .exe first.
  2. Within the installer archive, ignore folder names beginning with a dollar sign ($). You may also ignore the executable file whose name begins with "uninst_"; this is the uninstaller. (The uninstaller will not be able to uninstall scripts that are manually installed; it can only remove installations that the installer containing it created.) The rest of the files are what needs to be installed into JAWS.
  3. Look for a file whose name ends with _directives.txt and that starts with the base name of the script set you are installing. A full example file name would be skypeelectron_directives.txt. If no such file is included, check for the same file name in the June, 2020 zip of directives files, which is provided until supported projects are each updated to include their own directives files.
  4. If you do not find such a file, stop! This document does not apply to the scripts you are trying to install, possibly because the scripts are too old.
  5. Look in the directives file for a line beginning with ".jawsminver." This line indicates the oldest JAWS version supported by the scripts, which is also the oldest version presented as an option by the installer when run.
  6. If your target JAWS version is older than the version indicated on this line, stop! Installing the scripts into your older JAWS version is not likely to work properly.
  7. If the directives file includes any lines beginning with ".ini" or especially ".chain," consider the following before proceeding: Stop here if this is a problem or if you need to do this when you have more time.
  8. Copy or unpack the scripts into the appropriate JAWS Settings/enu folder. This folder is most easily found by going to the Start menu, then All Programs, then the appropriate JAWS version, then Explore JAWS, and finally Explore My Settings. Be sure to use "My Settings," not "Shared Settings."
  9. If the scripts come with any .jss file that is not accompanied by a .jsb file of the same base name, compile that .jss file via the JAWS Script Manager. This should not happen often.
  10. If the directives file contains any .ini directives, apply those now as directed by the .ini Directive section of this document.
  11. If the directives file contains a .chain directive, apply it now as directed by the .chain Directive section of this document.
  12. If you had to apply any directives in the previous two steps, restart JAWS now to make the changes take effect.
  13. Test whether the scripts are working by launching and focusing the application being scripted, and typing Insert+q. If the spoken result starts with a script revision number, you are done. If not, make sure your file installations and modifications were correct and that JAWS has been restarted after they were made.

Handling Directives Files

Starting in June, 2020, script installers may include a "directives" file that can be used to guide further manual installation steps that the installer would have performed automatically. This section explains how to use this file. If you reached this section directly by following a URL from such a file, it may help to consult the sections prior to this one that deal with installing scripts.

Directives files are generally named such that the name starts with the base name of the scripts being installed and end with "_directives.txt." A full example file name would be skypeelectron_directives.txt. As implied by the .txt file extension, these are text files; they will likely open automatically in Notepad under Windows.

Directives files may consist of comment lines, "directive" lines, data lines, and/or blank lines. Comment lines begin with a semicolon (;) or number sign (#) and are instructions or explanations to you with no other import. Blank lines are ignored. Data lines depend on the directive above them and will be explained under their respective directive types.

A directive line begins with a dot (.) and a directive type. More information may follow on the same line depending on the directive. Any subsequent line that does not begin with a dot (and is not a comment or blank line) is a data line for that directive. The next line that starts with a dot is a new directive.

To complete installation of a set of scripts that comes with a directive file:

  1. Read the comment lines to look for any special directions for this set of scripts. This should not happen often.
  2. Take each directive line in turn and apply it to the scripts. How to process each directive type will be explained in following subsections, one per directive type. (The order in which directives are applied does not actually matter.)
  3. When done altering JAWS files, restart JAWS to make the changes become apparent to JAWS.
  4. Test whether the scripts are working by launching and focusing the application being scripted, and typing Insert+q. If the spoken result starts with a script revision number, you are done. If not, make sure your file modifications were correct and that JAWS has been restarted after they were made.

A Full Directives File Example

The following example directives file is for a fictitious application called Yoyodyne Propulsion Systems Inventory Manager. The executable for this fictitious application is YPS IM.exe, and the script basename for it is ypsim (no space this time). The directives file includes the following items:

This directives file is more complex than most, in order to demonstrate all possibilities.

Contents of ypsim_directives.txt: 

# Directives file for the Yoyodyne Propulsion Systems Inventory Manager scripts.
# Consult https://www.dlee.org/code_common.htm#inst_directives for information on how to apply this file during a manual script installation.
.jawsminver 2018
.ini ConfigNames.ini
[ConfigNames]
YPS IM=ypsim
[Domains]
im.YoyodynePropulsionSystems.com=ypsim
.ini ypsim.jcf
[WindowClasses]
RichTextWndClass=Edit
MSFlexGridWndClass=ListBox
[MSAAClasses]
ThunderRT6ListBox=1
; This silences the Enter key for fast record entry.
; In practice, this author would not include the following entry because it really amounts to a user preference and not a requirement;
; but this demonstrates why it helps to have an installer manage some settings while letting the user manage others.
[KeyLabels]
return=0|Enter
.chain default ypsim_default 5
.ini default.jkm
[Common Keys]
JAWSKey+Alt+Y=ypsim__readLastAlert
Insert+Alt+Y=ypsim__readLastAlert

The specific directive types will be explained in detail in the following subsections.

The .jawsminver Directive

This directive is advisory. Do not attempt to install the scripts associated with this directive into a JAWS version that is older than the one indicated. Doing so is likely to result in problems. No other action is required for this directive.

The .ini Directive

A .ini directive indicates a file that conforms to the Windows "ini" format that needs to be updated. The name of the file to update will follow this directive on the same line. The data lines below this line will indicate what sections and keys need to be included in the file. Familiarity with the Windows ini format will be necessary. Examples of commonly updated files that conform to the ini format include JAWS configuration (.jcf) files, JAWS graphic icon label (.jgf) files, and the ConfigNames.ini file that JAWS uses to figure out which scripts to load for a particular application or website.

To update an ini-style file from a .ini directive and its data:

  1. For each section name in the directives file, look for that same section in the target ini file. Section names appear in square brackets ([]).
  2. If the section does not appear, copy the section line from the directives file into the target file. It is sufficient to place the new line at the bottom of the target file. Leave a blank line below it. Do not copy the section line if the section already exists in the target file, or JAWS may fail to find the items within one or the other of the section duplicates.
  3. For each key=value line in the directives file below the section line, look for a corresponding line in the same target file section, having the same key to the left of the = sign. If found, replace the line with the one from the directives file. If not found, copy the directives file line below the section line in the target file. The order of lines in a .ini section does not matter.
  4. Make sure the file ends with a blank line if using Notepad or a similar editor. (Technically, this simply ensures that the last line ends with an end-of-line character sequence.)
  5. Save and close the target file.

The .chain Directive

A script chaining directive, .chain, is followed on the same line first by the base name of the script file being chained through (usually "default"), and then by the base name of the script file that needs to be included in that file via a JAWS "use" statement. This document will refer to the first of these as the "anchor base" and the second as the "new member base." There may be a small number, such as 5, after these items on the same line; this will be referred to as the "new member priority number." This directive has no data lines.

The procedures below may look complicated, but they really amount to updating or writing a short new script file in the JAWS user folder and compiling it. The complexity below is simply to spell out a set of steps that should work reliably for people with varying degrees of experience managing files and folders in Windows.

Warning: The below procedures should work if followed correctly, but if not followed correctly, they can destabilize JAWS and result in a very difficult situation to escape. If you use these instructions, you do so at your own risk. This author explicitly disclaims any liability for any problems or losses caused by the correct or incorrect application of these instructions.

Safety Preparations Before Applying the Directive

Before attempting to apply a .chain directive, do the following to make sure it can safely be done on this computer system:

  1. Open the JAWS user folder into which you are installing the scripts. This folder is most easily found by going to the Start menu, then All Programs, then the appropriate JAWS version, then Explore JAWS, and finally Explore My Settings. Be sure to use "My Settings," not "Shared Settings."
  2. Look for all files starting with the anchor base (the first name after ".chain," usually "default"). The extensions of interest here are .jsb, .jsd, and .jss.
  3. If there is a .jsb file for this anchor base but no .jss file, stop! This generally means that a set of scripts is installed on this computer that already chained through this file but without allowing other script sets to do so. It will be necessary to contact the author of those scripts for assistance at this point.
  4. If there is no .jsb and no .jss file, it is safe to proceed; skip the remainder of this list and proceed to the next section. The update procedure may alter a .jsd file for this anchor base if one is present, but this should be harmless. Make a backup of the .jsd file now if this seems warranted.
  5. If there is a .jss file for this anchor base, use the JAWS Script Manager to examine it. Identify which of the following cases applies to it, and act accordingly.
  6. If the .jss file begins with a copyright by Vispero, Freedom Scientific, etc., it is likely a modified or unmodified copy of the file originally located in the JAWS shared folder. It will be necessary to delete this file before proceeding, so it will be important to know if the file has been modified from a JAWS original. If it is unmodified, or if you are ok with any modifications going away, deleting the file will equate to making JAWS default code again apply (which is good anyway); if it is modified, sift out the modifications into another file to be applied later, and compile the new file. Do not simply rename the file expecting to load it with a Use line later; extract what was changed with respect to the original JAWS shared file into a new .jss file, and compile it. If this is not practical to do, stop! Proceeding further would delete modifications to this file. Otherwise, delete the file now, skip the rest of this list, and proceed to the next section.
  7. If the .jss file does not appear to be a copy, modified or not, of a JAWS shared-folder file, it should be one of two things: A script chaining file such as would be created by this procedure, or a custom script file not created by this procedure. Files created by this procedure consist only of comments, use lines, and a default "filler" function that only contains a return statement. If this file meets that description, congratulations - you have a safe script chaining file already! Skip the rest of this list and proceed to the next section.
  8. If the anchor base .jss file is a custom script file that is not a chain manager, you will need to rename it to something that we can later load via a Use statement, then compile it with the new name. If this is not practical to do now, stop! Otherwise, rename the file now and compile it. Note that if you happen to restart JAWS after doing this and before completing the entire .chain directive sequence, any custom code in this file will be temporarily unavailable.
Applying The Directive After the Safety Preparations

Here are the steps to applying a .chain directive, after making sure it is safe to apply. Windows Explorer at this time should remain open to the JAWS user folder from the above steps.

  1. If the anchor base .jss file exists and is a chain manager:
  2. From here, we assume there are neither a .jss nor a .jsb file with the anchor base name. If the JAWS Script Manager is open from an earlier step, close it now.
  3. Open the JAWS shared folder by going to the Start menu, then All Programs, then your JAWS version, then Explore JAWS, and then Explore Shared Settings. Leave this folder open as you go to the next step. We will refer to this folder window as the Shared folder from now on.
  4. Type JAWSKey+0 to open the JAWS Script Manager, then type Ctrl+N and then Enter to open a blank screen within the Script Manager.
  5. Enter the following code, by typing or pasting from this document as you prefer, and replacing "AnchorBase" with the anchor base and "NewMemberBase" with the new member base name for the scripts you are installing. If there is a new member priority number on your .chain directive line, put it in place of the "5" below; otherwise, leave the "5" in place.
    Use "AnchorBase.jsb"
    Use "NewMemberBase.jsb" ; 5

    void function _filler()
    return
    endFunction
    The dummy function is necessary to avoid possible problems compiling.
  6. If you created a script file during the safety preparations, because it was either a modified JAWS shared file or a custom script file and not a chain manager, add a Use line for that file now. The new line should usually go just below the first Use line in the file and absolutely must go somewhere below that line and above the dummy function.
  7. Verify that all of the code you entered looks exactly as intended. If the anchor base is "default" as is commonly the case, failure to enter this code correctly can cause the next step to disable all JAWS keystrokes. If that happens, it may be necessary to find a way to delete a file from this User folder before JAWS will work properly again. See the next section for tips on handling this hopefully unlikely scenario.
  8. Save the new anchor .jss file and recompile it. Do this by typing Ctrl+S and, when prompted, entering the anchor base as the new file name (usually "default" without the quotes) and pressing Enter. You should hear JAWS say "Compile complete." If you get an error message instead, press the OK button, then go back and check the code and recompile as necessary.
  9. Close the JAWS Script Manager, the Shared folder window if open, and the User folder window, each with Alt+F4.
Accident Recovery Procedure When Modifying default.jss

In the event of a serious problem caused, for example, by mistyped code in default.jss, the following procedure may be of use. This procedure was initially worked out, tested, and reported to me by Roy Nickelson years ago during deployment of the SkypeWatch portion of the scripts for Skype Classic. Thanks much to Roy for this. This procedure has since been updated but may well no longer be necessary even in the worst of cases. Do not use this procedure if your anchor base for the scripts you are installing is not "default."

  1. Launch Microsoft Narrator to make sure there will be speech during this procedure. The command for this varies among Windows versions: If these fail for some reason, type Windows+R, then the word Narrator, then Enter.
  2. Type Windows+R, then the word JAWS20 or the appropriate command for your JAWS version, then Enter. Because JAWS is already running, this will bring up the Context menu for JAWS rather than running it again.
  3. Type Alt+Shift+F4. This will bring up the "Exit JAWS?" dialog. The "shift" part of that command gets around any possible script attached to a plain Alt+F4.
  4. Press Enter to close JAWS. The keyboard will now become fully usable.
  5. Launch the user settings folder by going to the Start menu, then All Programs, then your JAWS version, then Explore JAWS, and finally Explore My Settings. Be sure to use Explore My Settings, not Explore Shared Settings.
  6. From the folder just opened, delete default.jsb. This will restore JAWS' default behavior.
  7. Close Narrator by Alt+Tabbing to it and typing Alt+F4.
  8. Restart JAWS in your normal fashion.
Final Notes On Script Chaining

This author's installers actually forbid more than one script set in a chain to share either priority number 1 or priority number 9. Those two priority numbers are reserved for scripts that absolutely must come first or last in the JAWS script and function call search sequence.

Technically, though priority 1 puts a script just under the initial Use line for the shared anchor base, this has the effect of putting the associated scripts last in the JAWS search chain, before the shared JAWS code. Priority 9, which puts a script file at the end of the Use list, puts those scripts at the top of the JAWS search chain.

This author's code for managing script chains is freely available for use and inspection as a VBScript file called JAWSUtil.vbs. This utility includes other features but has been the reference implementation of the script chaining system since 2009.