Chapter 32: Application Development and Developer Productivity

Microsoft FoxPro has always provided developer tools for application development within the FoxPro application and the XBase language. Visual FoxPro has added object-oriented language and behaviors. This version of Visual FoxPro includes an enhanced application framework and object creation and maintenance tools designed to aid rapid application development and to streamline your maintenance tasks.

This chapter discusses:

Component Gallery

Coverage Profiler Application

Project Manager Hooks

New and Enhanced Wizards

Enhanced Application Framework

Component Gallery

The Component Gallery is a container for catalogs of software objects such as class libraries, forms, buttons, and so on. The Component Gallery also contains new Visual FoxPro classes. You can use the Component Gallery to organize components into object, project, application, or other groupings. These visual groupings are dynamically customizable so that you can use, duplicate, or rearrange components among several classifications within the Component Gallery. You can access a specific item from any of the places in the Component Gallery that you place a reference to that component. You can have several references in different catalogs or folders to a single object. For instance, a button might appear in one or more Component Gallery project categories (represented as folders), but might also be visible in a "Tools" category that holds references to all the buttons you use.

You can use the Component Gallery for all the functions provided by the separate Project Manager, Class Browser, and Form Controls toolbar. Each of the other Visual FoxPro components provides very specific focus to the projects or classes from within the special environment of either Project file or Class library. The Component Gallery allows you to manage the relationships between components and many of the behaviors of those components from either an abstract design level as well as from a more intimate development perspective.

You can drag and drop components within the Component Gallery and from the Component Gallery to projects or forms. You can also change properties of objects or classes from within the Component Gallery.

The Component Gallery can contain any Visual FoxPro element, including local and remote documents, files, or folders, Automation servers like Microsoft Excel and Word, and HTML locations and files. You can also include .prg files containing code snippets, classes, wizards, builders, or art.

To open the Component Gallery

• From the Tools menu, click Component Gallery.

  -or-

• Type DO (_GALLERY) in the Command window.

Managing Projects with the Component Gallery

You can use the Component Gallery to create Projects and Applications and to manage their development. Use the Component Gallery to arrange components within the Component Gallery or use the templates, builders, and wizards in the Component Gallery to create the project or application you want.

To create a project or an application from the Component Gallery

• Use the Application Wizard or New Application template in the Applications folder of the Visual FoxPro catalog.

For catalogs and folders, select tabs and options for the change you want to make. For details, see Component Gallery Options dialog box.

Moving and Viewing Items in the Component Gallery

You can move items in the right, Object, pane of the Component Gallery window to the desktop or to an open project or form. The Project Manager recognizes the item referenced by the Component Gallery item and places it in the proper location in the Project Manager. Component Gallery items placed on the desktop are nonfunctional. There is no desktop representation for the Database, Folder, and gallery items representing nonvisual files.

To move items from the Component Gallery

1. In the right pane, click the item you want to move.

   The Move icon, located in the upper-left corner of the Component Gallery window, changes according to what item you select.

2. Drag and drop the Move icon to the desktop or to an open project or form.

When the Component Gallery cannot find the original item represented by the gallery item, a Find dialog box opens so that you can locate the item.

The following table identifies the gallery items included in Visual FoxPro and their default behaviors.

  1 – Add hyperlink class
2 – Add an image class or set a Picture property
3 – Add a multimedia class
4 – Add a grid class
5 – Depending on the type (e.g., form) creates a new file and adds it  to the project
6 – Creates an instance in Screen
7 – Sets the Visual FoxPro wallpaper
8 – Launches a new Gallery window with that catalog
9 – Add a Button class to launch a form/report
10 – Add a shortcut menu to a form
11 – Opens in a designer (modifies)

Using Shortcut Menus in the Component Gallery

You can right-click on a selected item in the right, Object, pane to display an Item Shortcut menu containing all the action options for that item, including Add to Project or Add to Form options. Use the shortcut menu to modify or, in some cases, run the gallery item. The shortcut menus are characteristic for each type of gallery item. You can change some properties of the selected item by clicking Properties on the shortcut menu to open the Item Properties dialog box.

Organizing Visual FoxPro or Windows Components into User-Defined Groups

The Component Gallery folders represent an arbitrary grouping of gallery items. You can reassemble the gallery items using drag and drop or you can duplicate items into other folders. You can copy and rename a catalog or folder and reassemble the items it contains. There are few, if any, limits on how you can use, modify, or create catalogs or folders.

Reviewing and Modifying Classes

Since Component Gallery items represent real items that can be objects or classes, you can review or modify these classes by accessing the original object through the Component Gallery.

To review a class

1. In the Component Gallery, right-click a class.
   
   
2. On the shortcut menu, click View in Browser.

   This opens the Class Browser so you can view the properties and methods of the selected class.

To modify a class

1. In the Component Gallery, right-click a class.
   
   
2. On the shortcut menu, click Modify.

   This opens the class in the Class Designer.

Creating and Modifying Forms

You can use the Component Gallery to duplicate or modify forms and to add forms and other gallery items to a project.

To create a form from the Component Gallery

• Double-click any template or select New Form from the shortcut menu of any template in the Forms folder of the Component Gallery.

  -or-

• Double-click the Form Wizard in the Forms folder of the Component Gallery.

  -or-

• Select Create Form from the shortcut menu of Component Gallery items in the Forms folder of the Component Gallery.

Advanced Editing Features in the Component Gallery

The default settings for catalogs and folders enable you to perform basic review and management with gallery items. If you want to modify characteristics of catalogs or folders, or if you want greater access to gallery properties, select Advanced editing enabled in the Component Gallery Options dialog box.

