The Component Gallery: VFP's Best Kept Secret 

  • Article

This article may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. To maintain the flow of the article, we've left these URLs in the text, but disabled the links.

The Component Gallery: VFP's Best Kept Secret

Markus Egger

Visual FoxPro 6.0 shipped with a great new tool called the "Component Gallery." This tool is mainly thought to be a productivity-enhancing tool that makes the use of components, classes, and other items found in Visual FoxPro much easier. Unfortunately, so far, very few third-party vendors and development teams have utilized the Component Gallery to the extent one would expect, making this great new addition to VFP one of VFP's best kept secrets. In this article, Markus Egger not only demonstrates how the Component Gallery can be used, but also how you can create your own catalogs.

When you start the Component Gallery from the Tools menu, it starts up with several default catalogs already loaded. Catalogs are simply collections of items stored in hierarchical fashion. You can think of each item stored in the Component Gallery as a shortcut to a Visual FoxPro item such as a class, a form, or a report. You might wonder what makes this tool valuable since we already have access to these items through the Class Browser as well as the Project Manager. That's correct; however, there's a significant difference: The Class Browser as well as the Project Manager are built as tools for the developer who needs access to every single item in the project. They show all classes, support classes, include files, bitmaps, and much more. The Component Gallery, on the other hand, simply provides access to the top-level items such as classes or components, but hides the complexity under the hood. You can compare this to a car mechanic who needs access to every part of the car, including the engine, transition, and car alarm, while the driver who simply uses the car to get to work every day doesn't worry about all of those things.

If you're the "application mechanic," you'll be better off using the Class Browser or the Project Manager. It will provide access to every little bit of the application. This is especially true if you wrote the entire application by yourself. However, if you're using third-party tools or even components written by your fellow co-workers, you might not need this level of granularity. In fact, it will make it much harder to use those components. Imagine that a team member provides you with a class library that you can utilize for a specific task. This library contains a number of classes, one of which is useful to you. All of the other classes are really just helper classes that the main class depends on, such as parent classes, members of the class, or other classes that are utilized by the main class to do its job. In addition, you get a number of external files such as include (.H) files, bitmaps, and XML definition files that are also required to make this component work.

Do you really care about all of this information? Of course not! Or, well… you shouldn't. Why would you want to become the mechanic of somebody else's "car"? However, in reality, you'll have to familiarize yourself with all of those components to make sure you add them all to your project and to pick the right class in the first place. Little do you know at this point that your co-worker tried to make this class as easy to use as possible and even provided a builder that can be used to configure this class.

The Component Gallery will help you in this scenario. Your colleague can create a simple catalog that provides a link to the main class. When you drag and drop that link on your form, not only will the class get added, but, at the same time, all external references are taken care of, and immediately the provided builder starts to make it easy for you to configure the required properties rather than finding out manually which properties have to be set.

You say this isn't a problem for you, because you don't work in a team, or perhaps the team is so small you can simply ask the co-worker? Well, what about third-party products? At EPS, we produce a product line called the FEC (Fox Extension Classes). This is simply a set of classes stored in class libraries, plus a few external dependencies, just as described in the preceding scenario. We gave a lot of thought to the product architecture, resulting in a very flexible environment that farms most of the functionality out to special behavior objects that can be configured and extended at will. The downside of this architecture is that 80 percent of the classes shipped in the libraries aren't made to be used directly, but are designed for internal use only. How would you like to navigate all of the information through the Class Browser? So there!

Another great advantage of the Component Gallery is its hierarchical representation of the information. It allows organizing items into folders. This is surely much easier to use than the inheritance-view provided by the Class Browser, or the flat-view provided by the Project Manager.

So let's have a look at the Gallery. When you start it the first time, it shows several default catalogs that provide access to the FFC (Fox Foundation Classes) as well as VFP's samples (see Figure 1).

Most of the items referenced in the default catalogs are FFC classes. Note that the Gallery can maintain a large number of different items, such as forms, reports, wizards, files, utilities, ActiveX controls, and much more. Basically, any Visual FoxPro as well as Windows item can be referenced through the Gallery. In addition to static links to items, the Gallery also supports a feature called "Dynamic Folder." Figure 1 shows a reference to such a folder. It's named "Installed Controls." This folder automatically shows a list of all COM components and ActiveX controls installed on your system.

To use a specific class such as the FFC VCR Buttons class, simply select the item and drag and drop it to your form or class that's open in the designer (note that the Gallery can also be used for source code editing). It will automatically add an instance of the class to your form. You don't have to worry about what library it's stored in, nor are you bothered with all of the other classes stored in the same library. The Gallery abstracted all of that complexity away and provides simple, categorized access to this component. Note also that the Gallery displays a description of the component you selected.

