Utterly Voice icon image Utterly Voice

Functions

All commands are built on functions that are called in order. Utterly Voice provides many built-in functions that you can use in your commands. This page describes how to use functions, and it describes each of the available functions.

Fixed and Utterance Arguments

Most functions require arguments. These arguments can be supplied as fixed arguments or as utterance arguments.

Fixed arguments are supplied to a function via the command settings. Every time a command is called, these fixed arguments are supplied to the function as defined in the command settings.

Utterance arguments are supplied to a function via words from an utterance.

A function can be supplied no arguments, just fixed arguments, just utterance arguments, or both fixed and utterance arguments. If both types of arguments are supplied, the fixed arguments come before the utterance arguments.

Function Settings

Each mode file contains a list of commands in the commands list collection. Each command has a map collection that contains a functions setting that is a list collection. The functions in this list are called in order when the command is executed. A function has the following settings:

Setting Type Description
name String The name of the function to call.
fixedArguments List Collection Optional list of fixed arguments for the function. This is a list of strings. If not provided, no fixed arguments are supplied to the function.
utteranceArguments Number Optional number of arguments that should be acquired from the utterance. If this number is greater than the number of words left in the utterance, the available words will be provided to the function. If you want the remainder of the utterance words to be supplied as function arguments, set this to 100. If not provided, no utterance arguments are supplied to the function.

Examples

The quit utterly voice command in the global mode calls the quit function with no arguments:

The type escape command in the basic mode calls the keyPress function with one fixed argument:

The title command in the basic mode calls the title function with 100 utterance arguments (the remainder of utterance words):

The scroll up command in the basic mode calls the mouseScroll function with one fixed argument and one utterance argument:

The mouse position command in the basic mode calls the toggleMode function with two fixed arguments, then calls the openMouseGuide function with one fixed argument:

Function Descriptions

The following functions are available to use in commands:

Function Name Description Arguments
allCaps Types arguments in all uppercase. One or more words to be typed in uppercase.
autoScrollStart Starts automatic scrolling. Also see autoScrollStop. The first argument is the number of seconds between scrolls in the range 1-100.

The second argument is either "up" or "down".

The third argument is an integer number of scroll ticks in the range 1-10.
autoScrollStop Stops automatic scrolling. Also see autoScrollStart. None.
bankCopy Copies the content from the clipboard to a named bank. Also see bankPaste. The name of the bank to save the copied content to.
bankPaste Pastes the content from the named bank. Also see bankCopy. The name of the bank to retrieve the content from.
bumpy Types arguments in BumpyCase. One or more words to type in BumpyCase. If "stop" is provided as an argument, the function completes.
camel Types arguments in camelCase. If "stop" is provided as an argument, the function completes. One or more words to type in camelCase.
closeMouseGuide Closes the mouse guide. If a mouse action was supplied when opening the guide, the mouse action occurs after the guide closes. Also see openMouseGuide and updateMouseGuide. The only argument is optional and describes a particular mouse action that should occur when the guide window closes. This will override a mouse action provided to openMouseGuide. The value is one of "left" (left click), "double" (double click), "middle" (middle click), "right" (right click), "start" (start drag), "finish" (finish drag), or "cancel" (perform no mouse action).
ignore Ignores the provided arguments. This is useful for some exclusive modes, where the _default command should ignore utterances. For example, this is used by the "pause" mode. One or more words to ignore.
kebab Types arguments in kebab-case. One or more arguments to type in kabob-case. If the first argument is "upper", use all uppercase. If "stop" is provided as an argument, the function completes.
keyHold Presses a key and holds it. Also see keyRelease. The key to hold that must be supplied as a fixed argument.
keyRelease Releases a key from being held. Also see keyHold. The key to release that must be supplied as a fixed argument.
keyRepeat Presses a key combination one or more times. The initial optional arguments are modifier keys (shift, control, etc.) that must be supplied as fixed arguments.

The next required argument is a normal key that must be supplied as a fixed argument.

