5.2 The Class Browser

The Class Browser

The Class Browser is my favorite tool that ships with Visual FoxPro. In fact, I like it so much that I use it more often than the Visual FoxPro command window.

The Visual FoxPro Class Browser is used to manage visual classes and visual class libraries. One of the few things it cannot do is handle source code classes stored in PRG files. It is written entirely in native Visual FoxPro code and therefore, once instantiated, it is a regular FoxPro object sitting in memory. Many of the Class Browser objects' internals are exposed and can be easily manipulated, customized, extended and automated. This ensures that the Class Browser can fulfill the needs of every programmer.

Basic functionality

Figure 1 shows the new Visual FoxPro 6.0 Class Browser. The look and feel has changed slightly from Visual FoxPro 5.0. The new browser looks cleaner, more colorful, and overall more modern. The top portion of the window contains the toolbar, which has a reduced number of items to make the browser easier and more efficient to use. In return, the shortcut menu now contains more items. I'll discuss some of these items (that are not documented in depth elsewhere) in more detail shortly.

The two main panels of the browser show the classes (typically in hierarchical mode so you can see the inheritance structure) and all their properties, methods and other details. At the bottom you see some additional information about the class in plain English, or some comments you've added to your class.

The main area of the Class Browser is a lot more flexible and informative now. It has slider bars so you can resize each panel, and the right-hand panel has some nice icons to indicate the type and visibility of each property, method or member object. Until now, some cryptic special characters that came straight out of the VCX file (see below) indicated these details. Now, the Class Browser uses standard Visual Studio icons for properties and methods.

By default, the Class Browser displays only properties and methods that are exposed, and methods that have some code attached. I prefer to see some more information, like new defined methods that are still empty, or protected and hidden properties and methods. The shortcut (right-click) menu allows you to display this information. One nice feature of the Class Browser is that it remembers all the settings and other things you change, so you only need to activate the protected and hidden properties and methods once. The browser stores all this information in Browser.dbf. As you'll see later, you can also use this DBF for your own needs.

Most of the items in the Class Browser toolbar are well documented in the online help and in the regular documentation. However, almost every single button holds a little secret that I'd like to share with you. I'll do this in a logical order rather than going through the toolbar from left to right. Figure 2 shows the toolbar and a short description of its important items. Take note that not every button holds special features. In this case I won't discuss them. The Visual FoxPro documentation does a nice job explaining them.

Figure 1. The new Visual FoxPro 6.0 Class Browser.

 

Figure 2. The Class Browser toolbar.

Opening libraries

Opening class libraries is the most trivial and most common task you will perform. When you start the Class Browser, it opens modeless and without any content. This is different from what used to happen in Visual FoxPro 5.0, where the browser always asked for a library on startup. This behavior became inappropriate for reasons you'll discover shortly.

The browser can open a variety of different files, starting (of course) with visual class libraries. It can also handle forms, since their structure is identical to the VCX structure. In addition, you can browse applications, type libraries, ActiveX controls and even DLL files.

The browser has two different buttons to open libraries. The first one (from left to right) is used to open libraries exclusively. This means that all opened libraries will be closed before a new one is opened. The second button opens an additional library and leaves the one that's already there so you can view the contents of multiple libraries at once. This is very useful, especially since inheritance typically spans multiple class libraries.

So far, everything has been quite intuitive, but there's more! You can also right-click on both open buttons to see a list of the most recently used class libraries. The number of items in this list seems to grow with every (service) release of Visual FoxPro. In my current version I counted 32 items. It makes sense to keep a long list of recently used libraries because programmers modify many libraries during a typical project. This list of 32 items should be long enough to hold all the libraries you normally use, and it's the quickest way to open a class library. Now you also know why the browser doesn't ask for a library on startup anymore. It's simply quicker to select one from the right-click menu.

There is one more way to open a class library, which I use quite frequently. Often I need to look at a class whose parent class is stored in another class library (indicated by a little chevron as displayed in Figure 3). If this library isn't open, I can't see the class. I could click the Open button and select the library where the class is stored. But to do so I'd have to know the name and the location of the library, which is hard to remember in large projects. But there's an easier way to get to that library. Simply right-click on the class and choose "Select parent class." The browser will open the correct library and set the focus on the parent class of the previously selected class.

