Introduction

When used with most popular applications, JAWS screen reading software provides you with screen information for the application you are using. The information that tells JAWS how to behave is contained within a set of "default files." These default files, created by Freedom Scientific, are provided with JAWS. Unfortunately, not all applications are the same. Therefore, information telling JAWS how to behave in these applications is contained in a set of "application-specific files."

JAWS Version History

The trajectory of JAWS development from its inception in 1989 through 2026 demonstrates a steadfast commitment to expanding accessibility across diverse computing environments and application types. Early JAWS releases (1995-2003) focused on foundational screen reading capabilities and basic scripting support, establishing the technical infrastructure for accessibility customization. However, the real transformation in accessibility occurred post-1996 with the introduction of scripting language enhancements. When scripting was first introduced in 1996, it empowered individual users and developers to bridge accessibility gaps that Freedom Scientific could not address alone. As JAWS evolved through subsequent versions, scripting capabilities grew exponentially: from basic event-driven automation (2003), to comprehensive UI Automation integration (2011+), to domain-specific web scripting (2015+), and finally to AI-enhanced page analysis and dynamic content navigation (2025-2026). These incremental scripting improvements translated directly into expanded accessibility functionality--enabling users to interact with previously inaccessible modern web applications, cloud-based software, enterprise systems, and specialized domain-specific tools without waiting for native accessibility implementation. By decoupling accessibility customization from JAWS core development cycles, the scripting language created a sustainable model where the community itself could drive accessibility innovation, significantly accelerating the pace at which blind and low-vision users gained access to mainstream technology.

Through the many options available in the JAWS application, changes and adjustments can be easily made to all of the commonly used features, such as Verbosity and Screen Echo. But despite this ability, you may find special situations that require more advanced or specific instructions so that JAWS can properly navigate and provide the correct screen information in the application.

JAWS Scripting Language Versions

The JAWS scripting language has undergone significant evolution since its inception in 1996, each update bringing substantial improvements to accessibility capabilities. Early versions introduced foundational scripting concepts and event-driven automation, allowing users to customize JAWS behavior for inaccessible applications. The introduction of the UIA Script API in JAWS 14 marked a pivotal advancement, enabling direct integration with Microsoft UI Automation--a modern accessibility framework that opened doors to controlling contemporary Windows applications that relied on UIA rather than legacy accessibility APIs. Subsequent versions expanded these capabilities with enhanced event handling, domain-specific scripting functions for web environments, and refined UIA properties, progressively empowering developers to build more sophisticated accessibility solutions. These advancements have democratized accessibility customization, enabling blind and low-vision users to work effectively in previously inaccessible software environments, while simultaneously reducing the burden on application developers to implement native accessibility features by providing an alternative customization pathway through scripting.

A script file contains a variety of scripts and functions that work together to extend JAWS functionality and customize its behavior for specific applications and use cases. You can think of scripts and functions as small computer programs--self-contained units of logic that execute in response to specific events or user actions. Each script or function contains commands that tell JAWS how to navigate through an application's interface, what information to speak or braille, and how to interpret and present complex data structures to users. The power of JAWS scripting lies in its ability to create customized accessibility solutions tailored to individual user needs and organizational requirements.

As you progress through this manual, you will learn to modify existing script files to alter JAWS behavior in specific applications, and you will also learn to write entirely new commands and functions to make previously inaccessible applications functional for blind and low-vision users. Through systematic practice with keyboard managers, script managers, and event handlers, you will discover how to create scripts that not only navigate applications more efficiently but also automate repetitive daily tasks, customize keyboard shortcuts, and optimize speech output for domain-specific workflows. The scripting language offers virtually unlimited possibilities--accessibility solutions bounded only by your imagination, creativity, and understanding of both JAWS scripting concepts and the target application's structure.

JAWS is not the only product developed by Freedom Scientific that takes advantage of the powerful scripting language. Both the MAGic screen magnification application, ZoomText, and Fusion take advantage of the power and flexibility offered by the scripting language. This shared scripting foundation means that skills you develop writing JAWS scripts will transfer directly to creating magnification and speech customizations in these related products. With the familiarity gained from writing JAWS scripts, you will be able to easily apply your knowledge and techniques when generating scripts that control magnification and speech functionality found in MAGic, ZoomText, and Fusion--making you a versatile accessibility technology developer capable of serving multiple user needs across Freedom Scientific's entire product ecosystem.

MSAA, UIA, and Scripting

JAWS scripting primarily interacts with applications through two main accessibility frameworks: Microsoft Active Accessibility (MSAA) and Microsoft UI Automation (UIA). MSAA, introduced in the mid-1990s, was the original accessibility API for Windows applications. It provides a way for assistive technologies like JAWS to access and interact with user interface elements. However, MSAA has limitations, particularly when dealing with modern applications that utilize complex UI components and dynamic content.

UIA, introduced in the mid-2000s, is the successor to MSAA and provides a more robust and flexible framework for accessing and interacting with user interface elements. UIA supports a wider range of control types, properties, and events, making it better suited for modern applications with rich, dynamic interfaces. JAWS scripting leverages both MSAA and UIA to ensure comprehensive accessibility support across a wide variety of applications, allowing scripts to interact with both legacy and contemporary software environments.

I-Accessible2 is an extension of MSAA developed to address some of its limitations, particularly in providing richer semantic information about UI elements. While JAWS scripting primarily utilizes MSAA and UIA, understanding IAccessible2 is important for script developers working with applications that implement this extended accessibility framework, as it can provide additional context and information that can be leveraged in scripts.

Accessibility API Milestones and JAWS Scripting Integration

The evolution of Windows accessibility APIs has directly shaped the capabilities available to JAWS script developers. The following timeline documents key advances in MSAA, UI Automation (UIA), and IAccessible2 that script developers leverage to access and control both internet applications and the Windows desktop environment:

Do I Need a Programming Background to Write JAWS Scripts?

For those of you who ask, "Do I need a programming background to write scripts," the answer is that while a programming background is helpful, it is not necessary. In fact, many script developers working for Freedom Scientific are self-taught, and countless accessibility professionals and blind users have become proficient JAWS scripters through self-directed learning and community collaboration. The JAWS scripting language was deliberately designed to be accessible and approachable, with intuitive syntax and logical structure that makes it learnable by individuals with varying technical backgrounds. What matters most is not your prior programming experience, but rather your motivation to expand accessibility, your willingness to learn through experimentation and practice, and your commitment to understanding how JAWS interacts with applications. It is for this reason alone that we have compiled this comprehensive step-by-step manual in hopes that you will gain a solid foundation in scripting fundamentals, develop practical competency in creating and debugging scripts, and ultimately take the first steps toward becoming a successful JAWS script developer capable of solving real-world accessibility challenges.

Further Reading and Resources

More Resources for JAWS Version History

