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.