The Microsoft Visual FoxPro 6.0 Component Gallery 

Steven M. Black

March 1999

Summary: Discusses the new Microsoft Visual FoxPro Component Gallery. Covers the open architecture and programmable hooks that the Gallery and the companion Class Browser expose for customization. (17 printed pages)

Contents

Introduction The Visual FoxPro Component Gallery Understanding Item Types The BROWSER.DBF Structure

Introduction

This white paper discusses the new Microsoft® Visual FoxPro® Component Gallery. Together with the Visual FoxPro Class Browser, the Gallery provides useful ways to accomplish common development tasks. This document also discusses the open architecture and programmable hooks that these tools expose for customization. While this white paper presents the Gallery, an accompanying paper, The Visual FoxPro 6.0 Class Browser, presents the Class Browser, providing details specific to that development tool.

Update

The Visual FoxPro 6.0 Component Gallery and other related components have been updated. You can download this update from https://msdn.microsoft.com/vfoxpro/downloads/updates.asp. To ensure that you are using the latest version, you should download and install the update.

The Visual FoxPro Component Gallery

The Component Gallery is the Class Browser's companion. Both share the same display surface, and you can toggle between them with a handy toolbar button. The Component Gallery can be used to categorize and display almost anything (not just Visual FoxPro components), and its strength is in grouping the various artifacts of software development.

The Component Gallery is a flexible and programmable shortcut manager and explorer. Since it shows nothing but shortcuts, nothing you do directly in the Component Gallery affects the underlying files. You can create new files through the Gallery, for example, but the element 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, implementing, and living with this extension is up to you.)

Visual FoxPro 6.0 uses a system memory variable (named GALLERY) to identify the Component Gallery application. In Visual FoxPro 6.0, the default is GALLERY.APP in your HOME( ) directory. By changing the value of GALLERY, you can wrap and substitute the Component Gallery application just as you do many other Visual FoxPro tools. Visual FoxPro thus continues to provide user-definable extensibility. GALLERY.APP is a wrapper for BROWSER.APP. Running GALLERY.APP is the same as running BROWSER.APP and passing the sixth parameter as true (.T.). You can run the Component Gallery programmatically by using the following code:

DO (_GALLERY)

The full syntax respected by the Component Gallery includes the following parameters:

