Hacking the Class Browser and Component Gallery

Visual FoxPro’s Class Browser and Component Gallery (or just “Browser” and “Gallery”) are valuable development tools; most self-respecting VFP hacks will want to know them well.

Most of Visual FoxPro’s ancillary tools, like Browser and Gallery, are actually written in Visual FoxPro. (Surprised?) Starting with VFP 6, the source code for all the VFP-coded tools is included. This is great news for VFP developers because the source for these tools provides some great (and occasionally not so great) examples. If you search carefully, you may even find an astonishing feat of software prowess: a comment in the source code.

Lack of comments aside, if you’ve ever wondered just how a particular wizard or service works, you can now easily and legally reverse-engineer it.

The source for VFP’s tools is kept in a ZIP file in the HOME()+"Tools\XSource" directory. If this directory doesn’t exist on your system, it’s possible that you chose to omit some tools during installation. The Browser and Gallery source can be found in the HOME() + "Tools\XSource\vfpsource\Browser" directory. The most interesting file in this directory is the form Browser.SCX. The Browser and the Gallery share the same SCX file, and many of the methods therein serve both the Browser and the Gallery.

Let’s look first at the Browser, and then we’ll explore the Gallery.

The Class Browser

The Browser is useful for a variety of development purposes. These include, among others:

• Managing classes and class libraries, including adding, deleting, renaming and redefining classes.

• Generating equivalent code for visual classes.

• Creating running instances at design-time.

• Browsing all the classes and libraries used by a project.

• Browsing the interfaces of ActiveX and COM components.

Starting the Class Browser

There are three ways to start the Browser. From the Tools menu, select Class Browser. Another way is to use the _BROWSER system variable. _BROWSER defaults to “Browser.APP”, which is located in the Visual FoxPro home directory. Issuing the command:

DO (_BROWSER)

is equivalent to using the menu. In addition, you can pass a parameter containing the name of the class library to load. For example, this code:

DO (_BROWSER) WITH HOME(2)+"tastrade\libs\about"

loads About.VCX from the TASTRADE sample application. Add a second parameter to the command to select a particular class in the list. For example, this code:

DO (_BROWSER) WITH HOME(2)+"tastrade\libs\about", "aboutbox"

loads the About library and selects the class called AboutBox. Specifying a form file name directly works, too:

DO (_BROWSER) WITH HOME(2)+"tastrade\forms\customer.scx"

starts the Browser with the form Customer.SCX loaded.

Finally, if the Gallery is running, you can just click the Browser button to show the Browser.

The Browser Interface

Figure 5-5: Just browsing, thanks. The Class Browser interface.

Figure 5-5 shows the Browser. Here are a few things you should know about the Browser to increase your productivity with this tool.

	Click this button to see the class code. Note that in some cases, the code shown can't be executed correctly. (This happens if the class is a container of other classes.) Right-click this button and see the class code in HTML format. This isn't obvious, but the window that appears is actually an instance of your HTML browser. You can right-click in the window and choose View Source to display the HTML source for the display.
	Use this button to create a new class. This new class can be a subclass of the currently selected class, a subclass of any other class, or a subclass of a VFP base class.
	You can redefine classes (that is, change the parent class) in the Browser with this icon. Starting in VFP 6, you can even redefine a class to use a different base class, after being warned that some intrinsic methods and properties will understandably be lost in the process.
	When you have a method code window open, this button (which floats or docks independently of the Browser on a one-button toolbar) allows you to view the code up the class hierarchy in parent class methods. This button is available even after you close the Class Browser.

View More Than Class Libraries

In the Browser’s Open dialog, note the different types of files that are supported. Figure 5-6 shows the Browser’s Open dialog with the drop-down expanded to show the sorts of things you can display in the Browser.

Figure 5-6: Open sesame! The Class Browser’s Open dialog shows that you can view more than just class libraries in the “Class” Browser.

You can open VFP forms in the Browser; many of the features, such as showing code, work as you might expect. This is very handy for communicating your code examples with other users via e-mail.

If you open a VFP project file, all the class libraries in that project are visible in a single view. This is great if your project contains hundreds of classes and you have no idea which library a particular class belongs to. This view is a lifesaver when you inherit (or join) a new project.

