What is the first thing you do when you open an Office application for the first time on a freshly installed PC? I would bet that you say goodbye to your dear friend ClipIt! Am I right?
A great percentage of technical users like you and me usually dislike wizards like this one. But what about your users? Many of them just want to see some distraction on their screen!
In this column, I will show you how to integrate MS Agent characters into your own application.
Installation / Requirements
Chances are that most MS Agent requirements are already installed on your computer because parts of them are installed by Windows itself and Office. You will also need some characters (found in .acs files). To install this library visit the Microsoft Agent download page. From this page, you can download some characters (Merlin, Genie, Robby, Peedy) if you don’t already have them.
To quickly get the state of your installation, go to the Microsoft Agent 2.0 Setup page and look at the “Microsoft Agent Detector” box at the top of the page.
You can also find additional characters at some specific spot on the web. A good place to start downloading more characters (more then 75) is the Character Gallery page.
While I think of it, MS Agent documentation is available in the MSDN library at the MSDN Microsoft Agent Start Page.
MS Agent is still COM
MS Agent hasn’t been converted into a .Net object yet. You still have to use the COM version.
Create a new VB.Net Windows Forms application. Now, we need to add a reference to the MS Agent component. Open the Add References item of the Project menu and select the COM tab from the dialog that will open. In the list of COM objects, find the one named “Microsoft Agent Control 2.0”, click the Select Button and finally click the OK button.
Figure 1: Adding the reference
Basic common behaviours
All the characters must implement a specific set of methods like Play, Speak, Show, Hide, and a couple more. Additional behaviours may exist for each character most of them if the form of animations (more on that later). You must refer to each character’s documentation (when you find one) to see what’s available.
Start writing code
Enough talking! What you want is to see it in action.
You first need to declare 2 variables at the class level of your form (just under the “Windows Form Designer generated code”) to hold pointers to our character.
Private mobjController As AgentObjects.Agent
Private mobjCharacter As AgentObjects.IAgentCtlCharacter
Add a button to your form. This button will load the character. You need to use this code to create an instance of the Merlin character, to show it and size it: mobjController = New AgentObjects.Agent
With mobjController
.Connected = True
.Characters.Load("merlin", "merlin.acs")
mobjCharacter = .Characters("merlin")
End With
With mobjCharacter
.Show()
.Width = 200
.Height = 200
End With
By default, the Load method is looking for the .acs files into the “msagent\chars” folder located into your Windows directory. You can also provide a path as the second parameter like this: .Characters.Load("Homer", "c:MyChars\Homer Simpson.acs")
Play with Merlin
Now that Merlin is on the screen, you want him to do something. Most of the time, you will use the Play method to tell the character what to do. These actions are called animations and must have been taught to the characters. For the 4 MS Agents default characters, you can find a complete list of their animations in the MSDN library. The Microsoft Agent Ring website I already linked you too also list available animations for each characters. The syntax to animate is quite simple. You call the Play method and pass the name of the animations in the single arguments:
mobjCharacter.Play("Announce")
To discover at runtime the list of animations available from a character, add a button and a listbox (name it lstAnimations) to your form and paste this code into the button’s click event: loop:
Dim Animation As Object
For Each Animation In mobjCharacter.AnimationNames
lstAnimations.Items.Add(Animation)
Next
You can now easily have the character play the selected animation from the list using this code: mobjCharacter.StopAll()
mobjCharacter.Play(lstAnimations.SelectedItem.ToString)
The reason why I call the StopAll method before calling the Play method is because some animations are looping until we stop them.
Characters can also speak
At least, characters can easily display text into a balloon using the Speak method to mimic that they are talking. If your installation is correct, it can even talk for real (see the line “Text-to-speech engine” from the Microsoft agent detector web site). If you are running Windows XP, you may need to reinstall SAPI 4.0 (which is available from http://www.microsoft.com/MSAGENT/downloads/user.asp).
To test the speaking capabilities, add a textbox and a button to your form and paste this code:
mobjCharacter.Speak(txtToSpeak.Text)
Figure 2: Demo in action
Extending MS Agent
If you need to create your own characters from almost any bitmap image, you will need the Agent Character editor that you can download from http://www.microsoft.com/msagent/downloads/developer.asp#ace.
Conclusion
Faking some life into your applications is simple, can be fun for you to program and can make your users smiling. If you add one of these characters to your own application, just be sure to give users the availability to disable them (just like you probably into Office applications on your own PC!).
I hope you appreciated the topic and see you next month.