Microsoft

Adding a unique user interface to your scripts with Microsoft Agent technology

Getting your point across has never been easier with Microsoft Agent technology. If you want to animate your next software application rollout, check out this Daily Drill Down by Greg Shultz, with an accompanying download that ties it all together.


If you’ve been following along with my Windows Script Host series, you know I’ve repeatedly mentioned the one downside to the native scripting languages is that they are sorely lacking in the user interface department. I feel this severely limits the ability to create nice-looking interactive scripts. There are only two types of dialog boxes available in Windows Script Host: VBScript and, to a lesser degree, JScript. VBScript offers an input dialog box with which you can prompt the user to type information in a text box and a message box in which you can display buttons and prompt the user to make a selection by clicking one of them. Regrettably, there are only a few standard buttons to choose from, and there’s no way to customize the button text.

However, I recently discovered a way to compensate for this lack of user friendliness by using Microsoft Agent technology to enhance the user interface of Windows Script Host scripts. As you may know, the Microsoft Agent technology allows the creation of interactive animated characters. The characters can move freely around the screen, use a whole series of social gestures, speak using synthesized speech, and can now even listen and respond to verbal communications. When combined with the typical Windows user interface features, the Microsoft Agent technology can be used to enhance all sorts of applications—particularly in the area of user assistance.

Microsoft Agent technology includes an ActiveX control that makes it possible to create and use these animated characters in Windows Script Host. This brings a powerful new technology within the grasp of your users. Just think of the possibilities that it can offer in the area of technical support. Using VBScript, you can create Microsoft Agent characters that answer common technical support questions, assist users in making configuration settings, or describe new software.

In this Daily Drill Down, I’ll show you how to incorporate Microsoft Agent technology in scripts created for the Windows Script Host. I’ll use layman’s terms to explain the basics of programming Microsoft Agent characters in VBScript. I’ll also provide you with a script and a VBS demonstration file that exhibits a Microsoft Agent character’s capabilities, available as a separate download.

Getting the Microsoft Agent components
Before you can use the Microsoft Agent technology in your scripts, you have to download and install a few components on each system. Fortunately, doing so is quite easy.

First, you need the Microsoft Agent core components, which are now in version 2. If you’re running Windows Me or Windows 2000, you already have Microsoft Agent 2 core components. If you’re running Windows 95, Windows 98, or Windows NT, you can download the Microsoft Agent 2 core components from the Microsoft ActiveX site.

Once you have downloaded and installed the Microsoft Agent 2 core components, you’ll need to download and install the Text-To-Speech Engine, which allows the Microsoft Agent characters to talk. The Text-To-Speech Engine needs to be added to all versions of Windows. You can download the Text-To-Speech Engine from the MSDN Online Web Workshop site.

The Microsoft Agent technology has the ability to change the pitch of the voice it uses. Since the script presented in this Daily Drill Down demonstrates this capability, you’ll need to download and install the Speech API (SAPI) runtime binaries. You can download the SAPI runtime binaries from the MSDN Online Web Workshop site.

When you add the Text-To-Speech Engine and the SAPI runtime binaries to your system, you’ll also want to add the Speech Control Panel. This utility allows you to list the speech recognition and text-to-speech engines installed on your system and to view and customize the settings. You can download the Speech Control Panel from the MSDN Online Web Workshop site.

Finally, you’ll want to download and install a Microsoft Agent Character. There are a number of characters available from Microsoft, as well as from third-party developers. The script in this Daily Drill Down uses the Merlin character, which by default comes with both Windows 2000 and Windows Me. You can download Merlin and the other Microsoft characters from the MSDN Online Web Workshop site. You can find a great selection of other characters on the Microsoft Agent Ring.

While I won’t cover it in this Daily Drill Down, you may also want to download and install the Speech Recognition Engine, which, with the right programming, will allow you to talk to the Microsoft Agent characters and have them respond to your requests. You can download the Speech Recognition Engine from the MSDN Online Web Workshop site.

Incorporating the Microsoft Agent technology in a script
As I mentioned, the Microsoft Agent technology includes an ActiveX control that makes it possible to access its animated characters in Windows Script Host. However, since the Microsoft Agent technology is quite unique, there are some special programming/scripting techniques you’ll need to employ to incorporate Microsoft Agent technology in Windows Script Host.

Initializing a Microsoft Agent character
Since an ActiveX control is essentially an object, you’ll basically activate a Microsoft Agent character in a script the same way you activate an object in any script. However, there are a few special considerations. Let’s take a look at the lines of code shown in Listing A that initialize the Merlin character.

