• Introduction [Suggested Reading]
• Copyright and License
• Distribution
• Support
• Acknowledgements
• Installation Instructions [Suggested Reading]
• JumpStart [Recommended Reading]
• Using the Agent Templates
• Using the Special Agent DLL windows
• Examples
• Using 3rd Party Agents
• Agent Voice Changing
• Useful General Tips and Info [Recommended Reading]
• Error Messages
• Frequently Asked Questions
• Technical Documentation
• Microsoft Agent Documentation
• Removing Special Agent from your Program
• Version History

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.

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

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

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.

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

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

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.

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.

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.

Download here

 Version History for Version 1.49 - Released 11 November 2008

• Clarion 7 compatible install.

Version History for Version 1.48 - Released 5 September 2007

• Template Change - use template variables to project the DLL used in the project (so projects can be generated in C6 and compiled in C7).

Version History for Version 1.47 - Released 25 July 2007

• Fixed INI use - allows a ini file name longer than 9 chars :)

Version History for Version 1.46 - Released 20 July 2007

• Fixed INI use - INI file was always created in the Windows directory (for ini save/restore window position) - for Vista compliancy. INI file now used is the one stipulated in the Global Extension template.

Version History for Version 1.45 - Released 24 October 2003

• Fixed Template Regression (for C5 and C55) introduced in verrsion 1.44.

Version History for Version 1.44 - Released 18 September 2003

• Clarion6 compatible build - not extensively tested, and there seem to be some delay issues (with thread swapping) so not recommended for shipping with Agent activated. Recommend disabling Special Agent for c6 applications. This should not affect C55 and C5 versions.

Version History for Version 1.43 - Released 3 April 2003

