Partilhar via

The Microsoft Visual FoxPro 6.0 Component Gallery 

  • Artigo

 

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

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.

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:

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

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.

Field Description
PLATFORM "WINDOWS" except for records of type "ADDIN" in which the field value is blank.
TYPE "PREFW" records store browser and gallery preferences. "ADDIN" records store add-in information.
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 that 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 add-ins that are tied to a particular Class Browser event or method.

"MENU" records store Class Browser add-ins that are not tied to a particular Class Browser event or method, and are therefore available on the add-in shortcut menu.
DEFAULT Logical true (.T.) for the default Component Gallery catalog when the Component Gallery is started with an unspecified first parameter of GALLERY.APP.
GLOBAL Applies to Component Gallery catalog records. Logical true (.T.) 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 box.
BACKUP Specifies, when true (.T.), that the Class Browser or Component Gallery check for duplicate files in the backup subfolder.

When a catalog or a VCX is opened by browser/gallery, this field in the associated BROWSER.DBF record is queried. If the backup file doesn't exist, one is automatically created (including a subfolder named Backup if needed). Then the Backup field is set to false (.F.) You can set this field programmatically to force the browser or gallery to automatically back up that file or 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, containing the default catalogs (around 5 or so), is created. Because Visual FoxPro does not install the associated backup catalog tables, the Backup field is initially set to true (.T.) so that each catalog is backed up the very first time it is opened. Beyond that special function, its functionality is available to developers for their own purposes.
NAME Specifies the file name related 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 is .DBF.

In the case of Class Browser and Component Gallery add-ins, the name field stores the name of the add-in. This is what will appear in the add-in shortcut menu if the add-in is not tied to an event or method.
DESC Provides a description of the catalog referred to in the Name field. Used only by the Component Gallery.
METHOD Stores the name of the method to which a Class Browser or Component Gallery add-in is tied. If the method field content equals "*" then the add-in will run for all methods.
SCRIPT Internal Gallery use only
PROGRAM Used by the Class Browser and the Component Gallery to specify the name of the program to run by .PRG-based add-in.
CLASSLIB Used by the Class Browser and the Component Gallery to specify the name of the class library in the case of a .VCX-based add-in.
CLASSNAME Specifies the name of the class to run in the case of a .VCX-based add-in. Used by the Class Browser and the Component Gallery.
FILEFILTER Specifies file masks for which the add-in applies. The FileFilter is specified in the fourth parameter of the Add-in method.
TOP Specifies the top coordinate for the browser/gallery form.
LEFT Specifies the left coordinate for the browser/gallery form.
HEIGHT Specifies the height of the browser/gallery form.
WIDTH Specifies the width of the browser/gallery form.
HEIGHT1 Specifies the height of the class and member description panes in the Class Browser.
HEIGHT2 Specifies the height of the item description pane in the Component Gallery.
WINDOWSTAT Specifies the display size of the Component Gallery or Class Browser.

0 – Window is zoomed normal
1 - Window is minimized
2 - Window is maximized
DESCBOXES Specifies, if true (.T.), that the description panels are to be displayed. Used by the Class Browser and the Component Gallery.
AUTOEXPAND Specifies, if true (.T.), that the hierarchical items are automatically to be displayed expanded in the left-hand side pane. Used by the Class Browser and the Component Gallery.
PUSHPIN Specifies, if true (.T.), that the display is always on top. Used by the Class Browser and the Component Gallery.
VIEWMODE Gallery listview mode (1 – 4).
FONTINFO Specifies the Class Browser and the Component Gallery display font preference.
FORMCOUNT Number of instances running for file.
UPDATED The date and time this record was last updated.
COMMENT Unused.
User1….4 Unused.

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

Field Value Comment
Type 
"CLASS"
 Metadata class specification. 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.

The type field can be any value. The values that are reserved and used by the Component Gallery are:

"FOLDER"—Folder item (catalog, if parent field is empty).

"ITEM"— Item for the right pane, must have a valid parent field setting.

"CLASS"—Specifies an item type setting for that specific catalog, beyond the default item types of vfpglry.vcx.

"VIEW"—Specifies a custom view used when the catalog is open.

"SCRIPT"—Used to specify a special record that contains code in the Script field, and can be called by having a property setting like cDblClick=<MyScript>.

"OBJECT"—Used to specify a custom class to be instantiated when the catalog is refreshed. The ItemClass field is used to specify the class name, and the ClassLib field is used to specify the VCX of the class.
ID 
"fileitem"
 The unique identifier for this type of item.
Text 
"File"
 The item display text.
Typedesc 
"Item"
 Specifies the type of element. This is not a folder, but an item.
Desc   The text that appears in the item description pane.
Properties 
File name:{},cFileName
Parameters:{},cParams



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




Classlib

Vfpglry.vcx


The class library in which 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. Newly created items with these extensions are remapped to the designated item types.






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.











Field
Value
Comment






Type

"ITEM"


 




ID

"clireg"


This item's ID.




Parent

"actxtools"


The ID of the parent catalog record, which refers 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, and rightclick) by setting the [cEventName] 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 found in the script field.


You can use a record with Type="SCRIPT" to provide, in the catalog table, a reusable Script memo field that can be called when you run the browser object and reference the .RunScript( ) method.





Filename

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


The name, stored in oTHIS.cFileName, of the file to run. 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. 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 provides code for the SCRIPT type item with the ID specified by [cEventName] in the properties field. This Visual FoxPro code will run in a code block upon DblClick.

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


If you need a behavior like DODEFAULT( ), just manually make the direct call in the custom script like oTHIS.DblClick







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.