Platform SDK: Agent

The Command Object

A Command object is an item in a Commands collection. The server provides the user access to your Command objects when your client application becomes input-active.

To access the property of a Command object, you reference it in its collection using its Name property. In VBScript and Visual Basic you can use the Name property directly:

   agent.Characters("CharacterID").Commands("Name").property [= value]

For programming languages that don't support collections, use the Command method:

   agent.Characters("CharacterID").Commands.Command("Name").property [= value]

You can also reference a Command object by creating a reference to it. In Visual Basic, declare an object variable and use the Set statement to create the reference:

   Dim Cmd1 as Object
   ...
   Set Cmd1 = Agent.Characters("MyCharacterID").Commands("SampleCommand")
   ...
   Cmd1.Enabled = True

In Visual Basic 5.0, you can also declare the object as type IAgentCtlCommandEx and create the reference. This convention enables early binding, which results in better performance:

   Dim Cmd1 as IAgentCtlCommandEx
   ...
   Set Cmd1 = Agent.Characters("MyCharacterID").Commands("SampleCommand")
   ...
   Cmd1.Enabled = True

In VBScript, you can declare a reference as a particular type, but you can still declare the variable and set it to the Command in the collection:

   Dim Cmd1
   ...
   Set Cmd1 = Agent.Characters("MyCharacterID").Commands("SampleCommand")
   ...
   Cmd1.Enabled = True

A command may appear in either the character's pop-up menu and the Commands Window, or in both. To appear in the pop-up menu it must have a caption and have the Visible property set to True. In addition, its Commands collection object Visible property must also be set to True. To appear in the Commands Window, a Command must have its Caption and Voice properties set. Note that a character's pop-up menu entries do not change while the menu displays. If you add or remove commands or change their properties while the character's pop-up menu is displayed, the menu displays those changes whenever the user next displays it. However, the Commands Window dynamically reflects any changes you make.

The following table summarizes how the properties of a Command affect its presentation:

Caption Property Voice-Caption Property Voice Property Visible Property Enabled Property Appears in Character's Pop-up Menu Appears in Commands Window
Yes Yes Yes True True Normal, using Caption Yes, using VoiceCaption
Yes Yes Yes True False Disabled, using Caption No
Yes Yes Yes False True Does not appear Yes, using VoiceCaption
Yes Yes Yes False False Does not appear No
Yes Yes No1 True True Normal, using Caption No
Yes Yes No1 True False Disabled, using Caption No
Yes Yes No1 False True Does not appear No
Yes Yes No1 False False Does not appear No
No1 Yes Yes True True Does not appear Yes, using VoiceCaption
No1 Yes Yes True False Does not appear No
No1 Yes Yes False True Does not appear Yes, using VoiceCaption
No1 Yes Yes False False Does not appear No
No1 Yes No1 True True Does not appear No
No1 Yes No1 True False Does not appear No
No1 Yes No1 False True Does not appear No
No1 Yes No1 False False Does not appear No
Yes No1 Yes True True Normal, using Caption Yes, using Caption
Yes No1 Yes True False Disabled, using Caption No
Yes No1 Yes False True Does not appear Yes, using Caption
Yes No1 Yes False False Does not appear No
Yes No1 No1 True True Normal, using Caption No
Yes No1 No1 True False Disabled, using Caption No
Yes No1 No1 False True Does not appear No
Yes No1 No1 False False Does not appear No
No1 No1 Yes True True Does not appear No2
No1 No1 Yes True False Does not appear No
No1 No1 Yes False True Does not appear No2
No1 No1 Yes False False Does not appear No
No1 No1 No1 True True Does not appear No
No1 No1 No1 True False Does not appear No
No1 No1 No1 False True Does not appear No
No1 No1 No1 False False Does not appear No
1If the property setting is null. In some programming languages, an empty string may not be interpreted the same as a null string.

2The command is still voice-accessible.


When the server receives input for one of your commands, it sends a Command event, and passes back the name of the Command as an attribute of the UserInput object. You can then use conditional statements to match and process the Command.