The final argument is the number of times the key should be pressed in the range 1-100. This argument should be an utterance argument. If not supplied, the default value is 1 (single key press).
keyPress Presses a key combination. The initial optional arguments are modifier keys (shift, control, etc.) that must be supplied as fixed arguments.

The final required argument is a normal key that must be supplied as a fixed argument.
lower Types the first letter of each argument as a lowercase letter. Also see upper. One or more utterance words. If "upper" is provided as an argument, letters after that will be uppercase. If "lower" is provided as an argument, letters after that will be lowercase. If "stop" is provided as an argument, the function completes.
mouseClick Clicks the mouse at its current location. Single argument that is "left", "double", "middle", or "right".
mouseGo Moves the mouse to the provided pixel coordinates. This function is useful to create special commands that click on specific places of the screen. The first argument is the X pixel coordinate, where 0 is the left edge of the screen.

The second argument is any word and is ignored. It is only present to aid recognition of two distinct numbers.

The third argument is the Y pixel coordinate, where 0 is the top edge of the screen.
mouseHold Presses and holds the left mouse button. This is useful to start a drag. Also see mouseRelease. None.
mouseMove Moves the mouse in a given direction and number of pixels. The first argument is a direction: "up", "down", "left", "right".

The second argument is the number of pixels to move.
mouseRelease Releases the left mouse button from being held. This is useful to finish a drag. Also see mouseHold. None.
mouseScroll Scrolls the mouse. The first argument is either "up" or "down".

The second argument is an integer number of scroll ticks in the range 1-10.
number Types argument as a number. One, possibly multi-word argument that can be interpreted as a number. For example, each of the following are single arguments: "three", "twenty five", "one hundred thirty". Only numbers can have multiple words in a single argument. When a word is encountered that cannot be part of the number, the function completes and that word is processed as normal.
openHelp Opens mode and command help window. All utterance arguments are supplied to the function. If no argument is supplied, all modes are described. If one or more arguments are supplied, they are interpreted as the name of a mode, and the commands for that mode are described.
openMouseGuide Opens the mouse guide. Also see updateMouseGuide and closeMouseGuide. The first argument is required and is one of "screen", "pixels", or "grid".

The second argument is optional and describes a particular mouse action that should occur when the guide window closes. The value is one of "left" (left click), "double" (double click), "middle" (middle click), "right" (right click), "start" (start drag), or "finish" (finish drag).
openSetup Opens the setup window. None.
quit Quits the application. None.
sleep Creates a pause in a command sequence. One argument that is the number of milliseconds to pause.
smash Types the arguments without space between each word. One or more arguments are accepted. If the first argument is "upper", use all uppercase. If "stop" is provided as an argument, the function completes.
snake Types the arguments in snake_case. One or more arguments are accepted. If the first argument is "upper", use all uppercase. If "stop" is provided as an argument, the function completes.
title Types the arguments in Title Case. One or more arguments are accepted. If "stop" is provided as an argument, the function completes.
type Types the arguments. This is useful in commands that require typing. One or more fixed arguments.
toggleMode Toggles a mode on or off. Two or more arguments are supplied to the function.

The first argument is either "on" or "off".

The remaining arguments are interpreted as the name of a mode.
updateMicrophone Updates the microphone status. One argument that is "on" (turn microphone on), "off" (turn microphone off), or "pause" (pause microphone).
updateMouseGuide Updates the currently open mouse grid. Also see openMouseGrid and closeMouseGrid. One argument is accepted. If this is a "screen" mouse guide, this is a selected screen label. If this is a "pixels" mouse guide, this is a pixel coordinate. If this is a "grid" mouse guide, this is a grid cell identifier (1-9).
upper Types the first letter of each argument as a uppercase letter. Also see lower. One or more utterance words. If "lower" is provided as an argument, letters after that will be lowercase. If "upper" is provided as an argument, letters after that will be uppercase. If "stop" is provided as an argument, the function completes.