The Happy Project Hooker

• Many frameworks (such as Codebook, Stonefield AppMaker, and FoxExpress) created a starting project for an application either by copying a template project file or creating a PJX file from scratch. In either case, the PJX file was opened as a table, and the files it referenced were programmatically altered by manipulating the records based on what should go in the application.
• Tools like FoxDoc and the Documenting Wizard had to open the PJX file as a table to read the contents so they knew which files to document.
• Many developers have written utilities over the years to do things with the files in a project. For example, I've written utilities to open all the "table-based" source code files (SCX, VCX, MNX, and FRX) in a project and pack them to minimize space for transmission or storage, and to ZIP all the source code files for an application for backup purposes. These utilities had to open the PJX file as a table and process the records in it.

VFP 6 changes our approach to projects. There's no longer a need to hack the PJX file, because VFP 6 provides a new interface to projects: Whenever a project is opened, a Project object is now instantiated. Interestingly, Project objects are Automation -- not native VFP -- objects. This has several consequences:

• Errors that occur during Project object manipulation are OLE errors, not VFP errors.
• The Project object model uses more standard property names (for example, Count) than many native VFP objects do (which seem to have a different name for every Count property, such as PageCount, FormCount, ButtonCount, and so on).
• Automation clients and ActiveX controls can access projects through Project objects.
• Properties and members of Project objects don't always show up in the VFP Debugger because, for performance reasons, VFP doesn't read the typelib of Automation objects until a property is actually referenced.

There are two ways you can work with a Project object: through the Application (or _VFP) Projects collection or with Application.ActiveProject. Similar to VFP's Forms collection and ActiveForm property, there's an object reference to every open project in the Projects collection and a reference to the active project in the ActiveProject property. Like ActiveForm, ActiveProject is undefined (the TYPE function returns "U") when there's no open project.

As if Project objects weren't enough, VFP 6 also gives us ProjectHook objects. A ProjectHook object may be automatically instantiated when a project is opened (you have complete control over whether ProjectHooks are used or not), and its events are fired whenever something is done to the project: adding or removing files, modifying or running files, or building the project. ProjectHook is a new VFP base class, so we can create our own ProjectHook classes and put any code into them we want. Thus, we have a hook into the operation of the Project Manager, and we can even completely manipulate projects without using the Project Manager at all.

Because you'll need some background into Project objects and ProjectHooks before you can build some tools using them, this article will have more background than is usual for my articles. Please bear with me; I'll get to the good stuff soon.

Project object model
The object model for the Projects collection and Project objects is shown in Figure 1. As you can see, a Project object contains a reference to a ProjectHook object and has both Files and Servers collections. We'll look at these objects and collections, as well as their properties, events, and methods.

Projects collection
The Projects collection only has one property, Count (the number of Project objects in the collection), and one method, Item (which returns a reference to the specified project). Here are some examples:

? Application.Projects.Count ? Application.Projects.Item[1].Name

Like other collections, you can specify an index to the collection itself rather than having to use the Item method:

? Application.Projects[1].Name

One really cool thing about this collection (and other new collections in VFP) is that you can reference a project by index number or name. Thus, the following code works just fine as long as there's an open project called SOURCE (you must specify the extension or you'll get an error, but you don't have to specify the path):

? Application.Projects['source.pjx'].BuildDateTime

Project object
The properties of Project objects are listed in Table 1; properties common to all VFP base classes are omitted. You'll recognize many of these properties from the Project Info and EXE Version dialog boxes available from the Project Manager. In this table, "Access" is either read-only (R/O) or read-write (R/W), and "Type" is the data type of the property ("L" for logical, "C" for character, "O" for object, and so forth, plus "Coll" for collection).

Property	Access	Type	Description
AutoIncrement	R/W	L	.T. to increment the VersionNumber property when an EXE or DLL is built.
BuildDateTime	R/O	T	The date and time of the last build.
Debug	R/W	L	.T. to include debugging information for each compiled file.
Encrypted	R/W	L	.T. to encrypt files as they're compiled.
Files	R/O	Coll	A collection of File objects.
HomeDir	R/W	C	The home directory of the project.
Icon	R/W	C	The icon used when building an EXE.
MainClass	R/O	C	The name of the ActiveDoc class used as the main program (only used when MainFile contains the name of the VCX where this class is defined).
MainFile	R/O	C	The main program in the project, set using the SetMain method.
Name	R/O	C	The name of the project, including the fully qualified path.
ProjectHook	R/W	O	A reference to the ProjectHook object associated with the project.
ProjectHookClass	R/W	C	The name of the class from which the ProjectHook object is instantiated.
ProjectHookLibrary	R/W	C	The class library in which the ProjectHook class is defined.
SCCProvider	R/O	C	The name of the source code control provider if the project is under source code control.
ServerHelpFile	R/W	C	The name of the Help file for the typelib used for server classes.
ServerProject	R/W	C	The first part of the ProgID for the Automation server created by the project; the default is the same as the Name property.
Servers	R/O	Coll	A collection of Server objects.
TypeLibCLSID	R/O	C	The typelib Registry CLSID.
TypeLibDesc	R/W	C	The typelib description. The default is the name of the project + "Type Library".
TypeLibName	R/O	C	The fully qualified path to the typelib for the project.
VersionComments	R/W	C	Version comments.
VersionCompany	R/W	C	Version company name.
VersionCopyright	R/W	C	Version copyright.
VersionDescription	R/W	C	Version description.
VersionNumber	R/W	C	Version number in Major.Minor.Revision format.
VersionProduct	R/W	C	Version product name.
VersionTrademarks	R/W	C	Version trademarks.
Visible	R/W	L	.T. (the default) to display the Project Manager.

