Customizing Visual FoxPro 6.0 Application Framework Components 

 

Lisa Slater Nicholls

October 1998

Summary: Describes how the Microsoft® Visual FoxPro® version 6.0 Application Framework, including the Application Wizard and Application Builder, can be used by the beginning developer to turn out polished applications and customized by the more experienced developer to create more detailed applications. (32 printed pages)

Contents

Overview Examining Framework Components Designating the Classes You Want Specifying Your Own Framework Components A Closer Look at the Standard Application Wizard A New Application Wizard A Few Parting Thoughts about Team Practices Appendix 1 Appendix 2 Appendix 3 Appendix 4

Click to copy the appfrmwk sample application discussed in this article.

Overview

The Visual FoxPro 6.0 Application Framework offers a rapid development path for people with little experience in Visual FoxPro. With a few simple choices in the Application Wizard and the Application Builder, beginning developers can turn out polished and practical applications.

Under the hood, however, the framework offers experienced developers and teams much more. This article shows you how to adapt the framework components so they fit your established Visual FoxPro requirements and practices.

In the first section of this article you'll learn about the files and components that support the framework and how they work together while you develop an application. This information is critical to moving beyond simply generating framework applications to experimenting with framework enhancements.

The second section teaches you how to apply your experiences with the framework to multiple applications. After you've experimented with framework enhancements for a while, you will want to integrate your changes with the framework, for standard use by your development team. By customizing the files the Application Wizard uses to generate your application, you'll make your revisions accessible to team members—without sacrificing the framework's characteristic ease of use.

Examining Framework Components

This section shows where the framework gets its features and components, and how these application elements are automatically adjusted during your development process.

Once you see how and where framework information is stored, you can begin to try different variations by editing the versions generated for a framework application. When you're satisfied with your changes, you can use the techniques in the next section to migrate them to your team's versions of the framework components.

Note   Like most Visual FoxPro application development systems, the framework is composed of both object-oriented programming (OOP) class components and non-OOP files. This distinction is important because you adapt these two types of components in different ways; classes can be subclassed, while non-OOP files must be included as is or copied and pasted to get new versions for each application. The framework is minimally dependent on non-OOP files, as you'll see here, but these files still exist.

Throughout this article we'll refer to the non-OOP framework files as templates, to distinguish these components from true classes.

Framework Classes

The Visual FoxPro 6.0 framework classes are of two types:

1. Framework-specific classes. These classes have been written especially for the application framework and provide functionality specific to the framework. The standard versions of these classes are in the HOME( )+ Wizards folder, in the _FRAMEWK.VCX class library.
2. Generic components. These features come from class libraries in the HOME( )+ FFC (Visual FoxPro Foundation Classes) folder.

_FRAMEWK.VCX

The _FRAMEWK.VCX class library (see Figure 1) contains all the classes written specifically to support the framework. Each framework application you create has an application-specific VCX containing subclasses of the _FRAMEWK.VCX components. The Application Wizard puts these subclasses in a class library named <Your projectname> plus a suffix to designate this library as one of the wizard-generated files. To distinguish these generated, empty subclasses, it adds a special prefix to the class names as well.

Figure 1. _FRAMEWK.VCX framework-specific class library, as viewed in Class Browser, is found in the HOME( )+ Wizards folder.

Framework superclass: _Application

The _Application class is a required ancestor class, which means that this class or a subclass of this class is always required by the framework. This class provides application-wide manager services. For example, it manages a collection of modeless forms the user has opened.

You designate a subclass of _Application simply by using CREATEOBJECT( ) or NEWOBJECT( ) to instantiate the subclass of your choice. (By default, the framework provides a main program to do this, but this PRG contains no required code.) When your designated _Application subclass has instantiated successfully, you call this object's Show( ) method to start running the application.

Note   In this article, we'll refer to the object you instantiate from a subclass of _Application as the application object. We'll continue to refer to "your subclass of _Application" to mean the class definition instantiating this object, which will be in a VCX belonging to your application (not _FRAMEWK.VCX). You'll also see references to "_Application", that refer specifically to code and properties you'll find in the superclass located in _FRAMEWK.VCX.

At run time, the application object instantiates other objects as necessary to fill all the roles represented by the other classes in _FRAMEWK.VCX except _Splash. The framework identifies these roles as important to various application functions, but, as you'll see in this section, you have full control over how the roles are carried out.

Note   The _Splash class is an anomaly in _FRAMEWK.VCX; it isn't instantiated or used by the framework application directly. (If it were instantiated by the application object, your splash screen would appear too late to be useful.) Instead, _Splash merely provides a default splash screen with some of the same attributes as _Application (for example, your application name and copyright). The Application Builder transfers these attributes to your application's subclass of _Splash at the same time it gives them to your application's subclass of _Application, so they stay synchronized. The default main program delivered with a framework gives you one way to instantiate this splash screen before you instantiate your application object.

You certainly don't need to use the method shown in the default main program for your splash screen. In fact, many applications do not need a splash screen at all. For those that do, you may prefer to use the Visual FoxPro –b<file name> command-line switch, which displays a bitmap of your choice during startup, rather than a Visual FoxPro form of any description.

Framework superclass: _FormMediator

You'll grasp most of the "roles" played by the subsidiary classes in _FRAMEWK.VCX easily, by reading their class names and descriptions. (If you can't read the full class description when you examine _FRAMEWK.VCX classes in a project, try using the Class Browser.) However, you'll notice a _FormMediator class whose purpose takes a little more explaining.

You add an object descended from the _FormMediator custom class to any form or form class, to enable the form to communicate efficiently with the application object. This section will show you several reasons the form might want to use services of the application object. With a mediator, your form classes have access to these services, but the forms themselves remain free of complex framework-referencing code.

The _FormMediator class is low-impact. It doesn't use a lot of resources, and its presence will not prevent your forms from being used outside a framework application. Using this strategy, the framework can manage any forms or form classes your team prefers to use, without expecting them to have any special inheritance or features.

Like _Application, _FormMediator class is a required ancestor class. You can create other mediator classes, as you can subclass _Application to suit your needs, but your mediators must descend from this ancestor.

We'll refer to _FormMediator and its descendents as the mediator object, because (strictly speaking) your forms will see it as the "application mediator" while the application object treats it as a "form mediator."

The Visual FoxPro 6.0 Form Wizards create forms designed to take advantage of mediators when the framework is available. You can see some simple examples of mediator use in the baseform class of HOME( )+ Wizards\WIZBASE.VCX.

Examine _FormMediator's properties and methods, and you'll see that you can do much more with the mediator in your own form classes. For example, the application object calls mediator methods and examines mediator properties during its DoTableOutput( ) method. (This method allows quick output based on tables in the current data session.) Your mediator for a specific form could:

• SELECT a particular alias to be the focus of the output.
• Prepare a query specifically for output purposes (and dispose of it after the output).
• Inform the application object of specific classes and styles to be used by _GENHTML for this form.
• Change the output dialog box caption to suit this form.

The mediator also has methods and properties designed to specify context menus for the use of a particular form. If the application object receives this information from the mediator, it handles the management of this menu (sharing it between forms as necessary).

You'll find one example of mediator use in the ErrorLogViewer class. (This use is described in Appendix 1, which covers the options system.) A full discussion of the _FormMediator class is beyond the scope of this document. The more information you give a mediator or mediator subclass, however, the more fully your forms can use framework's features, without making any significant changes to the forms themselves.

