Project Object Architecture

Article
11/14/2006

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:

The project object is created.
The ProjectHook object is instantiated.
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:

The project object is created. The project object obtains its values from the project's .pjx file.
The ProjectHook object is instantiated.
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:

The ProjectHook Destroy event occurs and the ProjectHook object is released.
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:

The project object is created. The project object obtains its values from the project's .pjx file.
The ProjectHook object is instantiated.
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.

The project object is created. The project object obtains its values from the project's .pjx file.
The ProjectHook object is instantiated.
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:

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).
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:

The Open dialog box appears.
If you select a file and choose OK, a file object is created for the file you select.
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:

The appropriate designer or editor for the file is displayed.
When the new file is saved, the Save As dialog box is displayed. Clicking Save creates a file object for the new file.
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:

The ProjectHook QueryModifyFile event occurs before the appropriate designer or editor for the file is displayed.
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:

The ProjectHook QueryRemoveFile event occurs.
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:

The ProjectHook QueryRunFile event occurs.
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:

The Build Options dialog box is displayed.
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.
The ProjectHook BeforeBuild event occurs if you click OK, and the build process begins.
When the build is completed, the ProjectHook AfterBuild event occurs.