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 IAgentCtlCommand and create the reference. This convention enables early binding, which results in better performance:

    Dim Cmd1 as IAgentCtlCommand
    …
    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 Property	Visible Property	Enabled Property	Appears in Character's Pop-up Menu	Appears in Commands Window
Yes	Yes	True	True	Normal	Yes
Yes	Yes	True	False	Disabled	No
Yes	Yes	False	True	Does not appear	Yes
Yes	Yes	False	False	Does not appear	No
Yes	No	True	True	Normal	No
Yes	No	True	False	Disabled	No
Yes	No	False	True	Does not appear	No
Yes	No	False	False	Does not appear	No
No	Yes	True	True	Does not appear	No*
No	Yes	True	False	Does not appear	No
No	Yes	False	True	Does not appear	No*
No	Yes	False	False	Does not appear	No
No	No	True	True	Does not appear	No
No	No	True	False	Does not appear	No
No	No	False	True	Does not appear	No
No	No	False	False	Does not appear	No

*The command is still voice-accessible.

Generally, if you define commands with Voice settings, you also define Caption and Voice settings for its associated Commands collection. If a Commands collection has no Voice or no Caption setting and is currently input-active, but its Command objects do have Caption and Voice settings and their Enabled properties are True, the Command objects appear in the Commands Window tree view under "(undefined command)" when your client application becomes input-active.

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.