IAgentCommands

[Microsoft Agent is deprecated as of Windows 7, and may be unavailable in subsequent versions of Windows.]

The Microsoft Agent server maintains a list of commands that are currently available to the user. This list includes commands that the server defines for general interaction, such as Hide and Microsoft Agent Properties, the list of available (but non-input-active) clients, and the commands defined by the current active client. The first two sets of commands are global commands; that is, they are available at any time, regardless of the input-active client. Client-defined commands are available only when that client is input-active.

Retrieve an IAgentCommands interface by querying the IAgentCharacter interface for IAgentCommands. Each Microsoft Agent client application can define a collection of commands called a Commands collection. To add a Command to the collection, use the Add or Insert method. Although you can specify a Command's properties using IAgentCommand methods, for optimum code performance, specify all of a Command's properties in the IAgentCommands::Add or IAgentCommands::Insert methods when initially setting the properties for a new Command. You can use the IAgentCommand methods to query or change the property settings.

For each Command in the Commands collection, you can determine whether the command appears on the character's pop-up menu, in the Voice Commands Window, in both, or in neither. For example, if you want a command to appear on the pop-up menu for the character, set the command's Caption and Visible properties. To display the command in the Voice Commands Window, set the command's Caption and Voice properties.

A user can access the individual commands in your Commands collection only when your client application is input-active and the character is visible. Therefore, you will typically want to set the Caption, VoiceCaption, and Voice properties for the Commands collection object as well as for the commands in the collection, because this places an entry for your Commands collection on a character's pop-up menu and in the Voice Commands Window. When the user switches to your client by choosing its Commands entry, the server automatically makes your client input-active, notifying your client application using the IAgentNotifySink::ActivateInputState and makes the Commands in its collection available. The server also notifies the client that is no longer input-active with the IAgentNotifySink::ActivateInputState event. This enables the server to present and accept only the Commands that apply to the current input-active client's context. It also serves to avoid Command-name collisions between clients.

A client can also explicitly request to make itself the input-active client using the IAgentCharacter::Activate method. This method also supports setting your application to not be the input-active client. You may want to use this method when sharing a character with another application, setting your application to be input-active when your application window gets focus and not input-active when it loses focus.

Similarly, you can use IAgentCharacter::Activate to set your application to be (or not be) the active client of the character. The active client is the client that receives input when its character is the topmost character. When this status changes, the server notifies your application with the IAgentNotifySinkEx::ActiveClientChange event.

When a character's pop-up menu is displayed, changes to the properties of a Commands collection or the commands in its collection do not appear until the user redisplays the menu. However, when open, the Voice Commands Window does display changes as they happen.

IAgentCommands defines an interface that allows applications to add, remove, set, and query properties for a Commands collection. These functions are also available from IAgentCommandsEx.

A Commands collection can appear as a command in both the pop-up menu and the Voice Commands Window for a character. To make the Commands collection appear, you must set its Caption property. The following table summarizes how the properties of a Commands collection 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 the same as a null string.

²The command is still voice-accessible.

Methods in Vtable Order

IAgentCommands Methods	Description
GetCommand	Retrieves a Command object from the Commands collection.
GetCount	Returns the value of the number of Commands in a Commands collection.
SetCaption	Sets the value of the Caption property for a Commands collection.
GetCaption	Returns the value of the Caption property of a Commands collection.
SetVoice	Sets the value of the Voice property for a Commands collection.
GetVoice	Returns the value of the Voice property of a Commands collection.
SetVisible	Sets the value of the Visible property for a Commands collection.
GetVisible	Returns the value of the Visible property of a Commands collection.
Add	Adds a Command object to a Commands collection.
Insert	Inserts a Command object in a Commands collection.
Remove	Removes a Command object in a Commands collection.
RemoveAll	Removes all Command objects from a Commands collection.