Microsoft Agent Part 1: Animating Office Applications with Microsoft Agent
This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.
Lisa Wollin
Microsoft Corporation
April 2001
Applies to:
Microsoft® Office
Summary: With Microsoft Agent, you can create custom voice animations for your Microsoft Office applications and create animated tutorials and custom Help content. This article provides an overview of the Microsoft Agent Control 2.0 object model members that you can use to add voice animation to any of your Office documents. (7 printed pages)
Download ODC_MSAgent-I.exe.
Contents
Introduction Adding Microsoft Agent Features to Office Applications Animating the Microsoft Agent Characters Making the Microsoft Agent Characters Speak Pulling It All Together Animating with Application Events Unloading the Microsoft Agent Character Conclusion Additional Resources
Introduction
Have you ever wanted to add voice animation to a Microsoft® PowerPoint® presentation or provide interactive help for a custom Microsoft Excel form? Or have you ever wanted to include voice animation in Word to review comments and revisions in a document? These are just a few of the things you can do when you use the Microsoft Agent Control with your custom Microsoft Office applications.
This article discusses the members of the Microsoft Agent Control that you can use to animate your Office documents. The examples in this article are available for download and have been adapted for Microsoft Word, Excel, and PowerPoint.
Adding Microsoft Agent Features to Office Applications
For demonstration purposes, I will use PowerPoint. However, the basic principles that I will demonstrate in this article apply to all of the Office applications. In part two of this series, I'll show you how to create animated presentations using the Presentation Narrator for Microsoft Agent. For now, let's create a blank presentation and start the Visual Basic® Editor.
Before I can start using the animation features in Agent, I need to add a reference to the Microsoft Agent Control 2.0 (click References on the Tools menu). This ActiveX® control is installed with the core components of the Microsoft Agent Components, which is automatically preinstalled with Office 2000, Microsoft Windows® 2000, Microsoft Windows Millennium Edition, and other software. If you are unable to locate the Microsoft Agent Control 2.0 in the list of available references, you can download and install Agent and any or all of the available characters from the Microsoft Agent Web site.
Now that I have a reference to the Microsoft Agent Control 2.0, I can begin to access its functionality. To do this, I create one class module (for the presentation) and two standard code modules (one for the Agent Control and one for the main macro).
I name the class module clsPPT. At the top of the class module, I declare a variable called appPPT using the WithEvents keyword. This allows me to animate the Agent character during PowerPoint events. That takes care of my presentation.
The first standard code module I name AgtMerlin. Inside the code module I declare two global variables. I declare the variable g_ctlAgent as an Agent variable type, which acts as my control variable that I use to connect to my presentation. Next, I declare the variable g_charMerlin as an IAgentCtlCharacter variable type.
Then I need to create the connection between the Agent Control and my VBA code and use the Load method of the IAgentCtlCharacter object to specify the character I want to use. There are four characters available for you. They can be downloaded from the Agent Web site and hundreds of others elsewhere. You can even create your own characters. The following example loads the Agent and assigns the Merlin character to my g_charMerlin variable. I can then use this object variable throughout the rest of my code to save myself a lot of typing.
Sub LoadMerlin()
'Set the object variable for the Microsoft Agent ActiveX control.
Set g_ctlAgent = New Agent
'Establish a connection to Microsoft Agent.
g_ctlAgent.Connected = True
'Load the character animation data file from the default folder.
g_ctlAgent.Characters.Load CharacterID:="merlin", _
LoadKey:="merlin.acs"
'Set the object variable for the character.
Set g_charMerlin = g_ctlAgent.Characters(CharacterID:="merlin")
End Sub
When I run the code above, I see an icon of Merlin's hat in the Taskbar Notification Area that shows that the character was successfully loaded. Now I'm ready to start adding voice and other animation to my character.
Animating the Microsoft Agent Characters
Once I've created the character and loaded it into memory, I can call that character and tell it to perform actions and voice animations. The Show and Hide methods do just that: show the character when I want it to appear on the screen, and hide the character when I want it to go away. However, the two action animation methods I use most widely are Play and MoveTo.
The Play method is how I program the character to perform one of its animations. For example, to make Merlin perform the Congratulate and Explain animations, I write the following lines:
g_charMerlin.Play Animation:="Congratulate"
g_charMerlin.Play Animation:="Explain"
You can find a comprehensive list of the animations for each of the four characters in the Microsoft Agent documentation. Many of the actions for the characters are standardized with the same animation name, but each of the characters might perform the action somewhat differently. For example, the DoMagic1 animation for Merlin makes the character wave his magic wand, whereas it makes Genie turn to the side and wave his hands.
The MoveTo property uses x/y coordinates to move the character from his current location to a different place on your screen. For example, the line of code below moves Merlin to 250 pixels from the left edge of the screen and 500 pixels from the top edge of the screen.
g_charMerlin.MoveTo x:=250, y:=500
Now, let's make Merlin talk.
Making the Microsoft Agent Characters Speak
Making the Agent characters speak is very simple. You use the Speak method and follow it with the text you want the character to say. For example, if I want Merlin to introduce himself, I would write the line:
g_charMerlin.Speak Text:="Hello! I am Merlin."
However, there may be times when you want to add inflections or other vocal qualities. For example, you may want your character to whisper its words or emphasize a certain word. Perhaps you want it to pause, speed up, or slow down its speech. Or maybe you want to increase or decrease the volume. To do any of these actions, you add a speech output tag to the text the character is speaking.
To add speech output tags to your characters speech text, surround the speech output tags with backslash characters (\). Some of the speech output tags, for example Pau (pause) and Spd (speed), require additional information.
The Chr speech output tag specifies the character of the voice. You can specify the character as "Normal" (default), "Monotone", or "Whisper". The following line of code causes Merlin to whisper his introduction (always use two double quotes when you want to embed one string inside of another string).
g_charMerlin.Speak Text:="\chr=""whisper""\Hello! I am Merlin."
Another thing to note is that once you specify the voice, everything the character says is in that same voice for the remainder of this line of code. For example, if I specify that Merlin should whisper when he says "Hello" and then say his introduction in a normal voice but I never set his voice back to "Normal", everything he says on that line will be whispered. Therefore, the code below sets his voice back to normal after he says "Hello".
g_charMerlin.Speak Text:="\chr=""whisper""\Hello!\chr=""normal""\I am Merlin"
The Pau speech output tag causes the character to pause its speech. You specify the number of milliseconds you want the speech to pause. For example, in the following line of code, Merlin pauses for 5,000 milliseconds (5 seconds) between when he says "Hello!" and when he introduces himself."
g_charMerlin.Speak Text:="Hello!\pau=5000\I am Merlin."
Another speech output tag you might use is Emp. This speech output tag causes the character to emphasize the word immediately following the speech output tag. For example, if in Merlin's introduction, I want him to emphasize the word "I", I would write the code as follows.
g_charMerlin.Speak Text:="Hello!\emp\I am Merlin."
These are just a few of the speech output tags you can use to add voice inflection to your character's speech. There are eleven tags in all. To find more information, see the Speech Output Tags page.
Pulling It All Together
Now that you know the basics, let's pull all of the Show, Hide, Play, MoveTo, and Speak methods into a single example where Merlin introduces himself. The following subroutine causes Merlin to introduce himself and display a few of his animations.
Note
You must run the LoadMerlin subroutine shown earlier before this subroutine will function.
Public Sub IntroMerlin()
Dim strName As String
With g_charMerlin
'Display the character.
.Show
'Make the character play an animation.
.Play Animation:="Greet"
.Play Animation:="Restpose"
.Speak Text:="Hello!"
.Play Animation:="Announce"
.Speak Text:="I am Merlin."
.Play Animation:="Pleased"
.Speak Text:="It is nice to meet you."
'Move the character to a screen coordinate (in pixels).
.MoveTo x:=250, y:=500
.Speak Text:="I would like to show you"
.Play Animation:="Hide"
.Play Animation:="Show"
.Speak Text:="some of my animations."
.Speak Text:="Here is a magic trick."
.Play Animation:="DoMagic1"
.Play Animation:="DoMagic2"
.Play Animation:="Pleased"
.Play Animation:="Restpose"
.Play Animation:="Suggest"
.Speak Text:="Now, I have a suggestion."
.Speak Text:="Do you see the light bulb?"
.Play Animation:="Pleased"
.Play Animation:="Restpose"
.Speak Text:="I can also read"
.Play Animation:="Read"
.Speak Text:="and write."
.Play Animation:="Write"
.Play Animation:="Pleased"
.Play Animation:="Restpose"
.Speak Text:="Thank you."
.Play Animation:="Wave"
.Speak Text:="Goodbye."
'Hide the character when you are finished with the animation.
.Hide
End With
End Sub
Animating with Application Events
Now that I have my character set up with an introduction, I want Merlin to load and introduce himself when I start the slide show for my presentation. To do this, I create a macro called RunMerlin that I can run from the PowerPoint application. This subroutine, shown below and located inside the modRunMerlin.bas code module, initializes the clsPPT class and then runs the presentation.
Sub RunMerlin()
Dim preShow As Presentation
Set g_classPPT = New clsPPT
Set preShow = ActivePresentation
preShow.SlideShowSettings.Run
End Sub
Inside the clsPPT class module, I write code in the SlideShowBegin event to load (with the LoadMerlin subroutine) and introduce the character (with the IntroMerlin subroutine). Now, when I run the RunMerlin macro, the slide show starts and Merlin appears to introduce himself.
Unloading the MS Agent Character
Once the Agent character is loaded into memory, it stays there until you tell it to go away. To do this, I write a separate UnloadMerlin subroutine inside of my AgtMerlin code module, as follows.
Sub UnloadMerlin()
g_ctlAgent.Characters.Unload CharacterID:="Merlin"
End Sub
Since I only want the character to unload when my slide show is finished, I place a call to this subroutine inside the SlideShowEnd event in the clsPPT module. Then when the slide show ends or I end it prematurely, Merlin is unloaded from memory.
Conclusion
There are many things you can do with Microsoft Agent, and this article should get you started on the road to discovery.
Additional Resources
For more Microsoft Agent information and downloads, see the following resources: