5.5 Inserting Functions

You can insert both built-in and user-defined functions into the body of your scripts and functions. You can eliminate any spelling and syntax errors when you use this method to add these functions.

Activating the Insert Function Dialog

You can choose the Insert Function option from the Script menu or press CTRL+I to activate the Insert Function dialog.

Note: You cannot activate the Insert Function dialog unless the insertion point is within the body of a script or function.

When you activate the Insert Function dialog, the Function Name edit box is active. The dialog box also contains a Function Name list box, Description edit box, Function Returns edit box, and a number of different command buttons.

Selecting the Correct Function

You can type the name of the function you want to add to your script in the Function Name edit box. As you type the letters of the function name, JAWS moves the highlight to the matching name in the Function Name list box. When a matching function name is found, JAWS speaks the description of the function automatically.

If you have typed several letters in the Function Name edit box, but have not quite found the correct function, you can press TAB to move to the Function Name list box. This list box contains all built-in functions along with any user-defined functions from both the default and application script files. You can use your arrow keys to move up and down the list. You can also use first letter navigation to move immediately to a function that begins with a specific letter. For example typing S in this list box will move the highlight to the first function that begins with the letter S.

As in the Function Name edit box, JAWS speaks the description automatically as you move through this list.

Reviewing the Function Description

If you did not hear the entire description of the function, or would like to review the description of the function, you can press TAB until you reach the Description edit box. JAWS retrieves the description for functions built into JAWS from the documentation file for built-in functions, Builtin.jsd. For user-defined functions, JAWS retrieves the description from the appropriate application specific documentation file. You can use your arrow keys along with any of the other cursor navigation keys to read the information contained in this edit box.

Accepting the Function

After you have chosen the desired function, you can activate the Next button to continue inserting the function. You can activate this button by either pressing TAB until you reach the button and then press SPACEBAR or press ENTER while either the Function Name edit box or Function Name list box is active. If you move to and activate the Finish button, then the function is inserted directly into your script or function. However, you will not be prompted for any parameters that the function may require.

Adding Parameters

After you activate the Next button, the Script Manager prompts you for any parameters required by the function. The Parameter 1 edit box is active and the Script Manager reads the description of the parameter automatically. Like the description of the function, the Script Manager retrieves the parameter description from the appropriate documentation file.

You can choose to type in the value of the parameter, an appropriate variable type such as a string or integer, or insert a function whose return value will act as the parameter. If you choose to insert a function in the Parameter edit box, then you can activate the Insert Function button by pressing ALT+I. This action displays a second Insert Function dialog. You can select the function in the same manner as you did for the initial function.

You may find that some functions only require one parameter while others may require more. You can add the subsequent parameters in the same manner as you did the first. When you enter the last parameter, activate the Finish button to complete the insertion of the function. You need only to press ENTER from the last parameter edit box to activate this button. You can also press TAB to move to the button followed by SPACEBAR to activate it. In other words, the Insert Function dialog contains both Next and Finish buttons. You use the Next button to add the necessary parameters to the function, and you use the Finish button to complete the insertion of the function into your script.