Component Gallery Catalogs

When you open the Component Gallery, the left, Catalog, pane displays the default catalog shipped with the Component Gallery. A catalog is a visual representation of items that belong to a Visual FoxPro or user-defined group of items. Within a catalog you can create folders to further organize subgroups of items. Items can be forms, queries, programs, templates, art files, sound files, or other objects. The Visual FoxPro Component Gallery default catalog includes items grouped into several categories, including forms, controls, and others. The default catalog also includes an empty folder named Favorites that you can use to create or copy gallery items into. You can also copy and rename the default catalog, or create your own catalogs.

Component Gallery catalog options are set for catalog content and opening behavior. Global catalogs can contain any Component Gallery item type. Default catalogs open automatically when you start the Component Gallery. For details, see the Catalogs tab of the Component Gallery Options dialog box.

The Component Gallery includes the following catalogs.

When you click a catalog in the list view, the right, Object, pane, displays the contents of that catalog. You can open other catalogs by double-clicking the catalog in either panel. Several Catalogs are included in the Gallery folder.

Customizing the Component Gallery

You can customize the Component Gallery by changing the default behavior of catalog, folder, and gallery items through the appropriate Properties dialogs.

To create a Component Gallery catalog

1. Select the Options button on the Component Gallery toolbar.
   
   
2. Click the Catalogs tab in the Component Gallery Options dialog box.
   
   
3. Click New and name the new catalog in the Open dialog.
   
   
4. Click OK.
   
   
5. The Component Gallery adds the catalog to the treeview so you can begin using it as you would any existing catalog.

To change a catalog or folder configuration

1. Right-click the catalog or folder.
   
   
2. From the shortcut menu, click Properties.
   
   
3. In the Catalog Properties dialog box or Folder Properties dialog box, select the tab containing the options you want to configure.

   Gallery catalogs and folders, as displayed in the Component Gallery window Catalog pane, can represent URLs, folders, or files on your hard disk. You can view a Gallery folder as Web view or as an Explorer-level view, depending on the way you specify the name in the General tab of the Folder properties dialog.

Web Views

You can specify URLs or files as Gallery catalogs or as Gallery items. When you configure an item as a Gallery folder, the item automatically opens as a Web view in the Object (right) pane when you select it in the Catalog pane.

To configure a Gallery catalog or folder as a web view

1. In the Folder Properties Dialog_Box, select the Node tab.
   
   
2. In the Dynamic folder field, specify the Web page or file name as in the following examples:

   http:\\www.microsoft.com\

   file:\\c:\my documents\testpage.htm

   file:\\c:\my documents\Wordfile.doc

When you highlight the Eeb view icon in the Catalog pane, the toolbar changes to include Web navigation buttons. The Web view will reflect the settings of your Windows Explorer.

Explorer-level Views

You can specify a directory as a Gallery folder or catalog that has characteristics of Windows Explorer.

To configure a Gallery catalog or folder as an Explorer-level view

1. In the Folder Properties Dialog_Box, select the Node tab.
   
   
2. In the Dynamic folder field, specify a folder or file name and backslash (\) as the value as in the following examples:

   C:\My Documents\

Note   This specification creates a view of actual files, unlike other Component Gallery views. In this view you can delete files from your disk.

To create an Explorer-level view that maintains protection of displayed files, specify the target using a wildcard designation as in the following example:

C:\My Documents\*.*

Avoid using wildcards to create dynamic folders when you can expect to find more than 512 items, unless you have a fast machine with a large amount of RAM.

Component Gallery Object Members

The Component Gallery is comprised of an interface, whose classes are contained in Vfpglry.vcx, and items that reference the following Visual FoxPro Foundation Classes.

For full details on these class libraries, see the Visual FoxPro Foundation Classes topic. You can get information on how to use the foundation classes in Guidelines for Using Visual FoxPro Foundation Classes.

Component Gallery Class Library (Vpfgallery.vcx)

The Component Gallery class library, Vpfgallery.vcx, provides the item types as classes.

You can use the Class Browser to examine the details of any of these classes.

For details on other classes used in the Component Gallery, see the Visual FoxPro Foundation Classes topic or use the Class Browser to examine the libraries in the Ffc folder.

Component Gallery Table Structure

The Visual FoxPro Component Gallery is described in the following table structure.

Coverage Profiler Application

A coverage application writes information about which lines of code in a file were run. A profiler application provides information about which lines actually run, how many times a line is run, duration, and more. Coverage and profiling enable a developer to identify problem areas in an application, especially skipped code and performance bottlenecks.

Visual FoxPro Coverage Profiler is provided in two parts – a Coverage engine you can use or customize, and a multiwindow application you can use to analyze programs and projects.

The Coverage Profiler application provides several ways to view the data provided by the Coverage Engine. Coverage.app is a subclass of the Coverage engine. You can automate coverage, or modify the User Interface to suit your needs, run Coverage Profiler in unattended mode and not display the application window, or use engine features without using the interface.

Upon startup the coverage application suspends coverage logging enabled with a SET COVERAGE TO command. When you release the coverage object, the application provides a choice to restore the SET COVERAGE setting.

Coverage Profiler Log File

Coverage Profiler uses a log file generated by Visual FoxPro when you use the Coverage option in the Debugger Tools menu or use SET COVERAGE TO as in the following command:

SET COVERAGE TO cCoverage.log

When you use the command, the ADDITIVE clause allows you to avoid overwriting an existing log. This command starts data streaming and opens the file cCoverage.log, a text file that will gather the stream of details on the file or application you examine.

