Click here to Skip to main content
Click here to Skip to main content

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.

Introduction

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
    try
    {
        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.78MB Genie 1.55MB Peedy 3.24MB Robby 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.

History

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

CAgent

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
nReturn:
    - -1 - cancelled    
    - IDC_CHECKBOX - checbox
    - between IDC_BUTTONS and IDC_RADIOS - button
    - greater then IDC_RADIOS - radio
    For a sample code see demo project
*/

Contact

If you have any questions you can contact with me, send bugs and opinions to GreenSequoia@wp.pl.

License

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

Share

About the Author

Michael Mac
Architect macmichal.pl
Poland Poland
Micheal is an independent consultant - www.macmichal.pl.
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 (blog.macmichal.pl) and speaker.
 
In his spare time, he's climbing the mountains all over the Europe.

Comments and Discussions

 
Questionm_pSink variable [modified] PinmemberMember 97180438-Feb-13 1:35 
Generalquite nice work!! thx for sharing Pinmemberbuaa_dep61-Jun-10 22:55 
Generalthanks and How Pinmemberbahgat youw12-Mar-09 4:06 
Generalmsagent in multithreaded apllication Pinmemberharishdobhal19-Aug-08 22:36 
Questionvb.net PinmemberCorne.duplooy14-Jul-08 4:34 
Generalvery good,I like it Pinmemberhaoshenghan24-Apr-04 4:26 
GeneralAny VB Codes for MSAgent Forms PinmemberPravinu18-Jun-03 2:09 
GeneralRe: Any VB Codes for MSAgent Forms Pinmemberzero_code20-Jun-03 21:47 
GeneralMessage Box for MsAgent PinmemberRupaliSood22-Apr-03 17:02 
GeneralHelp me Please !! Urgent PinsussBadrus ZAman8-Mar-03 20:57 
GeneralAssert failure, any clue Pinmemberbrutus_alexus12-Jan-03 9:18 
Generalwhy build error in vc++6 Pinsussleonwang23-Dec-02 22:31 
GeneralRe: why build error in vc++6 PinmemberMichael Mac3-Jan-03 7:59 
Generali have a problem PinsussAnonymous12-Dec-02 9:23 
GeneralAnother problem here Pinmembershin j s31-Oct-02 19:36 
GeneralRe: Another problem here PinmemberMichael Mac2-Nov-02 6:52 
Generalmain dlg loses focus after agent moveto or setposition Pinsussshin j s29-Oct-02 21:06 
GeneralRe: main dlg loses focus after agent moveto or setposition PinmemberMichael Mac30-Oct-02 3:09 
GeneralRe: main dlg loses focus after agent moveto or setposition Pinsussshin j,s30-Oct-02 15:33 
GeneralRe: main dlg loses focus after agent moveto or setposition PinmemberMichael Mac2-Nov-02 6:44 
Generalsome twinckle when input balloon close... Pinsussshin joon seob28-Oct-02 21:33 
GeneralScroll lock button Pinmemberhappys24-Jul-02 3:27 
GeneralRe: Scroll lock button PinmemberMuammar©10-May-07 21:30 
GeneralMsAgent Voice Recognition Pinmemberhappys23-Jul-02 6:43 
GeneralRe: MsAgent Voice Recognition PinmemberMichael Mac23-Jul-02 8:04 

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

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

| Advertise | Privacy | Mobile
Web01 | 2.8.141022.2 | Last Updated 25 Aug 2002
Article Copyright 2001 by Michael Mac
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid