Wrapper class for MsAgent characters

• Download source files - 60 Kb
• Download demo project - 152 Kb

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

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