Session E-COMP

Advanced Component Gallery

Steven Black
steveb@stevenblack.com
http://www.stevenblack.com


The VFP6 Component Gallery and Class Browser

Introduction

This white paper discusses the Visual FoxPro (VFP) class browser and its companion, the new component gallery. Together the browser and the gallery provide many useful ways to accomplish common development tasks.

The class browser is presented first, then the component gallery is introduced. The appendices present useful information on the accessible data structures used by these tools. This document also discusses the the programmable hooks that these tools expose for customization purposes.

The VFP Class Browser

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

What's new in VFP6.

Most changes to the VFP6 class browser enhance its usability. The following enhancements to the VFP class browser are roundly welcomed.

Of course, the big change in the class browser is integration with the new component gallery.

The Browser Interface

Here are a few things you should know about the class browser to increase your productivity with this tool.

 

Click this button to see the class code. The class contains nested classes, the code won't execute. 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 browser, wherein you can use the shortcut menu to view the HTML source for displaying the source.

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 off a VFP base class.

You can redefine classes in the class browser with this icon. In VFP6, you can redefine a class to that of a different base class, after being warned that some intrinsic methods and properties will be understandably lost in the process.

When you have a method code window open, this button (which floats independently of the Browser) allows you to view the code up the class hierarchy in parent class methods.

View more than class libraries

In the class browser's open dialog, note the different types of files that are supported. The figure below is the class browser open dialog pointing to the component gallery directory, with the dropdown expanded to show the sorts of things you can show in the class browser.

To add controls to a form or class

In the class 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.

Invoke the class of a selected item on a form

Here's one I bet most folks don't know: In the form or class designer, select a control. Now if you invoke the class browser it will appear loaded with the class library of the selected class, with the select class as the current class. This works with running forms too, except that it uses the control that has focus.

Class management

Bewildered by many of the class management activities that you can do with the class browser? The see the following white paper available at http://www.microsoft.com/vfoxpro/techmat/whitepapers/mngcls2.htm.

Having Troubles with the Class Browser's Activex Controls?

If, as some people complain, the class browser is prone to instability on your system, try invoking the class browser as follows:

 DO (_BROWSER) WITH FileName, , .T. 

Note the third parameter is true. This will bring up the class browser in "listbox" mode where the treeview control are replaced with a listbox control. It's not as pretty looking, but this may work better for you.

You should be aware that I use the class browser extensively running the latest build of FoxPro ant NT4 SP3 on a completely NT-compliant machine and I have no instability problems whatsoever with the class browser.

Programming the Class Browser with Addins

The VFP class browser is designed for extendibility. It has a rich programming interface, and it exposes its complete object model. The usual way to program the VFP class browser is by hooking its events with class browser addins.

There is a good white paper about writing basic class browser addins located at http://www.microsoft.com/vfoxpro/techmat/whitepapers/addins.htm. Please refer to this paper if you've not written an addin before. In addition, the class browser is extensively documented under "class browser" in VFP help.

Conclusion

There you have it: a quick cafeteria-style tour of some of the neat things in the VFP component gallery and class browser. These are great tools, and if you use VFP every day it's likely that you could make much better use of them. I hope this document and the session presentation both help achieve that.

The VFP Component Gallery

The component gallery is the class browser's companion. Both share the same display surface, and you can toggle between the component gallery and the class browser with a handy toolbar button.

A key abstraction of the component gallery is this: the component gallery is a flexible and programmable shortcut manager. Since all it shows are shortcuts, nothing you do directly in the component gallery is fatal to the underlying files.  You can create new files through the gallery, for example, but the rendering in the gallery remains a shortcut to the new file. Delete the shortcut and the underlying file is not deleted. (You could extend the gallery to delete the underlying file when you delete the shortcut, but writing and implementing this extension is up to you.)

The component gallery can be used to categorize and display almost anything, and its strength is in grouping the various artifacts of software development. The highest-level element of the component gallery the catalog. A component gallery catalog is a .DBF table whose records define shortcuts to any sort of software resources.

For example, you could have a catalog named Office Pool.DBF which could contain folders and shortcuts to tables, programs, excel spreadsheets, documents, hyperlinks, and anything else to manage friendly office wagers. More than likely you'll also create project catalogs to organize all the artifacts of your software projects as they are created.