You want to know how much easier this is than using the Class Browser? Well, just right-click on the item and select "View in Browser." This automatically opens the library in which the class is stored and switches the Component Gallery into Class Browser mode (the Gallery and the Browser internally are really the same application). The result is shown in Figure 2.

As you can see, this view is much more cryptic. Not only do you see all kinds of classes you have no interest in (how about those custom classes—what's your guess, can they be used by themselves or not?), but you also see class names that are much harder to understand, and the Class Browser doesn't even provide a description.

Another good example is the list of samples that ship with VFP. Perhaps you're not aware of this, but the FoxPro team has produced a large number of examples that explain many aspects of the Visual FoxPro environment and language. In previous versions, this information was hard to find. Samples are scattered over all kinds of directories, and who wants to run all of them just to figure out what they're doing? The Component Gallery ships with a special catalog that lists all of the included samples and provides access to them in ways that make sense for each individual example (see Figure 3).

As I mentioned earlier, the Component Gallery can also be used to automatically trigger builders whenever a complex class is dropped in a designer. Try dropping the "Field Mover" class from the Data Navigation folder in the main Visual FoxPro catalog. Immediately, the builder shown in Figure 4 starts up and asks you to provide important property values. You can drop the same class from the Class Browser or the Form Controls toolbar, but then you'd have to go through an almost endless list of properties and try to figure out what they're for, whether or not they're important, and what the appropriate settings are.

Creating your own catalogs

So, by now are you convinced of the usefulness of this tool and eager to provide your own catalogs for your libraries, or perhaps even commercial third-party products? Well, you've come to the right place.

Creating a new catalog is easy. Simply click the option button and select the Catalogs page in the options dialog box (see Figure 5). Click the New… button and specify the name of the catalog file (which is a regular DBF file). Initially, the new catalog is listed by its filename. We'll define a friendlier name a little later. Click the OK button to close the dialog box and open the new catalog right away.

To rename the catalog, right-click the item and choose Properties (the Rename feature doesn't appear to work). This launches the dialog box shown in Figure 6. Note that you might not see all of the same options shown in Figure 6. If this is the case, open the Options dialog box and check the "Advanced Editing Enabled" feature on the first page. You can use the Properties dialog box not only to change the name, but also to set descriptions as well as icons that are to be displayed by the Gallery.

To make the new catalog useful, you'll have to add some items. First of all, add a new folder that provides links to the classes you'd like to keep track of. You can create new items, including folders, by right-clicking in the right-hand pane (see Figure 7). Again, you have to open the Properties dialog box to rename the folder and set other properties such as the icon.

You can now proceed to add items to that new folder, in the same way you created the folder itself: Right-click in the right-hand pane and choose to add a new Class. The Gallery will present you with a GetClass() dialog box to select the class. The item added to the Gallery will automatically be assigned the name of the class, but again, you can change this to a friendlier name through the Properties dialog box.

This is all you have to do to create a catalog for your classes. Note that the Gallery is smart enough to attach the proper behavior to your new class item. You can double-click on your class to edit it; you can drag and drop it to the form or class designer to create an instance; you can right-click on the item and open the class in the Class Browser; and much more. As you can see in Figure 7, the Gallery can handle a large number of different items and attaches the right behavior to them. This way, report items can be printed or previewed, video files can be played, tables can be opened, and so forth.

But what if you'd like to add items that the Gallery isn't aware of? A little while ago I wrote a public domain utility called GenRepoX (you can download it for free from www.eps-software.com). It extends the Visual FoxPro Report Writer, but it uses the internal report engine. Reports can be modified in the same way regular Visual FoxPro reports can be modified, but to execute the reports, a special function has to be called. Otherwise, the special features provided by GenRepoX will be lost. The Gallery is aware of reports and allows modifying, printing, and previewing them, but of course it isn't aware of GenRepoX. Luckily, there are ways to teach the Gallery new behaviors.

All Component Gallery behaviors are encapsulated in individual objects. The source code of those classes ships with Visual FoxPro in the _gallery.vcx and vfpglry.vcx class libraries. The behavior you need for GenRepoX is very similar to a regular report behavior, which is defined in the _reportitem class in the vfpglry.vcx library. To reuse what's already there, you can simply subclass this behavior. I chose to call the subclass "GenRepoXItem."

There are two methods we're interested in: Run() and SetMenu(). Those methods do what you think they would. Run() executes the item, and SetMenu() creates the right-click menu. Our major modification will be making the Run() method aware of GenRepoX, which can be done like so:

I basically overwrite all of the default behavior and replace it with my own, which is rather simple in this case, since all I do is execute the report in preview mode. In the second line, I create a command that executes the report. Note that the cFileName property tells us what report filename the item is linked to (once it's used in a catalog). In line 3, I execute the report by running it through the GenRepoX() method.

This is enough to make the new item work. However, I'd also like to give the user a little visual clue that the item at hand isn't a standard report, so I decided to modify the menu. The SetMenu() method is responsible for displaying the menu. Each behavior provided by the Gallery has default menu items. Some of those items are defined in each behavior, others (such as Cut, Copy, and Properties) are provided by the parent class used for all items, named "_item." In our scenario, I'd like all of the default items, but I don't want report-specific items, since I want to introduce my own. In do this in the following fashion:

In line 3, I execute the item defined in the _item class. Note that I specifically name the class rather than issuing a DoDefault(), because I intend to skip the behavior defined in the direct parent class, which is the report item.

In the next line, I add a new menu item using the AddMenuBar() method, which exists on every Gallery item. Parameter one specifies the caption, and parameter two specifies the method that's to be executed when the item is selected. In this case, I simply execute the Modify() method, which I inherited from the standard report item. Note the special "oTHIS…" syntax. oTHIS is a special pointer that allows me to access the current object. The SetMenu() method is called by a Gallery internal mechanism, so by the time the menu is actually displayed, my object isn't accessible through the THIS pointer anymore, which is the reason for this special naming convention used by the Gallery.

The last parameter is interesting, too. From within an item, "THIS.oHost" always links you to an instance of the Gallery itself. The Gallery has a property named "lRunFileDefault" that tells you whether the Gallery is configured to run items whey they're double-clicked (.T.) or modify them (.F.). In the menu, I'll print the default item in bold as required by the Windows interface guidelines. I specify this using the last parameter. So if lRunDefaultFile is set to .F., I pass a .T. as the parameter, and vice versa.

I'm sure you can now figure out the last line by yourself. It simply displays another menu item labeled "Preview GenRepoX," and it executes the Run() method (the one I coded earlier) when selected.

Now all that's left to do is tell the Gallery about the new item type. I do that in the Properties dialog box of the main catalog item (see Figure 8).

From now on, the new item shows up in the New Item menu (see Figure 9).

Once you've added a GenRepoX report item, you can right-click it to see and use the behavior you added. Note that the item also exhibits default behavior that makes a lot of sense for our use. The icon defaults to a report, for instance (see Figure 10). In addition, the item uses the custom menu and behavior. You can use the right-click menu or double-click the item to execute the GenRepoX report.

The options outlined in this article only represent a small example of what's possible with custom items. The possibilities are truly endless. You can find more information about this subject on the Microsoft Visual FoxPro Web site (https://msdn.Microsoft.com/vfoxpro), as well as in the documentation and in several books (such as my own <s>).

So far, so good. The new catalog is coming along nicely. But what if a user I've provided this catalog to has questions? Perhaps I should provide a link to my Web site. I can do this easily by adding a dynamic folder to my catalog. I add the folder just like any other folder, but this time, I set the folder's "Dynamic folder" property (in the Node page of the folder's Properties dialog box) to www.eps-software.com. That's all there is to it!

Conclusion

The Component Gallery is a very powerful tool. Unfortunately, there have been very few products and projects that make use of it. Partly, this appears to be due to the poor documentation, but it's also due to the not terribly obvious advantages the tool provides. However, once you've started using the Gallery, you'll have a hard time living without it.

If you have questions regarding the Gallery's use, custom catalogs, and even AddIns (a possibility I couldn't discuss in this article), feel free to e-mail me at Markus@eps-software.com.

To find out more about FoxTalk and Pinnacle Publishing, visit their website at http://www.pinpub.com/html/main.isx?sub=57

Note: This is not a Microsoft Corporation website. Microsoft is not responsible for its content.

This article is reproduced from the April 2001 issue of FoxTalk. Copyright 2001, by Pinnacle Publishing, Inc., unless otherwise noted. All rights are reserved. FoxTalk is an independently produced publication of Pinnacle Publishing, Inc. No part of this article may be used or reproduced in any fashion (except in brief quotations used in critical articles and reviews) without prior consent of Pinnacle Publishing, Inc. To contact Pinnacle Publishing, Inc., please call 1-800-493-4867 x4209.

© Microsoft Corporation. All rights reserved.