{{#cite jaws1}}

{{#cite jaws2}}

{{#cite jaws6}}

{{#cite jaws7}}

{{#cite jaws8}}

{{#cite jaws9}}

{{#cite jaws10}}

{{#cite jaws11}}

{{#cite jaws12}}

{{#cite jaws13}}

{{#cite jaws14}}

{{#cite jaws15}}

{{#cite jaws16}}

{{#cite jaws17}}

{{#cite jaws18}}

{{#cite jaws2019}}

{{#cite jaws2020}}

{{#cite jaws2021}}

{{#cite jaws2022}}

{{#cite jaws2023}}

{{#cite jaws2024}}

{{#cite jaws2025}}

{{#cite jaws2026}}

More Resources for JAWS Scripting Language History

{{#cite vispero1996}}

{{#cite afb2003}}

{{#cite fsmanual2011}}

{{#cite jaws14uia}}

{{#cite jaws15uia}}

{{#cite jaws17domain}}

{{#cite jaws18uia}}

{{#cite communityresources}}

MSAA, UIA, and Scripting History

{{#cite microsoft:MSAA-spec}}

{{#cite freedomscientific:basicsscripting}}

{{#cite linuxfoundation:IAccessible2-spec}}

{{#cite microsoft:UIA-spec}}

{{#cite w3c:WAI-ARIA}}

{{#cite jaws14uia}}

{{#cite jaws15uia}}

{{#cite jaws17domain}}

{{#cite jaws18uia}}

Definitions and Conventions

Definition of Terms

We will be using a variety of new terms in this manual to describe scripts and functions along with their uses. Terms are listed below along with their meaning. You will find more detailed information about these terms as they are introduced in this manual.

Built-in Function Built-in functions are functions created by the developers at Freedom Scientific. They are used as building blocks for your scripts and functions. Although built-in functions can be used anywhere, they cannot be modified.

Call The term "call" is used whenever a function is performed from within a script or another function.

Compile The term "compile" refers to the action of converting the scripts contained within your script file into a language that can be understood by your computer.

Constant A "constant" is a name you give to a hard-to-remember numeric value or sequence of characters. Constants are not changed during the execution of your script or function and are typically defined in a JAWS script header file. You use constants in place of hard-to-remember values in your scripts and functions.

Event Function Event functions have been created by developers at Freedom Scientific and are triggered by various Windows events. Examples of events that trigger event functions are when the system focus changes or when new text is displayed on the screen. Event functions can be modified or customized for your own use but you cannot create new event functions. You can find all the event functions in the Default.jss script file.

Function A "function" is also a series of statements that performs a given task. Functions are not activated by a keystroke. Functions are called by scripts or other functions.

Key Words "Key words" are words that are reserved for use by the scripting language. Some of the key words used in the scripting language are Script, EndScript, If, EndIf, While, and EndWhile.

Parameter A "parameter" is a piece of information that is passed to a function. The function uses the parameter to process its task.

Return A "return" is a piece of information a function sends back to a script or function from which it is called.

Script A "script" is a series of statements that performs a given task. The script is normally activated by a keystroke.

Script File A "script file" is a collection of scripts, functions, and variable declarations with the file extension of .jss for JAWS script source.

Statement A "statement" is a series of words used within your script that performs an action or group of actions. For example, the following block of code is considered to be a statement:

If A > B Then

User-defined Function User-defined functions are functions created by individual script writers. User-defined functions can be modified and you can create as many as you need. You will find many examples of user-defined functions in the default JAWS script files.

Variable A "variable" is an entity that holds a value. Unlike a constant, the value of a variable can be modified by your script or function during its execution.

Window A predefined rectangular area on the screen that can be identified by unique characteristics. Windows usually contain text, graphics, or various types of controls used by an application.

Scripting Language Key Words

Listed below are the key words used in the JAWS scripting language. These key words are reserved for use by the scripting language and cannot be used as variable names, function names or script names.

Const This key word begins a declaration section of constant values. All constant declarations follow on subsequent lines. The const key word must appear outside of any individual script or function. You can normally find constant definitions at the top of a script file or within a JAWS script header file.

EndFunction This key word terminates the definition of an individual user-defined function. Each user-defined function must be terminated with EndFunction. The Script Manager automatically places this key word into your script when you use the New Script dialog to create a user-defined function.

ElIf This key word offers a second way of creating a branch in an If statement structure. The ElIf key word is followed by a condition that JAWS evaluates. When the condition is found to be true, any statements following the ElIf are performed by JAWS.

Else This key word is an optional part of an If-Then-EndIf statement structure. The Else key word provides for a second branch in an If statement structure. When the preceding If statement is false, then any statements following this key word are performed by JAWS.

EndFor This key word terminates the For loop statement structure. Each For loop must be terminated with this key word. All statements placed between the For key word and this key word are performed by JAWS while the condition being evaluated in the For statement structure is true.

EndIf This key word marks the end of an If-Then-Else-EndIf statement structure. The EndIf key word is always required to terminate any If statement structure.

EndScript This key word terminates the definition of an individual script. JAWS automatically places this key word into your script file when you use the New Script dialog from within the Script Manager to create a script. Each script must be terminated by this key word.

EndWhile This key word terminates the While loop statement structure. Each While loop must be terminated with this key word. All statements placed between the While key word and this key word are performed by JAWS while the condition being evaluated in the While statement structure is true.

For The For key word begins the For loop statement structure. The For key word must be followed by a statement that dictates how many times the loop should execute. While the condition in the For statement structure is found to be true, the loop continues to be processed. Once the condition becomes false, the loop terminates.

Function This key word designates the beginning of a user-defined function. The key word is preceded by the return type of the function. The name of the user-defined function follows this key word along with any parameters the function requires enclosed in parentheses.

Globals This key word begins a declaration section of global variables. All global variable declarations follow on subsequent lines. The Globals key word must appear outside of any individual script or function. You can normally find global variable declarations at the top of a script file or within a JAWS script header file.

Handle This key word begins the definition of a handle variable type. The name of the variable follows this key word as in handle hMyHandle.

If This key word marks the beginning of an If-Then-Else-EndIf structure. A fully formulated statement includes: If, Then, Else, and EndIf. If statements evaluate a condition, that is part of the statement structure. When the condition being evaluated is true, then JAWS performs any statements following the If statement.

Int This key word begins the definition of an integer variable type. The name of the variable follows this key word as in int iMyInteger.

Not This key word reverses the question asked by an If statement structure. The key word is placed between the If key word and the condition being evaluated. This is also represented by an exclamation point (!)¹ in the script.

Object This key word begins the definition of an object variable. The name of the variable follows the key word as in object oMyObject.

Return This key word terminates execution of the function in which it appears. When you use this key word to return a value from a function, the information to be returned must follow the return key word. Control, along with any value, is then returned to the calling script or function. Since a script cannot return values, using the return key word within in a script terminates the script at the point the key word is used.

Script This key word designates the beginning of an individual script. This key word precedes the actual name of the script. Each time you use the New Script dialog in Script Manager to create a script, this key word, along with the script name, is placed in the script file automatically.

Then This key word follows the condition being evaluated in either an If statement or and ElIf statement.

String This key word begins the definition of a string variable. The name of the variable follows the key word as in string sMyString.

Var This key word begins a declaration section of local variables. All local variable declarations follow on subsequent lines. The Var key word must appear within an individual script or function. The first line of a script or function usually contains the Var key word as local variables must be declared before they can be used.

While The While key word begins the While loop statement structure. The While key word must be followed by a conditional statement that is evaluated each time the loop is repeated. While the condition in the While statement structure is found to be true, the loop continues to be processed. Once the condition becomes false, the loop terminates.

Keywords and Non-Required Keywords

The Freedom Scientific Scripting language supports the use of many keywords. But not all are required. Below is a listing of required and non-required keywords you may use in your scripts and functions.

Required Keywords

The below list of required keywords are reserved for use by the Scripting language and cannot be used as variable names, function names, or script names. The list is broken out into areas of usage in level 3 headings and the keywords themselves in level 4 headings within the level 3 headings. Links direct you to relevant summary pages or overview pages for a more in-depth discussion of complex concepts.

• Keywords for Functions and Scripts

• Keywords for Control Flow

• Keywords for Variables and Constants

• Keywords for Compiler Directives

Keywords for Functions and Scripts

The keywords in this section are for function and script code blocks. For more details on how to utilize Return statements, parameters, and function types, see Calling Scripts and Functions.

Function and EndFunction Begins and terminates the definition of an individual function, whether it is a built-in, default, or user-defined function. Each function must begin and terminate with the keywords, Function and EndFunction

EndFunction When you use the Script Manager's "New Script" dialog to create a user-defined function, the Script Manager automatically places the keywords, Function and EndFunction into your file, separated by several blank lines for you to fill with your source code. But if you check the control in the dialog that refers to assigning a keystroke, the Script Manager automatically changes the keywords placed into your file to Script and EndScript.

You may need to precede the Function keyword by the return type of the function. The name of the function is followed by a parameter list, whether those parameters are required or optional, and parameters that must be passed to the function by reference. The parameter list is enclosed in parentheses. For example a function might be called something like:

Void Function SpeakNames(String sMyName)

Script and EndScript Begins and terminates the definition of an individual script, whether it is a default script or a user-defined script. Each script must begin and terminate with the keywords, Script and EndScript.

When you use the Script Manager's "New Script" dialog to create a user-defined script, the Script Manager automatically places the keywords, Script and EndScript, along with several blank lines into your file for you to fill in your source code. But if you uncheck the control in the dialog that refers to assigning a keystroke, the Script Manager automatically changes the keywords placed into your file to Function and EndFunction.

The keyword, "Script", must be followed by the name of the script and end with opening and closing parentheses. If using the Script manager "New Script" dialog, the Script manager automatically does this for you. Scripts can take parameters in a very specific format and manner, although most of the time they do not. For example, the following statement is valid:

Script MyTestScript ()

But the following statement is in an invalid format for declaring a script or a function with parameters:

Script MyTestScript ("hello")

Return Terminates execution of the script or function in which it appears. When used to return a particular value from within a function, add the information to be returned immediately after the Return keyword in the format the calling script or function expects. Doing so shifts control, along with any value, to the calling script or function.

Since a script cannot return values, using the Return keyword within a script terminates the script at the point the keyword is used.

For more details on how to utilize Return statements, see Return Statements.

Optional Used to declare optional function parameters in a parameter list. All parameters you declare after the keyword, Optional, are assumed to be Optional parameters. For example, the following statement shows that the first parameter of the function is required when calling the function but the second is not:

Function SpeakNames (String sMyName, Optional Int iMyAccountNumber)

ByRef Used to declare that a parameter is to be passed by reference in a function. The following example shows that the parameter is to be passed by reference when the function is called rather than a copy being passed to the function when the function is called:

Function SpeakNames (String ByRef sMyName)

It is possible to list parameters such that some are passed by reference and some are not, regardless of whether the parameters are required or optional. The following example shows that a copy of the string is passed to the function, but the account number is passed by reference when the function is called:

Function SpeakNames (String sMyName, Int ByRef iAccountNumber) 

Keywords for Control Flow

For more details on working with conditional statement structures and looping functions, see the following:

If, ElIf, Else, and EndIf Used to create one form of a conditional control-flow code statement structure. The keywords, If and EndIf, are required to begin and terminate the statement structure. But unless more than one condition is being tested, ElIf, and Else are not necessary for an If-EndIf statement structure to be processed. The keyword, Then, is optional. (See the section on Non-Required Keywords below).

The ElIf keyword is an optional part of an If-EndIf statement structure. It allows you to create a second conditional branch in an If-EndIf statement structure. As with the If condition in the first branch, when the ElIf condition evaluates to true, the screen reader performs any statements following it.

The Else keyword is an optional part of an If-EndIf statement structure. It allows you to create another conditional branch that is processed only when any preceding conditions in theIf-EndIf statement structure have evaluated to false.

A completely formulated If-EndIf statement structure looks like the following sample:

If (My condition1) Then
    ; process Statements
ElIf (My next condition) Then
    ; process statements
    ; further ElIf conditions If needed...
    ; process statements For each ElIf condition
Else
    ; process statement when all above conditions are False.
EndIf ; formally ends the If-Then statements

For, To, Descending, EndFor The keyword, For, begins the For loop statement structure, and the keyword, EndFor, terminates the block. The keyword, To, is required. But the keyword, Descending, is required only to iterate in descending order.

Following the keyword, For, in the For loop statement block, you must have a statement that dictates how many times the loop should execute. As long as the condition in the For part of the statement block evaluates to TRUE, the loop continues processing any statements placed within the loop. When the condition becomes FALSE, the loop terminates. But the loop statement block must terminate with the keyword, EndFor, in order to compile properly.

ForEach, In, EndForEach The keyword, ForEach, begins the ForEach loop statement structure, and the keyword, EndForEach terminates the statement block. The keyword, In, specifies which structure to process.

Following the keyword, ForEach, you must have a statement that dictates the structure whose items are to be processed. Any statements placed within the loop are processed for every item in the structure named in the ForEach part of the statement. The loop statement structure must terminate with the EndForEach keyword in order to compile properly.

While-EndWhile Begins and terminates the While loop statement structure. A While loop must begin and terminate with the keywords, While and EndWhile. The While keyword begins the While loop statement structure. It must be followed by a conditional statement that is evaluated each time the loop is repeated. As long as the condition in the While statement structure evaluates to true, the loop continues processing any statements placed within the loop. When the condition becomes false, the loop terminates. But the loop statement structure must terminate with the EndWhile keyword in order to compile properly.

Keywords for Variables and Constants

For more details on working with variables and constants, see the following:

• Variables and Constants

• Constants.

• Non-aggregate Variables.

• Collections

• Array

Const Begins a declaration section of constant values. All constant declarations follow on subsequent lines, each ending with a comma except for the last one.

The Const keyword and its declarations must appear outside of any individual script or function. Constant declarations are typically located at the top of a script source file or within a screen reader script header file.

Globals Begins a declaration section of global variables. All global variable declarations follow on subsequent lines, each ending with a comma except for the last one.

The Globals keyword must appear outside of any individual script or function. Global variable declarations are typically located at the top of a script source file or within a screen reader script header file.

Var Begins a declaration section of local variables. All local variable declarations follow on subsequent lines, each ending with a comma except for the last one.

The Var keyword must appear within an individual script or function where local variables are declared. The first line of a script or function usually contains the Var keyword, followed by at least one local variable declaration since local variables must be declared before they can be used.

Handle Begins the definition of a handle variable type. The name of the variable follows: for example, Handle hwnd.

Int Begins the definition of an integer variable type. The name of the variable follows: for example, Int iMyAccountNumber.

Object Begins the definition of an object variable type. The name of the variable follows: for example, Object oMyObject.

String Begins the definition of a string variable type. The name of the variable follows: for example, String sMyName.

Variant Begins the definition of a variant variable type. The name of the variable follows: for example, Variant vMyVariant.

Var
    Handle hHandleVariable
    Int iIntVariable
    Object oObjectVariable
    String sStringVariable
    Variant vVariantvariable
Const
    True = 1
    False = 0
    On = 1
    Off = 0
Globals
    IntArray giaIdentificationsList,
    Int giChromeVersion,
    Int giChromeMinorVersion,
    Int giChromeUpdateVersion,
    String gsAppName,

Keywords for Aggregate Variable Types

The following keywords apply specifically to aggregate variable types. They include:

• Collection

• New

• IntArray

• StringArray

• HandleArray

• ObjectArray

• VariantArray

Keywords for Compiler Directives

The following are keywords for compiler directives. For more details on their usage, see Compiler Directives.

• Include

• Use

• Import

• #Pragma StringComparison

• Prototype

• ScriptFile

• ScriptFileVersion

Non-Required Keywords

The below list contains a few keywords that are no longer required but often make readability easier.

Then Follows the condition being evaluated in either an If statement or and ElIf statement. For example the following two statements are evaluated in the same manner:

If (MyCondition) Then
; is equivalent To
If (MyCondition)

Not Reverses the condition of a statement that evaluates conditions in an If-EndIf statement structure. The keyword is placed between the keyword that begins an evaluation statement and the condition being evaluated. The Not keyword is often replaced by the exclamation (!) operator², which is processed in the same manner when compiled. for example, the following two statements are evaluated in the same manner:

If Not (MyCondition)
; is equivalent To
If !(MyCondition)

Let Begins the assignment of a variable to a value. The variable name followed by a single equals (=) sign followed by the value completes the statement. If the variable type is a string, the value must be enclosed in quotation marks. For example, the following two statements are evaluated in the same manner:

Let sMyWorkplace = "Freedom Scientific" ; strings require quotation marks
sMyWorkplace = "Freedom Scientific"
    ; AND
Let iMyAccountNumber = 12345 ; numbers (integers) are Not surrounded by quotation marks
iMyAccountNumber = 12345

Void Used to declare a function type as returning no value when returning to a calling script or function. A function that is declared as being of a type like Integer or String returns a value of that type to the calling script or function. If a function is not declared to be of any specific type, it is assumed to be of type Void.

A Note on the Use of AI in JAWS Scripting

Introduction

The rapid advancement of Large Language Models (LLMs) and Artificial Intelligence (AI) has fundamentally transformed software development practices across the industry. Tools such as GitHub Copilot, ChatGPT, Claude, and various open-source alternatives have become integral to modern development workflows, with Google reporting that "the same amount of characters in the code are now completed with AI-based assistance as are manually typed by developers". This transformation has led many developers to explore AI-assisted code generation for specialized scripting languages, including JAWS Scripting Language (JSL).

However, the application of LLMs to specialized, low-resource programming languages like JAWS Scripting Language presents unique challenges that warrant careful examination. This chapter explores both the potential benefits and significant limitations of using AI for JAWS script generation, supported by current research on LLM code generation capabilities and their particular struggles with domain-specific languages.

The Promise and Reality of AI-Assisted Code Generation

Advantages of Using LLMs for Code Generation

When applied appropriately, LLMs and AI can offer several advantages in software development:

1. Increased productivity: LLMs can automate routine code generation tasks, allowing developers to focus on higher-level aspects of projects such as architecture, design decisions, and complex problem-solving.

2. Faster development cycles: By leveraging LLMs, developers can rapidly prototype and iterate on their ideas, potentially reducing time-to-market for new features and applications.

3. Reduced human error: Automated code generation can minimize certain types of human errors, such as typos or basic syntax mistakes, when the model has sufficient training data and the language is well-represented.

4. Consistent formatting: LLMs can help ensure that generated code adheres to consistent formatting and coding conventions, improving code readability and maintainability when properly configured.

5. Learning assistance: For developers new to a language or framework, LLMs can provide examples and explanations that facilitate learning, though these must be carefully verified.

6. Boilerplate generation: LLMs excel at generating repetitive code structures and standard implementations that follow well-established patterns.

General Disadvantages and Limitations

Despite these advantages, LLMs face significant challenges in code generation:

1. Lack of deep understanding: LLMs struggle to grasp intricate details and nuances of specific project requirements, leading to potential inaccuracies or incomplete code that may appear correct superficially but fail under real-world conditions.

2. Functional correctness issues: Generated code may run successfully but fail to pass all unit tests due to logic errors and misunderstandings, producing output that does not fully satisfy intended functionality or performance criteria.

3. Complex requirement handling: LLMs often struggle with generating code for complex or highly specific scenarios that require domain expertise and manual intervention.

4. Security vulnerabilities: AI-generated code can inadvertently introduce security vulnerabilities or expose sensitive information if proper security measures are not rigorously validated.

5. Dynamic content challenges: LLMs may struggle to generate code that effectively handles dynamic or user-generated content, such as robust input validation or real-time data processing.

6. Hallucination problems: LLMs frequently "hallucinate" by fabricating package names, APIs, or functions that do not exist, creating code that appears plausible but is fundamentally broken.

7. Overconfidence: LLMs deliver outputs with unshakable confidence, even when generating incorrect or fabricated code, making it difficult for less experienced developers to identify problems.

The Challenge of Low-Resource Programming Languages

Understanding Low-Resource and Domain-Specific Languages

JAWS Scripting Language falls into the category of Low-Resource Programming Languages (LRPLs) and Domain-Specific Languages (DSLs). Research has shown that LRPLs and DSLs face unique challenges, including severe data scarcity and highly specialized syntax and semantics that are poorly represented in general-purpose datasets.

The lack of specialized datasets and benchmarks, combined with limited research focus on LRPLs and DSLs, has resulted in fewer advancements in handling these languages effectively. This creates a significant gap in LLM capabilities when developers attempt to use these tools for specialized scripting tasks.

Technical Architecture of JAWS Scripting

Before examining the specific challenges LLMs face with JAWS scripting, it is essential to understand the technical architecture and compilation model that makes JAWS scripting fundamentally different from interpreted scripting languages that LLMs encounter more frequently.

The Compiled Nature of JAWS Scripts

JAWS Scripting Language is a compiled, proprietary language, not an interpreted scripting language. This distinction has profound implications for development workflow and for LLM-generated code:

1. Source to binary compilation: JAWS scripts are written in human-readable source files (.jss) that must be compiled into machine-readable binary files (.jsb) before execution. The compilation process is performed by either:

   • SCompile.exe - A command-line compiler located in the JAWS program directory (typically C:\Program Files\Freedom Scientific\JAWS[version]\scompile.exe)

   • The JAWS Script Manager - An integrated development environment accessed via INSERT+F2, which provides compilation, editing, and debugging capabilities

2. Compilation syntax checking: The compiler performs strict syntax validation, rejecting any code that violates JSL grammar rules. Error messages report the specific file, line number, and column where syntax violations occur (e.g., "file notepad.jss, line 5, column 1: Unknown variable ioi").

3. Language-specific compilation: A critical technical limitation is that scompile.exe always compiles scripts for the language of the currently-running JAWS instance. This means that generating a .jsb file in a folder for another language actually compiles the script for the running language, not the target language. Multi-language script distribution requires specialized build tools or JAWSUtil.vbs scripts.

4. Binary protection: The compiled .jsb files serve a dual purpose - performance optimization and intellectual property protection through source code obscuration. Users cannot read .jsb files to understand script logic without access to the original .jss source files.

5. Deployment requirements: For scripts to function, the compiled .jsb files must be placed in specific directory structures:

   • User-specific settings: C:\Users[username]\AppData\Roaming\Freedom Scientific\JAWS[version]\Settings\enu\

   • All-users settings: C:\ProgramData\Freedom Scientific\JAWS[version]\Settings\enu\

6. Script reloading: After compilation, JAWS must reload the scripts to recognize changes. This typically requires either restarting JAWS or explicitly reloading the script file for the active application.

The Multi-File Architecture

Professional JAWS script development involves coordinating multiple file types, each serving distinct purposes:

• .jss (JAWS Script Source): Contains the executable script code, user-defined functions, and event handlers. This is the primary file that developers write and that must be compiled.

• .jsb (JAWS Script Binary): The compiled machine code generated from .jss files. JAWS reads only .jsb files at runtime; .jss files serve solely as source for development.

• .jsh (JAWS Script Header): Defines global variables, constants, window names, window classes, and external function declarations. By convention, constants for window names use "wn" prefix, window classes use "wc", and global variables use "g" prefixes (gi for global integer, gs for global string, etc.).

• .jsm (JAWS Script Messages): Contains all localizable strings, spoken messages, and on-screen text used for comparison. Messages use "msg" prefix, comparison strings use "sc" prefix. This separation enables internationalization without modifying script logic.

• .jkm (JAWS Key Map): Defines keyboard shortcuts that trigger specific scripts. Uses a proprietary syntax for mapping key combinations to script names. Organized by keyboard layout (Desktop, Laptop, etc.).

• .jsd (JAWS Script Documentation): Contains structured documentation for each script and function, including synopsis, description, parameters, and return values. JAWS reads this file to provide Keyboard Help (INSERT+F1) information to users.

• .jcf (JAWS Configuration): Stores application-specific configuration settings and user preferences for how JAWS should behave with particular applications.

• .jdf (JAWS Default): Defines default settings and behaviors that JAWS should apply when no custom scripts exist for an application.

The coordination between these files follows strict conventions detailed in Chapter [scripting-standards]{reference-type="ref" reference="scripting-standards"}. For example, a message defined in the .jsm file as msgButtonText = "Click the button" would be referenced in the .jss file using SayFormattedMessage(msgButtonText, sButtonName) where sButtonName is a string variable containing the actual button name.

The Windows Accessibility API Layer

JAWS scripts operate at the intersection of multiple Windows accessibility APIs, each with different characteristics and capabilities:

MSAA (Microsoft Active Accessibility) The legacy API introduced in Windows 95, based on the Component Object Model (COM). MSAA exposes basic information such as object name, role, location, and state through the IAccessible interface. MSAA uses a hierarchical model with parent-child relationships and supports simple child elements identified by numeric Child IDs.

IAccessible2 An extension of MSAA developed by IBM and placed under the Linux Foundation. IAccessible2 fills perceived omissions in MSAA by adding support for:

- Complex text attributes and text formatting

- Table navigation with row/column headers

- Relations between objects (e.g., labels for controls)

- Unique object identifiers that persist across sessions

- Enhanced state information beyond MSAA's basic states

IAccessible2 does not support child IDs; full accessible objects must be created for each element. JAWS scripts must use QueryService to switch between MSAA IAccessible and IAccessible2 interfaces.

UI Automation (UIA) Microsoft's modern accessibility API introduced in Windows Vista and .NET Framework 3.0. UIA marks a radical architectural departure from MSAA, using a provider/client model rather than COM-based interfaces. Key differences include:

- Separate provider-side (application) and client-side (AT) APIs

- Rich support for patterns (interfaces) that controls implement

- More detailed element property exposure

- Event model based on property changes rather than focus changes

- Out-of-process operation for improved security and stability

UIA Express (IAccessibleEx) A bridge interface that allows mapping between UI Automation elements and MSAA interfaces, enabling interoperability during the MSAA-to-UIA transition period.

JAWS provides native support for all these APIs, but scripters must understand which API is being used by target applications and choose appropriate functions accordingly. The JAWS UIA Script API, introduced in JAWS 2020, gives scripters direct access to the UI Automation infrastructure through functions like:

• FSUIA_CreateElement() - Creates a UIA element object from a window handle

• FSUIA_GetProperty() - Retrieves UIA property values (returns VARIANT type)

• FSUIA_FindFirst() and FSUIA_FindAll() - Search for elements using UIA tree walker patterns

• ComAttachEvents() - Registers event handlers for UIA property changes, structure changes, and automation events

The UIA API uses pre-defined integer constants for element types, property identifiers, pattern identifiers, and control types, all declared in the UIA.jsh header file provided with JAWS.

Specific Challenges for JAWS Scripting Language

Given this technical architecture, JAWS Scripting Language presents several unique challenges that make it particularly problematic for LLM-based code generation:

1. Extremely limited training data: Unlike popular languages such as Python, JavaScript, or Java, JAWS scripts are rarely published in open-source repositories. The proprietary nature of many JAWS scripts and the small size of the JAWS scripting community mean that LLMs have minimal exposure to actual JSL code during training.

2. Unique syntax and semantics: JAWS Scripting Language is a proprietary compiled language with syntax patterns that differ significantly from mainstream languages. Without substantial training examples, LLMs frequently confuse JSL with more common languages like JavaScript, Python, Visual basic, and C#.

3. Cross-contamination with other screen reader languages: NVDA uses Python for scripting, while other assistive technologies use different languages. LLMs often generate hybrid code that borrows inappropriately from these other ecosystems, producing syntactically invalid JSL.

4. Specialized domain knowledge: Effective JAWS scripting requires deep understanding of:

   • Windows accessibility APIs

   • Screen reader interaction patterns

   • Application-specific behaviors

   • User experience considerations for blind and low-vision users

   • JAWS-specific functions and event handlers

5. Compilation requirements: A critical issue that LLMs consistently fail to address is that JAWS scripts must be compiled from .jss source files into .jsb binary files using either SCompile.exe or the JAWS Script Manager. LLMs rarely mention this essential step, leading users to wonder why their generated scripts do not function. The compilation process involves:

   • Running scompile.exe application.jss from the command line in the appropriate settings directory

   • Or using CTRL+S in the JAWS Script Manager to save and compile simultaneously

   • Receiving either "Compile Complete" (success) or detailed error messages with line/column information

   • Understanding that syntax errors completely prevent .jsb generation - there is no partial compilation

   • Recognizing that even successfully compiled scripts require JAWS to reload them before changes take effect

6. File structure complexity: JAWS scripting involves multiple coordinated files:

   • .jss (JAWS script source files)

   • .jsm (JAWS script message files for localization)

   • .jsh (JAWS script header files for constants and globals)

   • .jkm (JAWS key map files)

   • .jcf (JAWS configuration files)

   • .jdf (JAWS default files)

   • .jsb (compiled script binaries)

   LLMs typically generate only .jss content and fail to properly structure the supporting files required for professional script development.

Evidence from Research

Research on code generation for low-resource languages provides empirical evidence for these challenges. On the HumanEval benchmark, Codex could solve about 28.8% of tasks on the first attempt for well-represented languages, but performance drops dramatically for languages with limited training data.

General-purpose LLMs consistently fail at scale when faced with deep interdependencies, language-specific constraints, and intricate build systems. For JAWS scripting, these challenges are compounded by the language's specialized nature and the limited feedback available to train models.

Package Hallucination: A Critical Security Concern

The Nature of Package Hallucinations

One of the most serious issues with LLM-generated code is the phenomenon of "package hallucination" or "API hallucination." Package hallucination occurs when LLMs generate code that references or recommends packages that do not exist in any public repositories.

Research has found alarming rates of hallucination:

• 21.7% of package names recommended by open-source AI models were hallucinations, while commercial models hallucinated 5.2% of package names

• In testing across four LLMs, between 22.5% and 64.5% of conversations generated hallucinated packages

• Code generators referenced some 440,445 hallucinated packages, including 205,474 unique examples of totally invented package names

Security Implications

The security implications of package hallucinations are severe. An adversary can create a malicious package with the same name as a hallucinated package and inject malicious code, which unsuspecting users will download and execute.

This attack vector is similar to phishing, exploiting the trust users have in the model and relying on users not performing due diligence. For JAWS scripting, where scripts often have deep system access and can monitor user activity, the security risks of executing malicious code are particularly severe.

Persistence and Exploitability

The hallucination problem is not just pervasive but also persistent, with LLMs repeatedly recommending the same fictitious packages. This persistence makes the attack vector more viable, as malicious actors can reliably predict which hallucinated names to register.

Research shows that even when different developers ask LLMs questions about the same topic but craft questions differently, there is a likelihood the LLM would recommend the same hallucinated package in each case.

The "Vibe Coding" Phenomenon and Its Risks

Defining Vibe Coding

A troubling trend in AI-assisted development is "vibe coding"--the practice of rapidly prototyping or building entire applications by following LLM suggestions without deeply understanding or reviewing the code. The focus is on speed rather than security or verification, with developers accepting AI-generated suggestions without hesitation.

Risks for JAWS Scripting

For JAWS scripting, vibe coding poses exceptional risks:

1. Accessibility Impact: Poorly written JAWS scripts directly affect users who are blind or have low vision, potentially making applications less accessible rather than more accessible.

2. System Stability: Buggy scripts can cause JAWS to crash or behave unpredictably, disrupting critical assistive technology that users depend on for computer access.

3. Privacy Concerns: JAWS scripts can access screen content, keystrokes, and other sensitive information. Malicious or poorly vetted code poses significant privacy risks.

4. False Confidence: Users may believe LLM-generated scripts are correct because they compile and appear to run, not realizing they may contain subtle bugs or security issues.

5. Maintenance Burden: Scripts generated without deep understanding become technical debt, difficult to maintain or debug when issues arise.

Code Quality Issues in LLM-Generated Code

Types of Hallucinations and Errors

Research has identified several categories of problems in LLM-generated code:

1. Syntax violations: State-of-the-art models like GPT-4.1, Codex, and GPT-4o exhibit high frequencies of syntax violations, particularly in less common languages.

2. Invalid reference errors: Generated code frequently contains invalid reference errors, calling functions or using variables that do not exist.

3. API knowledge conflicts: LLMs demonstrate API knowledge conflicts, mixing APIs from different frameworks or versions.

4. Definition missing: LLMs occasionally omit variable or function definitions that are required before use.

5. Incorrect boundary conditions: Generated programs fail to verify boundary conditions properly, leading to runtime errors.

6. Logic errors and misunderstandings: LLMs struggle to extract information from natural language and establish correct logic, particularly for algorithmic problems.

7. Timeout issues: While LLM-generated code may be correct, algorithms are often suboptimal with high time complexity.

Recent studies on DSL code generation provide quantitative evidence. Research on DSLs with approximately 700 custom API functions found:

• Fine-tuned models achieved lower hallucination rates but higher syntax error rates

• RAG-based models demonstrated better syntax correctness (2 percentage points higher compilation rates)

• Both approaches struggled with custom function names, with hallucination rates between 22.5% and 64.5% of conversations generating hallucinated packages

• Multiple iterations were required to achieve correct syntax - in one robotics DSL study, LLMs required up to 117 rounds of refinement

For DSLs specifically, research highlights that "performance drops noticeably" compared to general-purpose languages, with hallucinations and syntax errors increasing particularly for DSLs with high numbers of custom function names.

JAWS-Specific Code Quality Concerns

For JAWS scripting, LLMs exhibit additional quality issues:

• Generating pseudocode rather than valid JSL syntax

• Mixing Python constructs from NVDA scripting with JSL

• Failing to use proper JAWS function names and signatures

• Incorrectly handling event-driven programming patterns

• Omitting required message file (.jsm) and header file (.jsh) definitions

• Generating scripts that violate Freedom Scientific's scripting standards

• Creating code that compiles but produces incorrect speech output or behavior

• Failing to properly handle cursor management and state restoration

Detailed examination of common LLM failures reveals specific patterns:

Syntax Confusion Between Screen Readers

LLMs frequently mix syntax from different screen reader scripting languages:

Python/NVDA contamination LLMs often generate code like:

``` {style="Alabaster"}
\# INCORRECT - Python/NVDA syntax, not JAWS
def AutoStartEvent():
    ui.message("Application started")
    return True
```

Correct JAWS syntax would be:

``` {style="Alabaster"}
; CORRECT - JAWS Script Language syntax
Void Function AutoStartEvent()
    SayMessage(OT_USER_BUFFER, msgAppStarted)
EndFunction
```

Lua/SuperNova contamination Occasionally LLMs mix Lua-like syntax:

``` {style="Alabaster"}
-- INCORRECT - Lua syntax, not JAWS
function sayWindowName()
    local windowName = getWindowName()
    speak(windowName)
end
```

Javascript Occasionally LLMs mix javascript-like syntax:

``` {style="Alabaster"}
// Javascript (not JAWS scripting), Often seen in web-related contexts and .js can be confused with .jss
// INCORRECT for JAWS: browser/DOM-focused example
function sayApplicationName() {
    const windowName = document.title || window.name;
    console.log(windowName); // or use a TTS API in a browser
}
```

C# Occasionally LLMs mix C-Sharp-like syntax:

``` {style="Alabaster"}
// C\# (desktop example using System.Windows.Forms; not JAWS code)
// INCORRECT for JAWS: managed WinForms example
using System;
using System.Windows.Forms;

public void SayApplicationName()
{
    string windowName = Form.ActiveForm?.Text ?? "Unknown";
    Console.WriteLine(windowName); // placeholder for speech API
}
```

VB.NET Occasionally LLMs mix Visual Basic .NET-like syntax:

``` {style="Alabaster"}
// Visual Basic .NET (not JAWS scripting)
' INCORRECT for JAWS: VB.NET example
Sub SayApplicationName()
    Dim windowName As String = If(Application.OpenForms.Count > 0, Application.OpenForms(0).Text, "Unknown")
    Console.WriteLine(windowName) ' placeholder for speech API
End Sub
```

Generic pseudocode Most commonly, LLMs generate syntactically invalid pseudocode:

``` {style="Alabaster"}
// INCORRECT - Generic pseudocode
script SayApplicationName() {
    windowName = GetWindowName();
    Speak(windowName);
}
```

Function Name and Signature Errors

LLMs frequently hallucinate function names or use incorrect parameters:

• Non-existent functions: Generating calls like GetControlText(handle), SpeakText(string), or ReadCurrentLine() - functions that sound plausible but do not exist in the JAWS API.

• Incorrect parameter types: Calling existing functions with wrong parameter types, such as:

  ; INCORRECT - SayString takes int for output mode, not string
  SayString("Text to speak", "user_buffer")
  
  ; CORRECT
  SayString("Text to speak", OT_USER_BUFFER)
  

• Missing required parameters: Omitting mandatory parameters like the output type parameter in Say() functions.

• API version conflicts: Mixing functions from different JAWS versions, calling functions not available until JAWS 17 in code supposedly targeting JAWS 13.

Event Handler Misunderstandings

LLMs demonstrate poor understanding of JAWS event-driven architecture:

• Incorrect event signatures: Generating Function FocusChangedEvent() without the required handle hWindow parameter.

• Missing return types: Omitting Void or proper return type declarations for event functions.

• Failure to call default handlers: Not including FocusChangedEvent(hWindow) calls to invoke default behavior after custom processing.

• Global variable management errors: Not updating necessary global variables like gCurrentWindow or ghLastFocus within event handlers.

• Performance-critical event misuse: Placing computationally expensive operations in frequently-called events like KeyPressedEvent(), causing JAWS to become sluggish.

File Structure and Organization Failures

LLMs typically generate only .jss content and fail to properly structure supporting files:

• Message definition omission: Using string literals directly in scripts instead of defining messages in .jsm files:

  ; INCORRECT - Hardcoded string, not localizable
  SayString("Click the OK button")
  
  ; CORRECT - Message from .jsm file
  SayMessage(OT_USER_BUFFER, msgClickOK)
  

• Constant definition failures: Not defining window names, window classes, or comparison strings as constants in .jsh files.

• Global variable declaration errors: Defining global variables in .jss files instead of .jsh files, causing scope issues.

• Key mapping omission: Generating scripts without corresponding .jkm entries, leaving scripts impossible to trigger.

• Documentation generation failures: Not creating proper .jsd documentation with Synopsis and Description fields required for Keyboard Help.

Cursor Management and State Restoration Bugs

LLMs generate code that violates critical cursor management principles:

; INCORRECT - Activates JAWS Cursor without saving/restoring PC Cursor
Function GetStatusBarText()
    JAWSCursorHome()
    JAWSCursorDown()
    Let sText = GetLine()
    Return sText
EndFunction

; CORRECT - Proper cursor save/restore
Function GetStatusBarText()
Var
    String sText,
    Int iSavedCursor
    
    Let iSavedCursor = SaveCursor()
    RouteJAWSToPC()
    JAWSCursorHome()
    JAWSCursorDown()
    Let sText = GetLine()
    RestoreCursor(iSavedCursor)
    
    Return sText
EndFunction

Common cursor-related errors include:

• Not calling SaveCursor() before cursor activation

• Not calling RestoreCursor() afterward

• Using JAWS Cursor when Invisible Cursor would be appropriate

• Not considering whether PC Cursor, JAWS Cursor, or UIA Scan Cursor is most appropriate

Why LLMs Struggle with JAWS Scripting

Training Data Scarcity

The efficacy of language models is constrained by both the volume and quality of available annotated data, a limitation especially pronounced in low-resource programming languages. For JAWS scripting:

• Few JAWS scripts are available in public repositories

• Most professional scripts are proprietary (ie., sold by Freedom Scientific, third-party developers, or free but shipped as .exe binaries that install .jsb and .jkm files without the .jss source)

• Freedom Scientific's documentation exists but is limited compared to mainstream language resources

• The community is small relative to general programming communities

• Script examples in forums and documentation are often incomplete snippets rather than full implementations

Specialized Knowledge Requirements

LLMs struggle with specialized hardware or software platforms and industries with strict regulatory requirements. JAWS scripting requires understanding of:

• Assistive technology principles and best practices

• Screen reader user experience patterns

• Windows accessibility API hierarchies (MSAA, UI Automation, IAccessible2)

• Application-specific object models

• Proper cursor management techniques

• Event-driven programming in the JAWS context

• Speech and braille output considerations

• Localization and internationalization for screen readers

Each of these areas requires deep technical knowledge that extends far beyond syntax:

Assistive Technology Design Principles

Effective JAWS scripts must embody AT-specific design principles that have no analogs in general-purpose programming:

• Non-visual information architecture: Understanding how to present information sequentially that sighted users perceive simultaneously. For example, a dashboard with multiple panels requires careful script design to announce each panel's heading and content in logical order.

• Cognitive load management: Scripts must avoid overwhelming users with excessive speech while providing sufficient information for task completion. This balance differs fundamentally from visual UI design.

• Progressive disclosure: JAWS scripts typically announce summary information first, with detailed information available through subsequent keystrokes (e.g., first keystroke speaks synopsis, double-press speaks description).

• Braille vs. speech considerations: Information displayed in Braille often requires different formatting than spoken output. Speech can use inflection and pacing; Braille must rely on punctuation and structure.

Windows Accessibility API Expertise

Understanding the technical differences between accessibility APIs is essential for effective scripting:

MSAA Limitations MSAA's IAccessible interface provides only basic information: name, role, description, value, state, location. For complex applications, scripters must often work around MSAA's limitations by:

- Using the Invisible Cursor to read on-screen text when object information is insufficient

- Parsing concatenated strings that applications incorrectly expose as single values

- Implementing workarounds for controls that expose incorrect or incomplete role information

IAccessible2 Capabilities When applications support IAccessible2, scripters can access rich text attributes, table structures, and object relations. However, this requires:

• Using QueryService to obtain IAccessible2 interfaces from MSAA IAccessible references

• Understanding that IAccessible2 does not support child IDs - full accessible objects must exist

• Working with unique IDs that persist for object lifetime within the current window

• Handling relation sets to navigate from controls to their labels or vice versa

UI Automation Complexity The UIA API introduces pattern-based programming where controls implement specific patterns (Value, Selection, Grid, etc.). Scripters must:

- Create FSUIA objects and attach event handlers using ComAttachEvents()

- Understand that UIA elements are tree-structured with multiple tree views (Raw, Control, Content)

- Work with VARIANT return types that may contain strings, integers, booleans, or element references

- Implement proper element caching strategies to avoid performance issues

- Handle the asynchronous nature of UIA events properly

- Manage object lifetime carefully to prevent memory leaks or dangling references

Cursor Management Patterns

JAWS provides multiple cursor types, each with specific use cases and technical requirements:

PC Cursor The standard Windows focus/caret. Scripts should respect PC Cursor position and avoid disrupting it unnecessarily.

JAWS Cursor An on-screen cursor that can read any visible text, including text that applications do not expose through accessibility APIs. Technical considerations include:

- Storing PC Cursor position before activating JAWS Cursor: SaveCursor()

- Positioning the JAWS Cursor: RouteJAWSToPC(), JAWSCursorUp(), etc.

- Reading text: GetLine(), GetWord(), GetCharacter()

- Restoring PC Cursor: RestoreCursor()

- Performance implications of Off-Screen Model (OSM) rendering

Invisible Cursor Similar to JAWS Cursor but operates without moving the user's focus. Critical for reading information without disrupting user workflow. Used via:

- RouteInvisibleToPC(), InvisibleCursorUp(), etc.

- GetLineWithCursor(Invisible_Cursor)

- Must save/restore PC Cursor position identically to JAWS Cursor

UIA Scan Cursors Introduced in JAWS 2020 to work with applications using UI Automation that render poorly in the traditional OSM. Technical differences include:

- JAWS Scan Cursor: GetLineWithCursor(JAWSScan_Cursor)

- Invisible Scan Cursor: GetLineWithCursor(InvisibleScan_Cursor)

- Navigate through UIA tree structure rather than screen coordinates

- More reliable for modern applications but with different navigation semantics

- Require understanding of UIA element tree hierarchies

The choice of cursor depends on application architecture, available accessibility API support, and specific task requirements. LLMs cannot reliably make these architectural decisions without deep understanding of screen reader internals.

Event-Driven Programming Patterns

JAWS scripting is fundamentally event-driven, with specific event functions that the JAWS engine calls when conditions occur:

• AutoStartEvent() - Called when JAWS loads for an application

• WindowCreatedEvent(handle hWindow) - Called when windows are created

• FocusChangedEvent(handle hWindow) - Called when focus moves between windows

• ActiveItemChangedEvent() - Called when active item changes in lists/trees

• ValueChangedEvent() - Called when control values change

• NewTextEvent() - Called when new text appears

• KeyPressedEvent(string sKey) - Called before keys are passed to applications

• MenuModeEvent(int iMode) - Called when menus are activated/deactivated

Effective use of these events requires understanding:

• When each event fires relative to application state changes

• How to avoid performance problems by keeping event handlers efficient

• Which global variables must be updated within each event handler

• How events interact with user buffer state and virtual cursor modes

• When to call default event handlers vs. implementing custom behavior

LLMs frequently generate key-driven code (scripts bound to keystrokes) when event-driven code would be more appropriate and reliable.

The Compilation Knowledge Gap

A particularly problematic gap is LLMs' consistent failure to inform users about compilation requirements. From extensive experience, even advanced models neglect to mention that:

1. Source files (.jss) must be compiled to binary files (.jsb)

2. Compilation can be done via SCompile.exe or the JAWS Script Manager

3. The compiled files must be placed in the correct directory structure

4. Scripts must be reloaded in JAWS after compilation

5. Syntax errors prevent compilation and provide error messages

6. Different JAWS versions may have different compilation requirements

This omission leaves users frustrated, unable to understand why their "completed" scripts do not function.

Trust and Reliability Concerns

The Trust Problem

One of the major concerns about language models today is trust--they can give strikingly amazing results in some cases but are often subtly wrong in others, and some are non-deterministic.

For JAWS scripting, trust issues are particularly acute:

• Users cannot easily verify script correctness without deep JSL knowledge

• Testing requires actual blind or low-vision users or extensive simulation

• Errors may not be immediately apparent but emerge in edge cases

• Security vulnerabilities may be hidden in plausible-looking code

• Performance issues may only manifest during heavy usage

The Need for Human Expertise

It becomes critical to design languages to be read, not just written, so humans can review and approve generated code. For JAWS scripting:

• Scripts should be written following Freedom Scientific's coding standards (Chapter [scripting-standards]{reference-type="ref" reference="scripting-standards"})

• All scripts must be thoroughly tested by experienced screen reader users

• Security implications must be carefully evaluated

• Performance impact must be assessed

• Scripts must be documented for future maintainability

FSCompanion Lacks Data to guide JAWS Scripting

FSCompanion was created as a help and support assistant, not as a code generator. Its training and tuning were focused on Freedom Scientific's public help articles, forum posts, FAQs, and other user-facing documentation; it was not trained on a curated corpus of JAWS scripting source code or on the multi-file project layouts that real JAWS scripts require. Consequently, any code-like output it produces is a byproduct of document-driven retrieval and general LLM pattern completion, not a reflection of direct knowledge of JAWS Script Language (JSL) internals.

Because FSCompanion's fine-tuning data is primarily documentation and support content, it lacks many of the concrete, executable examples and API usages that experienced scripters rely on. When prompted for script snippets, the assistant will often fall back to generic programming patterns learned by the underlying model (either GPT-3.5, GTP-4, or GPT-4o) rather than Freedom Scientific's precise APIs, compilation constraints, or recommended file organization. That leads to outputs that may look plausible -- and even syntactically similar to JSL at a glance -- but which can contain subtle API mismatches, incorrect parameter types, or references to functions that do not exist in a given JAWS version.

From a technical standpoint, FSCompanion does not know about several crucial aspects of JAWS development: the need to split definitions across .jss, .jsm, and .jsh files, the requirement to compile sources into .jsb artifacts, the event signatures and cursor-management patterns that preserve user state, or the nuances of UIA/MSAA/IA2 integration. Because those details are rarely present in support articles, the assistant cannot reliably generate scaffolding that respects the runtime and compilation model; code it suggests may omit necessary save/restore cursor calls, fail to call default handlers, or assume synchronous behaviors that are incorrect in JAWS's event-driven environment.

Using FSCompanion-generated code without careful vetting therefore carries real accessibility and safety risks. A superficially working snippet can still degrade the experience for users who rely on JAWS: announcing the wrong information, disrupting focus or cursor position, introducing regressions across JAWS versions, or creating performance bottlenecks in frequently fired events. Those outcomes can be more harmful than no script at all, because they may silently reduce usability in ways that are difficult to detect without expert testing.

Practically, treat FSCompanion as a documentation and discovery tool rather than a scripting authority. Use it to find references, examples in support articles, and explanations of high-level concepts, but always validate any code through the standard JAWS development workflow: consult official API docs, compile and test in the target JAWS version, and have an experienced scripter review the result. If automated code generation is required, prefer approaches that ground responses in curated code examples (RAG with vetted repositories or models fine-tuned on actual JAWS scripts) and enforce a verification step before any script is used in production.

Best Practices for Using AI in JAWS Script Development

Treat LLM Output as a Starting Point, Not a Solution

When using LLMs for JAWS scripting assistance:

1. Never deploy generated code without review: All LLM-generated code must be thoroughly reviewed by an experienced JAWS scripter before use.

2. Verify syntax carefully: Check that generated code uses actual JSL syntax, not Python, Lua, or pseudocode.

3. Validate all function calls: Ensure that all referenced functions exist in the JAWS API and are called with correct parameters.

4. Test extensively: Test scripts with actual screen reader users in real-world scenarios, not just in isolated test cases.

5. Review against standards: Compare generated code against Freedom Scientific's scripting standards (Chapter [scripting-standards]{reference-type="ref" reference="scripting-standards"}) and coding guidelines (Section [acceptable-guidelines]{reference-type="ref" reference="acceptable-guidelines"}).

6. Verify compilation: Always attempt to compile generated scripts and address any compilation errors before testing.

7. Check file structure: Ensure that supporting files (.jsm, .jsh, .jkm) are properly structured and coordinated.

Use LLMs for Specific Limited Tasks

LLMs may be more reliable for certain limited tasks:

• Generating boilerplate code structures

• Providing examples of common patterns (with verification)

• Suggesting function names or approaches (with validation)

• Explaining JAWS API documentation

• Converting between different code formatting styles

• Generating documentation templates

However, even these uses require expert verification before implementation.

Maintain Deep Understanding

When a model starts hallucinating, it can take more time to fix the generated code than to write it manually. Therefore:

• Invest in learning JAWS Scripting Language properly

• Study Freedom Scientific's official documentation

• Learn from existing, vetted scripts

• Understand the underlying accessibility principles

• Develop expertise in debugging JAWS scripts

• Participate in the JAWS scripting community

The Future of AI-Assisted JAWS Scripting

Potential Improvements

Future developments may improve LLM capabilities for specialized languages:

1. Specialized fine-tuning: Models fine-tuned on specialized datasets can improve performance, though this requires substantial JAWS scripting examples.

2. Retrieval-Augmented Generation (RAG): RAG approaches can help mitigate hallucinations by grounding responses in actual documentation.

3. Improved evaluation methods: Developing standard benchmark datasets and evaluation metrics for LRPLs and DSLs could drive improvements.

4. Domain-specific models: Creating models specifically trained on accessibility scripting languages could improve results.

5. Better validation tools: Integrated compilation checking and API validation could catch errors before deployment.

Realistic Expectations

However, several factors suggest that LLM limitations for JAWS scripting will persist:

• The JAWS scripting community will likely remain small

• Proprietary scripts will continue to limit public training data

• The specialized knowledge required remains difficult to encode

• Solutions developed for specific language pairs prove ineffective when applied to other language combinations

• The compilation and file structure complexity adds layers of difficulty

Conclusion

While LLMs and AI have transformed software development for mainstream languages, their application to JAWS Scripting Language faces fundamental challenges. The severe data scarcity, specialized syntax, and unique architectural requirements of low-resource programming languages mean that LLMs cannot fully leverage their capabilities.

For JAWS scripting specifically, LLMs frequently generate code in non-functional pseudocode, borrow inappropriately from other scripting languages (particularly Python from NVDA), fail to mention critical compilation requirements, misunderstand the multi-file architecture, demonstrate poor knowledge of Windows accessibility APIs, generate invalid function calls and event handlers, and produce code that violates established scripting standards. These limitations, combined with serious security concerns around package hallucinations (21.7% for open-source models) and the risks of "vibe coding" (accepting AI suggestions without review), mean that LLM-generated JAWS scripts require extraordinary caution.

The technical architecture of JAWS scripting--compiled language, multi-file coordination, Windows accessibility API integration, event-driven programming model, cursor management requirements, and speech/Braille output considerations--creates a complexity that LLMs cannot reliably navigate without extensive training data that simply does not exist in public repositories.

Developers must possess deep understanding of JAWS Scripting Language and its ecosystem to effectively evaluate, adapt, and integrate any LLM-generated code. The generated code should be treated as a potentially flawed starting point requiring expert review, never as a final solution. This expert review must encompass:

• Verification of syntactic correctness against JSL grammar

• Validation that all function calls use actual JAWS API functions with correct signatures

• Confirmation that event handlers follow proper patterns and update necessary global state

• Checking that cursor management includes proper save/restore sequences

• Ensuring proper file structure across .jss, .jsm, .jsh, .jkm, and .jsd files

• Verifying compliance with Freedom Scientific's scripting standards

• Testing with actual screen reader users in real-world scenarios

• Security review to prevent exposure of sensitive information

• Performance testing to ensure responsiveness

Until substantial improvements occur in LLM training data and specialized fine-tuning for assistive technology scripting languages, human expertise remains irreplaceable in JAWS script development. The stakes--affecting users who depend on assistive technology for computer access--are too high to accept anything less than rigorously validated, professionally developed scripts.

Research on DSLs and LRPLs confirms these concerns with quantitative evidence. Studies show that even with fine-tuning, DSLs with high numbers of custom function names (like JAWS with its hundreds of specialized API functions) experience hallucination rates of 21.7% for open-source models, compilation failures in significant percentages of attempts, and the need for multiple iterations (sometimes 100+ rounds) to produce correct code. The specialized nature of JAWS scripting, combining domain-specific language characteristics with assistive technology requirements and Windows API knowledge, places it among the most challenging environments for LLM code generation.

As LLMs become more reliable and trustworthy over time, they will augment the developer experience, but they will not replace the need for programming expertise. For JAWS scripting, this human expertise is not just desirable but essential. The compilation requirement alone--which LLMs consistently fail to mention--demonstrates the gap between LLM capabilities and the practical knowledge required for JAWS script development. When combined with the specialized knowledge of Windows accessibility APIs (MSAA, IAccessible2, UIA), event-driven programming patterns, cursor management techniques, speech and Braille output considerations, and assistive technology UX principles, the knowledge gap becomes insurmountable for current LLM technology.

The future may bring improvements through specialized fine-tuning, retrieval-augmented generation grounded in JAWS documentation, better evaluation methods, and domain-specific models trained on accessibility scripting languages. However, the fundamental constraint--the small size of the JAWS scripting community and the proprietary nature of professional scripts--suggests that training data limitations will persist indefinitely. Until these challenges are addressed, developers working with JAWS scripting must rely primarily on human expertise, treating LLM assistance as a supplementary tool requiring rigorous validation rather than a primary development method.

More Information

Additional Reading

This chapter draws on extensive research examining the capabilities and limitations of Large Language Models for code generation, particularly in specialized and low-resource programming languages. The following references provide comprehensive background on the technical challenges, security implications, and practical considerations discussed throughout this chapter.

Surveys and Comprehensive Studies on LLMs for Code Generation

{{#cite joel2024survey}}

{{#cite cassano2024knowledge}}

{{#cite cassano2023multiple}}

{{#cite diera2023enhancing}}

{{#cite klimek2023potential}}

{{#cite github2024repository}}

Package Hallucination and Security Vulnerabilities

{{#cite spracklen2024package}}

{{#cite saini2025importing}}

{{#cite lanyado2024package}}

{{#cite haque2025secure}}

{{#cite pradel2024hallucination}}

{{#cite liu2024exploring}}

{{#cite oyesanya2024package}}

{{#cite usenix2025package}}

{{#cite helpnetsecurity2025package}}

{{#cite sciencedaily2025threats}}

{{#cite darkreading2024hallucinations}}

{{#cite infoworld2025hallucinations}}

Vibe Coding: Definitions, Practices, and Implications

{{#cite karpathy2025vibe}}

{{#cite wikipedia2025vibe}}

{{#cite willison2025vibe}}

{{#cite kim2025user}}

{{#cite googlecloud2025vibeoverview}}

{{#cite ibm2025vibe}}

{{#cite codingscape2025tools}}

{{#cite mcnulty2025vibe}}

{{#cite uxplanet2025testing}}

{{#cite arsturn2025rapid}}

{{#cite nocodefinder2025vibe}}

Industry Reports on AI Adoption in Software Development

{{#cite google2024dora}}

{{#cite google2025dora}}

{{#cite github2023survey}}

{{#cite googlecloud2024announcing}}

{{#cite techrepublic2024dora}}

{{#cite register2025dora}}

{{#cite semaphore2025roundup}}

{{#cite opslevel2024takeaways}}

{{#cite devdynamics2024stateofdevops}}

{{#cite thoughtfuldane2024insights}}

Code Generation Quality and LLM Behavior

{{#cite chen2021evaluating}}

{{#cite ouyang2024llm}}

{{#cite orlanski2023measuring}}

{{#cite gong2022distributed}}

Accessibility APIs and JAWS Technical Documentation

{{#cite microsoft2023iaccessible2}}

{{#cite microsoft2023uia}}

{{#cite freedomscientific2024scripting}}

{{#cite freelists:new-era-in-scripting-jaws}}

Getting Started Guide

JAWS ships with the ability for you to customize scripts out of the box. You do not need a special build of the product but you must have administrative rights on your installed version and be using an Administrator user account in order to take advantage of this powerful tool.

Writing Script Files with Script Manager or a Text Editor

Editing

Create or edit JAWS Script Source (.jss) files from within any text editor. If you are new to scripting, you may find it easiest to use the JAWS Script Manager to create and edit script files because the Script Manager provides many helpful tools for navigating through a script file. Starting with JAWS 2020¹, the Script Manager provides an even more robust set of tools for creating your own script sets.

Tools include:

• SHIFT + F1 - Using a keystroke at the cursor where a function is located to have that function's details shown to you in a popup window you can review and dismiss with ESCAPE.

• Inserting built-in functions.

• Formatting scripts.

• Providing script language help.

• Writing and synchronizing the script documentation.

Formatting the script file for UTF-8 encoding.

You may learn about scripting by choosing the JAWS "Help Topics" item from the "Help" menu. Activate the Script Manager from within any application by one of the following methods:

• Press JAWSKEY + 0.

• Press JAWSKEY + F2 for the JAWS "Run Managers" dialog. Navigate through the list until Script Manager is selected, and then press ENTER. As mentioned above, starting with JAWS 2020, if you want to see the details for a function within a script, you can press SHIFT + F1 while your cursor is on the name of the function. For example, bring up the Notepad.jss file. It already has functions within it. Move to any function call within a script or function and place your cursor at the function call name. Pressing SHIFT + F1 shows you that function's details. Dismiss the function's details with ESCAPE. You are back in the .jss source file.

Naming

Script files follow the same naming and location conventions as most JAWS Settings files. Storing script files in the JAWS\Settings(Language) folder ensures that all necessary include files are present at compile time. By default, the JAWS Script Manager creates files with the same root name as the active application executable, and places them into the JAWS\Settings(Language) folder.

Compiling Script Files

The JAWS Script Manager compiles an active script file whenever the "Save" option is selected from the "File" menu. The compiler gives the resulting binary file the same root name as the script source file, and places it in the same folder. JAWS will load the new binary file the next time the application with the same root name gains focus by moving into the Windows foreground.

If you choose to edit script source files with a text editor instead of the Script Manager, you will need to call the application "SCompile.exe", located in the JAWS program folder to compile them from the command line. Call "SCompile", passing in script source file names. The compiler accepts wild cards, so many source files may be compiled with one command².

Formatting for UTF-8 Encoding

UTF-8 is an acronym for UCS Transformation Format 8-bit multibyte character encoding for Unicode. ANSI is an acronym for American National Standards Institute. For more technical information about the meanings of these terms, and how to format script files for UTF-8, see Formatting Script Files for UTF-8.

IME Support

JAWS can make Input Method Editors (IME) accessible. These special types of editors allow you to input from the keyboard into documents containing characters belonging to languages such as Chinese, Japanese, and Korean. In order for JAWS to support IME, you must install a text service compatible with Microsoft Text Services Framework (TSF). The installer is called FSTxtSvc.msi, and it installs the Freedom Scientific Text Service (FSTxtSvc). Note that this text service is not installed by default for languages other than Chinese, Japanese, and Korean.

Saving a UTF-8 Formatted Script File

When you open a script file using Script Manager, JAWS assumes that the file is formatted as an ANSI file. When you save the file, it is saved as an ANSI file. Unless you explicitly enable UTF-8 formatting for the current file, it is not saved as a UTF-8 file. Unless you direct it to be saved elsewhere, it will be saved in your User\Settings\(Language) folder.

If UTF-8 symbols are needed to appear on a Braille display, one or more .jbt files may need to be formatted as UTF-8 files.

The following example illustrates how to reformat your .jbt file for UTF-8:

• The .jbt file must temporarily replace the file whose name is identical in the Program Files folder for the current version of JAWS. Navigate to that folder. It's path will be something like, C:\Program Files\Freedom Scientific\JAWS\xx.0

• Change the name of the file called "US_Unicode.jbt" to something like "#US_Unicode.jbt".

• Copy the file with the same name as the original file whose name you just changed into the current folder. You should now have a file called "US_Unicode.jbt" file in the current folder as well as the renamed one that originally is part of the current JAWS build.

• From within Script Manager with the .jbt file open, find the option in the Files menu called "UTF-8 Format". The option is unchecked by default.

• Press ENTER on the option to enable UTF-8 formatting for the current file.

• Change or add whatever UTF-8 symbol is desired in the file, following its exact correct syntax.

• Save the file.

• Unload and reload JAWS without rebooting.

• From now on, the UTF-8 symbol coded into the .jbt file should be recognized by JAWS and displayed in Braille properly because the .jbt file has been saved with UTF-8 formatting enabled.

Naming JAWS Settings Files

Each time you start an application, JAWS determines what configuration files to load. Prior to JAWS 5.0¹, JAWS used the name of the executable file to retrieve and load the appropriate configuration files. JAWS uses only the first portion of the executable file name i.e. the part of the file without the extension. For example, when you started Microsoft Word 2007, the actual executable file name is winword.exe. JAWS uses only the first part of the file, winword, to locate and load into memory all configuration files for Word from the settings folder. JAWS loads these files on top of the set of default files already in memory.

Many times, the names of those files are not indicative of the actual application. For example, the configuration manager file for Internet Explorer 9 is Ieframe.jcf. The name of the file gives no indication of the actual program with which JAWS associates the file. This naming convention makes it difficult at times to locate the correct files for a particular application when its name is not clear.

The Confignames.ini File

JAWS 5.0 and later uses an .ini style file to equate more meaningful names with the executable file name. JAWS uses the Confignames.ini file to retrieve a more understandable name for a given application. This file can be found in your JAWS shared settings folder. The file contains aliases that are associated with the hard-to-remember executable file names. For example, when you run the Settings Center from within Internet Explorer 8 or 9, the file name JAWS displays in the title bar is Internet Explorer.jcf instead of Ieframe.jcf. As you browse the JAWS settings folder using Windows Explorer, you will see the same aliases there as you would in the title bar of a given JAWS manager as well.

Loading the Correct Files

Each time you start an application, JAWS uses the Confignames.ini file to determine if an alias exists for the application. If JAWS finds an alias in this file, then JAWS uses the alias to locate all the corresponding configuration files for the application. If no alias exists in the file, then JAWS uses the executable name of the application to locate all the corresponding configuration files.

For example, when you start Internet Explorer 9, JAWS notes the applications executable file name, Ieframe.dll, less the extension. JAWS must then search the Confignames.ini file for an entry containing Ieframe. When JAWS finds the entry, the alias of Internet Explorer is noted. JAWS then looks in the settings folder for all configuration files beginning with Internet explorer. When JAWS finds all the corresponding files, they are loaded into memory.

Adding Your Own Aliases

As you customize JAWS to work with new applications, JAWS continues to use the applications executable file name to create the various configuration files. However, you can add your own entries to the Confignames.ini file to give those hard-to-remember configuration files more meaningful names. When you add a new entry to this file, you must provide two pieces of information:

• application executable name less the extension

• alias to be used in place of the application name

If you are unsure of the exact name of the applications executable file, press JAWSKEY + Q and JAWS speaks the settings file currently in use along with the applications executable file name.

If the applications executable file name is hard to understand, you can press JAWSKEY + Q twice in succession to display the settings file in use information in the virtual viewer. Since you are adding an entry to the Confignames.ini file, your entry must follow a specific format. The applications executable name appears first. The executable name does not include the file extension. Following the executable name is the equals sign (=). You then type the alias for the executable file name. For example, the entry for Internet Explorer looks like the following:

ieframe=Internet Explorer

To add a new entry to the Confignames.ini file, do the following:

• Open the Confignames.ini file in a text editor e.g., Notepad++ or EdSharp.

• Press CONTROL + END to move to the bottom of the file.

• Add the new entry using the format of: executable name(less the extension) = alias

• Save the file.

When you start the application, JAWS uses the alias to locate and load the corresponding configuration files. If you have added an alias to the Confignames.ini file, you must restart the application before JAWS uses the alias to locate the configuration files. If you do not restart the application, JAWS uses the executable name to locate the configuration files.

Freedom Scientific Scripting Practices

This document contains a set of standards which is required for all script submissions to Freedom Scientific. Since failure to conform to these standards results in scripts which are either buggy, suffer from degraded performance, or which are not localizable to multiple languages, all submissions of scripts must conform to the following standards in order to be considered for acceptance:

• In the JSH file, define all script constants and globals. The only exception to this is for constants or globals that must be strictly local to the current script file and that should not be exposed to other script files.

• In the JSM file, define all messages to be spoken, and use only those message names in the JSS file.

• In the JSM file, define all strings used for comparison or for identification as constants, and use only those string names in the JSS file.

• In the JSM file, add a comment for string names whose meaning is not obvious, explaining to translators where to find the text those string names represent in the comparison, or where to use those string names for identification in the program.

• In the JSM file, define all window names and classes as constants, and use only those constants in the JSS file.

• In the JSM file, define all string variables that are messages consisting of a specific formatted pattern such that each variable uses a variable placeholder in the formatted message. Then use the FormatString() or SayFormattedMessage() functions in the JSS file to format the message.

• In the JSM file, document all replaceable parameters for each message that has them with comments explaining what information goes into the replaceable parameters.

• Name all defined constants and variables for windows or controls so that they are self-documenting in order that a scripter or localizer can recognize the location of the window or control.

  • If it belongs to a dialog, include the dialog name as part of the constant or variable name.

  • If it belongs to a page in a multi-page dialog, include the page name as part of the constant or variable name.

  • If it does not belong to a dialog, name the constant or variable so that the scripter or localizer can determine to which view or component of the program the window or control belongs.

• Create different constant or variable names for windows or controls that have the same names but appear in more than one area or in unrelated areas of the program. In this way, windows or controls each have their own constant or variable names that refer specifically to where they are used.

• In the JSD documentation file, document all your functions and scripts. Take care to document well the synopsis, description, and any parameters or return types for each function and script. For scripts in particular, Be sure that the text of the Synopsis and Description fields is appropriate to be spoken and displayed in Braille by the JAWS Keyboard Help feature.

• Do not attach the spacebar or any alphanumeric keys to scripts. If special behavior is required for these keys, use the KeyPressedEvent function instead of attaching scripts to the keys.

• Use the SayString function only as a debugging tool during scripting, and do not use this function to speak anything in the finished product.

• Do not use braces like "{" and "}" to simulate keystrokes. Use the TypeKey() or TypeCurrentScriptKey() functions when sending a keystroke to the application.

• Structure your code so that it tests and executes in the most expedient manner possible. When adding code to frequently-run events, be especially careful not to introduce unnecessary sluggishness.

• Use window or object information as opposed to screen information where possible.

• Use the JAWS or Invisible Cursor to obtain information only when no other method works. In this case, always use the Invisible Cursor unless the JAWS Cursor is required to perform the action because the Invisible Cursor cannot. If it is necessary to use the JAWS or Invisible Cursor, store the location of the PC Cursor prior to activating the JAWS or Invisible Cursor, or prior to calling a function that activates either of these cursors. Then take care to re-activate the PC Cursor at the stored location as soon as the desired action is completed with the JAWS or Invisible Cursor.

  As of JAWS 2020, you might instead choose to use the UIA Scan Cursors. See the functions related to these cursors available for JAWS 2020 and later. Generally speaking, the same rules apply to the use of these cursors as to the traditional JAWS and Invisible Cursors. There are several methods to work with these cursors. The addition of the JAWS Scan Cursor and Invisible Scan Cursor was because the standard Off-Screen Model (OSM) used by JAWS and Invisible cursors has been largely replaced by what is called User Interface Automation (UIA) to present screen content. This made the JAWS and Invisible cursors less effective in many applications (e.g., when activating the cursoes in applictions the program would return "blank" instead of informative speech.). The UIA Scan Cursors work with the UIA model to provide better access to screen content in many applications.

• Never use the SpeechOff() and SpeechOn() functions as a means of suppressing speech output temporarily. If you must suppress speech for specific purposes, use a specific global variable for the specific suppression.

• Always respect the active cursor when defining behavior in a script or function. Do not break the functionality of the JAWS, Invisible Cursor, or the UIA Scan Cursors.

• When designing your code, always consider whether the desired JAWS behavior should honor the status of the user buffer or the menu state as special or exception cases.

• When designing your code, always respect the user's speech output configuration, and always honor speech and sound scheme functionality for controls and for text properties.

• Keep all global variables up to date. If you overwrite a function that has global variables, be sure to update the necessary variables before returning from that function.

• Overwrite for the specific circumstance when overwriting the behavior of an existing function or script. Then call the default function or script for all other circumstances. Wherever possible, avoid copying the entire default function or script to your script file and then adding exception cases. Doing so renders your code obsolete if the default code changes. Always use the same name for your function or script as the name of the default function or script.

• Use event-driven code where appropriate. For instance, in lists or trees where first-letter navigation is possible, make sure that any code for outputting speech during navigation uses appropriate event-driven code such as the SayHighlightedText() function (called by the NewTextEvent() function), the ActiveItemChangedEvent() or ValueChangedEvent() function instead of key-driven code like the SayNextLine() or SayPriorLine() scripts.

• When designing your code for overwriting the functionality of a keystroke native to the application, evaluate whether the keystroke should be passed through to the application if the special testing conditions in your code are not met. In the JSM file, define the key name to be passed through as a constant with a meaningful name that explains the keystroke's functionality. For example: Do not use ksAltI; rather, use ksIgnoreButton since the hotkey for the button may vary from language to language.

• If overwriting the functionality of a key combination already defined in the default JKM file, do not make any entry in the application-specific JKM file for the key combination.

• In JAWS hotkey help, include all new non-application and non-standard Windows key maps for all keys added to the JKM file.

• Ensure that the ScriptFileName() function outputs relevant information for the current application and script file.

• Do not output any special messages for scripts attached to native Windows keystrokes.

• Ensure that the appropriate information (Application window information, real window information, and focus window information) is spoken when focus changes. Eliminate any double-speaking, and ensure that only relevant changes are spoken.

• Ensure that the SayWindowPromptAndText() function speaks the same information about the focus window that was spoken when the window gained focus. In addition, toggle on training mode temporarily for the SayWindowPromptAndText() function when speaking the focus window so that training information is spoken as appropriate.

• When designing help messages to be shown in the virtual viewer, place a statement at the top of the virtual viewer telling the user the current location. If showing a list of commands for a key layer, show what key should be pressed to start the layer. If showing a list of commands and their associated keystrokes, make each command in the list a link. Then for each command link, describe the command first, and then show the keystroke. Show any more general information in paragraph form without any links. Always end each virtual help screen with a message telling the user how to close the virtual viewer. This message need not be a link.

• When scripting for special behavior, script both for speech and for Braille behaviors.

• On controls where the position in group information is available, make sure that the position in the group is announced when focus moves to the control. Also, ensure that your special conditions cause the SayWindowPromptAndText() and SayLine() functions to announce the position in group. However, also ensure that JAWS does not announce the position in group when moving between the items in the group. JAWS should announce position in group information for controls such as lists, combo boxes, and radio buttons. For treeviews, along with position in group information, JAWS should also announce level and state information. Ensure that JAWS announces and displays in Braille the position, level and open/close state changes of treeview items as they are navigated.

Additional Guidelines for Writing Acceptable Scripting Code

Following are some additional guidelines for writing and formatting code so that it can be most easily maintained. Anyone looking at your code in the future (including yourself) will thank you for following these guidelines when writing your code.

Write self-documenting code by using meaningful script, function, variable and constant names. Self-documenting code is much easier to understand, maintain and debug.

Modularize code so that your scripts or functions do not become large and unwieldy. It is much more time-efficient to maintain and debug modular, smaller scripts and functions than to step through a large section of code line-by-line.

Capitalize script, function, variable and constant names so that JAWS speaks them in a recognizable manner. This is best accomplished either by capitalizing the individual "words" of the name, or by using underscore ("_") to separate the component "words" of the name.

In this document we favor using Pascal Case, which is Capitalizing each word making up a variable name. I find this the easiest to remember and the most readable. However, there are other acceptable formats for naming variables. The following table lists some of the most common formats for naming variables. The table also provides examples of each format.

Naming Scheme Description Example Common Use

Snake Case Snail Case Pothole Case Use underscore "_" to separate words; all lowercase var_name_in_snake_case Python (PEP 8 functions/variables)Rust (functions/variables)Ruby (methods/locals)Elixir (functions/variables)C (functions, varies)SQL schemas Kebab Case Lisp Case dash-case Use hyphens "-" between words; all lowercase var-name-in-kebab-case CSS properties/classesHTML data attributesURLs/filenamesnpm package names Camel Case Dromedary Case Lower camel case: first word lowercase, subsequent words capitalized varNameInCamelCase Java (methods/variables)JavaScript/TypeScript (functions/variables)C#SwiftKotlin,Dart (methods/variables) Pascal Case Upper Camel Case Each word capitalized; no separators VarNameInPascalCase Class/type names across most languages; public members in .NET (C#)modules in Elixir Flat case No separators; all lowercase varnameinflatcase Rare; sometimes short identifiers or legacy contexts Camel Snake Case Combination of camelCase and snake_case var_Name_In_Camel_Snake_Case Not standard; appears in mixed-style codebases or auto-generated code Pascal Snake Case Title Case Pascal-cased words separated by underscores Var_Name_In_Pascal_Snake_Case Niche; sometimes database/codegen conventions Macro Case Constant Case Screaming Snake Case Uppercase words with underscores; typically for constants/macros VAR_NAME_IN_MACRO_CASE C/C++ macrosconstants in PythonRustJava (static final)KotlinRuby environment variables COBOL Case Screaming Kebab Case Kebab case but ALL CAPS VAR-NAME-IN-COBOL-CASE COBOL identifiers and legacy systems Train Case HTTP Header Case Title-cased words separated by hyphens Var-Name-In-Train-Case Documentation headingsdesign systemssome HTTP headers and config keys

: Multiple-word Identifier Formats For Variables

When defining local variables, place "Var" on a line by itself at the left margin, and then place each succeeding local variable on a line by itself indented one tab stop. All varaibles except the final one in the list need to be followed by a comma. This makes the variable list easy to read quickly and to modify if items need to be added or deleted.

Var
    String sFirstVariable, ; first String variable followed by a comma
    Int iSecondVariable,   ; second integer variable followed by a comma
    Object oThirdVariable, ; third Object variable without a comma
    Handle hThirdVariable  ; final Handle variable without a comma

Place all level-0 statements at the left margin, and indent once using tab (not spaces) for each level. Line up the matching components of If-ElIf-Else-EndIf statements and of While-EndWhile statements. When an If or While statement contains compound conditions, place each condition on a line by itself. Line up the operator for each line of the compound test with the If, the ElIf, the Else, and the Endif, or the While-Endwhile statement. Following this convention makes it easy to find code blocks displayed in Braille and by using the JAWS indentation announcement capabilities.

; This is pseudocode, Not an actual JAWS Script
    While IsAppActive(appName)
    And (iteration < maxIterations)
  And (Not UserPressedKey("ESC"))

        SetFocusToForegroundWindow()

    While HasFocusChangedRecently(announceIntervalMs)
      And (GetObjectClass(GetFocus()) = "Edit")
      And (IsTextSelectable(GetFocus()))

      If (IsSelectionNonEmpty(GetFocus()))
        And (IsControlVisible(GetFocus()))
        And (Not IsControlProtected(GetFocus()))
        SayString("Selected text detected.")
                SayHighlightedText(GetFocus())
      ElseIf (IsCaretOnLineStart(GetFocus()))
        And (IsLineNonEmpty(GetFocus()))
        SayString("Line start. Reading line.")
                SayCurrentLine(GetFocus())
      Else
        SayString("Reading word under caret.")
                SayCurrentWord(GetFocus())
            EndIf

      If (IsDialog(GetForegroundWindow()))
        And (HasDefaultButton(GetForegroundWindow()))
        SayString("Dialog detected. Default button is " + GetDefaultButtonName(GetForegroundWindow()))
            EndIf

      If (UserPressedKey("CTRL+H"))
        And (IsHelpAvailable(appName))
        SayString("Opening Script help For " + appName)
        SayString(GetScriptDescription("FocusMonitor"))
        OpenHelpTopic("FocusMonitor")
            EndIf
        EndWhile

    If (UserPressedKey("CTRL+F"))
        And (GetObjectClass(GetFocus()) = "Edit")
        And (IsTextSearchable(GetFocus()))
        SayString("Find requested. Prompting For search term.")
        PromptUserForText("Enter search term:", "SearchTerm")
        If (SearchText(GetFocus(), GetVariable("SearchTerm")))
          SayString("Found: " + GetVariable("SearchTerm"))
                SayCurrentLine(GetFocus())
      Else
        SayString("Not found: " + GetVariable("SearchTerm"))
            EndIf
        EndIf

        iteration = iteration + 1
EndWhile

SayString("Focus monitor stopped.")

Comment your code judiciously. If the code itself is self-documenting¹, comments are unnecessary. However, if you are coding in a specific manner or employing a technique whose purpose may not be readily apparent simply by reading the code, then comments are critical. Remember that your code and comments may be read by anyone. So please keep the comments professional and appropriate for all readers.

; FocusMonitor.jss -- Monitors focus changes and announces relevant text
; Author: 
; Purpose: Demonstrate comment guidelines with JAWS Scripting conventions
; Notes: Comments Use semicolons. Only non-obvious techniques are documented.
SayString("Starting focus monitor For " + appName)

While IsAppActive(appName)
    And (iteration < maxIterations)
    And (Not UserPressedKey("ESC"))

        SetFocusToForegroundWindow()

        ; Technique: Throttle announcements using a "recent change" window
        ; Reason: Prevents rapid, repetitive speech when focus flickers
        While HasFocusChangedRecently(announceIntervalMs)
            And (GetObjectClass(GetFocus()) = "Edit")
            And (IsTextSelectable(GetFocus()))

            ; Strategy: Prioritize what To read (selection \textrightarrow line \textrightarrow word)
            If (IsSelectionNonEmpty(GetFocus()))
                And (IsControlVisible(GetFocus()))
                And (Not IsControlProtected(GetFocus()))
                SayString("Selected text.")
                SayHighlightedText(GetFocus())
            ElseIf (IsCaretOnLineStart(GetFocus()))
                And (IsLineNonEmpty(GetFocus()))
                SayString("Line start.")
                SayCurrentLine(GetFocus())
            Else
                SayCurrentWord(GetFocus())
            EndIf

            ; Context hint: If a dialog is present, announce default action
            If (IsDialog(GetForegroundWindow()))
                And (HasDefaultButton(GetForegroundWindow()))
                SayString("Default: " + GetDefaultButtonName(GetForegroundWindow()))
            EndIf
        EndWhile

        ; Non-obvious UX: inline help On CTRL+H To reduce cognitive load
        If (UserPressedKey("CTRL+H"))
          And (IsHelpAvailable(appName))
          SayString(GetScriptDescription("FocusMonitor"))
          OpenHelpTopic("FocusMonitor")
        EndIf

        ; Avoid unbounded loops
        iteration \textleftarrow iteration + 1
EndWhile

SayString("Focus monitor stopped.")

Naming Conventions for Variables and Constants

Use a standard and consistent method for naming variables and constants. The Freedom Scientific scripting code adheres mostly to the following naming conventions for notating types of variables and constants.

Precede handle variable names with "h", string variable names with "s", integer variable names with "i" and object variable names with "o".

Precede global variable names with "g". For example, a global integer variable name is preceded with "gi".

When naming constants, precede window names with "wn", and window classes with "wc".

When defining messages to be spoken, precede the name with "msg"; use "sc" as a prefix to constant strings defined for on-screen comparison.

This method is called Hungarian Notation. Using this notation makes it easier to identify the type of variable or constant being used in the code.

Definition:

: Hungarian Notation is a naming convention for variables where each name is prefixed with a short code (called a type tag) that indicates the variable's type or intended use. For example:

> strName (string), iCount (integer), oBuffer (object), bIsReady (boolean)

Purpose:

: This convention was introduced by Charles Simonyi at Microsoft during early Windows development. Its goals were:

1.  **Improve readability in weakly typed languages:** Early C and C++ lacked strong type checking and IDE hints. Prefixes helped developers quickly identify data types.

2.  **Reduce type-related bugs:** Seeing iCount vs. strName made accidental misuse less likely.

3.  **Aid maintainability in large codebases:** Prefixes allowed developers to scan code without jumping to declarations.

Variants:

: - Systems Hungarian: Prefix indicates the actual data type (e.g., i, o, str).

- **Apps Hungarian:** Prefix indicates semantic meaning or intended use (e.g., rwFileName for read/write filename, usPrice for U.S. dollars).

Why it is less common today:

: Modern languages (C#, Java, Python) provide strong typing, IDE support, and type inference, making Hungarian Notation largely unnecessary. Most style guides now recommend descriptive names instead (e.g., customerCount instead of iCustomerCount).

Criticism:

: - Can clutter names and reduce readability.

- Brittle when types change (e.g., iCount becomes a float).

- Adds cognitive overhead for new developers.

Modern Alternative:

: Use clear, descriptive names that explain the variable's purpose².

Here is an example of a script that uses Hungarian Notation for its variable names, along with proper formatting and comments as described in the previous sections.

; Script: FocusAnnouncer.jss
; Purpose: Demonstrate Hungarian-style prefixes + JAWS scripting conventions with judicious comments
; Notes: Comments use semicolons. Tabs for indentation. Aligned If/ElseIf/Else/EndIf and While/EndWhile.

Var 
    Int iMaxIterations,      ; maximum number of iterations to prevent infinite loops
    Int iIteration,         ; current iteration counter
    Int iAnnounceIntervalMs, ; interval in milliseconds to throttle announcements
    String strTargetApp,    ; target application name to monitor
    Bool bEnabled,          ; flag to enable/disable the announcer
    Object oFocusObj        ; reference to the current focus object

Let iMaxIterations = 100
Let iIteration = 0
Let iAnnounceIntervalMs = 1200
Let strTargetApp = "Notepad"
Let bEnabled = TRUE
Let oFocusObj = NULL

SayString("Focus announcer starting for " + strTargetApp)

While bEnabled
    And (IsAppActive(strTargetApp))
    And (iIteration < iMaxIterations)

        ; Obtain the current focus object (handle-like reference).
        ; Rationale: Centralize acquisition to avoid stale references.
        pFocusObj \textleftarrow GetFocus()

        ; Throttle announcements so rapid focus flicker doesn't overwhelm speech.
        While HasFocusChangedRecently(iAnnounceIntervalMs)
            And (IsTextSelectable(pFocusObj))
            And (GetObjectClass(pFocusObj) = "Edit")

            ; Read priority: selection \textrightarrow line \textrightarrow word.
            If (IsSelectionNonEmpty(pFocusObj))
                And (IsControlVisible(pFocusObj))
                And (Not IsControlProtected(pFocusObj))
                SayString("Selection.")
                SayHighlightedText(pFocusObj)
            ElseIf (IsCaretOnLineStart(pFocusObj))
                And (IsLineNonEmpty(pFocusObj))
                SayString("Line start.")
                SayCurrentLine(pFocusObj)
            Else
                SayCurrentWord(pFocusObj)
            EndIf

            ; Surface contextual default action when a dialog is foreground.
            If (IsDialog(GetForegroundWindow()))
                And (HasDefaultButton(GetForegroundWindow()))
                Initialize strDefaultBtn \textleftarrow GetDefaultButtonName(GetForegroundWindow())
                SayString("Default: " + strDefaultBtn)
            EndIf
        EndWhile

        ; Inline help reduces cognitive load for discoverability.
        If (UserPressedKey("CTRL+H"))
          And (IsHelpAvailable(strTargetApp))
          SayString(GetScriptDescription("FocusAnnouncer"))
          OpenHelpTopic("FocusAnnouncer")
        EndIf

        ; Allow graceful exit.
        If (UserPressedKey("ESC"))
          SayString("Focus announcer stopping.")
            bEnabled \textleftarrow FALSE
        EndIf

        iIteration = iIteration + 1
EndWhile

Be consistent with your convention, and choose a meaningful convention if an appropriate one does not already exist. Using this type of notation makes it easier to know instantly what type of variable is being used without having to look back at the declaration list in JSH or JSM files.

Compiling JSS Files with SCompile.exe

Set Up For Visual Studio Code/VSCodium

Why

I typically code outside of the Script Manager. I do my JAWS Script writing using VSCode, Positron, Theia, or Zed, which is comonly used by coders and programmers for python, R, Java, C#, TypeScript, JavaScript, and other development respectively[^1]¹. I also prefer NVDA as my daily screenreader, so I want to make sure that I can compile my scripts in a way that is maximally accessible to me.

To accomplish this, I use a round-about way to control my terminal outputs to increase screenreader accessibility and ease of browsing Errors.

I create a task in VSCode using a .JSON file². This will call a powershell .ps1 script or else a Command Prompt Batch (.bat) file that contains my actual commands. VSCode submits to the shell script the path of the file I currently have open, which is the one targeted to be compiled.

For this chapter, if you prefer Powershell in your terminal, follow the relavant instructions. If you prefer Command Prompt, follow the instructions for that.

Setup

To set up using SCompile, the following information is needed:

• File path to scompile.exe (typically C:\Program Files\Freedom Scientific\JAWS[year]\scompile.exe).

• VSCode, VSCodium, Code OSS, Positron, Theia, Mr. Code, or another compatible editor.

• Administrator Rights for running VSCode (Otherwise VSCode cannot run scompile.exe in an Elevated (Admin) terminal)

  OR

• A win-sudo or gsudo installation to allow Elevated Terminal Privileges (preferred)

To run scompile as administrator, one of the following need to be performed. One can also do both, but it is redundant.

1. To Open VSCode with Admin rights

   • When on the icon for VSCode, press ALT + ENTER to open Propertie

   • Navigate to "Compatibility" tab

   • Select "Run this Program as Administrator"

   Now when you open the program, and Administrator prompt will appear and all actions in the terminal will be run with Admin rights.

2. To install gsudo or win-sudo

   • In command prompt or powershell, type "winget install gsudo" or "winget install win-sudo" and follow the prompts

   Now when you open the program, you can type "gsudo" or "win-sudo" in the terminal before the command you want to run with Admin rights.

The steps to setting up a Task to run the necessary commands, the following steps need to be followed in order:

1. Press ALT, then T for Terminal

2. Press C for Configure Task

3. Press DOWN ARROW to "Create tasks.json file from template"

4. Press DOWN ARROW to "Others" and press ENTER

The resulting .JSON file looks like this³:

{
    "version": "2.0.0",
        "tasks": [
            {
            "label" : "echo",
            "type": "shell",
            "command": "echo Hello"
            }
        ]
}

Copy and paste the appropriate data into the appropriate sections and add an "args" section so the tasks.json looks like this if you open VSCode:

1. Use with Powershell

   {
       "version": "2.0.0",
       "tasks": [
           {
               "label": "compile",
               "type": "shell",
               "command": "pwsh",
               "args": [
                   "-File",
                   "workspaceFolder/compile.ps1",
                   "file"
               ],
               "group": {
                   "kind": "build",
                   "isDefault": True
               },
               "problemMatcher": {
               "owner": "custom",
               "fileLocation": ["absolute"],
               "pattern": {
                   "regexp": "^file (.*), line (\d + ), column (\d + ): Error: (.*)\$",
                   "file": 1,
                   "line": 2,
                   "column": 3,
                   "message": 4
                   }
               },
               "presentation": {
                   "reveal": "always",
                   "clear": True,
                   "showReuseMessage": False,
                   "echoCommand": False
               }
           }
       ]
   }
   

   Now create the following file in your User scripts directory (typically "C:\Users\AppData\Roaming\Freedom Scientific\JAWS[year]\Settings\enu"):

   Name the file "compile.ps1".

   The full path for the file is now "C:\Users[user]\AppData\Roaming\Freedom Scientific\JAWS[year]\Settings\enu\compile.ps1"

   • Option 1: VSCode launches with Admin rights.

     param (
         [String]\$filePath
     )
     If (-Not filePath) {
         Write-Error "No file path provided."
         exit 1
     }
     # Run the compiler and capture the output
     \$output = & "`C:\Program` Files\Freedom Scientific\JAWS\2024\scompile.exe" \$filePath 2>&1
     # Print the compiler output
     \$output
     # Check the exit status of the compiler
     If (\$LASTEXITCODE -eq 0) {
         Write-Output "\$filePath Compiled Successfully"
     } else {
         # Print the exit message
         Write-Output "The terminal process terminated with exit code: 1."
     
         # Print the error message again
         \$output -match "Error.*" | ForEach-Object { Write-Output \$_ }
     }
     

   • Option 2 (preferred): Run in an elevated Terminal prompt

     param (
         [String]\$filePath
     )
     If (-Not filePath) {
         Write-Error "No file path provided."
         exit 1
     }
     # Run the compiler and capture the output
     \$output = & sudo "C:\Program Files\Freedom Scientific\JAWS\2024\scompile.exe" \$filePath 2>&1
     # Print the compiler output
     \$output
     # Check the exit status of the compiler
     If (\$LASTEXITCODE -eq 0) {
         Write-Output "\$filePath Compiled Successfully"
     } else {
         # Print the exit message
         Write-Output "The terminal process terminated with exit code: 1."
     
         # Print the error message again
         \$output -match "Error.*" | ForEach-Object { Write-Output \$_ }
     }
     

2. Use with Command Prompt

   Create the following file in your User scripts directory (typically "C:\Users\AppData\Roaming\Freedom Scientific\JAWS[year]\Settings\enu"):

   Name the file "compile.bat".

   The full path for the file is now "C:\Users[user]\AppData\Roaming\Freedom Scientific\JAWS[year]\Settings\enu\compile.bat"

   {
       "version": "2.0.0",
       "tasks": [
           {
               "label": "compile",
               "type": "shell",
               "command": "pwsh",
               "args": [
                   "-File",
                   "\${workspaceFolder"/compile.ps1},
                   "\${file"}
               ],
               "group": {
                   "kind": "build",
                   "isDefault": True
               },
               "problemMatcher": {
               "owner": "custom",
               "fileLocation": ["absolute"],
               "pattern": {
                   "regexp": "^file (.*), line (\d + ), column (\d + ): Error: (.*)\$",
                   "file": 1,
                   "line": 2,
                   "column": 3,
                   "message": 4
                   }
               },
               "presentation": {
                   "reveal": "always",
                   "clear": True,
                   "showReuseMessage": False,
                   "echoCommand": False
               }
           }
       ]
   }
   

   • Option 1: VSCode launches with Admin rights.

     @echo Off
     setlocal
     set "filePath=%~1"
     If "%filePath%"==" " (
         echo No file path provided.
         exit /b 1
     )
     rem Run the compiler and capture the output
     "`C:\Program` Files\Freedom Scientific\JAWS\2024\scompile.exe" "%filePath%" 2>&1
     rem Check the exit status of the compiler
     If %errorlevel% equ 0 (
         echo %filePath% Compiled Successfully
     ) else (
         rem Print the exit message
         echo The terminal process terminated with exit code: %errorlevel%.
         rem Print the error message again
         For /f "tokens=* delims=" %%i in ('"`C:\Program` Files\Freedom Scientific\JAWS\2024\scompile.exe" "%filePath%" 2^>^&1 ^| findstr /r "Error.*"') do echo %%i
         )
     

   • Option 2 (preferred): Run in an elevated Command Prompt

     @echo Off
     setlocal
     set "filePath=%~1"
     If "%filePath%"==" " (
         echo No file path provided.
         exit /b 1
     )
     rem Run the compiler and capture the output
     sudo "C:\Program Files\Freedom Scientific\JAWS\2024\scompile.exe" "%filePath%" 2>&1
     rem Check the exit status of the compiler
     If %errorlevel% equ 0 (
         echo %filePath% Compiled Successfully
     ) else (
         rem Print the exit message
         echo The terminal process terminated with exit code: %errorlevel%.
         rem Print the error message again
         For /f "tokens=* delims=" %%i in ('"C:\Program Files\Freedom Scientific\JAWS\2024\scompile.exe" "%filePath%" 2^>^&1 ^| findstr /r "Error.*"') do echo %%i
     )
     

To speed up the keystrokes necessary to get to the Run Task dialog (currently 4 keystrokes at least), we can assign a keystroke to the Run Task command directly.

• Press CONTROL + K,release the K while keeping the CONTROL button down, and press K again

• "Tasks: Run Task" into the form field and press \

• Press DOWN ARROW to Run Task, it is the second one down. You are now placed in a form field labelled "Press desired key combination and then press ENTER"

• Press the desired shortcut combination and press ENTER. The program tells you if you are using a repeated keystroke. I used CONTROL + ALT + ; since it was not already being used.

Now you can press CONTROL + ALT + ; (semicolon) then just hit ENTER since scompile is the top run task available. It will bring up a drop down with output scanning options.

This will open a terminal on the bottom of the screen --either Powershell or Command Prompt depending upon your selected preferences -- and run the task of compiling the .jss file. If successful, the terminal output states

::: leftbar C:\ProgramData\Freedom Scientific\JAWS[year]\Scripts\enu[script.jss] Compiled Successfully :::

If there is an error, the following will be output to the terminal:

::: leftbar Compiling C:\ProgramData\Freedom Scientific\JAWS[year]\Scripts\enu[script.jss]

file C:\Users[user]\AppData\Roaming\Freedom Scientific\JAWS[year]\Settings\enu[script.jss], line XX, column XX: Error: Unexpected word XX

The terminal process terminated with exit code 1

file C:\Users[user]\AppData\Roaming\Freedom Scientific\JAWS[year]\Settings\enu[script.jss], line XX, column XX: Error: Unexpected word XX :::

If you press CONTROL + SHIFT + M and access the Problems tab, the top entry will be this:

::: leftbar Unexpected word XX [Ln XX, Col XX] :::

When you highlight the Error, the cursor for the editor moves to the line with the error and highlights it. Pressing F6 a few times moves the editing cusor there. Or else you can just use the line and column of the error to get to it

VS Code-Based Code Editors Summary

Given the popularity of Visual Studio Code and its open-source core Code-OSS, many editors and IDEs have been built on top of, or are compatible with, the VS Code base. The table below summarizes some of the notable editors and IDEs in this ecosystem, highlighting their relationship to VS Code, form factors, and key notes. My focus on these editors over others is the fact that accessibility tools work out of the box with them, making them suitable for JAWS scripting without a large amount of additional configuration. I am providing this list and diagram as a resource to alllow you to choose your preferred editor while still being able to follow along with the instructions in this book.

graph TD
    subgraph core["🔵 Core"]
        codeoss["Code-OSS<br/>(VS Code Open Source core)"]
        rawbuild["Code-OSS<br/>(raw builds)"]
    end
    
    subgraph forks["🟢 Forks / Distributions"]
        vscode["Visual Studio Code"]
        vscodium["VSCodium"]
        cursor["Cursor"]
        positron["Positron"]
        mrcode["MrCode"]
    end
    
    subgraph servers["🟠 Server / Browser"]
        openvscode["OpenVSCode Server"]
        codeserver["code-server"]
    end
    
    subgraph clouds["🟡 Cloud / Web IDEs"]
        codespaces["GitHub Codespaces"]
        vscodeweb["VS Code for the Web<br/>(vscode.dev)"]
        gitlabide["GitLab Web IDE"]
        gwork["Google Cloud<br/>Workstations"]
        gitpod["Gitpod"]
        sapbas["SAP Business<br/>Application Studio"]
        awsce["AWS SageMaker<br/>Code Editor"]
        coder["Coder platform"]
    end
    
    subgraph theia["🟣 VS Code-compatible"]
        theia_fw["Eclipse Theia<br/>Framework"]
        theiaide["Theia IDE"]
        theia_gen["Theia Yeoman<br/>Generator<br/>(custom IDEs,<br/>Embedded, IoT,<br/>Enterprise, Cloud,<br/>Education)"]
        che["Eclipse Che"]
        codeeditor["Code Editor<br/>(Oracle)"]
        smartface["SmartFace"]
        css["Code Composer<br/>Studio"]
        arduino["Arduino IDE 2.0"]
    end
    
    %% Forks from Code-OSS (solid arrows)
    codeoss --> vscode
    codeoss --> vscodium
    codeoss --> cursor
    codeoss --> mrcode
    codeoss --> rawbuild
    codeoss --> positron
    
    %% Servers from Code-OSS (solid arrows)
    codeoss --> openvscode
    codeoss --> codeserver
    
    %% Cloud services from Code-OSS (solid arrows)
    codeoss --> codespaces
    codeoss --> vscodeweb
    codeoss --> gitlabide
    codeoss --> gwork
    
    %% Cloud services from OpenVSCode Server (solid arrows)
    openvscode --> gitpod
    openvscode --> sapbas
    openvscode --> awsce
    
    %% Cloud services from code-server (solid arrows)
    codeserver --> coder
    
    %% Connection to Theia ecosystem (dashed for compatibility)
    codeoss -.->|compatibility| theia_fw
    
    %% Theia relationships (solid arrows)
    theia_fw --> che
    theia_fw --> theiaide
    theia_fw --> theia_gen
    theia_fw --> codeeditor
    
    theia_gen --> css
    theia_gen --> arduino
    theia_gen --> smartface
    
    %% Styling
    classDef coreStyle fill:#ADD8E6,stroke:#000,stroke-width:2px
    classDef forkStyle fill:#90EE90,stroke:#000,stroke-width:2px
    classDef serverStyle fill:#FFB347,stroke:#000,stroke-width:2px
    classDef cloudStyle fill:#FFFF99,stroke:#000,stroke-width:2px
    classDef compatStyle fill:#DDA0DD,stroke:#000,stroke-width:2px
    
    class codeoss,rawbuild coreStyle
    class vscode,vscodium,cursor,positron,mrcode forkStyle
    class openvscode,codeserver serverStyle
    class codespaces,vscodeweb,gitlabide,gwork,gitpod,sapbas,awsce,coder cloudStyle
    class theia_fw,theiaide,theia_gen,che,codeeditor,smartface,css,arduino compatStyle

The above information is from these sources:

{{#cite ms-code-oss-github}}

{{#cite ms-vscode-site}}

{{#cite vscodium-site}}

{{#cite archwiki-vscode}}

{{#cite positron-migrate-vscode}}

{{#cite posit-blog-positron-guides}}

{{#cite codecademy-cursor-guide}}

{{#cite vibe-coding-cursor}}

{{#cite gitpod-openvscode-github}}

{{#cite devclass-openvscode}}

{{#cite coder-code-server-github}}

{{#cite coder-code-server-docs}}

{{#cite stackblitz-webcontainers-post}}

{{#cite maiertech-codeflow}}

{{#cite eclipsesource-theia-vs-vscode}}

{{#cite theia-language-support}}

{{#cite che-theia-github}}

{{#cite eclipsesource-che-vs-codespaces}}

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.

The Keyboard Manager

Introduction to the Keyboard Manager

You use the Keyboard Manager to control the assignment of keystrokes to JAWS screen reading activities. The Keyboard Manager stores keystroke assignments in key map files with the extension of .jkm.

There are two types of key map files:

• Default

• Application

The default key map file contains the keystroke assignments for the default scripts. Application key map files contain keystroke assignments for scripts in an application script file. JAWS stores key map files in the JAWS settings directory.

Starting the Keyboard Manager

When running an application, press JAWSKEY + F2 to open the Run JAWS Manager dialog, followed by K, and ENTER. When you start the Keyboard Manager from within an application, the Keyboard Manager automatically opens the key map file for that application, if one exists. Otherwise, the Keyboard Manager opens the default key map file, default.jkm. When you start the Keyboard Manager from the Utilities menu within the JAWS interface, the default key map file is opened.

Using the Keyboard Manager

As will be seen later, you usually assign keystrokes to scripts at the time you create the script using the Script Manager. You can use the Keyboard Manager to browse and change current keystroke assignments, as well as add and delete keystroke assignments.

The Keyboard Manager has a similar screen layout to Windows Explorer. It consists of two panes.

• Left pane

• Right pane

The left pane contains a list of all current application specific and the default key map files in alphabetic order. The right pane contains a list of scripts in the script file associated with the current key map file.

The list is organized in four columns:

• Script name

• Keystroke

• Key map file name

• Key map section

Use the ARROW KEYS to select one of the key map files in the left pane and then TAB to the right pane and use the ARROW KEYS to select a specific script. You can add a keystroke assignment to the laptop, desktop, Kinesis keyboard layout or all keyboard layouts. When you add keystrokes to a specific keyboard layout, the keystroke assignment does not appear when the keyboard layout is changed. When you do not assign a keystroke to a specific keyboard layout, then the Keyboard Manager displays "common" in the key map section column.

::: {#add-change-or-delete-a-keystroke}

Add, Change, or Delete a Keystroke

:::

After you locate the proper script, use the Action menu to Add, Change, or Remove the keystroke assigned to this script.

::: {#find-a-keystroke}

Find a Keystroke

:::

To search for a specific keystroke in the current key map file, move to the Scripts List in the right pane, choose Find Keystroke from the Action menu, press the keystroke you wish to find, and press ENTER. If the keystroke exists, the Keyboard Manager selects the script name assigned to this keystroke. If the Keyboard Manager does not find the keystroke, then the Keystroke Not found dialog is displayed.

::: {#review-documentation-for-a-keystroke}

Review Documentation for a Keystroke

:::

When assigning a keystroke to a script, it is often useful to browse the script documentation first. The script documentation consists of the Synopsis (brief description of the script's purpose) and the Description (additional information about the script). You can view the documentation for the current script by choosing Documentation from the Action menu or by pressing ENTER while the script name in the list is selected.

::: {#changing-keyboard-manager-options}

Changing Keyboard Manager Options

:::

There are five groups of optional settings that change how the Keyboard Manager displays its information. All of these options are contained in one multi-page dialog. Choose any of the five groups from the Options menu to open that page of the Options multi-page dialog. Once you open the dialog, you can move to each page by pressing CONTROL + TAB.

The Options multi page dialog contains the following pages:

• Key Filter

• Sort

• Hot key

• Messages

• File Filter

Use the Key Filter page of the Options multi-page dialog to decide which key assignments and scripts to display in the scripts list. Use the Sort page of the Options Multi-page dialog to decide which column of the script list the Keyboard Manager uses to sort the list. Use the Hot Key page of the Options multi-page dialog to choose keys you can use in a hot key edit box. Use the Messages page of the Options multi-page dialog to choose messages used by the Keyboard Manager. Use the File Filter page to decide where the Keyboard Manager should look for key map files to display.

::: {#key-filter-options}

Key Filter Options

:::

The Keyboard Manager has two key filter settings:

• Key Assignments

• Scripts

Each filter option has three radio buttons.

• All

• Active

• Application

::: {#key-assignments-group}

Key Assignments Group

:::

Option Description All Displays all keystroke assignments in both the current key map file and the default key map file. Active Displays only active keystroke assignments in both the current key map file and the default key map file. If a keystroke is assigned in both the application and default key map files, only the application keystroke is active as JAWS always acts on the first keystroke it finds and it looks in the application key map file first. This setting filters out duplicate keystrokes in the default key map file. Application Displays only key assignments in the current key map file.

: Key Assignments Group

::: {#scripts-group}

Scripts Group

:::

Option Description All Displays all scripts. Assigned to Keys Displays only scripts assigned to keystrokes. Unassigned Displays only scripts not assigned to keystrokes.

: Script Groups

::: {#sort-options}

Sort Options

:::

The Sort page has four radio buttons that allow you to sort the key map file by a specific column.

• Script Name

• Keystroke

• Key Map File

• Key Map Section

Choose the radio button that corresponds to the column you would like to use as the sort column for the Scripts List in the right pane.

::: {#hot-key-options}

Hot Key Options

:::

The Keyboard Manager has four checkboxes on the Hot Keys page of the Options multi-page dialog that correspond to: TAB, SHIFT + TAB, ENTER, and ESCAPE. Check each one you want to use as a hot key. These keys are usually used to navigate in dialog boxes. For example, pressing TAB usually moves focus to the next control. That prevents it from being assigned to a script.

If you would like to assign TAB to a script, follow these steps:

1. Choose Hot Key from the Options menu, check the Tab checkbox, and press ENTER.

2. Select a specific script and choose either Add Keystroke or Change Keystroke from the Action menu.

3. The Assign To: edit box is active in either the Add Keystroke or Change Keystroke dialog, press TAB, and ENTER.

::: {#messages-options}

Messages Options

:::

There is only one checkbox on the Messages page of the Options multi-page dialog. Check the Show notification messages when about to modify a file checkbox to have Keyboard Manager notify you before modifying a key map file.

::: {#file-filter-options}

File Filter Options

:::

The File Filter page has three radio buttons that allow you to indicate which set of key map files JAWS should display in the eyboard Manager:

• Active Files

• User Files

• Shared Files

When you select the Active Files radio button, all key map files currently in use are displayed. If both a shared and user version of the same key map file exist, only the user-specific file is displayed. When you select the User Files radio button, only those key map files found in your user settings folder are displayed. These keystrokes override those in the shared key map files. When you select the Shared Files radio button, only those key map files found in the shared settings folder are displayed.

The Keyboard Manager Exercises

The following exercises give you practice in using many of the functions of the Keyboard Manager. The objective of the exercise is listed first.

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.

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.

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.

1. Press WINDOWSKEY + M to minimize all of your running applications.

2. Start Notepad from the start menu. You can find the Notepad application in your Programs | Accessories group within your Start Menu.

3. After Notepad starts make sure it is the active application by pressing JAWSKEY + T. You should hear JAWS speak "Untitled - Notepad".

4. 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?

5. Press ESC to close the Adjust JAWS Options dialog and return to Notepad.

6. Press WINDOWSKEY + M to minimize all of your running applications and make the Desktop active.

7. Press I until you locate the Internet Explorer icon on your desktop. When you find the icon, press ENTER to start Internet Explorer.

8. Press JAWSKEY + T to read the title of the active window. Internet Explorer should be the active application.

9. 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

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

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

The Script Manager

::: {#overview-of-the-script-manager}

Overview of the Script Manager

:::

The JAWS Script Manager is an application that makes it easier for a JAWS user or developer to write scripts. The Script Manager Looks just like any other Windows application, i.e. it incorporates menus, common keystrokes and various features, such as "find", "find and replace" and "go to". Script Manager also has a status bar which displays such things as the number of lines in your script file.

The fastest way to open the Script Manager is by following these steps:

• Start any program, like Microsoft Word or Microsoft Internet Explorer;

• Press JAWSKEY + 0 (on a number row).

JAWS will open the Script Manager application and load a certain file into it. The file that will automatically open is a script file (or script) for the Internet Explorer application.

Another way to open Script Manager is by pressing JAWSKEY + F2, then arrowing down to the "Script Manager" option and pressing ENTER.

If you briefly scroll through the content of the file, you will notice that it has a lot of different statements. Don't worry about their meaning at this point.

The script file consists of one or more scripts or functions. Each script or function consists of one or more statements. A script is a section of the script file that will do something when a user presses a shortcut key assigned to that script by a JAWS script programmer. A function, on the other hand, is a section of the script file that consists of one or more statement, but does not require a shortcut key in order to be executed. Instead, a function uses parameters and return values to communicate with the JAWS program.

::: {#scripts-versus-functions}

Scripts Versus Functions

:::

How do we differentiate between scripts and functions? The scripts are surrounded by the following statements:

Script MyScript ()
; Some statements here
EndScript

When writing your code, you can include comments. In fact, including commented text is very helpful particularly if you wish to refresh your memory at a later date when changing your scripts or when collaborating on scripting projects with other people. To include commented text, after typing each line of code type a semi-colon character (";"), then type the text for the comment. In the sample code, you will see some commented text.

Functions, on the other hand, use the following syntax:

Function MyFunction (Parameter1, Parameter2, Parameter3)
; Some statements here
EndFunction

Please note that Parameter1, Parameter2 and Parameter3 are optional. In other words, functions do not always need parameters in order to do something useful.

You can easily move between scripts and functions that are stored in a currently-opened script file by using F2 and SHIFT + F2 keystrokes. Press F2 to move forward through the scripts and functions; press SHIFT + F2 to move backwards. Notice that JAWS will announce the name of the script or of the function as you move through them. Unfortunately, JAWS does not automatically announce whether you are on a script or on a function. You will need to check for this yourself by using SayCurrentLine key or some other reading keystrokes.

Other useful commands in the Script Manager are:

• To display documentation for your script or function (under the cursor), press CONTROL + D once the cursor is on the first line of the script or function.

• To display information about a certain JAWS keyword, such as name of the function, place your cursor at the beginning of the keyword and press SHIFT + F1.

• Press CONTROL + F to search for a string of text

• Press CONTROL + G to jump to a line number

• Press CONTROL + H to find and replace one text string with another

• Press CONTROL + ALT + I to incrementally search the file for a text string.

The last keystroke mentioned is a particularly interesting feature of JAWS Script Manager. It allows you to search for a text string by automatically advancing the cursor through the file as you type. Press CONTROL + ALT + I and type the word "function". You will notice that JAWS composes the match string while you type. This is yet another great way to look for text within Script Manager.

Other useful commands, like inserting a function and deleting a script, you will find in the "help topics" for Script Manager.

Please practice opening script files for various programs, such as Microsoft Word, Microsoft Internet Explorer, Outlook Express etc, and start using the mentioned shortcut keys in your scripting tasks.

The following is a brief overview of each menu found in the Script Manager. Only items that are unique to the Script Manager or perform unusual functions are described. Other standard Windows® menu options are noted as "standard function" The shortcut keys for applicable commands are also listed.

::: {#file-menu}

File Menu

:::

::: {#tblr:table4-1} Menu Item Keystroke Description

New CONTROL + N Standard Function Open CONTROL + O This is a standard function. However, you can only open those files that reside in the user settings folder with this command. Open User File None Use this command to open a file that resides in the user settings folder. Open Shared File None Use this command to open a file that resides in the shared settings folder. Open Default File CONTROL + SHIFT + D Use this command to open the default JAWS script file, Default.jss. Close CONTROL + F4 Standard Function Save CONTROL + S This command saves the file, but also compiles and saves a binary .jsb version if you are saving a .jss file. Save As None Standard Function Save As User None Use this command to save and compile a file in the user settings folder. Save As Shared None Use this command to save and compile a file in the shared settings folder. Save Without Compile CONTROL + W This command saves any file, but will not compile a saved .jss file. Synchronize Documentation None Use this command to make sure the script and documentation files concur. Also, when pasting in scripts from another .jss file, this feature copies documentation into the related JSD file. Print CONTROL + P Standard Function Print Preview None Standard Function Print Setup None Standard Function Listing of previously opened files 1,2,3,4 ... This portion of the File menu will list in chronological order approximately four of the Most recently accessed files. Exit ALT + F4

: File Menu --- Script Manager file-menu commands and associated keystrokes and behaviors :::

::: {#edit-menu}

Edit Menu

:::

Most commands in the Edit menu are standard, except for the following:

::: {#tblr:table4-2} Menu Item Keystroke Description

Select Script CONTROL + R Use this command to select the entire script in which the cursor is located. Find CONTROL + F This command opens the Find dialog. Use this dialog to find a text string. Find Next F3 This command is used with the Find dialog and the Incremental Search feature. This command will find the next occurrence of the text string entered in the Find dialog, or, the incremental search feature. Find Prior SHIFT + F3 This command is used with the Find dialog and the Incremental Search feature. This command will find the previous occurrence of the text string entered in either the Find dialog or the incremental search feature. Replace CONTROL + H This command opens the Replace dialog. Use this dialog to find and replace a string of text in the open script file. Incremental Search ALT + CONTROL + I Use Incremental Search to quickly search through a script for a specific string of text. Similar to the Find feature, Incremental Search allows you to incrementally update your search string by allowing you to add letters one at a time.

: Edit Menu --- editing commands in Script Manager including find/replace and incremental search :::

::: {#script-menu}

Script Menu

:::

::: {#tblr:table4-3} Menu Item Keystroke Description

New Script CONTROL + E Use this command to open the New Script dialog for creating a new script or user-defined function. Delete Script CONTROL + DEL Use this command to delete the script where the Insertion point is located. Insert Function Call CONTROL + I Use this command to open the Insert Function dialog where you can add a function to your script. Insert Perform Script CONTROL + SHIFT + I Use this command to open the Insert Perform Script dialog for calling another script. This is similar to calling a function, but it calls another script instead. Next Script F2 Use this command to move the Insertion point to the beginning of the next script in the file. Prior Script SHIFT + F2 Use this command to move the Insertion point to the beginning of the current script or to the beginning of the prior script, depending on the location of the insertion point. Go To Line CONTROL + G Use this command to open the Go To Line dialog where you can enter the line number of the line to which you wish to jump. This command moves the caret to the specified line number. Line numbers are shown in the Script Manager Status Bar. Script List CONTROL + L Use this command to open the Script List dialog where the scripts and user-defined functions in the current file are listed in alphabetical order. Pressing enter on a script name takes you to that script.

: Script Menu --- script creation, insertion, and navigation commands :::

::: {#view-menu}

View Menu

:::

::: {#tblr:table4-4} Menu Item Keystroke Description

Documentation CONTROL + D This command opens the Script Information dialog that contains all of the documentation for the current script. Toolbar NONE Standard function Status Bar NONE Standard function Display Full Path NONE This option is checked if you want to display the full directory path of the script in the edit window of the Script Manager Title Bar. If a new file is opened in the edit window, the Title Bar displays "Untitled". Zoom NONE This command opens the Zoom dialog where you can choose the amount of screen information you want displayed. For example, selecting 200% would magnify the screen two times its normal appearance. Tab Sizes NONE This command opens a submenu containing a list of tab settings from which you can choose the indent distance between tabs in your script.

: View Menu --- display options and developer view features (documentation, toolbar, zoom, tab sizes) :::

::: {#window-menu}

Window Menu

:::

All items in the Window menu perform standard functions.

::: {#help-menu}

Help Menu

:::

::: {#tblr:table4-5} Menu Item Keystroke Description

Help Topics NONE This option opens the list of help topics for Script Manager. Keyword Help SHIFT + F1 Choosing this command presents help information for the script or function on which the cursor is located.

: Help Menu --- access Script Manager help topics and keyword help :::

::: {#the-new-script-dialog}

The New Script Dialog

:::

You can open the New Script dialog using either the New Script item in the Script menu, or, by pressing CONTROL + E. You can open the Script Information dialog using either the Documentation item found in the View menu, or by pressing CONTROL + D. These two dialogs are actually the same, except that the Script Manager displays the New Script dialog when you first create a script, while the Script Manager displays the Script Information dialog when you wish to review documentation for an existing script. We will discuss using the New Script dialog here. However, the information is the same for both.

The New Script dialog is a multi-page dialog and consists of the following two pages:

• General

• Parameters

Each is described below. You can press CONTROL + TAB to move between pages.

::: {#general-page}

General Page

:::

The entries in the General page are as follows:

::: {#script-name}

Script Name

:::

You enter the name of your script or function in this edit box. It is helpful to use a name that is descriptive of what action the script performs. You may use several words concatenated together. For example, in MySampleScript, start each word with a capital letter so JAWS will pronounce the name as separate words.

Press the SPACEBAR to check this check box when you want to create a script. If not, you will create a function. Remember that scripts can be attached to keys but functions cannot.

::: {#synopsis}

Synopsis

:::

Type a brief statement of what the script does in this edit box. The synopsis provides valuable information to you and other users when Keyboard help (JAWSKEY + 1) or Key Word help (SHIFT + F1) is accessed. To hear the synopsis, press JAWSKEY + 1 using the 1 on the number row, not the keypad. JAWS says "keyboard help on". Next, press the keystroke combination that calls your script. Keyboard help should say the information placed in the synopsis edit box. You can leave keyboard help mode by pressing JAWSKEY + 1 a second time.

::: {#description}

Description

:::

Enter a more detailed explanation of the action the script performs in this edit box. JAWS speaks the description when you enter Keyboard help (JAWSKEY + 1) or Key Word help(SHIFT + F1) in the Script Manager. The description is accessed by quickly pressing the key combination that calls your script twice after turning Keyboard Help on.

::: {#category}

Category

:::

Although an entry in this edit combo box is not required, you can type in a category name or choose one from the drop down combo box. When you select a category, the Script Manager adds the category to the script documentation file (.jsd). You can use the category to quickly locate all scripts and functions that are of the same category.

::: {#assign-to}

Assign To

:::

This edit box is only available if you checked the Can Be Attached to Key check box. Press the keystroke combination you wish to use for your script. For example, to enter CONTROL + ALT + Z, press and hold the CONTROL and ALT keys while pressing the Z key. If the choice you make is already assigned to another script, the Script Manager displays a warning message, at which time you can continue with the assignment or choose a different keystroke combination.

::: {#function-returns}

Function Returns

:::

This edit combo box is only available if you did not check the Can Be Attached to Key check box. You can type in a Return type or choose one from the drop-down combo box. Among the choices are Handle, Int, Object, String, or Void. Select the type of return that your function is designed to return to the calling script. Select Void if you do not need to use any value returned by the function. The return type appears on the first line of the function before the key word, Function.

::: {#return-description}

Return Description

:::

This edit box is only available if you did not check the Can Be Attached to Key check box. Enter a brief description of the information that is being returned by the function and how the information is to be used. After entering all the necessary information for your new script or function, you can either press CONTROL + TAB to move to the parameters page of this multi-page dialog and enter any parameters for your new function or press ENTER to close the New Script dialog and return to the main Script Manager edit window to begin writing your new script or function.

::: {#parameters-page}

Parameters Page

:::

This page contains information about parameters used by the function. A parameter is data that the function needs in order to accomplish its work. As with variables, the data can be in the form of an Integer, String, Handle, or Object. You will only use the Parameter page when you are creating a function. It is also never used if the function needs no parameters.

::: {#existing-parameters}

Existing Parameters

:::

If parameters already exist for this function, this list box displays them. It will also show parameters as you add them. You can use the arrow keys to select a parameter for subsequent deletion.

::: {#new-parameter}

New Parameter

:::

If you wish to add a parameter, type its name in this field. Follow the same naming conventions you would for naming a new script: start each word with a capital letter and no spaces.

::: {#by-reference}

By Reference

:::

Check this check box to allow a two-way exchange of information from the calling script to the function. Normally, this data transfer is in one direction. This process is known as passing the parameter "by value". In other words, when you call the function from the script, the current value of the parameter is copied and sent to the function. In this situation, once the parameter exchange takes place, if the value of the parameter changes, the script would not be aware of the change. When you check the By Reference check box, a two-way exchange of information takes place. In this situation, the data's memory address passes rather than the value.

::: {#description-1}

Description

:::

Type a brief description of the parameter in this edit box.

::: {#available-types}

Available Types

:::

You should choose Handle, Int, Object, or String from this list box, depending on which type of information this parameter is meant to contain. For example, Handle refers to a window handle.

::: {#add}

Add

:::

Once you have completed the preceding fields, the Add button becomes available. Press SPACEBAR to activate this button to add your new parameter to the Existing Parameters list box.

::: {#remove}

Remove

:::

This button is available if you have highlighted an entry in the Existing Parameters list box. Activating this button with SPACEBAR deletes the highlighted parameter from the list.

::: {#using-the-insert-function-dialog}

Using the Insert Function Dialog

:::

Under the Script menu there are two selections: Insert Function Call and Insert PerformScript. You use These commands to insert functions and to call other scripts from within a script. The Insert Function Call is described below. Use the following steps to Insert a function into your script:

With your script open, choose Insert Function in the Script menu, or press CONTROL + I. This displays the Insert Function dialog. The dialog lists over one thousand functions you can use when creating your scripts.

When the dialog opens JAWS speaks the title, "Insert Function 1". The term Function 1 means that you are at the first level of the dialog. The first field in the dialog is an edit box. If you happen to know the name of your function, you can start typing it in the edit box. The highlight in the alphabetical list automatically moves to the function whose name starts with the letters you type. As soon as you have typed in enough letters to hear the full name of the function for which you are searching, press ENTER to select the function.

If you do not know the name of the function, press TAB to locate the alphabetical list of all the available functions. Type in a few letters that you think might spell the name until you hear the name you want. You can then use the arrow keys to move to the exact function you want.

Press ALT + N to select a function. When you do, one of two things happens:

• If the function you selected does not require parameters, the Script Manager inserts the function into your script and you will return to the main Script Manager editing window.

• If the function requires one or more parameters, then JAWS displays a second dialog (Insert Function 1 dialog) and describes the type of parameter that is needed.

For example, if you choose SayAs () as a function, you will need to enter the text or message you wish spoken, specify a variable name, or insert a function.

If you want to insert another function as the parameter for the function you are adding to your script, TAB to the Insert Function button and press SPACEBAR or ALT + I. The Script Manager displays the Insert Function 2 dialog. The only difference between this list and the main list of functions is that only functions the Script Manager thinks are appropriate choices for this parameter are included.

You must either choose a function from this list or type the function name directly into the parameter edit field when it first appears. Press ENTER when you have finished.

Continue with this process until all of the required parameters have been entered. Sometimes you will need to go to a third or higher level; for example, "Insert Function 3", "Insert Function 4", and so on by pressing ALT + I again.

::: {#using-the-insert-performscript-dialog}

Using the Insert PerformScript Dialog

:::

You can use the Insert PerformScript command to add a line to your script that calls another script. Choose Insert PerformScript in the Script menu, or press CONTROL + SHIFT + I. The Script Manager displays the Insert PerformScript dialog with the cursor placed in a list box that contains all of the available scripts you can call from the script you are writing.

You can select one of these scripts by either using the ARROW KEYS to go through the list of suggested scripts until you locate the script you wish to use, or, by typing the name of the script until JAWS locates it.

Once the correct script has been located, press ENTER on its name. For example, if you selected a script called "SayName" the Script Manager inserts the line shown below:

::: center

PerformScript SayName ()

:::

This line causes the script "SayName" to be executed when your script is run, just as if you had pressed the keystroke yourself. This is one way scripts are reused by other scripts without reproducing the code all over again.

The Script Manager Exercises

The following exercises give you practice in using many of the functions of the Script Manager. The objective of the exercise is listed first.

Manipulating Cursors

The cursors used by JAWS are not as important for a regular user of the screen reader, but they are of a great importance for any JAWS Script writer as they add a lot of flexibility to what we can do with the information presented on and off the screen.

There are four cursors used by JAWS:

• PC Cursor -- a cursor that is synchronized with the physical cursor and keyboard navigation of an active application;

• JAWS Cursor -- a cursor that simulates mouse navigation, including mouse clicks, scrolling and by-pixel movements;

• Invisible Cursor -- very similar to JAWS Cursor, however, does not support mouse actions, such as clicks (single and double clicks);

• Virtual PC Cursor -- a cursor that is primarily used in HTML documents (such as in Internet Explorer).

It is crucial to be aware of the differences between these four cursors during scripting, because they behave differently and may provide you with different information every time you use them. Let's look at each of the cursors one by one.

::: {#pc-cursor}

PC Cursor

:::

When the PC Cursor is active, it will allow you to navigate only within the application window. For example, if you open Microsoft Word, you will only be able to use arrow keys, tab key and other keyboard keystrokes that are supported by Microsoft Word. You will not be able to view the information that is not directly accessible through keyboard, like ruler, toolbars or status line. Of course, you can review the status line with a JAWS keystroke (JAWSKEY + PAGE DOWN), but this is not a native Microsoft Word shortcut key and will not work if you close your screen reader.

Another good example is a window title. If you try to press UP ARROW within a Word Document, or any other application, you will never be able to get to the line that displays the title of the window. This is because applications do not give you direct keyboard access to that information, even though it is readily displayed on the screen. The JAWS keystroke JAWSKEY + T is only specific to JAWS and will not work if you shut down your screen reader.

::: {#jaws-cursor}

JAWS Cursor

:::

A JAWS Cursor, on the other hand, allows you to review the screen regardless of whether the application gives you keyboard access to the information on the screen or not. For example, if you switch to the JAWS cursor while in the Microsoft Word application and start using your arrow keys, you will notice that there is much more information available to you than before. You will find that you can now arrow up all the way to the top of the window and read the title of the application with your usual reading keystrokes (by word, by character etc).

The JAWS Cursor is very useful for JAWS scripters because it allows us to find more information about our application and apply it in our scripts. Let's say we wanted to have a keystroke to read the status line for our application. Our status line, however, is displayed two lines up from the bottom of an active window. We could have written something like this:

Script SpeakStatusLine()
Var
    String sStatusLine
SaveCursor()
JAWSCursor()
RouteJAWSToPC()
JAWSPageDown()
JAWSHome()
PriorLine()
PriorLine()
Let sStatusLine = GetLine()
Say (OT_STATUS, GetLine())
RestoreCursor()
EndScript

Assign your script to a keystroke of your choice and off you go!

You probably have questions about three functions that you have seen in this script: SaveCursor(), RestoreCursor() and RouteJAWSToPC(). The first two functions are especially important to remember because they allow you to tell JAWS to return the user to whatever cursor and location they were using before they switched to the JAWS Cursor. You cannot always assume that they were using PC Cursor before they turned on the JAWS Cursor, can you? SaveCursor(), therefore, tells JAWS to remember the active cursor and RestoreCursor() will return the users back to that cursor. It is always a good idea to use these functions in your scripts whenever you switch between various cursors. Usually you will use SaveCursor() immediately before activating a different cursor and RestoreCursor() once you completed your intended action.

::: {#restricting-jaws-cursor}

Restricting JAWS Cursor

:::

When sighted users review the screen with a mouse, they can position it anywhere on the screen and perform clicks at different points of it. The same can be achieved using the JAWS Cursor.

Because the screen can contain a lot of information from different windows, this could easily confuse a non-sighted person. To deal with this problem JAWS has a concept known as "cursor restrictions". With the JAWS Cursor or Invisible Cursor turned on, we can use JAWSKEY + R to toggle between:

• Application window restriction -- JAWS Cursor will only be allowed to move within the window of the active application;

• Current window restriction -- JAWS will only be allowed to move within the boundaries of a current window (note this can be different from an application window);

• Frame restriction -- the JAWS Cursor will only be allowed to move within the boundaries of the user-defined window/regions, called frames;

• Unrestricted -- the JAWS Cursor will be allowed to move anywhere on the screen, just like a physical mouse does.

When you script, it is useful that you make sure that your JAWS or Invisible Cursor is at the location where you want it to be. Otherwise, you may be clicking on the wrong button or reading wrong information. The quickest way to check whether your JAWS Cursor follows the PC Cursor is to use the function RouteJAWSToPC().

One last note on the JAWS Cursor. Please remember that when you move the JAWS Cursor in your scripts or with the arrow keys, the actual physical mouse pointer will also move on the screen. This concept will be more clear and make more sense when we discuss the Invisible Cursor below.

::: {#invisible-cursor}

Invisible Cursor

:::

The Invisible Cursor in many ways is identical to the JAWS Cursor. The major difference between the two is that the Invisible Cursor does not allow us to perform mouse clicks. However, all the other reviewing functionality of the JAWS Cursor is also applicable to an invisible cursor. We can also restrict the movements of the Invisible Cursor in exactly the same way we do with the JAWS Cursor (even the keystroke JAWSKEY + R is the same).

You may be wondering about the necessity of having both JAWS Cursor and Invisible Cursor since they act almost identically! Have you heard sighted people say that something changed on the screen as soon as they pointed their mouse at button or a picture? Did you know that some buttons or graphics change their color when the mouse pointer rests on them? Did you know that the shape of the mouse pointer itself can change if the application is doing something? Well, guess what! It can make our life difficult when we try to find the color of the graphic or even to label one for later use in our scripts. This is where Invisible Cursor can become useful.

Let's say that we have an application with a graphic that change its color or characteristics when a mouse pointer is moved over it. We would like to be able to label that graphic. If we use the JAWS Cursor to do this and label the graphic with a mouse pointer on it, JAWS may have problems recognizing that graphic later when the mouse pointer is not positioned on that graphic.

Here is the possible algorithm that we could use to make that graphic recognizable:

• Turn on the JAWS Cursor

• Move to the graphic that you would like to label or get an information about

• Get the information that you need (for example, retrieve the color of the graphic)

• Switch to Invisible Cursor

• Route Invisible Cursor to the JAWS Cursor

• Switch to JAWS Cursor and move your arrow key away from the graphic

• Switch back to Invisible Cursor and get the information about the graphic again (for example, retrieve its color)

• Compare the information that you've got before with the information that you obtained with Invisible Cursor and see if there are any differences.

The scenario can get even more complicated if your graphic will look differently after the user clicks on it with a single click or double click.

In basic terms, think of an Invisible Cursor as a copy of the JAWS cursor which is not displayed on the screen but can navigate just like a mouse pointer, but without an ability to perform mouse clicks. Also keep in mind that the JAWS Cursor will follow the movements of a physical mouse, whereas the Invisible Cursor will not.

::: {#virtual-pc-cursor}

Virtual PC Cursor

:::

The Virtual PC Cursor is completely independent of the screen and of any application. The idea behind this type of cursor is to enable JAWS to create its own navigation interface regardless of what is displayed on the screen. Two major examples of the applications where Virtual PC cursor is used are Internet Explorer and JAWS screen sensitive help. Whenever you press JAWSKEY + F1 to see the information about current application screen or shortcut keys, JAWS creates its internal area (known as the Virtual Viewer) that allows you to browse through the information as if you were viewing a regular web page. Try, for instance, to press JAWSKEY + F1 in Microsoft Word application or a document area, and you will find a lot of interesting and useful information about the currently-active document as well as some global settings for Microsoft Word. In addition, notice that in addition to regular text, JAWS is able to display links to other related information to make it look like you are browsing a web page.

::: {#summary}

Summary

:::

In this document we have discussed the four cursors that are available in JAWS: PC Cursor, JAWS Cursor, Invisible Cursor and Virtual PC Cursor. It is important that you understand the purpose of each of these cursors, because they behave differently from each other as well as provide different information about the application and the screen. When scripting, take extra care to make sure that you are in fact using the cursor that you intend to use, otherwise your scripts may report wrong information to the user. Remember to save the active cursor before you switch to a new one (using the SaveCursor() function), so that you can return the user to where they were before your script executed.

Creating Scripts to Read Information from the Screen

Now you know about the four cursors, let's discuss reading information directly from the screen.

You may find a variety of reasons for moving a cursor around a given window. Some applications contain buttons that are only accessible with the mouse or JAWS Cursor. These buttons usually cannot be reached by pressing TAB or through the menu system. You may also encounter applications that place blocks of text in areas of the screen that can only be read using the JAWS Cursor or Invisible Cursor.

Before you create any script that moves a cursor to read information, you should determine the outcome of the script. If you are trying to activate a button within an application window, use cursor movement keystrokes to move the JAWS Cursor or Invisible Cursor to the button. You should keep track of each keystroke you press as you move the appropriate cursor. Each cursor movement command you use has an equivalent built-in function. For example, the built-in function, NextLine, acts just like pressing the DOWN ARROW from your keyboard. It moves the active cursor down one line.

Instead of pressing JAWSKEY + PAGE DOWN to read the bottom line of the screen, use cursor movement commands instead. You can use the JAWS cursor to accomplish this task by following the steps below:

• Press NUMPAD MINUS (-) to activate the JAWS Cursor.

• Press JAWSKEY + NUMPAD MINUS (-) to route the JAWS Cursor to the location of the PC Cursor.

• Press PAGE DOWN to move the JAWS Cursor to the bottom of the window.

• Press JAWSKEY + UP ARROW to read the current line.

Now you know the steps needed to move the JAWS Cursor to and read the contents of the bottom line of the window. You can take these steps and use built-in functions to accomplish the same task.

You also need to think about which cursor you will use to read or access the information. Are you going to need mouse commands? Or will you only need to read the information? Use the JAWS Cursor when you will need to perform mouse commands such as left or right mouse clicking. Use the Invisible Cursor when you need to read information but do not need to perform mouse commands. You also need to remember not to leave the wrong cursor active when your script finishes. If you are using the invisible cursor to read information on the screen, you don't want to leave that cursor active when your script finishes. Instead, you want to make sure the cursor, which was active before the script is executed, is again activated when the script finishes.

Moving Cursors

After you activate a cursor you should save its location. This ensures that the cursor is restored to the correct position on the screen after your script is executed. For example, when you are using the JAWS Cursor to access a specific button within an application, you want it to stay there because you need to perform a left mouse click. If you write a script that moves the JAWS Cursor without saving it first, then you must move the JAWS Cursor back to the button after your script is finished. Failing to do this within your script results in the wrong cursor activated and in the wrong place.

When you have chosen to use either the JAWS Cursor or Invisible Cursor, you also need to move the cursor to the active application window. This action ensures the cursor you are using to read specific information is in the correct window. This is important as the JAWS Cursor and Invisible Cursor can be anywhere on your screen. So it is always a good idea to move these cursors to the active application. Otherwise, moving the cursor may yield unexpected results.

Saving the Cursor

You use the SaveCursor () built-in function to save the cursor and its location. The SaveCursor () function notes the active cursor and its present location. You can call this function after activating any of the cursors such as the JAWS Cursor. The following block of code illustrates the use of the SaveCursor () function:

JAWSCursor () ; activate the JAWS Cursor
SaveCursor () ; save the JAWS Cursor and its location

You can call the SaveCursor function multiple times in a script, after each cursor you activate. This is called "stacking saved cursors." The following code example illustrates the use of multiple SaveCursor () function calls:

JAWSCursor () ; activate the JAWS Cursor
SaveCursor () ; save the JAWS Cursor and its location
InvisibleCursor () ; activate the Invisible Cursor
SaveCursor () ; save the Invisible Cursor and its location

::: {#restoring-saved-cursors}

Restoring Saved Cursors

:::

After you perform your script and JAWS finds one or more saved cursors, JAWS restores them automatically. When you save multiple cursors, JAWS restores the cursors in reverse order.

You can also use the RestoreCursor () built-in function when you need to restore a specific cursor before your script finishes. This function is useful when you need to save a cursor first, perform an action with that cursor, and restore it before the script finishes.

The following code example illustrates the use of the RestoreCursor () function:

PCCursor () ; activate the PC Cursor
SaveCursor () ; save the PC Cursor
JAWSCursor () ; activate the JAWS Cursor
SaveCursor () ; save the JAWS Cursor
; reading statements go here
RestoreCursor () ; restore the JAWS Cursor

In the above example, the RestoreCursor () function restores the last saved cursor. In this case, the RestoreCursor () function restores the JAWS Cursor since it was the last cursor saved.

Routing the Cursors

The PC Cursor is generally the active cursor in most applications. When you need to access information outside of the boundaries of the PC Cursor, you need to route either the JAWS Cursor or Invisible Cursor to the location of the PC Cursor. When you route either cursor, you have a starting point that you know exists within the active application.

::: {#routing-the-jaws-cursor}

Routing the JAWS Cursor

:::

You use the built-in function, RouteJAWSToPC to move the JAWS Cursor to the location of the PC Cursor. This function repositions the JAWS Cursor to the exact position of the PC Cursor. This function also moves the mouse pointer to the location of the insertion point or selection highlight.

However, this function does not activate the JAWS Cursor. Any cursor movement functions used in your script will move the active cursor instead of the JAWS Cursor. If you want the JAWS Cursor to move you must activate it first. The following code example illustrates the use of the RouteJAWSToPC function:

JAWSCursor ()
SaveCursor ()
RouteJAWSToPC ()

In the above example, the JAWS Cursor is first activated and then saved. The RouteJAWSToPC function moves the JAWS Cursor from its current location to the location of the PC Cursor. At this point, you can use some of the cursor movement functions to move the JAWS Cursor.

::: {#routing-the-invisible-cursor}

Routing the Invisible Cursor

:::

You use the built-in function, RouteInvisibleToPC (), to move the invisible cursor to the location of the PC Cursor. This function repositions the Invisible Cursor to the exact position of the PC Cursor. Unlike the JAWS cursor, the Invisible Cursor is not connected to the mouse pointer, so the function does not move the mouse pointer.

If you want to move the Invisible Cursor you must also activate it first. The following code example illustrates the use of the RouteInvisibleToPC () function:

InvisibleCursor ()
SaveCursor ()
RouteInvisibleToPC ()

In the above example, the Invisible Cursor is activated then saved. The RouteInvisibleToPC () function then moves the Invisible Cursor to the exact location of the PC Cursor. Now that the Invisible Cursor is in the active window, you can use cursor movement commands to read information contained within the current application window.

Moving the Cursor

After you have activated, saved, and moved the JAWS Cursor or Invisible Cursor to the active application window, you can move the cursor. Nearly all of the keyboard commands you use to move the various cursors within JAWS have corresponding built-in functions. For example, pressing DOWN ARROW to move the cursor to the next line has a comparable built-in function of NextLine (). Likewise, pressing RIGHT ARROW has a comparable built-in function of NextCharacter.

The JAWSPageDown and JAWSPageUp built-in functions perform special versions of their respective keyboard commands. You can use these functions when any of the cursors are active. However, the outcome of the function is based on the active cursor.

When the PC Cursor is active, each function performs the standard PAGE UP and PAGE DOWN commands for the application. For example, when you press PAGE DOWN from within a word processor, the PC Cursor is moved down a screen of information. Likewise, when you press PAGE UP from within a word processor, the PC Cursor is moved up one screen of information. The following code example illustrates the use of the JAWSPageDown () function using the PC Cursor:

PCCursor ()
SaveCursor ()
JAWSPageDown ()

In the above example, the PC Cursor is activated and then saved before it is moved. Next, the JAWSPageDown function moves the PC Cursor down one screen of information.

When the JAWS or Invisible Cursor is active, the JAWSPageDown () function moves the cursor to the bottom of the active window based on the cursor restriction setting. Likewise, the JAWSPageUp () function moves the JAWS or Invisible Cursor to the top of the active window based on the restriction setting. The following code example illustrates the use of the JAWSPageDown () function using the Invisible Cursor:

InvisibleCursor ()
SaveCursor ()
RouteInvisibleToPC ()
JAWSPageDown ()

In the above example, the Invisible Cursor is activated and then saved. Next, the RouteInvisibleToPC () function routes the Invisible Cursor to the location of the PC Cursor in the active window. Finally, the JAWSPageDown function moves the Invisible Cursor to the bottom of the active window.

The JAWSEnd and JAWSHome built-in functions perform special versions of their respective keyboard commands. Like the JAWSPageDown () and JAWSPageUp () functions, you can use these functions when the PC Cursor, JAWS Cursor, or Invisible Cursor is active. However, the outcome of each function is based on the active cursor.

When the PC Cursor is active, each function performs the standard END and HOME commands for the application. For example, when you press END from within a word processor, the PC Cursor is moved to the end of the current line. Likewise, when you press HOME from within a word processor, the PC Cursor is moved to the beginning of the current line. The following code example illustrates the use of the JAWSHome () function using the PC Cursor:

PCCursor ()
SaveCursor ()
JAWSPageDown ()
JAWSHome ()

In the above example, the PC Cursor is activated, saved, and moved down one screen. The JAWSHome () function then moves the cursor to the beginning of the line. When you execute this block of code, the PC Cursor is limited to the active window.

When either the JAWS or Invisible Cursor is active, the JAWSEnd function moves the cursor to the last text character or graphic on the line within the active window. Likewise, the JAWSHome () function moves the cursor to the first text character or graphic on the current line within the active window. The active window is based on the cursor restriction setting. The following code example illustrates the use of the JAWSHome () function using the Invisible Cursor:

InvisibleCursor ()
SaveCursor ()
RouteInvisibleToPC ()
JAWSPageDown ()
JAWSHome ()

In the above example, the Invisible Cursor is activated, saved, moved to the location of the PC Cursor and moved to the bottom of the screen. Next, the JAWSHome () function moves the Invisible Cursor to the beginning of the current line. By moving the Invisible Cursor to the beginning of the current line, you now have a distinct starting point. You can then use a number of other built-in movement functions to move the Invisible cursor across the line to read a specific piece of information such as a line number.

::: {#next-and-prior-cursor-movement}

Next and Prior Cursor Movement

:::

You can also use built-in functions to move to the next or prior piece of information. Many of these functions also have equivalent keyboard commands like the JAWSEnd (), JAWSHome (), JAWSPageDown (), and JAWSPageUp () functions.

You can use these functions with any of the three cursors. However, the outcome of the function is determined by the active cursor. For example, if you move the JAWS Cursor to the title bar of the active application, you can continually press JAWSKEY + RIGHT ARROW to move across the title bar a word or graphic at a time. When you continually press this keystroke, the JAWS Cursor does not stop at the end of the line. Rather, it continues to move on to the next line until you reach the bottom of the window.

On the other hand, you can only move the PC Cursor within the document edit area of a word processor when you continually press JAWSKEY + RIGHT ARROW. Once you reach the bottom of the document edit window, the PC Cursor can move no further.

InvisibleCursor ()
SaveCursor ()
RouteInvisibleToPC ()
JAWSPageDown ()
JAWSHome ()
NextWord ()

Reading Information with Scripts Exercises

These exercises give you some practice in creating scripts that read pieces of information.

Constants and Variables

Variables

A variable is an entity that holds a value that can change during script processing. Each variable is of a specific type. JAWS stores the value of a variable in memory and can be used by script code whenever needed. You must declare variables with a name and a type before they can be used. You must give each variable a distinct name to distinguish it from other functions and names used in the script or script file. Using duplicate variable names within scripts or script files will cause compile or execution problems.

You can declare variables either locally, or, globally. Variable types include: handle, integer, object, and string.

Variable Types

You can use one of four variable types within your scripts and functions. You store only one specific type of information in each of these variable types.

Variable types include:

• Integer

• String

• Handle

• Object

::: {#integer-variables}

Integer Variables

:::

You use the integer variable type to store an integer or whole number. A whole number does not contain a decimal point. The default value of an integer variable is always 0. You must declare an integer variable before it can be used. You declare an integer as follows:

Var
    Int iMyIntegerVariable

::: {#string-variables}

String Variables

:::

You use the string variable type to store a string of characters. A string is a group of characters including letters, numbers, punctuation marks, and spaces. When you assign a value to a string variable, you must enclose the string value in quotation marks. The default value of a string variable is always null or no characters. You can indicate the value of Null by two quotation marks with no space between them. You must declare a string variable before it can be used. You declare a string variable as follows:

Var
    String sMyStringVariable

::: {#handle-variables}

Handle Variables

:::

You use the Handle variable type to store a window handle. A window Handle is a unique number assigned by the system to each window in a currently running program. A Handle is also a whole number and can be manipulated like other integer variables. However, the use of a Handle variable is reserved solely for the identification of a window handle. The default value of a Handle variable is always zero. You must declare a Handle variable before it can be used. You declare a Handle variable as follows:

Var
    Handle hMyHandleVariable

::: {#object-variables}

Object Variables

:::

You use the object variable type to store an object. An object refers to the types of objects used within certain Microsoft® applications such as the Office suite. The default value of an object variable is always null or empty. You must declare an object variable before it can be used. You declare an object variable as follows:

Var
    Object oMyObjectVariable

Naming Variables

As you begin to use variables within your scripts, there are a few ways you can name them to easily identify their contents. When you use multiple words for variable names, be sure to capitalize each letter. This will make for better pronunciation of the variables by JAWS. It is also a good idea to give your variables meaningful names. Giving a string variable the name of "i" does not indicate the string information stored in the variable. You can also use Hungarian notation to name your variables.

Var
    Int iAverageTemperatureForUtahLastWeek ; Too long: hard to read and pronounce
    Int iT; Too short: meaningless, unclear purpose
    Int iTemp ; Pointless/generic name: doesn't convey intent or scope
    Int iMeanTemperature ; Good: type prefix + descriptive, concise purpose

Hungarian notation uses lower case letters at the beginning of variable names to indicate the variable type. For example, you could name a string variable that contains a window name sWindowName. The lower case "s" indicates the variable is of type string. The "WindowName" portion of the variable name indicates the variable will contain a window name. Some examples of variable names follow:

• iVersion ("i" for integer type)

• sCellText ("s" for string type)

• hRealWindow ("h" for Handle type)

• oDocument ("o" for object type)

Local Variables

You can declare variables locally within a script in the first statement after the Script start statement. You use the key word, Var, to indicate the start of the local variable declaration. Each variable declaration is placed on a separate line. When you declare multiple variables, you follow each variable name with a comma except for the last variable in the list.

An example of a local variable declaration follows:

Var
    Handle hWnd, ; stores window Handle
    Int iIsJavaWindow,
    Int iTheTypeCode,; window sub type code
    Int iMenuMode ; stores value of menu

Global Variables

You declare global variables at the beginning of a script file outside of any script or user-defined function. You place global variable declarations immediately following any include statements. You indicate the start of the global variable declaration with the key word, Globals. Each variable declaration is placed on a separate line. When you declare multiple global variables, you follow the name of each variable with a comma except for the last variable in the list.

A good idea is to add a comment at the end of the declaration stating how the variable is used. After you declare and assign a value to a global variable, that value remains in memory even after you close the application that uses it. If you start the application during the same computer session, the global variables from that application's script file retain the same values they had prior to the application being closed. You can initialize the values of global variables programmatically or by unloading and restarting JAWS.

An example of a global variable declaration follows:

Globals
    Handle GlobalPrevFocus, ; Handle of previous focus window
    Handle GlobalPrevReal, ; Handle of previous real window
    String GlobalPrevRealName, ; name of previous real window
    Handle GlobalPrevApp, ; Handle of previous application
    Handle GlobalFocusWindow, ; temp variable To pass a window

You can also declare global variables in a JAWS script header file. You give a header file the file extension of .jsh and create the file in the Script Manager. You can find an example of a header file containing global variable declarations in the HJGlobal.jsh header file. The HJGlobal file is included in the Default.jss script file. Including the HJGlobal.jsh header file in a default script file allows the global variables to be used in any of the default scripts and user-defined functions. When you include the HJGlobal.jsh file in an application-specific script file, you can use these variables to get specific information as needed. Care should be taken when using any global variables from the HJGlobal.jsh file. The default scripts and user-defined functions often modify the values contained in these variables and may produce unwanted results in your script file.

Assigning Values to Variables

You use the let statement to assign values to any one of the 4 variable types. For example, "Let iControl = 1500" assigns the value of 1500 to the variable, iControl. If you fail to use the let statement to assign a value to a variable, the script compiler will generate a syntax error.

Some examples of let statements follow:

Let sDialogPageName = GetDialogPageName ()
Let iCount = 1
Let sWindowName = "Options"
Let hWnd = GetFocus ()

Constants

Constants do not change value. 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 default JAWS constants file,HJConst.jsh, both of the constants True and On are assigned the value of one. This means 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. The use of constants is strongly recommended because its more difficult to remember that when something is true, its state is one, but easy to understand the difference between TRUE and FALSE. Moreover, when someone else is reading your script file, it's much easier for the person 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.

You declare constants at the beginning of a script file. You indicate the beginning of a constant declaration section with the key word, Const. When declaring multiple constants, each constant name must be followed by a comma except for the last constant in the list.

An example of a constant declaration follows:

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

You may decide to define your own constants for a script file. You may also use those that are already declared in HJConst.jsh. If you decide to use either file or both, you must remember to include the header file or files.

The Include and Use Statements

You use the Include statement to tell JAWS to include the contents of a header or message file in a script file when you compile that script source file (jss). When you compile the .jss file creating the binary file (.jsb), all of the information in the included files is compiled into the resulting .jsb file.

You must include the file name and extension of the file to be included and enclose the entire name in quotation marks.

An example of an include statement follows:

Include "HJConst.jsh" ; default JAWS constants

The statement above tells the compiler that the file called HJConst.jsh, is to be included as part of the current script file. The optional comment provides information about the file being included. The file to be included must be contained within the language (ENU) sub-folder of the shared or user Settings folder for the specific version of JAWS you are using.

The use statement creates a link between the named binary file and the script source file in which the use statement is contained. The main difference between the Use statement and include statement is that the Use statement does not add more code to the script binary file.

An example of a Use statement follows:

Use "utilities.jsb" ; utility functions

The file name, including file extension, to be used is enclosed in quotation marks. The statement tells the script compiler that the Utilities.jsb file is to be linked to the script file in which the use statement is contained. The comment provides information about the file being used. This comment is optional. The binary file to be used must be contained within the language (ENU) folder of either the shared or user settings folder for the version of JAWS you are using.

Flow Cotrol

graph TD
    subgraph SEQ["Sequential Process"]
        S1["Start"]
        S2["Step 1"]
        S3["Step 2"]
        S4["End"]
        S1 --> S2 --> S3 --> S4
    end
    
    subgraph IFTHEN["If-Then"]
        IF1{If}
        THEN1["Then"]
        ENDIF1["EndIf"]
        IF1 -->|Y| THEN1
        THEN1 --> ENDIF1
        IF1 -->|N| ENDIF1
    end
    
    subgraph IFELSE["If-Else"]
        IF2{If}
        THEN2["Then Do X"]
        ELSE2["Else"]
        THEN21["Then Do Y"]
        ENDIF2["EndIf"]
        IF2 -->|Y| THEN2
        IF2 -->|N| ELSE2
        ELSE2 --> THEN21
        THEN2 --> ENDIF2
        THEN21 --> ENDIF2
    end
    
    subgraph IFELIF["If-ElIf-Else"]
        IF3{If}
        ELIF1{ElIf}
        ELIF2{ElIf...}
        ELSE3["Else"]
        THENA["Then Do A"]
        THENB["Then Do B"]
        THENC["Then Do..."]
        THEND["Then Do Z"]
        ENDIF3["EndIf"]
        IF3 -->|Y| THENA
        IF3 -->|N| ELIF1
        ELIF1 -->|Y| THENB
        ELIF1 -->|N| ELIF2
        ELIF2 -->|Y| THENC
        ELIF2 -->|N| ELSE3
        ELSE3 --> THEND
        THENA --> ENDIF3
        THENB --> ENDIF3
        THENC --> ENDIF3
        THEND --> ENDIF3
    end
    
    subgraph WHILE["While Loop"]
        W1{While}
        D1["Do"]
        EW["EndWhile"]
        W1 -->|Y| D1
        D1 --> EW
        D1 -->|Loop Back| W1
        W1 -->|N| EW
    end

JAWS does not always perform scripts in a sequential or top to bottom manner, with each line being performed in order and only once. You may find it necessary to perform a series of statements several times within a script. You may also find it necessary to skip statements in a script based on the outcome of a condition being evaluated. These types of statements control the flow, or sequence of events, in a script or function. A script or function can contain any or all of these techniques.

Sequential

Sequential flow is the most basic type of flow control. In a sequential statement structure, JAWS performs each statement sequentially beginning with the first statement in the script and continuing to the EndScript statement.

The following script is an example of sequential flow. You can find this script in the Default.jss script file. The script selects text from the beginning of the line to the cursor. The code of the script follows:

Script SelectFromStartOfLine()
Let nSaySelectAfter = False
SelectingText(True)
SelectFromStartOfLine ()
SelectingText(False)
EndScript

JAWS performs the script above each time you press SHIFT + HOME to select the text from the cursor to the beginning of the line. JAWS performs each statement in the script only once.

Selection, Conditional, or Decision Making

In this type of statement structure, JAWS evaluates one or more conditions before processing continues. The flow of the script is then based on the outcome of the condition being evaluated. This process is often referred to as branching. Think of walking down a path and coming to a fork in that path. Before you continue, you must decide which path is the best way to continue. Your script can do the same thing. As JAWS processes your script sequentially, there may be a poInt in the script where a decision must be made. The statements JAWS processes next are based on the outcome of that decision.

::: {#the-if-then-statement}

The If Then Statement

:::

You can use the If Then statement structure to select which path in your script is taken if the preceding statement is true. You must include the If, Then, and EndIf key words in all If statement structures. You place the condition to be evaluated between the If and Then key words. When JAWS evaluates the condition and finds it to be true, JAWS performs any statements following the If statement.

An example of a basic If statement follows:

If DialogActive () == True Then
    SayFormattedMessage (OT_MESSAGE, "A dialog box is active") ; The condition evaluates To True
EndIf

In the above example, JAWS can only take one path based on the outcome of the condition being evaluated in the If statement. When a dialog box is active, then JAWS performs the SayFormattedMessage () function and speaks "A dialog box is active." When the condition being evaluated is false, then JAWS does not perform the SayFormattedMessage () function and processing continues with any statements that follow the EndIf key word.

::: {#the-else-and-elif-statements}

The Else and ElIf Statements

:::

You can use two optional statements in an If Then structure. You can use the Else key word to provide an alternate path. When the condition specified in the preceding If statement is found to be false, then JAWS performs the statements following the Else key word. Thus, you can account for both true and false conditions in your If statement. An example of an If Then-Else statement follows:

If DialogActive () == True Then
    SayFormattedMessage (OT_MESSAGE, "A dialog box is active") ; the condition evaluates To True
Else
    SayFormattedMessage (OT_MESSAGE, "No dialog box is active") ; the condition evaluates To False
EndIf

In the above example, the If statement determines if a dialog box is active. When the If statement is true, JAWS performs the SayFormattedMessage () function following the If statement and speaks "A dialog box is active." If a dialog box is not active, then JAWS performs the SayFormattedMessage () function following the Else key word and speaks "No dialog box is active."

You can use the ElIf statement as a secondary way of formulating a branch. The ElIf statement can take the place of an Else statement. You can also use the ElIf statement in addition to the Else key word. You can use as many ElIf statements as needed in your scripts. However, when you use the ElIf statement in addition to the Else key word, those ElIf statements must precede the Else statement.

Two examples of the uses of the ElIf statement within an

If Then-Else-EndIf statement follow:

If DialogActive () == True Then
    SayFormattedMessage (OT_MESSAGE, "A dialog box is active")
ElIf DialogActive () == False Then
    SayFormattedMessage (OT_MESSAGE, "No dialog box is active")
EndIf

The above example uses an ElIf statement in the place of the Else key word. The If statement determines if a dialog box is active. When the If statement is true, JAWS performs the SayFormattedMessage ()function following the If statement and speaks "A dialog box is active." When the If statement is false, JAWS performs the ElIf statement that determines if there is no active dialog box. If the ElIf statement is true, then JAWS performs the SayFormattedMessage ()function following the ElIf statement and speaks "No dialog box is active." Since there are only two possibilities, JAWS must perform either the SayFormattedMessage () statement that follows the If statement or the SayFormattedMessage () statement that follows the ElIf statement.

The following example illustrates the use of an ElIf statement in conjunction with an Else statement:

If DialogActive () == True Then
    SayFormattedMessage (OT_MESSAGE, "A dialog box is active")
ElIf MenusActive () == ACTIVE Then
    SayFormattedMessage (OT_MESSAGE, "A menu is active")
Else
    SayFormattedMessage (OT_MESSAGE, "No dialog box or menu is active")
EndIf

The above example uses an ELIF statement in addition to the Else key word in the If Then statement structure. The initial If statement determines if a dialog box is active. If a dialog box is active, then JAWS performs the SayFormattedMessage () function following the If statement and speaks "A dialog box is active." If a dialog box is not active, then JAWS performs the ELIF statement that determines if a menu is active. If the ELIF statement is true, JAWS performs the SayFormattedMessage () function following the ELIF statement and speaks "A menu is active." However, if no menu is found to be active, then JAWS performs the SayFormattedMessage () function following the Else key word and speaks "No dialog or menu is active."

::: {#nested-if-statements}

Nested If statements

:::

You can place or nest an If statement inside of another If statement. Nesting If statements allows you to check for a condition only when another condition exists. JAWS evaluates the nested If statement only when the first condition is true. JAWS performs the sequence of statements within the nested If Then statement only if both conditions are found to be true. An example of the use of nested If statements follows:

If DialogActive () Then ; determine If a dialog box is active
    Let sWindowName = GetWindowName (GetRealWindow (GetFocus ())); retrieve the window name For the active dialog
    If sWindowName == "Open" Then ; the Open file dialog is active
        SayFormattedMessage (OT_MESSAGE, "The Open File dialog is active")
    Else
        SayFormattedMessage (OT_MESSAGE, "A dialog box other than the Open File dialog is active.")
    EndIf
Else
    SayFormattedMessage (OT_MESSAGE, "No dialog box is active")
EndIf

In the above example, the first If statement determines if a dialog box is active or being displayed. When the If statement is true, JAWS performs the let statement and retrieves theinuing to the EndScript statement. window name for the active dialog. Next, the nested If statement uses the window name to determine if the Open File dialog is active. If the nested If statement is true, then JAWS performs the SayFormattedMessage () function following the nested If statement and speaks "The Open File dialog is active." If a dialog box other than the Open File dialog is active, then the nested If statement is false and JAWS performs the SayFormattedMessage () function following the else key word and speaks "A dialog other than the Open File dialog is active."

If JAWS determines no dialog box is active, then JAWS performs the SayFormattedMessage () function following the Else key word in the outer If statement following the Else key word and speaks "No dialog box is active."

Iterative or Looping

The third type of flow control you can use in your scripts is called iterative or looping. You use the iterative statement structure to perform the same statement or group of statements repeatedly while a condition is true. You use a loop to perform a sequence of statements several times, thus shortening the number of statements required. Looping provides a way to determine the number of repetitions automatically, depending on conclusions derived from script operation.

::: {#the-while-endwhile-statement-structure}

The While-EndWhile Statement Structure

:::

You perform looping in your scripts by using the While-Endwhile statements structure. A While Loop is a statement structure that repeats or loops WHILE a condition is true.

A While loop consists of two parts:

• The While statement which sets the condition to be tested for

• EndWhile statement that terminates the loop.

JAWS performs all statements within the boundaries of the While and EndWhile statements repeatedly until the condition in the While statement becomes false. An example of a While-EndWhile loop structure follows:

While Variable1 < 5 ; this condition will cause the loop To be performed 4 times
    ; Statements To be performed go here
    Let Variable1 = Variable1 + 1 ; increment the value of Variable1 by 1   with each step
EndWhile

In the above example, JAWS performs the While loop while Variable1 is less than 5. Once the value of Variable1 becomes equal to 5, the loop ends and no further processing occurs.

When you create an iterative flow sequence in a script using a While loop, care should be taken not to create an infinite loop that results in a locked computer. Since a loop continues until a condition becomes false, you must be certain that the condition being tested can actually become false. One way you can avoid this problem is to include statements designed to break the loop after a certain number of repetitions. An example of this follows:

Var
    Int iSafety
Let iSafety = 1
While iSafety < 10
    NextLine ()
    If GetLine () == "%1" Then
        Let iSafety = 10 ; cause the loop To terminate
    EndIf
    Let iSafety = iSafety + 1 ; increment the value of the iSafety variable
EndWhile

In the above example, JAWS performs the loop while the value of iSafety is less than 10. Each time JAWS performs the loop, JAWS performs the NextLin () function to move to the next line. The If statement determines if the text at the location of the active cursor is that of "Save As ..." When the If statement is found to be true, the iSafety is given the value of 10. This makes the While statement false and the loop terminates. When the If statement is false, then the value of iSafety is incremented by 1.

When the value of iSafety becomes equal to 10, JAWS terminates the loop as iSafety is no longer less than 10.

A second example of a while loop follows:

While (hPos); perform the While loop While the value of hPos is Not zero once the value of hPos becomes zero, Then the loop terminates
    ; While statement could also be written as While hPos! = 0
    If IsWindowVisible (hPos) Then ; determine If the window referenced by hPos is visible
        SpeakWindowInformation (hPos)
    EndIf
    Let hPos = GetNextWindow (hPos) ; retrieve the Handle For the next window
EndWhile

In the above example, JAWS performs the loop while the value of the handle variable, hPos, is not equal to zero. Within the loop, JAWS determines if the window referenced by hPos is visible. If the window is visible, then JAWS speaks information about the window. Next, the GetNextWindo () function retrieves the handle for the next window. If the GetNextWindo () function does not actually find a next window, then th () function places zero in the hPos variable. When the hPos variable contains zero, the condition being evaluated in the While statement is no longer true as the value of the variable is now zero. This terminates the While loop.

Compound Statements

You can create compound statements using both If Then-EndIf and While-EndWhile statement structures. A compound statement can determine if 2 conditions are both true. A compound statement may also determine if one of two conditions are true.

::: {#compound-statements-using-and}

Compound Statements Using AND

:::

When you join 2 statements together using the && operators, the statement is said to be a "and" compound statement. In this type of compound statement, both conditions must be true before the entire If Then or While statement are true. If either one of the conditions being evaluated is false, the entire If Then or While statement is then considered to be false. You use two & symbols to indicate a compound statement where both sides must be true. An example of the use of the && symbols in an If Then statement follow:

Let sWindowName = GetWindowName (GetRealWindow (GetFocus ())) ; retrieve the name of the active window
If DialogActive () && sWindowName == "%1" Then
    Say ("%1", OT_MESSAGE)
EndIf

In the above example, the compound If statement determines if the active dialog box is the Open File dialog. The first part of the If statement determines if a dialog box is active. The second part of the If statement determines if the name of the active dialog is that of the Open File dialog. If both conditions of the If statement are true, then JAWS performs the Say statement following the If statement and speaks "The Open File dialog is active."

When there is no active dialog, the first condition is false making the entire If statement false. Likewise, if the name of the active dialog is something other than that of "Open", then the second condition is false making the entire If statement false. In either case, JAWS does not perform the Say statement following the If statement.

::: {#compound-statements-using-or}

Compound Statements Using OR

:::

When two statements are joined together using the operators, the statement is said to be a "or" compound statement. In this type of compound statement, either condition can be true for the entire If Then or While statement to be true. However, both statements do not have to be true to make the entire If Then or While statement true.

You use the symbol to indicate a compound statement where either side must be true. An example of the use of the symbols in an If Then statement follow:

If iValue < 5 || iValue 10 Then
    Say ("%1", OT_MESSAGE)
EndIf

In the above statement, either sides of the can be true for the entire If statement to be considered true. Therefore, the value of the iValue variable can be less than 5 or it can be greater than 10. A value of 4 in the iValue variable would make the entire statement true as the iValue < 5 statement is true.

Logical Operators

You use logical operators to compare variables to other variables or constants. You frequently need to know if one variable has the same value, a lesser value, or a greater value than another variable. Sometimes you must compare several items or groups of items 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.

Controlling the Flow of Scripts Exercises

The following exercises will give you practice in creating If-Then statements.

Understanding Functions

You can find three types of functions within the JAWS scripting language. The three types of functions include:

• Built-in

• User-defined

• Event

Built-in functions are included with the JAWS scripting language and cannot be modified. User-defined functions are functions created for a specific task within a script file and can be modified. Event functions are part of JAWS and can be modified. A description of each type of function follows.

You can find complete descriptions of all built-in, user-defined and event functions that come with JAWS by reviewing the Freedom Scientific Developer Network function reference manual. You can download the manual from the following URL: https://support.freedomscientific.com/support/jawsdocumentation/FSDN

Built-in Functions

Freedom Scientific has provided >1,000 pre-defined functions within the JAWS scripting language. Each function performs a specific series of activities. You use these functions as the building blocks or instructions used to develop your scripts. For example, the RouteJAWSToPC() function checks the position of the JAWS Cursor and PC Cursor, makes the necessary calculations and moves the JAWS Cursor to the same point as the PC Cursor. All the activity is transparent to the JAWS user.

There are built-in functions that accomplish such tasks as: speaking messages, retrieving specific blocks of text, navigating the windows hierarchy and more. You can use the Insert Function dialog to insert any built-in function into the body of your scripts. You can also type the name of the function manually into the body of your script. If you choose to type the built-in function into your script manually, you must make sure you spell the name of the function correctly. You must also be sure the parameters the function requires are of the correct type and in the correct order.

User-Defined Functions

You can also use the script language to create or modify user-defined functions. The difference between a built-in function and a user-defined function is that you can modify user-defined functions while you cannot modify built-in functions.

A user-defined function is a self-contained module of scripting code that you develop to accomplish a specific task. A function is useful when you need to accomplish the same task from a variety of scripts and other user-defined functions. You can use the code of the function without having to write it multiple times. When you write the code once in a function, the time you need to maintain the code is reduced. Rather than modifying blocks of code in several different locations, you need only to make the changes in one place. After you have made the changes, re-compile any scripts or user-defined functions that call the newly modified function.

After you have created the function, you can call it from another script or function, and the task is performed. When the function completes processing, control is returned to the calling script or function where processing continues. You can find many examples of user-defined functions written by the script developers at Freedom Scientific in the default script file, Default.jss. To view the default script file in the Script Manager, do the following:

• Press JAWSKEY + F2 to activate the Run JAWS Manager dialog.

• Press S to select the Script Manager followed by ENTER to start the manager.

• Press CONTROL + SHIFT + D to open the default script file.

Event Functions

The purpose of event functions is to cause JAWS to perform specific tasks automatically without waiting for you to initiate the action with a keystroke. Each event function is triggered by its corresponding windows event. For example, when an application writes new text to the screen, the new text event is triggered. This event causes JAWS to perform the NewTextEvent() function to determine what type of text was written to the screen. Event functions differ from user-defined functions in that you cannot create new event functions. However, you can modify the code in existing event functions.

All parameters for an event function are declared between the left and right parentheses in the function begin statement. When JAWS calls this event function, values are automatically passed for each of the parameters between the parentheses of the function call statement. You cannot add or remove parameters that an event function uses. However since values for each of these parameters are passed when the function is called, you can use the data provided by any of them when you need to customize the event function.

A list of some of the most important event functions follows:

• AutoStartEvent()

• FocusChangedEvent()

• NewTextEvent()

JAWS performs the AutoStartEvent() Function when an application starts and any time the application becomes active. Any code that you do not place within a conditional statement is performed each time the function is called. You can use the AutoStartEvent() Function to initialize any global variables used by the application script file, speak an introductory message when the application starts or perform functions to initialize other settings used by the scripts and user-defined functions contained in the application-specific script file.

A parameter is data you pass to a function. You pass a parameter at run time rather than include it as part of the code because the information may be different each time you call the function. A parameter can be any of the variable types used in the scripting language: handle, integer (int), object or string. You declare a parameter like a variable. Instead of declaring the parameter in the body of your function using the key word Var, you place the type and name of the parameter between the parentheses following the function name. When your function requires multiple parameters, you separate each parameter declaration with a comma. Some examples of function beginning lines containing parameter declarations follow:

Void Function SelectingText(Int nMode)
Void Function ProcessSelectText(Int nAttributes, String buffer)

You can also use the New Script dialog within the Script Manager to declare parameters. After you have entered all the general information about the new function, press CONTROL + TAB to move to the Parameters page of the New Script dialog. Press TAB to move to the New Parameter edit box and type the name of the parameter. You should follow the same rules for naming parameters as you would for naming variables. Press tab to move to the Description edit box and type in a description of the parameter. After you have entered a description for the new parameter, press tab until you reach the Available Types list box. Use your ARROW KEYS to select the type of data the parameter will contain. After you have chosen a parameter type, move to and activate the add button to add the parameter to your function.

You declare a function that requires a single string parameter as follows:

Void Function SayName (String sMyName)
SayFormattedMessage (OT_MESSAGE, sMyName)
End Function

In the above example, the SayName() function receives a string parameter, sMyName, from the calling script or function. The SayFormattedMessage() function uses the value in sMyName as its first parameter. You can call the SayName() function in one of the following ways:

::: {#example-1}

Example 1:

:::

Script SayMyName ()
SayName ("John")
End Script

Example 2:

Var
    String sMyName
Let sMyName = "John"
SayName (sMyName)
End Script

The data being passed in the sMyName parameter can either be enclosed in quotation marks as in the first example or declared as a variable in the calling script as in the second example. In either case, the function is expecting a string of data to be passed. When you insert the SayName() function into the above script using the Insert Function dialog, you are prompted to provide the data for the parameter just as if you were inserting one of the JAWS built-in functions.

::: {#returning-data}

Returning Data

:::

A return is data that is sent back from a function to the calling script or function after the function completes processing. You use the keyword, return, to return the data to the calling script or function. The calling script or function uses this returned data for further processing.

A function can return any of the following:

• Void

• Handle

• Integer

• Object

• String

When you create a function, the return type is placed in front of the key word, Function, in the beginning line of the user-defined function. You select the return type from the New Script dialog within the Script Manager at the same time you create the user-defined function.

A function that requires no parameters and does not return any data to the calling script or function is declared as follows:

Void Function SpeakTheName ()
Var
    String sMyName
InputBox ("Enter the name:", "EnterName", sMyName) ; prompt the user For their name
If sMyName != cscNull Then ; determine If a value was entered in the input box
    SayFormattedMessage (OT_MESSAGE, sMyName)
Else
    SayFormattedMessage (OT_ERROR, "No name entered.")
EndIf
EndFunction

In the above example, the Void keyword precedes the Function keyword. The void keyword indicates that the function does not return any data to the calling script or function.

A function that requires no parameters and returns a string value is declared as follows:

String Function ReturnTheName ()
Var
    String sMyName
InputBox ("Enter the name:", "EnterName", sMyName) ; prompt the user For their name
Return sMyName ; Return the name To the calling Script or Function
EndFunction

In the above example, the String keyword precedes the Function key word. The String keyword indicates that the function returns a string value to the calling script or function.

Understanding Functions Exercises

The following exercises will give you practice in creating varying types of user-defined functions. Each exercise creates a user-defined function and a corresponding script to call the function. Each exercise will indicate the script file that should be used.

; Script file For Notepad
; JAWS version 12.0
Include "hjconst.jsh"
Include "common.jsm"

Void Function SpeakGreeting ()
    SayFormattedMessage (OT_MESSAGE, "Hello world, it's a great day For writing scripts.")
    TypeString ("Hello world, it's a great day For writing scripts.")
EndFunction

Script TypeAndSpeakGreeting ()
SpeakGreeting ()
EndScript

Void Function SpeakTheName (String sName)
Var
    String sMessage
If sName == "" Then; check To make sure text was actually passed in the sName parameter
    SayFormattedMessage (OT_ERROR, MsgNoName); speak an error message
    Return; exit the Function
EndIf
Let sMessage = FormatString (MsgName, sName); format the message using the passed parameter
SayFormattedMessage (OT_MESSAGE, sMessage)
EndFunction

Script SayName ()
Var
    String sName
Let sName = "John"
SpeakTheName (sName)
EndScript

@MsgName
Hello world, my name is %1 %2.
@@

Void Function SpeakTheName (String sName, String sLastName)

If sLastName == "" Then
SayFormattedMessage (OT_ERROR, MsgNoName); speak an error message
Return; exit the Function
EndIf

Script SayName ()
Var
    String sLastName,
    String sName
Let sName = "John"
Let sLastName = "Doe"
SpeakTheName (sName, sLastName)
EndScript

InputBox ("Name entry", "Please enter your first name", \$sName)

String Function RetrieveTheName ()
Var
    String sFirstName,
    String sLastName,
    String sMessage,
    String sPrompt,
    String sTitle
Let sTitle = "Name Entry"
; retrieve the first name
Let sPrompt = "Enter your first name:"
InputBox (sPrompt, sTitle, sFirstName)
; retrieve the last name
Let sPrompt = "Enter your last name:"
InputBox (sPrompt, sTitle, sLastName)
; format the message
Let sMessage = FormatString (MsgName, sFirstName, sLastName)
; Return the formatted message
Return sMessage
EndFunction

Script SpeakFormattedMessage ()
Var
    String sMessage
Let sMessage = RetrieveTheName (); call the Function To retrieve and format the message
SayFormattedMessage (OT_MESSAGE, sMessage); speak the message
EndScript

Windows Program Structure

What is a Window?

Most people who use the Windows environment never really understand what the word "window" actually means. Most users realize the rectangular box that appears on the screen when a new application is opened is a window. They probably think of the text area of their word processor as a window as well.

In most applications, every dialog box, menu, button, edit field, list box, etc. is actually a separate window with one or more identifiers that can be used to refer to it. However, 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.

Windows Hierarchy

The operating system does not randomly place the various windows that may be present on your screen at any one time. They are interrelated with a special hierarchy that allows the Windows operating system and the programmers who work within it to keep track of each window.

You can think of these inter-relationships as one of parents and children. The desktop is the parent of all application windows. Thus, the JAWS window, your word processor's window and the Internet browser's window are all children of the desktop. These windows are all one level down from the desktop, which makes them all children of the desktop at the same logical level. It also means that all of them are peers of each other. When you later encounter terms such as PriorWindow() and NextWindow(), the reference is to moving among peer windows at the same logical level.

The word processor window 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 all children at the same logical level. When you press the keystroke to open a file in your word processor, the word processor displays a child window that prompts you for the file to open. This window is often referred to as a dialog box, but it is a child window to the word processor, its parent.

If you think of the Open File dialog box as a parent then you will find that the File Name edit box and all other controls are children of the open file dialog box. These are all children of the parent dialog and are 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 from it.

You can find a good analogy of the parent-child relationship by using the directory structure of your PC. On your disk drive, the C:\ drive 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 sub-folders named Program Files, Users, and Windows on your system, they are all one level down from C:\. They are all children of C:\ and are all one logical level down. For the purposes of folder structure and window hierarchy, you can assume that being at the same logical level means that all windows were spawned or generated by the same parent.

When you open the Program Files subdirectory, you should find subdirectories such as Common Files, Freedom Scientific and Internet Explorer. These three sub-folders are all one level down from Program Files, are children of Program Files, and are at the same logical level as each other, two levels down from C:\. This can continue until the lowest logical level of a particular branch is reached.

The parent/child structure of Windows works much the same way as a folder 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. Each of these children can spawn children of their own, and these children are three levels down from the parent application.

Diagram of Windows Window Hierarchy and File/Directory Analogy

graph TD
    subgraph WIN["🪟 Windows Window Hierarchy"]
        D["Desktop<br/>(window parent)"]
        A["Applications"]
        J["JAWS"]
        W["Word"]
        C["Chrome"]
        TA["Text Area"]
        MB["Menu Bar"]
        TB["Toolbar"]
        SL["Status Line"]
        OFD["Open File<br/>Dialog"]
        FNE["File Name<br/>edit box"]
        OC["Other controls"]
        
        D --> A
        A --> J
        A --> W
        A --> C
        W --> TA
        W --> MB
        W --> TB
        W --> SL
        W --> OFD
        OFD --> FNE
        OFD --> OC
    end
    
    subgraph FILE["📁 File/Directory Hierarchy"]
        DR["C:<br/>(drive root)"]
        PF["Program<br/>Files"]
        CF["Common<br/>Files"]
        FS["Freedom<br/>Scientific"]
        BR["Browser"]
        U["Users"]
        WD["Windows"]
        
        DR --> PF
        DR --> U
        DR --> WD
        PF --> CF
        PF --> FS
        PF --> BR
    end
    
    ANALOGY["🔗 Analogy<br/>Desktop ↔ Drive<br/>Window spawn ↔ Subfolder<br/>Dialog ↔ Folder"]
    
    style WIN fill:#ADD8E6,stroke:#4169E1,stroke-width:2px
    style FILE fill:#90EE90,stroke:#228B22,stroke-width:2px
    style ANALOGY fill:#FFE4B5,stroke:#FF8C00,stroke-width:2px
    style D fill:#ADD8E6,stroke:#000
    style A fill:#90EE90,stroke:#000
    style J fill:#FFFFE0,stroke:#000
    style W fill:#FFFFE0,stroke:#000
    style C fill:#FFFFE0,stroke:#000
    style DR fill:#ADD8E6,stroke:#000
    style PF fill:#90EE90,stroke:#000
    style U fill:#FFFFE0,stroke:#000
    style WD fill:#FFFFE0,stroke:#000

Identifying Windows

An application programmer assigns a number of identifiers to each window. These identifiers allow the window in question to be referred to unambiguously. Each window has a class, type, type code, window subtype code, and control ID. These window categories are important because JAWS behaves differently, depending on what category of window is active.

For example, if an edit field is active, JAWS tracks the insertion point. When you press DOWN ARROW, JAWS speaks the line of text to which the insertion point moves. When a list box or menu is active, 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 on the type of the window that has the focus when one of these keys is used.

::: {#the-window-handle}

The Window Handle

:::

The window handle is a unique number assigned by the operating system to each window when it is created during a given session. Window handles change each time the window is created. However, the handle value remains constant as long as the window exists.

As long as a window exists, you can use the handle to refer to and identify that window. But when a window is closed, it relinquishes its handle. If the window is created later, the operating system assigns a different handle.

You can retrieve the window handle using the built-in functions, GetCurrentWindow() and GetFocus(). There is a distinct difference between these two functions. The GetFocus() function retrieves the handle of the window that contains the insertion point or system focus. The GetCurrentWindow() function retrieves the handle of the window containing the active cursor.

An example of how the GetFocus() function is used follows:

Script GetWindowFocus ()
Var
    Handle hFocusWindow
Let hFocusWindow = GetFocus ()
; the GetFocus statement could be replaced by the following line:
; Let hFocusWindow = GetCurrentWindow ()
SayInteger (hFocusWindow); speak the value of the window Handle
EndScript

::: {#window-class}

Window Class

:::

The window class is a string of text that denotes some information about a window and what it does. A window class can be edit, list box, or a button. It provides valuable information about the window. However, the window class does not always provide specific information. Checking the window class will return the same information for a button, radio button, and checkbox all of which have a Window Class of button. JAWS recognizes 28 different classes.

Many times, programmers use custom window classes that JAWS cannot recognize. In these cases, you must tell JAWS how to treat the unrecognized class. After you tell JAWS how to treat a custom window class, JAWS reacts to the window class just as if it were a recognized window class.

You can retrieve the Window Class with the function, GetWindowClass().

An example of how the window class is retrieved follows:

Script RetrieveWindowClass ()
Var
    String sTheClass
Let sTheClass = GetWindowClass (GetFocus ())
If sTheClass == "Edit" Then ; the window class is an edit box
    SayFormattedMessage (OT_MESSAGE, "Focus is in an edit box.")
Else
    SayFormattedMessage (OT_MESSAGE, "The focus is Not in an edit box.")
EndIf
EndScript

::: {#window-type}

Window Type

:::

The window type is a string of text that describes the window. Occasionally, the window type reveals more specific information about certain windows. The window type and window class are the same if no more specific information is available. For example, the window class and window type of an edit box are exactly the same.

You can use the window type to differentiate between a checkbox and a radio button. You use the function GetWindowType() to retrieve the Window Type. The GetWindowType() function returns the string of "unknown window type" when the application programmer used a custom window class to define the window. The Window Type is always in English and is not very useful for those using JAWS in other languages.

An example of how the GetWindowType() function is used follows:

Script RetrieveWindowType ()
Var
    String sTheType
Let sTheType = GetWindowType (GetFocus ())
If sTheType == "Edit" Then
    SayFormattedMessage (OT_MESSAGE, "The focus is in an edit box")
Else
    SayFormattedMessage ("OT_MESSAGE, The focus is Not in an edit box.") ; a window type other than edit was found
EndIf
EndScript

::: {#window-type-code}

Window Type Code

:::

The window type code is a numeric value instead of a string. This number is translated into a recognizable string by constant definitions found in the file, HJConst.jsh. For example, in this file you can find lines such as WT_BUTTON=1, WT_COMBOBOX=2, WT_EDIT=3, WT_LISTBOX=4, and WT_SCROLLBAR=5. The WT prefix of the constant indicates that this is a constant that refers to a window type code.

While the window type code does not provide any more information than the window type, it does have the advantage of being language independent. You retrieve the window type code with the function, GetWindowTypeCode().

An example of how the GetWindowTypeCode() function is used follows:

Script RetrieveWindowTypeCode ()
Var
    Int iTheTypeCode
Let iTheTypeCode = GetWindowTypeCode (GetFocus ())
If iTheTypeCode == WT_Edit Then
    SayFormattedMessage (OT_MESSAGE, "The focus is in an edit box.")
Else
    SayFormattedMessage (OT_MESSAGE, "The focus is Not in an edit box.")
EndIf
EndScript

::: {#window-subtype-code}

Window Subtype Code

:::

Like the window type code, the window subtype code is also a numeric value. However, the window subtype code may provide more detailed information about a window. If no subtype code is available for the window, then the window type code and window subtype code are identical. You should use the window sub type code as it generally provides more specific information about a window than does the window type code. You can use the same constant definitions to refer to window subtype codes as you can for window type codes in your scripts and functions. For example, a radio button has a window type code of 1 (WT_Button) but a subtype code of 19 (WT_RadioButton).

Window subtype codes are also language independent. You use the function, GetWindowSubTypeCode(), to retrieve the window subtype code for a given window.

An example of the use of the GetWindowSubTypeCode() function follows:

Script RetrieveWindowSubTypeCode ()
Var
    Handle hWnd,
    Int iTheSubTypeCode,
    Int iTheTypeCode
Let hWnd = GetFocus ()
Let iTheTypeCode = GetWindowTypeCode (hWnd)
Let iTheSubTypeCode = GetWindowSubTypeCode (hWnd)
If iTheTypeCode == WT_Button Then
    If iTheSubTypeCode == WT_RadioButton Then
        SayFormattedMessage (OT_MESSAGE, "The active window is a radio button.")
    Else
        SayFormattedMessage (OT_MESSAGE, "The active window is Not a radio button.")
    EndIf
Else
    SayFormattedMessage (OT_MESSAGE, "The active window is Not a button.")
EndIf
EndScript

::: {#window-control-id}

Window Control ID

:::

The control ID is a number that is assigned by the programmer to each window during application development. The control ID, unlike the window class, has no special meaning, but you can use it to refer to a particular window. Ideally, no two windows in a program have the same control ID, but they sometimes do. If you know how to access the control ID, and, if it is unique within the application, you can tell JAWS to do certain things if you are focused on the window with the control ID you have identified.

One example where the use of control ID's are extremely useful is in applications where the buttons are labeled with bit map drawings instead of text labels. Normally, JAWS speaks the text label of a button when you move to it. 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, you can write a script that speaks the name of a button when the focus moves to a button with a particular control ID.

In most cases, the control ID is defined during application development and can be relied upon to uniquely identify a specific window. However, you may find cases where control ID's have not been assigned by the application developer. In these cases, you will find that each window in a given application have control ID values of 0. You must then rely on other window identifiers along with the window's hierarchical position to uniquely identify it.

You may also find that the control ID's in a given application are dynamically assigned. This means that each time an application window or any of it's child windows are created, the control ID's are assigned and do not remain constant. In these cases, you will find that you need to use the other windows identifiers and the window hierarchical position to uniquely identify the window.

You can determine if control ID's are dynamically assigned by running the application, noting the control ID values of some of it's child windows, then restarting the application and looking at those same control ID values. If they have changed, then you will know that the ID's are dynamically assigned. You use the function, GetControlID(), to retrieve the control ID for a given window.

An example of how the GetControlID function is used follows:

Script IdentifyWindow ()
Var
    iControlID
Let iControlID = GetControlID (GetFocus ())
If iControlID == 1100 Then
    SayFormattedMessage (OT_MESSAGE, "This is the file name edit box")
Else
    SayFormattedMessage (OT_MESSAGE, "This is Not the file name edit box.")
EndIf
EndScript

Reassigning Window Classes

There is a standard list of window classes used by most programmers during the development of windows applications. The scripts and user-defined functions found in the default script file contain the necessary logic to allow proper speaking of these standard classes. However, application programmers do not always use standard window classes during application development. Many times, a programmer creates custom window classes that are non-standard. JAWS is unable to recognize the custom class and speak the window correctly.

You use the Configuration Manager to equate the unknown class to a standard class to allow JAWS to process the window correctly. This process is called reassigning the window class. Once you have reassigned a custom window class, JAWS is able to identify the window and speak it correctly. During window reassignment, you may need to try more than one class to determine what standard class works best.

To reassign a window class, you can use the JAWS Cursor, Invisible Cursor or PC Cursor to locate the window. To reassign a window class, do the following:

• Move the JAWS Cursor, Invisible Cursor or PC Cursor to the window with the non-standard class.

• Press JAWSKEY + F2 to activate the Run JAWS Manager dialog.

• Press JAWS Cursor, Invisible Cursor or W to move to the JAWS Cursor, Invisible Cursor or Window Class Reassign item.

• Press ENTER to start the Configuration Manager and display the Window Classes dialog. The New Class edit box is the active control. The non-standard window class is shown in this edit box.

• Press TAB to move to the Assign To list box. This list box contains all of the standard window classes JAWS recognizes.

• Use your ARROW KEYS to move through the list. Select the window class you think best suits the non-standard window class.

• Press TAB to move to the Add Class button. Press SPACEBAR to activate this button. You can also press ENTER from the Assign To list box to activate the add Class button.

• Press the SPACEBAR to activate the OK button to close the Window Classes dialog. The Configuration Manager will also close.

Exploring Applications with the Utility Functions

JAWS provides you with a powerful set of utilities to quickly analyze an unknown application. These utilities are called the Script Utility Mode. When the Script Utilities are activated, the keyboard is placed in a shifted state. These utilities give you access to system level window information that you can use when scripting an unknown application. You can determine parent-child relationships, windows identifiers, and retrieve information about MSAA objects¹.

Press CONTROL + WINDOWS + HYPHEN to turn on the Script Utilities. Press CONTROL + WINDOWS + HYPHEN a second time to turn off the Script Utilities.

Speaking Window Information

After activating the Script Utilities, you can speak various types of information about the active window. Press F1 to speak information about the window. By default, the window and related text are spoken when the utilities are activated for the first time.

You can cycle through the different pieces of information spoken by pressing F3. The pieces of information spoken are referred to as output modes. Each time you press F3 followed by F1, a different output mode is spoken.

Output modes include:

• window type

• window text

• focus

• control ID

• class

• type

• subtype

• real name

As you cycle through the various output modes, you can press F1 to hear JAWS speak the current output mode. Pressing JAWSKEY + HOME on the number pad will reset the output mode to say type and text. After the keystroke is pressed, JAWS announces "output mode is type and text." This keystroke eliminates the need to press F3 to return to the say type and text output mode.

You can also copy the spoken information to the clipboard. Press CONTROL + F1 to copy the spoken information to the clipboard. You can paste this information into your favorite text editor for review. Press JAWSKEY + F1 to have JAWS place the information in the virtual viewer.

Moving to Windows

In the windows program structure, there is a parent-child relationship between all windows contained within an application. A parent window can have several child windows. All child windows of a specific parent window are siblings of each other and said to be on the same logical level. Using the Script Utilities , you can access each of these windows and speak information about them.

::: {#moving-across-the-windows-hierarchy}

Moving Across the Windows Hierarchy

:::

Using the Script Utilities , you can access windows even if they are not accessible through the TAB and SHIFT + TAB keys when Script is turned off. Press TAB to move to the next window on the same level. You can continue to press TAB until JAWS speaks "No next window." This message indicates you have reached the last window on the same logical level.

You can move to the prior window on the same level by pressing SHIFT + TAB. You can continue to press SHIFT + TAB until JAWS speaks "No prior window." This message indicates you reached the first child window on the same level.

As you press TAB or SHIFT + TAB to move through the windows, JAWS automatically speaks the selected output mode. You can press JAWSKEY + TAB to hear the window type and text spoken by JAWS for the active window. If you are not sure where you began, press F5 to return the Script Utilities to the location of the PC Cursor.

::: {#moving-up-and-down-the-windows-hierarchy}

Moving Up and Down the Windows Hierarchy

:::

You can use the Script Utilities to move up and down the windows hierarchy. This functionality gives you the ability to determine if the window with focus has any child windows associated with it. It also gives you the ability to move to the parent of the active child window.

Press F2 to determine if the active window has any associated child windows. When a child window is found, the focus is moved to the child window and JAWS speaks the output mode information about the child window. You can continue to press F2 until JAWS speaks "Child window not found." This message indicates you are at the bottom of the windows hierarchy and no more child windows are present. Press TAB and SHIFT + TAB to determine if there are other child windows on the same logical level.

Press SHIFT + F2 to determine if a child window has an associated parent window. You can continue to press SHIFT + F2 until JAWS speaks "Parent window not found." This message indicates you have reached the top of the windows hierarchy. After you have reached a parent window, press TAB and SHIFT + TAB to determine if there are other windows on the same logical level. Remember that a parent cannot only have child windows, but it can be the child of another parent window. After reviewing the parent-child relationships, you can press F5 to route the Script Utilities to the active window. This essentially takes you back to the starting point from which you activated the Script Utilities.

::: {#determining-window-visibility}

Determining Window Visibility

:::

As you move across, up, and down the windows hierarchy you are moving to windows that may or may not be visible on the screen. You can use the Script Utilities to identify the windows that are visible and those that are not. Press F6 to hear the visibility status of the current window announced automatically by JAWS. Each time you move from window to window with this option turned on, JAWS will announce the visibility of the window immediately following the output mode information. You can turn this feature off by pressing F6 a second time. You can also announce the visibility status of the current window by pressing F7. This will announce the visibility status regardless of the state of the F6 visibility status toggle.

Searching for Text Attributes

Many applications use text attributes to convey important information. You can search for attributes such as: highlight, bold, underline, italic, and strikethrough using the Script Utilities . To select the text attribute for which to search, press F4. Each time you press this keystroke, JAWS announces the text attribute. Pressing F4 repeatedly will cycle through all text attributes. Once you have selected the text attribute, press GRAVE ACCENT () to begin the search. If the search finds text on the screen with the selected attribute, the JAWS cursor is placed on the text and it is announced. If the attribute is not found, then JAWS speaks "Next attribute not found". This indicates there is no text with the selected attribute. Pressing GRAVE ACCENT () subsequent times will move the JAWS cursor to the next occurrence of the attribute and announce the text. Pressing SHIFT + GRAVE ACCENT () will move the JAWS cursor to the prior occurrence of the attribute and announce the text.

As you press GRAVE ACCENT or SHIFT + GRAVE ACCENT, the JAWS cursor moves to the next or prior occurrence of the attribute, but will not stop at the last or first occurrence. Instead, the search begins over again and JAWS will not announce, "Next attribute not found."

You can press CONTROL + GRAVE ACCENT to immediately move the JAWS cursor to the location of the first occurrence of the selected attribute. You can also press SHIFT + CONTROL + GRAVE ACCENT to move to the location of the last occurrence of the selected attribute.

Retrieving MSAA Information

When the active cursor is on an MSAA object, you can use the Script Utilities to provide information about the object. However, you cannot navigate through MSAA objects using the Script Utilities. If you need to retrieve information on an object you must first activate that object by moving to it with either the JAWS Cursor or PC Cursor.

Press F9 to speak information about the object. By default, the object name is spoken when the utilities are activated for the first time. You can move to the next output mode by pressing F10. You can move to the prior output mode by pressing SHIFT + F10. Each time you press either F10 or SHIFT + F10 followed by F9, a different output mode is spoken. Output modes include: name, type, and subtype.

You can also copy the output mode information about the active object to the clipboard by pressing CONTROL + F9. You can then paste the information into a text editor for review after you complete your analysis of the application.

Script Utilities Keystroke Summary

The following utilities are helpful in finding all the information you need to know about controls, parent/child relationships, and text attributes.

::: {#tblr:table11-1}

: Script Utility Keystrokes :::

Customizing an Unknown Application

Many questions should be answered about a new application to determine what customization is necessary. Before you write your first script, you should determine how JAWS® works with the application without any customization.

The Main Application Window

The first place you should start your analysis is the main application window. Begin by activating the menu bar using the ALT key. Explore the main application window to determine if any of the controls can be accessed using TAB or SHIFT + TAB. Note any areas within the main application window that contain static text. You will also need to determine if any of the options in the menu or tool bars offer keyboard access. The following checklist gives you some initial areas to assess how well JAWS performs:

• Do menu bars speak automatically when activated?

• Do menu options speak automatically when the arrow keys are used to move from option to option?

• Can all controls on the main application window be accessed?

• Is there keyboard access to menu or toolbar items?

• Are there areas of the screen that contain static text that provides useful information during application execution?

• If there is static text within the main application window, can the user quickly locate the text?

• Are the tool bars and other important graphics labeled?

• What information should be shown on the Braille display for quick access?

The above list gives you suggestions for reviewing the main application window of a new and unknown application. You may find that there are other items to check that are not contained on the list.

Dialog Boxes

After reviewing the main application window, you should then check each of the dialog boxes contained within the application. When the dialog box first opens, does JAWS speak the name and active control automatically? Note whether or not the TAB and SHIFT + TAB keystrokes move the focus from control to control. You should also note any areas within each dialog box that contain static text. You can use the following check list to assess the amount of information spoken by JAWS within dialog boxes:

• Does each text label speak?

• Does JAWS announce control types correctly?

• Can all controls be accessed while moving through the dialog box with TAB and SHIFT + TAB?

• Is each control its own window?

• Can static text contained within the dialog box be quickly located?

Application Structure and Windows Identifiers

After you have made an initial assessment of the application, you will need to look at information for each of the windows contained within. You can use the Script utilities to determine things such as parent-child relationships, control ID values, window classes and more. You should review the main application window and each subsequent dialog box in much the same way as before. However, you will need to note window identification information for each control or window. The following checklist can help you review the application using the Script utilities:

• Are control ID's defined?

• If the control ID's have been assigned, are they dynamic or constant?

• Does each window have standard window classes?

• Review the parent-child relationships in the main application window and each dialog box.

Beginning the Customization

After you have completed a thorough review of the application, you can now begin to think about how best to customize JAWS to work with it. If you found non-standard window classes, you should go back through the application and reassign each non-standard window class to a class that JAWS recognizes. Keep in mind that once you reassign a non-standard class, that reassignment is used for each occurrence of the non-standard window class throughout the application. Many times, reclassifying non-standard window classes significantly improves the ability of JAWS to read window information automatically using the default settings.

Before you create scripts to read areas of static text within any of the application windows, try creating frames around the text first. Creating frames around static text that is not contained within it's own window keeps from having to write scripts to access the information. You can then add frame events to monitor for changes within the boundaries of the frame and speak new text automatically when it appears. You can also attach a keystroke to the frame surrounding the text that will allow you to quickly read the information.

::: {#customizing-jaws-with-scripts}

Customizing JAWS with Scripts

:::

After you have tried frames and reclassifying non-standard window classes, you may find that you still need to create scripts for the application. Before you begin to look at the built-in functions used to create your scripts, there are a few things you should do.

Begin by using pseudo-code to list the steps your script should take to reach the desired outcome. Pseudo-code is nothing more than writing down the steps in short phrases that your script will need to complete the desired action. Write each step of the script down in a list. After you have written down the initial steps the script will need to execute, try to recreate those same steps with JAWS commands using the keyboard. You should also review the notes you made previously when you used the Script utilities. You may be able to take advantage of the relationships between parent and child windows to access information within the application.

After you have either tried recreating the steps using the keyboard or reviewed the program structure, note any additional steps you had to take that are not listed in your pseudo code. Now you can begin to look at the built-in functions you will need to use to create the script and achieve the desired outcome. You can follow this procedure for each script you need to write to customize JAWS to work with the application.

Passing Keystrokes and Typing Text with Scripts Exercises

The following exercises give you practice creating scripts that pass keystrokes, access menu options that do not have shortcut keys and type text into the active document window. These chapter exercises do not walk you through the steps needed to create the script. Instead, the goal of the script is shown first, the script documentation second and the code of the script third. If you need to review the steps used to create a script or add functions to the script, refer to chapters 1 through 9 for information on the steps needed to start the Script Manager and the use of the New Script dialog.

Typing Text with a Script

The objective of this exercise is to create a script that types your e-mail signature in any active application window. You can use this script in your e-mail application, any text editor, or a word processor. You can use a series of TypeString functions to type the text of your signature. Between each call to the TypeString function, be sure to insert calls to the EnterKey function. After you have typed all the necessary text for your signature, JAWS should speak a message informing you the signature was added. Script Documentation:

1. Script Name: TypeSignature

2. Can be Attached to Key: Checked

3. Synopsis: Types an e-mail signature in any application.

4. Description: Types an e-mail signature in any application using the TypeString function.

5. Category: Keyboard

6. Assign To: CONTROL + SHIFT + W

Script TypeSignature ()
    TypeString (\enquote{Training Department})
    EnterKey ()
    TypeString (\enquote{Freedom Scientific Inc.})
    EnterKey ()
    TypeString (\enquote{11800 31st CT. N})
    EnterKey ()
    TypeString (\enquote{St. Petersburg, FL 33716})
    EnterKey ()
    TypeString (\enquote{PH: (800) 444-4443})
    EnterKey ()
    TypeString (\enquote{FAX: (727) 471-7927})
    EnterKey ()
    TypeString (\enquote{training_info@FreedomScientific.com})
    EnterKey ()
    SayFormattedMessage (OT_STATUS, \enquote{Signature added})
    EndScript

Additional Practice: Turn this signature into a reusable snippet system: prompt for recipient or context and insert different templates across editors (for example, Notepad, email, Word). How would you detect the host application and pick the right snippet?

:::

Output Types

Correct Use of Output Modes

Prior to JAWS 6.0¹, Output Modes (or Output types) were used as a means of controlling information spoken at each verbosity level. With the introduction of Braille Flash Messages in JAWS 6.0, Output Modes are also now used to control which messages are sent as Flash messages to the display. It is thus vital to ensure that correct use of Output Modes is made during scripting to avoid unnecessary Flash messages appearing in Braille. This document outlines the use of Output Modes.

It is very important that correct Output Modes be used not only because of Flash Messages but because JAWS uses the Output Mode in conjunction with all of the JCF options and the Speech and Sounds Scheme in use to determine how text should be spoken. For example, if OT_SPELL is used, JAWS will spell rather than speak the text using the voice alias defined for spelling. Similarly, text spoken using OT_KEYBOARD will honour the current Typing Echo settings. Not all Output Modes are relevant for Braille. Generally, text which is rendered on the display by means of Line or Structured modes does not need to be sent as a Flash Message. For this reason, many of the Output Modes are disabled for Braille altogether. The relevant Output Modes which are configurable for Braille are listed at the end of this document.

::: {#ot_no_disable}

OT_NO_DISABLE

:::

This output Mode should be used very sparingly as messages spoken using it cannot be suppressed and will generate Flash messages.

::: {#ot_help}

OT_HELP

:::

This Output Mode Should be used to speak all Screen Sensitive, Hotkey, Keyboard or other help messages when these messages are not being displayed in the virtual viewer.

::: {#ot_app_start}

OT_APP_START

:::

This Output Mode should only be used to speak messages generated when an application first starts (and only once per JAWS session).

::: {#ot_jaws_message}

OT_JAWS_MESSAGE

:::

This Output Mode should be used to speak messages originating from JAWS, for example when the information is originating from JAWS rather than the application. For example, JAWS for Windows is Ready, JAWS is running in demo mode, or when the user presses a keystroke assigned to a JAWS function, to announce the function name.

::: {#ot_screen_message}

OT_SCREEN_MESSAGE

:::

This Output Mode should be used to speak screen text from application instructions or help messages not considered dialog text. It would typically be spoken via the SayNonHighlightedTextEvent. For example, if a window contains added information about how to interact with the application, but is not essential for interaction with the application. It could be considered supplemental information which the user would perhaps want to hear once but not each time they ran the program. Note that this Output Mode should only be used when the window is automatically spoken. If the user specifically requests the help text via a keystroke, the OT_USER_REQUESTED_INFORMATION Output Mode should be used instead.

OT_CONTROL_GROUP_NAME

This Output Mode should be used to speak the name of a group box surrounding a set of controls. For example, the title of a group of checkboxes. Note that this Output Mode should only be used when the group or a control within the group gains focus or is automatically spoken. If the user specifically requests the control group's title via a keystroke, the OT_USER_REQUESTED_INFORMATION Output Mode should be used instead.

::: {#ot_control_name}

OT_CONTROL_NAME

:::

This Output Mode should be used to speak the prompt of a control. For example, the text to the right of an edit or the label of a button. It should not be used to speak type information nor should it be used to speak the control's contents such as the text in an edit. Note that this Output Mode should only be used when the control gains focus or is automatically spoken. If the user specifically requests the control's prompt via a keystroke, the OT_USER_REQUESTED_INFORMATION Output Mode should be used instead.

::: {#ot_control_type}

OT_CONTROL_TYPE

:::

This Output Mode should be used to speak type information about the focused control. For example, if scripts are written to support a custom control, the description of the control should be spoken with this Mode. An example might be a new Grid control. The word Grid would be spoken using this Output Mode. Note that this Output Mode should only be used when the control is automatically spoken. If the user specifically requests the control's type via a keystroke, the OT_USER_REQUESTED_INFORMATION Output Mode should be used instead.

::: {#ot_dialog_name}

OT_DIALOG_NAME

:::

This Output Mode should only be used to speak the title of a dialog (when a dialog is invoked by the user or application). It should not be used when the user specifically asks for the dialog's title.

::: {#ot_dialog_text}

OT_DIALOG_TEXT

:::

This Output Mode should be used to speak descriptive dialog text essential for correct use of the dialog controls. dialog text is text not part of a control's prompt within the bounds of the current dialog. Note that this Output Mode should only be used when the dialog is automatically spoken. If the user specifically requests the dialog text via a keystroke, the OT_USER_REQUESTED_INFORMATION Output Mode should be used instead.

::: {#ot_document_name}

OT_DOCUMENT_NAME

:::

This Output Mode should be used to speak a document's title when a document window gains focus. If the user specifically requests the document title via a keystroke, the OT_USER_REQUESTED_INFORMATION Output Mode should be used instead.

::: {#ot_item_state}

OT_ITEM_STATE

:::

This Output Mode should be used to speak the state of a control, for example, checked or not checked. It should only be used when the state is toggled or changed, not when the state is specifically requested by the user via a keystroke.

::: {#ot_position}

OT_POSITION

OT_POSITION :::

This Output Mode should be used to speak the position of an item relative to others in its container. For example, the current item in a list, the current node in a tree. It should only be used when the position information is spoken automatically, not when it is specifically requested by the user via a keystroke.

::: {#ot_error}

OT_ERROR

:::

This Output Mode should be used to speak error messages generated as a result of the user performing an inappropriate action. For example, trying to invoke the ListOfLinks in a context where no links maybe listed. It is for JAWS user errors, not application errors.

::: {#ot_tool_tip}

OT_TOOL_TIP

:::

This Output Mode should be used to speak tooltips generated by the operating system or application. A tooltip is a small bubble which appears as a result of moving the mouse pointer over a graphical object.

::: {#ot_help_balloon}

OT_HELP_BALLOON

:::

This Output Mode is used to speak Help Balloons generated by the Aplication or operating system. a Help Balloon differs from a tooltip in that it is generated as a result of user action or when the application or operating system wants to inform the user without the use of a dialog.

::: {#ot_status}

OT_STATUS

:::

This Output Mode is used to speak status messages, for example, when the user presses a keystroke which toggles a JAWS setting on or off. The state of the setting is spoken using this output mode whereas the setting's name itself should be spoken using OT_JAWS_MESSAGE.

::: {#ot_smart_help}

OT_SMART_HELP

:::

This Output Mode should be used for supplemental help given by JAWS for efficient use of an application (text which is not on screen). This does not include Screen Sensitive, Keyboard or Hotkey help, these should be spoken using OT_HELP.

::: {#ot_select}

OT_SELECT

:::

This Output Mode should be used to speak the message preceding or following the act of selecting text in an editor.

::: {#ot_tutor}

OT_TUTOR

:::

This Output Mode should be used to speak tutor information when a control gains focus, for example, "Press Enter to activate" or "Type in text".

::: {#ot_access_key}

OT_ACCESS_KEY

:::

This Output Mode should be used to speak the Access Key (underlined character) in a menu or control's prompt. An access key represents the key to press as a short cut to invoking the action described by the prompt of the control. For example, in an Edit Menu, the E maybe underlined which means that the user needs to press E to select that item directly without having to arrow to that item and press Enter.

::: {#ot_user_requested_information}

OT_USER_REQUESTED_INFORMATION

:::

This Output Mode should be used whenever a user requests information to be spoken via a keystroke. For example, if the user presses JAWSKEY + F12 to hear the time, JAWSKEY + T for the window title, etc.

Special Uses

The following Output Modes have special uses:

::: {#ot_blank_line_count}

OT_BLANK_LINE_COUNT

:::

Use this when a script is controlling SayAll to speak the number of blank lines.

::: {#ot_user_buffer}

OT_USER_BUFFER

:::

Use this to redirect the text to the virtual viewer rather than speaking it directly.

::: {#ot_phonetic_char}

OT_PHONETIC_CHAR

OT_PHONETIC_CHAR :::

Use this to cause the string to be expanded to its phonetic rendering. For example, say("a", OT_PHONETIC_CHAR) would say "alpha". If the string contains more than one character, the string will be spelled phonetically.

::: {#ot_braille_message}

OT_BRAILLE_MESSAGE

:::

This Output Mode should be used for messages specifically for Braille which won't ever be spoken. This could be used for displaying a dot pattern which represents some graphical layout information which has no speech equivalent.

::: {#ot_highlighted_screen_text-and-ot_nonhighlighted_screen_text}

OT_HIGHLIGHTED_SCREEN_TEXT and OT_NONHIGHLIGHTED_SCREEN_TEXT

:::

These two Output Modes should be used to speak text from the SayHighlightedText and SayNonHighlightedText functions.

::: {#ot_keyboard}

OT_KEYBOARD

:::

This Output Mode should be used to speak key labels as keys are pressed on either the main keyboard or Braille keyboard.

::: {#ot_spell}

OT_SPELL

:::

When text is spoken using this Output Mode, it is spelled rather than spoken. If a voice alias has been chosen for spelled text, this voice alias will be used as the text is spelled.

::: {#ot_sayall}

OT_SAYALL

:::

This Output Mode should be used when scripts are used to control a SayAll during the speaking of the units of text.

::: {#internal-output-modes}

Internal Output Modes

:::

The following Output Modes are used internally by JAWS and should only be used when the intent is to override default JAWS behaviour in an equivalent situation. For example, the SayWord function is overridden, the text spoken by that function should use OT_WORD. etc. Another example might be a function which automatically speaks a graphic when it appears on the screen, OT_GRAPHIC should be used:

• OT_STRING

• OT_GRAPHIC

• OT_CHAR

• OT_WORD

• OT_FIELD

• OT_CHUNK

• OT_LINE

• OT_TEXT

• OT_FONT

• OT_CURSOR.

::: {#braille-specific-output-modes}

Braille Specific Output Modes

:::

The Output Modes which are relevant to Braille are as follows:

• OT_NO_DISABLE

• OT_HELP

• OT_APP_START

• OT_JAWS_MESSAGE

• OT_ERROR

• OT_TOOL_TIP

• OT_STATUS

• OT_SMART_HELP

• OT_TUTOR

• OT_HELP_BALLOON

• OT_BRAILLE_MESSAGE.

The only one of this list which is not configurable is OT_NO_DISABLE.

The JAWS Message Format

The JAWS message format allows you to create messages just as if you were typing the text of the message in a text editor or word processor. You no longer have to use string concatenation to produce speech output. The message format also gives you the ability to dynamically add information to your messages through the use of embedded place holders.

Using the message format, someone who is not a programmer can also edit the text of existing messages. You can type any character within the body of your message. JAWS can then speak the text or display the text of your message in the virtual viewer with a single function call to either the SayMessage or SayFormattedMessage function.

Although you can declare messages using the message format within a script source file (.jss), it is best to declare those messages within a script message file (.jsm). You then include the message file within your script file using the "Include" statement discussed earlier.

Message Format

The JAWS message format consists of several key words:

• Messages

• @MsgName

• @@

• EndMessages

::: {#messages-keyword}

Messages

:::

The Messages keyword indicates the beginning of the message block. It tells the compiler that everything between this line and the EndMessages line is written in the message format. You can place as many messages as you wish within a message block. You should only place this keyword once at the top of your message file following any comments. You do not need to include the Messages keyword for every individual message you create.

::: {#msgname}

@MsgName

:::

The @MsgName statement indicates the beginning of an individual message. The at symbol ("@") indicates the beginning of an individual message. The "MsgName" portion of this statement is the actual name of the message that you designate. You should follow the same rules for naming messages as you do variables, scripts and user-defined functions. You should use no spaces, capitalize the first letter of each word and no punctuation except for the underline character ("_"). You will use the string of text less the at symbol ("@"), to refer to this message in your scripts and functions that speak the message.

All text following the "@MsgName" statement is part of the message body. All characters typed in the message body are literal, meaning that all characters are part of the individual message. You no longer need to use the backslash ("") character in front of any special characters that previously required it for translation. When you want a new line in your message, you can insert it by pressing ENTER.

You can also use placeholders within the body of your message. These placeholders give you the ability to place information gathered during script or function execution into your message. You can use up to nine placeholders within the body of the message. To add a placeholder in the message, you precede the number of the placeholder with the percent sign ("%").

In addition to placeholders, you can use the KeyFor function to display keystrokes within the body of your message. This functionality is available only when displaying messages within the virtual viewer. When the KeyFor function is used, the keystroke is shown in the virtual viewer as a link. The keystroke can be activated by navigating to the link and pressing ENTER.

To add the KeyFor() function to the body of your message, you must precede the name of the function with the percent sign (%). This indicates the point in your message in which JAWS places the desired keystroke. The KeyFor function requires a single parameter: the name of the script for which the keystroke will be displayed. To add the KeyFor function to the body of any message, use the following syntax:

::: {#statement}

@@ Statement

:::

The "@@" statement indicates the end of an individual message. Each @MsgName must be followed by the @@ statement. There are no spaces between the 2 @ symbols.

::: {#endmessages}

EndMessages

:::

The EndMessages key word indicates the end of the Messages block. Each Messages statement must have a corresponding EndMessages statement. You only need to include this key word once in your message file and usually at the bottom of the file.

::: {#example-message-formats}

Example Message Formats

:::

Messages
@MsgTest
This is a test message.
Note that the text is formatted as you would type it or see it in a dialog box.
@@
EndMessages

The above example contains only one individual message within the message block.

Messages
@MsgTest
This is a test message.
Note that the text is formatted, as you would type it or see it in a dialog box.
@@
@MsgTest2
This is a second message.
Note that multiple Messages can be contained within the message block.
@@
EndMessages

The above example contains two individual messages.

You can find many of these messages in the file Common.jsm. It is recommended you include this file in all your script files, as all messages and string constants contained in it begin with the letter "c" or "sc" to avoid conflicts with your existing definitions. The Default.jsm file is still included to support any legacy code that uses the old JAWS system. If you need to copy some of your own scripts into the default file, just include the default.jsm file if you are using constants from there.

The FormatString Function

The FormatString function gives you the ability to dynamically replace text within the individual message using placeholders. As stated earlier, the placeholder uses the percent sign (%) followed by a number. These placeholders can be placed throughout the individual message.

The FormatString function formats the string containing the message and replaces any placeholders with strings of text. the FormatString function then returns the formatted string to the calling script or function. The syntax of the FormatString function is as follows:

Let sMessage = FormatString (MsgName, sString1, sString2, sString3)

The MsgName variable is the individual message declared within the messages block. The parameters listed next are used to replace their respective placeholders within the message.

When you use the FormatString function and do not use all parameters, you must be sure to remove all commas following the last actual parameter used. For example, if you are using the FormatString function to add text to three place holders within a message called MsgText, the line inserted in your script by the Insert Function dialog looks like the following:

Let sMessage = FormatString (MsgText, sText1, sText2, sText3, , , , , , , )

If you use the arrow keys to review the line above, you will notice seven pairs of commas and spaces between the sText3 parameter and the right parenthesis. To ensure no errors are encountered at the time you try to compile the script containing this statement, you must remove the seven pairs of commas and spaces. Failure to do so will result in a "incorrect parameter format" error message when you try to compile the script or function containing the line above.

Let sMessage = FormatString (MsgText, sText1, sText2, sText3) ; removed extra commas and spaces

The following examples illustrate the use of the FormatString function within a basic "Hello World" script.

::: {#test.jsm}

Test.jsm

:::

; test file containing message statements
Messages
; For msgHello, %1= the first name, %2 = The Last Name
@msgHello
HELLO WORLD! My name is %1 %2.
@@
EndMessages

::: {#test.jss}

Test.jss

:::

; test file To demonstrate the Use of the message format and FormatString Function
Include "HjConst.jsh"; default constants
Include "common.jsm"; default message file
Include "test.jsm"; test message file created above

Script HelloWorld ()
Var
    String sMessage
Let sMessage = FormatString (msgHello, "John", "  "," Doe")
SayFormattedMessage (OT_MESSAGE, sMessage)
EndScript

The spoken output from the above script is:

::: leftbar "HELLO WORLD! My name is John Doe" :::

The SayFormattedMessage Function

In the previous example showing the use of the FormatString function, the SayFormattedMessage function is used to output the text to the synthesizer. The benefit of using the SayFormattedMessage function is that it does a final format of the message in order to account for the %KeyFor() placeholder. The SayFormattedMessage function also gives you the ability to use short and long messages. This added functionality lets you account for the message length option in the Verbosity Options section of the Configuration Manager. You can choose to use short or long messages depending on your verbosity setting and preference.

The SayFormattedMessage function is called using the following syntax:

SayFormattedMessage (OutputMode Constant, LongMessage, ShortMessage)

If you are not using both short and long messages, then you will only need the output mode and long message parameters.

Creating and Speaking Messages Exercises

The following exercises give you practice in creating messages. You will also use the FormatString and SayFormattedMessage built-in functions in these exercises.

Script SayMyName ()
SayFormattedMessage (OT_MESSAGE, MsgMyName, MsgMyName, "John", "Doe")
EndScript

Script SpeakMyName ()
Var
    sMessage,
    String sFirstName,
    String sLastName
InputBox ("Enter your first name:", "First Name Entry", sFirstName)
InputBox ("Enter your last name:", "Last Name Entry", sLastName)
Let sMessage = FormatString (MsgMyName, sFirstName, sLastName)
SayFormattedMessage (OT_MESSAGE, sMessage)
EndScript

::: .hint For more information on the InputBox function, open the builtin.jsd script documentation file within the Script Manager. :::

The Virtual Viewer

In previous versions of JAWS, the virtual viewer was only used in applications such as Internet Explorer and Microsoft Outlook Express. When you pressed JAWSKEY + H to review the list of JAWS hot keys for a given application, the keystrokes were spoken and you had no way of reviewing the list without pressing JAWSKEY + H a second time. This functionality, at times, made it difficult to get the desired hot key for the application.

JAWS now displays all help messages such as those created for the hot key help script performed by pressing JAWSKEY + H, the JAWSKEY + W, and JAWSKEY + F1 in the virtual viewer. When JAWS displays the information in the virtual viewer, the virtual cursor is active. You can use the normal navigation keystrokes to read, select, and copy the selected text to your favorite text editor.

You can use this same functionality in your scripts to display help information. From a script development standpoint, the virtual viewer is a Virtual Buffer created using the JAWS Scripting Language as the interface. The virtual viewer is also known as the user buffer.

The JAWS message format gives you greater flexibility when displaying text in the virtual viewer. You can format the text using spaces, carriage returns, tab stops, etc. After formatting your message, JAWS displays the text in the virtual viewer with the same look and feel as text found in a text editor or word processor. By default, JAWS displays all text in the virtual viewer in black on a white background (except for links). The text also has a font type of Arial, and a point size of 12.

Displaying Text in the Virtual Viewer

Before you display text in the virtual viewer, you should check the status of the virtual viewer to make sure it is not currently being displayed. You can use the built-in function, UserBufferIsActive, to check the status of the virtual viewer. The function returns a value of 1 when the virtual viewer is active or displayed and a value of 0 when the viewer is not being displayed. When the virtual viewer is active, you can use the built-in function, UserBufferDeactivate, to close the virtual viewer prior to redisplaying text. Deactivating the virtual viewer before JAWS displays new information prevents the user buffer text from running together.

The following code example illustrates the use of the UserBufferIsActive() and UserBufferDeactivate() functions. You should place these statements before the virtual viewer is activated by either the SayMessage or SayFormattedMessage functions.

If UserBufferIsActive () Then
    UserBufferDeactivate () ; closes the virtual viewer
EndIf

You can use either the SayMessage and SayFormattedMessage functions to display information in the virtual viewer. You pass the output type of OT_User_Buffer as the first parameter in either function to tell JAWS to display the message in the virtual viewer. Each function also accepts two additional parameters. The second parameter is the long message. This is the text of your message and can be in the form of a message contained in a message file, a string of text or a string variable containing the message. The third parameter contains the short message. Like the long message, the short message can be a message contained in a message file, a string of text or a string variable containing the message. If you are displaying information in the virtual viewer, JAWS ignores this parameter. Therefore, it is not necessary to pass any information in this parameter.

You can call either function using the following syntax:

SayMessage (OT_USER_BUFFER, "This text is being displayed in the virtual viewer")
; OR
SayFormattedMessage (OT_USER_BUFFER, "This text is being displayed in the virtual viewer.")

Displaying Keystrokes as Links

You can also create keystroke links in the virtual viewer by using the %KeyFor function. The %KeyFor function replaces the older use of the GetScriptKeyName function. Using the older method of speaking or displaying messages, you had to concatenate the string using the GetScriptKeyName function. Using the new message format, you can insert the script name directly into your message by adding the following line:

The percent sign preceding the function name acts as a placeholder for the keystroke. When the message is displayed in the virtual viewer, the function retrieves the keystroke for the script named in the functions parameter. The keystroke is displayed as a link that can be activated by pressing ENTER on the line containing the keystroke.

The following script and message file additions illustrate the use of the JAWS message format to display text in the virtual viewer:

::: {#test.jsm-1}

Test.jsm

:::

Const ; Strings For edit prompt:
    sDlgName = "Enter Name",
    sFirstPrompt = "First Name: ",
    sLastPrompt = "Last Name: "

Messages
; For msgHello, %1= the first name, %2 = The Last Name
@MsgHello
HELLO WORLD! My name is %1 %2.
Press, %KeyFor(HelloWorld), To redisplay this message.
Press ESCAPE To close this message.
@@
EndMessages

::: {#test.jss-1}

Test.jss

:::

Include "HjConst.jsh"; default constant definitions
Include "HjGlobal.jsh"; default global variable definitions
Include "common.jsm"; default virtual viewer constants and Messages
Include "test.jsm"; test message file

Script HelloWorld ()
Var
    String sFirstName,
    String sLastName,
    String sMessage
If UserBufferIsActive () Then; determine If user buffer is active
    UserBufferDeactivate (); close or deactivate the virtual buffer
EndIf
InputBox (sFirstPrompt, sDlgName, sFirstName) ; prompt For the first name
InputBox (sLastPrompt, sDlgName, sLastName) ; prompt For the last ;name
Let sMessage = FormatString (MsgHello, sFirstName, sLastName)
; replace the % place holders with data
SayFormattedMessage (OT_USER_BUFFER, sMessage) ; display the message in the user buffer
EndScript

In the above example, the script begins by checking the status of the virtual viewer. If the viewer is active, then JAWS deactivates it before the script continues processing. The two InputBox statements retrieve the first and last names from user input. The FormatString function then takes the first and last name information and combines it with the message to create a final version of the message. The message is then displayed in the virtual viewer using the SayFormattedMessage function.

If you create the script above, assign it to CONTROL + 1 and you enter "John" for the first name and "Doe" for the last name, JAWS displays the following text in the virtual viewer:

::: leftbar "HELLO WORLD! My name is John Doe. Press, CONTROL + 1, to redisplay this message. Press ESCAPE to close this message." :::

Using the Virtual Viewer Exercises

The following exercises give you practice creating and using messages in the virtual viewer. Before you start these exercises, make sure you have the Notepad.jss script file open within the Script Manager. This file should contain any practice scripts from earlier chapters of this manual. If you run Script Manager from within Notepad and a blank file is opened, type the following lines at the top of the file:

; Script file For Notepad
; JAWS version 12.0
Include "hjconst.jsh"
Include "common.jsm"

Script DisplayVirtualViewer ()
If UserBufferIsActive () Then
    UserBufferDeactivate ()
EndIf
SayFormattedMessage (OT_USER_BUFFER, MsgVirtualViewer)
EndScript

JAWS and Braille

When you use a Braille display in structured mode, you can control the order and type of information shown on the display. There are several parts of JAWS that work together to place the desired information on the display. These areas include:

• JAWS user interface

• Configuration Manager

• JAWS Braille structured file

• Default Braille functions

The JAWS user interface and Configuration Manager are used to customize the information shown on your display. The Braille structured file contains settings used by JAWS to determine the type and order of information shown on the display. The default Braille functions are called internally from within JAWS to place the desired information on your display.

JAWS User Interface and Configuration Manager

You can access the Braille Options section of Configuration Manager in one of two ways. To reach the Braille Options section through the JAWS user interface, do the following:

• Press JAWSKEY + J to activate the JAWS user interface.

• Press ALT + O to open the Options menu.

• Press L to open the Braille Basic settings dialog.

• Press ALT + A to activate the Advanced... button.

• You are placed in the Braille Options section of the default configuration file, Default.jcf, within Configuration manager.

To reach the Braille Options section through the Configuration Manager, do the following:

• Press JAWSKEY + F2 to display the JAWS managers list.

• Press ENTER on Configuration Manager. This is the first item in the list so you will need to type C to reach the item.

• Press ALT + S to open the Set Options menu.

• Press B to open the Braille Options dialog.

This list box contains all the control types JAWS shows on the Braille display. The list box has 2 columns. The first column contains the actual control name such as button or checkbox. The second column contains the symbol for the control that is shown on the Braille display. For example, a button has an entry in the list box of: button btn

::: {#modify-control-button}

Modify Control... Button

:::

The modify control button, when activated, lets you change the type and order of information shown on the Braille display. When this button is activated, the define properties dialog for the highlighted item in the control types list is displayed. The focus is placed in the Show on Display Combo box. This combo box lists all the components that are shown on the Braille display for the selected control. You can think of a component as a piece of information shown on your Braille display about the highlighted control. Examples of components are name, type, state, and value.

You can use the Remove button to remove the highlighted component from the list, or use one of the movement buttons to change the order of components shown on the display. For example, when the control type of button is highlighted, the Show On Display combo box lists name, type, and state in this order.

When you remove a component from the list, the component is shown in the Available Items to Add list box. Once you have removed a component, the add button is available. If you decide at a later date that you want that component shown on the display, the Add button is used to place the removed component back into the Show On Display combo box.

::: {#modify-braille-symbol-button}

Modify Braille Symbol... Button

:::

When you activate this button, the Control Properties dialog box is displayed. The focus is placed in an edit box containing the current symbol for the highlighted component in the control types list. This is the symbol that is shown on the Braille display and represents the component. You can change the characters used to represent the component by typing a new value. For example, when the control type of button is highlighted, the Braille symbol shown in this dialog is btn. You can change the symbol from btn to bt or another value of your choice.

State Properties Page

When this page of the Control Type Options dialog is active, the focus is placed in a list box containing the various states used to show control states on your Braille display. Examples of entries found in this list box are:

• Unchecked < >

• PartiallyChecked <->

• checked <X>

The above examples are all used on a Braille display to represent the checked, partially checked, and unchecked states of a check box. You can modify the characters used to represent the states of various controls by pressing TAB to the Modify Braille Representation button, or, by pressing F2.

Section 3: The JAWS Braille Structured File

When you modify structured mode, those changes are stored in a JAWS Braille structured or jbs file. The jbs file is an ini style file consisting of a variety of sections and keys. You can modify structured mode so that the changes take effect across the entire operating system or in a specific application. When you make changes globally, those changes are stored in the default JAWS Braille structured file, default.jbs. If the changes you have made to structured mode are application specific, then those changes are stored in the jbs file for the active application.

Some of the sections found in the default jbs file, default.jbs, include control type, component aliases, state aliases, and control states. Each of these sections is used internally by JAWS to determine what is shown on a Braille display.

Component Aliases Section

This section defines component aliases used internally by JAWS to display information on your Braille display. It is also used to display component information in the Braille Options Control Options Control Properties dialog in Configuration Manager. Component aliases make the connection to the components contained in the jbs file and the information shown in the Control Options Control Properties dialog.

A component alias consists of an ini style key and it's corresponding value. The key is used within the jbs file to determine what is shown on a Braille display and in what order. The key value is more descriptive and used within the Control Options Control Properties dialog. An example of a component alias follows:

dlgTEXT=Dialog Text

In the above example the key, dlgTEXT, is used within the jbs file. This key value tells JAWS to display dialog text on your Braille display. The key value, dialog text, is what you see in the Control Options Control Properties dialog.

State Aliases and Control States Sections

The state aliases section is used to determine what is shown in the Control Options State Properties dialog for control states. Some of the controls that can have various states are buttons, checkboxes, and tree views.

Each item listed in this section consists of an ini style key and it's corresponding value. The key is used internally by JAWS to indicate the state of a control such as a checkbox or a button. The corresponding key value is used within the Control Options State Properties dialog as an English representation of the state. An example of a state alias follows:

csChecked=Checked

In the above example the key, csChecked, is used internally by JAWS to show a checked state for a checkbox. The key value, checked, is listed in the Control Options State Properties dialog.

The control state section of the default jbs file consists of key and key values that determine what characters are shown on a Braille display for a given control state. The key is used by JAWS to display the control state on your display. The corresponding key value is the actual characters that are used to show the state on the display. An example of a control state is: csChecked=<X>

In the above example the key, csChecked, is used internally by JAWS to show a checked state for a checkbox on a Braille display. The key value, <X>, are the characters actually displayed on the display when a checkbox has a checked state.

Both of these sections work together to create a link between the information shown in the Control Options State Properties dialog and the characters shown on a display for a given control state. It is the key values in both examples that are displayed in the Control Options State Properties dialog. The key value is the link between both sections. The entry in the user interface for a checked control state is: Checked <X>

The key value, csChecked, makes the link between the state alias of "Checked" and the control state of "<X>". When you make a change to the state shown on your display for a checkbox that is checked, it is the Control State entry that is modified. For example, you decide to change the checked state representation of <X> to <Y> for a checkbox. After you make the change in the Control Options State Properties dialog, the control state key value is modified in the jbs file and looks like: csChecked=<Y>

Control Type Section

Each standard windows control has a section located in the default jbs file. This section tells JAWS what components to show on the Braille display, what order they are to be shown, and the Braille symbol to be used for the control. The control type section uses the subtype code of each window JAWS recognizes as part of the section name. In the default jbs file, you will find sections for control types such as button, combo box, list box, and so on.

Each control type section contains 4 keys with their respective values. The names of these keys are:

• components

• type

• removed

• displayname

An example of a control type section follows:

; Section For checkbox
{[}SubtypeCode20{]}
components=name,state,type
type=chk
removed=
displayname=

::: {#components-key}

Components Key

:::

The components key and its respective value tell JAWS what to show on your display and in what order. The key value consists of components found in the components aliases section discussed earlier. When you modify the order or components shown on your display from the Control Options dialog found in the Braille Options section of Configuration Manager, the changes are saved in this key for the control you are modifying.

Using the control type section for a checkbox from above, the components key has a value of name, type, value. The key value tells JAWS to display the name of the checkbox first, the type of control second, and the state of the checkbox third.

::: {#type-key}

Type Key

:::

The type key contains the characters used by JAWS to display the type of control on your display. The type key is used within the components key to display the control type. From the control type section for a checkbox from above, the characters shown on your display for a checkbox are chk.

When you make changes to the Braille symbol used to show the control type on your display, the change is stored in this key. For example, you decide that you want to change the chk used to show the checkbox control type. If you change the symbol to ck, the type key entry for a checkbox would look like: type=ck

::: {#removed-key}

Removed Key

:::

The removed key and its corresponding value list any components that have been removed from within the user interface. For example, if you decide to remove the state component from the components key for a checkbox then the removed key looks like: removed=state

After the modification, the components key looks like: components=name,type

::: {#display-name-key}

Display Name Key

:::

The displayname key and its corresponding value contain the display name of the control in the JAWS user interface. This line is normally used for custom controls which do not have a SubTypeCode associated with them.

Section 4: Adding Custom Components

When the default Braille support within JAWS does not show the correct information on a Braille display, it may be necessary to modify the components shown. For example, you may be working with an application that does not show the dialog box name on the Braille display. In this instance, it may be difficult to easily identify what dialog box is active based solely on the information shown on the Braille display.

You can find a good example of default functionality not displaying all relevant control information in the Microsoft Outlook 2003 email application. When you choose to display the Navigation Pane by pressing ALT + F1, the application displays a tree view containing all of your e-mail folders on your system. The application also displays the total of unread messages for each folder to the right of the folder name. By default, JAWS does not show this extra information on your Braille display. Thus, the following information is shown for the Inbox folder:

::: {#tv-inbox}

Tv Inbox

:::

This information tells you that the active control is a tree view, and the folder name is Inbox. However, the total number of unread messages is not shown. If you were only using Braille without speech, then you would not have this additional piece of information available to you.

In order to provide the equivalent information in both speech and Braille, the script developers at Freedom Scientific had to alter the way in which information is shown on your Braille display for tree views. In addition to the default information, the script developers added the additional unread message information through additions to the Braille structured file for Microsoft Outlook 2003, Microsoft Outlook 2003.jbs. IN addition to these changes, additional functionality was added to the Microsoft Outlook 2003 script file to allow JAWS to correctly show this information on your display.

By making these changes, complete information about the active tree view item is shown. Now in addition to the name, type, level and other information relating to a tree view item, the number of unread messages is also shown. So, now the following is shown on your Braille display for a tree view item that has unread messages:

::: leftbar Tv 8 unread Inbox :::

Adding extra information on a Braille display involves two procedures:

• Modifying the application specific .jbs file

• Creating an application version of a Braille function

After these two procedures are completed, complete information is shown on the Braille display.

Modifying the Application Specific .JBS File

The first step to adding information to a Braille display involves creating a component alias in the application specific .jbs file. The component alias is then used in the section of the control for which the extra information is to be displayed.

Using the Outlook 2003 example from above, the component aliases and dialog control sections of the Microsoft Outlook 2003.jbs file look like the following:

{[}Component Aliases{]}
UnreadMessageCount=Number of Unread Messages
; Section For treeview.
{[}SubtypeCode31{]}
components=ContextHelp, name, type, level, value, state, position, UnreadMessageCount
type=tv
removed=
displayname=

The string of text to the left of the = sign in the line, "UnreadMessageCount=Number of Unread Messages," is used in the "components=" line of the tree view control section, [SubTypeCode41], to list the additional component information on the Braille display. The string of text to the right of the = sign is displayed in the Control Type Properties Define Control dialog.

Creating an Application Specific Version of a Braille Function

In order to show the custom component on the Braille display, you should create an application specific version of one of the BrailleAddObject... functions. The function to be created depends on the component you wish to show on the Braille display. Using the Microsoft Outlook 2003 example from above, an application specific version of any the BrailleAddObject... function should be created in the Microsoft Outlook 2003.jss file. For our purposes here, we will use the default version of the BrailleAddObjectName function. The code of the function follows:

Int Function BrailleAddObjectName(Int nSubtypeCode)
Return False
EndFunction

The code of an application specific version of the BrailleAddObject... function follows:

Void Function BrailleAddObjectUnreadMessageCount (Int nSubTypeCode)
Var
    Int nAttribBits
Let nAttribBits = GetCharacterAttributes()
If GetCurrentControlID() ==ciFolderTreeView Then
    If !StringIsBlank (gsUnRedMsgs) Then
        BrailleAddString (gsUnRedMsgs,0,0,nAttribBits)
        Return True
    EndIf
EndIf
Return False
EndFunction

Both functions require the subtype code to be passed as a single parameter and return an integer value. It is important to note the difference between the default and application specific versions of this function. The default function name ends with the word "Name", while the application specific version of the function has the string, "UnreadMessageCount ", before the "BrailleAddObject" contained within the function name. The "UnreadMessageCount " portion of the function name tells JAWS to add the component, UnreadMessageCount to the Braille display.

Web Scripting

Placemarkers

PlaceMarkers allow you to quickly and easily navigate to commonly used areas of your favorite Web pages or HTML documents. You can use PlaceMarkers to jump between certain areas of a page, mark important sections of an HTML document, or indicate key form elements. For example, you could use PlaceMarkers to move to required fields in a complicated form or specific paragraphs in a long HTML document.

There are two types of PlaceMarkers, fixed and temporary. Only one Temporary PlaceMarker can exist at a time but you can move it simply by dropping it in a new location. You drop the Temporary PlaceMarker by pressing CONTROL + WINDOWS + K. If you then move to some other place and press the same keystroke again, it will remove the Temporary PlaceMarker from the previous location and place it at the current location. The Temporary PlaceMarker, if assigned, will also appear in the List of PlaceMarkers discussed below.

When you open a Web page press textcolorbbeK to move to the next PlaceMarker, or press SHIFT + K to move to the prior PlaceMarker. Press CONTROL + SHIFT + K to display a list of all PlaceMarkers on the current page. Use the UP/DOWN ARROW keys to select a PlaceMarker in the list. Then press ENTER to activate the Move To button. You can also press TAB to move to the Move To button and press SPACEBAR on it or press ALT + M to activate it and move your cursor to the PlaceMarker's location on the page.

Adding PlaceMarkers Move your cursor to the location on the page where you want to put the PlaceMarker Press CONTROL + SHIFT + K Press SPACEBAR on the Add button or press ALT + A. JAWS suggests a name for the PlaceMarker based on the text present at your cursor's current location. You can ENTER a new name if necessary Press SPACEBAR on the OK button to add the PlaceMarker to this page NOTE: Use the Anchor to Text checkbox in the Add Placemarker dialog box to tie a placemarker to a specific word or phrase. This will keep the placemarker in the proper place even if the location of the text changes on the page.

Custom Labels

JAWS allows you to assign custom text labels to almost any HTML element that you can move to by pressing the TAB key in Internet Explorer and Web-based documents. These elements include text links, graphic links, form fields, and buttons. You can also label images on Web pages. JAWS reads these custom labels instead of the identifying text assigned to the elements by the Web page author. JAWS also uses custom labels to identify elements when they appear in lists, such as the list of form fields that displays when you press JAWSKEY + F5. You can use this feature to customize the elements of any Web page to help you navigate the page, reduce verbosity, compensate for incomplete or poorly labeled elements, and similar functions.

You can also use this feature to label form fields in Microsoft Word and Adobe Acrobat or Reader.

JAWS saves the labels you assign to a Web page so they are available each time you use that page. In addition, the labels you create are applied to identical elements any time they appear in that page's domain. For example, if you assign a label to a button, JAWS reads that label any time you encounter the button on any Web page within that domain. Custom labels are saved in JSI files in the Settings\Enu\PersonalizedSettings folder.

Exploring Various HTML Related Functions

Before we explore some of the scripts and functions designed to work in the HTML environment, we first need to create a test script we can use in Internet Explorer. Perform the following steps to create this script.

PerformScript DisplayBasicElementInfo ()

Script FormFieldEntry () ; Assign To CONTROL + SHIFT + F
If GetDocumentPath () != "http://www.freedomscientific.com/Training/Surfs-Up/WebTrack.htm" Then
    SayFormattedMessage (OT_Message, "This Script is only available On the Web Track sample form", "Not available")
    Return
EndIf
SpeechOff (False)
MoveToFormField (s_top)
TurnOnFormsMode ()
TypeString ("Ryan Jones")
Delay(2)
PerformScript ExitFormsMode ()
Delay (2)
MoveToFormFieldByIndex (2)
Delay(2)
TurnOnFormsMode ()
Delay(2)
TypeString ("800-444-4443")
PerformScript ExitFormsMode ()
Delay(1)
MoveToFormFieldByIndex (7)
SpeechOn ()
TypeKey ("SPACEBAR")
EndScript

If GetDocumentPath () == "http://www.freedomscientific.com/default.asp" Then
    PerformScript MoveToPlaceMarkerN (1)
EndIf

Further Reading

For more information on JAWS scripting and resources I have used to generate this manual, refer to the following resources:

{{#cite freedomscientific:basicsscripting}} {{#cite freedomscientific:FSDN}} {{#cite freedomscientific:JAWSUIA}} {{#cite freedomscientific:JAWSdocumentation}} {{#cite freedomscientific:trainingportal}} {{#cite freedomscientific:JAWSgettingstarted}} {{#cite springer:IntroJAWSscripting}} {{#cite vandyke:SecureCRTJAWSscripts}} {{#cite stackoverflow:JAWSscriptDOM}} {{#cite github:jamalmazrui:JAWSscripts}} {{#cite github:travisroth:VSCodeJAWSScripts}} {{#cite gould2000_jawsscripting}} {{#cite fs_intro_jaws_scripting}} {{#cite fs_fsdn_support}} {{#cite fs_uia_script_api}} {{#cite hartgenconsultancy_jawsscripting}} {{#cite hartgen_org_jawsscripting_archive}} {{#cite freedomscientific:JAWS-ARIA-support}} {{#cite freedomscientific:JAWS-ARIA-roles}} {{#cite freedomscientific:JAWS-ARIA-doc-index}} {{#cite freedomscientific:JAWS-UIA-API}} {{#cite freedomscientific:ScriptUtilityMode-MSAA}} {{#cite freedomscientific:JAWSscripts-MSAA}} {{#cite microsoft:UIA-spec}} {{#cite microsoft:MSAA-spec}} {{#cite linuxfoundation:IAccessible2-spec}} {{#cite w3c:WAI-ARIA}} {{#cite github:campg2j003:AudacityJAWS}} {{#cite github:raisedbar:SibeliusJAWS}} {{#cite github:munawarb:NotepadPPJAWS}} {{#cite dlee:scripteconomy}} {{#cite dlee:projects}} {{#cite snowmanradio:scripts}} {{#cite snowmanradio:tutorial}} {{#cite snowmanradio:reaper}} {{#cite gist:beastlytheos:JAWSscriptexample}} {{#cite dlee:codecommon}} {{#cite microsoft:dynamics365JAWS}}

JAWS UIA Script API

JAWS UIA Script API

Introduction

The JAWS UIA Script API provides access to Microsoft's User Interface Automation (UIA) infrastructure via the JAWS script language. You can find detailed information about UIA on the Microsoft web site. This document describes the objects, methods, properties, and events available through the JAWS UIA Script API.

Supported Versions

With each version of Windows®, Microsoft extends the features provided by UI Automation. Many of the methods and properties described in this document are supported in Windows 7, most in Windows 8 and Windows 8.1, and all in Windows 10. Please consult the Microsoft documentation to find out which UIA interfaces, methods, and properties are supported in which versions of Windows.

All the objects, methods, properties, and events described in this document are available as of JAWS 18.0.2530.

Getting the FSUIA Object

The primary object in the JAWS UIA script API is FSUIA. Using this object, you can get other objects that represent UIA elements, get tree walkers which will allow you to traverse the tree of UIA elements, register for UIA events, and more.

To get an FSUIA object in scripts, use the JAWS built-in Function CreateObjectEx as follows:

Var 
	Object omyObject 
omyObject = CreateObjectEx ("FreedomSci.UIA", False, "UIAScriptAPI.x.manifest");

You can create as many FSUIA objects as you like, although you probably won't need that many.

Properties

In the UIA Script API, all properties are get-only, except those for which "get/put" is explicitly declared in this document.

Caching

Those familiar with UIA will know that clients may request element and pattern data be cached in order to improve system performance. The JAWS UIA Script API handles UIA's caching mechanism internally. Several of the most commonly requested element and pattern properties are requested to be cached; and the cached values are always checked before the uncached values. Using this approach should make most situations efficient while keeping the API as simple as possible.

The "Bool" Type

At present, the JAWS script language has no Boolean type. The term "bool" is used throughout the remainder of this document to indicate an integer value where zero (0) represents a Boolean value of false and any non-zero value represents a Boolean value of true.

The "Variant" Type

In the JAWS script language, a "variant" is a variable whose type is unknown at compile-time. Variants may be an int, string, handle, or object, and they can be used like any of these types. You can use the JAWS built-in script function GetVariantType to determine the type of a variant, although you may already know the underlying type based on the context. For example, if you request the name property of a UIA element and the return type is a variant, the underlying type will almost certainly be a string. If you happen to know the type of a given variant, you can declare the variable as the known type in the scripts. For example: if the GetProperty function returns a variant, but you know the type of the property returned will be a string, you can assign the return value directly to a string variable, rather than having to declare a variant. But even if you don't know that a variant is a certain type like a string, you can still pass it to functions which take the string type.

Special Integer Types

There are several sets of pre-defined integer values used by UI Automation methods and properties. These represent various element types, property types, pattern identifiers, and so on. For JAWS scripters, these types are declared in the file UIA.jsh. In the file, each of the types listed below is preceded by a comment containing the name of the type in order to make them easy to reference from this document. These types are used to indicate the intended values of certain parameter, return, and property types from here on.

• AnnotationTypeID

• ControlTypeID

• DockPosition

• Endpoint

• EventID

• ExpandCollapseState

• LandmarkTypeID

• LegacySelectionFlags

• LiveSetting

• OrientationTypeID

• PropertyID

• RowOrColumnMajor

• ScrollAmountID

• StructureChangeTypeID

• StyleID

• SupportedTextSelectionID

• SynchronizedInputType

• TextAttributeID

• TextEditChangeType

• TextUnit

• ToggleState

• TreeScope

• WindowInteractionState

• WindowVisualState

• ZoomUnit

Parameters by Reference

When a parameter is passed to a function "by reference", the value of the parameter is not only passed to the function, but also returned from the function. Therefore, after calling a function that takes a parameter by reference, the value of the parameter may have changed. This is a way of returning multiple pieces of information from a single function call. Throughout this document, the term "ByRef" is used to indicate those parameters which need to be passed to a function by reference.

In the JAWS script language, When a parameter is passed by reference, it must be done using a call to one of the reference functions: IntRef, StringRef, or IDispatchRef.

Var 
    Int x;
    Int y;
element.GetClickablePoint(IntRef(x), IntRef(y));

Arrays

The table below lists the types of arrays provided by the UIA Script API. Although the types of items contained in each array are different, all arrays behave the same way.

To get the number of items in an array, use its Count property, for instance, myArray.Count.

To access a specific item in an array by index, include the index in parentheses after the array name, for instance, myArray(5).

Finally, arrays may be used in ForEach loops as follows

Var 
    String s;
ForEach s in myArray
    ; do something with s
EndForEach

: UIA array types and corresponding item types (e.g. FSUIAElementArray FSUIAElement; FSUIAIntArray int).

Objects

FSUIA : Methods

: FSUIA object methods: signatures and brief usage notes (e.g. AddAutomationEventHandler, GetElementFromPoint, GetFocusedElement).

FSUIA : Properties

: FSUIA object properties: type, name and short description (e.g. AutoSetFocus, ConnectionTimeout, RawViewWalker).

FSUIAAnnotation: Properties

: FSUIAAnnotation properties: Author, DateTime, Target, TypeID, TypeName --- annotation metadata and meanings.

FSUIACondition

The FSUIACondition object has no script-accessible members.

FSUIADock: Methods

: FSUIADock methods: dock-related actions (e.g. SetPosition(DockPosition) --- set dock position).

FSUIADock: Properties

: FSUIADock properties: Position --- dock position of an element within its container and related meanings.

FSUIADrag: Methods

: FSUIADrag methods: drag operations and examples (e.g. GetGrabbedItems returns elements being dragged).

FSUIADrag: Properties

: FSUIADrag properties: DropEffect, DropEffects, IsGrabbed --- drag/drop state and descriptive fields.

FSUIADropTarget: Properties

: FSUIADropTarget properties: Effect and Effects --- descriptions of drop-target behavior and possible effects.

FSUIAElement: Methods

: FSUIAElement methods: element operations (FindAll, FindFirst, GetPropertyValue, SetFocus, ShowContextMenu) with brief purposes.

FSUIAElement: Properties

: FSUIAElement properties: common element properties and explanations (Name, ClassName, BoundingRectangle, HelpText, IsEnabled, etc.).

FSUIAExpandCollapse: Methods

: FSUIAExpandCollapse methods: Expand() and Collapse() --- control expansion and collapse actions.

FSUIAExpandCOllapse: Properties

: FSUIAExpandCollapse properties: ExpandCollapseState --- indicates whether an element is expanded or collapsed.

FSUIAGrid: Methods

: FSUIAGrid methods/properties: grid operations and attributes (GetItem(row,col) to access grid cells).

FSUIAGrid: Properties

: FSUIAGrid properties: ColumnCount and RowCount --- grid size attributes.

FSUIAGridItem: Properties

: FSUIAGridItem properties: Column, Row, ColumnSpan, RowSpan, ContainingGrid --- indices and containment info for grid items.

FSUIAInvoke: Methods

: FSUIAInvoke methods: Invoke() --- programmatically invoke control actions (e.g., simulate button click).

FSUIAItemContainer: Methods

: FSUIAItemContainer methods: item location operations (FindItemByProperty to locate child elements by property).

FSUIALegacyIAccessible: Methods

: FSUIALegacyIAccessible methods: DoDefaultAction, GetIAccessible, GetSelection, Select, SetValue --- MSAA interoperability methods.

FSUILegacyIAccesible: Properties

: FSUILegacyIAccessible properties: ChildID, DefaultAction, Name, Role, State, Value --- MSAA property mappings.

FSUIAMultipleView: Methods

: FSUIAMultipleView methods: GetSupportedViews, GetViewName, SetCurrentView --- control-specific view management.

FSUIAMultipleView: : Properties

: FSUIAMultipleView properties: CurrentView --- the control-specific identifier for the active view.

FSUIARangeValue: Methods

: FSUIARangeValue methods: SetValue(int) --- programmatically set control value.

FSUIARangeValue: Properties

: FSUIARangeValue properties: IsReadOnly, LargeChange, Minimum, Maximum, SmallChange, Value --- range value details.

FSUIARect: Properties

: FSUIARect properties: Bottom, Left, Right, Top --- rectangle edge coordinates.

FSUIAScroll: Methods

: FSUIAScroll methods: Scroll and SetScrollPercent --- scroll content horizontally/vertically; parameters described.

FSUIAScroll: Properties

: FSUIAScroll properties: horizontal/vertical scroll flags and percentages (HorizontallyScrollable, HorizontalScrollPercent, VerticalScrollPercent, etc.).

FSUIAScrollItem: Methods

: FSUIAScrollItem methods: ScrollIntoView() --- scroll container to display the item in the viewport.

FSUIASelection: Methods

: FSUIASelection methods: GetSelection() --- retrieve the selected elements in a container.

FSUIASelection: Properties

: FSUIASelection properties: CanSelectMultiple, IsSelectionRequired --- selection capabilities of a container.

FSUIASelectionItem: Methods

: FSUIASelectionItem methods: AddToSelection, RemoveFromSelection, Select --- selection manipulation for an item.

FSUIASelectionItem: Properties

: FSUIASelectionItem properties: IsSelected, SelectionContainer --- selection state and container reference.

FSUIASpreadsheet: Methods

: FSUIASpreadsheet methods: GetItemByName(string) --- access spreadsheet cells by name (e.g. "A1").

FSUIASpreadsheetItem: Methods

: FSUIASpreadsheetItem methods: GetAnnotationObjects, GetAnnotationTypes --- retrieve annotations associated with a spreadsheet cell.

FSUIASpreadsheetItem: Properties

: FSUIASpreadsheetItem properties: Formula --- cell formula text and related metadata.

FSUIAStyles: Properties

: FSUIAStyles properties: ExtendedProperties, FillColor, Shape, StyleName --- document style attributes.

FSUIASynchronizedInput: Methods

: FSUIASynchronizedInput methods: StartListening and Cancel --- manage provider listening for mouse/keyboard input.

FSUIATable: Methods

: FSUIATable methods: GetColumnHeaders and GetRowHeaders --- retrieve header elements for a table.

FSUIATable: Properties

: FSUIATable properties: RowOrColumnMajor --- primary traversal direction of the table.

FSUIATableItem: Methods

: FSUIATableItem methods: GetColumnHeaderItems, GetRowHeaderItems --- header associations for a table cell.

FSUIAText: Methods

: FSUIAText methods: text-range and selection helpers (GetCaretRange, GetSelection, RangeFromPoint, RangeFromChild).

FSUIAText: Properties

: FSUIAText properties: DocumentRange and SupportedTextSelection --- document text range and selection support.

FSUIATextChild: Properties

: FSUIATextChild properties: TextContainer and TextRange --- child text container and its range.

FSUIATextEdit: Methods

: FSUIATextEdit methods: GetActiveComposition and GetConversionTarget --- IME composition-related operations.

FSUIATextRange: Methods

: FSUIATextRange methods: Clone, FindText, GetText, Move, Select, ScrollIntoView --- text-range operations and utilities.

FSUIAToggle: Methods

: FSUIAToggle methods: Toggle() --- cycle control toggle states.

FSUIAToggle: Properties

: FSUIAToggle properties: ToggleState --- current state of a toggle control.

FSUIATransform: Methods

: FSUIATransform methods: Move(x,y), Resize(w,h), Rotate(deg), Zoom(percent) --- transform operations for movable/resizable elements.

FSUIATransform: Properties

: FSUIATransform properties: CanMove, CanResize, CanRotate, CanZoom, ZoomLevel/ZoomMaximum/ZoomMinimum --- transform capabilities and limits.

FSUIATreeWalker: Methods

: FSUIATreeWalker methods: navigation helpers (GoToFirstChild, GoToNextSibling, GoToParent, GoToPriorSibling).

FSUIATreeWalker: Properties

: FSUIATreeWalker properties: Condition and CurrentElement --- tree-walking condition and current element reference.

FSUIAValue: Methods

: FSUIAValue methods: SetValue(string) --- set an element's value programmatically.

FSUIAValue: Properties

: FSUIAValue properties: IsReadOnly and Value --- value access and mutability.

FSUIAVirtualizedItem: Methods

: FSUIAVirtualizedItem methods: Realize() --- materialize a virtualized item into a full UIA element.

FSUIAWindow: Methods

: FSUIAWindow methods: Close, SetWindowVisualState, WaitForInputIdle --- window management operations.

FSUIAWindow: Properties

: FSUIAWindow properties: CanMaximize, CanMinimize, InteractionState, IsModal, IsTopmost, VisualState --- window capabilities and state.

Events

Scripts may register to receive UIA events by calling one of the add-event-handler methods on an FSUIA object.

Var Object events = CreateObjectEx ("FreedomSci.UIA", False,
"UIAScriptAPI.x.manifest" );\
Var Object element = events.GetFocusedElement();\
events.AddPropertyChangedEventHandler(UIA\_NamePropertyId, element,
TreeScope\_Element \textbar{} TreeScope\_Descendants )

The same FSUIA object must then be passed to the JAWS built-in Function ComAttachEvents:

ComAttachEvents( events, "UIA\_" );

Now, when a UIA property changed event occurs for the name property, the function UIA_PropertyChangedEvent in the JAWS scripts will be called.

Finally, to stop receiving events, the FSUIA object must be set to a null object.

Var Object nullObject;
events = nullObject;

Event callback functions

The following table gives the names and parameter types of the available event callback functions.

: Event callback functions: names, parameter types, and short descriptions (AutomationEvent, FocusChangedEvent, PropertyChangedEvent, StructureChangedEvent, TextEditTextChangedEvent).

Constants

Unlike variables, constants do not change value. They are most useful for hard-to-remember strings of characters or long numbers. Constants should have mnemonic names since it is easier to remember a name than a number or long string of characters.

The Freedom Scientific Scripting language has no restrictions as to how many constant names you assign to a particular value. For example, in the default JAWS constants file, HJConst.jsh, there are constants named True and On -- both of which hold the value 1. It is more intuitive to understand a code statement that checks a condition for values of True or On than a code statement that checks for the integer 1. Once you declare the constants, JAWS recognizes all of the constant names with the same value.

If the string of characters being stored in a constant includes Unicode characters, ensure that the script files where the constants are declared and utilized are formatted properly for UTF-8. For more information on UTF-8, see Formatting Script Files for UTF-8.

Advantages of Using Constants

There are several advantages to using constants in scripts:

It is easier to remember a constant name than its value. And it is more intuitive when the constant name is a readable word like "True" or "on".

It is much easier to maintain code when constant names are used rather than hard-coded strings of characters or hard-coded integer values.

Changing the value of a string of characters or an integer that is used throughout code is much easier to maintain if that value is stored in a constant. The change is made just in one place. In other words, simply changing the constant declaration affects the code wherever that constant is applied.

The Freedom Scientific Scripting language does not support direct declaration of a negative integer constant, as in "VBTrue = -1". However, it does support using hexadecimal representation of any integer, including negative integers, as in "VBTrue = 0xffffffff". Note: This is because the Scripting language uses four bytes to store numbers, and if the highest bit is a 1, the numbers are signed so that they are negative.

Declaring Constants

You may declare constants anywhere outside of a script or function, but conventionally, they are declared at the beginning of a script source (.jss) file or in a header (.jsh or .jsm) file. Begin declaration of constants either with the keyword, Const for simple constants, or with the keyword pattern that generates a block of message constants. A message block of constants begins with the keyword, Messages, and ends with the keyword, EndMessages.

Simple Constants

For simple constants, place each constant declaration on a separate line followed by a comma, except for the last one. For example:

Const
    True = 1,
    False = 0,
    On = 1,
    Off = 0,
    FS = "Freedom Scientific",
    FSZipCode = "33764" ; since this is used as a String, Not For computing

Formatted Message Constants

Although you may declare string constants such as for window names, window classes, and so on, it is much more practical to declare message constants as formatted strings. This ensures that when JAWS processes message constants, they are indicated properly in speech, Braille, and in the virtual viewer, if applicable. Furthermore, formatted message constant declarations may include replaceable parameters so that varied information may populate messages when JAWS processes them, depending on conditions you determine through scripts and functions or through events. When declaring and using message constants, especially those you wish to format with replaceable parameters in them, be sure to:

• Populate the message constant with text (it can be long and have multiple paragraphs), including spaces, tabs, and hard returns.

• If desired, create the text of the message constant with the "%" character followed by a number to indicate a replaceable parameter within the message. You may use multiple replaceable parameters in the same message.

• Use the FormatString function in order to populate the message with appropriate replacement strings for the replaceable parameters in the message constant. The FormatString function returns a string that is already formatted properly for you to pass to a function that outputs formatted strings .

• Utilize only functions that process formatted strings correctly, or enclose the string parameters in a call to the FormatString function. For example, if you pass the SayMessage function a formatted string, it cannot process any replaceable parameters; so the output may yield unexpected results. Instead, use one of the functions that processes formatted strings. These include:

  • SayFormattedMessage ()

  • SayFormattedMessageWithVoice ()

  • UserBufferAddFormattedMessage ()

For a complete list of formatting functions, see the String Functions category page of the Reference Guide called Strings Functions and Text Format Functions.

Syntax of Formatted Messages

Use the following format for message constants:

The keyword, "Messages"

On a new line, the name of the constant beginning with the "at" ("@") symbol.

As many lines as necessary for the content of the message, including hard returns, to generate multiple paragraphs, even replaceable parameters.

On a new line, a double "at" ("@@") symbol to end the constant declaration.

On a new line, the keyword, "endMessages" to end the block of message constants.

You may repeat the pattern for as many message constants as you wish of "@" followed by message constant name, constant message itself, and a double "@" symbol to complete each message constant within the block beginning and ending with the keywords, Messages and EndMessages. It is good practice to begin the names message constants with the letters "msg" to distinguish them from other types of string constants. Also, if the constant takes replaceable parameters, place a comment above each message constant declaration explaining the purpose of the replaceable parameter.

Messages
@msgFSHeadquarters
11800 31st CT North
St. Petersburg, FL
@@
@msgFSPhoneNumbers
800-444-4443
or
727-803-8000
@@
;For msgMyWorkplace, %1 is the name of the workplace.
@msgMyWorkplace
I work at %1.
@@
EndMessages

Using a Header File to Store Constants

Unless the constants you are declaring apply only to the current script source file, it is more practical to declare constants in a script header file. Typically, a header file has an extension of .jsh or .jsm. When you use a header file to declare constants, you must refer to that header file with an "Include" statement in the script source file where you want to use the constants. For examples, see the script source file that ships with the JAWS Shared user\settings(Language) folder. One of the "include" statements for this file is "hjconst.jsh". Another is "common.jsm". Since the constants declared in these header files are in the default script source file, it means that you can use all of them in any of the default scripts and user-defined functions.

If you add an "Include" statement for the HJConst.jsh file within an application-specific script source file, for example, those constants become available to that script source file.

Collection Type Variables

Description

Collection New

A collection is a data type that may contain members of any type, and whose members are accessed by means of a key. Members of a collection need not be of the same data type as each other. After declaring a collection, create it using the keyword, "New"

Items of a collection spring into existence the first time they are assigned. Assigning a collection member to a value makes that member's type the type of the value being assigned. Each member in a collection has a key of type string, and each member can contain a value of any data type.

You may access members of a collection by using the dot operator followed by the key name, or by the key as a string enclosed in square brackets.

Syntax

Var 
	Collection col
Let col = New Collection
Let col.item = value

• Col is a collection variable being declared and created.

• Item is the name (or key) of a member in the collection being created.

• Value is the value being assigned to a member of the collection.

Remarks

Declaring a collection does not create it. You must create the collection by means of the New statement.

Collection members are stored in alphabetical order of the member keys. If you know the name (or key) of a member in a collection, you can assign or retrieve that name (or key) using the dot operator. If the name (or key) of a collection member is enclosed in quotes or is contained in a variable, you must access that member using the variable name or quoted string enclosed inside square brackets instead of using the dot operator.

Collections are always passed to functions by reference.

::: .hint Assigning one collection to another results in two variables referring to the same collection. When retrieving a collection member into another variable, the script code must ensure that the value retrieved is stored in the appropriate type of variable. Retrieving a nonexistent item does not generate an error. :::

Code Sample

Script TestCollections ()
	CollectionOfFruitCollections()
EndScript

Void Function FRTINIT(Collection Frt, String Type, String Prep, String Cut)
Let Frt.Type = Type
Let Frt.Prep = Prep
Let Frt.Cut = Cut
EndFunction

Void Function CollectionOfFruitCollections()
Var
    Collection Fruit,
    Collection frt,
    String key,
    String sMsgFruitInfo
    sMsgFruitInfo = "%2 and %3 the %1."
Let Fruit = New Collection
Let frt = New Collection
FRTINIT(frt,"Bananas","peel","slice")
Let Fruit.Bananas = frt
Let frt = New Collection
FRTINIT(frt,"Apples","core","slice")
Let Fruit.Apples = frt
Let frt = New Collection
FRTINIT(frt,"Strawberries","sugar","halve")
Let Fruit.Strawberries = frt
Let frt = New Collection
FRTINIT(frt,"Oranges","peel","section")
Let Fruit.Oranges = frt
Let frt = New Collection
FRTINIT(frt,"Pears","peel","slice")
Let Fruit.Pears = frt
Let frt = New Collection
FRTINIT(frt,"Cherries","hull","chop")
Let Fruit.Cherries = frt
Let frt = New Collection
ForEach key in Fruit
    SayFormattedMessage(ot_line,
    FormatString(sMsgFruitInfo,
    Fruit[key].Type,
    Fruit[key].Prep,
    Fruit[key].Cut))
EndForEach
EndFunction

Strings Functions

A String function provides, processes, or returns information about a string of characters. One common use for these functions is to manipulate a string of characters in some way: chopping characters from the beginning or the end of a string, comparing two strings, parsing a string from a delimited list of strings, etc. JAWS uses this information to determine what to speak and display in Braille, for comparison purposes, and so on. The Freedom Scientific Scripting language is rich with Strings functions for you to utilize in conjunction with many of the Say functions, such as SayFormattedMessage, for example. String functions may also be used to read from or write to an INI-style file. Some examples of String functions include:

• FindString

• FormatString

• IntToString

• StringToInt

• StringSegment

• StringCompare

• StringTrimCommon

For a complete listing of Strings functions, see the topics in this category book of the Reference Guide. Code Sample Often, string functions are used for comparing window classes, window names, etc. For instance, you may obtain the window title with a command to JAWS, Insert + t. But what if you just want the name of the document without the application name. In the below code sample, the script manipulates some string functions to obtain the title of an existing Notepad document without speaking or flashing in Braille the name of the application. There are numerous ways to accomplish this. The code sample is just meant to show how you might utilize string functions to obtain a simple piece of information.

It is assumed that the script is being processed in the Notepad.jss script source file and compiled in the Notepad.jsb script binary file.

To set up the example, open Notepad into an existing document. then run the script from the document window of Notepad.

Script MyStringTest ()
Var
    Handle hReal,
    String sRealName,
    Int iRealLength,
    String sTitle
hReal = GetRealWindow (GetFocus ())
sRealName = GetWindowName (hReal)
iRealLength = StringLength (sRealName) ; the length of the entire real window name
; The next statement uses a combination of String functions:
; The StringContains Function returns an integer representing the location where the real window name and the name of the application begin To match.
; For sample purposes only, the part of the String that represents the application name is hard-coded here.
; But hard-coding strings is typically Not recommended because it is hard To maintain.
; In order To chop Off the application name from the entire real window name, we must take the lenth of the window name and subtract the integer that StringContains returns from it.
; Then we can chop this number Off from the real window name, and place the remaining String into the variable, sTitle.
sTitle = StringChopRight (sRealName, (iRealLength - StringContains (sRealName, " - Notepad")))
SayMessage (ot_JAWS_message, sTitle)
EndScript

Text Format Functions

A Text Format script or function provides or returns information about Text Format activities caused by user interaction or automatically updated by an event. JAWS uses this information to determine whether to speak and display Text Format information in Braille, for comparison purposes, and so on.

Text Format information may be about the font name, point size, or attributes of a character, about the attributes of a control, whether the text is intended to be read right to left instead of left to right, etc.

Some scripts that ship with JAWS fall into the category of Text Format, such as the script for SayFont, for example. However, the focus of the present discussion is on functions related to Text Format that you may call from your own scripts or that you may overwrite from those in default.jss or from the built-in functions.

Some examples of Text Format functions include:

• AttributesChanged

• IntToAttribName

• AttributeEnumerate

• GetCharacterAttributes

• IsRtlChar

For a complete listing of Text Format functions, see the topics in this category book of the Reference Guide.

Code Sample

In the below code sample, the script finds the first character in the text that is bolded.

To set up the example, simply type some text into the Wordpad document window. Using the Font options in the Home ribbon, change some text, not at the very top of the file, to be in bold. Then move to the top of the file and run the script. If bold text is found, the JAWS cursor moves to it, and the PC cursor is routed to the position and reactivated. Then the script confirms the font and speaks the current line where the bold text begins.

Take care when working with the Wordpad.jss script source file because it already contains scripts and functions by default that ship with JAWS. Place your sample code at the very bottom of the file. And make sure to remove this overwritten Wordpad.jss and its associated overwritten Wordpad.jsb and Wordpad.jkm files from your user Settings(language) folder when done testing. It is assumed that the script is being processed in the Wordpad.jss script source file and compiled in the Wordpad.jsb script binary file.

Script MyAttributesTest ()
Var
    Int attributes
If GetWindowClass (GetFocus ()) == cwc_RichEdit50W && ! DialogActive () ; This is the Wordpad document window.
    If FindFirstAttribute (attrib_bold,True) ; Restrict the search To the document window.
        RoutePCToJAWS ()
        PCCursor ()
        SayFont ()
        SayLine()
    EndIf
EndIf
EndScript

Array Type Variables

Keywords:

• IntArray

• StringArray

• HandleArray

• ObjectArray

• VariantArray

• New

Description

An array is a data type that contains a fixed number of elements, and whose elements are accessed by means of an integer index. Arrays are created to hold the data type for which they are intended. For example, IntArrays hold integers, StringArrays hold strings, etc. A VariantArray holds data of type variant, which means that it may hold any data type.

After declaring an array, create it and specify the size of the array using the keyword, New. The array is fixed to be the size specified at the time it is created. Multiple dimensions may be created, and can be separated with a comma.

You may access elements in an array by means of indices enclosed in square brackets.

Syntax

Var
    TypeArray xArray
Let xArray = New TypeArray(size)
Let xArray[i] = value
Var
    TypeArray xyArray
Let xyArray = New TypeArray(sizeX,sizeY)
Let xyArray[i,j] = value

• TypeArray is any of the types of arrays that may be created-IntArray, StringArray, HandleArray, ObjectArray, or VariantArray.

• XArray is an array variable being declared and created. It is a one-dimensional array.

• Size is the number of elements in the one-dimensional array xArray.

• XyArray is an array variable being declared and created. It is a one-dimensional array.

• SizeX is the number of elements in the first dimension of the one-dimentional array xyArray.

• SizeY is the number of elements in the second dimension of the one-dimensional array xyArray.

• I is an index into the array.

• J is an index into the second dimension of the one-dimensional array.

• Value is a value assigned to an element of the array.

Remarks

Declaring the array does not create it. Creation of the array must be done by means of the New statement.

A VariantArray can contain items of any type. Collections can be elements of an array if that array is of type VariantArray. The script code should take care to manage the types of data in variant arrays appropriately.

Arrays are always passed to functions by reference.

Assigning one array to another will result in two variables referring to the same array.

There is no compile-time error if the wrong number of index expressions is specified for an array, or if an index attempts to access outside the bounds of the array.

There is also no runtime error notification, but the error may cause JAWS to lock. Therefore, take care to avoid illegal index references.

Code Sample

The below nonsense example shows the power of arrays and in fact of the VariantArray type.

Messages
;For sMsgGemInfo, %1 is the gem type, %2 the jewelry, %3 the occasion, %4 the number, and %5 the shape
@sMsgGemInfo
%5 %1 %2s For the %4 %3s
@@
EndMessages

Script TestArrays ()
	ArrayOfGemsCollections()
EndScript

Void Function GmsInit(Collection Gms, String Name, String Type, String Occasion, Int Number, String Shape)
Let Gms.Name = Name
Let Gms.Type = Type
Let Gms.Occasion = Occasion
Let Gms.Number = Number
Let Gms.Shape = Shape
EndFunction

Void Function ArrayOfGemsCollections()
Var
    VariantArray Gems,
    Collection gms,
    Int i,
    String sMessage
Let Gems = New VariantArray[5]
Let gms = New Collection
gmsInit(gms,"emerald","pendant","birthday",6,"oval")
Let Gems[1] = gms
Let gms = New Collection
GMSInit(gms,"diamond","ring","engagement",7,"square-cut")
Let Gems[2] = gms
Let gms = New Collection
GMSInit(gms,"sapphire","bracelet","anniversary",9,"round")
Let Gems[3] = gms
Let gms = New Collection
GMSInit(gms,"ruby","pairs of earring","graduation",8,"tear-drop")
Let Gems[4] = gms
Let gms = New Collection
GMSInit(gms,"pearl","necklace","wedding",20,"cultured")
Let Gems[5] = gms
Let gms = New Collection
For i = 1 To 5
    SayFormattedMessage(ot_line,
    FormatString(sMsgGemInfo,
    Gems[i].name,
    Gems[i].type,
    Gems[i].occasion,
    Gems[i].Number,
    Gems[i].Shape)
    )
EndFor
For i = 1 To 5
    Let sMessage = FormatString(sMsgGemInfo,
    Gems[i].name,
    Gems[i].type,
    Gems[i].occasion,
    Gems[i].Number,
    Gems[i].Shape)
    TypeString (sMessage + cscBufferNewLine)
EndFor
EndFunction

Operators

The Freedom Scientific Scripting language supports the use of many operators. Operators are grouped by usage at heading level 2 elements, and each operator within that group is at a heading level 3 element along with its relevant descriptive information. Where the name of the operator is a punctuation character symbol or group of characters, it is spelled out in parentheses after the character or group of characters.

Unless otherwise specified, the version where the operator was first made available to the Scripting language was JAWS 4.5.

Arithmetic Operators

Operator: + (plus) Use the + (plus) operator in equations to indicate addition or to concatenate strings enclosed in quotation marks.

Operator: - (minus) Use the - (dash) minus operator in equations to indicate subtraction.

Operator: * (asterisk) Use the * (asterisk) operator in equations to indicate multiplication.

Operator: / (slash) The / slash operator is used in equations to indicate division.

Operator: % (percent) The result of the modulus operator (%) is the remainder when the first operand is divided by the second.

Comparison Operators

Operator: == (double equal) The == (double equal) operator asks whether the first condition is equal to the second condition.

Operator: != (is not equal to) The != (exclamation mark equal to) operator asks whether the first condition is not equal to the second condition.

Operator: >= (greater than or equal to) The >= (greater than or equal to) operator asks whether the first condition is greater than or equal to the second condition.

Operator: > (greater) The > (greater than) operator asks whether the first condition is greater than the second condition.

Operator: <= (less than or equal to) The <= (less than or equal to) operator asks whether the first condition is less than or equal to the second condition.

Operator: < (less than) The < (less than) operator asks whether the first condition is less than the second condition. Logical Operators

Operator: && (double ampersand) The && (double ampersand) operator asks whether the first condition is true, and additionally whether the second condition is true.

Operator: || (double vertical bar) The || (double vertical bar) operator asks whether the first condition is true, or if the second condition is true. If the first condition is true, the second condition is not evaluated. It does not matter which condition is true

Operator: ! (Exclamation point) The ! (exclamation mark) operator negates the expression to which it is applied. It is equivalent to the "not" keyword.

Bitwise Operators

Operator: & (ampersand) The & (ampersand) bitwise operator compares each bit of its first operand to the corresponding bit of its second operand. If both bits are 1, the corresponding result bit is set to 1. Otherwise, the corresponding result bit is set to 0.

The best example of how to use this operator is in the NewTextEvent function in default.jss. In this function, it is used for a binary comparison of two binary numerical values. The value of nAttibutes is a multiple digit binary numerical value that indicates all the attributes applying to the buffer string. Each attribute is indicated by whether a certain bit in the byte is turned on. The & operator returns all values that exist in both numerical values. For example, if the value of nAttributes is 01001010, then the seventh bit in the result byte of nAttributes & ATTRIB_HIGHLIGHT is set to 1 (ATTRIB_HIGHLIGHT = 64 or 01000000 binary). The second bit in the result byte of nAttributes & ATTRIB_BOLD is set to 1 (ATTRIB_BOLD = 2 or 00000010 binary). The fourth bit in the result byte of nAttributes & ATTRIB_UNDERLINE is set to 1 (ATTRIB_UNDERLINE = 8 or 00001000 binary). But the third bit in the result byte of nAttributes & ATTRIB_ITALIC is set to 0 since ATTRIB_ITALIC is 4 or 00000100 binary and the third bit in the nAttributes byte is 0.

Operator: | (vertical bar) The | (bitwise vertical bar) operator compares each bit of its first operand to the corresponding bit of its second operand. If either bit is 1, the corresponding result bit is set to 1. Otherwise, the corresponding result bit is set to 0.

This operator does a bit-by-bit comparison of two numerical values which is similar to that of the & operator. For example, the statement 00100110 | 11000000 returns 11100110.

Operator: ~(tilde) Use the ~(tilde) operator with & and | (the "and" and "vertical bar") bitwise operators to mask off or exclude a bit from being processed. A good example is in default.jss in the ObjStateChangedEvent function in the following statement:

IndicateControlState(iObjType,nState& (CTRL_CHECKED|CTRL_UNCHECKED))

The statement ensures that if the control is partially checked, the unchecked and checked states are not processed and therefore not indicated by JAWS.

Operator: << (less than less than) Bitwise left shift. Use to shift the bits in a bitwise pattern left. Often, this is done to move a bit to a specific position in a bit set before performing some other bitwise operation.

Operator >> (greater than greater than) Bitwise right shift. Use to shift the bits in a bitwise pattern right. Often, this is done to move a bit to a specific position in a bit set before performing some other bitwise operation.

Miscellaneous Operators

Operator: = (equals) Use this operator to assign a value to a variable.

Operator: . (dot) Use the dot operator to assign or retrieve the name of an item in a collection when the name of the item is known. For example, you can use Months.January to access the item called January in the Months collection. But you may not use The dot operator to access the name of the item if the name of the item is enclosed in quotes, contained in a variable, or is returned by a function call.

Version: This operator is available as of JAWS 11.

Operator: New Use the New operator to create an instance of an array of collection. You must specify the size and dimensions of the array when creating a new array and when creating an instance of the array.

Version: This operator is available as of JAWS 11.

Operator: [] (left bracket, right bracket) Use brackets to specify the size of an array when creating the array . Also, you may use them to access elements of an array. If the array is multi-dimensional, you must separate the index for each dimension by commas. For example, [3,5] specifies the element on the third row and fifth column of the array.

Additionally, use brackets to assign or retrieve the name of an item in a collection if the name of the item is enclosed in quotes, contained in a variable, or is returned by a function call.

Version: This operator is available as of JAWS 11.

Operator: () (left-parenthesis right-parenthesis)

Use to enclose a parameter list for a function call, or to establish order of precedence.

Event Function Reference

This reference gives you basic information about event functions utilized by JAWS, MAGic and PAC Mate Omni. Most of these functions can be found in the default script file, Default.jss. You can view the code of each function by opening the default script file within the Script Manager.

AppWillNotSpeakEvent

Description This function is performed when an unauthorized application is opened in restricted mode. The function produces the "Cannot speak in Restricted Mode" message when authorization is either not found or inaccurate.

Syntax AppWillNotSpeakEvent (strApp)

Parameters strApp - String; the name of the application that will not speak in restricted mode

Returns None

Category Application info

AutoFinishEvent

Description This event Function is performed when the application is closed. The function is also performed when the application is switched from or looses focus, as with ALT + TAB.

Syntax AutoFinishEvent ()

Parameters None

Returns None

Category Application info

AutoStartEvent

Description This event Function is performed when the application is started. This function is also performed when the application is switched to or gets focus, as with ALT + TAB.

Syntax AutoStartEvent ()

Parameters None

Returns None

Category Application info

BottomEdgeEvent

Description This function is performed when the active cursor attempts to move beyond the bottom edge of the active window. The function receives the window handle as a parameter.

Syntax BottomEdgeEvent (WinHandle)

Parameters WinHandle - handle; handle of the window whose bottom edged was reached

Returns None

Category Cursors

CellChangedEvent

Description This function is performed when the cursor moves from one cell in a table to a new cell in either the same table, a nested table or parent table.

Syntax CellChangedEvent (nNewCol, nNewRow, nNewNesting, nNewRowColCount, nPrevCol, nPrevRow, nPrevNesting, nPrevRowColCount)

Parameters

nNewCol - integer; the number of the new column

nNewRow - integer; the number of the new row

nNewNesting - integer; the number of the new nesting

nNewRowColCount - integer; number of the new row and column counts

nPrevCol - integer; the number of the previous column

nPrevRow - integer; number of the previous row

nPrevNesting - integer; the number of the previous nesting

nPrevRowColCount - integer; number of the previous row and column counts

Returns None

Category Screen text

ClipboardChangedEvent

Description This event is performed when the contents of the Windows clipboard is replaced.

Syntax ClipboardChangedEvent ()

Parameters None

Returns None

Category Clipboard

CursorShapeChangedEvent

Description This function is performed when the mouse pointer changes shape. The name of the new shape is passed to this function via a string variable.

Syntax CursorShapeChangedEvent (CursorType)

Parameters CursorType - String; the string value for the current cursor type

Returns None

Category Cursors

DialogPageChangedEvent

Description This function is performed when switching between pages of a multipage dialog box.

Syntax DialogPageChangedEvent(hwndNewPage, hwndOldPage)

Parameters

hWndNewPage - Handle; handle of the new page in a multi page dialog box

hWndOldPage - Handle; handle of the old page in the multi page dialog box

Returns None

Category Dialogs

DocumentLoadedEvent

Description This function is performed when a document is loaded in Internet Explorer. The function starts SayAll when the web page loads.

Syntax DocumentLoadedEvent ()

Parameters None

Returns None

Category HTML

FocusChangedEventEx

Description This function is performed when focus moves between applications, dialogs, dialog controls, or to another item within a control with child items. The function must determine the type of focus change and then call the proper event to handle the type of focus change that has occurred.

Syntax FocusChangedEventEx (hWndFocus, nObject, nChild, hWndPrevFocus, nPrevObject, nPrevChild, nChangeDepth)

Parameters

hWndFocus - handle; the handle of the window that has received the focus

nObject - integer; the number of the object that has received the focus

nChildObject - integer; the number of the current child object

hWndPrevFocus - handle; the handle of the window that previously had the focus

nPrevObject - integer; the number of the object that previously had the focus

nPrevChild - integer; the number of the child object that previously had the focus

nChangeDepth - integer; the change depth (number of levels in the window hierarchy affected by the change)

Returns None

Category Window

FocusChangedEvent

Description This function is performed when focus moves between applications, dialogs, and dialog controls. The window handles of the previous and current windows are passed to this function. This function calls either SayWindowTypeAndText, SayFocusedWindow or SayFocusedObject in order to ensure that the active control is properly spoken.

Syntax FocusChangedEvent (FocusWindow, PrevWindow)

Parameters

FocusWindow - Handle; handle of the window that has received the focus

PrevWindow - Handle; handle of the window that previously had the focus

Returns None

Category Window

FocusPointMovedEvent

Description This function is performed when the pixel location of the blinking caret or highlight changes. Examples of focus changes include moving focus from one control to a different control within an application or dialog and moving the insertion point through a document. The pixel location is determined by video resolution as in row and column coordinates. Processor intensive code should not be included in this function as it is performed each time the PC cursor moves.

Syntax FocusPointMovedEvent (nX, nY, nOldX, nOldY, Unit, nDir, nTimeElapsed)

Parameters

nX - Integer; current horizontal coordinate of the PC cursor

nY - Integer; current vertical coordinate of the PC cursor

nOldX - Integer; previous horizontal coordinate of the PC cursor

nOldY - Integer; previous vertical coordinate of the PC cursor

nUnit - Integer; the movement unit as constant variables defined in hjconst.jsh

nDir - Integer; the direction of movement as constant variables defined in hjconst.jsh

nTimeElapsed - Integer; the amount of time (milliseconds) that has elapsed since the movement occurred

Returns None

Category Cursors

ForegroundIconicEvent

Description This event function is performed when all apps are minimized or closed and the focus is not placed on the desktop. More testing is needed before it is implemented.

Syntax ForegroundIconicEvent(HANDLE hwndForeground)

Parameters hwndForeground - Handle; handle of current foreground window (not focus)

Returns None

Category Window

ForegroundWindowChangedEvent

Description This function is performed each time a new real window gains focus. A real window is a window that has a title. Real windows are often application, and dialog main windows.

Syntax ForegroundWindowChangedEvent (newWindow)

Parameters NewWindow - Handle; handle of the new window

Returns None

Category Window

FormsModeEvent

Description This function is performed when forms mode is entered or exited. The function is passed a Boolean value indicating which of these actions has taken place. If bEntering is equal to true, forms mode has been turned on. If bEntering is equal to false, forms mode has been turned off

Syntax FormsModeEvent(bEntering)

Parameters bEntering - Integer; boolean value representing the current state of forms mode

Returns None

Category HTML

FrameLoadedEvent

Description This function is performed when a web page updates or loads content to a frame contained on the page. It is currently implemented in only the Internet Explorer script file.

Syntax FrameLoadedEvent (hDoc, sFrameName)

Parameters

hDoc - handle; the handle of the window of the parent document

sFrameName - string; the name of the frame being updated

Returns None

Category HTML

HelpBalloonEvent

Description This function is performed for Windows XP Help Balloons. In Windows XP two kinds of bubbles are displayed to provide help. The first is a ToolTip that is processed by the ToolTipEvent. The second is a Help Balloon that triggers this event.

Syntax HelpBalloonEvent(hwnd, sText)

Parameters

hWnd - Handle; the handle to the help balloon window

sText - String; the text of the help balloon

Returns None

Category Window

ItemNotFoundEvent

Description This event is performed when the item cannot be found in the Off Screen Model.

Syntax ItemNotFoundEvent (int hwnd)

Parameters hWnd - Integer; Window handle

Returns None

Category Screen text

JavaFocusChangedEvent

Description This function is performed when focus moves between Java applications, dialogs, and dialog controls.

Syntax JavaFocusChangedEvent (FocusWindow, PrevWindow)

Parameters

FocusWindow - handle; the handle of the window that has received focus

PrevWindow - handle; the window that previously had the focus

Returns None

Category Window

KeyPressedEvent

Description This function is performed when a keystroke is pressed. All key presses cause this function to fire. If the key is assigned to a script, then KeyPressedEvent is called before the script itself. Because this function will be called quite frequently, it is recommended that you refrain from intensive tasks that will be performed each time a keystroke is pressed.

Syntax KeyPressedEvent (nKey, strKeyName,IsBrailleKey, IsScriptKey)

Parameters

nKey - integer; numeric key value

strKeyName - string; key name as it is used in the key map file

IsBrailleKey - Integer; set to 1 if the key is on a Braille display

IsScriptKey - integer; set to one if the key is assigned to a script

Returns None

Category Keyboard

MagSendKeyEvent

Description If a MAGic key event is attached to a key in a key map file, then you can use this function to send the key event on to the MAGic interface. For example, when the key is pressed to toggle magnification, the KI_MAGONOFF needs to be passed on to the MAGic user interface for processing.

Syntax MAGSendKeyEvent (nKICode)

Parameters nKICode - integer; The code for the key event. These codes can be found in magcodes.jsh.

Returns Integer - If MAGic is not running, or nKICode is out of range, then the function will return FALSE. Otherwise, TRUE is returned.

Category MAGic

MenuModeEvent

Description This function is performed when the status of a menu changes. There are three menu modes as defined in HJCONST.JSH. They are: MENU_INACTIVE, MENUBAR_ACTIVE, and MENU_ACTIVE. This event receives the Handle of the menu and the mode of the menu as parameters.

Syntax MenuModeEvent (WinHandle, mode)

Parameters

WinHandle - Handle; handle of the menu

mode - Integer; the mode of the menu whose status has just changed

::: {#returns-21}

Returns

:::

None

::: {#category-22}

Category

:::

Menus

MouseMovedEvent

::: {#description-24}

Description

:::

This function is performed when the mouse is moved. This function is passed two integers. The first value specifies the x-coordinate at the position of the mouse pointer. The second parameter specifies the y-coordinate and the position of the mouse pointer.

::: {#syntax-22}

Syntax

:::

MouseMovedEvent (int x, int y)

::: {#parameters-22}

Parameters

:::

x - Integer; the horizontal position of the mouse pointer in pixels

y - Integer; the vertical position of the mouse pointer in pixels

::: {#returns-22}

Returns

:::

None

::: {#category-23}

Category

:::

Mouse

NewTextEvent

Description This function is performed when new text is written to the screen. When this function is called, it receives information pertaining to the newly written text. If the text was written in a frame, then the text is spoken according to the frame's echo setting. Otherwise the text is sent to SayHighlightedText () or SayNonHighlightedText ().

Syntax NewTextEvent (hwnd, buffer, nAttributes, nTextColor, nBackgroundColor, nEcho, sFrameName)

Parameters

hWnd - handle; Handle of the window containing the text that was written

Buffer - String; string containing the text that was written

nAttributes,- Integer; The attributes of the text that was written

nTextColor - Integer; The foreground color of the text that was written

nBackgroundColor - Integer; the background color of the text that was written

nEcho - Integer; the echo setting associated with this text

sFrameName - String; the name of the frame containing the newly written text if applicable

Returns None

Category Screen text

SayAllStoppedEvent

Description This function is performed when the SayAll function stops.

Syntax SayAllStoppedEvent ()

Parameters None

Returns None