You can reference a particular character by using the Item property or the Character method. In fact, you can omit both keywords and simply specify the name of the character that you wish to use. The first three statements in the following code all perform the same function. In the last three statements, I declare a variable as type Object and create an object reference to it. This provides the quickest way of all to reference the character.
Agent1.Characters.Character(“Genie”).Speak “Hello Chris.”
Agent1.Characters.Item(“Genie”).Speak “Hello Chris.”
Agent1.Characters(“Genie”).Speak “Hello Chris.”
Dim MyAgent as Object
Set MyAgent = Agent1.Characters.Character(“Genie”)
MyAgent.Speak “Hello Chris.”There are three types of character files:
The three types of files are optimized for different situations. The .AAF and .ACF files are designed to let users download just enough data over the Internet to perform their immediate task. You use the Character object’s Get method to retrieve the pieces of information you need. The .ACS file is designed for use on your local hard disk, when the amount of information you want to access is not a problem.
Table 14.5 lists the Character object’s properties. By changing the values of Height and Width, you can change the size of the character. By changing the Top and Left properties, you can change the character’s location on the screen. All four of these properties use measurements in pixels, not twips.
Table 14.5: Selected Character Object Properties
| Property | Description |
| Balloon | Returns an object reference to a Balloon object |
| Commands | Returns an object reference to a Commands collection |
| Description | Contains a description of the character (may not be present with all characters) |
| ExtraData | Contains extra data about the character (may not be present with all characters) |
| HasOtherClients | When set to True, other applications are using this character |
| Height | Contains the height of the character in pixels |
| IdleOn | When set to True, the server plays the Idle animation after the character has been idle for a while. |
| Left | Contains the distance between the left edge of the character and the left edge of the screen, measured in pixels |
| MoveCause | Contains an Integer that describes who last moved the character |
| Name | Contains the name of the character |
| Pitch | Contains a Long value with the character’s speech output pitch setting (TTS) |
| SoundEffectsOn | When set to True, sound effects are automatically played for your character if included in the character information |
| Speed | Contains a Long value containing the user’s current setting for the speed of the character’s speech |
| Top | Contains the distance between the top edge of the character and the top edge of the screen, measured in pixels |
| VisibilityCause | Contains an Integer that describes who last changed the character’s Visible property |
| Visible | When set to True, the character is currently displayed on the screen |
| Width | Contains the width of the character in pixels |
Some of these properties, such as the character’s Name, Description, and ExtraData, are set when the character is created using the Agent Character Editor. Both the Description and the ExtraData properties contain optional information that may not be available in all characters.
Setting the IdleOn property to True will let the Agent server automatically provide animations when the character hasn’t been referenced in a while. The SoundEffectsOn property controls whether or not the character’s sound effects will be played. Of the characters shipped with Microsoft Agent 1.5, only the MerlinSfx character contains sound effects, so this property won’t make much of a difference with any of the other characters. The Pitch and Speed properties reflect the options set by the user in the Microsoft Agent Properties dialog box.
Since a particular character may be controlled by multiple applications, several of the properties are available to coordinate multiple access. You can see if you have exclusive use of the character by checking the HasOtherClients. You can find out who or what last moved the character with the MoveCause property, and you can check who last changed the Visible property with the VisibilityCause property.
When working with Agents, most of the functions involve requests that you will pass to an individual character to perform. These functions include speaking, gesturing, playing animations, and moving around on the screen. To perform these functions, you use the methods listed in Table 14.6.
Table 14.6: Character Object Methods
| Method | Description |
| Activate | Changes which character is active |
| GestureAt | Plays the animation where the character will gesture at the specified location on the screen |
| Get | Retrieves information about a character |
| Hide | Removes the character from the screen |
| Interrupt | Interrupts the current animation of another character and continues with the next animation in the queue |
| MoveTo | Moves the character to the specified location on the screen |
| Play | Plays the specified animation |
| Show | Displays the character on the screen |
| Speak | Uses the text-to-speech engine to say the specified text and displays the text in the balloon |
| Stop | Cancels the current animation and the rest of the animations in the queue |
| StopAll | Stops the specified list of requests |
| Wait | Waits for the specified request to be completed |
Because many of the actions that a character will perform take a relatively long period of time, most of the methods issue a command to the Agent server and then return control to your program. The Agent server maintains a queue with these commands and will execute them in the order that they were submitted to the server, unless you take explicit action to change what is happening.
Once you have used the Load method to load a character into the Characters object, you can use the Show method to display the character on the screen. Normally, the character will play a short animation rather than simply appearing on the screen. For instance, the Robby the Robot animation will begin by showing a door opening on your screen and then walking through the door, as you can see in Figure 14.9. You have the option to skip this animation and have the character appear immediately on the screen.
Figure 14.9: Robby the Robot’s Show animation
The opposite of the Show method is the Hide method. Normally, the Hide method will play a short animation rather than having the character simply vanish. However, you can specify that the character should skip this animation, which will cause the character to disappear immediately.
You can move your character around the screen by using the MoveTo method. This method requires an x, y location (in pixels) to specify where you want to move the character and a value to indicate the speed at which the character should be moved. An animation will be played while the character is moving. If you specify a value of 0 for speed, the character will immediately jump to the new location without any animation.
TIP: Jump before you show: You can use the MoveTo method before you use the Show method to display the character if you set the MoveTo speed to 0. Otherwise, using the MoveTo method before the Show method will cause an error.
The animation consists of two parts: the normal animation and the return animation. The normal animation takes the character from the neutral position to the desired position. The return animation takes the character back to the neutral state.
The GestureAt method also plays an animation. This animation is used to point at a location specified by an x, y coordinate on the screen. Figure 14.10 shows an example. The routine is smart enough to pick the appropriate animation to point in the correct direction relative to the character’s current location.
Figure 14.10: Merlin’s gesture
All of the other animations are handled by the Play method. This method adds the animation to the end of the queue at the Agent server. Each animation will be played in turn, unless a Stop, StopAll, or Interrupt method is used. Table 14.7 lists some of the animations handled by the Play method.
Table 14.7: Selected Play Method Animations for Genie, Merlin, and Robby
| Animation | Description |
| Acknowledge | Nods head |
| Alert | Straightens and raises eyebrows |
| AlertReturn | Returns to neutral state |
| Blink | Blinks eyes |
| Confused | Scratches head |
| ConfusedReturn | Returns to neutral state |
| DontRecognize | Holds hand to ear |
| DontRecognizeReturn | Returns to neutral state |
| Explain | Extends arms to the side |
| ExplainReturn | Returns to neutral state |
| Greet | Bows (Genie and Merlin ) or waves (Robby) |
| GreetReturn | Returns to neutral state |
| Pleased | Claps hands and smiles (Genie), smiles and holds hands together (Merlin), or straightens body and smiles (Robby) |
| PleasedReturn | Returns to neutral state |
| Read | Gets scroll and reads it (Genie), opens book and looks up (Merlin), or tears off printout and reads it (Robby) |
| ReadReturn | Returns to neutral state |
| Sad | Looks sad |
| SadReturn | Returns to neutral state |
| Suggest | Displays light bulb |
| SuggestReturn | Returns to neutral state |
| Surprised | Looks surprised |
| SurprisedReturn | Returns to neutral state |
| Think | Looks up with hand on chin (Genie and Merlin) or tilts head and scratches (Robby) |
| ThinkReturn | Returns to neutral state |
| Wave | Waves |
| WaveReturn | Returns to neutral state |
| Write | Writes and looks up |
| WriteReturn | Returns to neutral state |
If an animation doesn’t leave the character in a neutral state, and the next animation starts with the character in the neutral state, then the return animation associated with the last animation will be played automatically. For example, when you tell Merlin to play the Wave animation, Merlin finishes with his hand up. Then when you play the Surprised animation, the WaveReturn animation will be played automatically before the Surprised animation is started.
The Speak method uses the text-to-speech engine to convert the string of words into audible speech. The words will also be displayed in the character’s balloon as they are spoken. In addition, this method includes a number of speech tags that can be used to modify how the speech sounds Table 14.8 lists the available speech tags and what they do.
Table 14.8: Speech Tags Used with the Speak Method
| Tag | Description |
| Chr | Specifies the character of the voice; valid values are Normal, Monotone, and Whisper |
| Ctx | Sets the context of the output text; valid values are Address, Email, and Unknown |
| Emp | Emphasizes the next word |
| Lst | Repeats the character’s last spoken statement; this tag must be alone in the parameter for the Speak method |
| Map | Sends one block of text to the speech-to-text engine and displays the other in the balloon |
| Mrk | Triggers the Bookmark event with the specified number |
| Pau | Pauses the speech for the specified number of milliseconds |
| Pit | Sets the baseline pitch; this value can range from 50 to 400 hertz |
| Rst | Resets all tags to their default settings |
| Spd | Sets the baseline speaking speed |
| Vol | Sets the baseline speaking volume |
If you have a program with more than one Agent, you will need a way to synchronize the various characters. Synchronization can be accomplished by using the Wait and Activate methods. Each of the methods we’ve discussed here (GestureAt, Hide, MoveTo, Play, Show, and Speak) can return a Request object. The Wait method uses the Request object and will delay one character’s action until the action of another character has been completed.
WARNING: Wait not, want not: You can’t use the Wait method on the same character that created the Request object. Doing so will cause an error.
The Activate method is also important because it allows you to make a different character input-active. Without this method, you would need to play an animation or speak some words to switch the input-active state from one character to another.
To cancel the current animation and the rest of the animations in the queue, use the Stop method. You can also use the Stop method to cancel the animation associated with a particular Request object. The StopAll method can cancel all animations or other requests by request type. The Interrupt method is used to cancel the current animation and begin processing the next animation in sequence. All of these methods are not queued and take effect immediately.
The Get method is used primarily in Internet applications where character information and animations are loaded from a web server. This method allows you to retrieve three types of information: an animation, a state date, or a wave file. The requests are sent to the Agent server, which will get the information from the specified location if needed. By using the Get method, you will only download those animations you need, thus minimizing download time.
WARNING: You can’t play what you don’t have: You must use the Get method to retrieve character information and animation information before you use it. For example, before you use the Show method, you must download the Show animation. Of course, if you are using character data from your local hard disk, this warning doesn’t apply.