VFP6 uses a system memory variable (named _GALLERY) to identify the component gallery application. In this case it's "Gallery.App" in your HOME() directory. By changing the value of _GALLERY, The component gallery application can be 'wrapped' and substituted just like many other VFP  tools can. VFP thus continues its long tradition of user-definable extensibility, and the component gallery is certainly no exception.

In that vein, the component gallery is the epitome of flexibility and extensibility. Because of its intimate partnership with the class browser, the component gallery gets all the add-in mechanisms found in the browser. But the component gallery goes much further than the class browser because the display and behavior of items in the component gallery is completely metadata-driven.

Let's look at how you can use the component gallery, then we'll examine the metadata that makes it all work. Please bear in mind that I'm working with a beta version, and things could change between now and the public release of VFP6.

The Component Gallery Interface

By now you should be comfortable with explorer-type interfaces.  If so then the basic features of the component gallery work pretty much as you would expect.

The gallery is segmented into two panes.  The catalog pane, on the left, lists the hierarchy of currently open catalogs. The items pane, on the right, shows the items in the current catalog hierarchy. Both panes are endowed with item-sensitive context menus to do the usual useful things like cut, copy, paste, rename and so on. You can also invoke item-sensitive property dialogs for selecions in the left or right panes.  Moreover, the entire component gallery is enabled for both regular and OLE drag and drop.

Like in the class browser, the item-sensitive move icon 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. A nice touch here, when selecting Cancel in the GetPict() dialog, you get an option to reset the icon to the item default.

The view type control invokes a list default and user-defined views of the component gallery. For example, selecting "Internet" filters the catalogs to display Internet items only. To create your own custom views, see the Dynamic Views tabs in the Component Gallery Options dialog. Right-clicking the view type control passes through and displays the standard component gallery form right-click.

The Class Browser button toggles the view back to the standard class browser. Neat touch here: right-clicking the class browser button brings up a nice long list of the your previously opened folders.

The Open button is for opening new catalogs. The open dialog is a little unconventional and merits explanation and, in the process, we'll take our first look at the component gallery internals.

This isn't your garden-variety open dialog. The catalog dropdown control displays the catalogs currently registered on your system. The catalog names are kept in the BROWSER.DBF table, and the detail records for each catalog is stored in the GALLERY\VFPGLRY.DBF table. The Add catalog checkbox control adds the contents of the catalog to the current view (the default is replace). In addition you can use the Browse commandbutton to select an existing catalog that maybe isn't listed in the catalog dropdown.

The Options button brings you to a three-tabbed dialog wherein you can set certain component gallery properties.

The Standard tab displays the general defaults for the component gallery itself, and some of these are self-explanatory. Take note, however, of the Advanced editing enabled checkbox which will allow you to access advanced features of component gallery options and property dialogs.

Use the Catalogs tab to maintain the catalogs that will appear in the catalog dropdown in the Catalog Open dialog. The New button is only enabled when a catalog is loaded in the catalogs pane. A Global catalog is one that will be visible in the catalogs pane regardless of which catalog is selected for display. I've made my Favorites catalog a global catalog so I always have access to my favorites. A Default catalog is one that will be open whenever the component gallery is invoked. Note that when you invoke the component gallery from the class browser, it always comes up empty. The only way the component gallery appears initially populated is when its original invocation is with DO (_Gallery).  I'm told that this is by design.

The Dynamic Views tab can be used to create your own custom dynamic views of your catalogs. In the figures below, I've created a new dynamic view called "Excel Spreadsheets" that displays all items of type "file" that contain ".XLS" in their names.

In the example below, I've created a dynamic view of use case documents by both creating and assigning keywords like "Actor" and "Extends". The keywords displayed in this list are stored in a table called Keywords.DBF.

The Find button is a nice surprise -- it works just like dynamic views! In effect, when you hit find you are creating a new persistent view just like we defined under Options -Dynamic views. I'm not so sure I'm crazy about this, after all cluttering my own dynamic views every time I execute a "Find" might be a bit much, but on the other hand dynamic views are easy enough to purge in the Dynamic Views tab of the Component Gallery Options dialog.

Component Gallery Productivity Tips

Appendix 1 - Metadata

BROWSER.DBF

The class browser stores all its metadata in a table named BROWSER.DBF found in your HOME() directory. The Component gallery also uses BROWSER.DBF to store its catalog-related information. Here's a field-by-field description of important elements in BROWSER.DBF.
Field Description Browser Gallery

PLATFORM