• First parameter (cFileName): File Name or file list (catalog(s) separated by commas).
• Second parameter (cDefaultItem): Text of Catalog, Folder, or Item to be selected when the Component Gallery is started.
• Third parameter (nWindowState): Window state of Component Gallery form when started (0=normal, 1=minimized, or 2=maximized).
• Sixth parameter (lGallery): Must be true (.T.) to run in Component Gallery mode. False (.F.) is for Class Browser mode; refer to The Visual FoxPro 6.0 Class Browser.
• Seventh parameter (lNoShow): Default false (.F.). If set to true (.T.), the Component Gallery is not activated or shown. You can then use the public memory variable, _oBrowser, to access the Component Gallery object model. (Refer to Visual FoxPro Help for documentation on the Class Browser methods, properties, and events.

Because of its intimate partnership with the Class Browser, the Component Gallery supports all the add-in mechanisms found in the browser. The Component Gallery, however, adds metadata-driven display and behavior of items to its Class Browser functionality.

Let's define a few terms that will help us understand the Component Gallery. After that, we'll look at how you can use the Component Gallery, then we'll examine the metadata that makes it all work.

Component Gallery Terms

Here are some terms that will serve us well in subsequent discussion.

Catalog: The highest-level container in the Component Gallery and its unit of file storage. A catalog is a .DBF or .FPT table whose records define shortcuts to software resources. For example, you could have a catalog named Office Pool.DBF*,* which contained folders and shortcuts to tables, programs, documents, hyperlinks, and anything else needed 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. Displayed in the Component Gallery, a catalog is a folder with no parent folder.

Folder: Like a subdirectory, a logical package of items. Catalogs can contain zero or more folders. Folders are either static or dynamic. A static folder contains predefined shortcuts to items. A dynamic folder determines its contents each time the Component Gallery is refreshed. A dynamic folder can be defined as a directory such as "C:\Projects\*.*," a Visual FoxPro project (.PJX) file, a class library (.VCX) file, a database (.DBC) file, or any URL or file that is valid in the Internet Explorer Web Browser control pane mode.

Item: A shortcut to a particular artifact.

Item Type: A category that defines the behavior of the items in the catalog. The default item types are stored in the home( )+"\Gallery\VfpGlry.VCX" class library, and are configurable for each catalog. (For each catalog, see the Properties dialog box, available on the Shortcut menu). The root catalog, always named "Catalogs," contains the default item types that all catalogs inherit.

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 expect.

The Gallery is divided 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 provide item-sensitive context menus for doing the usual useful things: cut, copy, paste, rename, and so on. You can also invoke item-sensitive property dialog boxes for selections in the left or right panes. Moreover, the entire Component Gallery is enabled for both regular and OLE drag-and-drop operations.

In Web view mode, the Items pane is automatically hidden by an Internet Explorer Web browser control. When the selected folder is a dynamic folder that is a URL, the Component Gallery displays in Web view mode. In the Web view mode, the four display control buttons become Back, Forward, Stop, and Refresh buttons.

As in the Class Browser, you can use the Item icon to drag the currently selected item to the desktop, design surface, or project. Right-clicking Item invokes a GetPict( ) dialog box to change the icon. A nice touch here is that when you select Cancel in the GetPict( ) dialog box, you get an option to reset the icon to the item default. Setting the icon using the Item icon is the same as setting the item picture in the Properties dialog box for that item.

The View control box contains default and user-defined views of the Component Gallery. Views are queries of specific items in and across catalogs. For example, selecting Internet filters the catalogs to display Internet items only.

To create your own custom views, see the Dynamic Views tab in the Component Gallery Options dialog box. If Advanced Editing mode is enabled, you can create custom item-type views.

To create custom item-type views:

1. Select an item and invoke its properties.

2. Click the Views tab.

3. In the EditBox, type a line item such as the following text.

   My Stuff=Test Files
   

4. Press F5 to refresh the Component Gallery.
   The My Stuff view appears in the Views control box.

5. Select this view, the Test Files folder appears.

6. Select this folder and a shortcut for that item appears in the right pane.

This process allows you to create custom item-type views, and any item can be in any view. Refer to the existing item type settings in the shortcut items included in the Visual FoxPro Catalog items.

The Go to Browser button toggles the Component Gallery window to the standard Class Browser. Hint: right-clicking the button displays a long list of the previously opened folders.

The Open button is for opening new catalogs. The Open dialog box is a little unconventional and merits explanation. In that discussion, we'll take our first look at the Component Gallery internals.

This isn't your garden-variety Open dialog box. The Catalog box 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 are stored in the GALLERY\VFPGLRY.DBF table. The Add catalog checkbox adds the contents of the catalog to the current view (the default is "replace"). In addition you can use the Browse button to select an existing catalog that is not listed in the catalog dropdown.

When you click Options in the Component Gallery window, a three-tabbed dialog box appears wherein you can set certain Component Gallery properties.

The Standard tab displays the general defaults for the Component Gallery itself; some of these are self-explanatory. Note, however, the Advanced editing enabled checkbox, which enables you to access advanced features of Component Gallery options and property dialogs.

Use the Catalogs tab to maintain the catalogs that appear in the Catalog box in the Open dialog box. Click New to load a new catalog in the Catalogs pane. A Global catalog is 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 opens whenever you invoke the Component Gallery. Note that when you invoke the Component Gallery from the Class Browser, it always comes up empty. The Component Gallery initially appears populated only when the original invocation is performed with the DO (_Gallery) command.

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

In the following example, I've created a dynamic view of "UseCase" documents by both creating and assigning such keywords as "Actor" and "Extends." The keywords displayed in this list are stored in a table named Keywords.DBF.

The Component Gallery Find button is a nice surprise—it works just like dynamic views! In effect, when you use Find you are creating a new persistent view like the one defined on the Dynamic Views tab. I'm not so sure I'm crazy about this. After all, cluttering my own dynamic views every time I search through a file might be a bit much. On the other hand, dynamic views are easy enough to purge in the Dynamic Views tab of the Component Gallery Options dialog box.

Understanding Item Types

The behavior of a Gallery item, as in what happens when you click it or drag it, is defined in 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 file, such as My_VfpGlry.VCX. This allows you to later update the Component Gallery class libraries without fear of clobbering your work.

Here is the hierarchy of the Component Gallery item types supplied by Microsoft. _item and _folder are abstract root classes that are defined in _Gallery.VCX. All the others are in VfpGlry.VCX.

When creating your own item types, the most flexible prototype is the _fileitem. In fact, _fileitem should serve most of your needs, since it invokes Windows file associations to run or modify the item. Moreover, the _fileitem type can redirect popular file extensions to other file types. We'll talk more about redirection shortly.

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 on the Folder Properties of the root catalog, you'll see something like this dialog box.

Note the following points about the Item Types tab in this dialog box.

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 Class Item tab of the Item Properties dialog box. For example, the Properties box of the ActiveX item in the Component Gallery example above show the following:

• File name: (and, within braces, ".ocx, .exe, and .dll"), cFileName—Specifies that the Class Item tab of this class of item will provide a label, textbox, and command button. This information is stored in the object cFileName property.
• Remote path: (and, within braces, ".ocx, .exe, and .dll"), cRemoteField—Specifies that the Class Item tab of this class of item will provide a label, textbox, and command button. This information is stored in the object cRemoteField property.
• ActiveX ProgID: cProgID—Specifies that the Class Item tab of this class of item will provide only a label and testbox for ActiveX ProgID. This information is stored in the object ProgID property.

Note   The entries within braces create a command button with an ellipsis (…) that will, when clicked, display the Open dialog box that defaults to browse for the listed file extensions.

The other lines of the ActiveX item type are out of view; they include entries for Class, Class library, Source project, and Associated file, and these all work the same as those already described.

Note   Placing an asterisk (*) before the property name marks that property to be displayed as read-only text in the Properties dialog box. For example, the following entry in Class Item displays the textbox as read-only.

*Base class:,cBaseClass

If you create your own item types, you can make them available by clicking Add and specifying the new item type.

Item Redirection

The Properties page of the _FileItem item type is worth a look because, in addition to showing custom properties, it shows an example of item redirection. See the Redirect box in the following dialog box.

This is the full list of redirections:

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 file as an item, the Component Gallery uses the PRG redirection to create 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.

The BROWSER.DBF Structure

The Class Browser stores all its metadata in a table named BROWSER.DBF 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 that pertain to the Gallery.

The Catalog Table Structure

This is a very brief overview of Component Gallery-specific metadata. The Component Gallery distributes its metadata to 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 such as whether the catalog is a global (auto-open) or default (in the default view). See the BROWSER.DBF metadata description.

If you delete a Component Gallery catalog record from BROWSER.DBF, it won't appear in the Component Gallery Open dialog box. The Component Gallery catalog records in BROWSER.DBF contain ".dbf" in the Name field. Since this field is of type memo, you can't easily identify Component Gallery records in a simple browse of BROWSER.DBF.

The rest of the Component Gallery metadata is stored in VFPGLRY.DBF, which installs in the Visual FoxPro 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 fields in a representative record, the one with ID="fileitem".

"CLASS"

"fileitem"

"File"

"Item"

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

Vfpglry.vcx

_fileitem

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

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

Catalog tables contain records that reference actual catalog items. The main native catalog is named "Visual FoxPro Catalog," and it is found in VFP_Catalog.DBF. All the Visual FoxPro 6.0 foundation classes, for example, are cataloged there.

The structure of catalog tables is the same as that of VFPGLRY.DBF, so that 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. This example uses the record with ID="clireg" in Activex_Catalog.Dbf. This item allows you to register a custom Visual FoxPro automation server remotely, using its generated .VBR file.

"ITEM"

"clireg"

"actxtools"

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

cDblClick=<>

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

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

Steven Black specializes in developing multilingual, multisite, and other challenging software situations, including project turnarounds and cleanups. He is the creator of Steven Black's INTL Toolkit, a multilingual framework for FoxPro and Visual FoxPro. He's a regular speaker at Visual FoxPro conferences, and his contributions occasionally darken the pages of FoxPro books and magazines.

Steven can be reached via email at steveb@stevenblack.com*. His Web site is* http://www.stevenblack.com.

© Microsoft Corporation. All rights reserved.