Note   The _Application class includes a property, lEnableFormsAtRuntime (defaulting to .T.), which causes the application object to add mediators at run time to any form not having a mediator of its own. You can specify the mediator subclass that the application adds to a form at run time. Keep in mind, however, that mediators added at design time will have a more complete relationship with their form containers, because these forms can include code referencing their mediator members. During a form's QueryUnload event, for example, the form can use the mediator to determine whether the form contains any unconfirmed changes. Without code in the form's QueryUnload method, the mediator can't intercede at this critical point.

Additional _FRAMEWK.VCX classes

The other classes in _FRAMEWK.VCX are all dialog box and toolbar classes to perform common functions within an application. None of these classes are required ancestors; you can substitute your own user interfaces and class hierarchies for these defaults at will. Two of them (_Dialog and _DocumentPicker) are abstract; that is, they are never instantiated directly, existing only to provide properties and methods to their descendent classes. Others will not instantiate unless you pick specific application characteristics. For example, if you don't write "top form" applications (MDI applications in their own frames) you will never use _TopForm, the _FRAMEWK.VCX class that provides the MDI frame window object.

Once you have examined these classes, and identified their roles, you will know which ones supply the types of services you need in applications you write—and, of these, you will identify the ones you wish to change.

Designating the Classes You Want

For each class role identified by the framework, the application object uses corresponding xxxClass and xxxClassLib properties to determine the classes you want. To change which class is instantiated for each role, you change the contents of these properties in your subclass of _Application.

For example, _Application has cAboutBoxClass and cAboutBoxClassLib properties, and it uses these properties to decide what dialog box to show in its DoAboutBox( ) method (see Figure 2).

Figure 2. Class and ClassLib property pairs in the _Application object

If you fill out a class property but omit the matching Classlib property, _Application assumes that your designated class is in the same library as the _Application subclass you instantiated. If your _Application subclass is in the MyApplication.vcx and cAboutBoxClass has the value "MyAboutBox" but cAboutBoxClassLib is empty, a call to the Application object's DoAboutBox( ) method instantiates a class called MyAboutBox in MyApplication.vcx.

If you call the method instantiating one of the subsidiary classes when the matching class property is empty, _Application attempts to provide appropriate behavior to the specific situation. For example, if the cAboutBoxClass property is empty, DoAboutBox( ) will simply do nothing, because it has no alternative. By contrast, if the cErrorViewerClass property is empty, the _Application DisplayErrorLog( ) method will ask its cusError member object to use its default error log display instead.

Except for the cMediatorClass and cMediatorClassLib properties, which must specify a class descending from _FormMediator in _FRAMEWK.VCX, remember that there are no restrictions on these dialog boxes and toolbars. You don't have to subclass them from the classes in _FRAMEWK.VCX, or even follow their examples, in your own classes fulfilling these framework roles.

Even when you design completely different classes, you will still benefit from investigating the defaults in _FRAMEWK.VCX, to see how they take advantage of their relationship with the framework. For example, all the classes descended from _Dialog have an ApplyAppAttributes( ) method. When the framework instantiates these classes, it checks for the existence of this method. If the ApplyAppAttributes( ) method exists, the application object passes a reference to itself to the form, using this method, before it calls the Show( ) method. In this way, the dialog box can derive any framework-specific information it needs before it becomes visible. For instance, the About Box dialog box might adjust its caption using the _Application.cCaption property.

If the ApplyAppAttributes( ) method does not exist in yourcAboutBoxClass class, no harm is done. The _Application code still tries to harmonize your dialog box with its interface, in a limited way, by checking to see whether you've assigned any custom value to its Icon property. If you haven't, _Application assigns the value in its cIcon property to your dialog box's icon before calling its Show( ) method.

Note   This strategy typifies the framework's general behavior and goals:

• It tries to make the best use of whatever material you include in the application.
• When possible, it does not make restrictive assumptions about the nature of this material.
• It avoids overriding any non-default behavior you may have specified.

Investigating the default _Options dialog box class and _UserLogin default dialog boxes will also give you insight into the _Application options and user systems. While the dialog boxes themselves are not required, you will want to see how they interact with appropriate _Application properties and methods, so your own dialog boxes can take advantage of these framework features. In particular, the _Application options system has certain required elements, detailed in Appendix 1.

FoxPro Foundation Generic Classes

You may be surprised that _FRAMEWK.VCX contains only two required classes (the application and mediator objects), and in fact even when you add the other subsidiary classes, _FRAMEWK.VCX doesn't contain much of the functionality you may expect in a Visual FoxPro application. You will not find code to perform table handling. You won't find dialog boxes filling standard Visual FoxPro roles, such as a dialog box to select report destinations. You won't find extensive error-handling code.

_FRAMEWK.VCX doesn't include this functionality because there is nothing framework-specific about these requirements. Instead, it makes use of several Visual FoxPro Foundation Classes libraries, useful to any framework or application, to perform these generic functions. The _Application superclass contains several members descending from FFC classes, and it instantiates objects from other FFC classes at run time as necessary. Then it wraps these objects, setting some of their properties and adding some specific code and behavior to make these instances of the FFC classes especially useful to the framework.

For example, _Application relies on its cusError member, descended from the _Error object in FFC\_APP.VCX, to do most of its error handling, and to create an error log. However, as mentioned earlier, _Application code displays the error log using a framework-specific dialog box. The application object also sets the name and location of the error log table to match its own needs, rather than accepting _Error's default.

The framework uses four FFC class libraries: _APP.VCX, _TABLE.VCX, _UI.VCX, and _REPORTS.VCX. Figure 3 shows these libraries in Class Browser views, as well as in a Classes tab for a framework application project.

Figure 3. A framework application uses generic Visual FoxPro Foundation Classes, from HOME( )+ FFC folder, to supplement the framework-specific classes in _FRAMEWK.VCX.

Unlike the subsidiary classes in _FRAMEWK.VCX, the FFC classes and their complex attributes are used directly by _Application, so you don't specify alternative classes or class libraries for these objects. You can still specify your own copies of these class libraries, as you'll see in the next section.

If you examine the Project tab in Figure 3, or the project for any framework application, you'll find this list of libraries built in. You'll see _FRAMEWK.VCX, and there will be at least one class library containing the subclasses of _FRAMEWK.VCX for this application.

You'll see one more FFC library: _BASE.VCX, which contains the classes on which _FRAMEWK.VCX and all the FFC libraries are based. Your framework project must have access to a library called _BASE, containing all the classes found in _BASE. However, neither the framework nor the four FFC class libraries it uses require any specific behavior or attributes from these classes. You are free to create an entirely different _BASE.VCX with classes of the same name, perhaps descending from your team's standard base library.

Framework Templates

The framework templates are of three types:

1. Menu templates, a collection of Visual FoxPro menu definition files (.mnx and .mnt extensions)
2. Metatable, an empty copy of the table the framework uses to store information about the documents (forms, reports, and labels) you use in your application
3. Text, a collection of ASCII supporting files

Unlike the .vcx files used by the framework, Visual FoxPro doesn't deliver separate versions of these templates on disk. Because the templates are copied, rather than subclassed, for framework applications, the templates don't need to be available to your project as separate files. Instead, these items are packed into a table, _FRAMEWK.DBF, found in the HOME( )+ Wizards folder. The Application Wizard unpacks the files when it generates your new application (see Figure 4).