Starting with VFP5 the platform field has a value of "WINDOWS" except for records of type "ADDIN" where the field value is blank.

n

n

TYPE

Records with type field value "PREFW" store browser and gallery preferences. Records with type field value "ADDIN" store addin information.

n

n

ID

"FORMINFO" records are used by the class browser to store form preferences and by the component gallery to store information about your catalogs.  The only way to tell the difference is component gallery records contain the string ".dbf" in the Name field.

"BROWSER" records contain default settings for the class browser. See the Properties field for this record to see these  default properties.

"METHOD" records store class browser addins that are tied to a particular class browser event or method.

"MENU" records store class browser addins that are not tied to a particular class browser event or method, and are thus available on the addin shortcut menu.

 

n

 

 

 

n

 

n

 

n

n

 

 

 

 

 

n

 

n

DEFAULT

Logical true for the default component gallery catalog.

 

n

GLOBAL

Applies to component gallery catalog records. Logical true if the catalog is global. By default, new catalogs are not global. To specify a catalog to global, select the Catalogs tab in the component gallery options dialog.

 

n

BACKUP

When a catalog or a VCX is opened by browser/gallery, this field in the associated BROWSER.DBF record is queried. If the value is logical true, the browser/gallery checks to see if a file of the same name exists in the backup subfolder below that one.  If the backup file doesn't exits, one is automatically created (including a subfolder called Backup if needed).  Then the Backup field is set to .F.  So, this field can be set programmatically to force the browser/gallery to automatically backup that file/table the next time that file is opened, and only the next time. You can set this field via add-in hooks or just at any time with a program that opens and updates browser.dbf.  This feature is  used internally in one special case, when browser.dbf is first created after VFP is installed, a new browser.dbf is created with the default catalogs (around 5 or so) and the Backup field is set to .T. so that each catalog gets backed up the very first time it is opened since VFP does not install the associated backup catalog tables.  Beyond that special function, it can be used at will by developers for their own purpose.

n

n

NAME

The file name that relates to this record. For a class browser record the file type could be, among other things, .VCX, .PJX, .SCX, .OCX, .DLL, .EXE, or APP. 

For component gallery records the file type will be .DBF.

In the case of clas browser and component gallery addins, the name field stores the name of the addin. This is what will appear in the addin shortcut menu if the addin is not tied to an event or method.

n

 

 

 

 

n

 

 

 

 

n

 

n

DESC

Used only by the component gallery and it stores the description of the catalog referred to in the Name field.

 

n

METHOD

Stored the name of the method to which a class browser or component gallery addin is tied. If the method field is equal to "*" then the addin will execute for all methods.

n

n

PROPERTIES

Used by the class browser to store default settings.

n

 

SCRIPT

(???)

 

n

PROGRAM

Used by the class browser and the component gallery to store the name of the program to execute by .PRG-based addin.

n

n

CLASSLIB

Used by the class browser and the component gallery to store the name of the class library in the case of a .VCX-based addin.

n

n

CLASSNAME

Used by the class browser and the component gallery to store the name of the class to execute in the case of a .VCX-based addin.

n

n

FILEFILTER

Used by addin records to specify file masks for which the addin applies.  The FileFilter is specified in the fourth parameter of the Addin method.

n

 

DISPMODE

The WindowState for the browser/gallery form for that FileName (vcx/scx/dbf/etc). 

 

 

TOP

The stored top coordinate for the browser/gallery form.

n

n

LEFT

The stored left coordinate for the browser/gallery form.

n

n

HEIGHT

The stored height of the browser/gallery form.

n

n

WIDTH

The stored width of the browser/gallery form.

n

n

HEIGHT1

The stored height of the class and member description panes in the class browser.

n

n

WIDTH1

The stored width of the class and member description panes in the class browser.

 

 

HEIGHT2

Relates to the stored height of the item description pane in the component gallery.

 

n

WIDTH2

Relates to the stored width of the item description pane in the component gallery.

 

 

WINDOWSTAT

0 - Window is zoomed normal; 1 - Window is minimized, 2 - Window is maximized

n

n

PROTECTED

Used by the class browser. Logical true if protected members are to be displayed.

n

 

EMPTY

Used by the class browser. Logical true if empty methods are to be displayed.

n

 

HIDDEN

Used by the class browser. Logical true if hidden members are to be displayed.

n

 

DESCBOXES

Used by the class browser and the component gallery. Logical true if description panels are to be displayed.