Table 1: Project object properties.

Project objects have the following methods (see the VFP documentation for syntax):

• Build -- This builds the project and returns .T. if successful. Parameters specify the name of the file to build, the type of file (APP, EXE, and so on), whether all files should be compiled, whether errors should be displayed after building, and whether new GUIDs should be generated. The following code builds an APP with the same name as the project:
  
  

  oProject.Build(, 2)

  
  
• CleanUp -- This packs the project and optionally removes object code.
• Close -- This closes and releases the project.
• Refresh -- This refreshes the project by re-reading DBC and VCX files and optionally the source code control status of each file.
• SetMain -- This sets or clears the main file for the project:
  
  

  oProject.SetMain('startup.prg')

Files collection
The Files collection is a collection of File objects, one for each file in a project. It has one property, Count (the number of files in the collection), and two methods, Item (which returns a reference to the specified file) and Add (which adds a file to the project and returns an object reference to it). Here are some examples:

oProject = Application.ActiveProject ? oProject.Files.Count ? oProject.Files[1].Name ? oProject.Files['myclasses.vcx'].Description oFile = oProject.Files.Add('myprogram.prg')

File object
The properties of File objects are listed in Table 2; properties common to all VFP base classes are omitted.

Property	Access	Type	Description
CodePage	R/O	N	The code page for the file.
Description	R/W	C	The description shown in the Project Manager.
Exclude	R/W	L	.T. if the file is excluded from the project.
FileClass	R/O	C	The class a form is based on.
FileClassLibrary	R/O	C	The library the form's class is defined in.
LastModified	R/O	T	The date and time the file was last modified.
Name	R/O	C	The name of the file, including the fully qualified path.
ReadOnly	R/O	L	.T. if the file is read-only.
SCCStatus	R/O	N	The source code control status of the file. "0" means the file isn't source controlled; see the VFP documentation for other values (such as checked out or not).
Type	R/O	C	The file type: V for VCX, P for program, R for report, B for label, K for form, Q for query, L for API library, D for table, d for database, Z for APP, M for menu, T for text, and x for other.

Table 2: File object properties.


File objects have the following methods (see the VFP documentation for syntax):

• AddToSCC -- This adds the file to source code control.
• CheckIn -- This checks the file in.
• CheckOut -- This checks the file out.
• GetLatestVersion -- This gets a local copy of the latest version of the file but doesn't check it out.
• Modify -- This opens the file in the appropriate editor or designer (specify the class name if the file is a VCX).
• Remove -- This removes the file from the project and optionally deletes it.
• RemoveFromSCC -- This removes the file from source code control.
• Run -- This runs the file (preview in the case of reports and labels).
• UndoCheckOut -- This performs an undo checkout.

Servers collection
The Servers collection is a collection of Server objects, one for each Automation server in a project. It has one property, Count (the number of files in the collection), and one method, Item (which returns a reference to the specified server).

Server object
The properties of Server objects are listed in Table 3; properties common to all VFP base classes are omitted.

Property	Access	Type	Description
CLSID	R/O	C	The Registry CLSID for the server.
Description	R/W	C	The server's description in the Registry.
HelpContextID	R/W	N	The help context ID for the typelib.
Instancing	R/W	N	Specifies how the server is instantiated: 1 (the default) for single use, 2 for not creatable outside of VFP, or 3 for multi-instance.
ProgID	R/O	C	The Registry ProgID for the server.
ServerClass	R/O	C	The class name of the server.
ServerClassLibrary	R/O	C	The library the server class is defined in.

Table 3: Server object properties.


ProjectHooks
As I mentioned earlier, VFP has a new ProjectHook base class. A ProjectHook object may be automatically instantiated when a project is opened (you have complete control over whether ProjectHooks are used or not), and its events are fired whenever something is done to the project: adding or removing files, modifying or running files, or building the project. Like Project objects, ProjectHooks are actually ActiveX objects, not native VFP objects.

You can set a ProjectHook for individual projects or globally. To specify which ProjectHook class to use for an individual project, choose the Project page of the Project Info dialog box, and choose the desired class for the Project Class. You can also set the ProjectHookClass and ProjectHookLibrary properties of the Project object, although this won't instantiate the ProjectHook class until the project is closed and reopened. To set a ProjectHook for all projects that don't have individually specified ProjectHooks, use the Projects page of the Tools Options dialog box. You can also instantiate a ProjectHook object and store a reference to it in a Project object's ProjectHook property, but this provides a non-persistent hook to the project.