You can open all manner of EXE and OLE files, and the Browser displays their public interfaces. If help is available, double-clicking an item or pressing the spacebar invokes it.

Clever Tricks

To add controls to a form or class, in the Browser open the VCX (class library) containing the class of the object you want to add to the form, select the class, and then drag and drop the class icon to the design surface. You can also drop a control on the desktop, and you’ll get a running instance of that class.

To quickly get to a class you’re using, in the Form or Class Designer select an object. Open the Browser. It opens with the class library of the selected class loaded, and with the selected class highlighted.

Class Management

Table 5-1 shows what you can do with classes using either VFP commands or the Browser.

Table 5-1: The class-management functions of the Class Browser.

Programming the Class Browser with Add-Ins

The VFP Browser is designed for extensibility. It has a rich programming interface, and it exposes its complete object model. The usual way to program the Browser is by hooking its events and methods with Browser add-ins.

An add-in is a program that you create (or download) and then register with the Browser. Once registered, the add-in can be invoked automatically by Browser events or methods. If the add-in is not assigned to a particular event or method, the user can invoke it.

Here is an example Browser add-in that demonstrates some of the most important qualities of add-ins.

* Program Add-InSample1.PRG
* This program echoes class information to
* the debug output window
 
#DEFINE DEBUGWINDOW  "Debug Output"
 
LPARAMETERS oBrowser
 
IF ! oBrowser.lFileMode AND !EMPTY(oBrowser.cClass)
 ACTIVATE WINDOW DEBUGWINDOW
  
  *-- Output the class name 
  DEBUGOUT "Class Name: "+ oBrowser.cClass
 
  *-- Output the class library name
  DEBUGOUT "Class Library: "+ oBrowser.cFileName
 
  *-- Output the class's timestamp
  DEBUGOUT "Timestamp: "+ PADR(oBrowser.nTimeStamp,25)
  
  *-- Display the entire class pedigree
  DO WHILE oBrowser.SeekParentClass()
      *-- Output the parentclass name
      DEBUGOUT "Parent Class: "+ oBrowser.cClass
  ENDDO
ELSE
  WAIT WINDOW "Please select a class and try again"
ENDIF

Observe the following points about the sample add-in above: The Browser passes a reference to itself as a parameter to the add-in. This means that all of the Browser’s members are available for reference. The example demonstrates the Browser’s cClass, cFileName, and nTimeStamp properties, and its SeekParentClass method.

Now, with the Browser running, register the add-in as follows:

_oBrowser.AddIn("Sample Add-In", "Add-InSample1.PRG")

While the Browser form is running, you can refer to it with a memory variable named _oBrowser.

The Browser’s AddIn method registers add-ins. The syntax shown here specifies a name for the add-in and the program to run. An optional third parameter specifies the event or method to which the add-in gets assigned.

If a Browser event is assigned to the add-in, then the add-in is invoked automatically near the beginning of that event’s execution. If a Browser method is assigned to the add-in, then the add-in is invoked near the end of that method’s execution.

In the example above, since no method or event is specified, the add-in is listed in the Browser’s add-in shortcut menu.

The Add-In option doesn't always appear on the shortcut menu. When the mouse is over the Classes or Members panes, right-clicks don't show add-ins among the choices. You have to right-click on either of the description pages or the top of the Browser, where the buttons are, or over the Browser form itself, to see the add-in item.

Alternately, passing the name of an add-in to the Browser’s DoAddIn() method runs that add-in.

Tell me more! Tell me more!

The Browser is extensively documented under “Class Browser” in VFP Help. Also take a look at the following topics: “Class Browser Buttons”, “Class Browser Methods”, and “Class Browser Properties.” For more information on add-ins, see also the white papers section of the Visual FoxPro pages on the Microsoft Web site.

Having Trouble with the Class Browser’s ActiveX Controls

Some people complain that earlier versions of the Class Browser crashed a lot. Although that’s not much of an issue in later versions, if the Browser is prone to instability on your system, try invoking it with the optional third parameter set to .T.:

DO (_BROWSER) WITH FileName, , .T.