A coverage log file consists of records in comma-delimited lines. The following list describes the structure of each record.

After specifying the log file name, run the program or application you want to examine. When you end the program you can use the SET COVERAGE TO command to stop the data stream to the coverage log.

You can view the coverage log by starting Coverage Profiler from the Tools menu or by using DO as in the following command:

DO (_COVERAGE) [WITH cCoverage]

Visual FoxPro prompts you for the name if you do not specify a log file. The _COVERAGE System variable in Visual FoxPro 6.0 defaults to the Coverage Profiler application, Coverage.app.

Examining Application Coverage and Profile

To use the Coverage Profiler effectively, prepare your application and your environment carefully. If you use the following guidelines, the Coverage Profiler can provide accurate and useful information about your project or application.

To use the Coverage Profiler to examine application coverage

1. Use the Coverage Logging option of the Debugger Tools menu or the SET COVERAGE command to start the coverage data stream and to open the file to log that data.
   
   
2. Run the program or application you want to examine for coverage.
   
   
3. Run the coverage application from the Tools menu or use DO (_COVERAGE) in the command window.

   The Coverage Profiler application starts in Coverage Mode by default.

To use Coverage Profiler to examine application profile

1. Use the SET COVERAGE command to start the coverage data stream and to open the file to log that data.
   
   
2. Run the program or application you want to profile.
   
   
3. Run the coverage application from the Tools menu or use DO (_COVERAGE) in the command window.
   
   
4. Click the Profile Mode button in the Coverage Profiler dialog box.

   If you find that you are most often interested in profiling, you can change the default to Profile Mode in the Coverage Profiler Options dialog box.

To use the Coverage Profiler with a specific log file

Run the coverage application using the WITH option and the log file name as in the following example:

DO (_COVERAGE) WITH "Mylog.LOG"

This example uses the log file Mylog.log and opens the Coverage Profiler application window to display the results. If you specify no file name, the Coverage Profiler uses the log specified in a current SET COVERAGE TO command or displays the Open file dialog box when coverage logging is OFF.

To use the Coverage Profiler without the User Interface

Run the coverage application using the WITH option and specify true (.T.) for unattended mode running as in the following example.

DO (_COVERAGE) WITH "Mylog.LOG",.T.

In this example, the Coverage Profiler application uses the log file Mylog.log and runs without displaying the Coverage Profiler application window.

To use the Coverage Profiler with a specific Add-In file

Run the coverage application using the WITH option and the add-in file name as in the following example:

DO (_COVERAGE) WITH "Mylog.LOG",, "add_ui.prg"

This example uses the log file Mylog.log and opens the Coverage Profiler application window to display the results, and then the Add-In program ADD_UI.PRG runs. The second, unspecified, parameter is a logical value that specifies whether the coverage engine operates in unattended mode. In the default setting, false (.F.), the Coverage Profiler window displays.

Besides viewing the profiler information, you can insert comments or markers and you can save the information as a file to use later.

Modifying the Coverage Profiler

By default the Coverage Profiler application runs in a separate window. You can reconfigure it to run inside the main Visual FoxPro window by changing the Environment Option. In the Coverage Profiler Options dialog box, change the Environment selection from Coverage frame to FoxPro frame, and then restart the Coverage Profiler.

You can also use the Coverage Profiler Options dialog box to modify the following Coverage Profiler characteristics.

Ensuring Relevance in the Coverage Profiler

To help ensure that the files processed by the Coverage Profiler are the correct files:

• Set your project directory as the default before you start coverage logging so that the referenced files are relative.
  
  
• Avoid renaming objects dynamically. The Coverage Profiler will not find objects if you rename them at run time.
  
  
• Avoid using source files with exactly the same root name, even with different extensions. Internally, the Coverage Profiler cannot distinguish between them.
  
  
• Make sure that your project contains only the correct versions of much-modified files.
  
  
• Make sure your project does not contain multiple copies of a file in subdirectories.
  
  
• Perform a compile for the coverage run:
  • Make sure Debug information is in your application.
    
    
  • Turn Encrypt OFF.
    
    
  • Use RECOMPILE or Build All to force a fresh compile of all source code.
    
    
  • Perform the compile immediately before the coverage run so that you know that the source code exactly matches the object code.

Some lines in code, such as comments, DEFINE CLASS and ELSE statements, and lines within TEXT … ENDTEXT do not appear in coverage logs because they are not even potentially executable. Also, lines broken by continuation symbols (semicolons) are considered as a single line of code and marked only on the last line.

Coverage Profiler Add-Ins

Add-Ins are code files (usually .prg or .scx) that provide an easy way for you to adjust the Coverage Profiler. The cov_standard subclass of the coverage engine which comprises the User Interface of Coverage.app shows only a small part of what you can do with the engine. The engine analyzes the coverage log; cov_standard just displays the results in one of many ways you could want to see them.

You could create a different subclass of cov_engine with a very different display. For example, your subclass might display a dialog that runs queries against the coverage statistics gathered by the engine. The display options might provide a view of the marked code for a filtered set of log entries, or only a graph of the profiling results.

You may not want to subclass cov_engine to create a new interface from scratch because the cov_engine class provides an easier process. You can add functionality to cov_standard, or any cov_engine subclass, using Add-Ins. Cov_standard exposes this feature through a button in the main dialog of Coverage Profiler. When you run an Add-In on an instance of cov_standard such as Coverage Profiler, the Add-In can manipulate the capabilities of cov_engine, the coverage tables, as well as cov_standard. Add-Ins might also add new dialogs and features to the cov_standard visual interface.

