ADD_READ.TXT: GENERAL INFORMATION ABOUT COVERAGE ADDINS
------------  -----------------------------------------

This file serves as a general read.me for the sample AddIns delivered with COVERAGE.APP.  It explains: 

*-- what AddIns do for COVERAGE.APP
*-- how to call them
*-- how to write your own
*-- how to get rid of this dialog when you run the sample AddIns ;-)!

Each of the sample AddIns also has a .TXT file with a matching filename, to explain what that specific AddIn does.

As delivered, each sample AddIn will bring up the information in this file, plus its own *.TXT file, when it runs (assuming it can find the relevant files).  

If you don't need to see this information for any or all of the sample AddIns, change the #DEFINE for COV_ADDIN_README in each AddIn to .F., and re-compile. 

You'll find the #DEFINE in the following locations for the sample AddIns of these allowed AddIn file types:

PRG/FXPs:   top of program
QPR/QPXs:   top of program
MPR/MPXs:   top of program
APP/EXEs:   top of main program
SCXs:       top of Init method
PROCEDURES: top of Procedure

Note: there may not be sample AddIns of each type, but the above file types are all supported by the Engine for AddIns.  

These file types, and most other aspects of AddIns described in this text, are specified and handled by the *Coverage Engine*, not the *Standard Coverage UI* instantiated by the default COVERAGE.APP.  Refer to the main COVERAGE.APP technical reference material and "Using AddIns with your own Coverage Subclass" below, for more information.

What AddIns Can Do
------------------

Using a reference to the Coverage Engine, AddIns can manipulate any aspect of COVERAGE.APP.  For a few examples:

* -- interrogate the tables created by COVERAGE.APP to get more statistics

* -- change the physical appearance of the standard UI or add member controls to it

* -- filter or order the results displayed by COVERAGE.APP 

* -- tell the Engine to parse additional log files and display the results

The sample AddIns delivered with COVERAGE.APP will examine at least a few of these possibilities.

Note: If you would like to do Coverage-related things without bothering to write an AddIn program at all, just use the Engine's public reference variable (_oCoverage by default) in the Command Window!


Restrictions and Limitations
----------------------------

1) An AddIn must be one of the permitted file types, listed above. 

2) A Procedure you use as an AddIn should be available in a currently-loaded procedure library (SET PROC TO), since the Engine will call it using the following syntax:
  
    DO [FORM] <name> WITH THIS
    
... it does not use the IN <filename> syntax, and it does not call procedures or PRGs as functions and RETURN their values. It does not use the NAME or LINK keywords on the DO FORM command; you are responsible for maintaining these forms yourself. 

3) If you create the forms as ShowWindow = 1 and run Coverage in its own frame, your AddIn forms should show up in the Coverage frame.  This way, even if modeless, the forms will automatically disappear when Coverage does. It is your responsibility to make sure that your AddIns show up in the frame. If you call them from the Coverage Standard UI's context menu, tool button, or any other method of invoking then while the Coverage frame is active, this should happen automatically.  However, if you .RunAddIn() from the Command window, it is your responsibility to make sure that you make the Coverage frame the active MDI frame before you instantiate your forms.

4) Each AddIn *must* accept one parameter, since the Coverage Engine passes a reference to itself to the AddIn. If your AddIns need additional arguments, you can subclass the Engine's .RunAddIn() method in your own Coverage subclass, if you like (see below).  

Otherwise, you can find other ways for your AddIns to get this information. For example you could AddObject() a custom member to the default Coverage object, or to one of its dialogs, and this object's properties could hold the information your AddIn required. 

Use similar methods to send return values and other messages from your AddIn to other objects.

5) At startup (see "Running an AddIn at Startup", below), you *must* use this reference because the public variable is not yet available.  At other times, you can use the public variable reference within your own code, if you prefer.  

6) There are no other real restrictions on what AddIns can do, but be reasonable!  If you SET DATASESSION TO _oCoverage.DataSessionID in your AddIn, for example, it is probably not a good idea to CLOSE DATA during your AddIn <g>.


Running an AddIn at Startup
---------------------------

COVERAGE.APP receives three parameters:

1) a log filename to parse

2) a logical value, which you set to .T. if you simply want to parse all the records in the log file automatically and not have a user interface ("Unattended mode")

3) the name of an AddIn to run at startup.

If you pass the third parameter, the AddIn you pass will be run during the Init, after the Coverage Engine has set up an initial log file and parsed its records.

AddIns can be run from the Init either in Attended or Unattended mode.  

In an Attended Coverage run, you might want to add a button to the standard UI, which will run additional procedures later, during the life of the Coverage dialogs. 

When you are running Coverage Unattended, you might want to add some queries on the parsed log.

When you run an AddIn during Startup, the public reference variable is not available, so you must use the passed reference that all AddIns receive if you want to access Coverage properties, members, and methods.


Using AddIns with your own Coverage Subclass
--------------------------------------------

Since AddIn use is governed by the Engine superclass, any other Coverage subclass you create should be able to use AddIns in the same manner as the standard subclass. 

The Standard UI class instantiated by the default COVERAGE.APP does not augment the Engine's .RunAddIn() method in any way.  It does, however, invoke a modal dialog to allow the user to pick an AddIn before it invokes the Engine's .RunAddIn() method.  The modal dialog receives a reference to the Coverage object and sets the Engine's .cAddIn property. 

Your Coverage Engine subclass should be able to use this modal dialog class (cov_AddInDialog) too, if you like; the dialog does not rely on any features of the Standard UI class. 

If you prefer a different approach, you can call a different modal dialog, set the cAddIn filename directly in the cAddIn property, or override the contents of the cAddIn property by passing RunAddIn() the name of the AddIn file you wish to run. 

However you pick (or allow the user to pick) the AddIn to run in your subclass, you can investigate the list of AddIns registered to COVERAGE.APP by using the Engine's aAddIns[] collection of filenames (see below).

ErrorHandling in AddIns
-----------------------

The Coverage Engine will store the name of a successfully-run AddIn in its cAddIn property for additional calls.  It checks its own lError property to find out if a run was successful.  Therefore, if you want to notify the Engine that a run was *not* successful, simply set the Engine's lError flag to .T. before RETURNing.

Registering AddIns and Retrieving a List of Registered AddIns
-------------------------------------------------------------

If you turn on the Engine's .lRegisterAddIn option, it will add the fully-pathed filename of an AddIn that you have run successfully to a list in the Windows Registry, so that you can more easily choose to run this AddIn again.  

The Coverage Engine maintains a list of all such registered AddIns in its aAddIns[] collection. 

The modal dialog class cov_AddInDialog presents previously-registered dialogs to you in a drop-down list. It has a checkbox to set the .lRegisterAddIn Engine property for the AddIn you are currently choosing to run. The Standard UI class also allows you to set this property in its Options dialog.