As you can see, line 1 uses a Dim statement to define and allocate space in memory for the variables that will be used to access the Microsoft Agent object. In line 2, the CreateObject command initializes the Microsoft Agent object—Agent.Control.1—and assigns it to the MyAgent variable. This allows you to easily access all the properties and methods associated with the Microsoft Agent object.

Unlike other objects, which are ready to use as soon as you initialize them, the Microsoft Agent object requires an additional step. This consists of setting the Connected property equal to True, as shown in Line 3, which alerts the Windows Script Host that the Microsoft Agent object is available.

Now that the Microsoft Agent object is ready to go, you’re ready to load one of the characters. To do so, you use the Load method, as shown in line 4. You need to tell the Load method which character you want to load and where to find the character file.

In this example, I’m instructing the Load method to access the Merlin character, which is stored in the Merlin.acs file in the C:\Winnt\Msagent\Chars folder on my example Windows 2000 system. If you’re running Windows 9x/Me, the character files are stored in the C:\Windows\Msagent\Chars folder, so you’ll need to change the path accordingly.

Once you load the Microsoft Agent character you want, you will next issue a Set command to assign a character object to a simple variable. You’ll then be able to access all of the Microsoft Agent character’s capabilities via that variable. In line 5, I assign the Merlin character object to a variable appropriately called Merlin.

To make the Microsoft Agent character appear on the screen, you use the Show method. Line 6 demonstrates the use of the Show method to conjure up the Merlin character.

Synchronizing a Microsoft Agent character
When you use a Microsoft Agent character in a Windows Script Host script, you need to synchronize the operation of the Microsoft Agent character with the script. This is due to the fact that Windows Script Host will process the lines of script faster than the Microsoft Agent object will be able to respond to animation requests that the script makes to it. Thus, the script will finish running before the Microsoft Agent character can perform whatever tasks you assign to it in the script. In other words, the script will end and you’ll never see the Microsoft Agent character.

In order to synchronize a Microsoft Agent character with a Windows Script Host script, you’ll need to add a looping structure at the end of the script that keeps the script running until the Microsoft Agent object finishes responding to all of the animation requests called from the script.

To do so, you’ll take advantage of the fact that once the Microsoft Agent character completes its assigned animations, it will automatically hide itself. You then set up the looping structure so it runs until the Microsoft Agent character hides itself. The lines of code shown in Listing B illustrate this technique and will appear at the end of a script that uses the Microsoft Agent technology.

Listing B: Synchronizing an agent 
Set AnimationComplete = Merlin.Hide 
Do Until AnimationComplete.Status = 0
Wscript.Sleep 100
Loop  


In line 1, I set up an object variable called AnimationComplete and assign it to the Hide method. Lines 2 through 4 set up a Do…Loop statement that accesses the Status property and checks its value. As long as the Microsoft Agent character is performing some task, the Status property contains a value of either 2 or 4; the former indicates pending animation requests, and the latter indicates that an animation request is in progress. I then pause the loop using the Windows Script Host Sleep method, which processes time in milliseconds. Since I don’t want the script to pause too long before it recognizes that the Status property is set to 0, I use a value of 100, which only pauses the loop for slightly longer than the blink of an eye.

As soon as the Microsoft Agent character completes its assigned animations and automatically hides itself, the Status property contains a value of 0. Once that happens, the loop exits.

Terminating a Microsoft Agent character
As soon as the Do…Loop shown in Listing B exits, you’ll need to terminate the Microsoft Agent character before exiting the Windows Script Host. To do so, set the Microsoft Agent character variable to Nothing, as shown in line 1 of Listing C. You’ll then use the Unload method to remove the character, as shown in line 2, before you exit the script and the Windows Script Host in line 3.

Listing C: Terminating an agent 
Set Merlin = Nothing
MyAgent.Characters.Unload "Merlin"
Wscript.Quit


Animating a Microsoft Agent character
Animating a Microsoft Agent character is easy! However, before you can do so, you need to know what animations are available for a particular character. You can usually view or download a detailed list of a character’s animations when you download a character. For example, you can view a list of the animations for the Merlin character from the MSDN Online Library.

Moving around the screen
Regardless of which particular animations are associated with a character, you’ll move all characters around the screen using the MoveTo method. When you use the MoveTo method, each character will use a unique moving animation associated with that character’s theme. For example, Merlin dons a propeller beanie and flies from one location to another, while Robby the robot uses a jet pack.