Writing Add-Ins

You can write Add-Ins to enhance the standard interface or you can subclass cov_standard to create your own wholly new interface.

Enhancing the Standard Application

The following list includes features you might want to provide through Add-Ins:

• Add a visible feature to the main dialog.
  
  
• Add a dialog into the coverage engine formset (reference limitation below on how to make sure your dialog shows up in the right place).
  
  
• Display a separate dialog that accesses a Coverage engine feature (reference limitation below on how to make sure your dialog shows up in the right place).
  
  
• Provide a querying interface that uses the Source table and presents a list of all lines that meet your criteria, and filters or orders the results.

Note   You can use the Adjust… methods (AdjustCoverageFilenameCursor( ), AdjustSourceCursor( ), and AdjustTargetCursor( )) of the Engine to add fields to the Source and Target tables when the engine creates them, and use these fields in your Add-Ins.

• Add file names to the IgnoredFiles cursor, to eliminate those files from analysis. This can save analysis time.
  
  
• Use the special Init hook for Add-Ins.
  
  
• Register Add-Ins for retrieval and easy access to a list of Add-Ins.

  The modal dialog class cov_AddInDialog in the standard coverage engine subclass, presents previously registered dialogs in a drop-down list. When you set the coverage engine lRegisterAdd-In option ON, the full path name of successfully run Add-Ins are added to the Windows Registry so you can easily run these Add-Ins again. The Standard UI class also allows you to set this property in the Coverage Profiler Options dialog box.

  The Coverage Engine object maintains a list of all registered Add-Ins in the aAddIns property.

• Use the final coverage.log field information, callstack, to design your own interface or your own view of the coverage log.

When you write Add-Ins, consider the following information:

• You can use any of the supported file types as Add-Ins. The supported file types are .qpr, .qpx, .mpr, .mpx, .app, .exe, .scx, fxp, .prg and .procedures (if the procedures are already available in an open procedure library).
  
  
• The Coverage Engine formset has an "invisible" toolbar. If your Add-In is nonvisual you can use this toolbar to contain it. If your Add-In is a visual control, the standard subclass main dialog .Cov_tools member container is probably the most convenient place to put it. This allows the position and size to be automatically synchronized with the rest of the dialog when it is resized.
  
  
• All the engine methods that use the Source and Target tables take optional arguments that will allow you to point these methods at the appropriate aliases while you're working with them. You can also change the current cSourceAlias and cTargetAlias property contents to match the pair of cursors in which you are interested. This allows you to compare multiple Coverage log runs to each other within the same interface.
  
  
• Limitations:
  • Add-Ins must accept one parameter (the Coverage engine passes a reference to itself).
    
    
  • An Add-In must be one of the permitted file types, listed above.
    
    
  • Procedures you use as Add-Ins should be available in a currently loaded procedure library (see SET PROCEDURE). The Engine does not use the IN FileName syntax, and it does not call procedures or .prg files as functions and RETURN their values. It does not use the NAME or LINK keywords on the DO FORM command; you can either manage the reference yourself, or allow the Engine to scope a form for you by making your form a member of the Engine formset.
    
    
  • If you run an Add-In at startup, you must use a reference because the public _oCoverage variable is not yet available. At other times, you can use the public variable reference within your own code, if you prefer.
    
    
  • When you write an Add-In as a form, if you create the form as ShowWindow = 1 and run Coverage in its own frame, your Add-In forms should display in the Coverage frame.
    
    
  • If you use .RunAddIn from the Command window, make sure the coverage frame is the active MDI frame before you instantiate your forms.

Subclass Cov_Standard Class

You can subclass either the coverage engine or its standard subclass. The following list describes the structure of the COVERAGE project source file set.

   #INCLUDE COV_CHAR.H

   #INCLUDE COV_LOCS.H

   #INCLUDE COV_DLGS.H

   #INCLUDE COV_SPEC.H

   #INCLUDE COV_REGS.H

The COVERAGE project source file set also includes various .ico .bmp, and .msk files.

Use the file COV_TUNE.H (containing appropriate comments and explanations) to become familiar with options available to you without rewriting code.

Since Add-In use is governed by the coverage engine superclass, any other coverage subclass you create can use Add-Ins in the same manner as the standard subclass.

The coverage engine subclass instantiated by the default Coverage.app does not augment the coverage engine RunAddIn( ) method in any way. It does, however, invoke a modal dialog box to allow the user to pick an Add-In before it invokes the coverage engine RunAddIn( ) method. The modal dialog box receives a reference to the Coverage object and sets the coverage engine cAddIn property.

If you write your own coverage engine subclass, ensure that your subclass can use the same modal dialog class (cov_AddInDialog) to handle Add-Ins as the standard Coverage application; the dialog box does not rely on any features of the standard subclass.

You can call a different modal dialog box, set the cAddIn file name directly in the cAddIn property, or override the contents of the cAddIn property by passing the name of the Add-In file you wish to run to the RunAddIn( ) method.

However you access an Add-In to run in your subclass, you can investigate the list of Add-Ins registered to Coverage.app by checking the file names in the coverage engine aAddIns property.

For details on the Properties, Events, and Methods of the coverage engine, see Coverage Engine Object.

Project Manager Hooks

In previous versions of Visual FoxPro, the only access to a project was through direct table manipulation of the project’s .pjx file. In Visual FoxPro 6.0, you can access a project programmatically, allowing you to manipulate a project as an object. A project can be manipulated at design time while the project is open in the Project Manager, or at design time and run time without the Project Manager visible.