n

n

AUTOEXPAND

Used by the class browser and the component gallery. Logical true if hierarchical items are automatically to be displayed expanded in the left hand side pane.

n

n

PUSHPIN

Used by the class browser and the component gallery. Logical true if the display is always on top.

n

n

PCBROWSER

Parent class toolbar flag. If logical true for a file item, then the toolbar is on for that file.  If you close the parentclass toolbar the VCX(s) open will have PCBrowser=.F. for those records.

 

 

VIEWMODE

??

 

 

FONTINFO

Used by the class browser and the component gallery to store the display font preference.

n

n

FORMCOUNT

??

 

 

UPDATED

The datetime this record was last updated.

n

n

COMMENT

 

 

 

USER1

 

 

 

USER2

 

 

 

USER3

 

 

 

USER4

 

 

 

Additional Component Gallery Metadata

This is a very brief overview of component gallery-specific metadata. The component gallery distributes its metadata in several locations.

Like the class browser, the component gallery keeps some of its metadata on a table named BROWSER.DBF, which is found in your HOME() directory. The data therein stores the references to the available catalogs, as well as some of their properties like whether the catalog is a global one (auto-open) or default (in the default view). See the BROWSER.DBF metadata

Delete a component gallery catalog record from BROWSER.DBF and it won't appear in the component gallery Open dialog. The component gallery catalog records in BROWSER.DBF contain ".dbf" in their name field. Since this field is of type memo, you can't easily identify component gallery records in a simple browse of BROWSER.DBF, and that's a pain.

The rest of the component gallery's metadata is stored in VFPGLRY.DBF, which installs in VFP's Gallery\ subdirectory. This table stores catalog item type metadata. It is here that the behavior of the various item types is defined. When you look at the component gallery, you are looking at catalogs whose items are defined in the particular catalog tables, but whose behavior emanates from the items defined here.

To illustrate some of the functionality of VFPGLRY.DBF, let's examine some of the fields in a representative record, the one with Id="fileitem".

 
Field Value Comment

Type

"class"

Metadata class specifcation. Catalog items can "inherit" from one another. There are thus many different variants of "fileitem" elsewhere in the metadata, and they may override or augment the things defined in this record.

Id

"fileitem"

The unique identifier for this type of item.

Text

"File"

The item display text.

Typedesc

"Item"

i.e. not a "Folder".

Desc

 

The text appearing in the item description pane.

Properties

File name:{},cFileName
Parameters:{},cParams

 

Specification for input fields that appear in the properties dialog for items of this type. Values inside the curly braces are used as the parameter in GetFile() dialogs.

Classlib

Vfpglry.vcx

The class library where the item's class is stored.

Classname

_fileitem

The default class that embodies this catalog item.

Itemtpdesc

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

Alternate classes to embody file items of these particular types.

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

Catalog tables contain records that reference actual catalog items. The main native catalog is called "Visual FoxPro Catalog", and it is kept in VFP_Catalog.DBF. All the VFP6 foundation classes, for example, are cataloged therein.

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. For this example I've chosen the record with Id="clireg" in Activex_Catalog.Dbf. This items allows you to register a custom VFP automation server remotely using its generated VBR file.

Field Value Comment

Type

"ITEM"

 

Id

"clireg"

This item's Id.

Parent

"actxtools"

Id of the parent catalog record, in this case it corresponds to a folder named "Tools".

Desc

"This tool allows you to register a custom VFP automation server remotely using the generated VBR file."

The description window text.

Properties

cDblClick=<>

You can override the events (keypress, click, dblclick, rightclick) by setting the c[EventName] property.  If it's something like cDblClick=DO foo.prg, then it will run that line.  If you set cDblClick=<testscript>, then it will run the code in the Script memo field of the record with Id= "testscript".  If you set cDblClick=<>, then it will run the code in the Script memo field of that record.

Thus this DblClick runs the code in the script field below.

Filename

(HOME(6)+"CLIREG\CLIREG32.EXE")

The file name to execute, stored in oTHIS.cFileName. See the Script field below. Note that the whole behavior of this item is defined by the filename field and, in this case, the Script field also.  The ClassName and ClassLib fields are blank in this record.

Script

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])

The Script field gives you control over what happens when the user runs the item. This VFP code will execute in a code block upon DoubleClick.

Note that in this version there ois no script equivalent of DODEFAULT() so if you script an event, the default behavior for this event will not execute.