Scripting Solutions with WSH and COM: Have Agents Work for You, Part 2

In "Scripting Solutions with WSH and COM: Have Agents Work for You, Part 1," July 2001, I introduced you to Microsoft Agent 2.0. I showed you how to instantiate an agent, use basic methods and properties to make an agent come alive, and ensure that an agent behaves properly on screen. This month, I continue looking at what you can do with agents. First, I show you how to use animations and various methods and properties to make agents enter, exit, speak, think, gesture, and move. Then, I give you hints about how to explore the animations and expand your knowledge.

Entering and Exiting
As I explained in Part 1, Microsoft Agent comes with four animated characters (i.e., agents): Genie, Merlin, Peedy, and Robby. Each agent comes with a unique set of animations that you can use. Two animations that you'll likely use often are the Show animation, which prompts the agent to make an entrance, and the Hide animation, which prompts the agent to exit gracefully. The animation sequence that appears depends on the agent. For example, Robby makes his entrance by walking through a doorway, whereas Peedy makes an entrance by flying on screen. As Figure 1 shows, Genie makes his entrance by mystically appearing in a puff of smoke.

You can call the Show and Hide animations several ways. For example, you can make Robby appear with the command

Robby.Show

Counterintuitively, this command is equivalent to

Robby.Show False

Thus, if you want the agent to appear but you don't want the entrance animation, you use the command

Robby.Show True

If you want Robby to exit the screen gracefully with the Hide animation, you can use either

Robby.Hide

or

Robby.Hide False

If you want Robby to immediately disappear with no animation, you use the command

Robby.Hide True

To determine whether an agent is currently visible or hidden, you can call the Visible property. For example, you can use the command

Merlin.Visible

to determine Merlin's status. If the command returns the value of True, Merlin is onscreen. If the command returns the value of False, Merlin isn't onscreen. As Listing 1 shows, you can use this command in an If...Then...Else statement to take action in response to whether Merlin is visible or hidden.

By default, all the animations, including Show and Hide, include sound effects. You can use the SoundEffectsOn property to turn off the sound effects. You set this property to False with code such as

Peedy.SoundEffectsOn = False

To turn the sound effects back on, you set the property to True.

Speaking and Thinking
You can use the Speak method to make an agent speak. As the first code sample in Listing 2 shows, you call the Speak method, then specify the lines to speak. Figure 2 shows the results of running this code. In addition to the message appearing in a cartoon word balloon, Peedy speaks the message if you have a text-to-speech engine installed.

You can use the Characters::Balloon object to alter a cartoon word balloon's appearance. This object has several properties that let you customize the balloon. For example, you can use the FontSize property to change the font size of the text in the balloon.

You can change the way in which an agent speaks by including tags inside the spoken lines. For example, you can emphasize a word by placing the Emp tag in front of that word. You can include the Chr=""Monotone"" tag at the beginning of the spoken line to make an agent speak in a monotone voice or the Chr=""Whisper"" tag to make the agent whisper. You can change the pitch with the Pit=n tag, where n is the desired pitch in hertz. For example, in the third code sample in Listing 2, I changed Peedy's voice to be high-pitched. Because I also changed the voice to a monotone, this speech pattern is probably more appropriate for Robby the robot than Peedy the parrot.

You can have an agent relay a message without speaking at all. The Think method displays the message you specify in a thought word balloon.

Gesturing
Each agent's animation set includes GestureUp, GestureDown, GestureLeft, and GestureRight. If you want an agent to gesture to a specific spot, you can use the GestureAt method. When you call this method, the agent automatically uses the appropriate gesture animation (i.e., GestureUp, GestureDown, GestureLeft, or GestureRight) to gesture toward the location you specify. You use (x,y) coordinates in pixels to specify the location with code such as

Merlin.GestureAt 300,200

The top left of the screen is the coordinates' point of origin.

Moving
Each agent's animation set includes MoveUp, MoveDown, MoveLeft, and MoveRight. If you want an agent to move to a specific location, you can use the MoveTo method. Like the GestureAt method, the MoveTo method needs the (x,y) coordinates in pixels. For example, to move Peedy to the (500,230) coordinates, you use the command

Peedy.MoveTo 500,230

As Figure 3 shows, Peedy then flies to the specified coordinates.

As I explained in Part 1, when you have two or more agents on screen, you need to use the Wait method to tell one agent to wait until the other agent action has completed its action. So, if you want to move Peedy and Genie is also onscreen, you need to use the code

Genie.Wait Peedy.MoveTo 500,230

Exploring the Animations
So far, I've discussed only a few of the animations available for each agent. You can run code to obtain a list of all the available animations for an agent. For example, Listing 3 contains code that lists the available animations for Peedy. Figure 4 shows the results of running this code. To obtain the animation list for another agent, simply change the code Peedy.AnimationNames in the For Each...Next statement to Robby.AnimationNames, Merlin.AnimationNames, or Genie.AnimationNames, depending on which agent you're interested in.

Another way to learn about the available animations is to visit the Microsoft Developer Network (MSDN) Online Library. Go to http://msdn.microsoft.com/library and navigate to Platform SDK Documentation, User Interface Services, Microsoft Agent. Under Microsoft Agent, you'll find the entry Microsoft Agent Animations for Genie Character as well as entries for the three other characters. When you click one of these entries, a table appears that lists the available animations. The table includes short descriptions of the animations.

Written descriptions are no substitute for viewing the animations. To view the antics of Peedy, Genie, Robby, and Merlin firsthand, you can use the Play method. This method plays the animation you specify for the character you specify. For example, if you want to watch Robby's Surprised animation and Peedy's Confused animation, you use the commands

Robby.Play "Surprised"Peedy.Play "Confused"

Extending What You've Learned
You now know the basics of how to use Microsoft Agent. Here are some ways you can expand on what you've learned so far:

A host of information about Microsoft Agent is available to keep you entertained for quite a while. Who said scripting had to be boring?