The following are some of the actions you can perform programmatically on a project:

• Add or delete files from a project.
  
  
• Add files in the project to source code control applications (such as Microsoft Visual SourceSafe) and check files in and out of source code control.
  
  
• Determine the number of files in a project and their types.
  
  
• Open and modify files in the project.
  
  
• Change properties of the project.
  
  
• Change properties of files in the project.
  
  
• Change properties of Automation servers (.dll dynamic-link libraries or .exe executable files) built from the project.
  
  
• Execute code when events occur in the project.
  
  
• Rebuild the project, or build .app, .exe, or .dll files from the project.

With the new project manager hooks, advanced developer’s can create their own project managers with unique customized user interfaces.

The Project Object Hierarchy

The object hierarchy for a project consists of the project, a project object, and its associated ProjectHook object. A project object contains a files collection, consisting of files in the project, and a servers collection, consisting of Automation servers created from the project. The following diagrams illustrates the project object hierarchy within the Visual FoxPro object model:

Projects Collection

The projects collection gives direct access to a project object, allowing you to manipulate the project and the files and servers the project contains. A project object is added to the projects collection whenever a project is created, opened or an .app, .dll, or .exe is built from the project.

Like other OLE collections, you can obtain information about a project from the projects collection. For example, the following code uses the projects collection Count and Item properties to display the names of all the projects in the projects collection, and then uses the FOR EACH command to display the same information:

nProjectCount = Application.Projects.Count

FOR nCount = 1 TO nProjectCount
   ? Application.Projects.Item(nCount).Name
NEXT

FOR EACH oProj IN Application.Projects
   ? oProj.Name
ENDFOR

This line of code uses the ActiveProject property to add a program, Main.prg, to the currently active project:

Application.ActiveProject.Files.Add('Main.prg')

This line of code adds Main.prg to the first project added to the projects collection:

Application.Projects[1].Files.Add('Main.prg')

A projects collection has the following properties and methods:

The Project Object

The project object is instantiated whenever a project is opened from the File menu or with the CREATE PROJECT, MODIFY PROJECT, BUILD APP, BUILD DLL, BUILD EXE, or BUILD PROJECT commands. The project object allows you to programmatically manipulate the project, and can be accessed through the Visual FoxPro Application object. Note that the Application object supports a new ActiveProject property that provides a project object reference to the project open in the currently active Project Manager.

A project object has the following properties and methods:

The ProjectHook Object

A ProjectHook object is a Visual FoxPro base class that is instantiated by default whenever a project assigned to the ProjectHook object is opened. (You can include the NOPROJECTHOOK clause in CREATE PROJECT and MODIFY PROJECT to prevent a ProjectHook object from being instantiated for the project.)

The ProjectHook object allows programmatic access to events that occur in a project. For example, you can execute code whenever a file is added to a project.

You can specify a default ProjectHook class for new projects in the Projects tab of the Options dialog box. If a default ProjectHook class isn’t specified in the Projects tab, new projects aren’t assigned a ProjectHook class. You can specify a project hook class for an individual project (overriding the default ProjectHook class) in the Project Information dialog box. At runtime, you can use the ProjectHook property to specify a project hook class for a project. If you change the ProjectHook class for a project, the new ProjectHook class doesn’t take effect until the project is closed and opened again.

A ProjectHook object has the following properties, events, and methods:

Project Object and the ProjectHook Object Interaction

When you open the Project Manager from the File menu, or with the CREATE PROJECT or MODIFY PROJECT commands, the Project Manager window appears and a project object is instantiated with its associated ProjectHook object. Project build commands (BUILD PROJECT, BUILD APP, BUILD DLL, and BUILD EXE) also instantiate the project and ProjectHook objects.

When an event occurs in a project, the project object passes the event to the ProjectHook object. User code in the event in the ProjectHook object is executed and control is passed back to the Project object. The value returned to the project object from the ProjectHook object determines if the project object finishes the operation. Placing NODEFAULT in the event code prevents the default action from being performed. For example, placing NODEFAULT in the QueryAddFile event prevents a file from successfully being added to a project.

Files Collection

The files collection gives direct access to a file object, allowing you to manipulate file objects in a project while the project is open. Like other OLE collections, you can obtain information about a file in a project from the files collection. For example, the following code uses the files collection Count and Item properties to display the names of all the files in the files collection, and then uses the FOR EACH command to display the same information:

nFileCount = Application.ActiveProject.Files.Count

FOR nCount = 1 TO nFileCount
   ? Application.ActiveProject.Files.Item(nCount).Name
NEXT

FOR EACH oProj IN Application.ActiveProject.Files
   ? oProj.Name
ENDFOR

This line of code uses the ActiveProject property to add a file, Main.prg, to the currently active project:

Application.ActiveProject.Files.Add('Main.prg')

This line of code adds Main.prg to the first project added to the projects collection:

Application.Projects[1].Files.Add('Main.prg')

The files collection has the following properties and methods:

File Object

The file object allows you to manipulate individual files in a project.

A file object has the following properties and methods:

Servers Collection

The servers collection gives direct access to a server object, allowing you to manipulate the servers that a project contains. A server object is added to the servers collection whenever a .dll dynamic-link library or .exe executable file containing an Automation server is built from the project. For more information about creating Automation servers, see Creating Automation Servers in Chapter 16, “Adding OLE,” in the Programmer's Guide.

A servers collection has the following properties and methods:

Server Object

The server object lets you determine information (including type library information) about Automation servers contained in a project. This information is also available in the Servers tab of the Project Information dialog box. Note that a server object isn’t created until the project containing the OLEPUBLIC class (specified in the DEFINE CLASS command) is built.

