Product Review: The Clarion Class Browser

by Dave Harms

Published 1999-04-12    Printer-friendly version

Shortly after Topspeed released the first ABC templates Gordon Smith (aka "Le Schmoo") produced the Clarion Class Browser. Class browsers are a common feature in OO languages and are a much better way to view class source than viewing the source files directly.

The Clarion Application Generator does come with a class browser of sorts already, it's true. But this built-in browser has limited capabilities and cannot be run outside the AppGen. For most situations, and definitely when you're working with non-ABC classes, Le Schmoo's browser is the tool of choice. And the price is certainly right: it's free.

The class browser comes as a single executable setup program and installs into the directory you specify. This is a locally-compiled EXE – you do not need a particular runtime DLL.

After you install and run the program you'll need to create at least one class library file, which is a database of class header files. Choose File|New and provide a location and name for the database (the file will have the extension .clb). Click OK, and you'll see the library properties window, shown in Figure 1.

Figure 1. The class libraries   properties window.

I always dutifully fill in the fields as requested, but I have noticed that no matter what I specify for the default folder, the browser always looks in its own directory first when I wish to add a header. This may be because I have the class browser installed on a different drive than Clarion. (You can always go back and change these settings by choosing File|Properties.)

This directory amnesia isn't a big problem as you can add multiple classes at once, thereby avoiding repeated trips to the file dialog. Choose Edit|Insert OOP Header (or press Ins) to bring up a file dialog that looks for files ending in .INC. You select multiple files using the shift or control keys along with the mouse (or cursor keys). Click OK to add the header (.INC) files, which will provide the browser with the class declarations. Figure 2 shows the browser with the ABC (and several other) class headers loaded.

Figure 2. The Class Browser main window.

As Figure 2 shows, the top window shows the headers and their contents in a list box, and the bottom window shows the source code. I'll refer to these windows as the header and source windows. You can also have the source window on the right hand side if you prefer. This is how I work, but because of limitations on image size in this document most of the screen shots show the source on the bottom. Click here for a large image of the side by side view.

If you select a class element in the header window that is declared in the INC file (such as a group or queue, or the first line of a class declaration) the corresponding line is located and highlighted in the source window. If you select a method in the header window, the method source (from the corresponding CLW file) is shown.

As Figure 2 shows, header elements are identified by symbols. Figure 3 shows the symbol key (available from the Help menu).

Figure 3. The symbol key.

You can decide which of the header elements to display by making selections from the View menu, shown in Figure 4.

Figure 4. The view menu.

One of the key benefits of a class browser is it shows you the whole structure of derived classes. Figure 5 shows the beginning of the ABC BrowseClass, which is derived from ViewManager.

Figure 5. The ABC BrowseClass.

The + sign before the class declaration indicates that the list can be exploded at that point to show ViewManager's declaration, as shown in Figure 6.

Figure 6. The ABC BrowseClass exploded to show the parent ViewManager class.

Note that within ViewManager there are other declarations (Order and Primary) which can also be expanded. Order can be further expanded to show two of its complex elements: Filter (another queue) and RangeList. RangeList of type BufferedFieldPairsClass which is derived from FieldPairsClass, and FieldPairsClass contains a queue. Figure 7 shows these declarations.

Figure 7. Deep in the bowels of BrowseClass.

Without a class browser, the only way you could get a picture of the actual structure of BrowseClass would be to go digging through the header files (which is exactly what the class browser does for you), and then you'd have to go through the source files to see what the methods do. With the class browser, the method source is also only a click away.

The class browser also has a Find feature which lets you search all or selected parts of the class library. Once you've found the first instance you may wish to close the modal Find window and use the Edit|Find Next feature (or just press F3).

Figure 8. The Find window.

The class browser also has a Compile menu which has but one item: Generate Project. This option will create a PRJ and corresponding EXP (export) file (with the same name as the class library) and a set of modified INC files for the classes you have loaded. This is NOT intended for use with the ABC classes since there are also typically global variables and files involved when setting up multi-dll applications, but it's a nifty solution for creating handcoded dlls as it handles the export file creation. The EXP created is for 16 bit applications. You can use it for 32 bit apps but be aware that the SIGNED and UNSIGNED data types mangle differently in 32 bits so if you're using these as parameters you'll have to modify the EXP file. One item on the toolbar which isn't on the menu anywhere is the Edit Source button. Use this button to switch to edit mode in the source menu, and to switch back (and save your changes). Although this is a nice feature, I think I'd prefer to use the Clarion editor to work with my source.

Documentation

One drawback to the class browser is the complete lack of documentation. Fortunately, most features (except perhaps DLL creation) are fairly intuitive. Another weakness is that the Class Browser is time-limited, and several times per year you will need to download an updated version from Gordon's web site. As I use the class browser heavily it seems I'm occasionally the first person to discover the browser has expired, but I've always been able to obtain an updated version in short order, most recently the same day.

I've given the the Class Browser a "three pyramid" rating rather than a four only because there is no documentation explaining where to get support. As this is a mature product you most likely won't need any, but the author's email address is in Help|About. Earlier in the product's life I did report some bugs to Gordon and always received prompt action.

If you're interested in exploring the inner workings of ABC, I suggest you use the Class Browser in conjunction with cciProfilerClass to generate a method call tree. As you follow down the log of method calls use the browser to locate the source and see what code is being executed.

The Class Browser is one of my most-used utilities and I recommend it highly. Click here to download. Also available at that page: Compile Manager, a tool for automated compiles of multi-app projects.

---

David Harms is an independent software developer and the editor and publisher of Clarion Magazine. He is also co-author with Ross Santos of Developing Clarion for Windows Applications, published by SAMS (1995), and has written or co-written several Java books. David is a member of the American Society of Journalists and Authors (ASJA).

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