To use the MoveTo method, you need to specify X, Y coordinates based on screen pixels as parameters. As you specify X, Y coordinates, keep in mind that the origin of the coordinates are 0, 0, which corresponds to the upper-left corner of the screen. Furthermore, the coordinates you specify as parameters reference the upper-left corner of the character’s animation frame.

Listing D: Moving an agent 
Merlin.MoveTo 0, 0
Merlin.MoveTo 300, 225
Merlin.MoveTo 700, 475


For example, the parameters passed to the MoveTo method shown in line 1 of Listing D will position the Merlin character in the upper-left corner of the screen. The parameters passed to the MoveTo method shown in line 2 will position the Merlin character about dead center of a screen that’s using a display resolution of 800x600, while the parameters used in line 3 will position the Merlin character in the bottom-right corner of that same screen.

Social gesturing
Almost all of the Microsoft Agent characters have a wide range of social gestures in their lists of animations. To get a character to perform one of its animations, you’ll use the Play method and pass it the name of the animation as a parameter. In Listing E, the Greet animation parameter passed to the Play method will make the Merlin character bow. The Pleased animation parameter will make the Merlin character smile, while the GestureRight animation parameter will make the Merlin character point to the right.

Listing E: Animating an agent 
Merlin.Play “Greet”
Merlin.Play “Pleased”
Merlin.Play “GestureRight”


Making a Microsoft Agent character talk
As long as you have the Text-To-Speech Engine installed, all Microsoft Agent characters can talk. To make them talk, you’ll use the Speak method and pass it a text string as a parameter. The Speak method recognizes all punctuation. This means that the character will pause for commas and periods, as well as add the appropriate inflections for exclamation points and question marks. Lines 1 through 3 in Listing F demonstrate how you can use the Speak method to have Merlin enthusiastically introduce himself and ask a question.

Listing F: Making an agent talk 
Merlin.Speak(“Hello! My name is Merlin.”)
Merlin.Speak(“I am a Microsoft Agent!”)
Merlin.Speak(“How are you?”)


Changing the voice
If you installed the SAPI runtime binaries, you can change the default voice of a Microsoft Agent character. To do so, access the TTSModeID property through the Microsoft Agent character object and pass it a parameter that is associated with a specific voice. When you download the SAPI runtime binaries, you’ll have 10 voices to choose from—eight male voices and two female voices. Those voices and their associated ModeID values are listed in Table A.

Table A
Voice ModeID
Adult Male #1 CA141FD0-AC7F-11D1-97A3-006008273000
Adult Male #2 CA141FD0-AC7F-11D1-97A3-006008273001
Adult Male #3 CA141FD0-AC7F-11D1-97A3-006008273002
Adult Male #4 CA141FD0-AC7F-11D1-97A3-006008273003
Adult Male #5 CA141FD0-AC7F-11D1-97A3-006008273004
Adult Male #6 CA141FD0-AC7F-11D1-97A3-006008273005
Adult Male #7 CA141FD0-AC7F-11D1-97A3-006008273006
Adult Male #8 CA141FD0-AC7F-11D1-97A3-006008273007
Adult Female #1 CA141FD0-AC7F-11D1-97A3-006008273008
Adult Female #2 CA141FD0-AC7F-11D1-97A3-006008273009
Voices included with the SAPI runtime binaries

For example, to change the default voice associated with the Merlin character to the Adult Male #1 voice, you’d use this command.

Putting it all together
Once you know how to use the basic techniques I’ve introduced so far, you’ll be able to easily implement the Microsoft Agent technology with VBScript in a Windows Script Host environment. To help you get started, I’ve created a demonstration script in which Merlin himself introduces you to the Microsoft Agent technology. Since this script is simply intended as a demonstration of the Microsoft Agent technology and uses techniques that I’ve already described in this and some of my previous Daily Drill Downs, I won’t go into detail on the script. However, be sure that you type all the commands exactly as shown. If you don’t, the script will not work correctly. When you’ve finished, save the file as MerlinDemonstration.vbs.

If typing in lines of code isn’t your cup of tea, don’t worry; the MerlinDemonstration.vbs script is available for download. If you want to learn more about the Microsoft Agent technology, be sure to investigate the Microsoft Agent documentation page on the MSDN Online Library site.

About Greg Shultz

Greg Shultz is a freelance Technical Writer. Previously, he has worked as Documentation Specialist in the software industry, a Technical Support Specialist in educational industry, and a Technical Journalist in the computer publishing industry.

Editor's Picks

Free Newsletters, In your Inbox