The MSAgent control also includes an assortment of events that you can use to track the execution of your characters or respond to user requests. Unlike the normal Click and DblClick events, these contain the following information:
Table 14.2 lists the MSAgent control events.
Table 14.2: MSAgent Control Events
| Event | Description |
| ActivateInput | Occurs when a character becomes input-active |
| BalloonHide | Occurs when a character’s balloon is hidden |
| BalloonShow | Occurs when a character’s balloon is shown |
| Bookmark | Occurs when a bookmark is encountered while using the Speak method |
| Click | Occurs when the user clicks on the character; includes button clicked, Shift key status, and x, y location of the cursor |
| Command | Occurs when the user issues a command |
| DblClick | Occurs when the user double-clicks on the character; includes button double-clicked, Shift key status, and x, y location of the cursor |
| DeactivateInput | Occurs when the character becomes non–input-active. |
| DragComplete | Occurs when the user has finished dragging the character |
| DragStart | Occurs when the user starts dragging a character |
| Hide | Occurs when a character is hidden |
| IdleComplete | Occurs when the server ends the idle state of a character |
| IdleStart | Occurs when the server places a character into the idle state |
| Move | Occurs after a character has been moved |
| RequestComplete | Returns the Request object after the server has finished a queued request |
| RequestStart | Returns the Request object before the server starts processing a request |
| Restart | Occurs when the server goes from a suspended to an active state |
| Show | Occurs when a character is displayed with the Show method |
| Shutdown | Occurs when the user shuts down the Agent server |
| Size | Occurs when the size of the character changes |
The Command event occurs when the user sends a command to the character, either by speaking or by choosing a command from the command menu. The UserInput object will be returned as a value to the event. This object contains information for up to three commands (the best match and up to two alternatives) that the speech recognition engine believes are possible matches, as listed in Table 14.3.
Table 14.3: The UserInput Object Used in the Command Event
| Property | Description |
| CharacterID | The name of the character that received the command |
| Name | The name of the command |
| Confidence | A value in the range of –100 to +100 indicating how close the spoken input was to the Voice property |
| Voice | The string of characters that was matched against the spoken input |
| Alt1Name | The name of the first alternate command |
| Alt1Confidence | Same as Confidence but for Alt1Name |
| Alt1Voice | Same as Voice but for Alt1Name |
| Alt2Name | The name of the second alternate command |
| Alt2Confidence | Same as Confidence but for Alt2Name |
| Alt2Voice | Same as Voice but for Alt2Name |
| Count | The number of alternatives returned |
Each returned command includes the name of the command, the string containing the voice text, and a confidence number in the range of –100 to +100 that indicates how well the spoken words match the command. The event also includes the number of commands returned. If the command was selected via a menu, Count will be set to 1 and the Confidence value will be set to +100. If the server was unable to match the spoken words with a command, Count will be set to 0.
The Shutdown and Restart events occur when the user stops the server and restarts it again directly from outside the program’s control. These events will occur in all programs that have an active connection to the server.
The Hide event is triggered whenever a character is hidden. Why this character is hidden is also included as an argument to this event. Similarly, the Show event occurs when the character is shown.
The Move event is triggered after the character is moved to a new location on the screen, with the coordinates specified in pixels. Similar to the Move event are the DragStart and DragComplete events; however, these events are sent only to the input-active character. When the size of a character is changed via its Height and Width properties, the Size event will be triggered.
WARNING: It’s not my fault: Many of the events in the MSAgent control are triggered system-wide for all applications using Agents. You should verify the character name passed to check that the event applies to your program.
The ActivateInput and DeactivateInput events occur at the beginning and the end of the period of time that a particular character can receive input. More specifically, the ActivateInput is triggered when the character becomes input-active, and the DeactiveInput event occurs when the character becomes non–input-active.