How to: Specify and Distribute ReportBuilder.App

  • Article

When you write and distribute Visual FoxPro applications, you may choose to give your users the ability to customize some or all of your application's report layouts. The report builder and report protection features in Visual FoxPro 9.0 makes this a safer and controlled solution for your application.

In this topic, you will learn how to redistribute the default Report Builder application in two ways:

  • Distribute the Report Builder as a separate file alongside your own application, and ensure that Visual FoxPro is directed to the location of the reportbuilder.app file at run time.

  • Build the Report Builder source files directly into your own application.

Redistributing ReportBuilder.App with Your Application

By default, if ReportBuilder.App exists in the same directory as the Visual FoxPro run-time files, then _REPORTBUILDER will contain the fully-qualified path and filename. One solution is to ensure that the setup program used to distribute your application places ReportBuilder.App in the same directory as the run-time files. Alternatively, you can distribute ReportBuilder.App in the same directory as your application, providing you explicitly set _REPORTBUILDER to point to your copy of the ReportBuilder.App file.

To make sure the Visual FoxPro run-time environment can find your distributed copy of ReportBuilder.App

  • In the main program of your application, use code similar to the following:

    * Get the application's home directory:
cHomeDir = CURDIR()  && use whatever method you prefer
* Set the system variable to use the fully-qualified path:
_REPORTBUILDER = m.cHomeDir+"ReportBuilder.App"
:

You could also use a line in CONFIG.FPW:

_REPORTBUILDER=<path>\ReportBuilder.App

Considerations

If you distribute ReportBuilder.App in this way, you will not be able to specify an alternative report event handler registry table that is built-in to your application's APP file. This is because the code running inside ReportBuilder.App cannot use any files built in to other applications (.app or .exe files).

Integrating the Report Builder Source into Your Project

Instead of distributing the compiled application, you may choose to incorporate the source code of the report builder directly into your application's project.

To integrate the report builder source into your application

  1. Unpack the xsource.zip file found in the Tools\xsource\ folder under the Visual FoxPro home directory.

  2. In the main program of your application, use code similar to the following:

    * Ensure the report builder source is pulled into the project:
EXTERNAL PROCEDURE frxbuilder.prg
* Set the system variable to use the local source version:
_REPORTBUILDER = "frxbuilder.prg"
:

  3. Rebuild your project.

    The report builder source code and event handler lookup table will be added to your project and compiled in to your application.

Rather than use the original version of the event handler lookup table, frxbuilder.dbf, you may wish to customize it. Be careful - your project is referencing your master copy of the report builder source. You may prefer to remove the frxbuilder.dbf file from your project, and replace it with a customized copy local to your application's source tree.

You do not have to keep the default name for this table. If you wish, you can tell the report builder to use an alternatively named table instead:

To specify an alternate event handler registry table

  • In the setup portion of the main program of your application, use code similar to the following:

    do frxBuilder with 3, "mylookup.dbf"

Shared Source Files

ReportBuilder.App and ReportPreview.App have the following source files in common:

  • frxControls.vcx

  • frxCommon.prg

  • grabber.gif

  • wwrite.ico

  • foxpro_reporting.h

The Project Manager creates only one reference to each of these files in your application's project, depending on the order of the EXTERNAL statements in your main program.

Considerations for Report Builder Help

Report Builder Application dialog boxes are supplied with help information in the Visual FoxPro help file, associated with the HelpContextID Property (Visual FoxPro) of various interface elements. The Visual FoxPro help file cannot be redistributed with your application. For information, see Distributable and Restricted Visual FoxPro Features and Files.

When you distribute Report Builder Application or its components, and if you provide help files for your applications, you can choose one of the following strategies:

  • Create help topics using the appropriate context IDs in your help file, matching the context IDs the Report Builder uses. Check the help ID constants defined in FRXBUILDER.H for the correct context IDs to use.

  • Do not create help topics with these context IDs. When the user presses the F1 key or uses a Help button, your help file will appear with your top-level topic showing.

  • Change the constants defined in FRXBUILDER.H in the Report Builder source to use one or more different context IDs, and create a topic or multiple topics in your help file to match the context IDs you use. You will need to recompile ReportBuilder.App from the source code in order for this change to take effect.

To specify different help context ID values for Report Builder Application components

  1. Modify the help context id constants defined in FRXBUILDER.H and save your changes.

  2. Recompile the Report Builder Application, or recompile your application if you are building in the Report Builder components to your application.

When you distribute Report Builder Application or its components, and if you do not provide a help file for your application, you have the following options:

  • Distribute ReportBuilder.app or its components as-is. When they determine that SET("HELP") = "OFF", ReportBuilder components disable the Help button.

  • Adjust an associated constant in the frxbuilder.h file to remove the Help button.

To remove the Help button from Report Builder Application interface elements

  1. Locate the frxbuilder.h file in the Report Builder Application source.

  2. Change the value of the SHOW_HELP_BUTTON_ON_HANDLER_FORMS constant to False (.F.).

  3. Recompile the Report Builder Application, or recompile your application if you are building in the Report Builder components to your application.

For more information about using the Visual FoxPro help system in applications, see SET TOPIC ID Command and SET HELP Command.

See Also

Tasks

How to: Specify an Alternate Report Event Handler Table

Reference

_REPORTBUILDER System Variable
Including Report Files for Distribution

Concepts

Application Distribution Process

Other Resources

Configuring Help Files for Applications