Vote for this Product at ClarionShop
 
Buy now at ClarionShop
Version 1.45
© 2003 by CapeSoft Software (Pty) Ltd
www.capesoft.com
Updated 20 October, 2003
c3pa approved
     

Peedy the ParrotRobby the robotMerlin the wizardGenie Wartnose
for more agents see www.msagentring.org
E-Clips Animations



Contents
  General Information  
  Introduction [Suggested Reading]
  Copyright and License
  Distribution [Very Important]
  Where can you get it
  How to get Technical Support
  Acknowledgements
Getting Started - some basics
  Installation Instructions  [Suggested Reading]
  Quick jump start  [Recommended Reading]
Some More Detail
  Using the Agent Templates
  Using the Special Agent DLL windows
  Examples
Features
  Using 3rd Party Agents
  Agent Voice Changing
  Useful General Tips and Info [Recommended Reading]
Support
  Error Messages
  Frequently Asked Questions [Latest FAQs immediately after the FAQ index]
  Technical Documentation
  Microsoft Agent Documentation
  Removing Special Agent from your Program
  Version History [Suggested Reading for existing users]
     


Introduction

Special Agent provides an excellent way of using a Microsoft Agent to learn and play back sequences, which are useful for training and help. This will not only reduce the programmer's training time, but also will reduce technical support and provide all sorts of other features like demos, etc.

Special Agent integrates the Microsoft Agent OCX into your program. You can teach a sequence or series of sequences, which can be played back by the user at relevant points in the program. The Microsoft Agent can be used in these sequences to highlight certain points and explain important details. Special Agent also takes control of your mouse while running sequences to show which buttons must be clicked, fields entered, etc.

Note: Special Agent can only be used in 32-bit applications and in Clarion 5 or later.


Installation Instructions

Installing Special Agent, with ABC support, is a 2 step process:

1. Run the supplied installation program. (You may have already done this, to get this far).
2. The Special Agent template will be automatically loaded when you run the install program.

Note:
There are some example applications which you can find in the clarion5\3rdParty\examples\agent (or c55\3rdParty\examples\agent) directory, which will demonstrate some of the features of Special Agent. The applications with a 'leg' suffix use legacy the legacy templates and those with 'abc' suffix use the ABC class templates. Compile these applications and check out some of the sequences as well.

You will also need to install the OCX components to enable the agents (more info).

Quick jump start

For those of you who hate reading manuals - this section is especially for you. Unfortunately there are always the few things that you absolutely have to know before you get started in order to at least get the ball rolling. This is only for single EXE apps - for multi-DLL applications you'll need to read up a bit more on the Global Extension template.

1. What you need to do to your application

1.1 You need to add the Special Agent Global extension template to your application. To do this:
 
1.1.1 Click the 'Global' button on the Application tree window.
1.1.2 Click on the 'Extensions' button on the 'Global Properties' window.
1.1.3 Click on the 'Insert' button on the 'Extension and Control Templates' window.
1.1.4 Select the 'Activate_Agent' template from the list of extension templates and click on the 'Select' button.
1.1.5 Back at the 'Extension and Control Templates' window the should appear the template with its details on the right.
 
1.2 You'll need to set-up the 'How Do I?' menu on the frame. To do this:
 
1.2.1 Select the frame procedure on which to the menu options will be placed.
1.2.2 Click on the 'Properties' button.
1.2.3 Click on the 'Extensions' button to edit the local extension.
1.2.4 On the Main Details tab, select a menu from the drop down list. This must be a valid menu or the application will not compile. The menu must also have a valid Clarion 'Use variable'. The agent menu 'How Do I?' will be placed onto this menu at run time. (Using the ?Help menu is normally the best)
 
1.3 You'll need to set your application to 32-bit mode. To do this:
 
1.3.1 Click on the 'Project' button on the Application tree window.
1.3.2 Highlight the 'Project: Generator' item in the Project Tree and click on the 'Properties' button.
1.3.3 In the 'Global Options' window that appears, select 'Windows - 32-bit' in the 'Target OS' drop-down list.
1.3.4 Click the 'OK' button (x2) to save the properties.
 
1.4 Now you can compile and run your application.

2. A quick guide in creating sequences

2.1 Once your application is running, press CTRL-F12 to bring up the Sequence Window. The list box should be blank (since you have not created a sequence yet). To create a sequence:
 
2.1.1 Click on the Learn button (book icon) on the Sequence Window
2.1.2 The 'Adding a Sequence Record' window appears with the 'Name' prompt highlighted. Enter a unique sequence name here.
2.1.3 Press the ENTER key or click the 'OK' button.
2.1.4 The 'Learn Sequence' window appears indicating that you are now in learn-mode. Any steps you perform will now be added to the current sequence. It's a good idea to start your sequence with an 'Open Agent' step (click lamp icon button) and finish it with a 'Close Agent' step (click crossed-out lamp icon button).
2.1.5 To quite out of learn mode, click on the 'No-learn' button (crossed-out book icon), which will bring you back to the 'Sequence Window'
 
2.2 To run the sequence that you have just created, click on the 'Run' button (VCR Play icon). Each step that has been learnt while in learn mode will now be performed. If you want to stop the sequence before it is completed, double-click on the agent and select the 'Stop' item from the pop-up menu that appears.

What You Need to Distribute to your Users

As the Microsoft Agent is a Microsoft product, you will have to acquire the necessary free distribution license from Microsoft in order to distribute the Microsoft Agent with your program. You can get the all the Agent documents, programs, etc from the Microsoft website: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msagent/intro_9ywk.asp and the license details are also there: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msagent/lic_7h66.asp

You may, however, use the Microsoft Agent distributed with Special Agent for your own personal use as this is licensed.

When you distribute your Special Agent enabled application, if it's compiled in 'stand-alone' mode (i.e. it requires the use of  DLLs) then you will need to ship the following DLLs with your application:

DLLs required

 
Clarion Version
DLL required  
Clarion 5 C5MSAX.DLL
C5OLEX.DLL
Clarion 5.5 C55MSAX.DLL
C55OLEX.DLL
     

You will also need to distribute all the normal TopSpeed DLLs that you would ship with your standard Clarion application.

TopSpeed DLLs required

 
File Name
Description  
'Agent.tps' file The file containing the sequence information
'Gestures.tps' file The file containing the Agent, Gestures, Languages (optional) and Voices (optional) information.
The Agent OCX files  These are the install-sets for the Microsoft Agents. This includes the Agent OCX (MsAgent.exe), at least one speech-engine (like tv_enua.exe) and at least one character (<Character>.exe). If you require voice changing, then you need to install the Microsoft Speech Control Panel (spchcpl.exe) on each PC where voice changing is required.
     