Figure 4. The Application Wizard copies template files from this _FRAMEWK.DBF table in HOME( )+ Wizards folder.

Because the files don't exist on disk, their template file names are largely irrelevant, except to the Application Wizard. Although we'll use the template names here, keep in mind that their copies receive new names when the Wizard generates your application.

Menu Templates

Just as the framework identifies "dialog box roles" and supplies sample dialog boxes to fill those roles, it identifies some "menu roles," and comes equipped with standard menus to meet these requirements. The roles are startup (the main menu for your application) and navigation (a context menu for those forms you identify as needing navigation on the menu).

There are three template startup menus, each corresponding to one of the three application types described by the Application Builder as normal, top form, and module. T_MAIN.MNX, is a standard "replace-style" Visual FoxPro menu. It's used for normal-style applications, which take over the Visual FoxPro environment and replace _MSYSMENU with their own menu. T_TOP.MNX, for top form applications, looks identical to T_MAIN.MNX, but has some code changes important to a menu in an MDI frame. T_APPEND.MNX is an "append-style" menu, characteristic of modules, which are applications that add to the current environment rather than controlling it.

There is one navigation menu template, T_GO.MNX. Its options correspond to the options available on the standard navigation toolbar (_NavToolbar in _FRAMEWK.VCX).

Note   Because both T_GO.MNX and T_APPEND.MNX are "append-style" menus, they can exist as part of either _MSYSMENU or your top form menu. The Application Builder synchronizes your copy of T_GO.MNX to work with your normal- or topform-type application. However, if you change your application type manually rather than through the Application Builder, or if you want a module-type application that adds to an application in a top form, you may need to tell these menus which environment will hold them.

You make this change in the General Options dialog box of the Menu Designer (select or clear the Top-Level Form check box). If you prefer, you can adjust the ObjType of the first record in the MNX programmatically, as the Application Builder does. See the UpdateMenu( ) method in HOME( )+ Wizards\APPBLDR.SCX for details.

Like the document and toolbar classes in _FRAMEWK.VCX, the menu templates are not required. They simply provide good examples, and should give you a good start on learning how to use menus in a framework application.

In particular, you'll notice that the menus do not call procedural code directly, only application object methods. This practice ensures that the code is properly scoped, regardless of whether the MPR is built into an app, or whether the .app or .exe holding the MPR is still in scope when the menu option runs.

Because Visual FoxPro menus are not object-oriented, they can't easily hold a reference to the application object. To invoke application object methods, the menus use the object's global public reference. This reference is #DEFINEd as APP_GLOBAL, in an application-specific header file, like this:

#DEFINE APP_GLOBAL              goApp

Here is an example menu command using the #DEFINEd constant (the Close option on the File menu):

IIF(APP_GLOBAL.QueryDataSessionUnload( ),
  APP_GLOBAL.ReleaseForm( ),.T.)

Each template menu header #INCLUDEs this header file. You can change the #DEFINE and recompile, and your menus will recognize the new application reference.

