My previous articles, "VB and Voice Recognition" and "VB and Voice Recognition, Part 2" covered a few of the basic properties and methods of the Voice recognition controls. You now are going to look at each control's properties, methods, and events. I gave a very basic description of what each does, the variables used, and a short list of valid settings. In the download is a module containing all the constants detailed in this article.
Some of the properties and methods of the two controls are not listed here. This is because they either are not fully implemented yet (the AttributeMemory property, for example, is specified as 'Under construction' in the SDK help files), or Methods that work with Properties are not fully implemented yet. The CopyToMemory method, for example, has (and I quote the SDK Helpfiles) 'If an application wishes to free the information, both chunks must be freed with [??]. Also, the application must call [???] (only once) on each of the [???] returned by [???}.' in the description.
Right, so take a look at the Voice Command Control first. Here are the properties.
AutoGainEnable () As Long
This property forwards the applied gain setting to or from the sound card, if the sound card supports Auto gain.
Valid Settings: 0 to 100 (0 = No gain, 100 = 100% Auto gain adjustment)
AwakeState () As Long
Although this property is defined as long, it uses a Boolean (True of False) setting. When set to True (awake), the control will listen for commands from any voice menu in the application. When set to False (asleep), the control will listen for commands only listed in the sleep menu in the application.
This property differs significantly from the Activate and Deactivate methods. These two methods actively activate or deactivate only the menu listed, not the entire control.
CountCommands (Menu as long) As Long
Passing a command menu number to the property will return the number of commands currently on the menu.
Device () As Long
Returns or sets the device identifier of the Wave-In device used by the control. Most users need not worry about altering this property unless you have multiple audio capture devices installed on the PC.
Enabled () As Long
Again, although this property is defined as a long, it uses a Boolean setting. This enables or disables the control. When disabled, the control will not respond to any voice commands, even those on the sleep menu.
EnableMenu () As Long
Used to enable voice menu number x.
Note: You need to use the value returned by MenuCreate.
HWnd () As Long
The Window handle of the control.
Initialized () As Long
Returns or sets the initialised state of the control. Most methods and properties will automatically initialise the control.
Valid Settings: 0, 1 (0 = Not initialised, 1 = Initialised)
LastError () As Long - Read only
Returns the result code of the last method or property called.
MenuCreate (Application as String, State as String, Flags as long) As Long
Creates a Voice Menu object in the control returning a unique identifier.
- VCMDMC_CREATE_ALWAYS: Creates a empty menu. If it exists, the menu is cleared.
- VCMDMC_CREATE_NEW: Creates a empty menu. If it exists, an error is returned.
- VCMDMC_OPEN_ALWAYS: Opens the menu. If it does not exist, an empty menu is created.
- VCMDMC_OPEN_EXISTING: Opens the menu. If it does not exist, an error is returned.
Microphone () As String
The name of the type of microphone used.
Speaker () As String
The name of the currently set speaker (User). The control can be set up for multiple users, each with their own training files.
SRMode () As String
The GUID of the recognition engine mode.
SuppressExceptions () As Integer
Enables or Disables the suppression of Exception errors. When enabled, you can check the LastError property to get the Error code of the last method or property call.
Threshold () As Long
A % level that the control compares the match % to. Any match under the threshold level is discarded as unrecognised. A high value can return a good match to the spoken command. A low value will return more matches that are not necessarily exact matches.
Valid Settings: 0 to 100 (0= Worst case match, 100 = Best case match)
Activate (Menu as Long) As Long
Activates the secified menu in the control. Until the menu has been activated, no command on the list will be recognised.
AddCommand (Menu As Long, id As Long, command As String, description As String, category As String, flags As Long, action As String)
Adds or modifies a command to the menu specified.
- VCMDCMD_DISABLED_PERM: Disables this command on the menu.
- VCMDCMD_VERIFY: Asks for verification before passing the command to the application.
- VCMDCMD_CANTRENAME: Locks the command on the menu so that it cannot be changed.
CmdMimic (Application as String, State as String, Command as string)
Causes the control to respond as though the command has been spoken by the user.
Deactivate (Menu as Long)
Deactivates the speciffied menu in the control.
EnableItem (Menu As Long, Enable As Long, Cmdnum As Long, Flag As Long)
Enables or Disables items on the menu. Although defined as long, Enable accepts Boolean (True or False)
- VCMD_BY_IDENTIFIER: Cmdnum is the identifier of the menu item.
- VCMD_BY_POSITION: Cmdnum is the position in the list of the menu item.
GetCommand (Menu As Long, Index As Long, Command As String, Description As String, Category As String, Flags As long, Action As String)
Returns details about the specified command on the given menu.
- VCMDCMD_DISABLED_PERM: This command is disabled.
- VCMDCMD_VERIFY: This command requires verification before passing to the application.
- VCMDCMD_CANTRENAME: This command is locked and cannot be changed.
ListGet (Menu As Long, List As String, Listdata As String)
Returns a list of commands stored on the specified menu by Listset.
ListSet (Menu As Long,List As String, ListNum As Long, Listdata As String)
Sets a list of phrases in the voice menu. The user can speak any phrase in the list in place of the list name. The usage here is best described with an example:
AddCommand Vcmenu ,1,"Today is <Weekday>","list example","",2,"" ListSet VCmenu,"Weekday List",3,"Monday|Tuesday|Friday"
MenuDelete (Application As String, State As String)
Deletes a menu from the control. You cannot delete a menu if it is currently active.
ReleaseMenu (Menu As Long)
Releases the menu identifier and frees up the allocated memory.
Remove (Menu As Long, Index as long)
Removes the specified command from the menu.
SetCommand - Requires (Menu As Long, Index as long, id As Long, command As String, description As String, category As String, flags As Long, action As String)
Changes the information for an existing command on the menu specified. (Options are the same as for Addcommand.)
AttribChanged (Attrib as Long)
Occurs when one of the attributes of the control is changed.
ClickIn (X as Long, Y as Long))
Occurs when the user clicks the object's icon.
CommandOther (CmdName As String, Command As String)
Occurs when a phrase was not recognized as being from the application's command set. This event is mostly ignored in applications.
CommandRecognize (ID As Long, CmdName As String, Flags As Long, Action As String, NumLists As Long, ListValues As String, command As String)
Occurs when a spoken phrase was recognized as being from the application's command set, and returns all the commands set's options.
Occurs when recognition processing has begun for a command.
MenuActivate (cmdName As String, bActive As Boolean)
Occurs when a voice menu has been activated or deactivated.
Occurs when the speech recognition engine has detected the beginning of an utterance or sound.
Occurs when an utterance is finished. Typically, when between .25 to .5 of a second of silence is detected.
VUMeter (Level As Long)
Notifies the application of the current VU level.
On the next page, you will see the Diction Control.