Partager via

Guidelines for Using Visual FoxPro Foundation Classes

  • Article

The Visual FoxPro visual class (.vcx) libraries located in the Visual FoxPro ...\FFC directory contain a variety of foundation classes for enhancing your Visual FoxPro applications with little or no programming. You can freely distribute the foundation classes with your applications.

You can browse these foundation classes in the Component Gallery. The Component Gallery provides a quick and easy way to learn more about the properties, events, and methods of each of the foundation classes. For more information about the Component Gallery, see Using the Component Gallery.

You can also open a foundation class in the Class Designer or Class Browser to see its structure and code. This is a great way to learn how the foundation class works as well as offering excellent insights into programming with Visual FoxPro.

The following guidelines provide information about how you can add the Visual FoxPro foundation classes to your applications.

Class Types

Before you can add a foundation class to your application, you need to know the Visual FoxPro base class of the foundation class.

Tip

To see the base class from the Component Gallery, right-click the foundation class in the Component Gallery, click Properties on the shortcut menu, then the Class Item tab. The base class name appears in the Class name box.

Certain foundation classes can be used only as visual objects on forms, while others are non-visual and can be run programmatically without being placed on a form. To determine if the foundation class can be added to a form or run programmatically in your application, see Visual FoxPro Foundation Classes A-Z, which contains Help topics for each foundation class that indicate the base class for each foundation class.

The following table lists Visual FoxPro base classes and how they can be added to your applications.

Category A – base classes that can be dropped onto a form

Category B – base classes that can be dropped onto a form or run programmatically in your application

Category C – base classes that can only be run programmatically in your application

Checkbox

Custom

Form

Combobox

Container

Formset

Commandbutton

Timer

Toolbar

Commandgroup

ProjectHook

 

Editbox

 

 

Grid

 

 

Hyperlink

 

 

Image

 

 

Label

 

 

Line

 

 

Listbox

 

 

OLE Control

 

 

Optionbutton

 

 

Optiongroup

 

 

Shape

 

 

Spinner

 

 

Textbox

 

 

Adding Foundation Classes to Forms

You will most often add foundation classes to forms. You can drag and drop foundation classes from the Component Gallery, Class Browser, Project Manager, and the Forms Control toolbar onto forms.

Note

You can select a foundation class that you have added to a form and then choose Class Browser from the Tools menu to display more information about the foundation class.

Component Gallery   The Component Gallery provides the easiest way to add foundation classes to a form. For foundation classes with Category A and B base classes, you can drag the foundation class from the Component Gallery and then drop it on a form. You can also right-click a foundation class in the Component Gallery to display a shortcut menu, and then choose Add to Form to add the foundation class to the form.

Some of the foundation classes have associated builders that are automatically launched to prompt you for more information needed by the foundation class.

Class Browser   You can drag foundation classes with Category A and B base classes directly from the Class Browser to a form by using the drag icon in the upper left corner of the Class Browser. Select the foundation class in the Class Browser, click the icon for the foundation class in the upper left corner of the Class Browser, and then drag the icon over the form. Release the mouse button over the form where you would like the foundation class to appear on the form.

Foundation classes dragged from the Class Browser to a form do not launch the associated builder. However, you can launch the builder by after the foundation class has been dropped on the form. Select the foundation class on the form, and then right-click to display the shortcut menu. Choose Builder from the shortcut menu to launch the builder.

Project Manager   Foundation classes with Category A and B base classes can be dragged from the Project Manager and dropped on a form.

Foundation classes dragged from the Project Manager to a form do not launch the associated builder. However, you can launch the builder by after the foundation class has been dropped on the form. Select the foundation class, and then right-click to display the shortcut menu. Choose Builder from the shortcut menu to launch the builder.

Form Controls toolbar   Foundation classes with Category A and B base classes added to the Form Controls toolbar can be added to a form.

If the Builder Lock is not on, foundation classes dropped from the Form Controls toolbar may launch an associated builder. If the Build Lock is on, you can launch the builder by after the foundation class has been added to the form. Select the foundation class on the form, and then right-click to display the shortcut menu. Choose Builder from the shortcut menu to launch the builder.

Adding Foundation Classes to Projects