This opens the Browser in “listbox” mode with the TreeView control replaced by a VFP listbox. It’s not as pretty looking, but it may work better for you. (This is a legacy feature from VFP 3, which had a Mac version; the listbox is a substitute for the outline OLE control, which doesn’t have a Mac counterpart.)

The VFP Component Gallery

The Gallery is the Browser’s companion. Both share the same display surface, and you can toggle between them with a handy command button.

The Gallery is a flexible and programmable shortcut manager. Because it works with shortcuts, you can’t hose a file using the Gallery; when you delete a shortcut from the Gallery, the underlying file is not deleted.

The Gallery can be used to categorize and display almost anything, and its strength is in grouping the various resources used in software development. With the Gallery, you can create and display your own abstractions, organized as you wish, with event behavior—such as click, right-click, double-click—that you can innovate and control. Moreover, the Gallery also has dynamic folders, which we’ll discuss in a minute, which have the ability to hold all the contents of VFP projects, class libraries and directories.

Now, you could use the Other Files section of the Other tab in Project Manager to do some of this, but that’s primitive, inflexible, and—let’s face it—low tech.

What’s What in the Gallery

It’s probably a good idea to explain a few things before going further.

A catalog is both a DBF table and the highest-level element of the Gallery. A catalog’s records define the shortcut items you see in the right-hand pane in the Gallery.

A folder is simply a logical package of items and possibly other folders. (Folders look just like subdirectories and that abstraction works for us.) Folders are either static or dynamic. A static folder contains predefined shortcuts to items. A dynamic folder determines its contents each time the Gallery is refreshed. A dynamic folder could be defined as a directory (“C:\Projects*.*”), a VFP project, or a class library.

An item is a shortcut to a particular file or URL.

An item type defines the behavior of particular items in the catalog. Item types are stored in the HOME()+"Gallery\VfpGlry.VCX" class library, and are configurable through the Properties dialog for each catalog. The root catalog, named “Catalogs”, contains the default item types that apply to all catalogs. See “Understanding Item Types” below for more on item types.

Start Me Up!

VFP has a system memory variable named _GALLERY to identify the Gallery application. By default, it’s called “Gallery.App” in your HOME() directory. You can replace or “wrap” the Gallery application by changing the value of _GALLERY.

You can use the _GALLERY memory variable to invoke the Gallery, like this:

DO (_GALLERY)

In addition, you can pass a parameter containing the name of the catalog to load. For example, this code:

DO (_GALLERY) WITH HOME()+"Gallery\Vfp Catalog"

loads Vfp Catalog.DBF.

You can also start the Gallery from the Tools menu, or click the Gallery button in the Browser.

The Component Gallery Interface

If you’re comfortable with Explorer-type interfaces, the basic features of the Gallery (shown in Figure 5-7) will work pretty much as you’d expect.

Figure 5-7: The Component Gallery interface—yet another Explorer-type interface

The Gallery is segmented into two panes. The Catalog pane, on the left, lists the folder hierarchies within the currently open catalogs. The Items pane, on the right, shows the items in the current catalog or folder. Both panes are endowed with item-sensitive context menus to do the usual useful things such as cut, copy, paste, rename, and so on. You can also invoke item-sensitive property dialogs for selections in the left or right panes. Moreover, the entire Gallery is enabled for both regular and OLE Drag and Drop.

As in the Browser, the Move icon—the top-left icon in the Gallery form (which changes based on the highlighted item)—can be used to drag the currently selected item to the desktop, a design surface, or a project. Right-clicking the Move icon invokes a GETPICT() dialog to change the icon. There’s a nice touch here: When you select Cancel in the dialog, you get the option to reset the icon to the default for that item.

The View Type drop-down lets you choose among different views of the Gallery. For example, in the VFP Catalog, selecting “Internet” filters the catalogs to display Internet items only. To create your own custom views, use the Dynamic Views tab in the Gallery Options dialog—we’ll look at that in more detail a little farther along. The Browser button toggles the view back to the standard Browser. Neat touch here: Right-clicking the Browser button brings up a nice long list of the previously opened folders.

The Open button is for opening new catalogs. The Open dialog (Figure 5-8) is a little unconventional and merits explanation. In the process, we’ll take our first look at the Gallery internals.

