Click here to Skip to main content
13,898,644 members
Click here to Skip to main content
Add your own
alternative version


53 bookmarked
Posted 10 Dec 2001

Wrapper class for MsAgent characters

, 24 Aug 2002
Rate this:
Please Sign up or sign in to vote.
An article providing an easy way to use msagent characters
<!-- Article image -->

Sample Image - screen.jpg

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

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 CWinApp::InitInstance
  • CoInitialize( NULL );
  • And of course the uninitialize function. Place it somewhere at the end of the execution.
    CoUninitialize ();
  • Create a new variable of type CAgent
  • 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();      // Create NotifySink
        m_cAgent.Init ( m_pSink );  // Init MsAgent
        // Load Merlin
        m_cAgent.LoadCharacter ( "merlin.acs", &m_cAgent.m_lDefaultCharID );    
        m_cAgent.SetLanguageID ( 0x0409 );    // Set language ID
        m_cAgent.Show ();           // Show MsAgent
    catch (int *pErr)
        // An error
        MessageBox ("Init err");
        PostQuitMessage( 0 );
        delete pErr;

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 NOERROR value;

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)
  • Characters:
    Wizard 1.78MBGenie 1.55MBPeedy 3.24MBRobby 2.12MB
    see example 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

Quick References

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 GetAnimationNames
pCharID - character ID. -1 if you want to use the ID stored in m_lDefaultCharID.

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 );
/* dwFlags:
    - BI_CHECKBOX        - check box visible
    - BI_CHECKBOXSEL    - checkbox selected
    - BI_TEXTBOX        - textbox visible
    - BI_SINGLELINE        - textbox singleline
m_cAgent.GetInputBalloon()->m_strTitle = m_strTitle;    // Set title text
m_cAgent.GetInputBalloon()->m_strText = m_strText;        // Set text
m_cAgent.GetInputBalloon()->SetPosition(  );            // Calc contols position
nReturn - m_cAgent.GetInputBalloon()->Show( m_hWnd, dwFlags );    // Show
/* dwFlags:
    - BI_RADIORETURN    - return after radio click
    - BI_CHECKRETURN    - return after checkbox click
    - -1 - cancelled    
    - IDC_CHECKBOX - checbox
    - between IDC_BUTTONS and IDC_RADIOS - button
    - greater then IDC_RADIOS - radio
    For a sample code see demo project


If you have any questions you can contact with me, send bugs and opinions to


This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here


About the Author

Michael Mac
Poland Poland
Micheal is an independent consultant -
He's main areas of interest are: DDD\CqRS, TDD, SaaS, Design Patterns, Architecture. He specializes in .Net/C# for the early beginning of it and T-SQL. He's a writer, blogger ( and speaker.

In his spare time, he's climbing the mountains all over the Europe.

You may also be interested in...

Comments and Discussions

Questionm_pSink variable Pin
Member 97180438-Feb-13 1:35
memberMember 97180438-Feb-13 1:35 
Generalquite nice work!! thx for sharing Pin
buaa_dep61-Jun-10 22:55
memberbuaa_dep61-Jun-10 22:55 
Generalthanks and How Pin
bahgat youw12-Mar-09 4:06
memberbahgat youw12-Mar-09 4:06 
Generalmsagent in multithreaded apllication Pin
harishdobhal19-Aug-08 22:36
memberharishdobhal19-Aug-08 22:36 Pin
Corne.duplooy14-Jul-08 4:34
memberCorne.duplooy14-Jul-08 4:34 
Generalvery good,I like it Pin
Ventruing24-Apr-04 4:26
memberVentruing24-Apr-04 4:26 
GeneralAny VB Codes for MSAgent Forms Pin
Pravinu18-Jun-03 2:09
memberPravinu18-Jun-03 2:09 
GeneralRe: Any VB Codes for MSAgent Forms Pin
Haitham Khedre20-Jun-03 21:47
memberHaitham Khedre20-Jun-03 21:47 
GeneralMessage Box for MsAgent Pin
RupaliSood22-Apr-03 17:02
memberRupaliSood22-Apr-03 17:02 
GeneralHelp me Please !! Urgent Pin
bzaman8-Mar-03 20:57
memberbzaman8-Mar-03 20:57 
GeneralAssert failure, any clue Pin
brutus_alexus12-Jan-03 9:18
memberbrutus_alexus12-Jan-03 9:18 
Generalwhy build error in vc++6 Pin
leonwang23-Dec-02 22:31
memberleonwang23-Dec-02 22:31 
GeneralRe: why build error in vc++6 Pin
Michael Mac3-Jan-03 7:59
memberMichael Mac3-Jan-03 7:59 
Generali have a problem Pin
Anonymous12-Dec-02 9:23
memberAnonymous12-Dec-02 9:23 
GeneralAnother problem here Pin
31-Oct-02 19:36
suss31-Oct-02 19:36 
GeneralRe: Another problem here Pin
Michael Mac2-Nov-02 6:52
memberMichael Mac2-Nov-02 6:52 
Generalmain dlg loses focus after agent moveto or setposition Pin
shinbatd29-Oct-02 21:06
membershinbatd29-Oct-02 21:06 
GeneralRe: main dlg loses focus after agent moveto or setposition Pin
Michael Mac30-Oct-02 3:09
memberMichael Mac30-Oct-02 3:09 
GeneralRe: main dlg loses focus after agent moveto or setposition Pin
shinbatd30-Oct-02 15:33
membershinbatd30-Oct-02 15:33 
GeneralRe: main dlg loses focus after agent moveto or setposition Pin
Michael Mac2-Nov-02 6:44
memberMichael Mac2-Nov-02 6:44 
Generalsome twinckle when input balloon close... Pin
shinbatd28-Oct-02 21:33
membershinbatd28-Oct-02 21:33 
GeneralScroll lock button Pin
happys24-Jul-02 3:27
memberhappys24-Jul-02 3:27 
GeneralRe: Scroll lock button Pin
Muammar©10-May-07 21:30
member Muammar©10-May-07 21:30 
GeneralMsAgent Voice Recognition Pin
happys23-Jul-02 6:43
memberhappys23-Jul-02 6:43 
GeneralRe: MsAgent Voice Recognition Pin
Michael Mac23-Jul-02 8:04
memberMichael Mac23-Jul-02 8:04 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

Permalink | Advertise | Privacy | Cookies | Terms of Use | Mobile
Web05 | 2.8.190306.1 | Last Updated 25 Aug 2002
Article Copyright 2001 by Michael Mac
Everything else Copyright © CodeProject, 1999-2019
Layout: fixed | fluid