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

Many 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 while using the application.

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:

  - name: "quit utterly voice"
    description: >-
      Quits the utterly voice application.
    functions:
      - name: "quit"

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

  - name: "press escape"
    description: >-
      Presses the escape key.
    functions:
      - name: "keyPress"
        fixedArguments:
          - "escape"

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

  - name: "title"
    description: >-
      Use this command to type words in Title Case.
      By default, the remainder of the utterance words are supplied as arguments,
      but you can say "stop" to complete the command
      and continue speaking without pause.
    functions:
      - name: "title"
        utteranceArguments: 100
    spaceLeft: true
    spaceRight: true

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

  - name: "scroll up"
    description: >-
      Scrolls the mouse up.
      The single utterance argument is the number of scroll ticks.
    functions:
      - name: "mouseScroll"
        fixedArguments:
          - "up"
        utteranceArguments: 1

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:

  - name: "mouse position"
    description: >-
      Activates the "mouse pixels" exclusive mode to control the mouse.
    functions:
      - name: "toggleMode"
        fixedArguments:
          - "on"
          - "mouse pixels"
      - name: "openMouseGuide"
        fixedArguments:
          - "pixels"

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.
autoCapitalization	Turns automatic capitalization provided by the recognizer on or off.	The only argument is either "on" or "off".
autoScrollStart	Starts or restarts automatic scrolling. Also see autoScrollStop.	The first argument is either "up" or "down". The second argument is an integer number of scroll ticks in the range 1-10. The third optional argument is the number of seconds between scrolls in the range 1-100. Defaults to 5 if not provided.
autoScrollStop	Stops automatic scrolling. Also see autoScrollStart.	None.
autoSpacing	Turns automatic spacing between words within an utterance on or off.	The only argument is either "on" or "off".
autoUtteranceSpacing	Turns automatic spacing after each utterance on or off.	The only argument is either "on" or "off".
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).
commandsOnly	Turns the commands-only interpreter state on or off.	The only argument is either "on" or "off".
context	Used to type a single word within a full phrase that provides context for the word. If "stop" is provided as an argument, the function completes.	The first argument is a numeric position (starting at 1) within the remaining utterance arguments. The remaining arguments contain the phrase. If the arguments are "one write a book", the word "write" is typed. If the arguments are "two school principal", the word "principal" is typed.
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.
monitorChange	Moves the mouse to a specific monitor.	Single numeric argument that is the number identifier for the monitor. These numbers are assigned by Windows and are shown on the display settings.
monitorNext	Moves the mouse to the next monitor in the sequence.	None.
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.
reloadSettings	Reloads number and mode settings files. Also regenerates associated help files.	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. Words that are supplied to the `titleSkip` setting of the `config\settings.yaml` file are not capitalized unless supplied as the first or last argument.	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 arguments to be typed. If multiple arguments are provided, space will be inserted between each argument if auto-spacing is active. If "stop" is provided as an argument, the function completes. The text can include `\n` for a newline and `\t` for a tab character.
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.

❮ Mode Settings Keys ❯