Coverage Profiler Add-Ins
Add-Ins are code files (usually .prg or .scx) that provide an easy way for you to adjust the Coverage Profiler. The cov_standard subclass of the coverage engine, which comprises the User Interface of Coverage.app, shows only a small part of what you can do with the engine. The engine analyzes the coverage log; cov_standard just displays the results in one of many ways you could want to see them.
You could create a different subclass of cov_engine with a very different display. For example, your subclass might display a dialog that runs queries against the coverage statistics gathered by the engine. The display options might provide a view of the marked code for a filtered set of log entries, or only a graph of the profiling results.
You might not want to subclass cov_engine to create a new interface from scratch because the cov_engine class provides an easier process. You can add functionality to cov_standard, or any cov_engine subclass, using Add-Ins. Cov_standard exposes this feature through a button in the main dialog of Coverage Profiler. When you run an Add-In on an instance of cov_standard such as Coverage Profiler, the Add-In can manipulate the capabilities of cov_engine, the coverage tables, as well as cov_standard. Add-Ins might also add new dialogs and features to the cov_standard visual interface.
Writing Add-Ins
You can write Add-Ins to enhance the standard interface or you can subclass cov_standard to create your own wholly new interface.
Enhancing the Standard Application
The following list includes features you might want to provide through Add-Ins:
Add a visible feature to the main dialog.
Add a dialog into the coverage engine formset (reference limitation below on how to make sure your dialog shows up in the right place).
Display a separate dialog that accesses a Coverage engine feature (reference limitation below on how to make sure your dialog shows up in the right place).
Provide a querying interface that uses the Source table and presents a list of all lines that meet your criteria, and filters or orders the results.
Note
You can use the Adjust... methods (AdjustCoverageFilenameCursor(), AdjustSourceCursor(), and AdjustTargetCursor()) of the Engine to add fields to the Source and Target tables when the engine creates them, and use these fields in your Add-Ins.
Add file names to the IgnoredFiles cursor, to eliminate those files from analysis. This can save analysis time.
Use the special Init hook for Add-Ins.
Register Add-Ins for retrieval and easy access to a list of Add-Ins.
The modal dialog class cov_AddInDialog in the standard coverage engine subclass, presents previously registered dialogs in a drop-down list. When you set the coverage engine lRegisterAdd-In option ON, the full path name of successfully run Add-Ins are added to the Windows Registry so you can easily run these Add-Ins again. The Standard UI class also allows you to set this property in the Coverage Profiler Options dialog box.
The Coverage Engine object maintains a list of all registered Add-Ins in the aAddIns property.
Use the final coverage.log field information, callstack, to design your own interface or your own view of the coverage log.
When you write Add-Ins, consider the following information:
You can use any of the supported file types as Add-Ins. The supported file types are .qpr, .qpx, .mpr, .mpx, .app, .exe, .scx, fxp, .prg and .procedures (if the procedures are already available in an open procedure library).
The Coverage Engine formset has an "invisible" toolbar. If your Add-In is nonvisual you can use this toolbar to contain it. If your Add-In is a visual control, the standard subclass main dialog .Cov_tools member container is probably the most convenient place to put it. This allows the position and size of the toolbar to be automatically synchronized with the rest of the dialog when it is resized.
All the engine methods that use the Source and Target tables take optional arguments that allow you to point these methods at the appropriate aliases while you're working with them. You can also change the current cSourceAlias and cTargetAlias property contents to match the pair of cursors in which you are interested. This allows you to compare multiple Coverage log runs to each other within the same interface.
Limitations:
Add-Ins must accept one parameter (the Coverage engine passes a reference to itself).
An Add-In must be one of the permitted file types, listed above.
Procedures you use as Add-Ins should be available in a currently loaded procedure library (see SET PROCEDURE Command) in Help. The Engine does not use the IN FileName syntax, and it does not call procedures or .prg files as functions and RETURN their values. It does not use the NAME or LINK keywords on the DO FORM command; you can either manage the reference yourself, or allow the Engine to scope a form for you by making your form a member of the Engine formset.
If you run an Add-In at startup, you must use a reference because the public _oCoverage variable is not yet available. At other times, you can use the public variable reference within your own code, if you prefer.
When you write an Add-In as a form, if you create the form as ShowWindow = 1 and run Coverage in its own frame, your Add-In forms should display in the Coverage frame.
If you use .RunAddIn from the Command window, make sure the coverage frame is the active MDI frame before you instantiate your forms.
Subclass Cov_Standard Class
You can subclass either the coverage engine or its standard subclass. The following list describes the structure of the COVERAGE project source file set.
File |
Description |
|---|---|
Coverage.prg |
A "wrapper" for the coverage object, which instantiates the object. |
Coverage.vcx Coverage.vct |
All classes for the engine and its standard subclass. |
Cov_short.mnx Cov_short.mnt |
Shortcut menu. |
Cov_pjx.frx Cov_pjx.frt |
Default mechanism to deliver project-level results. |
Coverage.h |
Header file for all Coverage code, incorporating the following elements: *— Coverage character constants for log and parsing: *— Coverage localized strings (can use some log and parsing constants): *— Coverage common dialog component constants: *— Coverage specs & requirements: *— Coverage registry object constants: *— Coverage tune-able options: |
The COVERAGE project source file set also includes various .ico .bmp, and .msk files.
Use the file COV_TUNE.H (containing appropriate comments and explanations) to become familiar with options available to you without rewriting code.
Because Add-In use is governed by the coverage engine base class, any other coverage subclass you create can use Add-Ins in the same manner as the standard subclass.
The coverage engine subclass instantiated by the default Coverage.app does not augment the coverage engine RunAddIn( ) method in any way. It does, however, invoke a modal dialog box to allow the user to pick an Add-In before it invokes the coverage engine RunAddIn( ) method. The modal dialog box receives a reference to the Coverage object and sets the coverage engine cAddIn property.
If you write your own coverage engine subclass, ensure that your subclass can use the same modal dialog class (cov_AddInDialog) to handle Add-Ins as the standard Coverage application; the dialog box does not rely on any features of the standard subclass.
You can call a different modal dialog box, set the cAddIn file name directly in the cAddIn property, or override the contents of the cAddIn property by passing the name of the Add-In file you wish to run to the RunAddIn( ) method.
However you access an Add-In to run in your subclass, you can investigate the list of Add-Ins registered to Coverage.app by checking the file names in the coverage engine aAddIns property.
For details on the Properties, Events, and Methods of the coverage engine, see Coverage Engine Object in Help.
See Also
Concepts
Coverage Profiler Modification