Search Tools Links Login

MS Agent Control Tutorial for Absolute Beginners


This tutorial will teach you how to use the MS Agent control. It will show you how to get a character file associated with MS Agent and then how to use it in different ways. Does not require any previous knowledge of using the control. While this tutorial shows you the inns and outs of using the MS Agent control and the various characters that can be associated with it, it also shows every step in an easy to understand manner. Although this extensive tutorial covers nearly all the aspects of using the MS Agent Control, even novice programmers will be able to understand this tutorial and use the example code in their own applications. 

Original Author: Mahangu

Code

 


How to use the
MS Agent Control for Absolute Beginners


 


Introduction


This tutorial will teach you
how to use the MS Agent control. It will show you how to get a character file
associated with MS Agent and then how to use it in different ways. Does not
require any previous knowledge of using the control. While this tutorial shows
you the inns and outs of using the MS Agent control and the various characters
that can be associated with it, it also shows every step in an easy to
understand manner. Although this extensive tutorial covers nearly all the
aspects of using the MS Agent Control, even novice programmers will be able
to understand this tutorial and use the example code in their own
applications. 


 


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.


 


New In this Version


In this version I have added a 'Fun Code'
section where you can get some cool code that makes the characters act in
different ways. I have also updated the 'Customizing the Agent Control' by
describing some new properties you can change. I have also made a few minor
adjustments to other areas of the tutorial.


Getting Started


In order to use this tutorial you will need
Microsoft Visual Basic 5 or 6. 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 monkey. 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:WindowsMsAgentChars
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)


 


 


Doing Stuff With
the Character


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


 


 


 


Customizing the
Agent Control


 


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"


 


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 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


 


 


 


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:WindowsMsAgentChars
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?


Yes, the Agent Character files are freeware
and can be downloaded from MSDN (Microsoft Developer Network).


 


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


Well the latest version character files will
have more functions (Robby the Monkey is the latest I think), so in order use
all the functions you may need to get a new character file. For example the char.play
"Idle2_3"
function does not work on Peedy.


 


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 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.


 


 


THE END


I've worked for a 
long time to get this tutorial to you so I would really appreciate some feedback and votes!
You are free to use the example source code in your applications.


About this post

Posted: 2002-06-01
By: ArchiveBot
Viewed: 105 times

Categories

Visual Basic 6

Attachments

CODE_UPLOAD1211111272000.zip
Posted: 9/3/2020 3:45:00 PM
Size: 3,196 bytes


Loading Comments ...

Comments

No comments have been added for this post.

You must be logged in to make a comment.