When a form containing foundation classes is added to a Visual FoxPro project, the Project Manager automatically adds the visual class libraries containing the foundation classes to the project. However, there are other cases where you may need to add foundation classes to a project. For example, your application may run a Category C foundation class, so the foundation class must be added to the application's project.

Foundation classes can be added to a project from the Component Gallery, by dragging the .vcx visual class library containing the foundation classes from the Windows Explorer, or by choosing the Add button in the Project Manager.

You can drag a foundation class from the Component Gallery to a project, or you can right-click the foundation class in the Component Gallery to display a shortcut menu, and then choose Add to Project to add the foundation class to the project. When you add a foundation class to a project, the Add Class to Project dialog box is displayed, prompting you with the following options:

  • Add class to project
    Choose this option to add the foundation class and its .vcx class library to the project. Again, this is done automatically for classes dropped onto a form (Categories A and B). For certain Category B and C classes where you plan to call them programmatically from within your application, you will want to choose this option.

  • Create a new class from selected class
    Choose this option to create a new subclass from the foundation class you want to add to the project. This option makes it possible for you to enhance the functionality of the original foundation class, usually by adding additional program code.

  • Create a new form from selected class
    Choose this option for foundation classes with a Form base class (for example, the foundation classes in _dialogs.vcx). This option makes it possible for you to create a new form from the foundation class and enhance the functionality of the original foundation class.

Adding Foundation Classes from the Windows Explorer

A foundation class can be added to a project by dragging the .vcx visual class library containing the foundation class from the Window Explorer to the Project Manager. The visual class library is added to the Class Libraries item in the Project Manager.

Adding Foundation Classes from within the Project Manager

A foundation class can be added to a project by selecting the Classes tab and then choosing the Add button. Select the class library from the \Ffc\ folder that contains the foundation class to add to the project.

Incorporating Classes into your Application

In many situations, most foundation classes do not require additional programming to work with your application. However, you may need to provide additional program code for certain foundation classes (those of Category B and Category C non-visual base classes).

Non-Visual Foundation Classes

For example, foundation classes are often based on the Category B Custom class, and these require additional programming. These non-visual classes often perform common tasks such as checking information in the Windows registry, handling environment settings, managing application errors, and utilizing Automation with other applications, such as performing mail merge with Microsoft Word.

You can drop these non-visual classes onto a form, but you will need to do some additional work in order for them to work with your application. In some cases, a builder is launched when you drag a foundation class onto a form.

The following example demonstrates some of the program code typically necessary to use a non-visual foundation class in your application:

  1. Drag the File Version foundation class from the Component Gallery (Foundation Classes\Utilities folder) onto a form.

  2. Add a command button to the form and add the following code to its Click event:

    WITH THISFORM._FILEVERSION1
   .cFileName = HOME( )+ 'VFP8.EXE'
   .GetVersion( )
   .DisplayVersion( )
ENDWITH

  3. Run the form and click the command button.

You can incorporate a non-visual class in your application without dropping it on a form, as long as you include it in the project used to create the application. The following code illustrates how to executed this same File Version foundation class if the class is not dropped onto a form.

LOCAL oFileVersion
oFileVersion = NewObject('_fileversion', '_utilities.vcx')
WITH oFileVersion
   .cFileName = HOME( )+ 'VFP8.EXE'
   .GetVersion( )
   .DisplayVersion( )
ENDWITH

Note

This example assumes that the code can locate the _utilities.vcx class library or from an .app file that is built containing _utilities.vcx.

When you use a non-visual foundation class, you need to know how and when the class is used within your application so it can be scoped correctly. If only a single form uses the class, you can just drag the class onto the form. However, if the class is used by many forms or is used globally by the application, the foundation class should have a global scope in the application so it remains accessible throughout the application. A global scope may also improve performance.

Adding Visual Foundation Classes to Applications

You can programmatically add visual foundation classes, such as those containing form base classes, to your application. For example, you can use the following code to display an About dialog box:

LOCAL oAbout
oAbout = NewObject('_aboutbox','_dialogs.vcx')
oAbout.Show( )

