Simply Clarion - Documenting ABC Embed Points - Part 2 --Text

by Don Reynolds

Published 1998-08-01    Printer-friendly version

Download the code here

Last Month

We talked about how to determine what should be put into the #AT command of an embed point. This template command is essential when creating Control and Extension templates, for it determines where precisely the template-generated code should go.

This Month

We'll talk about how to use the same techniques to document templates for ease of use. Of course if you've memorized the Application Handbook, the various embed points and their appropriate priorities, you probably won't need this. But some of us need help.

Scenario

You are working on a project using the ABC templates. Your project consists of many procedures, and involves a fair amount of embedded code. You know that you can set ABC properties and invoke ABC methods within the embed points in your code. You also know that the Application Handbook contains good documentation on ABC methods and properties, plus some tips on how to do certain things.

The embeditor gives you a good way to input embedded code at various embed points. But over time, you find yourself going back and forth between the embeditor and the Application Handbook.

What you want is a way to selectively have notes from the Application Handbook appear in the embeditor code...so the embeditor would be a teaching tool as well as a programming tool.

An example

For this example I've used notes pulled out of the Application Handbook concerning the Window Manager Class---specifically ASK, INIT, and KILL. These three methods are sufficient to illustrate the techniques involved. You may want to refer to pages 706 - 709 to see what parts I've used.

The #AT

Using techniques described in last month's article, I determine how to set the #AT command in my template.

The Template

I then create a template as follows:

#TEMPLATE(ABCEMBED,'ABC Documenter'),FAMILY('ABC')
#EXTENSION(ABCEmbDoc,'ABC Embed Documenter')
#DISPLAY('')
#DISPLAY(' ABC Embed Documenter')
#DISPLAY('')
#DISPLAY(' No prompts are needed for this template')
#AT(%WindowManagerMethodCodeSection,'Ask'),PRIORITY(4500)
!***** ABC Documentation
! The ASK method displays the window and processes its events
!
! TIP: To shut down the window procedure while the Ask method is
! running RETURN Level:Fatal from any of the TAKE methods.
!
! TIP: To immediately stop processing for an event (including
! stopping, resizing and alerted keys), RETURN Level:Notify
! from any of the TAKE methods.
!
! Priority points to watch for:
! Before Parent.Ask()
! After Parent.Ask()
!-----
#ENDAT
#AT (%WindowManagerMethodCodeSection,'Init'),PRIORITY(4500)
!***** ABC Documentation
! The INIT method initializes the Window Manager object. Init
! returns Level:Benign to indicate normal initialization.
!
! The WindowManager may be configured to implement a variety of
! options regarding update windows (forms). You can use the INIT
! method to configure form behavior by setting the Request,
! InsertAction, ChangeAction, DeleteAction properties.
!
! TIP: To prevent the ASK method from starting, RETURN Level:Notify
! from the INIT method.
!
! Priority points to watch for:
! Before Self.RequestSet
! Before Parent.Init()
! Before Parent.Init()
!-----
#ENDAT
#AT (%WindowManagerMethodCodeSection,'Kill'),PRIORITY(4500)
!***** ABC Documentation
! The KILL method frees any memory allocated during the life of the
! object and performs any other required termination code. Kill
! returns a value to indicate the status of the shut down.
!
! Priority points to watch for:
! Before Parent.Kill()
! After Parent.Kill()
!-----
#ENDAT

Registration and Usage

I register the template in the normal way. To use this template, I select a procedure which has a window and press Extensions.

In the extensions window, I press Insert, then select ABCEmbDoc and press Select.

My ABC Embed Documenter now appears in my list of extensions.

I press OK to close the extension window, press OK to return to the Application tree. I right click on the highlighted procedure and press "Source" to activate the embeditor. I now find the following in the embeditor generated comments for ASK:

My documentation appears along with the tips. I can use the existing embed points to insert code as needed.

For the INIT method I find:

The Kill method now includes the following:

Notes:

You will note that I do not specify the priority within the documentation. I've found that sometimes the generated priority changes depending on what other embeds are included with the source. The above syntax seemed to be clear enough to determine which embed point to use.

Implications:

Many shops establish development standards which enable them to produce consistent quality code. It has been my experience that usually a small subset of embed points are used within a shop rather than every possibility. Following the above guidelines, a documentation template could be created within a shop which documented its standard embed usage. This would provide for consistency and standardization and save many lookups into the Application Handbook.

As with all documentation, this takes discipline and commitment. If the templates change, the documentation needs to be reviewed and changed appropriately.

Summary

Using the tools Clarion provides, we can provide additional means to assist us in developing systems faster and more consistently. By documenting templates (those provided by TopSpeed and others) within the embeditor, we bring the documentation to the point where the code is being created.

Printer-friendly version

Copyright © 1999-2008 by CoveComm Inc. All Rights Reserved. Reproduction in any form without the express written consent of CoveComm Inc., except as described in the subscription agreement, is prohibited.

Clarion Magazine ISSN 1718-9942