Skip to main content.

Web Based Programming Tutorials

Homepage | Forum - Join the forum to discuss anything related to programming! | Programming Resources

Special Edition Using Visual FoxPro 6

Special Edition Using Visual FoxPro 6 -- Ch 12 - Organizing Components of an Application into a Project

Special Edition Using Visual FoxPro 6


Chapter 12

Organizing Components of an Application into a Project




Finding your Way Around the Project Manager



The Project Manager is Visual FoxPro's tool for organizing all your application files-forms, reports, menus, programs, include files, graphics, and even data-into a single command center. Most programmers who have worked with FoxPro over the years have grown increasingly reliant on the Project Manager. There are many reasons for this growing relationship. First, many programmers have found that once an application grows beyond the three-program, two-form, one-report stage, its various parts become increasingly difficult to keep track of. The Project Manager enables access to all of an application's files through a single tool. Second, many Visual FoxPro programmers now release their applications as .EXE or .APP files, and the Project Manager makes creating those files a snap. Third, the Project Manager has grown in its functionality and usability, and now, with the release of Visual FoxPro 6, it is a fully exposed object, complete with development hooks to help automate source control and testing.

If you're a current FoxPro developer who hasn't taken full advantage of the Project Manager, there's no time like the present! And if you're new to FoxPro, you'll find the Project Manager a very valuable tool in your effort to keep track of your various application files.

In this section, you'll review each aspect of the Project Manager's interface.

Using the Outline Control

The outline control is the heart of the Project Manager. It's an easy to use, expandable hierarchy that's reminiscent of the Windows Explorer and File Manager tools. A plus sign icon indicates that there are hidden levels that can be uncovered with a click. Clicking a minus sign icon hides all the nested, subordinate levels.

Creating a new project in Visual FoxPro is easy. Just select New, Project from the system menu, or type Create Project in the Command window. When you are prompted for a filename, enter a name and press OK. The Project Manager will appear (see Figure 12.1).

Figure 12.1 : The Visual FoxPro Project Manager enables you to access all your application's files through one central tool.

You can create a project as a late step in your application design and add existing files at that point. But to really take advantage of this tool, you should use it while you code and design, not after. I like to create a project at the same time as I create directories, and even before I create a main program for the application.

Types of Files Included in the Project Manager

The Project Manager window is reminiscent of the Properties window in the Form and Class Designers (and in the Data Environment of the Report Designer). Six different tabs are available, each of which shows a different subset of file types. The All tab, not surprisingly, shows all the project files. Let's take a moment to review each of the other tabs.

The Data Tab  The Data tab includes all databases, free tables, and queries (see Figure 12.2). It might shock you to learn that you can include data files in a project. But Visual FoxPro enables you to do so, which makes it easy to keep track of and quickly access the data your application runs against.

Figure 12.2 : The Data tab includes all the data elements in your applications, including databases, free tables, and queries.

The Databases icon expands to show any databases in your project, but it doesn't stop there! The database icons each expand to differentiate among tables, local views, remote views, ODBC connections, and even stored procedures. Wherever possible, the Project Manager keeps expanding, showing more and more detail. So, for example, the Tables icon expands to show each table, and each table expands to show each field and index (see Figure 12.3).

Figure 12.3 : By expanding the icons on the Data tab, you can see each table in your application and even each field and index within tables.

Notice the small icon to the left of each table entry (a circle with a slash through it, known as the Exclude icon). This icon indicates that the file will not be included in any compiled .APP, .EXE, or .DLL created from the project. You'll learn more about compiling projects later in this chapter, but for now, keep in mind that there are some data or files you will probably distribute separate from your .EXE or .APP. Data files are a good example, and Visual FoxPro defaults to an exclude mode for these files. But you can also exclude other files or choose to include data files. Just choose Project, Exclude or Project, Include.

The Documents Tab  The Documents tab includes all document-style files, namely, forms, reports, and labels (see Figure 12.4). Again, expanding any of these icons results in a listing of all files of that type.

Figure 12.4 : The Documents tab shows all forms, reports, and labels in your application.

The Classes Tab  The Classes tab includes all class libraries (see Figure 12.5). Class libraries can be expanded to show all member classes.

Figure 12.5 : The Classes tab shows all class libraries in your application.

The Code Tab  The Code tab shows all programs, API libraries, and applications (see Figure 12.6).

Figure 12.6 : The Code tab shows all programs, API libraries, and external applica-tions.

The Other Tab  The Other tab shows all other types of Visual FoxPro files, such as menus, text files, or graphics files (see Figure 12.7).

Figure 12.7 : The Other tab shows all miscellaneous Visual FoxPro or external files.