Figure 5-8: An Open dialog like no other. The Component Gallery’s Open dialog is different because it offers catalog tables, and those references are kept in Browser.DBF.

This isn’t your garden-variety Open dialog. The catalog drop-down control displays the catalogs currently registered on your system. The catalog names are kept in the Browser.DBF table. If you ever clean out or lose Browser.DBF, you can click the Browse button to select an existing catalog file that isn’t listed in the Catalog drop-down. The “Add catalog” check box control adds the contents of the catalog to the current view (the default is to close the current catalog and open the one you specify).

The Options button brings you to a three-tabbed dialog (Figure 5-9) where you can set certain Gallery properties.

Figure 5-9: I need options. The Component Gallery comes with its own options; this figure shows the Standard tab.

The Standard tab displays the general defaults for the Gallery itself. Like some of the Tools, Options dialog options, these brief labels can be pretty obscure until you understand the product well:

• The “Enable item renaming” check box determines if clicking and then hovering over the item puts you in a name-edit mode, just as it works in Explorer.

• The “FFC Builder Lock” check box will, if checked, automatically invoke builders for new objects you create with the Gallery. If they have a builder, that is. Some do, some don’t.

• The “Drag and drop to desktop” check box enables dragging and dropping to the desktop, just like it works in the Class Browser.

• Checking the “Advanced editing enabled” check box gives you access to advanced features of Gallery property dialogs. This is where the Gallery really starts to shine!

The "Advanced editing enabled" check box is a killer. If this option isn't checked, that explains why you can't do half the stuff we're talking about in this chapter.

• The “Catalog default behavior” option determines whether new catalogs are appended to, or replace, the current visible collection of catalogs.

• The “Item default behavior” option determines whether double-clicking on an item opens or edits an item by default. This applies only to items that can be edited in VFP, of course. Otherwise, the selection will simply run regardless of what you’ve specified here.

Figure 5-10: What, no underwear ads? A catalog page suitable for family viewing.

Use the Catalogs tab (Figure 5-10) to maintain the list of catalogs that appear in the Catalog drop-down in the Catalog Open dialog.

The New button is enabled only when at least one catalog is loaded in the Catalogs pane. We don't know why we need to load a catalog before we can create a new one, and frankly this behavior seems wrong. Nonetheless, that's the way it is.

The Global and Default check boxes let you set the persistent visibility of each catalog. A Global catalog is always visible in the Catalogs pane, regardless of which catalogs you open for display. You may want to mark the Favorites catalog as a global catalog so you always have access to your favorite things. A Default catalog is the one that’s active and current whenever the Gallery is invoked programmatically. You can have any number of default catalogs.

When you invoke the Gallery from the Browser, it always comes up empty. The only way the Gallery appears initially populated with the default catalogs is when it's originally opened with DO (_Gallery) or with Tools, Component Gallery.

The Dynamic Views tab lets you create your own custom, live views of your catalogs. Figures 5-11 and 5-12 show how to create or edit a new dynamic view called “Excel Spreadsheets” that displays all items of type “file” that contain “.XLS” in their names.

We think dynamic views are ultra cool. This adds a second powerful dimension to the Gallery. The first dimension is the obvious one: catalogs and folders that logically segment things as you choose. But dynamic views permit you to see all the items of a particular type (you define), regardless of their logical placement within a catalog.

Figure 5-11 Click the New button to create a new view, or the Edit button to bring up the dialog below.

Figure 5-12: A different view of things. This is where you define and edit dynamic views.

Figure 5-13 shows the Keywords dialog, accessible from a button in the Edit View dialog. This dialog lets us create dynamic views based ON KEYwords used to describe them. The keywords displayed in this list are stored in a table called Keywords.DBF. You can use keywords to further expand the power of the Gallery’s dynamic views.

Figure 5-13: Views can be based ON KEYwords you specify.

In order to add a keyword, you must first have a catalog loaded in the Gallery. When we instructed the underpaid workers at Hacker Laboratories to take the screen shot shown in Figure 5-13, we forgot to mention that, so that's why the Add and Remove buttons look disabled.