Figure 3. The class cbizpicklist has a parent class that's stored in a different library, which is indicated by the leading chevron.

Renaming items

The Class Browser allows you to rename classes as well as properties and methods. The ability to rename properties and methods is a rather unique feature. To do so, simply select the item you want to rename, and either press the Rename button or select Rename from the right-click menu.

Renaming items is an important but dangerous feature. If you rename a class, you could break inheritance structures forever. Let's say you rename a class that has a subclass in another class library. The subclass refers to its parent class only by name. So if that name changes, the subclass loses its parent and cannot be instantiated or modified. If this happens, you have to rename the parent class back to the original name. However, this can be tricky! You might have new subclasses that rely on the new name. Or maybe you renamed the class because the name was mistyped. In this case it might be hard to remember the original name. The only way out of this situation is to redefine (see below) the now broken subclass, if the browser can even open and display the class library.

The Class Browser has continually been improved to find subclasses that can be influenced by a renamed class. In the latest version, it is fairly safe to rename a class if all subclasses from different libraries are opened at the same time. In this case, the browser iterates through all involved classes and updates the relation. Unfortunately, this doesn't work with source code. For this reason it's very dangerous to rename methods and properties. All source code references to these items will be broken after renaming them. For instance, if you refer to MyFavoriteMethod() in your Init() code and you change the name of the method to MyMostFavoriteMethod, your code will error out. You can use Visual FoxPro's Find feature to locate references in code and make the changes there.

Redefining classes

To "redefine a class" means to change the class's parent class, which is easy to do in source code. Simply go to the class definition and change the AS clause. With visual classes, however, this is a whole different story. The Class Browser is basically the only tool that can redefine these classes.

Redefining classes is useful for many different reasons. You might want to add one more layer of subclassing to your inheritance structure. If you have Class A and a subclass of it called Class B, you could simply add a layer in between by creating another subclass of Class A called Class C, and by redefining Class B to be a child of Class C. Or you might have a bug in your structure or a misconception in your design. In all these cases, redefining classes can be very helpful. You can also redefine forms. If you want to create a Visual FoxPro form of a certain class, you can either specify the class in the Options dialog or add an additional clause in the CREATE FORM command. Both methods are rather cumbersome, so I prefer to create a default form later on, I'll open it in the Class Browser and redefine it. Not really straightforward, but at least better than the other methods.

Unfortunately, redefining classes is very dangerous. To explain why, I'll walk you through a small sample. Let's say we created a MovieTheater class for our movie theater example that I use throughout the book. It is a subclass of the abstract class Theater. In this class we have a method called Perform(). This method is empty, but we have several hundred lines of code in this method of the MovieTheater class. Now we decide to redefine this class to be a subclass of our generic Screen class. This class doesn't have a Perform() method. The next time we open our MovieTheater class, FoxPro checks its internal list of all defined methods and properties, and figures that no Perform() method is supposed to be in this class. For this reason FoxPro assumes that the code is outdated, and removes the whole method permanently from our class. Not exactly the results we expected!

In Visual FoxPro 6.0, the Redefine feature is a lot easier to use than in previous versions. You now get a nice dialog (see Figure 4) that allows you to pick a class rather than to enter the class name and its location manually. It also allows redefining directly to the class's base class and even switching to another base class. I'll discuss this feature in more detail later.

Figure 4. The new Redefine dialog allows you to choose different base classes. Using its Browse ( ) button, you can navigate to the regular class selection dialog, rather than having to remember the class name.

Switching to different base classes

Different Visual FoxPro base classes can be very similar Custom and Container classes, for instance, or TextBoxes and EditBoxes. In fact, sometimes I wish these classes would be the same with just a couple of additional properties like a ScrollBars property for TextBoxes or a Visible property for Custom classes. But because they are different I often need to change to an entirely different base class. Let's say you change a field in your database from a regular text field to a memo. You now have to change all classes that refer to this field from TextBoxes to EditBoxes. Or maybe you've based a lot of invisible composite classes on the base class Custom. This is perfectly fine until you want one part of this class to be visible. Now you really need a Container.