To customize the contents of the About dialog box for each application, create a subclass of the About Dialog Box foundation class for each of your applications:

  1. Open the project for your application.

  2. On the Tools menu, click Component Gallery.

  3. In the Component Gallery, expand the Visual FoxPro Catalog node, then the Foundation Classes node, and click Dialogs.

  4. Drag the Aboutbox class to the Project Manager for your application.

  5. In the Add Class to Project dialog box, click Create new form from selected class.

  6. In the Save As dialog box, enter a name for the new form.

    After saving the form, the Form Designer opens and displays the newly created form.

  7. In the Properties window, change the Caption property for the title of the new form for your application. Save and close the form.

  8. Add program code, such as DO FORM FormName, to the procedure that runs the form, such as an About menu item procedure.

    -or-

    From the Foundation Classes\Buttons folder in the Component Gallery, drag the Run Form button class onto the form. A builder launches so you can specify the name of the form to execute.

If you use the Visual FoxPro Application Framework, the Application Builder automatically handles adding forms (both .scx and .vcx form classes). The new Application Wizard or the Component Gallery New Application item installs this framework in the projects they create. The Application Builder interacts directly with the framework and enables you to specify how and where the form is launched.

By using a framework built with the Application Wizard, the Application Builder, and Component Gallery, you have a rich set of tools for creating entire applications with minimal manual coding.

Class Naming Conventions

The Visual FoxPro Foundation classes and their properties and methods use the following naming conventions.

Classes and Class Libraries

Most foundation classes are subclassed from classes in the _base.vcx visual class library, which you can also find in the \Ffc\ folder. The naming conventions for these classes reflect the base class used. For example, a subclass of the Custom class is called *_*Custom in _base.vcx. All classes use an underscore ( _ ) to preface the name of a class in _base.vcx.

A few class libraries do not contain classes that are subclassed from _base.vcx because these classes are shared with other Visual FoxPro components such as wizards and builders. These classes are contained in class libraries without a preceding underscore, such as Registry.vcx.

Methods and Properties

Methods are often based on an action name such as RunForm. If the name contains several words, for example, RunForm, then capitalization reflects this. Properties are usually prefaced with a single letter characterizing the data type of that particular property. For example, cFileName indicates that the property is of character type. In addition, default values for properties are also set to the appropriate data type. For example, a logical property can be initialized to false (.F.), while a numeric property can be initialized to 0.

Properties of classes that shipped in earlier versions of Visual FoxPro do not strictly adhere to these property-naming conventions, and retain their earlier names to avoid compatibility conflicts with user code referencing these properties.

Enhancing or Modifying FoxPro Foundation Classes

You can enhance or modify the Visual FoxPro foundation classes to meet the needs of your application. However, we recommend that you do not modify the foundation classes themselves. The foundation classes may be periodically updated with new functionality.

Subclassing the Foundation Class

The source code is provided for the foundation classes, so you can subclass any foundation class to override or enhance properties and methods. This choice is common when the behavior of a particular foundation class varies between different applications. One application might use a foundation class directly, while another application uses a subclass of the foundation class.

Updating _base.vcx

If you want to add global changes to the Visual FoxPro foundation classes, you can modify _base.vcx. Since foundation classes are subclassed from _base.vcx, changes to this class library are automatically propagated to the foundation classes. A common set of methods and properties are provided for all the classes in _base.vcx. However, you can alter the classes in _base.vcx if they add desired behavior to your applications (unlike the foundation classes that we recommend that you do not change).

Instead of changing _base.vcx, however, you should redefine the classes in _base.vcx to inherit their behavior from your own custom base classes (rather than from the Visual FoxPro base classes currently used). If you already have a custom class library which subclasses the Visual FoxPro base classes, you can redefine the classes in _base.vcx to inherit from your custom classes so that when components use the _base classes they will inherit from your custom classes too. You can use the Class Browser to redefine the parent class for a particular class.

Note

If you redefine the classes to inherit from your own custom base classes, you should add DODEFAULT() calls at appropriate locations if you desire that parent class method code be executed.

If you replace the entire _base.vcx class with your own, make sure that you have the same set of named classes; otherwise the foundation classes will have missing links.

See Also

Reference

Visual FoxPro Foundation Classes A-Z

File Version Foundation Class

About Dialog Box Foundation Class

Run Form Button Foundation Class

Other Resources

Foundation Class Samples