TIP
Text files usually consist of Include files, but can also include programmer documentation and tips. And remember, you can choose to exclude such files before compiling a program file by selecting Project, Exclude.

Taking Advantage of the Project Manager's Functionality

If the Project Manager stopped there, it would still be useful; all the files you need are stored together in a nice hierarchical fashion, providing a self-documenting file management system. But the Project Manager also includes six buttons that are always present, no matter which tab or level of the hierarchy is selected, to enable you to modify, add, delete, or run files. These buttons will be enabled or disabled depending on what kind of file and level of hierarchy are selected. Here's a brief description of each:

TIP
Some programmers find these options so useful that they find themselves never, or rarely, typing commands such as MODIFY FORM or Do Program File. Others mix and match techniques. Visual FoxPro lets you decide which approach works best for you and your team.

Creating Files Through the Project Manager

You can create any type of Visual FoxPro application file right from the Project Manager. Let's take a look at creating a program file. Click on the Code category and expand it. Visual FoxPro's Project Manager enables you to differentiate among three different types of code: programs, API libraries, and external applications (see Figure 12.8). Highlight Programs and click the New button to create a new program. A new program, with a default name of Program1, will appear (see Figure 12.9). Don't worry about the title in the Code window; when you save this program, you will be prompted for a more sensible name.

Figure 12.8 : You can expand the Code icon-or any icon-to indicate exactly what kind of file you want to add or create.

Figure 12.9 : Creating a new program launches the Visual FoxPro Code window.

After you save the program, you can expand the Code, Programs outline branch to see it and any other programs you add to the project.

TIP
You can expand or contract categories either by double-clicking the heading or by clicking the plus or minus icons.

NOTE
The very first program you create or add to the project is listed in bold type (see Figure 12.10). This indicates that the program is the main point of entry into the application, and it will be the first program code that fires when you start an application or project that you've created. You can always decide to use a different main program later by clicking on the file to highlight it and then selecting Project, Set Main.

Figure 12.10: The main program, or starting point, of your application is listed in bold type.

Just as you use the New button to create a program file, you can use it to create a new form, menu, report, text file, or any other type of file. When you press the New button, Visual FoxPro looks at the file type selected and takes the appropriate behind-the-scenes action (Create Form, Modify Command, Create Report, and so on).

TIP
You can include descriptions for each file in the project by highlighting the file and choosing Project, Edit Description.

Adding Existing Files

You can also include preexisting files in your project. Just highlight the type of file you want to add and click the Add button. You'll be prompted to select an existing file from a GetFile() dialog box.

TIP
Remember that you can include the same file in several projects. The Project Manager just points to the underlying file. This is an extremely helpful tool for maintaining and making good use of reusable code and class libraries. But there's a downside: Remember that any changes you make to a program file, for instance, are reflected in any other projects using the program.

If you have decided to create a new project from a series of existing files and you're worried about having to add a hundred files in the manner demonstrated above, stop worrying! Just add the main file and when you rebuild the project (discussed below), Visual FoxPro will draw in any other called files. Of course, you might need to add a few references that Visual FoxPro could not pick up (such as any program that is called via macro-substitution, for instance), but you'll certainly get a running start.

Modifying Files

The Modify button, like the Add button, provides access to the native editor of the element you have highlighted. A Code window is brought forward for programs, the Form Designer for forms, and the Menu Designer for menus.

Visual FoxPro even activates the appropriate editor when you select an OLE component. Figure 12.11 shows what happens if you highlight a bitmap file and click Modify. This feature demonstrates the remarkable strength of the Project Manager. As the quantity and variety of multimedia, hypertext help, and other features in your applications increase, you will certainly be thankful for the ability to modify these files from one central development tool.

Figure 12.11: Whenever possible, Visual FoxPro lets you modify an OLE component through the associated application.

Running Programs and Forms and Previewing Reports

When you highlight a project element and press Run, Visual FoxPro runs the program or form for you.

This button's caption changes to Preview when you select a report. Of course, a particular program, form, or report can depend on certain variables or settings that might not be present. In that case, you might experience runtime errors. But, often, this is an extremely useful feature.

This button's caption changes to Browse when you select a table or a field. Clicking Browse will activate a browse window so that you can look directly at the table.

Removing Files

If you've worked with other project managers, you've probably been frustrated by the two-step (or more) process required for cleaning up and maintaining projects. After removing the file from the project, you still have to delete the actual file from disk. Visual FoxPro lets you handle both of these tasks at once. Just select the file and click Remove, and you will see the dialog shown in Figure 12.12.

Figure 12.12: The Visual FoxPro Project Manager lets you remove a file from the project and even delete it from disk.

