README.md

December 4, 2022 · View on GitHub

This is my fifth tutorial on Ms Agent. In this tutorial I went beyond the basics, so even advanced VB coders will be able to use some of this code. This tutorial is VERY EXTENSIVE, but beginners never fear - as this tutorial is based on my other acclaimed tutorials for beginners, you will be able to understand this tutorial with ease.

More Info


Submitted On
By	Mahangu
Level	Beginner
User Rating	4.9 (97 globes from 20 users)
Compatibility	VB 4.0 (16-bit), VB 4.0 (32-bit), VB 5.0, VB 6.0
Category	Complete Applications
World	Visual Basic
Archive File

Source Code

Ms Agent - Beyond the Basics

Introduction

Understanding this tutorial

Through out this tutorial you will see text like this - italic text and green italic text . The normal italic text means that the text is code and can be copied and pasted straight into your application. The green italic text means that the text is a comment (you will often see this type of text beside code) that was place to show you how to do something or to give you an example.

Index

Getting Started - Provides all the data you need to jump start your Agent application

Declaring the Character File - Shows how to declare the Character file for use in VB

Initializing the Character - Shows how to initialize the Character file

Displaying Various Animations - Shows how to get the Character to display various animations

Using Ms Agent With VB Script - Shows you how to use Ms Agent with VB Script

Events and Properties of the Agent Control - Describes the Events and Properties of the Agent Control

Fun Agent Code to Add to your Applications - Gives some cool code which makes the Character do some fun things

Examples of How you can use the Agent Control - Gives some ideas as to how you can use the Agent Control

Frequently Asked Questions - Various related questions and their answers.

Getting Started

In order to use this tutorial you will need Microsoft Visual Basic 5 or 6 (parts of this tutorial may work in VB 4 if you have Agent 1.5 installed). You will also need the Speech Synthesis libraries from MSDN along with a Microsoft Agent Character File (*.acs file).

MS Agent is an ActiveX control supplied with Microsoft Visual Basic 5 and 6. It can be used in many other ways but the most popular use is for creating 'Desktop Pets'. At the moment there are 4 different characters to chose from - Peedy the Parrot, The Genie, Merlin the Wizard and Robby the Robot. In this tutorial I have used Peedy the Parrot as an example.

To start making your first Microsoft Agent application, open Visual Basic and chose standard exe. Then right click the toolbar and add the the Microsoft Agent Control. You will see a new Icon (it looks like a secret agent with sunglasses). Then double click on the icon on the toolbar to place the control on the form. You can rename this control to whatever you want but in the code I'm going to call it Agent1.

Declaring the Character file

We need to to tell VB that we are using the character file so we need add the following code to the general declarations.

Dim char As IAgentCtlCharacterEx 'Declare the String char as the Character file

Dim Anim as String 'Dim the Anim string which we will use later on (declaring this will make it easy for us to change the character with ease, later on)

Char.LanguageID = &H409 'This code is optional. The code worked fine without it but we will add it for usability purposes (it sets the language ID to English)

Initializing the Character

We need to tell VB, who the character is and where his *.acs file is. So we'll use the following code.

Anim = "Peedy" 'We set the Anim String to "Peedy" . You can set this to Genie, or Merlin, or Robby too.

Agent1.Characters.Load Anim, Anim & ".acs" 'This is how we tell VB where to find the character's acs file. VB by default looks in the C:\Windows\MsAgent\Chars\ folder for the character file

Set char = Agent1.Characters(Anim) 'Remember we declared the char string earlier? Now we set char to equal Agent1.Charachters property. Note that the because we used the Anim string we can now change the character by changing only one line of code.

char.AutoPopupMenu = False 'So the Character wont keep displaying it's annoying popup menu every time you right click him. You can now add your own popup menu (see examples).

Char.Show 'Shows the Character File (If set to "Peedy" he comes flying out of the background)

Getting to Know The Different Characters

