Defining Functions

Vocola supports calling user-defined functions as well as built-in functions. If you find yourself using the same action sequence in several commands, defining a function can make the commands more concise and understandable.

For example, consider these three commands to change font properties in Notepad:

Font Size 6..72           = {Alt+o}f WaitForWindow(font) {Alt+s} $1 {Enter};
Font (Arial|Courier)      = {Alt+o}f WaitForWindow(font) {Alt+f} $1 {Enter};
Font Style (Regular|Bold) = {Alt+o}f WaitForWindow(font) {Alt+y} $1 {Enter};

The first command sets the font size—{Alt+o} opens the "Format" menu, f chooses the "Font" option to activate the font panel, WaitForWindow(font) waits for the font panel to be frontmost, {Alt+s} puts focus in the "Size" field, $1 inserts the spoken size, and {Enter} closes the font panel. The other two commands work similarly, and most of the command actions are duplicated.

We can simplify the commands by defining a function to activate the font panel:

This defines a function called getFontPanel which performs the first three actions of our commands. The commands can then be written more simply by calling this function:

Font Size 6..72           = getFontPanel() {Alt+s} $1 {Enter};
Font (Arial|Courier)      = getFontPanel() {Alt+f} $1 {Enter};
Font Style (Regular|Bold) = getFontPanel() {Alt+y} $1 {Enter};

These commands still contain some duplication. For maximum conciseness we could define our function differently, using arguments:

setFontProperty(field, value) := {Alt+o}f WaitForWindow(font) 
                                 {Alt+$field} $value {Enter};

With this function we generalize the idea of setting a font property, where the field argument specifies a field on the font panel and the value argument specifies the desired value. In the function's actions the references $field and $value retrieve the respective arguments. Using this function we can simplify our commands further:

Font Size 6..72           = setFontProperty(s, $1);
Font (Arial|Courier)      = setFontProperty(f, $1);
Font Style (Regular|Bold) = setFontProperty(y, $1);

Suggestion: name user-defined functions beginning with a lower-case letter to distinguish them from library function names (which begin with an upper-case letter).