<!-- Article image -->
What is Microsoft Agent?
Microsoft Agent is a great technology. It's a set of services that supports the presentation of interactive
animated characters. It can be used in a variety of cases to introduce, guide, entertain or others. For example,
your're coding an address book. It will be great if you add some cool technique to communicate with the user. MsAgent
can also be placed on the web page but it's another stroy.
This article is about the set of wrapper classes which I've written recently. I needed several things which were not
included. I decided to write them on my own:
- Tip window - a little window with a light bulb inside.
- InputBalloon - a window with controls. It's used to obtain data from the user. The balloon's very similar to the one from office assistant (see picture)
How to add it to the project?
The library consists of several classes. First download the source files and unpack them. Then add all files to the
project except AgtErr.h, AGTSVR.H and AgtSvr_i.c. Open Agent.h. At the very beginning you will see the
constants shown below. If you don't want to use tip/input balloon comment them out.
#define BALLOONINPUT // Input MFC balloon
#define TIP // Tip MFC balloon
Next you should add appropriate bitmaps which will be used in a balloon and tip window - only if you want to use
this features. They are shown on the picture 1
- IDB_BUTTON - bitmap which contains 3 states of the button: normal/focus/down
- IDB_CHECKBOX - bitmap which contains 4 states of the checkbox normal/focus/down/selected
- IDB_RADIO - bitmap which contains 4 states of the radio: normal/focus/down/selected
- IDB_TIP - bitmap which will be shown in a tip window. RGB (255, 0, 255) is a transparent color
I attached sample bitmaps but radio and checkbox are the same.
How to show an agent?
It's quite easy but there are several important steps:
- First you must initialize the COM library. You can do this by adding the following line somewhere at the
very beginning of the program, for example in the
CoInitialize( NULL );
And of course the uninitialize function. Place it somewhere at the end of the execution.
Create a new variable of type
We need to stop here for a while. There is one thing more if you want to use tip/input balloon. You must create a NotifySink (see next paragraph). Without it the balloon won't move correctly.
Now we only need to initialize MsAgent. The code below shows how to do this
m_pSink = new CSink();
m_cAgent.Init ( m_pSink );
m_cAgent.LoadCharacter ( "merlin.acs", &m_cAgent.m_lDefaultCharID );
m_cAgent.SetLanguageID ( 0x0409 );
catch (int *pErr)
MessageBox ("Init err");
PostQuitMessage( 0 );
What is and how to write the NotifySink class?
NotifySink is a class which receives events from other classes (in this example from MsAgent). When user click the character we can get click event for example to show a popup menu. It's pretty useful.
If you want to take advantages of that class go through the steps below:
- Derive class from
CAgent::CNotifySink (as in the example).
- Override the function (event) which you want. If you want to get click notification this function will be Click.
NOTE: all the arguments must be like in the base class.
NOTE: You should call functions from the base class if you want your tip/input balloons work correctly.
- After you process the message return
How to make a character?
I was asked how to do my own character. You should download the character editor from microsoft. It's about 1MB. If you make a character by yourself you can send it to me. I'll be very happy.
Required files you can download from:
- MsAgent core this file installs the main library but You also must download at least 1 character (or make it by yourself, see paragraph above)
For more information visit
MsAgent Homepage or
MsAgent ring, from which you may download free characters. Some of them are quite good.
- 25 August 2002
Now the wrapper works fine with VC++ 7.0.
- 12 March 2002
The wrapper class is completely new. I wrote it once again. Now you can load many characters at the same time. The basics of speech support are now present.
- 18 December 2001
First article improvement.
- 5 December 2001
The wrapper class was created. It contained the main functionality, Balloon (responsible for balloon options), NotifySink
Here I'll describe only the main functions because the rest are very simple.
This is a main class. It contains the main functionality. Some of the functions from this class should be placed in a catch-try block, otherwise if the error occurred the program will crash.
void Init ( CNotifySink* pNotifySink = NULL);
throw ( int );
Initializes the MsAgent.
pNotifySink - pointer to the NotifySink
void LoadCharacter ( CString strChar, long *pCharID );
throw ( int );
Loads a character
strChar - a file with a character. Usually characters are located in [c:\windows]\msagnet\chars. One .acs file in this folder is a character.
pCharID - loaded character ID. You must use it when you call other functions. You can stroe it in m_lDefaultCharID member and instead of passing the ID to functions you pass -1.
void Play ( BSTR bstrAnimation, long lCharID = -1 );
void Play ( CString strAnimation, long lCharID = -1 );
throw ( int );
Plays an animation
strAnimation, bstrAnimation - an animation name. You can get them using function
pCharID - character ID. -1 if you want to use the ID stored in
void SetLanguageID ( long lLangID, long lCharID = -1);
throw ( int );
Sets language ID
lLangID - language ID // NOTE: all ID are enumed at the beginning of the header file
How to configure the input balloon
m_cAgent.GetInputBalloon()->SetUpControls( m_nButtons, m_nRadios, dwFlags );
m_cAgent.GetInputBalloon()->m_strTitle = m_strTitle;
m_cAgent.GetInputBalloon()->m_strText = m_strText;
nReturn - m_cAgent.GetInputBalloon()->Show( m_hWnd, dwFlags );
If you have any questions you can contact with me, send bugs and opinions to GreenSequoia@wp.pl.