Building an application for distribution is similar to developing a standard Visual FoxPro application. You work in the Visual FoxPro development environment as usual, but then you create an executable file or Automation server (a COM component) and test it in the run-time environment. You then distribute your application and any related files to your distribution sites.
This chapter describes changes you need to make to prepare an application for distribution, as well as some suggested changes that help make a distributed application look unique.
This chapter addresses:
The following list identifies the steps you need to follow to distribute a Visual FoxPro application:
Important Certain development environment features aren’t available in the run-time environment and must be removed from your application. These features are listed in Removing Restricted Visual FoxPro Features and Files later in this chapter.
The following sections describe the steps you might need to take to prepare your application for the run-time environment. These steps include:
Before you can distribute your application, you must build either an application file, with an .app extension, or an executable file, with an .exe extension. The following table lists the differences between the builds.
| Build Type | Characteristics |
| Application (.app) file | 10K to 15K smaller than an .exe file. User must own a copy of Visual FoxPro. |
| Executable (.exe) file | Application includes the Visual FoxPro loader so users don’t need to own Visual FoxPro. You must provide the two support files Vfp6r.dll and Vfp6renu.dll (EN denotes the English version). These files must be placed in the same directory as the executable file or along the MS-DOS path. See BUILD EXE for more information about creating and distributing executables. |
| OLE DLL | Used to create a file that can be called by other applications. For details about using this build option, see Chapter 16, Adding OLE. |
When you choose the type of build, consider the size of your final application file and whether your users own Visual FoxPro.
You should consider and test the minimum environment your application can operate in, including the amount of disk space and memory. The results of your testing and the resolution of other issues covered in this chapter can help determine the type of build you choose, the files you include with your application, and the way you structure your distribution directory.
The applications you create have the same hardware, memory, and network requirements as Visual FoxPro. For more information on those requirements, see “System Requirements” in Chapter 1, Installing Visual FoxPro, in the Installation Guide. For additional information on creating applications for multiuser environments, see Chapter 17, Programming for Shared Access.
An executable application file always checks for the presence of the Visual FoxPro run-time library, Vfp6r.dll. To run an application .exe file using the development version of Visual FoxPro, you must force the application to use the Visual FoxPro .exe file instead.
To run an executable application in Visual FoxPro
-or-
-or-
MYAPP.EXE -E
This command line switch forces the application to use the executable file Vfp6.exe. For this switch to work, Vfp6.exe must be in the search path.
An application consisting only of modeless forms will not function properly in a run-time environment unless you provide a READ EVENTS command. You can ensure that the application runs properly by adding a calling program or setting the WindowType property.
To run a form in a run-time environment
-or-
Some Visual FoxPro applications rely heavily on Visual FoxPro system menus. At run time, some menus and commands are unavailable, and without a provision for a READ EVENTS command, a menu-driven application ends as quickly as it starts. Use the following section to review any menus you include in your application.
For more information on structuring an application with the READ EVENTS command, see “Controlling the Event Loop” and “Examples of How to Structure an Application” in Chapter 13, Compiling an Application.
If you use the Visual FoxPro system menu, your application file includes only the following default menus and menu commands.
| Menu | Menu items |
| File | Close, Save, Save As, Exit |
| Edit | Undo, Redo, Cut, Copy, Paste, Paste Special, Select All, Find, Replace |
| Window | Arrange All, Hide, Hide All, Show All, Clear, Cycle, all open windows |
| Help | Contents, Search for Help on, Technical Support, About Visual FoxPro |
You can disable or remove any of the default menus and menu commands, or add your own menus and menu commands to run-time applications.
Troubleshooting If your menu system works in the development environment but closes prematurely in your application, make sure you have a READ EVENTS command active while your menu system is running. Also be sure to include a CLEAR EVENTS command when you exit the menu system.
For more information about customizing menus, see Chapter 11, Designing Menus and Toolbars.
Visual FoxPro provides several resource files that extend the basic functionality of your applications, including FOXUSER resource files, API libraries, and ActiveX controls. If you use these files, you must include them in your project or distribution tree.
Visual FoxPro resource files store useful information for your application, including window positions, Browse window configurations, and label definitions. If your application relies on specific settings for any of these resource items, you must also distribute the FOXUSER database and memo files or the resource files you create specifically for your application. These resource files consist of a Visual FoxPro table with an associated memo file, usually named Foxuser.dbf and Foxuser.fpt.
Note The FOXUSER resource file isn't the same as the locale-specific resource file that contains dialog boxes and error messages. The FOXUSER resource file stores application information such as macros you've defined; the locale-specific resource file stores system text strings. For more information, see Including a Locale-Specific Resource File later in this chapter.
If your application includes external library files such as ActiveX controls (.ocx files) or Visual FoxPro API libraries (.fll files), use the Setup Wizard to ensure they're placed in the appropriate directory. You can distribute the Visual FoxPro file Foxtools.fll with your applications. For more information on creating external libraries to access the Visual FoxPro API, see Part 9, Accessing APIs.
If you include ActiveX controls or have created a Automation server (a COM component) as part of your application, include any .ocx files in your project and ensure the necessary support files are installed on the user’s machine in the Windows system directory. Note that you can only distribute ActiveX controls for which you are licensed. For Automation servers, you must also include registration files, such as type libraries (.tlb files) and registry files (.vbr files), with your application.
If you use the Setup Wizard to create the distribution disks, you can include these files automatically. In Step 6, make sure the ActiveX column contains check marks for the ActiveX controls you’re shipping. When you do this, the Setup program created by the Setup Wizard will ensure that COM components are registered properly on the user’s computer when the application is installed. For more information on the Setup Wizard, see Chapter 26, Creating Distribution Disks
All users can run forms containing ActiveX controls; however, your application cannot accomplish certain tasks if it is running under the run-time version of Visual FoxPro. Remember the following guidelines:
PUBLIC frmOleNewForm
frmOleNewForm = CREATEOBJECT("form")
frmOleNewForm.Show
frmOleNewForm.ScaleMode = 3
frmOleNewForm.Addobject("NewOutline","OLEControl",;
"MSOutl.Outline")
Note When a form is closed, controls added at run time aren't saved.
RedOutline subclass from the Outline class, and distribute the subclass in Olelib.vcx; all users can then add the RedOutline control to a form by running the following code:
PUBLIC frmOleNewForm
frmOleNewForm = CREATEOBJECT("form")
frmOleNewForm.Show
frmOleNewForm.ScaleMode = 3
SET CLASSLIB TO CURR() + OLELIB.VCX
frmOleNewForm.Addobject("NewOutline","RedOutline")
The configuration file, Config.fpw, can establish many default Visual FoxPro settings. For instance, you can change the Visual FoxPro title, the background color, and the way a user navigates with the keyboard.
If you want the configuration file to be read-only, place it in your project and mark it as included. If you want the configuration to be modifiable, place the file in your project and mark it as excluded. Then distribute the configuration file with your application or executable file, as a separate file. By default, Visual FoxPro looks for a configuration file named Config.fpw. However, you can specify a different configuration file name using the -C command-line switch when starting Visual FoxPro.
For more information about options that you can set in the configuration file, see “Using a Configuration File” in Chapter 3, Configuring Visual FoxPro, in the Installation Guide.
If you're distributing your application along with the run-time version of Visual FoxPro, you might need to include a locale-specific resource file. This file contains the dialog boxes and other user-interface elements that Visual FoxPro uses to interact with the user. There's a different run-time resource file for each language in which Visual FoxPro is available.
For more information about using locale-specific run-time files, see “Distributing Locale-Specific Run-Time Files” in Chapter 18, Developing International Applications.
Note The locale-specific resource file isn't the same as the FOXUSER resource file, which stores application information such as macros you've defined. The locale-specific resource file stores system text strings. For more information, see Including FOXUSER Resource Files earlier in this chapter.
You can freely reproduce and distribute some Visual FoxPro files, graphics, and programs with the applications you create. For detailed information, see Removing Restricted Visual FoxPro Features and Files later in this chapter.
Before you build your application, make sure that your project includes the necessary files for your application as well as any additional resource files, such as graphics files or templates.
The following table list files you can add to your project.
| If you are | Add these files to your projects |
| Applying a custom configuration to your application | Config.fpw |
| Applying custom settings to your application | Foxuser.dbf and Foxuser.fpt |
| Distributing a .dbf-style Help file | Your .dbf-style Help file |
To add files to your application
If you don't want to change them in the distributed application, place the files in your project and mark them as included. The files are then read-only and cannot be modified.
-or-
If you want to modify them, place the files in your project and mark them as excluded. Then distribute them with your application as separate files.
For more information about creating a project, and including or excluding files in a project, see Chapter 13, Compiling an Application.
The development environment of Visual FoxPro contains many features and files that are licensed for your use only. If your application contains any of these features or files, remove them.
You cannot include the following Visual FoxPro menus and their menu commands in a distributed executable file.
| Restricted menus | |
| Database | Project |
| Form | Query |
| Menu | Table |
| Program |
If your application includes the following commands, it will return the error “Feature not available.” Although you cannot include commands that create or modify menus, forms, or queries, you can run compiled menu, form, or query programs in your application.
If used in a distributed application, the following commands are ignored.
| Ignored commands | |
| SET DEBUG | SET DOHISTORY |
| SET DEVELOPMENT | SET ECHO |
Visual FoxPro installs files on your computer that are restricted and may not be reproduced or distributed, including:
Although you cannot distribute Visual FoxPro sample applications with your applications, you can refer to portions of sample application code as examples for building your own application. You can also include the wizard class library, Wizstyle.vcx, and the sample class libraries in your application.
Visual FoxPro contains many files that are licensed for your use for design, development, and testing purposes only. See License.txt, located in your Visual FoxPro directory, for a list of restricted files.
If your application contains any of these files, remove them. Under the terms of the Microsoft License Agreement you received with this product, you aren't permitted to ship these files in your application or on your disks.
You may distribute any Visual FoxPro file that isn't restricted. Pursuant to the Microsoft License Agreement you received with this product, files must be distributed in conjunction with a corresponding application. The following guidelines apply to distributable files.
The Setup Wizard checks for restricted files and will exclude them from distributable disk sets. Do not assign these file names to any files you will distribute. The Setup Wizard will exclude any file that has a name identical to one on this list.
Any files in the Visual FoxPro Distrib.src and SETUP directories that are required to support a corresponding application may be distributed. When you use the Setup Wizard to create distribution disks, it automatically places the required files from these directories on the distributable disks in a compressed format. Upon installation, these file are decompressed and are installed by name in the appropriate directories on the user’s machine. It isn't necessary to copy these files to your distribution tree.
Files in the Visual Studio …\Samples\Vfp98 folders and in the Vfp98\Api\Samples folders are provided for you to learn from and build on. Although you may not distribute unmodified Visual FoxPro sample applications, you may refer to portions of sample application code as examples for building your own application.
If you use any files in these directories (including all .bmp, .ico, and .cur files), they must be included in your project and in the application build. They must not appear by name on the distributable disks and may not be distributed independently of your applications.
You can use any .vcx file, including those in the Vfp98\Ffc and Vfp98\Gallery directories, without modification in your applications. The libraries must be included in your project and in your application build.
Please refer to the Microsoft License Agreement you received with this product for specific restrictions with respect to your redistribution of ODBC files.
Visual FoxPro includes a set of ActiveX controls (.ocx files) you can add to and distribute with your applications.
The Visual FoxPro default run-time environment looks like the development environment: it displays Visual FoxPro icons and menus. To give your application a unique appearance, you might want to customize some of its features by:
To prevent users from viewing or changing the source code of your application, encrypt your source code and remove debugging information.
Tip Always back up your source code before encrypting it.
To protect your source code
Before you begin the distribution process, if you haven’t already done so, you can comment and format your code so it has a consistent appearance and is easier to maintain. You can use the Beautify option from the Tools menu or the Documenting Wizard to customize your application documentation in several ways, including:
To use the Documenting Wizard
You can also use the Documenting Wizard to create cross-references of symbols you’ve used in your application and to produce an analytical summary of your project.
At times, errors occur when users run your application. You can call your own error-handling routine by including ON ERROR. Typically, ON ERROR uses a DO command to run a routine which handles the error, as in:
ON ERROR DO My_Error
If your application contains no error-handling routines when an error occurs, the application pauses and Visual FoxPro displays an error message with the following options:
For more information about error handling, see “Handling Run-Time Errors” in Chapter 14, Testing and Debugging Applications.
For a complete list and explanation of Visual FoxPro error messages, see Error Messages.
Tip Be sure to provide documentation to your users that describes the errors that they might see, and suggests ways in which they can correct errors.
Create your own shutdown routine by including the command ON SHUTDOWN in your code. Typically, ON SHUTDOWN uses a DO command to call a routine if you try to exit the application, as in the following example:
ON SHUTDOWN DO My_Shutdown
This routine typically includes a dialog box that asks if the user is sure they want to quit the current application. If the user wants to quit the application, the routine can close open files and clean up the environment, and then issue the QUIT command. If the user doesn't want to exit the current application, the routine can return control to the application.
You can integrate context-sensitive Help into your applications, so that users can press F1 or choose Help from a menu to get assistance with your application. The Help that you provide with your application has the same features as the Help in Visual FoxPro. For more information, see Part 7, Creating Help Files.
If you create graphical Help for your application, include the .chm or .hlp file in your application distribution directory so that the Setup Wizard includes it on your distribution disks.
Note You cannot distribute Winhelp.exe or the Help files shipped with Visual FoxPro. For more information, see Removing Restricted Visual FoxPro Features and Files later in this chapter.
You can modify the appearance of your application without changing your application code by:
You can add your own menus and menu options to distributed applications by using the Menu Designer. If you don't create your own menu, the run-time environment displays a default Visual FoxPro menu.
For details on the default menus, see Ensuring Correct Run-Time Behavior earlier in this chapter. For more information about the Menu Designer, see Chapter 11, Designing Menus and Toolbars.
Your application runs in the main Visual FoxPro window. By default, the text “Microsoft Visual FoxPro” appears in the title bar.
To customize the title of the main Visual FoxPro window
TITLE = cMyTitle
Replace cMyTitle with the title of the main window of your application.
To include a Visual FoxPro function as part of the title, use the Caption property of the main window as in the following example.
COMMAND=_SCREEN.Caption=;
"Visual FoxPro " + SUBSTR(VERSION(),25,3)
After your application is compiled, the default Visual FoxPro icon appears in the Windows Explorer or Start Menu as the application icon. You can use the generic icon that is supplied by Visual FoxPro or design your own.
If you want to display your own icon, create an icon (.ico) file with two images: one small (16 by 16) and one standard (32 by 32). Create both images as 16-color icons.
You can change the default Visual FoxPro icon in the Project Info dialog box of the Project menu. If you use the Setup Wizard to create distribution disks for your application, you can also specify an application icon there.
To change the default application icon using the Project Manager
In all application development, it’s a good practice to make complete backup copies of your original program files before you build an application. Store the backup copies separately from your compiled applications.
Important Be sure to maintain separate copies of your original source programs for future use. You cannot re-create your source programs from their compiled code.
When your application project contains all the necessary files, you're ready to build a distributable file. You can build your project as a standard application that only runs when Visual FoxPro is present, or as an executable application that runs without Visual FoxPro.
Note You can also build your application as an Automation server. For details, see Creating Automation Servers in Chapter 16, “Adding OLE”.
You can build a standard Visual FoxPro application with the Project Manager or with the BUILD APP command. However, more build options are available when you create an application through the Project Manager.
To build a standard application
-or-
You can build a Visual FoxPro executable file with the Project Manager or with the BUILD EXE command.
To build an executable file
-or-
If you include the STANDALONE or EXTENDED clauses of the BUILD EXE command, Visual FoxPro generates a “Feature not available” error message.
You can also build an Automation server, which creates a DLL that can be called from other Windows programs.
To compile an Automation server
-or-
Now that you’ve considered all the requirements and options that Visual FoxPro provides, and built an application from your files, follow these steps:
The distribution directory contains copies of all the project files that comprise your application. The structure of this distribution tree represents the way the Setup routine created by the Setup Wizard will install files on a user’s machine.
Mapping the project files to the distribution tree
To create the distribution directory
You can use this directory to test your application in the run-time environment. If necessary, temporarily reset defaults on your development machine to reflect the minimum settings on a target user machine. When everything works correctly, use the Setup Wizard to create disk images that will reproduce the correct environment when you distribute copies of your application.
To create distribution disks, use the Setup Wizard. The Setup Wizard compresses the files in the distribution tree and copies these compressed files to the disk image directory, placing them in a separate subdirectory for each disk. After you use the Setup Wizard to create images of your application disks, copy the contents of each disk image directory to a separate disk.
When you distribute the package, the user can install all the files for your application by running Setup.exe from Disk 1.
For details on using the Setup Wizard, see Chapter 26, Creating Distribution Disks.