• DLL Fix - Fixed the selector on the Sequence list box.
• Added feature to the ds_StopSequence function. You can stop the sequence immediately (without waiting for the Agent to complete it's task).
• Template Fix - Lib not included in the project if Agent is disabled in this application.

Version History for Version 1.42 - Released 4 October 2002

• DLL Fix - Fixed the resizing of the screen controls in the Learn Sequence window and added a 'Do' and a 'Say' button to aid in agent interface.
• Examples Fix - Updated examples to ship with new graphics.

Version History for Version 1.41 - Released 11 June 2002

• DLL Change - attempt to minimize C5.5 BIND problem by removing as many PUSHBIND/POPBind pairs as possible (RunSequence, ItemHandler, ds_TheAgent, ds_NewAgentThread (if already open))
• DLL Change - Was not deleting controls from the Control Q upon exit from procedures - so duplicates could occur.
• DLL Change - Protection for PosFetch - when obtaining the position of a window - if the event gets 'lost' - reposted (PosFetch contains the thread value of the window required).
• DLL Change - Aborts running the sequence if the event cannot be posted. PostSequenceEvent changed to funciton - returns a 1 if failed.
• DLL Change - API function to bring window to the top when an event is posted to it (if it does not already have the focus). Event used is event:UserPosition.
• TPL Change - Don't show options in DLL templates that pertain to EXEs only.
• Install Fix - included gifs in install set.
• DLL Change - FilePath added to No Agents loaded message to inform users of where the OCX is expecting the Agents (Microsoft Terminal Client support).

Version History for Version 1.40 - Released 17 May 2002

• Install fix - Included icons for the examples in the install set.
• DLL Change - Fixed screen flash for Agent windows when running a sequence.
• DLL Change - stabilised sequences when run on XP (Deleted list on Agent window, protect Timer event in RunSequence window)

Version History for Version 1.39 - Released 25 April 2002

• DLL Change - Fixed bug in ds_ImmediateSay - new agent OCX don't have unique start event.
• DLL & TPL Change - New feature: allows Balloon to be hidden, while just audio occurs.

Version History for Version 1.38 - Released 5 March 2002

• DLL & TPL Change - Allows Idle mode off.
• Tpl Change - Allows the Agent Settings to be defaulted in the Global Template for each application. Done through a new function: ds_SetAgentOptions().Allows settings overriding and specification of the filename.

Version History for Version 1.37 - Released 23 January 2002

• DLL Change & TPL Change - Allows disabling the Agent settings in the agent popup menu. (new function to set variables and code template to call function).
• DLL Change & TPL Change - Allows no learning of user specified/move events. Events to be ignored are stored in a file (setting in the Global Extension Template) and the file is editted from the Sequence Window.
• DLL Change - If gestures file must not be created, give abort option (which deletes the gestures file on the way out).

Version History for Version 1.36 - Released 08 October 2001

• DLL Change - All relevant AgentWait changes made in the ds_AgentWait procedure.
• DLL Change - Win2K does not post all events to the OCX control. Now caters for no Start Event (1).

Version History for Version 1.35 - Released 10 August 2001

• TPL fix - fixed multi-proj support
• DLL change - increased string size (255 to 2048) for popup (Popup that appears on the select sequence template)
• DLL change - allows complete disable of Special Agent (in ds_MsAFileNames function or Code Template).
• DLL Change - Access to the Agent Properties Screen, and more settings (Keep bubble open, Text shown immediately). Right click the agent during run-mode (details).
• DLL Change - Checks in some of the newer functions to return if Special Agent is disabled at runtime, or there are no filenames loaded. Prevents GPFs in some of the functions (that use the agent files) if the filenames aren't specified.

Version History for Version 1.32 - Released 9 May 2001

• Tpl change - Checkbox entry (change() instead of display()) - support for Capesoft MessageBox
• DLL change - ds_GetRunString
• DLL change - ds_SetPosition
• DLL change - ds_AgentWait: increments/decrements AgentWait instead of setting it  - support for Capesoft MessageBox
• TPL change - Global Extension Sheet changed:1. in EXE set error handling (multi-DLL), 2. check for multi-DLL apps changed
• DLL change - ds_AgentDoGesture. Opens agent if not open already. Optional parameter allows you to select the agent to appear
• Tpl change - fix Multi-Proj support
• DLL change - prevent empty say commands
• DLL change - Handle Event:AlertKey properly (especially in relation-Trees)
• Tpl change - support toolbar buttons

Version History for Version 1.31 - Released 23 February 2001

• Doc change - error message documentation updated
• Tpl change - support for multi-proj
• DLL change - prevent 'Hide' popup menu with right click from occuring
• Bug Fix in TPL - supports toolbar buttons (was trying to run a sequence when toolbar button was pressed)
• New Function - ds_GetAgentStatus returns the current agent open, it's busy status and the thread of the window controlling the agent
• New Function - ds_AgentDoGesture does the required gesture if the agent is open (similar to what ds_ImmediateAgent does for speech)
• Tpl change - allows controls to be disabled from recording events to a sequence (existing events in sequences will still be run)
• Changed the way the template inserts the MsATakeEventinto the procedure.

Version History for Version 1.30 - Released 18 January 2001

• Doc and tpl change - Explained Agent_CallASequence template
• Bug fix in tpl - GPFs when closing a multi-DLL legacy App

Version History for Version 1.29 - Released 14 Decemeber 2000

• Bug Fix - occasional GPF in close window
• Bug in C55 - Mouse Move not working, worked around real to short compare.

Version History for Version 1.28 - Released 15 November 2000

• Bug Fix - fixed compile problem in C55 for local-mode compiles.

Version History for Version 1.27 - Released November 1, 2000

• Bug Fix - All Applications check box in the Sequence select window
• Bug Fix - Force Voices/Language selections when invalid to 0 (for old sequences)
• Bug Fix - Default Agent gesture time-out too short so causing problems for long gestures
• TPL Fix - Code TPL for changing the language fixed to include changing the 'How do I?' menu
• Bug Fix - All DLL windows translated (Voices, Languages, etc. were missed out in v1.26)
• Docs revamped and explain example apps
• Added to TPL - can change 'How Do I..' menu name (for translation purposes)

Version History for Version 1.26 - Released September 15, 2000

• New function ds_GetAvailableAgents to check if agent is available, and to select an agent from a popup list. (see the Code Template)
• Bug Fix - ds_ImmediateAgent calls selected Agent (bug introduced in 1.25)
• Translation added. Translate DLL windows and Error messages in an ini-type file. (see International Support).
• Template modified for INTL support. Allows filesetup and %ProgramSetup code in EXE only.
• Prevents Sequence Window, ImmediateAgent and Sequence popup menus from appearing if no agents/no agent OCX loaded.
• Limit sequences to the selected language. (see Sequence Selection Limiter)
• Functionality added to change the agent voice. (see Changing the Agent's voice)
• Correction for names that appear in the 3rd party agent list. Obtains fullname instead of shortname (i.e. DoctorMike instead of Doctor~1)

Version History for Version 1.25 - Released August 9, 2000

• Support for 3rd Party agents. (see Using 3rd Party Agents)
• Bug Fix - GPF fix in learn moves (file handling out of OCXEvent routine to procedure)
• Show agent in a specified position (first move after Show is recorded as the ShowAt position) (see Showing Agent Elsewhere)
• If unknown gesture is issued to Agent, continues with next gesture
• Optionally display error message when unknown gesture is posted (setting on Sequence Window, stored in ini file for Dev use). (see Warn on Unknown Gesture)
• Optional (set in Global Template) Error Messages if no Agents or no Agent OCX loaded. (see Don't display Agent load errors)
• Only issue stop if Agent in continuous gesture, else Stop gesture ignored
• Removed "Remake Gestures" item from the sequence window's "View" menu

Version History for Version 1.24 - Released July 31, 2000

• TPL fix - Export AgentRemainOpen variable for multi-DLL applications
• Updates by popup in the Sequence Window (and hotkeys)
• Learn window is set to resizable so that larger text entry fields can be viewed
• "Ignore Default Timer" check box fixed to hide/unhide Timer field correctly
• Timer EIP removed in the Sequence Window
• Setcursor to wait during agent open in learn mode - helps prevent the GPF when the IMM attribute is on
• Bug Fix - GPF on window/agent moves in IMM windows
• Learns only 1 move when an IMM window is moved
• Template generated Source cleaned up and moved (where possible) to the DLL
• Bug Fix - Check box action (in legacy) works

Version History for Version 1.23 - Released June 2, 2000

• Bug Fix - occasional GPF in move command
• Bug Fix - moves learnt sometimes learns (2;2) co-ordinates
• Bug Fix - in change event window, event co-ordinates when negative are not displayed correctly
• Add auto-IMM attribute check box in global extension template set. Forces IMM attribute on windows if checked, embed added to local extension template for handling sizing/moving windows which cannot have the IMM attribute

Version History for Version 1.22 - Released May 17, 2000

• When learn button pressed on last event, add steps to the bottom of the sequence, instead of inserting
• Added 'Delete' and 'Maintain Sequence' items to the Sequence menu of the Sequence window
• Print button on the SelectSequence window moved off tab to window
• Print button added to the Sequence window
• Item and menu messages and tips corrected
• Call to HTML docs added on the Sequence window
• Added error message to TPL when no variable is used for a check box
• Get correct agent after running a sequence with a sub-sequence call at the end
• Correction in continuous gesture after say command to allow stop gesture
• Updated HTM docs (Acknowledgements, C55)
• Bug Fix - If seq starts with call to sub-sequence, ran from previous sequence
• Bug Fix - Could not add call when no other events existed in the sequence

Version History for Version 1.21 - Released March 16, 2000

• Supports Clarion 5.5
• Text Entry improved - entered from DLL
• Fix for contracted in Relation tree structures

Version History for Version 1.20 - Released February 22, 2000

• Template support for CPCS' Report template
• Eliminate infinite wait after Agent move error
• Default 'Omit the Agent from this procedure' to true for all Report, Process and Source templates. Also disabled for these
• Enable All & Disable All buttons added to the Gesture select screen
• Remove Number from Item Message in the 'How Do I' menu
• Change Agent event after Say to end speaking rather than Balloon Close - makes the sequences flow better
• Index to FAQ and tech docs added
• Template change to compact generated code. EVENT:UserSelect handled outside the case field statement
• Immediate Move option to allow instant change in position for an Agent move
• ds_AgentSetWait variable added to local template so as to monitor the calling of ds_AgentWait - prevents AgentWait from remaining set if the ProcedureReturn is executed before the AgentWait is cleared
• Sequence file is used directly instead of loading the file to a queue and working on the queue. All editing, etc. is done directly on the sequence file. As a result, some functions are slightly slower, but far more robust
• Text entry is made more robust with checks that the window is in focus so that text is entered into the control with focus and not to another window
• Upgraded Docs - FAQ contents table with Hyperlinks, makes using the FAQ easier
• Supports Expanding and contracting of Tree structures in a list box
• Fix for mixed upper and lower case application and procedure names (which can change with a different operating systems)
• New sequences will use lower case only. A procedure is added to convert the old sequences to only use lower case procedure and application names.

Version History for Version 1.19 - Released November 8, 1999

• Fix to prevent no agent EXEs that use agent DLLs from crashing on file open because no file name loaded
• Option to post Agent run-time errors back to the exe so that they can be handled by the exe
• Fix the cancel insert sequence
• Move the Sequence Properties to the Sequence menu in the Sequence window
• Add checkbox in the frame template to disable the 'How Do I?' menu
• Option (in global template) to keep Agent open when sequence finished running
• Gesture file created. In the sequences window there is a menu item 'Gestures' where all the available gestures can be enabled/disabled
• 'Remake Gestures' in the sequences window menu is an item to remake the gestures file to restore the default gestures

Version History for Version 1.18 (Template change only) - Released August 17, 1999

• Move the function ds_MsAFileNames() to the Global template (in the Program Setup).
• Allows the user to set the file name in the Global Extension if the application is a multi-DLL application where the Global Data is defined in another DLL.

http://www.capesoft.com/accessories/drawsp.htm

 

• Hide/unhide Default Timer according to use
• Load default timer after initial learn
• Add Sequence properties item to the menu to view the sequence properties straight from the sequence window
• Fixed Agent moves (was referenced to incorrect window after closed before next event from new window saved)
• Fixed Mouse moves (occasional moves missed)
• Added Cancel button in BeginningorEnd window (used before running/learning a sequence)
• Fixed NewSelection for Option control in Legacy
• Column in Sequence window changed to XDelay (Extra Delay). Normally shows a 0, else if Ignore Default Timer, then shows delay time. Edit-in-place still available
• Auto-set Ignore Default Timer when Delay changed in Sequence Window
• Changed default sequence file name to 'Agent.tps' (NB for users upgrading from version 1.16, but irrelevant for prior users)
• Changed look of the Learn window, no 'Say' and 'Do' buttons. Press the enter key when you require to gesture or say (depending on which field is selected)

Version History for Version 1.16 - Released July 15, 1999

• New Feature: Drop down menus during running sequences. If you would like your previous sequences to drop the menus down then you need to indicate which steps pertain to items (see Control is an Item)
• Event from Agent to post next event changed to 25 (Close Speech bubble event after say) and 11 (after startagent)
• Updated ds_AddEvent to ds_AddEvent1 procedure to optimize generated code
• Added a sequence report to print out a sequence
• Added the REQ attribute to the Agent_JustSay code template's text field
• Stabilised Save routine - escape route from infinite loop (in auto-renumber) and stabilized auto-renumber
• Allowed a change in name for the sequence file (set in the global extension). It is important (for Version 1.16 users) that you either change the file name of your 'Agent.tps' to 'Agent.csa' or enter 'Agent.tps' into the file name field in the global extension (see Sequence File Name)
• Deleted Agent selection from the global extension template

Version History for Version 1.15 - Released July 1, 1999

• Special Agent moves learnt and played back with respect to the current window font and the frame font proportionally
• Speech output tags enabled (see Useful Agent Speech Tips)

Version History for Version 1.14 - Released June 8, 1999

• "Save As" fixed - loads saved sequence instead of the previous sequence
• Displays correct name on the sequence window
• Steps the highlighted step, not the previous step
• Included auto-conversion of the data file changes made in ver 1.13

Version History for Version 1.13 - Released June 4, 1999

• Fixed AutoLoad bug - ini setting is not overwritten
• Fixed Learn Beginning|Previous|End Window and it shows counter not steps
• Procedure name string fixed (two variables in DLL limit it to 40 chars) - now 120 chars max

Version History for Version 1.12 - Released June 3, 1999

• Included menu template into local template (Agent.tpl)
• Added AutoLoad option to Options menu on the Sequences window. Auto-Load is for loading the last sequence that was edited when the Sequence window is run
• Added tab containing all sequences in Agent.tps file to the Select Sequence window
• Fixed drops - undrops the list after new selection is accepted
• Added Start in procedure and application fields on the Update Sequence details window
• Stops all Agent animations when the Agent is double-clicked
• Displays current sequence that is loaded in the title bar of the Sequence window
• Auto-Renumber of a sequence if there is an error saving it

Version History for Version 1.11 - Released May 27, 1999

• Fixed saving of file from auto load-up
• Fixed compile in local mode (template change and include c5olexl.lib into the c5msaxl.prj)
• Fixed export of Hot-key in multi-DLL mode
• Fixed Text box entry
• Added LastEdit file to the dictionary - contains the last edited sequence information instead of in an ini file

Version History for Version 1.1 - Released May 20, 1999

• Fixed BeginningorEnd window from popping up during sequence run
• Drop combos fixed in ABC and legacy
• Fixed timer default (takes individual time unless > default time)
• Fixed double click on sequence window. Only goes to form if List db-clicked
• Added autoblink after say to delay allow the agent to finish saying before next event
• Fixed mouse movements
• Fixed the tab sequence in the "Changing Sequence Details" form
• Fixed the Agent Position hide in the "Changing a step's details" form
• Added ds_ImmediateAgent to replace ds_ImmediateGenie. Will now perform immediate say with agent specified

Version History for Version 1.07 - Released May 14, 1999

• File required Agent.tps (not just Agent) in dictionary
• Default Timer for each sequence, with override available for each event
• Column Resizing saved for sequence window
• Restore defaults column sizes menu item added
• Changed window after learning new sequence to UpdateSequence window
• Autoload last sequence that was worked on
• Quick load of last 6 sequences that were worked on - app dependant
• Select agent when you open the agent (popup menu) (Learn Sequence screen)
• Add last attrib to DLL Global mappings in TPL
• Fix menu item call to sequence
• Drop Lists fixed in ABC
• Text entry modified

Version History for Version 1.06 - Released April 15, 1999

• Put delay in after Closing the Agent at the end of a Sequence
• When double click Agent, pause automatically, with option to continue or stop
• Locate '+' button on sequence window correctly, immediately
• Display name of file on the sequence window
• Hide Default timer options until implemented (From Sequence form and Step form)

Version History for Version 1.05 - Released April 14, 1999

• Fixed Double click on the Sequence window to change step
• Fixed in EIP for timer (not working properly)
• Justified Event Comment and Value on the Sequence window
• Locate '+' button on sequence window correctly
• Drop-down list for Agent select
• Default agent in new sequence to the default one
• Resize drop-down list box for gestures
• After say return to say field
• Change to loaded agent if the learnt one is not loaded
• Fix pause bug when another agent is used when running
• Begin override timer function - to be completed in version 1.0
• Code template to call a sequence

Version History for Version 1.04 - Released April 14, 1999

• Code template to call a specific sequence
• Sequence Window resizing immediately
• Agent Check bug - check reflects correct status of the Agent
• Pop window up to select here/beginning/previous when running
• Fixed Agent moves
• Restore default Agent when starting a new sequence
• Hide controls after fail in select sequence
• Hide renumber item when sequence queue is clear
• Put in EIP for timer
• Agent gestures back in alphabetical order

Version History for Version 1.03 - Released April 12, 1999

• Agent moving - store in dialog units, solves moving problem for different screen settings
• Popup menu at double click genie to pause/stop the sequence at runtime
• Assign CtrlF12 to be an option on the global extension template
• Sequence window resizable
• EIP removed
• Window to prompt user for saving on exit
• Allow user to select a character for a sequence
• Make provision in the .dct for two fields for the Agent speech - one to say and one to show
• Renumber item on the menu - allows sequence to be renumbered
• ImmediateSay command closed when speech bubble close event is received
• Bug - Sequence won't finish until the Agent has completed what he's doing

Version History for Version 1.02 - Released March 16, 1999

• Tab swapping - browse refreshes in legacy
• Options - selects the desired option in legacy
• Agent events - use 11 for all except start (1) and end (3)
• No edit-in-place on the Sequence Window Value
• Auto close when sequence stopped/ sequence window closed
• First Agent move in new window fixed to correct reference
• Version control in DLL
• Autorun in AgentMenu template
• Add-Call added before the highlighted step
• Agent Say nothing prevents run freeze

Version History for Version 1.01 - Released March 5, 1999

• When moving MDI child windows takes the moved to co-ordinates
• References each control by name and not by ID
• Timing of genie events all set to 500 msec to prevent any delays
• Step comments to show agent, not genie

Version 1.00 - Released February 26, 1999