Obviously, only a handful of base classes are interchangeable. Redefining a Grid to be a Line or vice versa wouldn't be a great idea. The Class Browser only allows you to redefine classes to which it can securely convert. But you still need to be careful with this feature. It's powerful but it needs an experienced programmer to be tamed.

To change to a different base class, you can either pick a different base class directly from the drop-down list, or you can select another user-defined class from the class selection dialog. In this case you have even more flexibility because you can basically redefine to every base class you want. The Class Browser gives only a sloppy warning message indicating the possible problems you could get yourself into. So be aware of the fact that you carry all responsibility for this operation! I recommend trying such operations on backup copies of your class libraries so you can easily recover older versions in the event of a problem.

Cleaning up class libraries

Visual class libraries tend to grow extremely large. When you modify a class and save it, Visual FoxPro deletes the old copy of the class and appends a new one at the end of the VCX file. This is due to the structure of the VCX file and the way classes are stored. When a class is modified, even small changes can cause major rearrangements in the class library. For this reason, it is safer to append a new copy at the end of the file. The old copy remains there, marked as deleted. (See below for more information about the structure of the VCX file and how classes are stored.) If you create a large composite class and modify it 10 times (even if changes are minor), the VCX becomes 10 times larger than necessary. Even very small class libraries can end up being several megabytes in size because of all the "hot air" they contain.

The clean-up feature of the Class Browser is a great way to remove all outdated copies of your classes. All you have to do is open a library, click the Clean-up button and the browser will take care of the rest. It amazes me every time I use this feature. It is not unusual for several-megabyte class libraries to shrink to a handy 50 or 100 KB.

The class icon

The class icon is probably the most overlooked element of the Class Browser. At the same time, it has more hidden functionality than any other item in the toolbar. Let's start by examining one of its simpler features.

Changing the icon

When you right-click on the Class Browser icon, the File Selection dialog appears so you can select a new image file. The image file will then be used in the Class Browser as well as in the Form Controls toolbar, instead of the standard icon for each individual base class. You can right-click again to switch to another icon. If you press Cancel in the File Selection dialog, the browser asks whether you want to cancel only the current operation, or if you want to revert to the standard icon for the base class of the selected class. This is almost like a two-step undo. It is the only way to revert to the default icon.

Drag and Drop

The main reason why the class icon is so important is its drag-and-drop functionality. I'm still not certain whether I have discovered all the different options, but I will try to give you a good overview of the possibilities.

The standard drag-and-drop action is to drag the icon and drop it on the Visual FoxPro screen. In this case, the Class Browser creates an instance of the class you dropped. If you dropped a form class on the screen, the class will be created using NewObject(). You can also see the instance in the right-hand panel of the Class Browser as shown in Figure 5. If the dropped class needs a hosting container (such as a command button), the class will be instantiated inside the Visual FoxPro screen using AddObject(). Such an object is not a stand-alone object and cannot be detected by the Class Browser. For this reason, it will not show up as an instance in the details panel. This is sometimes well confusing.

When you drag and drop to the screen, the Class Browser ignores all errors that occur during instantiation. All later errors that occur when you use this object will still be fired. The fact that the errors are ignored is important for bench testing. ("Bench testing" is a technique that allows testing single components without instantiating and invoking the entire system. This also includes ignoring certain errors and dependencies.) Typically, all your classes will be part of a larger object system, and therefore will depend on other objects during construction. For this reason, many errors can occur when instantiating the class. But those errors might not be relevant at that time because you might want to test something totally different.

On the other hand, this behavior can also hide bugs. Very often I create a class, test it directly from the Class Browser, and later on I discover some problems during instantiation that were hidden by the browser. Fortunately, you can tell the browser not to ignore errors. Simply press the Ctrl key while dragging and dropping.

Often it is interesting to know what the browser actually does when you instantiate a class by dragging and dropping. You can see the appropriate code when you drag and drop to the command window. In this case, the code will be placed in the command queue and will be executed right away. Usually it is your responsibility to make the new instance visible by either setting the Visible property or calling the Show() method.

Figure 5. The Class Browser and the form we instantiated by dragging and dropping. The new instance is also listed in the details (right-hand) panel of the browser.

