The SECAgentCharacterExPtr class derives from the IAgentCharacterExPtr smart pointer, which is created by running #import on the AgentSvr.exe containing the Agent components’ type library. This is done within the Objective Toolkit headers, and the user does not have to worry about #importing the type-library manually. However, be sure to add a path to AgentSvr.exe in the Visual Studio Libraries variable to compile the Objective Toolkit libraries properly.

You can create an SECAgentCharacterExPtr object by calling IAgentApp::CreateChar(), or initialize it just as you would an IAgentCharacterExPtr smart pointer.This class creates and registers a default notification sink for the underlying character.

This class creates a command, "Change Default Character", which can be enabled programmatically. Using this command, users can change the underlying character at any time. When users invoke this command, it brings up a dialog with a combo-box allowing the user to chose a character out of the available characters in the system, previewing the chosen character.

The class provides APIs that instruct the underlying character to prompt at a Window or Rectangle. It has a MessageBox API with which you can display a message box accompanied by the Agent reading out the text from it. It also provides an elaborate framework to enclose character actions within Act objects. Take a look at SECAgentCharAct for more information.

Deriving your CWinApp object from IAgentApp instantly hooks a lot of default Agent functionality into your application. Take a look at the SECAgentApp template for more information. SECAgentApp exposes simple APIs to initialize the AgentServer, creates and maintains a default agent character (an SECAgentCharacterExPtr object), provides agent support in Dynamic Data Validation (DDV) of forms and dialogs in the application, provides support for Tip of the Day and more.

You need not necessarily derive your CWinApp class from IAgentApp. You could create an instance of IAgentApp anywhere in your application. If you do this, part of the DDV support implemented in the SECAgentApp template will have to be reproduced for proper agent-enabled DDV functionality. Also, you need not have an IAgentApp interface in your application to work with SECAgentCharacterExPtr.

Derive your application class from SECAgentApp, passing in CWinApp as the template variable. This will provide agent-enabled Dynamic Data Validation in your forms and dialogs, besides providing the other features implemented in IAgentApp.

SECAgentCharAct is an abstract base class from which all Act objects are derived. This class provides the basic implementation for the Act object. You can create custom Acts by deriving from this abstract class.

An important drawback of the Microsoft Agent architecture is that the function calls that initiate an animation are asynchronous, hence there is no easy way of knowing which animation is currently being played. Furthermore, the programmers have to deal with low-level animations rather than high-level Acts (sequence of animations).

The Objective Toolkit framework, allows an animation sequence on a Character (an Act) within an SECAgentCharAct object to be represented by an ActID. Acts are categorized as Critical or NonCritical. Using the ActID, the corresponding Act can be interrupted any time. Also, the framework provides high priority to the Critical Acts by interrupting any current/pending NonCritical Acts.

The classification of Acts into Critical/NonCritical, together with the ability to interrupt the current Acts, provides a powerful way of handling the agent character for demonstrative and instructive purposes.

For example, if the character is in the middle of providing a tooltip hint and the user triggers Dynamic Data Validation—causing a Message Prompt via the agent, then the agent should immediately abandon the tooltip task and move on to the DDV Prompt message task. This is possible only if the Acts are finely demarcated and prioritized, as in this framework.

A few implementations of SECAgentCharAct that are provided are SECAgentPromptAtWndAct, SECAgentPromptAtRectAct, and SECAgentSpeakAct.

SECAgentNotifySink is the default sink for an SECAgentCharacterExPtr object.

This class listens for RequestComplete(), RequestStart() and Command() notifications.

You can derive from this class and listen for more notifications or modify the default behavior by overriding the corresponding virtuals. You can attach your custom sink object to an SECAgentCharacterExPtr object via its m_pNotifySink member.