A server object has the following properties and methods:

Project Object Architecture

A Visual FoxPro project object exposes an IDispatch interface so that Automation clients, ActiveX controls, and other COM objects can access the project object through standard OLE interfaces. Because a project object now exposes an IDispatch interface, the errors that can be generated when manipulating projects are OLE errors.

Language Enhancements

Two new clauses have been added to the CREATE PROJECT and MODIFY PROJECT commands. The first clause, NOPROJECTHOOK, prevents the ProjectHook object from being instantiated for a project. The second clause, NOSHOW, opens a project without displaying it in the Project Manager, allowing you to programmatically manipulate the project without displaying it. You can use the Visible property to later display the Project Manager. For more information about these new clauses, see CREATE PROJECT and MODIFY PROJECT.

Project Events

The following sections describe events and the order in which they occur when projects are created, modified, closed, built, and so on.

Creating a New Project

The following events occur when you execute CREATE PROJECT, create a new project from the File menu, or click the New toolbar button and specify to create a new project:

1. The project object is created.
   
   
2. The ProjectHook object is instantiated.
   
   
3. The Init event for the ProjectHook object occurs. If the Init event returns true (.T.), the default, the project is created and the project is displayed in the Project Manager.

   If the Init event returns false (.F.), the project isn’t created, the project and ProjectHook objects are released, and the Project Manager isn’t displayed.

Modifying an Existing Project

The following events occur when you execute MODIFY PROJECT, modify an existing project from the File menu, or click the Open toolbar button and specify an existing or new project:

1. The project object is created. The project object obtains its values from the project’s .pjx file.
   
   
2. The ProjectHook object is instantiated.
   
   
3. The Init event for the ProjectHook object occurs. If the Init event returns true (.T.) (the default), the project is opened for modification in the Project Manager.

   If the Init event returns false (.F.), the project isn’t opened for modification, the project and ProjectHook objects are released, and the Project Manager isn’t displayed.

Closing a Project

The following events occur when an open project is closed:

1. The ProjectHook Destroy event occurs and the ProjectHook object is released.
   
   
2. The Project object is released.

Issuing BUILD APP, BUILD DLL, or BUILD EXE

The following events occur when BUILD APP, BUILD DLL, or BUILD EXE is issued:

1. The project object is created. The project object obtains its values from the project’s .pjx file.
   
   
2. The ProjectHook object is instantiated.
   
   
3. The Init event for the ProjectHook object occurs. If the Init event returns true (.T.), the default, the ProjectHook BeforeBuild event occurs. If NODEFAULT is included in the BeforeBuild event, the .app, .dll, or .exe isn’t built. Otherwise, the build process continues.

   If any files are added to the project during the build process, the ProjectHook QueryAddFile event occurs before each file is added. If NODEFAULT is included in the QueryAddFile event, a file isn’t added to the project. Otherwise, the file is added to the project. When the .app, .dll, or .exe is successfully built, the ProjectHook AfterBuild event occurs, and then the ProjectHook Destroy event occurs.

   If the Init event returns false (.F.), the app, .dll, or .exe isn’t built, and the project and ProjectHook objects are released.

Issuing BUILD PROJECT

The following events occur when BUILD PROJECT with the FROM clause is issued. If the FROM clause is omitted, the events occur in the order described above when BUILD APP, BUILD DLL, or BUILD EXE is issued.

1. The project object is created. The project object obtains its values from the project’s .pjx file.
   
   
2. The ProjectHook object is instantiated.
   
   
3. The Init event for the ProjectHook object occurs. If the Init event returns true (.T.), the default, the files specified in the FROM clause are added individually to the project. The ProjectHook QueryAddFile event occurs before each file is added to the project. If NODEFAULT is included in the QueryAddFile event, the file isn’t added to the project. Otherwise, the file is added to the project.

   The ProjectHook BeforeBuild event then occurs. If NODEFAULT is included in the BeforeBuild event, the project isn’t built. Otherwise, the project is built. When the project build is complete, the ProjectHook AfterBuild event occurs, and then the ProjectHook Destroy event occurs.

   If the ProjectHook Init event returns false (.F.), the project isn’t built. The project and ProjectHook objects are released and a new .pjx file isn’t created.

Using a Drag and Drop Operation

The following events occur when you drag a file or a set of files over the outline section (treeview) of the Project Manager:

1. When the mouse pointer is positioned over the outline section of the Project Manager, the ProjectHook OLEDragOver event occurs with the nState parameter set to 0 (DRAG_ENTER in Foxpro.h). The OLEDragOver event then occurs repeatedly with the nState parameter set to 2 (DRAG_OVER in Foxpro.h). If the mouse pointer moves outside of the outline section of the Project Manager, the OLEDragOver event occurs with the nState parameter set to 1 (DRAG_LEAVE in Foxpro.h).
   
   
2. The ProjectHook OLEDragDrop event occurs if you release the mouse button while the mouse pointer is positioned over the outline section of the Project Manager. By default, Visual FoxPro adds each file dropped on the Project Manager to the project. The ProjectHook QueryAddFile event occurs before each file is added to the project.

Adding a File with the Add Button

The following events occur when you add a file to a project by clicking the Add button in the Project Manager:

1. The Open dialog box appears.
   
   
2. If you select a file and choose OK, a file object is created for the file you select.
   
   
3. The ProjectHook QueryAddFile event occurs and the name of the file object is passed to the event. If NODEFAULT is included in the QueryAddFile event, the file isn’t added to the project. Otherwise, the file is added to the project.