Once a ProjectHook class has been specified for a project, the ProjectHook object is automatically instantiated whenever the project is opened, and it's destroyed when the project is closed. If you want to open a project but not instantiate the ProjectHook, use the new NOPROJECTHOOK clause of the MODIFY PROJECT command. You can also use NOPROJECTHOOK with CREATE PROJECT to create a project without the global ProjectHook. These two commands have another new clause, NOSHOW, that instantiates the Project and ProjectHook objects but doesn't display the Project Manager, so you can manipulate a project without any user interface at all.

ProjectHook events
ProjectHook objects don't have any properties beyond those of other VFP base classes, but they have several specific events that automatically fire when something is done to the project (see the VFP documentation for parameters these events receive):

• AfterBuild -- This event fires after the project build is complete.
• BeforeBuild -- This event fires before the project build is started, either by clicking on the Build button in the Project Manager, calling the Build method of a Project object, or using one of the BUILD commands. Putting NODEFAULT in the BeforeBuild event of the ProjectHook prevents the build from continuing.
• OLEDragOver -- This event fires when a file is dragged over the TreeView area of the Project Manager window.
• OLEDragDrop -- This event fires when a file is dropped on the TreeView area of the Project Manager window. After this event fires, the QueryAddFile event fires.
• QueryAddFile -- This event fires when a file is added to the project, either by clicking on the Add button in the Project Manager (after the user has chosen the file in the Open File dialog box), by clicking on the New button (after the file is saved and the appropriate editor or designer window is closed), when a file is dropped on the Project Manager window (after the OLEDragDrop event fires), or when the Add method of the Project object's File collection is called. Since this fires after the file has been chosen or created, it can't be used to display a dialog box of which class to create a form from, for example. Putting NODEFAULT in the QueryAddFile method prevents the file from being added to the project.
• QueryModifyFile -- This event fires upon clicking the Modify button in the Project Manager or calling the Modify method of a File object. Putting NODEFAULT in the QueryModifyFile method prevents the file from being modified.
• QueryRemoveFile -- This event fires when the Remove button in the Project Manager is clicked or the Remove method of a File object is called. Putting NODEFAULT in the QueryRemoveFile method prevents the file from being removed.
• QueryRunFile -- This event fires when the Run button in the Project Manager is clicked or the Run method of a File object is called. Putting NODEFAULT in the QueryRunFile method prevents the file from being executed.

Extending functionality
Because a ProjectHook object is automatically instantiated when a project is opened from a user-defined class, and its events are automatically called when something is done with the project, you have the ability to define what happens when the user works with a project. I'm sure you can think of all kinds of things you could do with this capability; I'll discuss some of the ideas I've come up with.

Before I discuss what types of tools you can build, however, keep one thing in mind: Avoid the temptation to build a ProjectHook with everything in it, including the kitchen sink. There are a number of good reasons for making your ProjectHook classes granular:

• Not all functionality might be appropriate for all projects. You might want to vary the behavior of some functions for certain types of projects (for example, typical data entry applications vs. Automation server projects vs. ActiveDoc applications). It'd be an ugly class with lots of CASE statements that had to implement this in one place.
• Using dynamic composition instead of subclassing is cleaner, makes a simpler class hierarchy, and might be the only means possible if someone else wrote a ProjectHook you want to use.
• You might want to give someone else some but not all of the functionality of ProjectHooks you've created, or use ProjectHooks they've created to add new tools to your arsenal without having to modify your own.

There are several ways you can build modular ProjectHook classes and use dynamic composition to put them together:

• You can chain ProjectHook objects together using hook operations. For example, the MyActivityTracker class in the sample files for this article -- available in the accompanying ping, documentation, and so on. These utilities will be much easier to build in VFP 6 because they don't require knowledge of the PJX file and can be executed while the Project Manager is open. Another useful tool would be a project audit utility; it would ensure that every file has its Description property filled in, that the project has the Version properties filled in, and so forth.

Conclusion

Thanks to the new Project objects and ProjectHooks in VFP 6, we can now add to or change the behavior of the Project Manager. This allows us to create tools that give us more capabilities or more productivity than we get with the Project Manager. I expect we'll be seeing a lot of such tools in the months ahead.



Doug Hennig is a partner with Stonefield Systems Group Inc. in Regina, Saskatchewan, Canada. He is the author of Stonefield's add-on tools for FoxPro developers, including Stonefield Database Toolkit and Stonefield Query. He is also the author of The Visual FoxPro Data Dictionary in Pinnacle Publishing's The Pros Talk Visual FoxPro series. Doug has spoken at the 1997 and 1998 Microsoft FoxPro Developers Conferences (DevCon), as well as user groups and regional conferences all over North America. He is a Microsoft Most Valuable Professional (MVP). 75156.2326@compuserve.com, dhennig@stonefield.com.