CAUTION
While this procedure is very convenient, exercise caution! If there is any chance that the project might be associated with another project, choose to remove the file rather than deleting it entirely. (Of course, it's good practice to back up your files periodically, anyway.)

TIP
The project files are actually special instances of .DBF and .FPT files. The Remove option deletes the element's particular record, but doesn't PACK the table. When you select Project, Clean Up Project, Visual FoxPro executes a PACK against the table.

Dragging and Dropping Project Elements

The Project Manager makes extensive use of drag-and-drop technology. With a little experimenting, you'll get a sense of just how powerful this feature will be in your development. For instance, you can drag and drop a control from one class library to make a copy of it in a second library. You can also drag a control from the Project Manager and drop it into the Form Designer to include an instance of it on a form.

Collapsing and Docking the Project Manager

For all its usefulness, the Project Manager is a big bulky window to have sitting on your desktop throughout your development. You can resize the window to some degree, just as you can most Visual FoxPro tools, but that's probably not enough in all cases. Fortunately, there is an alternative.

Click the up-arrow button in the upper-right corner (below the Close button) and the Project Manager is minimized. Only the tops of the tabs remain visible. This doesn't mean you've lost any functionality, though. If you click a particular tab, the tab expands downward and all your functionality returns. Figure 12.13 shows the Code tab dropped down. You can also continue to use the Project menu and right-click for certain shortcut options.

Figure 12.13: Even when the Project Manager is minimized, all its options are available to you.

In this collapsed state, the Project Manager is a toolbar. If you drag it to the top of the screen, it docks there like any other toolbar. Additionally, you can drag a tab off the collapsed Project Manager down onto the Visual FoxPro screen. These torn-off tabs enable you to see only the parts of the Project Manager that you need. Figure 12.14 shows the Classes tab torn off; the rest of the Project Manager sits docked at the top of the screen. If you click the pushpin in the top right corner of the tab, it will stay on top. Just click it again to toggle it off and enable other windows to be moved above it.

Figure 12.14: You can tear off one tab of the Project Manager and place it anywhere in your Visual FoxPro environment.

TIP
Torn-off tabs are particularly useful when you use the Form Designer. You can keep the Classes tab visible and active and drag classes into the Form Designer canvas.

The Project Information Dialog Box

The Project Information dialog box can be brought up by choosing Project, Project Info. The dialog box includes three tabs.

The Project tab enables you to specify information on the developer or company (see Figure 12.15). This tab also includes a setting for the home directory of the project and several compilation options, such as whether debug information is included and whether the compiled code is compiled. The Project Class check box and text box enable you to specify a ProjectHook class (the new project hook functionality is covered later in this chapter).

Figure 12.15: The Project tab holds information on the developer or company.

The Files tab includes a complete listing of all files in the project, the dates they were last modified, whether they are included, and the code page for the file (see Figure 12.16).

Figure 12.16: The Files tab includes a quick reference list of all files in your project.

NOTE
If the Included check box is blank, it is not included in any compiled .APP, .EXE, or .DLL files. If the check box is marked with an X, the file is included. If the check box is completely filled in, the file is the main file of the project. Remember, you can set the main file by highlighting the new main file in the Project Manager and choosing Project, Set Main.

The Servers tab includes information on any classes (whether defined in code or visually) that are marked as OLE Public (see Figure 12.17). When you highlight a listed item, you see the library name and the name of the class. Also displayed is a description of the class name and a description of the library the selected class is based on. If you create your own help files and topic IDs, the filename and context ID are also shown. The public class's project name is displayed in the Project name box. The Instancing pull-down menu offers three choices:

Figure 12.17: You can access information on OLE public classes through the Servers tab.

Building Visual FoxPro .APP, .EXE, and COM .DLL Files

The Project Manager makes creating an application or executable file from your various program and document files a breeze. Just click the Build button on the right of the Project Manager. The dialog box shown in Figure 12.18 appears and enables you to choose from the following options:

Figure 12.18: The Project Manager lets you rebuild the project, build a Visual FoxPro .APP file, or build an .EXE.

During any of the processes listed above, Visual FoxPro recompiles or regenerates any files that have been modified since the last build. The Recompile All Files option will force a recompile of all the files.

TIP
Visual FoxPro does a pretty good job of knowing which files have to be recompiled, and as a result, I usually let it take the wheel and decide for itself what to recompile. But now and then, a file does not recompile (usually due to some action I've taken, such as restoring a backup .PRG without the corresponding .FXP). So, every few compiles, and definitely before I send anything out the door, I execute a recompile with a Rebuild All.

Visual FoxPro always maintains a log of compilation errors in a file with the same base name as your project and an .ERR extension. You can (and should) view this file right after a recompile by clicking the Display Errors option.

If you want your application to run right after the build, select the Run After Build option.

A Note on the Main File

As I discussed earlier in this chapter, the main file of your project is the file that gets called when a client runs your .APP or .EXE. It is easier to see in the list of Project Manager elements because it is always listed in bold. Although it can be a form, menu, or program, it is definitely best to make it a program. This program can be a very simple calling .PRG, but it will make your life much easier than starting with a form or menu. For instance, at its most simple, a main program might look something like this:

* setup code
DO MainMnu.MPR          && the menu code
DO Form StartUp.scx     && startup form
READ EVENTS             && VFP's internal event loop (kind(c)
* cleanup code

Including and Excluding Files from .APPs and .EXEs

Including and excluding files is sometimes a source of confusion, particularly for those new to Visual FoxPro. But it's really quite simple: Although you might want every file in your project to end up on clients' machines, you won't necessarily want them all to arrive there embedded in the .APP or .EXE. To begin with, anything included in the .APP or .EXE is read only, which means that some types of files should never be included.As a result, Visual FoxPro, by default, excludes databases, tables, .FLLs, .DLLs, and .APPs.

Wait a minute! It's easy to see why databases and tables shouldn't be included because you don't want them marked as read only, but why exclude .FLLs, .DLLs, and .APPs? Well, in those cases, the issues are more of a technical nature, and they have to do with the very nature of dynamic link libraries. Windows must be able to load a .DLL in to memory whenever it needs to, and if the files were embedded in your .APP or .EXE, that wouldn't be possible.

You'll have to make sure that you include any of these non-embedded files when you distribute your application. Fortunately, the Setup Wizard makes this easy to do.

You might also want to exclude Report Forms or other files that your clients might want to modify themselves. Even if your clients don't modify the reports you design for them, you might choose to deliver them separately as a part of your implementation strategy. Excluding reports will make your .APP or .EXE smaller, which means it will transmit more quickly. And, if you edit one report, you won't need to recompile and resend a large executable. Your decisions on which files to include will be based in part on your client base and the size and scope of your applications.

CAUTION
You can also create projects, .APPs, and .EXEs right from code, although there are very few reasons to do so. The BUILD PROJECT, BUILD APP, and BUILD EXE commands will do in code what you've already done in the examples above. But beware of the BUILD PROJECT FROM command! Build Project MyProj will rebuild the project, but Build Project MyProj from Main will overwrite the current project with a brand-new one, with Main.prg at its center. That is probably not the behavior you desire.

Building Setup Disks to Distribute your Application

Creating setup disks is the final step in producing an application. But keep in mind that it is the first part of your product that your customers will see. And in this age of slick programs and rising user expectations, first impressions count.

Of course, programmers would rather put their time and energy into actual application development than slick setup procedures. And in fact, that should be the case. Fortunately, Visual FoxPro makes it easy to create professional setup programs without too much time or effort.

A slick interface is not the only reason to use Visual FoxPro's Setup Wizard. The simple fact of the matter is that a Visual FoxPro application is not a simple system to install. Gone are the days of batch files, a standalone .EXE, and a simple overlay file. These days, you need to install-and in many cases register with the operating system-the runtime modules, OLE files, .DLLs, and maybe even ODBC drivers.

At first glance, all of this might make you yearn for simple ZIP files and DOS paths. But then again, that would leave us with blue screens and modal forms. Visual FoxPro's power comes with a cost, but fortunately, Visual FoxPro comes with a powerful tool to assist you: the Setup Wizard.

Specifying Files to Include

Run the Setup Wizard after you build your .EXE. Then move the .EXE and any other files you want to distribute (reports, ReadMe.TXT files, and so on) to a separate subdirectory from the project. This subdirectory should include only the files you want to distribute and nothing more. To start the Setup Wizard, select Tools, Wizards, Setup, which brings forward the first page of the Setup Wizard (see Figure 12.19). This page requests one crucial piece of information: the directory location of the files you want to install. Press the ellipsis button to select a directory.

Figure 12.19: The first screen of the Setup Wizard requests the source directory for your setup files.

Specifying Components to Include

The second page of the Setup Wizard enables you to specify the components that must be distributed along with your executable file (see Figure 12.20). You will most likely want to include the Visual FoxPro 6 runtime (unless you know for sure that your users already have a Visual FoxPro 6 application installed on their machines). The chances are good that you will also want to include one or more other components. If your application includes graphs, select the Microsoft Graph 8.0 runtime option. If you use ActiveX components, ODBC connections, or HTML help, select these options.

Figure 12.20: The second screen of the Setup Wizard enables you to specify the additional system components that .EXE users require.

Notice that any of the check boxes with an ellipsis will prompt you for additional information. For example, when you click the ActiveX Controls option, Visual FoxPro will search your Registry for any current ActiveX components and bring forward a modal dialog box from which you can select any and all applicable items (see Figure 12.21).

Figure 12.21: The ActiveX Controls option enables you to specify which ActiveX controls are included in your application.

Specifying Location of Setup Images

The third screen of the Setup Wizard enables you to choose the location for your installation images or directories and the type of installation images you would like to create (see Figure 12.22).

Figure 12.22: The third screen of the Setup Wizard requests a target directory for your setup files.

NOTE
Creating setup files requires a file management decision, and maybe even an overall file management strategy. As I mentioned, you should not place the files you want to distribute in the same directory path as your actual project. In addition, you don't want to place the setup images in the same directory as the files. I keep a Setup Disk folder on my C:\ drive with a separate directory for each project. Each project folder, in turn, has two branches: Files and Distrib. You might find that some other approach works for you, but the important thing is to put at least a bit of thought into your strategy.

The type of installation image you want will depend on your distribution strategy. If you are distributing your application via several disks, choose the 1.44 Diskette option and Visual FoxPro will divide the files for you into several subdirectories, each representing one disk. This makes it easy to copy each directory directly to a disk. But, whenever possible, use the Websetup or NetSetup options. They each put all the setup files into one directory: Websetup compresses them a bit more tightly.

TIP
If you plan to distribute your application via CD-ROM, the preferred approach is probably NetSetup. After the files have been created, write them onto your CDs.

Specifying Setup Program Information

The fourth step in the Setup Wizard involves providing information that will be seen by the user during the setup (see Figure 12.23). This is a good place to include the application name, your company's name, and any copyright information. You can also choose to run a particular .EXE after the setup has completed on the client's machine. This might be a demo or a program that augments the setup functionality. In object-oriented terms, it is a hook process that runs after the main setup is complete.

Figure 12.23: The fourth screen of the Setup Wizard lets you provide information to users during the installation process.

TIP
If you distribute your application via CD-ROM, you might consider writing a small program that sets the appropriate files back to a read/write setting. You could run this program right after setup by specifying it as the Post-setup executable.

Specifying the Application's Directory and Program Group

The fifth step of the process enables you to specify a default application destination and Windows program group (see Figure 12.24). You can also specify whether your customers can override your defaults. Your users will most likely have their own ideas on where application files should reside and from which branch of the Windows Start and Program menus they will call the program. You should make every attempt, during your programming as well as your setup disk creation, to permit them to do so. The boost in client relations will probably be well worth the additional programming cost. I know many computer users and very many IS professionals who raise their eyebrows at any application that insists on loading into a specified directory.

Figure 12.24: The fifth screen of the Setup Wizard lets you specify the default Windows group and application destination.

Specifying File Directories

The sixth step in the process enables you to direct the ultimate destination of each of the files you are distributing (see Figure 12.25). You can choose to place a file in the Application directory, the Windows directory, or the Windows\System directory. The PM Item check box lets you add multiple icons to the program group from the same setup disks. For example, you might want your program group to include not just the icon for the application itself, but an icon for the Readme file. In that case, just click the PM Item check box for the Readme.txt file. You then can specify a name and an icon (see Figure 12.26).

Figure 12.25: The sixth screen of the Setup Wizard lets you specify different target directories for files in your application.

Figure 12.26: The Icon option lets you specify names and icons for the various Project Manager items that you install.

Launching the Setup Wizard

The seventh and final step puts FoxPro to work creating your files (see Figure 12.27). But first, you can specify whether to create a Web executable. This is a nice way to enable installation of an application right from your Web site, rather than requiring your users to first download your setup files. This approach is very slick and avoids the problem of setup files cluttering your users' disks following a standard NetSetup or Websetup download. On the other hand, remember that setup speed will vary by Internet connection speeds.

Figure 12.27: The final screen puts the Setup Wizard in motion creating and compressing the necessary files.

This screen also enables you to create dependency (.DEP) files. Select this option if you are including new ActiveX files among your distribution files or if the version of the ActiveX file you are installing might be newer from the one already on the client computer. This will help ensure that the ActiveX component is installed and registered correctly.

Press Finish and Visual FoxPro will build your image files (see Figure 12.28). The wizard does this in four passes:

Figure 12.28: The Setup Wizard lets you know its progress during file creation.

Don't be alarmed if the Setup Wizard takes a while to run. Remember, it's doing an awful lot behind the scenes.

Using Visual SourceSafe for Version Control in Team Development

One of the biggest headaches with a large product is managing the development and keeping track of changes to the source code. From one point of view, thorough object-oriented programming complicates this even further: If you have several objects designed to send messages back and forth to one another, and one of your programmers changes one object, the entire scheme can fall apart. Unless you've instituted a source control scheme, you might find it impossible to track down the rogue code (or the guilty programmer). Fortunately, Microsoft has a product that can be integrated quite tightly and smoothly with Visual FoxPro's development environment (and in particular the Project Manager).

Integrating Visual SourceSafe with your Visual FoxPro Project

It's beyond the scope of this book to provide a complete discussion of source control tools, or even Visual SourceSafe itself. But source control is such an important part of team development that I hope to provide you with enough information to begin incorporating it into your projects. It can be quite comforting to have Visual SourceSafe looking over Visual FoxPro's shoulder during your development, helping to manage the process of team programming.

All you really need to do to get up and running is install VSS, with the server installation, on the server where the master files will be stored. Then install VSS for each client (that is, each programmer). After successful installations, Visual FoxPro 6 adds VSS to the source control options in the Tools, Options dialog box's Projects tab, as shown in Figure 12.29. From here, select Visual SourceSafe and set it as your default source control manager.

Figure 12.29: You can choose how tightly to integrate Visual FoxPro and Visual SourceSafe in your development environment.

The additional options shown in Figure 12.29 in the Source Control Options area are essential to your VFP/VSS configuration. With them, Visual FoxPro defines whether files should be automatically checked out on modification, included in source control on addition to your local project, or removed from source control on removal from your local project. You are also given the option to automatically add new projects to source control. Don't worry: Even if you don't choose to add this feature, you can always go back and add an existing project to Visual SourceSafe.

The Projects tab of the Options dialog box consists mainly of source control configuration items, but there are four other options.

Project Double-Click Action indicates what action should occur when you double-click a file inside the Project Manager. The default behavior is to modify the selected file, but you can change the setting so that the file runs on a double-click.

Prompt for Wizards indicates the action Visual FoxPro takes when you click the New button on the project. If this option is turned off, you proceed right to the appropriate editor for the file type. If this option is on, Visual FoxPro determines whether any wizards exist for the file type, and if so, gives you the choice of using them.

Display User-Defined Container Icons indicates whether or not the icons shown should be the default Visual FoxPro icons or user-defined and assigned icon files.

Project Class indicates a class to be used as the project hook. Project hooks are covered later in this chapter. Visual FoxPro 6

Creating a Source Control Project

As long as you have chosen to automatically add projects to source control, any project you create will automatically be managed by VSS based on the options that you have set. But as I noted earlier, if you want to go back and add an existing project to source control, that's easy, too. Just open the project you want to add and choose Project, Add Project to Source Control. You will be prompted for a login (see Figure 12.30). If you have not yet added usernames and passwords through the server version of VSS, just enter a login name of Guest, keep the password blank, and click OK.

Figure 12.30: You can choose to include login security to Visual SourceSafe.

NOTE
The Database text box in this dialog box has nothing to do with your Visual FoxPro databases or tables. Instead, it indicates the VSS database that will hold this project. The default setting is the Common database.

Figure 12.31 displays the Visual Sourcesafe dialog box for adding a project to source control. Click Create and then click OK. You will have the opportunity to enter a comment (see Figure 12.32). After entering a comment and clicking OK, you will be presented with a list of files from your project. Choose which of these should be kept under source control by clicking the check boxes to the left (see Figure 12.33).

Figure 12.31: It's easy to add a project to Visual SourceSafe control, even right within Visual FoxPro.

Figure 12.32: You can include comments on each project you add to Visual SourceSafe.

Figure 12.33: You can pick and choose which of your Visual FoxPro project files should be included under Visual SourceSafe version control.

That's all there is to it! When you return to your project, any files that are under source control are displayed with a lock icon beside them. Whenever you modify a file, it is checked out by Visual FoxPro and the lock turns into a check mark. Figure 12.34 shows these icons in action.

Figure 12.34: Visual SourceSafe's lock and check mark icons provide visual clues to the status of your files.

Files you have checked out remain checked out until you either check them back in or undo the checkout. Either of these actions can be performed by right-clicking the file and selecting the relevant shortcut option. When you check in a file, you are offered the chance to enter comments on the file or files you are checking in (see Figure 12.35). Try to determine a convention, with your team where applicable, and take care to follow it. Your comments will probably include your name or initials, the date, and perhaps some form of tracking ID. You might also include a brief synopsis of the changes you have made. The Keep Checked Out box will check in your changes, making them available to other programmers, but will keep the file checked out under your name.

Figure 12.35: Many development teams encourage comments for each check-in (such as programmer name, a tracking ID, and a summary of changes made).

A Closer Look at Visual SourceSafe Terminology

Because both Visual FoxPro and Visual SourceSafe have collections of files called "projects," the terminology can get a bit confusing. In Visual SourceSafe, a project is a collection of files that you store under lock and key, checking them out in small bunches. These files are stored in Visual SourceSafe databases. Managing these files is accomplished through different combinations of the actions listed below. You'll find these options, and some lesser-used goodies, in several places in the Project Manager: the Project menu bar, the right-click shortcut menus, and even the Tools, Options menu:

TIP
As you work with Visual SourceSafe through the Project Manager, it tracks its actions through commented lines in the Command window. This is a useful feature because it keeps an instant log of your session.

Figure 12.36: The Show History screen enables you to pin a file, causing it to remain static in the project, even if it is changed in other projects.

TIP
Because Visual FoxPro 6 is so well-integrated with Visual SourceSafe, you might never need to enter VSS through its own icon. But there are some options in Visual SourceSafe that you cannot access through Visual FoxPro, so I suggest giving VSS a whirl when you're feeling adventurous. And, needless to say, the server version of VSS includes many features not available through VFP or the client copy of Visual SourceSafe.

Accessing the Project Manager as an Object

The discussion so far has focused on using the Project Manager as a visual development tool, enabling programmers to interactively run, edit, and check out files, and making it easier to create compiled applications and executable files. But there are many facets of the Project Manager above and beyond what I've discussed. After all, everything I've talked about so far has been useful and interesting, but it involves an awful lot of clicking, doesn't it? And, if you are working in an environment where you create large numbers of small applications, you probably don't want to dig in to your precious time by creating new project files every week. You want a template or some other way to speed the process. Finally, if you are a team leader or senior programmer working with a crew of less experienced VFP programmers, you might want some way to automate some of the Project Manager's functionality or protect against its misuse.

Fortunately, with Visual FoxPro 6, the Fox Team at Microsoft has greatly enhanced the Project Manager by exposing it as a full-fledged object.

The Project Manager Object Design

You might never need to access the properties or methods of the Project Manager, and that's just fine. FoxPro programmers have done so for years and have still made great use of many facets of the Project Manager's functionality. But, you've also gotten used to jumping through hoops to make this tool even more useful, or to fill in the gaps between its functionality and your needs.

As of version 6, Visual FoxPro fills in many of those gaps by enabling direct access to the Project Manager as an object (more specifically, as an OLE object). Figure 12.37 shows the Project Manager as it appears in the debugger.

Figure 12.37: You can view the exposed properties of the Project Manager by referencing it in the debugger.

Accessing Project Methods and Properties

The Visual FoxPro application object (which can be referenced as _VFP or Application) now includes a new collection: Projects. It also includes a new object property, ActiveProject, which holds a reference to the current project.

To access a project, you can use the Count property or the Item method of the Applications.Projects collection. Or, you can use the Application.ActiveProject reference. The following two lines of code generate the same result as long as Darts.PJX is the only currently active project:

? Application.ActiveProject.Name
? Application.Projects[1].Name

If you have more than one project open, however, the Projects collection offers an advantage over the ActiveProject reference: It enables you to access all open projects as you would any other collection. For example, the following code is perfectly valid and will rebuild every open project:

FOR EACH oProject IN Application.Projects
     OProject.BUILD()
ENDFOR

Project Properties and Methods

Visual FoxPro's Project object includes over 25 properties, five methods, and two collections, all of which you can access programmatically just as you would with any other object. Some of the most useful properties include the following:

TIP
The Project object also includes a family of Version* properties that hold your company name, comments, copyright information, description, version number, product, and trademarks.

Project also includes among its methods the following useful processes:

TIP
If you have a Cleanup.PRG or similar environment-clearing program or a Visual FoxPro backup routine, consider including calls to any open projects' Cleanup methods.

NOTE
The Project Manager uses a table to hold the information on its files (the table extension is .PJX and the associated memo field is held in a .PJT file). Many of us who worked with pre-Visual FoxPro 6 projects became somewhat used to opening these tables interactively to hack away-this was pretty much the only way to edit properties-or else we would open them in code to copy the projects to new locations, or create new projects from templates. With Visual FoxPro's new Project object model, there's no need to do this anymore (which is fine, because it never sat well with most of us to begin with). If your curiosity gets the best of you, you can still open project files as tables by executing a USE ProjectName.pjx command, but exercise caution. A hosed project is no fun at all.

File Properties and Methods

Your access to the Project Manager doesn't stop at the project itself! The Project object also includes two collections, Files and Servers. The Files collection holds one object for each file in the project. The Servers collection holds an object reference for every OLE Automation server in the project.

Most programmers will spend more time accessing Files properties than Servers properties. Here are some of the more useful Files properties:

     B           Label
     d           Database
     D           Table
     K           Form
     L           API Library
     M           Menu
     P           Program file
     Q           Query
     R           Report
     T           Text
     V           Class library
     X           Other (including bitmaps)
     Z           App

As with Project itself, the Files object includes a number of useful methods:

With these exposed methods and properties, you can easily write quick utilities to rebuild projects (no more worrying about the steps you've missed). Below is some very basic code that gets the latest version of every file and recompiles the project. If you've ever struggled with a team recompile, you'll recognize the strengths of this approach.

* get the latest version of every file
For each oFile in APPLICATION.ActiveProject.Files
     oFile.GetLatestVersion()
* Let's exclude all tables and databases
IF UPPER(oFile.Type) = "D"
oFile.Exclude = .T.
ELSE
oFile.Exclude = .F.
ENDIF
endfor

* now, clean up the project. No need
* to have deleted references clogging
* everything up
APPLICATION.ActiveProject.CleanUp()


* Finally, build the project.
APPLICATION.ActiveProject.Build("AutoBuild.APP",2)

* And, always view the error log!
MODI COMM AutoBuild.Err

Of course, you can (and will definitely want to) go much further. You should check for errors from each method, for example, and you will want to determine which files are under source control before trying to get the latest version of them. But the point is, these exposed properties and methods can be extremely powerful tools for project management and version control.

ProjectHooks

Visual FoxPro 6 enables you to further extend the Project object model through the use of its new ProjectHooks. Simply put, a ProjectHook is an object that includes several events that fire upon certain actions in the Project Manager. ProjectHooks are ActiveX objects, but again, Visual FoxPro 6 incorporates them so cleanly that you'll barely know the difference.

You can set a particular ProjectHook class for a given project in a couple of ways. You can open a project and select the Project page of the Project, Project Info menu option. Or you can set a ProjectHook default; refer to Figure 12.29 and recall that the Projects tab in the Options dialog (reached by choosing Tools, Options) includes an area to enter a ProjectHook class. If a ProjectHook class is entered here, it is used by any project that doesn't have its own ProjectHook class specified. Visual

TIP
Actually, there's a third way to specify a project hook: by populating the exposed ProjectHookClass and ProjectHookLibrary properties on the Project object.

Project hooks do a pretty good job of taking care of themselves: they instantiate when the project is opened and are destroyed when the project is closed. The following ProjectHook events fire as you manipulate the project (whether interactively-the old-fashioned way-or via code):

TIP
The Query* events of the ProjectHook can be used to prevent the specific action from occurring by including NODEFAULT in the method code.

NOTE
Visual FoxPro 6 offers several new clauses for the MODIFY PROJECT command. The NOPROJECTHOOK clause opens the project without the associated ProjectHook class. NOSHOW opens both the Project Manager and the ProjectHook, but doesn't show the Project Manager window. This means that you can run your programs without even having the Project Manager visible.

Using ProjectHooks

Of course, you can choose not to use ProjectHooks at all. But if you decide to give them a shot, you won't have to look far to find uses for them. For example, you could clean up the project just prior to a build by including a call to the Project object's Cleanup method in the ProjectHook's QueryBeforeBuild. You could check that any file being added to the project conforms to naming conventions or filename length requirements by a check placed in the QueryBeforeAdd method. You could get the latest version of a file just prior to running it by calling a file object's GetLatestVersion method from the QueryBeforeRun. Or you could even utilize MAPI calls in the AfterBuild method to email your fellow programmers and inform them that the project has been freshly built (here's an even better idea: include the .ERR file if any errors occurred). ProjectHooks provide a tremendous degree of control over your projects and enable you to manipulate a project as you would almost any other object.

The Project Manager: A Last Word

The Visual FoxPro 6 Project Manager offers programmers a remarkable degree of control over the development environment. Your use of the Project Manager will depend on your programming experience, your interest, and your needs. You might choose to use the Project Manager simply as a file maintenance tool. Or, you might use a series of ProjectHook events and Project and File PEM calls to manage source control behind the scenes. Or, like most of us, the Project Manager's role in your development will fall somewhere between these extremes.

The bottom line is that the Project Manager is available, flexible, powerful, and easy to learn. Your clients will probably never see the Project Manager in action, but they, like you, will benefit from its presence on your desktop.


© Copyright, Sams Publishing. All rights reserved.