Adding a File with the New Button

The following events occur when you add a new file to a project by clicking the New button in the Project Manager:

1. The appropriate designer or editor for the file is displayed.
   
   
2. When the new file is saved, the Save As dialog box is displayed. Clicking Save creates a file object for the new file.
   
   
3. The ProjectHook QueryAddFile event occurs and the name of the file object is passed to the event. If NODEFAULT is included in the QueryAddFile event, the file isn’t added to the project. Otherwise, the file is added to the project.

Modifying a File with the Modify Button

The following events occur when you modify a file in a project by clicking the Modify button in the Project Manager:

1. The ProjectHook QueryModifyFile event occurs before the appropriate designer or editor for the file is displayed.
   
   
2. The file object for the file to modify is passed as a parameter to the QueryModifyFile event. If NODEFAULT is included in the QueryModifyFile event, the appropriate designer or editor for the file isn’t displayed and the file isn’t modified. Otherwise, the file is opened in the appropriate designer or editor for modification.

Removing a File with the Remove Button

The following events occur when you remove a file in a project by clicking the Remove button in the Project Manager:

1. The ProjectHook QueryRemoveFile event occurs.
   
   
2. The file object for the file to be removed is passed as a parameter to the QueryRemoveFile event. If NODEFAULT is included in the QueryRemoveFile event, the file isn’t removed from the project. Otherwise, the file is removed from the project.

Executing a File with the Run Button

The following events occur when you execute a file in a project by clicking the Run button in the Project Manager:

1. The ProjectHook QueryRunFile event occurs.
   
   
2. The file object for the file to be executed is passed as a parameter to the QueryRunFile event. If NODEFAULT is included in the QueryRunFile event, the file isn’t executed. Otherwise, the file is executed.

Rebuilding a Project or Building a File with the Build Button

The following events occur when you rebuild the project or build an .app, .dll, or .exe from a project by clicking the Build button in the Project Manager:

1. The Build Options dialog box is displayed.
   
   
2. You can choose Rebuild Project, Build Application, Build Executable, or Build COM DLL, and specify additional build options. If you click Cancel, the build doesn’t occur.
   
   
3. The ProjectHook BeforeBuild event occurs if you click OK, and the build process begins.
   
   
4. When the build is completed, the ProjectHook AfterBuild event occurs.

Project Manager Hooks Sample

The Visual FoxPro Solutions Sample application includes a sample named “Track activities in a project” that demonstrates many of the new Project Manager hooks.

To run the Solutions Sample application

• Enter the following in the Command window:

  DO (HOME(2) + 'solution\solution')
  

   – Or – 

1. From the Program menu, choose Do.
   
   
2. Choose the …\Samples\Vfp98\Solution folder.
   
   
3. Double-click Solution.app.

To run the “Track activities in a project” sample

1. After starting Solution.app, double-click New Features for Visual FoxPro 6.0.
   
   
2. Click Track activities in a project and then click the Run Sample button.

The “Track activities in a project” sample allows you to open a project and then manipulate the project in any manner. Any changes you make to the project are stored in a table. When you close the project, you can view the changes you made to the project in a Browse window.

For more information about how the “Track activities in a project” sample works and to take a closer look at the code behind the sample, you can open the form used to create the sample.

To open the “Track activities in a project” form

1. After starting Solution.app, double-click New Features for Visual FoxPro 6.0.
   
   
2. Click Track activities in a project and then click the See Code button.

Acttrack.scx, the form used to create the “Track activities in a project” sample, is opened in the Form designer.

You may also want to take a closer look at the ProjectHook class library, Project_hook.vcx, that is assigned to the project you open in the “Track activities in a project” sample. Most of the code that is executed when project events occur is in the event procedures in this class library. Project_hook.vcx is located in the …\Samples\Vfp98\Solution\Tahoe directory.

New and Enhanced Wizards and Builders

The following wizards and builders are either new or enhanced.

Application Wizard     New

The Application Wizard for Visual FoxPro 6.0 provides support for the enhanced Application Framework and the new Application Builder. You can run the Application Wizard from the Component Gallery or from the Visual FoxPro Tools menu by clicking Wizards and then Application.

Note   The Application Wizard (5.0) from Visual FoxPro 5.0 is available from the Wizard Selection dialog box for backward compatibility.

Connection Wizards     New

The Connection Wizards include the Code Generation Wizard and the Reverse Engineering Wizard. These wizards let you easily manage transfers between Visual FoxPro class libraries and Microsoft Visual Modeler models.

Database Wizard     New

The Visual FoxPro Database Wizard uses templates to create a database and tables. You can also use the wizard to create indexes and relationships between the tables in a new database.

Documenting Wizard     Enhanced

The Visual FoxPro Documenting Wizard now provides an option to use the Code Analyzer as documentation is created.

Form Wizard     Enhanced

The updated Visual FoxPro Form Wizard provides input mask, format, and a field mapping class for specific fields as stored in a database. This wizard also includes more form style options, including scrolling forms.

Graph Wizard     Enhanced

The Visual FoxPro Graph Wizard creates a graph from a Visual FoxPro table using Microsoft Graph. This updated wizard supports the Graph 8.0 component of Microsoft Office 97, including automation of the datasheet and the Series by Row/Col option.

Import Wizard     Enhanced

The updated Visual FoxPro Import Wizard supports Office 97 and Microsoft Excel multisheet handling and provides the option to import a table to a database.

Label Wizard     Enhanced

