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 (!)1 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 (!) operator2, 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.

1

This is often pronounced "bang" by JAWS and NVDA screenreaders

2

JAWS and NVDA pronounce this as "bang" by default