You can drag and drop not only on Visual FoxPro desktop standard objects, such as the screen or the command window, but also to any kind of existing container object in memory. If you have a form, for instance, you can simply add a button to it by dropping a button class on the form. Keep in mind that even objects you modify are "alive" and fully functional. So if you edit a form, you can drag and drop classes from the Class Browser onto it, because there is no difference between a final instance and a class or form that is being modified. When you drop on a modified class, the Class Browser acts as a builder that replaces the Form Controls toolbar. I prefer to use the browser over the toolbar because it is a lot easier to find classes in the browser. Also, you can start multiple instances of the browser or open multiple libraries in one browser window.

A word about multiple instances: If you are running multiple instances of the browser, you can drag and drop from one instance to another. By default, the browser moves a class from the library displayed in one browser to the library displayed in another. When doing so, the Class Browser also redefines all dependencies and inheritance structures in all class libraries that are opened in both instances. It's important to maintain a working inheritance structure because moving the class influences all its subclasses.

Again, you can press the Ctrl key during the drag-and-drop operation, and the Class Browser will copy the class instead of moving it. Usually this is the safer choice, but you have to come back and clean up afterwards (unless the class libraries involved in the drag-and-drop operation belong to entirely different projects).

Creating source code

When I first started using Visual FoxPro and visual classes as well as forms, it bothered me that I could never see the entire source code in one piece. In FoxPro 2.x, I created screens and generated source code, and I could then read the code and learn from it. In Visual FoxPro this capability was lost. Or was it? Actually, it wasn't! The Class Browser can create source code for all visual classes and forms.

To view the code for a specific class, select the class in the browser and click the View Class Code button. The browser creates a file called Viewcode.prg, which shows the exact code for your class. There are some limitations, though. Subclassed ActiveX controls, for instance, don't show much information when viewed in source code. But overall, this feature is quite useful. You can also create code for an entire class library. To do so, select the library (at the very top of the list) instead of a specific class.

A new feature was added to the browser in Visual FoxPro 6.0. If you right-click on the View Class Code button, you get a view of the class code that looks almost the same as the created PRG file. But if you take a closer look, you will discover that you're looking at an HTML file displayed using Internet Explorer within Visual FoxPro. It also includes some syntax coloring, although it is not as complete as Visual FoxPro's internal syntax coloring. The HTML preview is useful for anyone who wants to publish source code in technical articles, or also for documentation purposes. To save the created HTML, simply right-click on the code window, select "View Source," and save the file under a name of your choice.

Different ways to start the Class Browser

The easiest way to start the Class Browser is to select it from the Tools menu. However, there are other ways as well for instance, you can use the "_Browser" system variable:

DO (_BROWSER)

This is especially useful if you want to pass parameters to the browser. The Class Browser is very flexible when it comes to receiving parameters. One possibility is to pass a numeric parameter:

DO (_BROWSER) WITH 0

When you pass 0, the Class Browser installs itself in the menu if it isn't already there. It seems that this has been accepted as a standard throughout the FoxPro world. Many tools do the same if called with 0 as the first parameter.

However, the first parameter can also be of type character. In this case, the browser expects the name of the class library to open on startup. Optionally, you can pass a second parameter, which is the name of the initially selected class and member, separated by a period:

DO (_BROWSER) WITH "SAMPLES\VFP98\CLASSES\BUTTONS.VCX","vcr.recordpointermoved"

This will open one of the sample classes that ships with Visual FoxPro and will select the vcr class and one of its methods, called recordpointermoved. Typically you wouldn't specify all of this just to open a class, but many tools that use the Class Browser use this syntax.

When you start the Class Browser from the Tools menu, it first looks at the current environment. If you are currently modifying a class, the browser will open with this exact class selected.

Usually, I start the browser without any classes opened by default. I then right-click the Open button and select the class library I want to work on. However, if you always work on the same class, you can also specify this as your default file. To do so, open the desired class library and call the SetDefaultFile() method of the browser like so:

_oBrowser.SetDefaultFile()

_oBrowser is a reference to the currently active Class Browser instance. (See below for more details.) The SetDefaultFile() method registers your current library as the default library. If you want to register more than one library, open another one and call the method again, with.T. as a parameter. To remove a library from the list of default libraries, use the ResetDefaultFile() method the same way you use the SetDefaultFile() method.