A voice menu contains a set of one or more voice commands that can be recognized when the voice menu is active. This section describes the attributes of a voice menu.
Every voice menu has a name and a language. The name consists of two strings: the name of the application that uses the menu and a string that identifies the application state in which the menu is valid. The application name must be unique among all applications registered to use voice commands in the system. Typically, the state string is the title-bar text of the window or dialog box with which the voice menu is associated (for example, "Main Window"). An application uses the VCMDNAME structure to specify a voice menu's name.
A voice menu's language identifies the language and dialect that the speech-recognition engine should use for the menu. A language consists of a Win32 language identifier and a dialect string. An application uses the LANGUAGE structure to specify a voice menu's language.
Once a voice menu is created and has commands, it must be activated before its commands can be recognized. When a menu is active, the engine checks the menu for a matching command whenever the engine processes an utterance from the voice-command site. The engine does not check the menu when it is inactive. An application uses the IVCmdMenu interface with the Activate and Deactivate member functions to explicitly activate and deactivate a voice menu. The menu remains open after a Deactivate command, so the application only needs to call Activate to reactive the menu; the application does not need to reopen the menu.
When calling Activate, an application specifies whether the voice menu is to be associated with a particular window or is a global menu. When a voice menu is associated with a window, the menu is automatically activated whenever the window becomes the foreground window and is automatically deactivated when the user switches to another window. The application does not need to explicitly activate or deactivate the menu. Instead of being associated with a particular window, a voice menu can also be global. A global voice menu remains active at all times regardless of which window is in the foreground, until the application explicitly deactivates it.
A global voice menu is useful for an application such as a clock program. The user can, for example, ask what time it is and get a response no matter what other applications are active. Global menu commands have a lower priority in case of a recognition conflict, which happens when multiple commands with the same name appear in different menus.
When an application calls Activate, it specifies whether the voice menu should remain active when speech recognition is asleep for the voice-command site. By specifying the VWGFLAG_ASLEEP value, the application indicates that the menu should be active only when speech recognition is asleep and should be automatically deactivated when speech recognition is awake. A menu activated with the VWGFLAG_ASLEEP value is called a sleep menu. If the application does not specify this value, the menu is only active when speech recognition is awake.
An application can use the IVCmdMenu::ListSet member function to associate any number of phrase lists with a voice menu. A phrase list is a named set of words or phrases. By embedding the name of a list in the command string, the user can speak any word or phrase in the list at the given point in a command string. For example, a list named "myfriends" might contain the names "Linda," "Tom," and "Mary." If the list name were embedded in a command string, such as "Send mail to myfriends," the user could speak "Send mail to Linda," Send mail to Tom," or "Send mail to Mary."
Typically, a list contains information that changes dynamically at run time, such as the ten people to whom the user most recently sent electronic mail. For best results, a list should have fewer than 20 entries. Having more than 20 entries in a list can reduce the accuracy of recognition.
A list is associated with a menu rather than an individual command. The list must appear in at least one command string, but can be used by more than one command on the menu. The list persists until the voice-menu object is released. List entries are not automatically saved to disk. To preserve the list, call the IVCmdMenu::ListGet member function and take steps to store the result. ListGet retrieves the phrases stored in the current list for the selected voice menu.
The IVCmdMenu::ListSet member function is much faster than the IVCmdMenu interface's Add, Remove, or Set member functions because list entries are substituted when a command is recognized and the menu is not recompiled. This means that ListSet can be called on an active menu without affecting performance.
The IVCmdMenu::TrainMenuDlg member function displays a modal dialog box to train the engine for the selected menu. Because the Train Menu dialog box is provided by the speech-recognition engine, the controls in the dialog box and the training it requests depend on the speech-recognition engine being used. Some engines may not offer this dialog box.
An application can call TrainMenuDlg to obtain training for the commands on a particular menu. In contrast, the training obtained by calling the IVCmdDialogs::TrainGeneralDlg member function applies to all commands, regardless of the menu they are on.