IAgentCommands

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.

¹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