We think all the things you can do in the Options dialog are a good idea. But we cannot fathom why the Catalogs page is in that dialog. More specifically, we can't understand why the New button is in that dialog. This isn't an option, it's an action. Options are choices you make about how things look or operate. It's as if the New button in the Project Manager could only be accessed from the Project Info dialog. We'd feel the same way about the Dynamic Views page, except for one thing. Surprise! The Find button works just like choosing New on the Dynamic Views page! In effect, when you choose Find, you create a new persistent view. We're not really crazy about this; after all, cluttering our dynamic views every time we go searching is a bit much. However, it's easy enough to clean up the list of dynamic views using the Dynamic Views page.

Understanding Item Types

So, how does the Gallery work internally, you ask?

The behavior of a Gallery item, like what happens when you click or drag it, is defined by its item type. The class library Gallery\VfpGlry.VCX stores the item types supplied by Microsoft, and you can modify, subclass, or simply copy these classes to create your own types. If you develop your own custom item types, it’s probably a good idea to store them in some other VCX, such as My_VfpGlry.VCX. This allows you to later update the Gallery’s class libraries without fear of clobbering your work.

Here’s the hierarchy of the Gallery item types as supplied by Microsoft. The _item and _folder classes live in _Gallery.VCX. All other classes are defined in VfpGlry.VCX.

Figure 5-14: Type-o-rama! The Item Types hierarchy provided by Microsoft.

When creating your own item types, the most flexible base type is the _fileitem. In fact, _fileitem should serve most of your needs because its behavior is to simply invoke the Windows file associations. Moreover, the _fileitem type has the ability to redirect popular file extensions to other file types. We’ll talk more about redirection in a minute.

Item types can be tied to particular catalogs. The root catalog, which is always named “Catalog”, serves as the basis for all catalogs. If you select the Item Types tab of the properties of the root catalog, you’ll get something like the dialog in Figure 5-15 once you’ve turned on the Advanced Editing option on the Class Browser’s option dialog. Do it now! C’mon, you’re reading the Hacker’s Guide! That alone qualifies you as “Advanced!”

Figure 5-15: Catalog Properties, Item Types.

Note the following things about the Item Types page in this dialog:

• The list of item types matches the item types you see in the New Item shortcut menu. To modify the New Item shortcut menu, simply edit this list.

• Each item type can be associated with display text, a class, and a class library. In this case the display text is “ActiveX”, the class is _ActiveXItem, and the class library is VfpGlry.VCX.

• The lines in the Properties edit box specify what’s displayed in the final page of the item’s Properties dialog. For example, for the ActiveX item type pictured in Figure 5-15, when you examine the properties of an ActiveX item in the Component Gallery you’ll see the following:

• File name: with an associated Open dialog initialized with OCX, EXE, and DLL files, and the file name specified will be stored in the item’s cFileName property.

• Remote path: with an associated open dialog initialized with OCX, EXE, and DLL files, and the file name specified will be stored in the item’s cRemoteFile property.

• Other lines in the edit box can’t be seen in Figure 5-15. They include entries for Class, Class Library, Source project and Associated file; these all work the same as described above for the corresponding text box entries.

• If you create your own item types, you make them available by clicking the Add button and filling in the specifics of your new item type. The properties for the _fileitem item type are worth a look because, in addition to showing custom properties, they show an example of item redirection. See the Redirect field in Figure 5-16.

Figure 5-16: Item Types.

Here is the full list of redirections:

BMP=_imageitem, ICO=_imageitem, JPG=_imageitem, GIF=_imageitem, WAV=_sounditem, RMI=_sounditem, AVI=_videoitem, DBF=_dataitem, SCX=_formitem, MNX=_menuitem, FRX=_reportitem, LBX=_reportitem, PRG=_programitem, APP=_sampleitem, OCX=_activexitem, HTM=_urlitem, HTML=_urlitem, PJX=_projectitem, TXT=_programitem, LOG=_programitem, H=_programitem.

You can probably guess how redirections work: When an item with any of those file extensions is created, the designated item type is created instead. For example, if you try to add a PRG as a file item, the Gallery notices the PRG redirection and creates a _programitem instead of a _fileitem. This is why the _fileitem item type is so flexible; it has the ability to properly redirect new items to the correct item type.