The Visual FoxPro Label Wizard now includes greater control of label fonts and direct access to the Add Label Wizard.

Mail Merge Wizard     Enhanced

The Visual FoxPro Mail Merge Wizard creates either a data source for a Microsoft Word merged document or a text file that can be used by any word processor. This updated wizard supports the Microsoft Word 8.0 component of Office 97 and true VBA Automation with Application object and collection support.

Pivot Table Wizard     Enhanced

The Visual FoxPro PivotTable Wizard helps you create interactive worksheet tables that summarize and analyze data between two or more fields in a table. This updated wizard supports the Microsoft Excel 8.0 component of Office 97. You can choose either to save a pivot table directly in Excel or to add one as an object on a form.

Report Wizard     Enhanced

The Visual FoxPro Report Wizard now includes advanced grouping and summary functionality so you can more easily customize your reports inside this single wizard. There are also more report styles to choose from.

Remote View Wizard     Enhanced

The Visual FoxPro View Wizard now provides access to System tables so you can use the functionality of ODBC drivers that support these.

Sample Wizard     New

The Visual FoxPro Sample Wizard provides simple steps to creating your own wizard. The output is an HTML file created from records in the data source you specify.

Setup Wizard     Enhanced

The Visual FoxPro Setup Wizard now provides enhanced support for ActiveX controls and override of the Windows file number limit for use in NT setups. It also enables you to add external .DLLs to your application through the setup and to create Web-based installs.

Table Wizard     Enhanced

The Visual FoxPro Table Wizard now provides new table templates, optional style settings, support for both Character and Memo binary data types, and access to databases. You can add your table to a database and you can use database settings to determine the formats of fields you add to your table. You can also establish relationships between tables in the database.

Web Publishing Wizard     New

The Visual FoxPro Web Publishing Wizard generates an HTML file created from records in the data source you specify.

Enhanced Application Framework

The Visual FoxPro 6.0 Application Framework is designed to make it easier to develop Visual FoxPro applications. You can access the enhanced Application Framework through the Application Wizard or through the New Application item of the Component Gallery. This enhanced framework supports the framework available in Visual FoxPro 5.0 including the following:

• A project (.pjx) file.
  
  
• A main program file (Main.prg) for global and environmental settings, launching any Splash Screen or other specific calls, and launching any Quick Start form.
  
  
• A main menu.
  
  
• The Visual FoxPro Framework Application Object for running the main menu, forms toolbars and report management, error handling, and data session management.

The Visual FoxPro 6 framework uses an enhanced Application Object and provides the following additional elements:

• A master Include file that contains the APP_GLOBAL value to ease localization and for use by components with settings and strings.
  
  
• An optional configuration file (Config.fpw) for certain types of applications.
  
  
• Uses the ProjectHook class for control of events related to the project.
  
  
• An Application Meta table to hold information used by the project hook class and application builders for creating forms within the new project.
  
  
• Use the Application Builder to make it easy to add components to the project.

Starting the Application Builder

You can start the Application Builder from the Visual FoxPro Tools menu or from the Component Gallery.

To start the Application Builder from the Tools menu

1. Click Wizards, and then click All.
   
   
2. Click Application Builder from the Wizard Selection dialog box.

To start the Application Builder from the Component Gallery

• Double click the New Application item.

  When you choose OK, the builder closes, applying the property settings from all tabs.

You can also start the Application Builder with a right-click in the Project Manager window, but when opened this way, Application Builder creates only meta tables for your Application — you will see only three tabs in the Application Builder. The only way to provide the full Enhanced Application Framework to your application is through the Application Wizard or through the New Application item of the Component Gallery.

For details on the contents and use of the enhanced Application Framework and the Application Builder, see Developing Applications Using the Application Framework in Help.

Files

Master Include File

This common #INCLUDE file is used by components with settings and strings. The file also includes the APP_GLOBAL value, the name used by components for referencing.

Configuration File

An optional Config.fpw used for applications such as top-level forms in order to implement settings such as SCREEN=OFF.

Project Hook Class

Controls events related to the project such as adding new files. It also can access Application Builder for setting actions and properties of file interaction within the application.

Application Meta Table

Contains information such as project settings made or used by the Application Builder and Project Hooks.

Application Builder

Facilitates adding components to the project and setting properties such as navigation options.

An application framework includes the project file and a starter class library subclassed from the Visual FoxPro base classes, ready for you to populate with new or existing tables and documents.

The framework allows you to specify whether to create a complete application or just an application framework. If you choose to create a complete application, you can either include in the application a database and forms or reports you have already created, or you can create a new application from scratch using a database template. If you choose to create a framework, you can go back later and add components to the framework.

Creating a Framework

You can create an Application Framework by using the Application Wizard or by using the New Application item in the Component Gallery. When you use the Component Gallery, a new project folder item is added to your Favorites folder.

Whichever method you use, Visual FoxPro displays an Application Builder so you can add information to be stored in a meta table.

To create an application

1. From the Tools menu, click Wizards, and then click Application.

   -or-

1. In the Catalogs folder of the Component Gallery, double-click the New Application item.
   
   
2. In the Enter Project Name dialog box,
   • Specify the project name.
     
     
   • Accept or locate the project file.
     
     
   • Choose your options to Create project directory structure (default) and Add to Favorites catalog (default)

For details on the contents and use of the enhanced Application Framework and the Application Builder, see Developing Applications Using the Application Framework in Help.

You can also use the Component Gallery to add forms, reports, data, and service objects to your new application framework and controls to forms.

When you use the Component Gallery to add a form to an application, you can create a new form or subclass from an existing class.