Note   The application object can manage this public reference on its own (you don't need to declare or release it). It knows which variable name to use by consulting its cReference property, which holds this name as a string. You can either assign the value in the program that instantiates your application object (as shown in the default main program) or you can assign this string to the cReference property of your _Application subclass at design time.

The template menus are the only part of the framework using this global reference. If you wish, your forms and other objects can use the reference, too, but there are rarely good reasons to do this. Before you opt to use the global reference, think about ways you might pass and store a reference to the application object in your forms instead. If your forms have mediator objects, they have a built-in method to receive this reference any time they need it.

Metatable Template

_FRAMEWK.DBF contains records for T_META.DBF/FPT/CDX, the table holding information about documents for your application. Records in this table indicate whether a document should be treated as a "form" or "report"—and you can create other document types on your own.

The document type designation is used by the framework dialog boxes descending from _DocumentPicker, to determine which documents are displayed to the user at run time. For example, the _ReportPicker dialog box will not display documents of "form" type, but the _FavoritePicker dialog box displays both forms and reports.

However, document type as specified in the metatable does not dictate file type. A "report" type document might be a PRG, which called a query dialog box and then ran a report based on the results.

The Application Builder creates and edits metatable records when you use the Builder to add forms and documents to the application. If you manually add a form or document to a framework project, the Project Hook object invokes the Builder to ask you for details about this document and fill out the metatable accordingly. Of course, you can also add records to the metatable manually.

The Application Builder and the _FRAMEWK.VCX dialog boxes descending from _DocumentPicker rely on the default structure of this metatable. (You'll find its structure detailed in**Appendix 2.) The dialog boxes derive from this table the information they need to invoke each type of document, including the options you've set in the Application Builder for each document. (Appendix 3 gives you a full list of _DocumentPicker subclasses and their assigned roles.)

Just as you don't have to use the _DocumentPicker dialog boxes, you don't have to use the default metatable structure in a framework application. If you like the idea of the table, you could design a different structure and use it with dialog boxes with different logic to call the _Application methods that start forms and reports.

Note   If you design a metatable with a different structure from the default, the application object can still take care of it for you. On startup, the metatable is validated for availability and appropriate structure. Once the metatable is validated, the application object holds the metatable name and location so this information is available to your application elements later, even though the application object makes no use of the metatable directly.

Edit your _Application subclass's ValidateMetatable( ) method to reflect your metatable structure if it differs from the default. No other changes to the standard _Application behavior should be necessary to accommodate your metatable strategy.

You can also dispense entirely with a metatable in a framework application. No part of the framework, except the _DocumentPicker dialog boxes, expects the metatable to be present.

For instance, you might have no need for the dialog boxes or data-driven document access in a simple application. In this case, you can eliminate the metatable and invoke all your reports and forms directly from menu options. Simply provide method calls such as APP_GLOBAL.DoForm( ) and APP_GLOBAL.DoReport( ) as menu bar options. Fill out the arguments in these methods directly in the command code for each menu option, according to the requirements of each form and report.

Additional Text Templates

_FRAMEWK.DBF holds copies of some additional text files copied for your application's use.

T_START.PRG is the template for the program that initializes your application object and shows the splash screen. Its behavior is well documented in comments you'll find in the application-specific header file, described later. In addition, as just mentioned, it is not necessary. The program that creates your application object does not have to be the main program for your application, nor does it have to do any of the things that T_START.PRG does.

For example, suppose your application is a "module type," handling a particular type of chore for a larger application. Because it is a module, it does not issue a READ EVENTS line or disturb your larger application's environment. It may or may not need to use the framework's user log on capabilities; you may have set up a user logging system in the outer program. The outer application may be a framework application, or it may not. All these things will help you decide what kind of startup code you need for this application object.

Let's look at some sample code you might want to use for an accounting application. This .exe file is not a framework application, but it has a framework module added to it, which performs supervisor-level actions. Only some users are allowed to have access to this module. When your accounting application starts up, it may have an application manager object of its own, which performs its own login procedures. The method that decides whether to instantiate the framework module might look like this:

IF THIS.UserIsSupervisor( )
   THIS.oSupervisorModule = ;
      NEWOBJECT(THIS.cMyFrameworkModuleSupervisorClass,;
                THIS.cMySupervisorAppClassLib)
   IF VARTYPE(THIS.oSupervisorModule) = "O"
      * success
   ELSE
      * failure
   ENDIF
ELSE
   IF VARTYPE(THIS.oSupervisorModule) = "O"
      * previous user was a supervisor
      THIS.oSupervisorModule.Release()
   ENDIF
ENDIF

This code does not handle the public reference variable, a splash screen, or any of the other items in T_START.PRG.

You may not need the public reference variable at all because, in this example, your framework application is securely scoped to your larger application manager object. However, if your module application has menus that use the global reference to invoke your application object, you might assign the correct variable name to THIS.oSupervisorModule.cReference just above the first ELSE statement in the preceding sample code (where you see the "* success" comment). This is the strategy you see in T_START.PRG.

Note   If many different outer applications will use this module, you will prefer to assign the appropriate cReference string in the class, rather than in this method (so you only need to do it once). You can assign this value to cReference either in the Properties window or in code during startup procedures for the application object. Either way, an assign method on the cReference property in _Application does the rest.

T_META.H is the template name for the application-specific header file, just mentioned in the section on menu templates. Only the menus and T_START.PRG use this header file, so it is up to you whether you use it, and how you use it. In the preceding example, you might not use it at all, or you might use only its APP_GLOBAL define to set the application object's global reference.

The framework uses a few more text templates:

• T_CONFIG.FPW

  Not surprisingly, provides a template for the config.fpw generated for your application. The template version gives new Visual FoxPro developers some ideas about what the config.fpw is for (it's mostly comments); you will almost certainly wish to edit this file to meet your own standards.

• T_LOG.TXT

  Provides a startup file for the "action log" the Project Hook will write during the life of your application to let you know what changes it has made to your application while you worked with the project.

• T_HEAD.TXT

  Provides a standard header that the Application Wizard uses when generating your application-specific copies of framework templates. You might want to revise T_HEAD.TXT to include your own copyright notices, especially after you've edited the rest of the templates.

Specifying Your Own Framework Components

If you've done any development at all, you've undoubtedly experienced moments in which you identify something you wish to abstract from the process of developing a single application. You've done it too many times, you know how to do it, and now it's time you figure out the best way to do it—so you never have to do it again.

In OOP terms, this is the time to develop a superclass to handle this function, so you can reuse its features. In template terms, this is the time to edit the template you copy for each application's use. In the Visual FoxPro 6.0 application framework's mixed environment, as you know, we have both types of components.

We'll quickly review how these components are managed automatically by the Application Wizard and Builder during your development cycle. Then we'll turn our attention to how you integrate your own superclasses and edited templates into this system.

Framework Components During Your Application Lifecycle

When you choose to create a new framework application, the Application Wizard takes your choices for a location and project name and generates a project file. If you select the Create project directory structure check box, the Application Wizard also creates a directory tree under the project directory. It adds _FRAMEWK.VCX and the required foundation class libraries to this project. It also adds a class library with appropriate application-specific subclasses of _FRAMEWK.VCX.

The Application Wizard then adds template-generated, application-specific versions of all the non-OOP components the application needs. As you probably realize, the Application Wizard copies these files out of the memo fields in _FRAMEWK.DBF.

_FRAMEWK.DBF contains two more records we haven't mentioned yet: T_META.VCX and T_META.VCT. These records hold straight subclasses of the classes in _FRAMEWK.VCX, and they are copied out to disk to provide your application-specific class library.

Note   T_META.VCX is not a template. It is just a convenient way for the Application Wizard to hold these subclasses, and is not part of your classes' inheritance tree. Your subclasses descend directly from _FRAMEWK.VCX when the Application Wizard creates them, and thereafter will inherit directly from _FRAMEWK.VCX.

Once your new framework project exists, the Application Wizard builds it for the first time. It also associates this project with a special Project Hook object, designed to invoke the Application Builder. The Application Wizard shows you the new project and invokes the Application Builder.

At this point, the Application Builder takes over. The Application Builder provides an interface you can use to customize the framework aspects of any framework-enabled project, throughout the life of the project.

You can use the Application Builder to customize various cosmetic features of the application object, such as its icon. When you make these choices, the Application Builder stores them in the appropriate properties of your _Application subclass. (In some cases, it also stores them in the matching _Splash subclass properties.)

In addition, the Application Builder gives you a chance to identify data sources, forms, and reports you'd like to associate with this project. It gives you convenient access to the data, form, and report wizards as you work, in case you want to generate new data structures and documents. For inexperienced developers, the Application Builder provides a visual way to associate data structures directly with forms and reports, by providing options to invoke report and form wizards each time you add a new data source.

Whether you choose to generate reports and forms using the wizards or to create your own, the Application Builder and its associated Project Hook object help you make decisions about framework-specific use of these documents. (Should a report show up in the Report Picker dialog box, or is it only for internal use? Should a form have a navigation toolbar?) It stores these decisions in your framework metatable.

As you think about these automated elements of a framework development cycle, you'll see a clear difference between the changes you can effect if you change the Application Wizard, or generation process, and the changes you can effect by editing the Application Builder and Project Hook. The files provided by the Wizard, in advance of development, represent your standard method of development. The changes made thereafter, through the Builder and Project Hook, represent customization you can do for this single application.

The balance of this article concentrates on enhancing the Wizard to provide the appropriate framework components when you begin a new application. Once you have established how you want to enhance the startup components, you will think of many ways you can change the Builder and the Project Hook, to take advantage of your components' special features, during the rest of the development cycle.

Note   An important change in versions after Visual FoxPro 6.0 makes it easy for you to customize the Application Builder to match your style of framework use. Rather than directly invoking the default appbldr.scx, the default Application Builder in later versions is a PRG.

The PRG makes some critical evaluations before it displays a Builder interface. For example, it checks to see whether the project has an associated Project Hook object, and whether this Project Hook object specifies a builder in its cBuilder property. See HOME( )+ Wizards\APPBLDR.PRG for details. You will find it easy to adopt this strategy, or to edit appbldr.prg to meet your own needs for displaying the Builder interface of your choice.

A preview version of appbldr.prg is included with the source for this article. See appbldr.txt for instructions on making this new Application Builder available automatically from the VFP interface, similar to the new wizard components delivered as part of the document.

A Closer Look at the Standard Application Wizard

You'll find the Visual FoxPro 6.0 Application Wizard files in your HOME( )+ Wizards folder. When you invoke the Application Wizard from the Tools menu, it calls appwiz.prg, which in turn invokes the dialog box in Figure 5, provided by appwiz.scx.

Figure 5. The standard Visual FoxPro 6.0 Application Wizard dialog box provided by appwiz.scx

When you choose a project name and location, appwiz.prg invokes HOME( )+ Wizards\WZAPP.APP, the Visual FoxPro 5.0 Application Wizard, with some special parameters.

The older wizard contained in wzapp.app does most of the work of creating your new project files. The Visual FoxPro 5.0 Application Wizard determines that you are in a special automated mode from the object reference it receives as one parameter and does not show its original interface. It evaluates a set of preferences received from this object reference, and proceeds with the generation process.

The standard implementation has a number of constraints:

• Your application subclasses descend directly from _FRAMEWK.VCX. This prevents your adding superclass levels with your own enhancements to the framework, and you certainly can't specify different superclasses when you generate different "styles" of applications.
• Your copies of the ancestor classes, in _FRAMEWK.VCX and FFC libraries, are presumed to be in the HOME( )+ Wizards and HOME( )+ FFC directories. Because these ancestor classes are built into your framework applications, and therefore require recompilation during a build, you have to give all team members write privileges to these locations or they can't use the Application Wizard to start new framework applications. In addition, the fixed locations hamper version control; you may wish to retain versions of ancestor classes specific to older framework applications, even when Microsoft delivers new FFC and Wizards folders.
• Your non-OOP components are always generated out of HOME( )+ Wizards\_FRAMEWK.DBF. The templates are not easily accessible for editing. The assumed location of _FRAMEWK.DBF prevents you from using different customized template versions for different types of apps, and also presents the same location problems (write privileges and versioning) that affect your use of the framework class libraries. As with your application subclasses, you can't designate different templates when you generate different types of applications.
• You have no opportunity to assign a custom Project Hook to the project.

To allow you to design and deploy customized framework components, a revised Application Wizard should, at minimum, address these points.

You can make the required changes without major adjustment of the current Application Wizard code, but some additional architectural work provides more room for other enhancements later.

A New Application Wizard

If you DO NEWAPPWIZ.PRG, provided in the source code for this article, you will get a dialog box almost identical to Figure 5, and functionally equivalent to the original dialog box. The only difference you'll notice is a request, on startup, asking you if you wish to register this wizard in your HOME( )+ Wizards\WIZARD.DBF table for future use (see Figure 6).

Figure 6. The Newappwiz.prg wizard classes can be registered to HOME( )+ Wizards\WIZARD.DBF so you can choose them from the Tools Wizards menu later.

Though your newly instantiated wizard class calls the old Visual FoxPro 5.0 Wizard code just as the original one did, its internal construction allows completely new generation code to replace this approach in a future version.

You can call newappwiz.prg with a great deal of information packed into its second parameter, to indicate what wizard class should instantiate and what this wizard class should do once instantiated.

Why the second parameter, rather than the first? Newappwiz.prg, like appwiz.prg, is designed with the standard wizard.app in mind. wizard.app, the application invoked by the Tools Wizards menu option for all wizard types, uses its registration table, HOME( )+ Wizards\WIZARD.DBF to find the appropriate wizard program to run. Wizard.app passes other information in its first parameter to the wizard program (in this case, newappwiz.prg). Wizard.app passes the contents of the Parms field of wizard.dbf, as the second parameter.

If you choose Yes in the dialog box in Figure 6, the NewAppWizBaseBehavior class becomes a new choice in the registration table, and fills out its options in the Parms field. Additional NewAppWizBaseBehavior subclasses will do the same thing, registering their own subclasses as separate entries. Once a class is registered in wizard.dbf, you don't have to call newappwiz.prg directly again.

If you've chosen Yes in the dialog box in Figure 6 and also choose to register the wizard subclass we investigate in the next section, when you next choose the Application Wizard from the Tools menu, you'll get a choice, as you can see in Figure 7.

Figure 7. Select your Application Wizard du jour from the Tools Wizards option—once you have more than a single Application Wizard listed in your HOME( )+ Wizards\WIZARD.DBF table.

An Extended Subclass of the New Wizard: AppWizReinherit

With an enhanced architecture in place, we can address the issues of component-generation we've raised.

Run newappwiz.prg again, this time with a second parameter indicating a different wizard subclass to instantiate:

You should get another message box, similar to Figure 6, asking you if you want to register this subclass in the wizard.dbf table. When you've dismissed the message box, you see the dialog box in Figure 8.

Figure 8. Re-inheritance Application Wizard, page 1

The first page of this dialog box contains exactly the same options as the standard Application Wizard.

Note   You'll find all the visual classes used in the new wizards in newappwiz.vcx, as part of the source code for this article. The container you see on this page of the AppWizFormReinherit class is the same container class used in AppWizFormStandard. You can read more about these dialog box classes in Appendix 4.

Each subsequent page of the dialog box addresses one of our concerns with the way the original Application Wizard delivers components, and includes some information about how it works. (Figure 9 shows you pages 2 and 3.) Each option defaults to the same behavior you'd get from the original Application Wizard—you don't need to fill out information on all pages.

Figure 9. Pages 2 and 3 of the Re-inherit App Wizard provide a layer of superclasses and the locations of your FFC and _FRAMEWK.VCX libraries for this framework application.

If you change the parent VCX as suggested on the second page of the dialog box, you can have one or more layers of superclasses between your application's subclasses of _FRAMEWK.VCX. You'll create team-specific enhancements in these layers.

Note   This version of the Application Wizard will create the initial classes for you, as subclasses of the components in _FRAMEWK.VCX, if you specify a VCX name that does not exist. Later, you can create more layers of subclasses from the one the Application Wizard derived from _FRAMEWK.VCX, and designate your subclass layer in this dialog box as appropriate. The VCX you designate on the second page of this dialog box should always conform to the following rules:

• Be the immediate superclasses (parent classes) of the application-specific VCX for this application.

  –and–

• Include all the required subclasses of _FRAMEWK.VCX, with the same names as the _FRAMEWK ancestor classes.

You may want several different branches of your team-specific class levels, to match different types of framework applications you commonly create. For example, you could have one superclass set with your team's options for a framework module and another one with your team's topform custom attributes (including the class and classlibrary for your subclass of _topform to provide the correct frame).

Note   These branches, or types, are not restricted to the "styles" or options you see represented in the Application Builder. They are just part of the normal process of subclassing and enhancing a class tree.

For example, you may decide to create Active Documents as framework applications. To do so, you'll need an _Application subclass that is aware of its hosted environment, and makes certain interface decisions accordingly. You'll also need an ActiveDoc subclass that is aware of the framework's capabilities and calls application object methods in response to browser-triggered events, just as the menu templates invoke framework behavior.

Now that you can insert class levels between _FRAMEWK.VCX and your application-specific level, you can make the implementation of these features standard across applications.

If you change the locations of the FFC and _FRAMEWK.VCX libraries on the "Ancestors" page, the Application Wizard will place appropriate copies of the required class libraries in your specified locations if they don't exist. The Application Wizard also ensures that your copy of _FRAMEWK.VCX inherits from the proper version of FFC, and that your parent classes point to the proper version of _FRAMEWK.VCX.

Note   As mentioned in the section "FoxPro Foundation Generic Classes," your FFC location can include your own version of _BASE.VCX. Your _BASE.VCX does not have to have the same code or custom properties as the original _BASE.VCX, but like your parent classes, your _BASE must include classes descended from the same Visual FoxPro internal classes, with the same names, as the classes in the original _BASE.

Other FFC libraries, not used in the framework and not described in this article, will not necessarily work with your own _BASE.VCX. For example, if your application uses _GENHTML, the _HTML.VCX library relies on code in the HOME( ) + FFC\_BASE.VCX library. If you use other FFC libraries in your framework application, you may have two _BASE.VCXs included in your project—this is perfectly normal.

The Application Wizard then focuses on your template files on the next page of the dialog box. If you set a location for your template files, the Application Wizard will create fresh copies of these files (by copying them from the original _FRAMEWK.DBF), ready for you to edit.

In each case, if the files are already in the locations you supply, the Application Wizard will use the ones you have.

The last page of the dialog box allows you to pick a Project Hook. The original AppHook class in HOME( ) + Wizards\APPHOOK.VCX is the required ancestor class for a Project Hook designed to work with this application framework, but you can add a lot of team-specific features to your Project Hook subclass. The Application Wizard attempts to verify that the class you specify on this page descends from the appropriate AppHook class.

When you generate your application, the Application Wizard will create a new set of straight subclasses from your parent VCX (or _FRAMEWK.VCX, if you haven't changed the default on the "Parents" page). These subclasses become the new T_META.VCX/VCT records in _FRAMEWK.DBF. The Wizard appends new contents for all the other template records of _FRAMEWK.DBF from the template folder, if you've named one.

Note   The first time you and the Application Wizard perform these tasks, it won't make much difference to the final results. Once the Wizard gives you editable superclass layers and your own copies of the templates, however, you have all the architecture necessary to customize the framework for subsequent uses of the Application Wizard.

Having replaced _FRAMEWK.DBF records, the Application Wizard proceeds to create your new application much as before, inserting information about your designated Project Hook class at the appropriate time.

All the "enhanced" Wizard actions are tuned to respect the current setting of the lDelegateToOriginalAppWizard switch, which indicates whether the Visual FoxPro 5.0 Application Wizard code is running or if new code is creating the project. For example, because the original code only looks in the HOME( )+ Wizards folder for _FRAMEWK.DBF, if you have indicated a different place for your _FRAMEWK.DBF (on the "Templates" page) this table will be copied to HOME( )+Wizards before wzapp.app runs. (The first time this occurs, the new Wizard copies your original _FRAMEWK.DBF to a backup file in the HOME( ) + Wizards folder.) Presumably, newer code simply uses your templates table wherever you've placed it.

When you use this Wizard to generate a framework application it saves information about your preferred parent classes, as well as the locations of your FFC and _FRAMEWK libraries and template files, to special _FRAMEWK.DBF records. You won't need to enter this information, unless you wish to change it. This release of the Application Wizard doesn't save information about the custom Project Hook subclass you may have specified. However, the next section will show you how to put this information into the Parms of wizard.dbf for default use.

Note   Because the Application Wizard reads its stored information out of _FRAMEWK.DBF, it can't get the location of _FRAMEWK.DBF from a stored record! However, you can put this information into the Parms field of wizard.dbf, as described in the next section, so all your developers use the proper version of _FRAMEWK.DBF without having to look for it.

You may even decide to use a version of this Wizard class, or of its associated dialog box, that only allows some developers to change the "advanced" pages. Other team members can fill out standard information on Page 1, but they'll still get your improved versions of all the framework components.

Registering Additional Wizard Subclasses and Customized Records

The new Application Wizard provides the opportunity to register each subclass of its superclass separately in the wizard.dbf table. The wizard stores its class name and location in the Parms field of its own wizard.dbf record.

However, you can add more information in the Parms field. You can even store multiple entries in the wizard.dbf for a single subclass, with differently tuned Parms values. The Application Wizard, once instantiated, uses this additional information.

Here's the full list of nine options you can pass in the second parameter, or place in the Parms field, for use by NewAppWizBaseBehavior and its subclasses. All #DEFINEs mentioned in this list are in the newappwiz.h header file associated with newappwiz.prg:

These three options instantiate the Wizard:

• Wizard class

  Must descend from #DEFINEd APPWIZSUPERCLASS, defaults to NEWAPPWIZSUPERCLASS.

• Wizard classlib

  Library containing wizard class, defaults to NEWAPPWIZ.PRG.

• .App or .exe file name

  Optional file, containing the wizard class library.

These six options are used by the Application Wizard after it instantiates:

• Wizard form class

  Must descend from #DEFINEd APPWIZFORMSUPERCLASS, defaults to #DEFINEd NEWAPPWIZFORMSTANDARD.

• Wizard form classlib

  Library containing the form class, defaults to NEWAPPWIZ.VCX.

• .App or .exe file name

  Optional file containing the wizard form class library.

• Project Hook class

  The Project Hook class you want to associate with this project, if you don't want to use the default Project Hook class associated with framework-enabled projects. This class should descend from the AppHook class in HOME( )+ "Wizards\APPHOOK.VXC", so it includes the default functionality, but can include enhancements required by your team.

• Project Hook classlib

  The class library containing the Project Hook class you choose to associate with this project.

• Template DBF

  Holding application components, defaults to HOME( )+ Wizards\_FRAMEWK.DBF (#DEFINED as APPWIZTEMPLATETABLE).

Store these values delimited by commas or carriage returns in the Parms field of wizard.dbf. Similarly, if you call newappwiz.prg directly, you can pass all this information as the program's second parameter, as a single string delimited with commas or carriage returns.

After you've registered the AppWizReinherit class, the Parms field for this class' record in wizard.dbf contains the following information:

APPWIZREINHERIT,<fullpath>\newappwiz.fxp,,AppWizFormReinherit, <fullpath>\NEWAPPWIZ.VCX,,APPHOOK, <fullpath of HOME()+ "Wizards"> \APPHOOK.VCX, <fullpath of HOME()+ "Wizards"> _framewk.DBF

You could run the NEWAPPWIZ program, passing the same string as its second parameter, to get AppWizReinherit's default behavior.

Using our ActiveDoc example just shown, you could create a wizard.dbf entry that invokes the same Wizard class but defaults to a different parent VCX and different menu templates than the rest of your framework applications.

To accomplish this, you'd edit the information in the ninth value for this row of the wizard.dbf table, which indicates Template DBF, by editing the Parms field.

Your new row in the table contains the same string in the Parms field, except for the section following the last comma, which points to a new template table. Your special ActiveDoc copy of _FRAMEWK.DBF holds your special Active Document menu templates and superclass information.

Next, suppose you decide that your ActiveDocument framework applications need a special Project Hook subclass, not just special superclasses and menu templates. You could specify this hook automatically, in the seventh and eighth sections of the Parms field. You might even subclass the AppWizFormReinherit dialog box, to disable the last page of this dialog box for ActiveDocument-type applications, by changing the fourth and fifth sections of the Parms field. (This way, your team members would always use the right Project Hook class when generating this type of framework application.)

If you made all these changes, this new entry in the wizard.dbf table might have a Parms field that looked like this:

APPWIZREINHERIT,<fullpath>\newappwiz.fxp,,MyAppWizActiveDocumentDialog, <fullpath>\MyAppWizDialogs.VCX,,MyActiveDocumentAppHookClass, <fullpath> \MyHooks.VCX, <fullpath>\MyTemplates.DBF

You would also edit the Name field in wizard.dbf for this entry, perhaps to something like "Active Document Framework Application," to distinguish this entry from your standard values for the AppWizReinherit class.

When one of your team members accessed the Tools Wizards option from the system menu, "Active Document Framework Application" would now appear on the list of available Wizards, as part of the list you saw in Figure 7. The developer could automatically create the right type of framework application, without making any special choices.

A Few Parting Thoughts about Team Practices

You'll notice a check box in the Reinheritance Wizard's dialog box, indicating that you can omit message boxes and generate your new application with no warning dialog boxes or user interaction. Although this is a helpful option once you've used this Wizard a few times, please be sure to read all the message boxes, and the information in the edit boxes on the various pages of this dialog box, at least once.

Any developer's tool, especially one that edits visual class libraries and other metafiles as extensively as this one does, can potentially cause problems if the system is low on resources. The Help text available within this Wizard attempts to point out its potential trouble spots, so you can close other applications as needed, and have a good idea of what to expect at each step. Other caveats, such as incompletely validated options in this preliminary version, are indicated in the Help text as well.

You also see a More Info button, which provides an overview of the issues this class is meant to address, and how you can expect it to behave (see Figure 10).

Figure 10. Wizard documentation under the More Info button

Beyond its stated purpose to enhance the Application Wizard, AppWizReinherit and its dialog box class try to give you a good model for tool documentation, both at design and run time. The dialog box's NewAppWiz_Documentation( ), GetUserInfo( ), and DisplayDocumentation( ) methods should give you several ideas for implementation of run-time documentation. Newappwiz.prg has a demonstration procedure, BuilderGetDocumentation( ), which shows you how you can apply these ideas to design time documentation for Builders as well. A final demonstration procedure in newappwiz.prg, ReadDocs( ), shows you another aspect of this process.

Each documentation idea demonstrated here is a variation on a theme: Text is held (using various methods) within the VCX, so it travels with the VCX and will not get lost no matter how widely you distribute the library.

Whether you use these particular implementations is not important; in many cases you'll be just as well off if you create a text file with documentation and use Visual FoxPro's FileToString( ) method to read this information for display by the tool whenever necessary.

No matter how you decide to implement it, documentation that helps your team better understand the intended use, extension possibilities, and limitations of the tools you build is critical to their adoption and successful use.

A framework is, in itself, a kind of abstraction, a level above daily activities. Enhancements to a framework represent yet another level of abstraction. Your team will benefit from all the extra attention you can give to communicating your goals for this process.

With any framework, you can efficiently prototype applications and build complete lightweight applications. With a framework set up the way your team operates, you can accomplish these goals without sacrificing quality, depth, or your normal habits of development. With a framework set to deliver your standard components and practices automatically, even new developers can make meaningful, rewarding contributions to your team effort.

Appendix 1: The User Option System

The framework employs a user-registration system based on a user table that is created by the application object if not found at run time. The application object uses the cUserTableName property to set the name and location of this table. If no path is supplied in this property, the location will be set by the cAppFolder property.

Note    By default, the application object sets cAppFolder to the location of the APP or EXE that instantiated it. If, for some reason, the application object was instantiated outside a compiled APP or EXE container, cAppFolder contains the location of the application object's VCX.

If necessary, the application object creates this table in the appropriate location, using the following code (excerpted from the CreateUserTable( ) method):

lcIDField = THIS.cUserTableIDField
lcLevelField = THIS.cUserTableLevelField
* names of two generic-requirement fields,
* User ID and level, are specified by
* _Application properties in case you
* wish to match them to some existing system
CREATE TABLE   (tcTable) ;
   ((lcIDField) C(60), ;
   (lcLevelField) I, ;
   UserPass  M NOCPTRANS, ;
   UserOpts  M NOCPTRANS, ;
   UserFave  M NOCPTRANS, ;
   UserMacro M NOCPTRANS, ;
   UserNotes M )
INDEX ON PADR(ALLTR(&lcIDField.),60) TAG ID
* create a case-sensitive, exact word match
INDEX ON PADR(UPPER(ALLTR(&lcIDField.)),60) TAG ID_Upper
* create a case-insensitive, exact word match
INDEX ON DELETED( ) TAG IfDeleted

If you don't opt to have users log in and identify themselves in this application, this table is still created. In this case it supplies a default record, representing "all users," so user macros, favorites, and options can still be stored in this table on an application-wide basis.

Note   Because of their "global" nature in Visual FoxPro, user macro saving and setting features are only available to framework applications that issue READ EVENTS. Module applications are not allowed to edit the macro set.

When a user logs in, his password is evaluated using the user table's UserPass field. A SetUserPermissions( ) method, abstract in the base, is called at this time so the user's level can be checked in order to make appropriate changes to the application and menu options as well.

If the login is successful (or when the application starts up assuming no user login for this application), user name and level are stored in the cCurrentUser and iCurrentUserLevel properties.

User macros, favorites, and options are set from the user's record in the user table. The _Application code handling macros rely on standard Visual FoxPro abilities to SAVE and RESTORE macros to and from the UserMacro memo field. The favorites system uses an easy-to-read ASCII format in the UserFave memofield. However the options system and the UserOptions field deserve more explanation.

The user table stores option information in its UserOptions memo field, by SAVEing the contents of a local array. This local array is RESTOREd and copied into a member array, aCurrentUserOpts, to establish user options when the current user is set.

The array format is fixed, and yet extremely flexible in the types of user options that can be stored. The allowable options include SETs and member properties, and the options should be specified as being "global" to the application or private to a datasession. The array is laid out, to specify these attributes of each option, in four columns, as follows.

User Option Array Column 1	Column 2	Column 3	Column 4
Item name For a SET command, the item you're setting, same as what you'd pass to the SET( ) function. For an object, the property you wish to set. Can be the Member.Property you wish to set.	Value for this item	Property (.F.) or SET (.T.) ?	Session (.F.) or Global (.T.) ?

Each time a user logs in, the application method ApplyGlobalUserOptions( ) applies SET options and application object property values for all array rows with .T. in the fourth column. The mediator object has the responsibility to call the application method ApplyUserOptionsForSession( ), on your instructions, passing a reference to its parent form. This method applies SET options and form property values for all array rows with .F. in the fourth column.

The _Options dialog box supplied in _FRAMEWK.VCX gives you examples of all the combinations that can be created for a user option using this array, although its contents are merely examples. It shows you how the user options stored in an array can be expressed as a user interface, giving the user a chance to make changes. It also shows how results of a user-option-setting can be "translated" back into the user options array for use during this login, or saved as defaults to the user preference table.

You will note that, when the user options to apply changes to the current settings, the Options dialog box reinvokes ApplyGlobalUserOptions( ) and then iterates through the available forms, giving their mediators a chance to reapply session settings if they're set to do so.

In many cases, a "global" setting can transferred to forms as well. For example, the _ErrorLogViewer dialog box has a mediator that checks the application's cTextDisplayFont setting. This is a global user option, because it provides a chance for the user to specify a text font across all the UI of an application. The mediator transfers the value of the cTextDisplayFont to a property of the same name belonging to its parent dialog box. An assign method on this property then applies the fontname value to all members of the dialog box that should reflect the setting.

Appendix 2: The Default Metatable Structure

This table shows you the default structure of the framework's metatable. Appendix 3 shows you how the default _FRAMEWK.VCX dialog boxes use this information.

FieldName	Type	Use
Doc_type	C	This field contains a character to distinguish between document types. Currently, "F" is used for "forms" and "R" is used for "reports." But this designation just determines how the document type is presented in the interface, not necessarily what type of Visual FoxPro source code file underlies the document. See Alt_Exec and Doc_wrap fields, below. More document types may be added. The framework already contains one extra type, "A," specifically reserved for you to add application information. The framework will not use "A"-type metatable records in any way, so the reservation of this type simply allows you to use metatable records, or perhaps one metatable header record, as a convenient place for system storage. In most cases, you would want to transfer the contents of such a record to application properties on startup.
Doc_descr	C	The "caption" or long description you want to show up in document picker lists.
Doc_exec	M	The name of the file to be run, usually an .scx or .frx file. In the case of a class to be instantiated, this is the .vcx file name. For Form-type documents, the file extension is assumed to be .scx unless this entry is marked "Doc_wrap" (see below) or the Doc_class field is filled out, in which case the extension is assumed to be .vcx. For Report-type documents, the file extension will default to .frx unless this entry is marked "Doc_wrap". If no .frx file exists by that name, the application object looks for an .lbx file. In all cases, you may also fill out the file extension explicitly. In all cases, if you Include the file to be run in the project, you need not use paths in this field. If you wish to Exclude the file from the project, you may use path information. Assuming your applications install their subsidiary Excluded files to the appropriately located folder, relative pathing should work in the metatable, and is probably the best policy in this case!
Doc_class	M	The class to be instanced, where the Doc_exec is a .vcx file
Doc_new	L	Mark this .T. for a Form-type document you wish to show up in the FileNew list. When the application object instantiates a form from the FileNew list, it sets its own lAddingNewDocument property to .T. This practice gives the form a chance to choose between loading an existing document or a blank document during the form's initialization procedures. In many cases, the form delegates this process to its mediator object. The mediator object saves this information for later use. If you do not use a mediator, you may wish to save this information to a form property; you can't expect the application object's lAddingNewDocument to reflect the status of any particular form except during the initialization process of that form. For a Report-type document, this field denotes an editable report (new report contents, or even a new report from a template). This capability isn't currently implemented.
Doc_open	L	Mark this .T. for a Form-type document you wish to show up in the FileOpen list. For a Report-type document, this field denotes a runnable report or label and will place the item in the report picker list.
Doc_single	L	Mark this .T. for a Form-type document that is modeless but should only have one instance. The application object will bring it forward, rather than create a second instance, if the user chooses it a second time.
Doc_noshow	L	Mark this .T. for a Form-type document that you wish to .Show( ) yourself after additional manipulation, rather than allowing the DoForm( ) method to perform the .Show( ). Note   You will have to manipulate the application's forms collection or the current _SCREEN.Forms( ) contents to get a reference to this form, so you can manipulate the form and then .Show it when you are ready. If you need this reference immediately, the best place to get it is probably the application object's aForms[] member array. At this moment, the application object's last-instantiated form is the one for which you want the reference, and the application object's nFormCount property has just been refreshed. Therefore, .aForms[THIS.nFormCount] gives you the reference you need when you're in an application object method (in other code, replace THIS with a reference to the application object). You can see an example of this usage in the _Application's DoFormNoShow( ) method. You can create Doc_Wrap programs as described in the entry for the next field. Your wrapper program can take advantage of the DoFormNoShow( ) method, receive its return value (a reference to the form or formset object), and proceed to do whatever you want with it.
Doc_wrap	L	If this field is marked .T. indicating a "wrapped" document, the application's DoProgram( ) method will run instead of its DoReport( )/DoLabel( ) or DoForm( ) method. If you omit the file extension, the DoProgram( ) method uses the standard Visual FoxPro extension hierarchy to figure out what file you wish to run (".exe .app .fxp .prg").
Doc_go	L	If this field is marked .T. and the document is "Form"-type, the form uses the framework's standard Go context menu for navigation. The menu name is configurable using the application object's cGoMenuFile property. This field is not used for report-type documents.
Doc_nav	L	If this field is marked .T. and the document is "Form"-type, the form uses the framework's standard navigation toolbar for navigation. The class is configurable using the application object's cNavToolbarClass and cNavToolbarClassLib properties. This field is not used for report-type documents.
Alt_exec	M	If this field is filled out, it takes precedence over the Doc_exec field just described. When the user makes a document choice, the _DocumentPicker's ExecDocument( ) method converts the contents of this field into a string and runs that string as a macro. Your Alt_exec statement can be anything you choose, and it can use attributes of the metatable, including the Properties field (below) however you want. For example, you can choose to have the metatable editable (on disk) rather than included in the APP/EXE, and you can place information in the Properties field dynamically at run time. Your document would then be able to be "aware" of this information by examining the current contents of the Properties field.
Properties	M	This memo field is not used by the framework in any way. It's for developer use, primarily in conjunction with the Alt_exec field.
User_notes	M	This memo field is not used by the framework in any way. It can be used for notes that would be displayed as Help text for a particular form or report, and so on.

Appendix 3: Default Document- Management Elements of the Framework

The framework accesses metatable information through the _DocumentPicker classes. _DocumentPicker is an abstract standard dialog box class, which contains a picklist and a couple of buttons. The working _DocumentPicker subclasses each have their own way of using the information in the metatable to perform two tasks:

• Show the documents in the picklist.
• Run the appropriate action when the user picks a document.

Each subclass stores the relevant metatable fields into an array, which serves as the data source for the list box in the dialog box. The same array holds the metatable information that will eventually act on the user's choice.

The _DocumentPicker superclass has an abstract FillDocumentArray( ) method, designed to perform the first service during the dialog box Init( ), and another abstract method called ExecDocument( ), which is triggered whenever/however the user makes a selection from the document list.

The _DocumentPicker class receives a parameter from the application object. Each subclass of _DocumentPicker uses the parameter to determine which of two states it is supposed to be in when it displays its document list and acts on the user's choice of a document from the list. The _DocumentPicker superclass simply makes note of this logical value, leaving it to the subclasses to interpret it.

The various _DocumentPicker's FillDocumentArray( ) methods concentrate on different document types, and fill the array with the appropriate information for that type. Their ExecDocument( ) methods call different application object methods depending on their document type and the dialog box's current state, sending information from the metatable from the array to method arguments as needed.

The first two columns in the table below show you the names of these working classes and the document types that will appear in their lists, courtesy of their FillDocumentArray( ) method. The other columns show the application methods that call them, and the meaning assigned to their two states when ExecDocument( ) is triggered. Each application method listed here takes a logical parameter (defaulting to .F., State 1) to indicate for what purpose the class presents its document list.

_DocumentPicker Subclass	_Document types	Associated _Application method	State 1 action	State 2 action
_NewOpen	forms	DoNewOpen( )	Edit	Add
_ReportPicker	reports and labels	DoReportPicker( )	Run report/label	Modify/Add not implemented in _Application superclass.
_FavoritePicker	documents and files of any type	DoStartupForm( )	Run document/file	Put document / file on Favorites menu for quick access.

Appendix 4: Using the NEWAPPWIZ Visual Classes

AppWizFormReinherit, the dialog box called by AppWizReinherit, and AppWizFormStandard, the default dialog box with the same interface as the original wizard, both descend from the same superclass, AppWizFormBaseBehavior (see Figure 11).

Figure 11. Newappwiz.vcx in the Class Browser

AppWizFormBaseBehavior is the required superclass for any dialog box provided as the UI of a NewAppWizBaseBehavior or its descendents. The Application Wizard superclass validates your dialog box class when it instantiates the dialog box as descending from this superclass dialog box.

NewAppWizBaseBehavior contains only the very simple required behavior, no visible controls. It has three custom properties to represent required wizard information (project name, location, and whether or not the Wizard should generate project directory structure). It receives this information from an object reference the Wizard passes. It has a Finish( ) method which passes this information back to the Application Wizard.

In your subclass of AppWizFormBaseBehavior, you simply databind the interface controls of your choice to these three custom properties. You create other controls and custom properties to represent your enhanced options. Your dialog box calls the Finish( ) method when you're ready to generate. (Both AppWizFormReinherit and AppWizFormStandard use the OKButton class you see in Figure 11, which contains the call to its parent form's Finish( ) method.)

You can augment Finish( ) to pass more options from the dialog box back to your Wizard subclass as necessary.

You'll find more information in the NewAppWiz_Documentation method of the superclass. The default AppWizFormStandard subclass shows you a simple example of how to make it work.

© Microsoft Corporation. All rights reserved.