Note that dragging VCX or PJX files from Windows Explorer just creates a regular file shortcut, and not a dynamic folder. We think VFP's Gallery should be able to recognize VFP's own components.

Programming the Component Gallery with Add-Ins

Since the Gallery and Browser are really the same application, you can hook into the Gallery’s events and methods with add-ins in the same way you can with the Browser.

I Never Metadata I Didn’t Like

Here’s a brief description of the data structures used by the Browser and the Gallery.

Browser.DBF

The Browser stores all its metadata in a table named Browser.DBF found in the VFP home directory. The Gallery also uses Browser.DBF to store its catalog-related information. Table 5-2 shows a field-by-field description of Browser.DBF.

Table 5-2: The structure of Browser.DBF.

Additional Component Gallery Data Structures

Here’s a brief overview of Gallery-specific structures. The Gallery distributes its metadata in several locations.

Like the Browser, the Gallery keeps some of its metadata in Browser.DBF (described above). That data stores references to the available catalogs, as well as some properties such as whether the catalog is a global one (auto-open and always in view) or default (in the default view). Delete a Gallery catalog record from Browser.DBF and it won’t appear in the Gallery Open dialog. The Gallery catalog records in Browser.DBF contain “.dbf” in their Name field. Since this field is of type memo, you can’t easily identify Gallery records in a simple browse of Browser.DBF—what a pain.

The rest of the Gallery metadata is stored in VfpGlry.DBF, which lives in the Gallery subdirectory below the VFP root. VfpGlry.DBF defines the default display and behavior of the Gallery. When you look at the Gallery, you are looking at catalogs whose items are defined in the particular catalog tables, but whose default behavior emanates from definitions in VfpGlry.DBF.

In fact, delete all Gallery records from Browser.DBF and the Gallery will re-initialize the root catalog from data in VfpGlry.DBF.

Many of the records in VfpGlry.DBF point to behavior classes stored in VfpGlry.VCX through fields named ClassLib and ClassName. Thus the records in VfpGlry.DBF are pointers to the behavior classes that, in the case of the native VFP-supplied behaviors, live in VfpGlry.VCX. Of course, any custom gallery behavior you define or modify can live in any VCX you choose. In fact, if you define custom Gallery behavior classes or modify existing ones, we suggest that you keep these in a different class library so that future upgrades of VFP don’t clobber your work.

To illustrate some of the functionality of VfpGlry.DBF, Table 5-3 examines some of the fields in a representative record—the one with ID = “fileitem”.

Table 5-3: Some of the fields in VfpGlry.DBF for the “fileitem” record.

Other records may use different fields and different values, but this representative record is enough to get you started in hacking the Gallery.

Catalog tables contain records that reference actual catalog items. The main native catalog is called “Visual FoxPro Catalog” and is kept in “VFP Catalog.DBF.” All VFP foundation classes, for example, are cataloged there.

The structure of catalog tables is the same as that of VfpGlry.DBF, so much of what we’ve already seen also applies here. This is a good opportunity to look at a few other metadata fields and how they work. Table 5-4 shows the record with ID = “clireg” in “ActiveX Catalog.DBF.” This item allows you to register a custom VFP Automation server remotely using its generated VBR file.

Table 5-4: The “clireg” record in ActiveX Catalog.DBF.

cVBRFile = GETFILE("VBR")
cCliReg = oThis.cFileName
 
IF !FILE(m.cCliReg)
  RETURN .F.
ENDIF
 
IF EMPTY(m.cVBRFile) OR ;
 UPPER(JUSTEXT(m.cVBRFile))#;
 "VBR"
  RETURN .F.
ENDIF
oThis.Runcode([RUN /N ] + ;
 [&cCliReg. "&cVBRFile."] + ;
 [ -NOLOGO])

Please Sir, I Want Some More

We’ve just scratched the surface of the Browser and Gallery. If you’re interested in finding out more about these powerful and extensible tools, we recommend Advanced Object Oriented Programming With Visual FoxPro 6.0 by Markus Egger, also available from Hentzenwerke Publishing (www.hentzenwerke.com).