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.