IAgentCommand
[Microsoft Agent is deprecated as of Windows 7, and may be unavailable in subsequent versions of Windows.]
A Command object is an item in a Commands collection. The server provides the user access to your commands your client application becomes input active. To retrieve a Command, call IAgentCommands::GetCommand.
IAgentCommand defines an interface that allows applications to set and query properties for Command objects that can appear in a character's pop-up menu and in the Voice Commands Window. These functions are also available from IAgentCommandEx. A Command object is an item in a Commands collection. The server provides the user access to your commands when your client application becomes input active.
A Command may appear in either or both the character's pop-up menu and the Voice Commands Window. To appear in the pop-up menu, it must have a Caption and have the Visible property set to True. The Visible property for its Commands collection object must also be set to True for the command to appear in the pop-up menu when your client application is input-active. To appear in the Voice Commands Window, a Command must have its VoiceCaption and Voice properties set. (For backward compatibility, if there is no VoiceCaption, the Caption setting is used.)
A character's pop-up menu entries do not change while the menu is displayed. If you add or remove Commands or change their properties while the character's popup menu is displayed, the menu displays those changes when redisplayed. However, the Voice Commands Window does display changes as you make them.
The following table summarizes how the properties of a command affect its presentation.
| Caption Property | Voice-Caption Property | Voice Property | Visible Property | Appears in Character's Pop-up Menu | Appears in Voice Commands Window |
|---|---|---|---|---|---|
| Yes | Yes | Yes | True | Yes, using Caption | Yes, using VoiceCaption |
| Yes | Yes | No¹ | True | Yes, using Caption | No |
| Yes | Yes | Yes | False | No | Yes, using VoiceCaption |
| Yes | Yes | No¹ | False | No | No |
| No¹ | Yes | Yes | True | No | Yes, using VoiceCaption |
| No¹ | Yes | Yes | False | No | Yes, using VoiceCaption |
| No¹ | Yes | No¹ | True | No | No |
| No¹ | Yes | No¹ | False | No | No |
| Yes | No¹ | Yes | True | Yes, using Caption | Yes, using Caption |
| Yes | No¹ | No¹ | True | Yes | No |
| Yes | No¹ | Yes | False | No | Yes, using Caption |
| Yes | No¹ | No¹ | False | No | No |
| No¹ | No¹ | Yes | True | No | No² |
| No¹ | No¹ | Yes | False | No | No² |
| No¹ | No¹ | No¹ | True | No | No |
| No¹ | No¹ | No¹ | False | No | No |
¹If the property setting is null. In some programming languages, an empty string may not be interpreted as the same as a null string.
²The command is still voice-accessible.
Generally, if you define a Command with a Voice setting, you also define Caption and Voice settings for its associated Commands collection. If the Commands collection for a set of commands has no Voice or no Caption setting and is currently input-active, but the Commands have Caption and Voice settings, the Commands appear in the Voice Commands Window tree view under "(undefined command)" when your client application becomes input-active.
When the server receives input that matches one of the Command objects you defined for your Commands collection, it sends a IAgentNotifySink::Command event, and passes back the ID of the command as an attribute of the IAgentUserInput object. You can then use conditional statements to match and process the command.
Methods in Vtable Order
| IAgentCommand Methods | Description |
|---|---|
| SetCaption | Sets the value for the Caption for a Command object. |
| GetCaption | Returns the value of the Caption property of a Command object. |
| SetVoice | Sets the value for the Voice text for a Command object. |
| GetVoice | Returns the value of the Voice property of a Command object. |
| SetEnabled | Sets the value of the Enabled property for a Command object. |
| GetEnabled | Returns the value of the Enabled property of a Command object. |
| SetVisible | Sets the value of the Visible property for a Command object. |
| GetVisible | Returns the value of the Visible property of a Command object. |
| SetConfidenceThreshold | Sets the value of the Confidence property for a Command object. |
| GetConfidenceThreshold | Returns the value of the Confidence property of a Command object. |
| SetConfidenceText | Sets the value of the ConfidenceText property for a Command object. |
| getConfidenceText | Returns the value of the ConfidenceText property of a Command object. |
| getID | Returns the ID of a Command object. |