The Project Object Hierarchy

Article
10/23/2006

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 diagram 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 property and method:

Properties
Count

Methods
Item

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:

Properties
Application	AutoIncrement
BaseClass	BuildDateTime
Debug	Encrypted
HomeDir	Icon
MainClass	MainFile
Name	Parent
ProjectHook	ProjectHookClass
ProjectHookLibrary	SCCProvider
ServerHelpFile	ServerProject
TypeLibCLSID	TypeLibDesc
TypeLibName	VersionComments
VersionCompany	VersionCopyright
VersionDescription	VersionLanguage
VersionNumber	VersionProduct
VersionTrademarks	Visible

Methods
Build	CleanUp
Refresh	SetMain

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. This optional object differs from the Project Object, which contains all the properties and methods available in the Project Information dialog box.

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 run time, 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:

Properties
BaseClass	Class
ClassLibrary	Comment
Name	OLEDropEffects
OLEDropHasData	OLEDropMode
Parent	ParentClass
Tag

Events
AfterBuild	BeforeBuild
Destroy	Error
Init	OLEDragDrop
OLEDragOver	OLEGiveFeedBack
QueryAddFile	QueryModifyFile
QueryRemoveFile	QueryRunFile

Methods
AddProperty	ReadExpression
ReadMethod	ResetToDefault
SaveAsClass	WriteExpression

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:

Properties
Count

Methods
Add
Item

File Object

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

A file object has the following properties and methods:

Properties
CodePage	Description
Exclude	FileClass
FileClassLibrary	LastModified
Name	ReadOnly
SCCStatus	Type

Methods
AddToSCC	CheckIn
CheckOut	GetLatestVersion
Modify	Remove
RemoveFromSCC	Run
UndoCheckOut

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 dynamic-link library (.dll) or executable (.exe) file containing an Automation server is built from the project. For more information about creating Automation servers, see Creating Automation Servers in Adding OLE.

A servers collection has the following property and method:

Properties
Count

Methods
Item

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:

Properties
CLSID	Description
HelpContextID	Instancing
ProgID	ServerClass
ServerClassLibrary

Share via