Important Note: Don't create a sub-directory called 'Agent.tps' (or whatever you've named your sequences file) in the directory from which you run your program as this will split up your Agent.tps file into 5 files. The same goes for 'Gestures.tps' (or whatever you've named your gestures file).

Template Guide

Note: There is no support (at present) for report and process templates, so the Special Agent code will be omitted from these template types.

Important Note: When quitting from a window you must use the ProcedureReturn or the ThisWindow.Kill procedure so that the necessary settings of Special Agent are updated.


The Agent Global Extension Template
The Agent Local Extension Template
Running a Sequence from a button (Control Template)
Running a Specific Agent Sequence (code template)
Using an Agent to say a brief message (code template)
Changing the Special Agent Language (code template)
Get the available agents (code template)
Get the Agent Error details (code template)
Disable Special Agent form the entire application at runtime
The 'Setup Agent's popup menu' code template

1. The Agent Global Extension:

 The first step (once your application is open) is to add the Global Extension. To do this:

1.1 Click the 'Global' button on the Application tree window.
1.2 Click on the 'Extensions' button on the 'Global Properties' window.
1.3 Click on the 'Insert' button on the 'Extension and Control Templates' window.
1.4 Select the 'Activate_Agent' template from the list of extension templates and click on the 'Select' button.
1.5 Back at the 'Extension and Control Templates' window there should appear the template with its details on the right.
1.6 Check the 'No Agent' check box if you don’t want to generate any Special Agent code. This is useful if your app doesn't compile and you want to exclude all agent source when compiling.
1.7 The 'This is part of a Multi-DLL App' check box is used to indicate that the Agent data is exported from another DLL.
1.8 The 'Export Agent defined in this DLL' check box (which is hidden unless the application is a DLL) should be checked if the Agent data must be exported to other applications.
1.9 If this is an EXE change to the 'File Details' tab (EXE Only), or else continue with step 1.21.
1.10 The default file name for the sequence file is 'Agent.tps'. You can change this by entering another file (and a path if you require a set path) or a variable (by omitting the quotes) into the field provided. If the file name field is left blank, the file name will automatically default to 'Agent.tps'.
1.11 Check the 'Use this file for the Character Gestures' if you want to store the characters and their gesture sets in this file. (see What Files to Use for some suggestions on file usage)
1.12 If you left the 'Use this file for the Character Gestures' unchecked then you may enter a file name and path here (don't use quotes if you want to enter a variable name). If left blank, then a "Gestures.tps" file will be used to store the characters and their gesture sets.
1.13 If you are wanting to omit learning some events (like size/move) you can enter a file setting for this file in the 'File to store excluded events'. This file is only used for learning purposes, and will not prevent events from being sent that are already in the sequence. This is purely a time saver to prevent general unwanted events from being entered into the sequence. You may want to make one Excluded events file for all your Special Agent programs and keep this in one place, or you may decide to use one for this application. (see 'Excluded Events' in the 'Setup' on excluding events)
1.14 Change to the 'Translation' tab. (EXE Only)
1.15 Check the 'Use Special Agent's Translator' checkbox if you require the Special Agent windows and messages to appear in a language other than English. (see Translating the Special Agent DLL for more details on translating)
1.16 The Default language file is the file that the translator is set to use at program start-up. You may change this file using the 'Call_MsALanguage' code template.
1.17 The Position options are used to determine where the translation files are stored. You can either select the EXE directory or specify another directory. If the translation files are not there when the program is run, a new translation file will be made.
1.18  The 'All Messages into Translation File on Start-up' is useful when creating a translation file. If this is checked, then on program start-up, Special Agent will ensure that all the messages it uses are in the translation file. The ones that it does not find are written into the translation file there and then. If this is left unchecked, then it will only check the messages in the translation file as the occur individually.
1.19 The 'Restrict Menus to One Language' is useful if you have a sequence file containing sequences of more than one language. This will restrict the sequences displayed in the 'How Do I?' menu and the sequence popup menus to the setting below. If unchecked, then all the language settings of the sequences in the sequence file will be ignored.
1.20 The 'Selected Language' is the language that you select to limit the sequences to. This language must match a language in the Special Agent language file, otherwise the language setting will be ignored.

Note: If you leave this field empty, the Special Agent will maintain the Sequence Selection Limiter changes in the agent ini file. Update this setting to use the changes made in the Change the Language item from the Sequence window. (see International Support for more details)
1.21 Change to the 'Other' Tab.
1.22 The 'Force IMM attribute on windows' is used to ensure that all windows have the IMM attribute. If a windows does not have the IMM attribute, then the agent.DLL is not updated with the new positions of the window when it is moved/sized. If you require that a window does not have the IMM attribute, check this off and ensure that all your other windows have the IMM attribute checked on. You will need to ensure that when that window's dimensions or position is changed that you use the function ds_SendPosition to inform the agent.DLL of the changes.
1.23 The default Hot key to bring up the Sequence window is 'Ctrl-F12'. If you require a different Hot key, you can select one here. (EXE/Data DLL only)
1.24 The 'Keep Agent open after running sequence' check box will keep the agent open when the sequence is finished running. This is useful if you want the agent continuously open, e.g. running random sequences now and then. (EXE/Data DLL only)
1.25 Check the 'Don't display Agent load errors' check box if you don't want the following Warning messages to be displayed: No Agents found, No Agent OCX loaded and No Gestures.tps file found (see Runtime Warning Messages). (EXE Only)
1.26 The 'Don't display error messages at runtime' checkbox is used to hide all the error messages that are normally displayed at runtime. Instead of displaying the message, the DLL will place the message in an error group and post an EVENT:UserError to the frame of your application. There are two embed points: 'Agent - Error Event Handling' and 'Agent - Error Event Handling (After Generated Code)' at the point of handling this event in your frame procedure. The function 'ds_MsAErrorCheck' will be placed there to retrieve the error parameters (see the Special Agent Technical Manual for more details on this function). If this check-box is left unchecked then these embed points will not appear and the errors (when they occur) will be displayed as messages. (EXE Only)
1.27 In the 'Agent Options' group you can select the default options for the Agent's behaviour. These options are: 'Show the Speech balloon', 'Pace the Balloon text', 'Close the speech balloon' and 'Allow Agent Idling'. These are stored in 'msa.ini' file in your windows directory (by default). These are only the default settings, the user can double click on the agent while a sequence is running and change them if required (if permitted - more details). If you require the settings for all Special Agent applications, then you can leave the 'Apply these settings to this app only.' checkbox blank, or else check it and it will save unique settings for the current application. To override existing settings, check the 'Override existing values' check box. Everytime the program is started, it will override any settings that have been altered by the user or another program (if not program unique).You can enter a filename for the ini settings if you would rather not use the default ini file 'msa.ini'.
1.28 Press the 'OK' button to exit from the 'Extension and Control Templates' window.
1.29 Each of the local procedures will be populated with the extension template that applies to the Special Agent controls

2. The Local Procedure template for Special Agent

The 'Activate Agent functions in a Procedure' template is automatically populated by the global extension template. It does not have any prompts (normally), except the 'Omit the Agent from this procedure' check box, the 'Omit Controls' button and the 'Force This window's IMM attribute ON' checkbox on the 'General' tab (see 2.8 to 2.10).

If the procedure is the frame then the menu options form part of this template and you may need to edit the relevant details.

2.1 Select the frame procedure on which to the menu options will be placed.
2.2 Click on the 'Properties' button.
2.3 Click on the 'Extensions' button to edit the local extension.
2.4 On the Main Details tab, select a menu from the drop down list. This must be a valid menu or the application will not compile. The menu must also have a valid Clarion 'Use variable'. The agent menu 'How Do I?' will be placed onto this menu at run time. (Using the ?Help menu is normally the best)
2.5 The 'Place items directly on this menu' check box (if it is checked), will place all the sequences (that are not sub-sequences (see Changing a Sequence)) as items directly onto this menu, instead of having the 'How Do I?' menu created, with the items on it.
2.6 You can change the name of the 'How do I...' menu if you want to. The field is available to do this if you left the above check box unchecked. You can enter a variable if you would like (this is useful for translation).
2.7 The 'Disable "How Do I?" Menu' can be used if you don't want to use the 'How Do I?' menu. This will exclude all the menu populating code from the frame procedure of your application.
2.8 If you would like to run a sequence when this window is opened, change to the 'Other Details' tab and enter a sequence name (using quotes) or the name of a variable containing the sequence name in the Auto-run field. This means that if your program is a demo, it will start the sequence without the user having to do anything. There is an embed point called 'Agent - Before auto-running a sequence', where you can set the variable (for instance using an ini file) before the auto-run. This can be useful when you only want the sequence to run the first time that a user runs the program. Check out the Example Applications on specific details
2.9 Another available option is to show the current step on the status bar while a sequence is running. On the 'Other Details' tab, enter a number in the 'Display Step' field, which will indicate which status bar field to display the step on. If you don't want the step to be shown, leave this option blank or 0.
2.10 On the 'General' tab are the prompts that appear on all procedure's local agent extension template. You can check the 'Omit the Agent from this Procedure' to prevent Agent code from being generated for this procedure.
2.11 You can prevent controls being included in the sequences by clicking the 'Omitted Controls' button and adding the control to the list that appears. This will ensure that no events associated with that control will be learnt in a sequence.
2.12 The 'Force IMM attribute ON' check box will be enabled if you uncheck the 'Force IMM attribute on all windows' check box in the Agent Global Extension template. If you uncheck this, then the IMM attribute will be turned off for this window. You will need to manually inform the Agent DLL of changes in the window's size and position using the ds_SendPosition() function.
2.13 Press the 'OK' button to exit from the 'Extension and Control Template' window.
2.14 Press the 'OK' button to exit from the 'Procedure Properties' window.

3. The 'Call Agent from a Popup menu' Control Template 

There is a Special Agent control template (a button), which may be used to run a sequence from a popup-menu (instead of from the main 'How Do I?' menu). This button may be populated on any window. To place this button:

3.1 Select a procedure, which requires the control template, and click on the 'Properties' button.
3.2 On the 'Procedure Properties' window, click on the 'Window' button.
3.3 On the 'Window Formatter' window, select the 'Populate' menu from the menu bar, and the 'Control Template' item from the 'Populate' menu.
3.4 Select the 'Agent_CallSequence' template from the 'Select Control Template' window, and click on the 'Select' button. The 'Window Formatter' window regains focus and the cross-and-book cursor appears.
3.5 Place the button in a suitable position by moving the cursor to that position and clicking the left mouse button. A button with the question mark icon on it will appear.
3.6 There are no options to set for this template.

4. The 'Call a Specific Agent Sequence' code template.

There is also a Special Agent code template to call a specific sequence. If you would like to use this (this may be useful if your user tries to do something they're not meant to do) in your code then:

4.1 Find the place in the code (using the embed points) to insert the code template.
4.2 Press the Insert button and from the menu tree in the 'Select Embed Type' window, select the 'Agent_CallASequence' template.
4.3 Enter the name of the sequence to call in the available field (using single quotes or a variable name) and click OK.

5. The 'Agent_JusySay' code template

Special Agent can also appear, say something and disappear. This may be useful to display short help messages or error messages. To make use of this function:

5.1 Find the place in the code (using the embed points) to insert the code template.
5.2 Press the Insert button and from the menu tree in the 'Select Embed Type' window, select the 'Agent_JustSay' template.
5.3 Enter the variable containing the words that the Agent must speak and the variable to contain the returned status (optional). Click on the OK button.

6. The 'Call Special Agent's SetLanguage function' code template.

You can set the Language file used for translating the window and the language to limit the sequences listed in the 'How Do I?' and popup menus using the code template 'Call_MsALanguage'.

6.1 The 'Language File name' prompt is the filename in the Language Path that is used for translating the Special Agent Windows and messages. 
6.2 The 'Select sequences by this language' checkbox will set the Sequence Selection Limiter to the language setting found in the translation file.

7. The 'Agent_GetAvailableAgents' code template.

You can get the available agents or check for one specific agent using the 'Agent_GetAvailableAgents' code template.

7.1 Check the 'Test for 1 Agent' checkbox if you're wanting to check for a specific agent, else leave this unchecked.
7.2 If the 'Test for 1 Agent' checkbox is checked then the 'Check Agent' tab will appear with a prompt to enter the Agent name. This name should match the name in the Special Agent Character's file.
7.3 If the 'Test for 1 Agent' checkbox is unchecked then the 'Get All Agents' tab will appear.
7.3.1 If the 'Select one Agent by popup and return that agent' check box is checked then a popup menu of all the agents that  are in the Characters file will be displayed and the User's choice will be returned. Alternatively the returned string will be a | (vertical bar) delimited list of the agents in the Characters file. 
7.3.2 If the 'Include Agents not loaded' checkbox is checked, then the agents that are in the Characters file, but not loaded will have a '~' preceding them in the return string, or will be disabled in the popup menu (if 7.3.1 is checked.
7.4 The 'Variable for result' field should be a string long enough to contain the returned string. If 7.1 and 7.3.1 are unchecked then your string size should be 1024 to 2048.

8. The 'Check Agent Error Group' code template

This code template calls the ds_MsAErrorCheck function. The fields prompted for are to contain the values returned by this function. The template is simply there to aid you in using this function.

9. The 'Disable Special Agent at runtime' code template

This code template calls the ds_MsAFileNames function with the parameter to clear the file names set. The Gesture and Sequence filenames are cleared, thus disabling Special Agent completely from this application. The template is simply there to aid you in using this function. It also places the necessary checks around the function call.

10. The 'Setup Agent's popup menu' code template

This code template allows you to disable some of the items from the popup menu that appears when you double-click an agent. This template allows you to enable/disable the 'Change voice' item and/or the 'Agent Settings' menu from the Agent's popup menu.

You can see an example of this in the sadabc.app example that ships with Special Agent.


Some more detail on the DLL functionality

Getting around the Sequence Window
Learning a Sequence
Changing a Sequence's Details
Printing a Sequence's Steps
Changing a Single Step's details
Running a Sequence
Stopping a Sequence

1. Getting around the Sequence Window

Press 'Ctrl-F12' (Control and F12) to bring up the sequences window. (If you require a different hotkey, you can change it in the global extension template in your application and re-compile your application. See the Setting up a default Hot Key).

The 'Sequences window' has a menubar, a toolbar and a list box. The list box shows the list of steps in the present sequence (which should be blank as no steps have been learnt). The toolbar is made up of a number of buttons (from left to right):

1.1 The 'Learn' button (with an icon of a book on it) will enter learn mode, where new steps can be added to your sequence.
1.2 The 'Run' button (with a VCR play icon on it) will run the present sequence.
1.3 The 'Step' button (with a VCR last icon on it) will step through the present sequence - one step at a time. It will post the step that is highlighted in the Sequence Window and then highlight the next step.
1.4 The 'Load' button (with a select file icon on it) will bring up the select sequence window, where an existing sequence can be selected, changed or deleted.
1.5 The 'Print' button (with the print icon on it) will print the details and events of the loaded sequence directly from this window.
1.6 The 'New' button (with a clear page icon on it) will clear the present sequence so that a new sequence can be learnt.
1.7 The 'Add Call' button (with an insert or plus sign icon on it) will add a call to another sequence at the present highlighted position in the sequence. The sequence can be selected from the 'Select Sequence' window.
1.8 The 'Edit' button (with a triangle icon on it) will bring up the change step screen, where the relevant fields can be changed. You can also do this by double-clicking the left mouse button on the step in the browse box.
1.9 The 'Delete' button (with a 'minus' sign icon on it) will delete the highlighted step from the sequence.
1.10 The 'Cut', 'Copy' and 'Paste' buttons are not available at present.
1.11 The 'Shift Up' button (with an up triangle icon on it) will shift the highlighted step up in the sequence.
1.12 The 'Shift Down' button (with a down triangle icon on it) will shift the highlighted step down in the sequence.
1.13 The 'Exit' button (with an 'exit' icon on it) will close the sequence window. The save to file routine is initiated when the window is closed.
 
The menu bar contains all the functions of the buttons on the toolbar in menu format. The extra items that are in the menu, but not on the toolbar are:

1.1.1 The 'Previous' menu in the 'Sequences' menu contains a list of a maximum of 6 of the last sequences that have been edited. This allows quick loading of one of those sequences.
1.1.2 The 'Save As..' item in the 'Sequences' menu allows you to save an existing sequence as another sequence.
1.1.3 The 'Renumber' item in the 'Sequences' menu will renumber the current sequence into a more easily readable order (10,20,30,etc) because (when editing sequences) the numbering soon becomes rather shabby.
1.1.4 The 'Properties' item in the 'Sequences' menu allows you to change the properties for the sequence that is loaded (without having to go via the 'Select a Sequence' window).
1.1.5 The 'Maintain' item in the 'Sequences' menu brings you to the sequence browse window which allows you to change and view sequences without affecting the present sequence that is open in the sequence window.
1.1.6 The 'Delete' item in the 'Sequences' menu will delete the present sequence that is open in the sequence window.
1.1.7 The 'Mouse Move' item in the 'Options' menu, which is an on/off toggle and is defaulted to 'On'. This option is used to switch on/off the mouse move function to allow/prevent the mouse from moving while the sequence is being run.
1.1.8 The 'Auto-Load' item on the 'Options' menu is an on/off toggle to set whether you want the sequence that was previously run or edited to load up automatically when you call the Sequence window. This is an ini setting and will be maintained when the application is closed.
1.1.9 The 'Warn On Unknown Gesture' will issue a warning when an unknown gesture is issued to the Agent. This option is stored in an ini file, but is defaulted off. It is only available to the script writer.
1.1.10 The 'Change Language' item on the 'Options' menu will bring up the 'Set Language Window', which will enable you to change the translation file used for translating the windows and the Sequence Selection Limiter (prompted: 'Saved Language'). Press the '...' lookup button next to the 'Saved Language' field in order to select a language from the language file. This will only set the language until the program is closed. When it is restarted, the language will be reset to the default (as set in the global extension template).
1.1.11 The 'Agent' item in the 'View' menu is used to open and close the agent. This is useful if you are learning a sub-sequence and the agent must be open before learning new steps.
1.1.12 The 'Restore Defaults' item in the 'View' menu allows you to restore the default sizing of the columns of the list box.
1.1.13 The 'Agents' item in the 'Setup' menu is used for agent maintenance. You can add agents here and maintain their gesture sets. (see Using 3rd  Party Agents)
1.1.14 The 'Gestures' item in the 'Setup' menu is used to for gesture maintenance. Selecting this item will bring up a browse screen showing all the gestures (the defaults on the one tab and the gesture set for the currently used agent on the other) and their active state (1 = de-activated). To activate an item double click on it and check/uncheck the 'de-activate' checkbox. If a Gesture is de-activated it will not appear in the drop down list in the learn window. If a Gesture has been learnt and is subsequently de-activated it will not affect the previously learnt sequence.

Note: If a Gesture ends in 'ing' (or IDLE level 3) it is a continuous gesture. You will need to learn a 'Stop' gesture in order for any other Agent gestures to be played subsequently.
1.1.15 The 'Voices' item in the 'Setup' menu is used to setup the possible voices that can be used with the agents. (see Setting an Agent's voice)
1.1.16 The 'Languages' item in the 'Setup' menu is used to access the languages that can be used for the various language settings. Selecting this option will bring up the 'Browse the Languages File' where you can view, insert, change and delete records in the  Languages file. Both the Hex ID and the Language fields are critical as settings for the languages are stored by both indices. The Hex ID must be a 4 digit number and be proceeded by a capital 'H'. The standard windows language IDs and descriptions can be found in the Microsoft Agent doc: 'progagentcontrol.doc' (under the #LanguageID section).
1.1.17 The 'Excluded Events' in the 'Setup' menu is used to setup events that should not be recorded into a sequence. You can set an event for a specific control type (like mouseIn on regions) or for all types (move/size) and when this event is trapped, it will not be saved into the sequence. This does not pertain to existing sequences that have these events in already. These events will still be sent when you run those sequences. If this item is disabled, then you have not set a filename for the ExcludedEvents file in the Global Extension Template.
1.1.18 The 'Agent Docs' item in the 'Help' menu is a URL link to this document on the CapeSoft website (by default).
1.1.19 The 'Set to local path' item in the 'Help' menu will allow you to set the URL link for the 'Agent docs' item (above) to a local path if required. To reset the path to the CapeSoft website, click on this item and press the cancel button on the Filedialog window that appears.

You can resize the sequence windows and the column in the list box to suite your needs and taste. When the sequence window is opened it will automatically open in the size in which it was previously closed.

You can see where the Sequence file that you're currently using is stored. On the sequence window below the browse you will see the details of the path and the file name where the sequences are.

Note: The Agent events are not time dependant because of the varying length of the Agent animations, thus the delay field cannot be edited for the Agent events.

2. Learning a Sequence

In the sequence window, click on the 'Learn' button. If there are other steps already in the sequence, the option will be given to start learning at the highlighted position on the list box ('Here'), at the beginning of the sequence ('Beginning') or at the previous step that was posted during a run/step/learn ('Previous'). This will enable steps to be inserted into any point in the sequence. There is also a 'Cancel' button to abort learning. If this is a new sequence then the Update Sequence window will appearing requiring some information before you begin learning (see Changing a Sequence).

Tip When inserting steps into an existing sequence, ensure that the necessary windows have been opened before learning (i.e. you must be at the same place in the program when you start learning as the previous step in the sequence).
Note You can resize the Learn Sequence window to suite your needs. You may find that the window is too small to contain all the text that you want the agent to say.
Note When inserting steps, highlight the next step when pressing the learn button and the steps will be inserted above the highlighted step (unless the last step is highlighted then the steps will be added to the end of the sequence).

The 'Learn Sequence' window will appear, which contains a drop list box, a number of buttons and an entry field.

2.1 The Drop list box contains a list of all the possible agent gestures. Once you have selected a gesture for the Agent, press the enter key.

Note: If a Gesture ends in 'ing' (or IDLE level 3) it is a continuous gesture. You will need to learn a 'Stop' gesture in order for any other Agent gestures to be played subsequently. You may learn program events while the Agent is in continuous gesture mode though.
2.2 The entry field is used to type words that the agent will say. (Note: the agent must be opened before gesturing or speaking). After entering the words for the genie to speak, press the enter-key.

Note: There are some characters which will cause the Microsoft Agent to ignore a 'Say' command (`<>{}[]&*%^$#@ and characters with ASCII values > 128). These should not be used in this field. The double quotes " are reserved for tags only. Using double quotes incorrectly will abort the 'Say' command. See Useful Agent Speech Tips for more details on speech tags.
Hint: You can use punctuation to vary the agents voice.


2.1.1 The 'Agent' button (with an icon of a lamp on it) is used to open and close the agent.
When you open the agent for the first time in a new sequence, a pop-up menu will appear. This menu shows the available agents allowing you to select an agent for this sequence. If you select an agent that is not loaded, then the first available agent will be used instead.
2.1.2 The 'NoRecord' button (with an icon of a cassette crossed out on it) is used to play the next gesture without recording it in the sequence. This is useful if you're not completely familiar with all the agent gestures and are unsure of which gesture you would like to insert in the sequence. You can try out a gesture before recording it. This button will only apply to gestures, all other events will be recorded in the sequence, whether this button is pressed or not.
2.1.3 The 'NoLearn' button (with the icon of the book crossed out on it) is used to stop learning mode and return to the sequences window.

While this window is open, all the relevant steps that are posted will be added to the sequence in order. Menu-items can be clicked, and fields entered, etc, etc and it will be saved to the sequence. You perform manually what your sequence will do at run time, and Special Agent will record what you do. When the sequence is run, then Special Agent will play back the events that it recorded to your program.

Note: Special Agent does not directly record menus being dropped down (as this is handled by windows) you need to click on an item in the menu in order for the menu to appear when the sequence is run.

NB: Do not learn a step in your sequence that requires an interface with a system message as this will hang your application. Do not learn a step which will run a sequence or issue a command to use the code template 'Agent_JustSay'.

3. Changing a Sequence's details

In the 'Sequences Window', click on the 'Properties' item in the 'Sequences' menu. The 'Changing a Sequence' window will allow you to:

3.1 Change the sequence name (that appears on the 'How Do I?' menu),
3.2 Change the sub-sequence status (if this is checked, the sequence will be omitted from the How Do I Menu and Sequence Popup Menus).
3.3 A drop list will allow you to change the Agent that should be used in the sequence (if you would like another Agent other than the one that you learnt the sequence with).
3.4 The Time Limit Option allows you to set a maximum time between steps. You may find that most of the time between steps is too high. You can set a sequence maximum, and then override this default on the individual steps that require a longer delay.
3.5 Change the description (the message that is displayed on the status bar when the sequence item on the 'How Do I?' menu is highlighted), on the "Details" tab.
3.6 The 'Start in' procedure (on the "Details" tab) is the starting point of the sequence. In the case of a frame with a splash screen, the starting point of the sequence is often taken from the  splash screen and not the frame. You edit the name of the procedure so that it appears in the 'How do I?' menu if this is the case.
3.7 The 'Application' field  (on the "Details" tab) allows you to edit the sequence's parent application. This is useful if you have a multi-DLL application and you require that the sequence starts in one of the DLLs.
3.8 The 'Override Voice' field will allow you to override the default voice that the agent uses. This can be left 0 in order to use the default voice. If you would like to change the voice for the specific agent globally, then change the voice for that agent rather than changing it every time you use it and leave this field 0.
3.9 Use the 'Language Field' to set the language of a sequence. This is not necessary if the sequence file contains sequences in only one language. However if you ship the same sequence file with your application to countries with different languages then use this option so that only those sequences pertaining to the language (as setup in the translation file) will be displayed in the 'How Do I?' menu. Otherwise leave the field 0.

In this screen you can also delete sequences and fix old sequence files. The 'Fix App & Proc fields to lower case' button will check each record in the Sequence file for application and procedure names that have upper case letters in them and change them to lower case. From Version 1.20, Special Agent converts the application and procedure names that it receives to lower case.

4. Printing a Sequence's Steps

In the 'Sequences Window', click on the 'Load' button. A list of sequences (that have previously been learnt) will appear on the 'Select Sequences' window. To print the Sequence's steps, highlight the sequence and click on the button with the printer icon on it.

5. Changing a Single Step's details

In the 'Sequences Window', select the step that you want to make changes to. Click on the 'Change' button (the one with the triangle on it). The 'Make Changes to an Event' window will appear allowing you to change the following:

5.1 The comment - describes the step
5.2 The time - (hidden for Agent steps and steps that use the default timer as the maximum) sets the delay before the next step. To unhide this field click on the 'Ignore Default Timer' check box.
5.3 The value field - is used for text entry, tab selection, Agent speech text, etc. If you've made a spelling mistake in your Agent speech (for example) you can edit it in this field.
5.4 The 'No Mouse Move' check box - gives you the option not to move the mouse for this specific step. This is only applicable for events that use this function (like selecting fields, pressing buttons, changing tabs, etc.)
5.5 The 'Agent Position Co-ordinates' - are used if the step is an 'Agent Move' step. You may edit the co-ordinates that the Microsoft Agent moves to. These co-ordinate fields are otherwise hidden.
5.6 The 'Ignore Default Timer' checkbox allows you to override the sequence time limit for this specific step. This is not applicable for agent steps.
5.7 The 'Item Control' check box is used for sequences that were learnt before Version 1.16. This changes the event that is saved from an EVENT:Accepted to an EVENT:UserItem, which enables the menu drop down. If this is left unchecked, the browse (for example) that the item selects will just appear, without the menus dropping down and the required item highlighted.

Changing a step's details will cause the step counter to reset, so when the next step command is issued, it will step through the sequence from the beginning.

6. Running a Sequence

A sequence can be run in 3 different ways:

1. The sequence can be run from the 'Sequence Window' by loading the sequence and clicking on the 'Run' button.
2. Select the 'How Do I?' menu and then select the sequence to run from this menu.

Note: This will only apply to sequences that start in the window where the menu appears and that are not sub-sequences.
3. Press the 'Call Sequence' button (the Agent's control template), if it has been populated, and select the sequence from the list that appears.

Note: This will only apply to sequences that start in the window where the control appears and that are not sub-sequences.

7. Stopping a Sequence

To stop the sequence at any point, double click on the agent
. The sequence will pause and a popup menu appears allowing you the option to continue or stop the sequence. If the sequence is being run from the sequence window, the sequence window will reappear and the next step will be highlighted in the list box. To continue the sequence after pausing it, you can double-click on the Agent again and select the continue option from the popup menu. The Agent will complete the step that he is currently busy with before pausing or stopping.

Note:  Special Agent does not support Dragging and dropping as yet, and does not support VBX, OCX, OLE or EIP controls. All other controls are supported and most functionality has been catered for.


Example Applications

There are a few example applications which will aid you in the use of some of the Special Agent features. You fill find these in the Clarion\3rdParty\Examples\Agent directory. All the example applications are in their respective sub-directories, although they use the common data in the data directory.

1. There are two example applications in the SADemo directory: one using abc templates (SADabc.app) and one using legacy templates (SADleg.app). These applications illustrate:
 
1.1 Auto-running sequences (i.e. running an introductory sequence at program start-up) and ways of disabling the auto-run at run-time.
1.2 Using sub-sequences effectively.
1.3 Using the Special Agent Control template to run sequences from a popup menu.
1.4 Ways of demonstrating the different characters that are loaded.
1.5 Handling the Special Agent run-time errors in the EXE.
1.6 Completely disabling Special Agent at runtime (you need to run the example program more than once to try this feature).
 
2.  There is one example application in the SAMulti-DLL directory made up of 4 applications (SAMLE.app, SAML1.app, SAML2.app and SAML3.app), which use the legacy templates. These applications illustrate the use of Special Agent in a multi-DLL application. This application does not include the full functionality that the SADemo does. You must compile the applications in the following order:

SAML1.app, SAML2.app, SAML3.app and then SAMLE.app

You can run the exe SAMLE.exe once you have done the complete compile.
 
3.  There is one example application in the SATranslation directory, which uses abc templates. This application illustrates:

3.1 The translation of the Special Agent windows into another language. (Checkout the Portugue.irf file in a text editor to see how it's done)
3.2 The use of the Sequence Selection Limiter

 

Using Third Party Agents

They're Here!!

Now you can pick from a wide range of characters to use as your demonstrator. From the disgusting Wartnose to the pristine James the Butler you can select a character that will suite your needs and your clients. From version 1.25 onwards you can use a 3rd party agent or agents other than Genie, Robby, Peedy or Merlin. A good website to start looking for other agents is the www.msagentring.org website. You will find a host of free agents that you can download directly or go to the sites of their creators to buy some of their agents that are for sale.

Once you've downloaded an agent, run the exe from the download, making it available for use. You will still need to run msagent.exe and tv_enua.exe in order to install the Microsoft Agent OCX and the text to speech engine.

Using Third Party Agents in your Program
Gesture set Troubleshooting
What files to use
Exporting & Importing gesture sets

Using them in your Program

Run your program (with the Special Agent template added) and bring up the sequence window (press the Sequence Window Hot key). In the sequence window you will find an "Agents" item in the "View" menu. Selecting this will bring up the Agents Browse screen and you will see all the agents that are installed and that you have added manually (including the one that you have just installed). Highlight the agent you have just installed and click on the "Change" button. Do not change the Character name as this is the name that the OCX uses to identify the character. If you would like to use the default gesture set then do not enter any gestures in here. Many of the characters use gestures apart from or far fewer than the default gesture set so it is useful to enter an independent gesture set for each character. As many gestures that you enter and do not make "InActive" are the ones that will appear in the Gestures drop down box as you are learning a sequence (see Learning a Sequence).

You will find a "Gestures.tps" file in the clarion\3rdparty\examples\agent directory which has a complete gesture set for all of the free characters downloadable from www.msagentring.org 

Gesture set Troubleshooting

It's useful to run the sequences with the "Warn On Unknown Gesture" check on after entering a new gesture set as this will indicate any invalid gestures as they are being played. You can then immediately be notified of the invalid gesture and edit the gesture set. Normally (with the "Warn On Unknown Gesture" unchecked) if an invalid gesture is issued to the Agent, it will just skip over the gesture and continue with the next.

What files to use

It's normally best to use a single central "Gesture.tps" file from where you can access the characters and their gesture sets. This means that you don't have to export and import the character sets to each of your "Agent.tps" files that your different programs use. You will, however, need to ship the "Gesture.tps" file with your exe to ensure that the correct character is used for the sequences that you have learnt. If you would prefer to ship just the one file you can incorporate the characters and their gesture sets into the "Agent.tps" files. (How do I set this up in my program?)

Exporting and Importing gesture sets

There are "Export" to text and "Import" from text functions available in the "Browse Characters" window. This is useful if you are maintaining more than 1 gesture set. In the sequence window (How do I get there?), select the "Agents" item from the "View" menu. The "Browse Characters" window will appear. Select the Character which you wish to export and click the export button. Enter a file name in the filedialog box provided and click "Export". If you would like to import a loaded character's gesture set, then you will need to first delete the character (you cannot have two gesture sets for the same character) before importing from the text file. 


Agent Voice Changing

Note:  You must install the Microsoft Agent Speech Control Panel (spchcpl.exe) in order to be able to change the agent's voices. You will need to install this on every PC where voice changing is required.

Before you can manipulate the agent's voices you will need to set up a voice file.

1. Setting up a voice file

To do this you go to the sequences window (How do I get there?) and click on the 'Voices' item in the 'Setup' menu.

A Browse screen will appear showing you all the voices (if any) that you have inserted. This does not mean that these are necessarily all the voices that are loaded, but merely the ones that have previously been inserted into the Special Agent's voices file.
Click the 'Insert' button to add a new voice.

The 'Adding a Voices Record' window will appear allowing you to add the details of the voice. The name of the voice is the field that will be used to select and change voices.

1. The 'Voice Code' is the unique ID which Special Agent uses to identify the voice. This is auto-numbered.
2. The 'Manufacturer' is the creator of the Speech engine ('e.g. Lernout & Hauspie')
3. The 'Name' is the description for the voice that will appear in the popup menu if the user wants to change the voice for an agent.
4. The Gender indicates whether the voice is a male or female voice.
5. The 'TTSModeID' must be accurate. This is the manufacturer's unique identifier to activate this voice.
6. The 'Language' is the language setting for the voice. Although this is not presently necessary, it will be supported in future versions of Special Agent.

2. Changing the Agent's voice

The Agent's voice can be changed in the following ways (in priority order):

2.1 At runtime, while a sequence is running, you can double-click the agent and select a voice from the popup menu. This list is obtained from the Voices file in the Sequence window. This voice will then be fixed for that agent in an ini file, so that whenever that agent is used (in a Special Agent application) on the selected voice will be used. There is a default voice option, which will eliminate the voice being changed from the ini file when the agent is run.
2.2 The voice can be set for this specific sequence, so that you can override the default voice for the agent in this sequence. This is useful if you have one sequence file with sequences in different languages in it.
2.3 The default voice for an agent can be set in the Characters file, so that if an agent has an irritating voice, or an uncharacteristic voice, you can change it so that when that agent is used it defaults to a different voice to the manufacturer's default.

Important Note:
Not all the speech engines support the speech tags used in the standard Lernout & Hauspie speech engines.


Useful Tips and Info

Stopping or pausing the sequence
Turning Mouse Moving off for running sequences
Turning Mouse Moving off during testing
Timer details
Sub-sequences explained
Calling sequences and the 'How do I' menu
Drop-Lists and Drop combos - some hints
Starting the Agent in a different position
Setting the Agents' options

1. To stop or pause the sequence while it's running see Stopping the Sequence.
2. If you don't want the mouse to move for a specific step (like a hidden region) you can check the 'No Mouse Move' checkbox, which will prevent any mouse movements during this specific step.
3. Note: The Mouse Move item in the Sequence window is only used to prevent the mouse from moving during testing. It isn't saved and once you close the window, this setting will be lost. The mouse will only move if (when you're learning the sequence) you actually click on the control. If you use the hot key, or the tab to get to the control, the mouse won't move when you're running the sequence.
4. The Timer is measured in hh:mm:ss and can be set for any steps, except the Agent steps. This will set the delay period after the step is processed, before the next step is issued. The Agent steps are dependant on events passed to the DLL from the Agent OCX, as the gestures, speaking, opening and closing, all have different time periods, thus the timer is ignored for these steps (you will see that it appears as 00:00:00) when the step is learnt. If you want to change the time for a step you can use the Edit In Place function to shorten or lengthen the delay. The individual times can be overridden by the Time Limit option in the Sequence Details see Changing a Sequence.
5. You can learn a few sequences and string them into one. This is useful if you're wanting to use parts of the sequence elsewhere (like an all demo, and a demo of a browse screen). You can use different agents in sub-sequences, string them together into one, and have a sequence that uses different agents for different tasks. You must close the agent before opening the next one though.
6. All sequences that start on the Frame will appear in the 'How Do I?' menu unless they have the 'Sub-Sequence' option clicked on. Similarly if you have used the 'Agent_CallSequence' control template on your screen and you don't want a sequence to be activated from that button, check the 'Sub-Sequence' option on. Thus the 'Sub-Sequence' option will make your sequence hidden from the end user. To do this, go to Changing a Sequence.
7. If you want a Drop List/combo to stay dropped while selecting a record (while playing a sequence back), check the NoMouseMove option ON on the Dropdown and NewSelection steps to that Drop List/combo.
8. If you would like the Agent to appear somewhere other than the top left corner of the screen, then when you learn a "StartAgent" command (i.e. click the "Open the Agent" button on the Learn window) immediately move the character to the place where you require it to open. When you run the sequence, the character will be opened in the position you required.
9. The user can set some specific options for the Agent on their PC if they would like to. If you're running a sequence, you can double-click on the agent for the Agent's pop-up menu, there is a sub menu item called 'Agent Settings' (which can be disabled if preferred - thus preventing the user from altering this). In this sub-menu are 5 options:
1. 'Show Speech Text Immediately' - if you check this option then the agent's speech text will immediately appear in the speech bubble, instead of appearing as it speaks the text.
2. 'Keep Speech Bubble Open' - if you check this option, then the agent's speech bubble will remain open after it has finished speaking. The speech bubble will close if you move the agent, click on it, or close it. 
3. 'Show Speech Balloon' - if you check this option, the agent's speech balloon will be displayed with a speech command. If not, then only the audio is heard with no balloon being displayed.
4. 'Show Property Sheet' - opens the property sheet, which allows you to set some of the agent's properties.



 5. 'Allow Agent Idling' - allows the agent to perform idle gestures when no command is issued to it. 



Useful Agent Speech Tags


Mapping Balloon (displayed) Text to spoken text
Emphasizing specific words while speaking
Changing the speed that the agent speaks the words
Changing the character of the voice (whisper, etc.)

1. Balloon Text and Spoken Text

There is often the problem that Special Agent will pronounce things incorrectly. This leaves you with the choice of compromise in the Agent's voice or the display of the sentence in the balloon using strange spelling. This is solved by the \Map tag in the actual sentence spoken. The syntax is

'\Map="SpokenTextString"="BalloonTextString"\

where SpokenTextString is a valid Visual Basic string for the phonetics of the voice, while BalloonTextString is a valid Visual Basic string for the text displayed in the balloon.

Example

One of CapeSoft's products is Makeover and it users a program called "Styler" to enable you to edit the styles of your screens. Special Agent pronounces "Styler" as "Stealer", which is noticeably incorrect. To pronounce this string correctly and have the correct text displayed in the balloon, the Clarion string that should be used for the Agent speak command is as follows: (Note the two double quotes preceding and following each string.)

'You can use the program \Map=""stiler""=""Styler""\ to edit your screen'.

2. Emphasizing words

You can use the \Emp\ tag to emphasize a word in a sentence.

Example

In the following example the words "Special" and "Agent" will be emphasized.

'\Emp\Special \Emp\Agent is simply the best help tool there is around.'

3. Changing voice speed

If you are finding that there is a specific use for increasing or decreasing the speed of the sentence, you can specify the speed at which the words are spoken by using the \Spd tag in the sentence. Speed is indicated in words spoken per minute. The slowest speed is 50, while the maximum speed is 249 (the normal default speed is 150).

Example

In the following example the words "Special Agent" will be spoken slowly.

'\Spd=70\Special Agent \Spd=140\is simply the best help tool there is around.'

4. Changing voice character

If you would like to change the character of the way that Special Agent speaks, you can use the \Chr tag. You can make Special Agent whisper, speak in monotone or speak normally (You mean you thought Genie normally spoke in monotone? <gr>).

Example

In the following example the words "Special Agent" will be whispered (Note the two double quotes preceding and following the string description).

'\Chr=""Whisper""\Special Agent \Chr=""Normal""\is simply the best help tool there is around.'

International Language Support

There are a number of aspects involved in supporting languages other than English.

1. The Special Agent DLL windows need to be translated so that the sequence writer can understand the different prompts.
2. The Special Agent DLL messages need to be translated so that both the sequence writer and the end user can understand the respective messages.
3. The Agents need to be able to talk in the new language (i.e. pronounce the words correctly).
4. The end user must only be able to play the sequences that are in their respective language.

1. Translating the Special Agent DLL Windows and Messages

1.1 You will need to set a translation path and a translation file in your EXE. You can do this in the global extension (in your EXE if this is a multi-DLL project).
1.2 If you are supporting multiple languages then you can change the language at run-time using the 'Call_MsALanguage' template in your code. You should have one translation file for each language that your program will use. You can change the language file from the Sequence Window at runtime using the 'Change Language' item.
1.3 When you run your program, the translation file will be created (if it is non-existent) as an ini-type file. There will be a section (e.g. [Main]) for each window with an equate for each of the translatable properties of each control. Thus a button may have 3 properties: one for the text on the button, one for the tip and one for the statusbar message. If the translation engine does not find an entry for a translatable text, then it will create one and put the default English text into the equate. 
1.4 Once the entries are placed in the ini file, you will need to edit these with a text editor.

Example:

?Cancel=Cancel

would appear in the text file as the default text for the Cancel button. To change the text to Portuguese edit as follows:

?Cancel=Cancelam
1.5 You will need to open each window at runtime in order to create the necessary translation entries into the translation file. If you check the 'All Messages into Translation File on Start-up' in the global extension template then the messages that Special Agent uses will be written into the translation file when your program is run. This makes translating the messages much easier as you don't have to force the messages to occur in order translate them.

2. Changing the Agents' voices

2.1 You will need to create a voices file.
2.2 You can then Change the Agent's voice to be a voice that is compatible with the language pronunciation.

3. Setting the Sequence Selection Limiter

The Sequence Selection Limiter is a LanguageID that can be set to limit the sequences (that the user has access to) to that Language. You can thus have sequences in different languages in the same sequence file that you can ship with your application. You can then allow the user to select a language and the sequences that can be selected from the 'How Do I?' menu and the popup menus will be restricted to the language that the user selects.

3.1 You will need to set the language setting of the sequence. You can do this in the Sequence Properties.
3.2 There are a number of ways of setting the Special Agent DLL's language setting.
3.2.1 You can set the default language setting in the Global Extension Template. When your program is run, the Special Agent DLL will be set to this language. 
3.2.2 During sequence creation it is useful to be able to change the default language so that when you create a sequence it will be set to that  default language automatically. You can do this in the 'Change Language' item. This will be reset to the default (as set in the Global Extension Template) when the program is closed. Thus you can set the Saved Language to French, learn all the French sequences, and then continue to Spanish, etc.
3.2.3 You can use a code template to change the language setting in the Special Agent DLL. For example, you could attach instances of this template to a number of buttons (e.g. 'French','Spanish','English',etc) and when the user clicks that button, the Sequence Selection Limiter will be set to the specified language. 



Runtime Error Messages

Each message can be translated (if required) in the translation file. Thus each error message is numbered for ease of identification. The number appears in brackets in the message heading.

(1) Error: You must first load a valid sequence. The DLL is trying to perform function on a sequence when no sequences are loaded. First load a sequence before proceeding.

(2) Question: Would you like to restore the link to the|capesoft page for the agent help docs? The hyperlink to the Special Agent docs is not traceable as the Agent docs are not where they are expected. If you select 'Yes' then the hyperlink will be replaced by the link to CapeSoft's page instead of trying to find the docs on your local machine.

(3) Note: Feature not yet available. You have attempted to perform a function that is not available in the present version of Special Agent.

(4) Suggestion: Renumber before shifting. A message that is now unused.

(5/7) Note: Error moving step up/down: You are trying to move a step in the sequence up/down in the sequence. This means that the sequence has somehow got corrupted or you trying to move the step up/down when it is at the top/bottom of the sequence. Quit the program (you may also have to restart Windows) and restart the program again.

(6) Error: Error getting step from the queue. An error occurred while trying to access the sequence items files and so the step could not be obtained. This could mean that the file is corrupt or that the file is in read only mode.

(8) Error: Error getting from the stack or Error obtaining previous pop-point: <error>: The sequence has one (or more) calls in it (i.e. it calls other sequences from it). When it returns from the call, it cannot locate the previous sequence to return to. This is a stack error so there may be a memory-handling problem. Returned errorcode is <errorcode()>* (where errorcode() is the error that occurred while trying to access the record from the stack).

(9) Error: Error getting next Sequence: <error>: The sequence has one (or more) calls in it (i.e. it calls other sequences from it). It cannot load the sequence that is called. This usually means that the AGENT.TPS file is corrupt or that the path is changed during runtime. Returned errorcode is <errorcode()>* (where errorcode() is the error that occurred while trying to access the record from the file).

(11) Note: You must save the sequence name first|before learning steps in the sequence. The 'Cancel' button was pressed when learning a new sequence when the sequence details are required.

(12) Note: Renumber a success. Renumbering of the sequence is completed abnd was successful.

(13) Special Agent Warning: Gesture not known for this agent: <Gesture>. A gesture was issued to the current agent that it does not recognize.

(14) Error: Error getting thread for <Procedure>: This sequence was started in the incorrect procedure, the procedure wasn't opened, or the procedure was closed prematurely. This is usually a learn sequence error. Learn the necessary steps to get to where you want to start (e.g. open the Microsoft Agent before you issue commands to it). Returned errorcode 152*.

(18) Delete Sequence: There is a sequence that has no steps in it.|Would you like to delete it? <Seq:Name>. A 'Yes/No' option that allows you to remove a sequence that has been created without any steps in it.

(19) Error: You must enter a valid filename|[errorcode()] [error()]|[clip(TEX:Text)]. You are attempting to export/import to/from an invalid/non-existant text file. Re-enter a correct text file and proceed.

(20) Error during import loop: This file is not included in the routine:|[clip(TEX:Text)]|Abort loop?. While importing from a text file, the import routine came upon an illegal import command/structure in the file and is not sure what to do with it. You may abort if this is not a valid import text file.

(21) Warning: You will need to import the Sub-Sequence:|<Sub-Sequence name>|so that this sequence can run correctly. You are importing a sequence that has a call to a non-existant sub-sequence. You must import the sub-sequence as well in order for the sequence to run correctly.

(22) Warning: Cannot find the required/selected voice. You are trying to use a voice that is not existant in the voices file any more (e.g. the voices file has been deleted or a sequence has been imported and the voice that the sequence requires is not in the voices file.

(23) Warning: Cannot find the required/selected language. The Agent is attempting to set the language, but cannot find the specified language in the language file. The cause of this problem could be a mis-placed language file (gestures.tps), an incorrect language specification (i.e. the language is named 'English' instead of 'English (USA)') or an outdated/new language file (gestures.tps) which does not contain the language specified.

(24) Warning: Cannot Find this Sequence. You've got a call in your routine to run a sequence that has been deleted or renamed. This is either handcoded in or using the Code Template 'Call a Specific Agent Sequence'. Check for the line in your source ds_AgentInterface(parameters).

(25) Error: Error accessing the [clip(SequenceFN)]|[errorcode()] [error()]. An error occured while trying to read a record from the Sequence file. The error is displayed in the Message Box.

(26) Error: Error adding Sequence step.|[errorcode()] [error()]. An error occurred while trying to save an event in the sequence. The file and error are displayed in the message box.

(27) Error: Cannot save records to the Position file in:|[clip(SeqPosFN)]. While attempting to add co-ordinates to the position file (a window re-size or move event), there was a file error.

(28) Error: Error converting old file structure to new file structure. The sequence file structure that you are currently using is the old file structure (pre version 1.16). While attempting to up grade to the new file structure, there was a file error.

(29) Error: Menu item incorrectly mapped. You've handcoded your menu/item mapping and have not ended your map with an E, or there is an E occuring before the end of the string. You may only have one E in the string.

Runtime Warning Messages

(15) Special Agent Warning - The Microsoft Agent OCX is not loaded. You will not be able to run any of the help sequences. Run the MsAgent.exe and the tv_enua.exe programs to install the Microsoft Agent OCX.

(16) Special Agent Warning - Cannot find the Agent Gestures file or no Characters found in the Gestures file expected at: <FilePath>. There are <NumberOfAgents> Agents installed. Would you like to create a new gestures file?(This may use different Agents in previously learnt sequences). If the Yes button is pressed, then all the agents installed will be added to the Gestures file, but they will have no gesture sets, so you will only be able to learn gestures from the default gesture set for each character until you create the respective gesture set. However, existing sequences will be played as they were created (with the correct gestures), except the Agent used in the running of the sequence may be different to that with which the sequence was originally learnt. If the No button is pressed, then a blank gesture file is created with no characters/ gestures. When a sequence is run 'Genie' (or a random other character if Genie is not installed) will be used in the sequence.

(17) Special Agent Warning - You do not have any Microsoft Agents installed. You will not be able to run any of the help sequences without installing a Microsoft Agent. Contact Your supplier for details. You must run at least one of the <agent>.exe character install programs so that your sequences will run.

Note: If you have the ' Don't display error messages at runtime' checkbox in the global extension template checked you can use these error codes together with the ds_MsAErrorCheck() function to handle the errors. The returned errorcode appears in the second field of the group returned in ds_MsAErrorCheck(). Check out the example application 'msaabc.app' for examples on Agent Error handling.

Error Messages (Compiler)

File not found: <path>\you_need_to_change_your_app_to_32-bit.lib: This occurs when the project has been set to 16 bit instead of 32 bit. You'll need to edit the project properties and change it to a 32 bit project.

DS_AgentControlQ is unresolved in file c:\clarion5\obj\<filename>001.obj: You could have misplaced the c5(5)msax.lib file or the c5(5)msaxl.lib file and so the project can't find the definitions for the Special Agent functions.

If you have not selected a menu item for the 'How do I' menu, three compile errors will be generated. If you edit these errors, the errors will explain how to rectify this problem.

If you have not assigned a variable to a check box, an error will be generated. Editing this error will provide the instruction as to rectify the problem.


Frequently Asked Questions

Audio Issues
1.1 I cannot get the Agent to speak. The speech text appears in the bubble, but there is no audio.
1.2 I don't want my users to be able to change some of the agents settings (like voice, speech, bubbles, etc). How do I do this?
1.3 I don't want the speech bubble to appear, how do I do this?
Translation Issues
2.1 If I'm going to use (for eg.) Spanish, must I use the Call_MsALanguage function? If so How.
2.2 Where in the template must I establish that I'm going to use (for eg.) Spanish as a language?
2.3 I am translating and using a number of agents, but one agent (eg Merlin) always speaks in Spanish
Timer Issues
3.1 I have long delays in my sequence
3.2 What is the difference with the default timer on/off?
3.3 What are the timing units, hours, mins, secs?
Position Issues
4.1 How do I position the mouse?
4.2 When I learn an 'AgentMove' step I often get the position wrong.
4.3 How do I open the Agent in a position other than the top left hand corner?
4.4 I tried to issue ds_SendPosition right after positioning the window, but to no avail.
Startup and Setup Issues
5.1 Can I get SA to start working via a BUTTON on the MAIN procedure without having SA ?attached? to a menu item? If so how?
5.2 If I have a terminal client session open with the terminal server and I run my application in that session it does not see MsAgent.
5.3 Will you be able to run Special Agent if you distribute the agents.tps and gestures.tps to the client's machine and then run the agent on the local machine?
5.4 Not all my sequences appear in the 'How do I?' menu. Is there a limit to the amount of sequences that appear in the 'How do I? menu?
5.5 None of my sequences appear on the 'How Do I?' menu
5.6 How should one use sub-sequences?
5.7 When I press CTRL-F12 the sequence window does not appear
5.8 I've already used Ctrl-F12, what must I do now?
5.9 When I run my application there is no 'How Do I?' menu.
5.10 I can't put Special Agent on the Help Menu. 
Sequence Running/Learning Issues
6.1 My Sequence often GPFs my program and comes up with PUSHScope/POPScope errors, as well as 801 Bind errors.
6.2 If the Agent does one of the gestures ending in 'ing' it does not do any other gestures, but continues doing that one. How do I get it to stop?
6.3 I would like to know when my sequence has finished running. What is the best way to find out?
6.4 My sequences hang when I open one of my windows. The sequence stops and the agent 'falls asleep'.
6.5 My menus don't always drop down in the sequence that I've learnt
6.6 Sometimes my text does not input
6.7 When I run my sequence, I get an error message "Error getting thread for The Agent".
6.8 I would like to run a sequence automatically when my program starts, how can I do this?
6.9 The Agent does not always select the correct item in the menu during sequence play-back
6.10 I am having problems with figuring out how to "Learn" opening menus, selecting tabs etc.
6.11 I have a sequence of ds_AgentDoGesture() and ds_ImmediateAgent() commands together. Some of the ds_AgentDoGesture() commands are not being done.
Registration Issues
7.1 I bought Special Agent for Clarion 5 but I now need the version for Clarion 5.5 (or later). How much does it cost...
7.2 So how do I register?



1.1 I cannot get the Agent to speak. The speech text appears in the bubble, but there is no audio.

Step 1: You may not have a text-to-speech engine loaded (like tv_enua.exe). Load the engine and try running your sequence again.

Step 2: If you are running windows XP then you need to install the SAPI 4.0 Runtime (spchapi.exe freely downloadable from Microsoft http://activex.microsoft.com/activex/controls/sapi/spchapi.exe ).

Step 3: If you've tried steps 1 and 2 then you may have set an invalid voice for that agent then you may have a situation such as this. The agent's voice is set in 1 of 3 ways. Clear all 3 ways and then re-attempt the sequence. If you require a specific voice, then ensure that the TTSModeID for that voice is correct and that the voice is in fact loaded.

Step 4: If you've tried steps 1 and 2 then you have probably changed voices without installing the Microsoft Speech Control Panel (spchcpl.exe). Run the installer to enable the voice changing.

1.2 I don't want my users to be able to change some of the agents settings (like voice, speech, bubbles, etc). How do I do this?

Answer: You can insert a call to the ds_DisablePopupOptions function somewhere in your program by using the code template: 'Setup Agent's popup menu'  or using the function directly and setting which item must be disabled in the popup menu.

1.3 I don't want the speech bubble to appear, how do I do this?

Answer: There are 3 ways of doing this (depending on the application).

1. To do this by default you can clear the 'Show Speech Balloon' check box that occurs in the Global Extension template
2. To do this at runtime you can double click on the Agent (while running a sequence) and select the 'Show Speech Balloon' item on the 'Agent Settings' menu that appears. 
3. To do this manually in your program, you can use the function ds_SetAgentOptions() to force the balloon off.

2.1 If I'm only going to use (for eg.) Spanish, must I use the Call_MsALanguage function? If so How.

Answer: Call_MsALanguage is only for applications that support multiple languages. For example if you ship your program in Spanish, French, Portuguese and English, then you could prompt the user on startup for a language of their choice and then set the Special Agent's language to that language using the Call_MsALanguage function. You could then set your default language in the global extension to the preferred one. But in the case of using only one language, none of this is necessary. See the SATabc.app example in the clarion\3rdparty\examples\agent\SATranslation directory for a practical guide to use this function.

2.2 Where in the template must I establish that I'm going to use (for eg.) Spanish as a language?

Answer: If you're only going to use Spanish then that makes things a bit easier. You don't need to worry about setting the language if you're only going to use one language. You can set the translation file (in the global extension template) so that the messages and Special Agent windows will be translated. You'll need to translate and ship the translation file though. There is an example of a translation file in the clarion\3rdparty\examples\agent\data.

2.3 I am translating and using a number of agents, but one agent (eg Merlin) always speaks in Spanish, no matter what I set the language in the sequence to. How do I get him to speak in English again?

Answer: Take another look at the Changing the Agent's voice. It sounds like you have set the agent's voice using the 'Change Voice' option in the double-click on the agent (No 1 priority in Changing the Agent's voice). If you have set a voice for an agent, this voice is stored in an ini file, so whenever you use that agent on your machine, it will speak in the voice that you've specified. If you select the 'Use Default' then this deletes the setting from the ini file, and the next time the agent is used, it will use the next priority voice. If you want to get back to the original voice, you need to remove all 3 possibilities that could be changing the voice.

3.1 I have long delays in my sequence. How do I edit the time?

Answer: (see Changing a Step). Alternatively you can edit the field directly in the sequence list box on the 'Sequence Window'. See Useful Tips for more info on the timer.


3.2 What is the difference with the default timer on/off?

Answer: The 'Ignore Default Timer' only works for non-agent steps. If you've set a default time limit for the sequence (like 1 second), this will ignore all the times that it's recorded and that are greater than the time limit during the learning cycle (because you generally take more time in the learning cycle than you would like during playback). However, if you want to delay the step after a specific step you can select this option, which will use the time that's recorded for that step ( say 12 seconds). If you haven't set a default time for this sequence then the 'Ignore Default Timer' naturally means nothing.

The handy thing about the Default Timer Limit is that you can set a maximum time without having to go back and change all the times because they're too slow.


3.3 What are the timing units, hours, mins, secs?

Answer: The timer is in hh:mm:ss


4.1 How do I position the mouse?

Answer: If you click on a control (say a button) you should see the mouse move to the location of the button when running the sequence. It only works for certain controls (tabs, lists, combos, fields, buttons, regions, options and check-boxes).


4.2 When I learn an 'AgentMove' step I often get the position wrong. Is there anyway to edit the co-ordinates that he moves to, to get the positioning accurate?

Answer: (see Changing a Step).


4.3 How do I open the Agent in a position other than the top left hand corner?

Answer: (see Setting the Opening Position of the Agent )

4.4 I tried to issue ds_SendPosition right after positioning the window, but to no avail. What am I doing wrong?

Answer: The agent is controlled by an OCX on a hidden window. The problem you may be experiencing is that the Agent window or another window (like the splashscreen) has the focus and not the window that you are calling the function from. Call settarget before doing the ds_SendPosition (and make sure that you're not omitting the parameters when calling ds_SendPosition).

5.1 Can I get SA to start working via a BUTTON on the MAIN procedure without having SA ?attached? to a menu item? If so how?

Answer:
Yes you can.
1. You need to check the 'Disable "How Do I?" Menu' in the Agent local extension template on the frame.
2a. Go into the window editor of the frame and populate the 'Call Agent Browse Sequence' control template onto the toolbar.
OR
2b. Place a button on the toolbar and handcode the necessary calls to the Agent DLL to display the sequences that can be run from the frame.   Both 2a and 2b are demonstrated in the 3rdparty\examples\agent\sademo\sadabc.app example.

5.2 If I have a terminal client session open with the terminal server and I run my application in that session it does not see MsAgent.

Answer: Terminal Server creates a separate 'windows' directory for each client, so the Agent are all loaded in the default root directory, but it is looking for them in the client directory. 

You basically need to copy the c:\WinNT\Msagent directory to the c:\WinNT\profiles\<UserName>\Windows\MsAgent directory. If you are using Windows 2000 the folder is: C:\Documents and Settings\<UserName>\Windows\MSAgent Directory.


5.3 Will you be able to run Special Agent if you distribute the agents.tps and gestures.tps to the client's machine and then run the agent on the local machine?

Answer: In the frame, Special Agent checks if you have a gestures.tps file and if there are any character details in it. If not, it warns you that if cannot find/invalid gestures file. This is because all the agents are stored with a ID code, and your sequence has the agent stored by that ID code. It can then build the gestures file making a database from the character files that it finds in the windows\msagent\chars directory - the problem is that all chars are not necessarily loaded in the same order that was in the initial gestures file, thus sequences learnt with Peedy may be played with Genie, etc. 

If the chars in the gestures file are not found on the client's machine it simply ignores the specified agent and uses the default agent (by default it's Genie - but you can make it anything). If the default agent is not found, it picks the first in the list. If no chars are installed, it will warn you when you first load the program. Special Agent will be disabled if there are no characters found, but your program (with all normal functionality) will continue to run - although you will be unable to run any sequences.

Similarly, if there is no agent object ocx installed, you will be warned on startup and Special Agent will thereafter be disabled. You can disable the warnings (in the Global extension template) if you prefer.

5.4 Not all my sequence appear in the 'How do I?' menu. Is there a limit to the amount of sequences that appear in the 'How do I? menu?

Answer: There is a limit of 100, but what you're probably experiencing is one of two things: 

1. Some of your sequences may have the 'Sub-Sequence' property checked on.  
2. Some of your sequences may be attached to the wrong procedure (like a Splashscreen or hidden window). Ensure that the 'Start In' field is set to the frame. 

5.5 None of my sequences appear on the 'How Do I?' menu.

Answer 1: Check that your sequences do not have the sub-sequence checked on (Changing a Sequence) and that the sequences that you require to start from menu have their first step in the window with the menu on it.

Answer 2: You may have a splash screen, and all the sequences are being started from there. You need to change the start procedure to the frame, you can do this in the (Changing a Sequence) window.

5.6 How should one use sub-sequences?

Answer: There is no real difference between a sub-sequence and a normal sequence apart from the appearance (or lack thereof) on the menu or on the pop-up when the Control Template Button is pressed. You can use sub-sequences and sequences as sub sequences (i.e. as insertions into other sub-sequences or sequences). For example, you could have a Grand Tour sequence which has only four lines, each of which calls another sequence or sub-sequence. You could then call the Grand Tour from a sub-sequence (because you may want to include some Agent activities which you don't want to include in the Grand Tour) so that the user can't run that sub-sequence from the "How Do I?" menu.

5.7 When I press CTRL-F12 the sequence window does not appear?

Answer: Steps to check:

1. Ensure that your application does use CTRL-F12 as the hotkey. 
2. Delete the msa.ini file, which saves the previous position of the Sequence window. The window may have been moved off the screen on a previous occasion.
3. If still no success, continue with the steps in When I run my application there is no 'How Do I?' menu.

5.8 I've already used Ctrl-F12, what must I do now?

Answer: See Details on changing the Sequence Hot Key.

5.9 When I run my application there is no 'How Do I?' menu.

Answer: Steps to check:

1.Check that you have loaded the agent onto the PC where the application is being run from.
2.Check that the 'Place items directly on this menu' check box (How Do I Menu) is unchecked.
3.If you have set your program to use a variable for the Filenames, then you need to set the global variable for the file names before the call to the procedure ds_MsaFileNames - which occurs in the program Setup in your default module. In the global embeds - Program Setup - Priority < 1000.

5.10 I can't put Special Agent on the Help Menu. On the drop down list from which I choose, the Help Menu is not there. Other menus are there, and the Help items are there, but not the help menu.

Answer: You need to add a variable to your HelpMenu. Go into your window, into the menu editor, click on the help menu and enter a Use Variable (like '?HelpMenu').

6.1 My Sequence often GPFs my program and comes up with PUSHScope/POPScope errors, as well as 801 Bind errors.

Answer: Unfortunately there has been some binding problems in Clarion 5.5. It will be fixed in Clarion 6, and is non-existant in Clarion 5. As much of the binding as possible has been removed from Special Agent in version 1.41 to minimalize this effect, but this problem will still occur occasionally.

6.2 If the Agent does one of the gestures ending in 'ing' it does not do any other gestures, but continues doing that one. How do I get it to stop?

If a Gesture ends in 'ing' (or IDLE level 3) it is a continuous gesture. You will need to learn a 'Stop' gesture in order for any other Agent gestures to be played subsequently.



6.3 I would like to know when my sequence has finished running. What is the best way to find out?

Answer: The best way is use the ds_GetRunCheck() function. This will return a 0 when a sequence is not running.



6.4My sequences hang when I open one of my windows. The sequence stops and the agent 'falls asleep'.

Answer: It sounds like you have got a call to open your window in the middle of opening another window. When you open a window, while the window is initializing, the agent is put on standby. 

There's a flag called AgentWait that gets set right at the top of your window. Once the window has finished opening, the flag is cleared, so that the Agent can continue with the sequence. This is to ensure that the procedure is in the 'Accept' loop before events are posted to it. If the procedure is not in the 'Accept' loop then the events that are posted to that procedure during window opening are 'lost'. 

Thus it appears that the flag is being set, and then incremented in the new window's routine (the value is now 2), which is then decremented at the end of the second window's opening procedure (now 1). Special Agent is waiting for the AgentWait to be cleared before it can continue (which will only occur when the second window closes and the 1st window is allowed to continue it's opening routine). There are 3 possible solutions (ranging from best to worst):

1. Move the call to your 2nd window to the very first command in your ThisWindow.Init routine (i.e. before the ds_AgentWait() call).

2. Move the call to your 2nd window to after the opening is finished. In fact the call to clear the AgentWait flag is only in the event:OpenWindow. You will find a call to a routine called 'MsAAgentWaitSet'. You need to call your window after this call. For example:

of EVENT:OpenWindow
  do MsAAgentWaitSet
  SecondWindow


3. Place a call to clear and set the AgentWait flag before and after the call to your second window.

ds_AgentWait(-1,,,1)
SecondWindow
ds_AgentWait(1,,,1)


6.5 My menus don't always drop down in the sequence that I've learnt. What am I doing wrong?

Answer: Unfortunately Special Agent does not record menus dropping down (this is all handled by windows), it can only record the event that occurs when an item is accepted. During sequence playback, Special Agent presses a sequence of keys to drop down the menus and get to the item that was selected. You need to select an item in order for the menu to be displayed.



6.6 Sometimes my text does not input, is their something that I can do to change this?

Answer: You need to ensure that the EVENT:Accepted for the text that you've entered into a field is immediately preceded by a EVENT:Selected for that field. This means that you need to select that field and then type the changes to that field before you do anything else (like making the Agent gesture or speak).



6.7 When I run my sequence, I get an error message "Error getting thread for The Agent".

Answer: Check that your sequence opens The Microsoft Agent before issuing any commands to it, or check that the sequence calling the sub-sequence opens it. (See Errors)


6.8 I would like to run a sequence automatically when my program starts, how can I do this?

Answer: See Auto Running. Check out the example application (SADabc.app) that comes with the agent. I'll explain what I do in this example:

1. The Agent Extension Template on the frame contains the auto-run info ('Other Details' tab). I've put a variable in this field (AutoRunName).
2. I set the variable in the ThisWindow.Init method just before opening the window (on the frame). It reads from an ini file to determine whether the sequence must be run or not.
3. In the 'AboutDemoWindow' procedure, there's a check box that allows you to disable the auto-run sequence. I set the ini file in the ThisWindow.Kill method dependant on the state of the Run Sequence At Startup 

Compile it and run this example to see the effect


6.9 The Agent does not always select the correct item in the menu and so I get sub-sequent errors because the window is not open.

Answer: You'll find that you have hidden, created or destroyed controls in your code, thus the menu mapping is incorrect for controls below or to the right of those that have been hidden, created or destroyed. There are 4 possible solutions (ranging from best to worst case) depending which will suite you the best.

1. Disable/enable controls rather than destroying/creating/hiding/unhiding controls.
2. Move the menus and items that are destroyed/created/hidden/unhidden to the right or below menus and items used in sequences.
3. Hand code the call to the menu mapping routine for each of the controls occurring to the right of the hidden menus like this:

Agent - Before EVENT:UserItem event handling

if ~MenuHidden

Agent - After EVENT:UserItem event handling

else
0{prop:active} = 1
if MenuHidden = 1
ds_ReceiveItemMap(MsAHotKey & 'RRRRDDE') !This is the key sequence to get to the item
                                                                       !through it's parents
elsif MenuHidden = 2
ds_ReceiveItemMap(MsAHotKey & 'RRRDDE') !This is the key sequence to get to the item through it's parents
end
end


You can check the technical manual for more details on the ds_ReceiveItemMap, but briefly - an R means a RightKey stroke and a D means a DownKey stroke. Obviously the map for each item will be different. You must only have one E at the end of the map (for Enter). Create a variable called MenuHidden (for e.g.) and each time you destroy or hide a control, increment the variable. The easiest way to work out what the map is, is to run the program and press the actual keys to get to the menu item. Special Agent always presses the ESCKey after the MsAHotKey so as not to drop down the menus that are not needed. If you hide or destroy the route menu (i.e. the left most menu) you will need to reset the MsAHotKey.

4. On each item event that is learnt in a sequence, uncheck the "Item Event" check box. This will ignore item mapping (so you won't have the drop down menu effect). This will handle items like the way Special Agent used to do it before Version 1.16.


6.10 I am having problems with figuring out how to "Learn" opening menus, selecting tabs etc.

Answer: When you're in 'Learn' mode, the events that are generated in your program will be recorded and stored as a sequence. In other words you get into learn mode (CTRL-F12 and click the Learn button - the 'Learn Sequence' window should appear), and then you open the browses as normal, click buttons, enter text into fields, etc and whatever you do will be recorded. Click the 'NoLearn' button (crossed-out book) on the 'Learn Sequence' window to get out of LearnMode. When you run the sequence, it will be played back in the sequence that the events were recorded.

6.11 I have a sequence of ds_AgentDoGesture() and ds_ImmediateAgent() commands in sequence. Some of the ds_AgentDoGesture() commands are not being done, and the agent picture isn't refreshed (i.e. it leaves a picture trail). What am I doing wrong?

Answer: What's happening is that the ds_AgentDoGesture is skipped if the agent is busy (see Tech. Docs for more info). You need to put the ds_AgentDoGesture() command in a loop and then refresh the window once the ds_AgentDoGesture() command is completed. For example:

DS_IMMEDIATEAGENT('MERLIN','Hi')
loop until ~band(DS_AGENTDOGESTURE('Alert'),1h) ; yield() .
DS_IMMEDIATEAGENT('MERLIN','Hi')
loop until ~band(DS_AGENTDOGESTURE('Announce'),1h) ; yield() .
ThisWindow.Reset(1)                                                                        !do refreshwindow  for legacy  This does away with the agent gesture trail
DS_IMMEDIATEAGENT('MERLIN','Hi')
loop until ~band(DS_AGENTDOGESTURE('Blink'),1h) ; yield() .
ThisWindow.Reset(1)
DS_IMMEDIATEAGENT('MERLIN','Hi')
loop until ~band(DS_AGENTDOGESTURE('Confused'),1h) ; yield() .




7.1 I bought Special Agent some time ago - for Clarion 5 - but I now need the version for Clarion 5.5 (or later). How much does it cost, and where can I get it?

Answer: Updates are free, and can be downloaded from the web site - www.capesoft.com - the password is issued to you when you register.


7.2 So how do I register?

Answer: Send us your contact details, via email (sales@capesoft.com) or via fax (+27 21 715 2535). Include the dealer you bought it from and the order number.




Technical Documentation

The technical documentation for Special Agent is available in a separate document entitled Technical Documentation.


Removing Special Agent from your application

You will need to delete the Special Agent global template from your application. You must then exit the application and re-enter again. You may need to compile a few times, because each time the compiler gets to a procedure that has used an Agent code template it generates an error before removing the code template.

It is important to note that when you remove Special Agent from your application, all your settings may be lost. A more advisable option is to check the 'No Agent' check box in the global template, which will not generate any Agent code into the application when it is compiled.


Copyright and License

This product, and all the files contained therein, is copyrighted © 2003 by CapeSoft Software (Pty) Ltd. You are licensed to distribute any of the DLL's contained in this package with your applications. You are not allowed to copy any of the other files, including but not limited to, Template (TPL) files, Library (LIB) files, Resource (RSC) files and documentation files.

CapeSoft Software (Pty) Ltd, employees of CapeSoft Software (Pty) Ltd, and Dealers of CapeSoft Software (Pty) Ltd products, explicitly accept no liability for any loss or damages which occur from using this package. Use of this package constitutes agreement with this license. This package is used entirely at your own risk.

Acknowledgements

Thanks to all supporters and critics of Special Agent for the e-mails. Your suggestions and recommendations have been extremely valuable to the shaping and growth of this product.

A special thanks to James Fortune and John Maguire for all your helpful input.

Where can you get it?

The full working version of Special Agent is available at $199 from:

CapeSoft Sales
  Web www.capesoft.com  
Email sales@capesoft.com
Telephone +27 21 715 4000
Fax +27 21 715 2535
Post PO Box 511, Plumstead, 7801, South Africa
     


Buy Online
  Web
Buy now at ClarionShop
www.clarionshop.com 
 
 
 
 
 
     


CapeSoft Support
  Email
support@capesoft.com
 
Telephone +27 21 715 4000
Fax +27 21 715 2535
Post PO Box 511, Plumstead, 7801, South Africa
     


Version History

Version History for Version 1.45 - Released 24 October 2003 Version History for Version 1.44 - Released 18 September 2003 Version History for Version 1.43 - Released 3 April 2003 Version History for Version 1.42 - Released 4 October 2002 Version History for Version 1.41 - Released 11 June 2002 Version History for Version 1.40 - Released 17 May 2002 Version History for Version 1.39 - Released 25 April 2002 Version History for Version 1.38 - Released 5 March 2002 Version History for Version 1.37 - Released 23 January 2002 Version History for Version 1.36 - Released 08 October 2001 Version History for Version 1.35 - Released 10 August 2001 Version History for Version 1.32 - Released 9 May 2001 Version History for Version 1.31 - Released 23 February 2001 Version History for Version 1.30 - Released 18 January 2001 Version History for Version 1.29 - Released 14 Decemeber 2000 Version History for Version 1.28 - Released 15 November 2000 Version History for Version 1.27 - Released November 1, 2000 Version History for Version 1.26 - Released September 15, 2000 Version History for Version 1.25 - Released August 9, 2000 Version History for Version 1.24 - Released July 31, 2000 Version History for Version 1.23 - Released June 2, 2000 Version History for Version 1.22 - Released May 17, 2000 Version History for Version 1.21 - Released March 16, 2000 Version History for Version 1.20 - Released February 22, 2000 Version History for Version 1.19 - Released November 8, 1999 Version History for Version 1.18 (Template change only) - Released August 17, 1999 Version History for Version 1.17 - Released August 5, 1999 Version History for Version 1.16 - Released July 15, 1999 Version History for Version 1.15 - Released July 1, 1999 Version History for Version 1.14 - Released June 8, 1999 Version History for Version 1.13 - Released June 4, 1999 Version History for Version 1.12 - Released June 3, 1999 Version History for Version 1.11 - Released May 27, 1999 Version History for Version 1.1 - Released May 20, 1999 Version History for Version 1.07 - Released May 14, 1999 Version History for Version 1.06 - Released April 15, 1999 Version History for Version 1.05 - Released April 14, 1999 Version History for Version 1.04 - Released April 14, 1999 Version History for Version 1.03 - Released April 12, 1999 Version History for Version 1.02 - Released March 16, 1999 Version History for Version 1.01 - Released March 5, 1999 Version 1.00 - Released February 26, 1999

[End of document]