As far as I know, there are 4 different characters you can use with Ms Agent. You can download them all from the Ms Agent Developers Website ( http://msdn.microsoft.com/msagent ). Although you can configure each character to your own liking, they tend to convey different types of impressions.

Peedy - The first agent character (I think). He is a temperamental parrot (that's the way I see him). I use him mostly to add sarcasm to my apps. Has an (sort of) annoying voice - squeaky in parroty sort of way. You use him to some cool stuff though.

Genie - Cool little guy to add to your apps. Can do some neat stuff too! Use him to add a touch of class and mystery to your apps. Has an OK voice and has a cool way of moving around.

Merlin - Your neighborhood Wizard! Always has the look that he is total control. Also has a vague look of incomprehension (that's the way I see it!). Useful little dude but I don't like the way he moves around (wears beanie and flies).

Robby - Probably the newest addition to the series. Never got down to downloading him but I hear that he is an Robot / Monkey??

What? You don't like any of these characters? Wanna create you're own? It's not easy.. but you can give it a shot... Just visit the MSDN page for Ms Agent (check FAQs for web address).

Displaying Various Animations

Through code, we can make the character do some cool stuff. Apart from talking he can do various interesting things. The following code may be pasted into any event in VB (Form_Load, Command1_Click).

Showing the Character

This code is used to bring the character on to the screen.

char.show

Hiding the Character

This code is used to hide the character (take him off the screen).

char.hide

Making Him Talk

The code for this is relatively simple and this works with every character. You can customize this code for him to say anything. The text appears in a speech bubble but can also be heard.

Char.Speak "Your Message Here" 'Says "Your Message Here"

Making Him Think

The code for this is relatively simple and this works with every character. You can customize this code and make him think of anything. The text appears in a thought bubble and cannot be heard.

Char.Think "Your Message Here" ' "Your message here" appears in a though bubble

Making Him Move To Somewhere Else On The Screen

This code too is pretty simple and works on every character. You can move him anywhere on the screen be changing the co ordinates. Please note that screen co ordinates vary from resolution to resolution. For example on a 640 x 480 resolution monitor 300,500 is off the screen wile on a 800 x 600 monitor the co ordinates are on the screen.

char.MoveTo 300, 300 'This code will move him to the screen co ordinates 300,300

Also note that in the code 300,300 we are referring to the screen as x , y (horizontal , vertical).

Making Him Stay In His Rest Pose

This code brings him back to the way he was started

char.play "Restpose" 'Note - To get out of the rest pose you will have to use the char.stop function (see below)

Making Him Stop Whatever He Is Doing

Sometimes you may need to stop the Character from doing something. This code makes him stop everything and wait.

char.stop 'Character stops whatever he is doing

Making Him Read, Write, Process and Search

The character can various animations that may prove useful in your applications.

char.Play "Write" 'The character writes for a while and then stops

char.Play "Writing" 'The character writes until the char.stop function is executed

char.Play "Read" 'The character reads for a while and then stops

char.Play "Reading" 'The character reads until the char.stop function is executed

char.Play "Process" 'The character processes for a while and then stops

char.Play "Processing" 'The character processes until the char.stop function is executed

char.Play "Search" 'The character searches for a while and then stops

char.Play "Searching" 'The character searches until the char.stop function is executed

Making Him Show Facial Expressions

The character can show various facial expressions that may be useful in your application.

char.play "Acknowledge" 'This code makes the character acknowledge something

char.play "Alert" 'This code makes the character look alert

char.play "Blink" 'This code makes the character blink

char.play "Confused" 'This code makes the character look confused

char.play "Decline" 'This code makes the character decline something

char.play "DontRecognize" 'This code makes the character look like he doesn't recognize something

char.play "Hearing_1" 'This code makes the character look like he is listening (left)

char.play "Hearing_2" 'This code makes the character look like he is listening (right)

char.play "Hearing_3" 'This code makes the character look like he is listening (both sides)

char.play "Hearing_4" 'This code makes the character look like he is listening (does not work on peedy)

char.play "Pleased" 'This code makes the character look pleased

char.play "Sad" 'This code makes the character look sad

char.play "Surprised" 'This code makes the character look surprised

char.play "Uncertain" 'This code makes the character look uncertain

Making Him Look Somewhere

The character can look at different angles.

char.play "LookDown" 'Looks Down

char.play "LookDownBlink" 'Looks and Blinks

char.play "LookDownReturn" 'Stops looking and returns to restpose

char.play "LookUp" 'Looks Up

char.play "LookUpBlink" 'Looks and Blinks

char.play "LookUpReturn" 'Stops looking and returns to restpose

char.play "LookRight" 'Looks to the Right

char.play "LookRighBlink" 'Looks and Blinks

char.play "LookRightReturn" Stops looking and returns to restpose

char.play "LookLeft" 'Looks to the Left

char.play "LookLeftBlink" 'Looks and Blinks

char.play "LookLeftReturn" 'Stops looking and returns to restpose

Making Him Do Various Gestures

The character can do various gestures that can be quite useful.

char.play "GestureUp" 'Gestures Up

char.play "GestureRight" 'Gestures Right

char.play "GestureLeft" 'Gestures Left

char.play "GestureDown" 'Gestures Down

char.play "Explain" "Explains Something

char.play "GetAttention" 'Gets the users attention

char.play "Greet" 'Greets the User (by action)

char.play "Announce"

char.play "Congratulate_1" 'Congratulates user

char.play "Congratulate_2" 'Congratulates user

char.play "DoMagic1" 'Does Magic 1 - Can be used with DoMagic2

char.play "DoMagic2"

char.play "StartListening" 'Starts Listening

char.play "StoptListening" 'Stops Listening

Making him Gesture at a specific location on Screen

Using the GestureAt property you can get the Character to point at a specific screen co ordinate. More useful than GestureRight and GestureLeft because using this you can point diagonally too.

char.GestureAt 300,300 'Character points at screen co ordinate 300,300

Events and Properties of the Agent Control

Events

Using the Agent1_IdleStart event to set what the Agent does when He is Idle

You can place code in the Agent1_IdleStart event to tell VB what the agent does when he is idle. The Agent can do the following idle stuff. Please note that some functions may not work for some characters. You can put the following functions in a loop or just let them run. Also note that some functions cannot be stopped unless the char.stop command is used. You may also include any other functions in the Agent1_IdleStart event.

char.play "Idle1_1"

char.play "Idle1_2"

char.play "Idle1_3"

char.play "Idle1_4"

char.play "Idle1_5"

char.play "Idle1_6"

char.play "Idle2_1"

char.play "Idle2_2"

char.play "Idle2_3"

char.play "Idle3_1"

char.play "Idle3_2"

char.play "Idle3_3" 'This one works only for Peedy I think! - He listens to music!

Using the Agent1_Complete event to set what the Agent does when He is finished idling

This tells VB what to with the agent once he is finished idling. Example -

char.play "Restpose" 'This will put the character in his default rest pose

Using the Agent1_Click event to Set what happens when the Character is clicked

You can place some code in the Agent1_Click event to tell VB what to do when the user clicks on the character. You can place almost any command here. Example -

char.play "Alert"

Using the Agent1_Move event to Set what happens when the Character is moved

You can place some code in the Agent1_Move event to tell VB what to do when the user moves the character. You can place almost any command here. Example -

char.play "Surprised"

Using the Agent1_DragStart event to Set what happens when the user starts to drag the Character

You can place some code in the Agent1_DragStart event to tell VB what to do when the user starts to drag the character. You can place almost any command here. Example -

char.play "Think"

Using the Agent1_DragStop event to Set what happens when the user stops dragging the Character

You can place some code in the Agent1_DragStop event to tell VB what to do when the user stops dragging the character. You can place almost any command here. Example -

char.play "Blink"

Using the Agent1_BalloonHide event to Set what happens when the Character's speech balloon is shown

Using this event you can set what happens every time the speech balloon is shown (basically every time the character starts speaking).

Using the Agent1_BalloonShow event to Set what happens when the Character's speech balloon is hidden

Using this event you can set what happens every time the speech balloon is hidden (basically every time the character stops speaking).

Properties

Using the SoundEffectsOn property to switch the Characters sound effects on / off

Using this property you can toggle the characters sound effects on an off. Useful if you want the character to stay silent for a while

char.SoundEffectsOn = True Turns sound effects on

char.SoundEffectsOn = False 'Turns sound effects off

Using the IdleOn property to toggle the Character's idle mode on / off

Using this property you can toggle the character's idle mode on an off.

char.IdleOn = True 'Sets Idle Mode On

char.IdleOn = False 'Sets Idle Mode Off

Using the AutoPopupMenu property to toggle the default (Agent's) popup menu on and off

Using this propert you can set the agent's popup menu on or off. This menu has only one option (hide) ,so by it is not really useful. If you want a popup menu for your character see the Agent Right Click Popup Menu Example (below) on how to create custom popup menus. As you may have noticed, in the 'Initializing the Character' section I have turned off the auto popupmenu. Never the less you can use the following code to toggle it on or off.

char.AutoPopupMenu = True 'Turns Auto PopMenu On

char.AutoPopupMenu = False Turns Auto PopMenu Off

Using the Connected property to set whether the Agent is connected to the Microsoft Agent Server

Using this you can set whether the control is connected to the Microsoft Agent Server (useful for creating client / server applications).

char.Connected = True 'Not Connected

char.Connected = False 'Connected

Using Ms Agent with VB Script

Ms Agent can be used in VB script too. VB script 2.0 is needed to do so. Here is an example. Using VB script is very useful if you want to include MS Agent on your web page. Please note - I am not too familiar with VB script so If there are any syntax errors please let me know.

Using the Connected property to set whether the Agent is connected to the Microsoft Agent Server

Using this you can set whether the control is connected to the Microsoft Agent Server (useful for creating client / server applications).

char.Connected = True 'Not Connected

char.Connected = False 'Connected

Initializing The Character

To initialize the character you will need to contact the Agent Server.

<SCRIPT LANGUAGE = “VBSCRIPT”>

<!—-

Dim Char 'Declare the String Char

Sub window_OnLoad 'Window_Onload Event

AgentCtl.Characters.Load "Genie", "http://agent.microsoft.com/characters/v2/genie/genie.acf"

‘Create an object with reference to the character on the Microsoft server

set Char= AgentCtl.Characters ("Genie") 'Set the the Char string to = The Agent Cotnrol

Char.Get "state", "Showing" ‘Get the Showing state animation

Char.Show 'Show the Character

End Sub

-->

</SCRIPT>

Sending Requests to the Server

You will need to send requests to the agent server in order to do certain commands.

Dim Request

Set Request = Agent1.Characters.Load ("Genie", "http://agent.microsoft.com/characters/v2/genie/genie.acf") 'Sets the request

If (Request.Status = 2) then 'Request is in Queue

'Add your code here (you can send text to status bar or something)

Else If (Request.Status = 0) then 'Request successfully completed

'Add your code here (you can do something like display the annimation)

End If

Showing Animations

If you are using VB script you will need to get the animations from a server using the Get method. For example the following code will get all the 'Moving' animations which the character needs.

AgentCtl.Characters ("Peedy").Get "Animation", "Moving", True

After an animation is loaded you should be able to play it in the usual way.

Examples of How you can use the Agent Control

Agent Right Click Popup Menu Example

This code is very useful if you only want to have the agent visible on the screen and not the form. Now you can set the agent to display a popup menu so that you wont have to display the form. To use this you will need a Form called frmMain and in that form a Menu Item called mnuMain. mnuMain must have submenus. You can type the following code into the Agent1_Click Event

if Button = vbRightButton then frmMain.popupmenu mnuMain 'This code will display the popup menu only if the user right click son the age

Now all you have to do is to add submenus and functions to the mnuMain menu item!

Agent1_IdleStart Event Example

When the user does not click on or interact with the Agent for a long time it automatically sets itself to idle. So you may want to add some functions to make the agent do stuff while the user is not working with him. You may add the following code to the Agent1_IdleStart Event -

10 'Specify line number so that we can loop back later

char.play "think"

char.play "read"

char.play "write"

Goto 10 'Tells VB to go to the line number which was specified earlier

You may also want to add the following code to the Agent1_Click Event so that the character will stop doing hid idle part when the user clicks on him - char.stop

Fun Agent Code to Add to your Applications

Character 'Dive' Code Example

This is some fun code I sometimes use in applications. It creates a cool effect.

char.Play "LookDownBlink" 'Looks down and blinks
char.Play "LookDownBlink" 'Looks down and blinks
char.Play "LookDownBlink" 'Looks down and blinks
char.Play "LookDownReturn" 'Stops looking down
char.Stop 'Stops what he is doing
char.MoveTo 300, 700 'Moves him to co ordinates 300,700 (off the screen!)
char.Speak "Man It's really dark ..inside your monitor!" 'Speaks char.MoveTo 300, 50 'Move him to co ordinates 300,50
char.Speak "Nice to be back!" 'Speaks

Character 'Move Around' Code Example

This is some fun code I sometimes use in applications. It looks really funny on Peedy! Note - you may have to change the screen co ordinates to suite your resolution.

char.MoveTo 2000, 300 'Moves him to co ordinates 2000,300 (off the screen!)
char.MoveTo 300, 300 'Moves to co ordinates 300,300 (lower middle of screen)
char.Play "confused" 'Looks Confused
char.Speak "Nothing like a little flying to clear the head!" 'Speaks
char.Play "pleased" 'Looks pleased

Character 'Open Notepad' Code Example

This code makes the character look like he is writing in his notepad while you use your notepad.

char.MoveTo 50, 1 'Moves character to upper left hand corner of the screen
char.Speak "Let's use notepad!" 'Speaks
char.Play "Writing" 'Character starts writing
Shell "Notepad.exe", vbNormalFocus 'Opens Notepad with Normal Focus

Character 'Grow' Code Example

This code makes the Character grow big! Looks really cool (you tend to see the pixels though). You can customize the code to make the character any size you want.

char.Height = "750" 'Sets the Characters Height

char.Width = "450" 'Sets the Characters Width

Character 'Shrink' Code Example

This code makes the Character shrink! Looks really cool (the animations don't look as good though). You can customize the code to make the character any size you want.

char.Height = "75" 'Sets the Characters Height

char.Width = "25" 'Sets the Characters Width

Using an Input Box to let the User specify what the Character Says

This code is very useful because it lets the user decide what the the character says.

Message = InputBox("What do you want Peedy to say?") 'Sets the Message String to equal the input box. Also sets the input box's heading
char.Speak Message 'Speaks out the text in the Message String

Using a Text Box to let the User specify what the Character Says

This code is useful to make the character read a whole document. You can load text in to a text box and then tell the character to read it. The following example requires a text box called Text1.

if Text1.text <> " " then char.speak text1.text 'Checks to see if the text box is empty. If it is not empty then it tells the character to speak the text.

End if

Frequently Asked Questions

How do I know if I have a Microsoft Agent Character file(s) on my computer?

Just goto Start > Find > Files or Folders and search for the extension *.acs . If you find any such files in your C:\Windows\MsAgent\Chars\ folder then you are luck. If you have a file called Peedy.acs then this tutorial will work. Otherwise just specify Anim = "Your Character's Name).

Hey I'm too lazy to go sifting through all that... is there some way I can do it through code?

Yes there is a way.. just add this code to a form that has a agent control on it called Agent 1. This code will show a box which has all the character files installed on your computer. Look through that and you will know if you have character files or not. Here is the code

Agent1.ShowDefaultCharacterProperties

I don't have the file(s). Where can I download them from? Are they freeware?

The agent files can be freely downloaded, but you are never the less bound by the Microsoft EULA (End User License Agreement). For more information go to the URL specified below. The agent files (inlcuding the character files) are available for download on http://msdn.microsoft.com/msagent

Why don't some functions (commands) work on some character files?

Some versions of character files will have more functions, so in order use all the functions you may need to get a new character file. For example the char.play "Idle3_3" function does not work on Robby.

Sometimes the character doesn't stop what he is doing for a long time... how can I force him to stop?

Some functions take a long time to finish or may even loop for ever so you may have to force a stop. Just add the char.Stop or the char.StopAll function to an event to stop the character. When this function is called the character will automatically stop doing what he was doing and go to his rest pose.

Can I use the Ms Agent in my applications?

Yes! as far as I know Microsoft is distributing this freely across the internet. You can use the control freely (for more info go to the MSDN site - msdn.microsft.com ), and you can use any of the code you see in this tutorial freely!

How can I change the character file?

In lots of examples I have seen, in order to change the character file you need to change a lot of code. But if you used my code you only have to change one line of code. All you have to do is to set the Anim String to equal the character you want. For example to choose Peedy just type the following code Anim = "Peedy". Note that you can only change the character if you have the character installed on your machine.

Can I use Ms Agent in VB 4.0?

I have got reports that you can use Ms Agent 1.5 in Visual Basic 4. I am not sure if it will work in VB 4.0 (16 Bit), but it should work in VB 4.0 (32 Bit).

Can I use Ms Agent in Java?

As far as I know you can. I saw some Java code on the MSDN site. You may want to check out the site (see below for URL).

Where can I get more info on Ms Agent?

Microsoft's official Ms Agent developer page is at - http://msdn.microsoft.com/msagent

When are you going to add a Speech Recognition Section?

Have patience. I will add this tutorial as soon as possible (I am working on it!).

What can I expect in your next tutorial?

Frankly... a lot! I hope to add a speech recognition section as well as how to control Ms Agent via API.

THE END

A lot of hard work has gone into this tutorial. I have spent many hours writing this article in an easy to understand manner. If you like this please vote for me. Also feel free to post any comments or suggestions as to what I can include in the next version.

Ms Agent - Beyond the Basics

Description

More Info

Source Code