Guide to Reporting Improvements

Visual FoxPro 9's Report System has undergone a thorough revision. This topic sketches the broad outlines of the changes, and provides you with information about where to look for details.

The following main areas of enhancements to the Report System are covered in sections of this topic.

• Design-time enhancements.
  Multiple features and changes make designing reports in Visual FoxPro better for you and your end-users. The Report Builder Application re-organizes your design experience out-of-the-box. If you want to customize the design process, Report Builder dialog boxes and Report Designer events are fully exposed for you to do so.

• Multiple detail bands.
  You can handle multiple child tables and data relationships more flexibly in the revised Report Designer. When you run multiple-detail-band reports, you can leverage the new bands, with associated detail headers and footers, both for appropriate presentation of these relationships and for more capable calculations.

• Object-assisted run-time report processing.
  An entirely re-built output system, including a new base class, changes the way Visual FoxPro provides output report and label files at run time. Object-assisted reporting provides better-quality output, new types of output, and an open-architecture based on a new Visual FoxPro base class, the ReportListener. A programmable Report Preview interface interacts with ReportListeners to give you full control over report preview experience. The Report Preview Application provides improved out-of-the-box previewing facilities.

• Printing, rendering, and character-set-handling improvements.
  Visual FoxPro 9 makes better use of the operating system's printing features and GDI+ rendering subsystem. It also handles multiple locales and character sets better than previous versions. These changes are showcased in the Report System, and are accessible for use in custom code during report design and run-time processing.

• Extensible use of report and label definition files (.frx and .lbx tables).
  Visual FoxPro 9 handles your existing reports and labels without modification, while allowing you to add new features and behavior to these reports easily. This backward-compatible, yet forward-thinking, migration strategy is made possible by the Report System's newly-flexible handling of the .frx and .lbx table structure.

Design-time Enhancements

Numerous changes in the Report System help you enhance the design-time experience for developers and end-users. This section directs you to information about design-time improvements.

Report Designer Event Hooks and the Report Builder Application

The Report Designer now offers Report Builder Hooks, which enable you to intercept events occurring during a report or label design session to override and extend designer activity. The default Report Builder Application replaces many of the standard reporting dialog boxes with new ones written in Visual FoxPro code. Components of the Report Builder Application are exposed as Visual FoxPro Foundation Classes for your use.

To learn about:	Read:
Report Builder Hooks	Understanding Report Builder Events
How the Report Builder Application uses Report Builder Hooks	How to: Configure the Report Builder's Event Handling
How to specify and distribute a Report Builder with your applications	_REPORTBUILDER System Variable How to: Specify and Distribute ReportBuilder.App Including Report Files for Distribution
Using Report Builder algorithms in your code	FRX Cursor Foundation Class FRX Device Helper Foundation Class

Protection for End-User Design Sessions, and other Design-time Customization Opportunities

You can allow end-users to MODIFY and CREATE reports and labels, while setting limitations on what they can do in the Report Designer interface, using the new PROTECTED keyword. Protection is available individually by object and globally for the report. You can change what end-users see on the designer layout surface, from complex expressions to simple labels or sample data, while working in PROTECTED design mode, using Design-Time Captions. You can also provide helpful instructions, for both PROTECTED and standard design mode, by specifying Tooltips for report controls.

To learn about:	Read:
Using the PROTECTED keyword	MODIFY REPORT Command MODIFY LABEL Command
Setting Protection in the Report or Label Designer, and what Protection settings do	Setting Protection for Reports
Protection settings exposed in Report or Label Dialog dialog boxes when you use the default Report Builder Application	Protection Tab, Report Control Properties Dialog Box (Report Builder) Protection Tab, Report Properties Dialog Box (Report Builder) Protection Tab, Report Band Properties Dialog Box (Report Builder)
Design-Time Captions	How to: Add Design-time Captions to Field Controls
ToolTips for Report Controls	How to: Add Tooltips to Report Controls

Enhanced Data Environment Use in Reports

You can save the Data Environment you designed for a Report or Label as a visual class. You can load a Data Environment into a Report or Label design from either a visual class or a previously-saved report or label.

To learn about:	Read:
Saving a Report Data Environment	How to: Save Report Data Environments as Classes
Loading a Report Data Environment	Data Environment Tab, Report Properties Dialog Box (Report Builder) How to: Load Data Environments for Reports

Miscellaneous Design Improvements

There have been numerous enhancements to the Report and Label Designers. Some features are subtle changes to make design sessions more efficient and more enjoyable, and others improve your choices for resulting output.

To learn about:	Read:
Improvements to the Report and Label Interactive Development Environment (IDE), such as: Enhanced Report Designer toolbar, and easier access to the Report Designer Toolbar from the View menu New global Report Properties context menu Improvements and additions to existing context menus Revised and extended Report menu	Report Layout and Design
Changes to global report and label design options	Reports Tab, Options Dialog Box
Using the new PictureVal property of the Image control to specify images in reports	How to: Add Pictures to Reports PictureVal Property
New picture template characters (U and W) and updated format instructions (Z, now supported for date and datetime data), useful in reports and labels	Format Expressions for Field Controls InputMask Property Format Property
Receiving improved HTML output, which leverages run-time reporting enhancements, when you choose Save As HTML… while designing a report or label	How to: Generate Output for Reports Tip Other Visual FoxPro components that invoke Genhtml.prg, the default _GENHTML implementation, automatically share the improved HTML output, although these components have not changed. These include the FRX to HTML Foundation Class and the Output Object Foundation Class.
Report document properties enable you to include information about the report in the report. Document properties are included as elements and attributes in XML and HTML output.	How to: Add Document Properties to a Report Document Properties Tab, Report Properties Dialog Box (Report Builder)
You can dynamically change the properties of report controls at run time based on the evaluation of an expression.	How to: Dynamically Format Report Controls Dynamics Tab, Report Control Properties Dialog Box (Report Builder)

Multiple Detail Bands

The Report Engine can now move through a scope of records multiple times. The records can represent related sets of detail lines in child tables, or they can be multiple passes through a single table. These multiple passes through a scope of records are represented as multiple detail bands.

Detail bands can have their own headers and footers, their own associated onEntry and onExit code, and their own associated report variables. Each detail band can be explicitly associated with a separate target alias, allowing you to control the number of entries in each detail band separately for related tables.

Multiple detail band reports provide many new ways you can represent data in reports and labels, and new ways you can calculate or summarize data, as you move through a record scope.

To learn about:	Read:
Designing reports and labels with multiple detail bands and their associated headers and footers	Optional Bands Dialog Box Report Band Properties Dialog Box Band Tab, Report Band Properties Dialog Box (Report Builder)
Handling multiple, related tables in report and label data	Controlling Data in Reports Working with Related Tables using Multiple Detail Bands in Reports
Associating report variables with detail bands	How to: Reset Report Variables
Comparing multiple groups and multiple detail bands	Report Bands

Object-assisted Run-time Report Processing

Visual FoxPro 9 has a new, object-assisted method of generating output from reports and labels. You can use your existing report and label layouts in object-assisted mode, to:

• Generate multiple types of output during one report run.

• Connect multiple reports together as part of one output result.

• Improve the quality of traditional report output.

• Dynamically adjust the contents of a report while you process it.

• Provide new types of output not available from earlier versions of Visual FoxPro.

This section covers the array of run-time enhancements that work together to support object-assisted reporting mode.

Object-Assisted Architecture and ReportListener Base Class

The new ReportListener base class and supporting language enhancements are the heart of run-time reporting enhancements.

To learn about:	Read:
Fundamentals of the architecture, how its components work together, and what happens during an object-assisted report run	Understanding Visual FoxPro Object-Assisted Reporting
The ReportListener base class and its members	ReportListener Object ReportListener Object Properties, Methods, and Events
Invoking object-assisted reporting mode automatically	SET REPORTBEHAVIOR Command _REPORTOUTPUT System Variable Reports Tab, Options Dialog Box
Invoking object-assisted reporting mode explicitly with Visual FoxPro commands	REPORT FORM Command LABEL Command
Debugging and error-handling object-assisted report runs	Handling Errors During Report Runs

Report Preview API and the Report Preview Application

Visual FoxPro 9's object-assisted reporting mode gives you complete control over report and label previews.

To learn about:	Read:
How object-assisted preview works	The Preview Container API Creating a Custom Preview Container
The default Report Preview Application	Leveraging the Default Preview Container
How to specify and distribute Report Preview components with your applications	_REPORTPREVIEW System Variable How to: Specify and Distribute ReportPreview.App Including Report Files for Distribution

New Types of Output and the Report Output Component Set

Because you can subclass ReportListener, you can create new types of output. Visual FoxPro 9 supplies a Report Output Application to connect ReportListener subclasses with output types, as well as ReportListener-derived classes with enhanced output capabilities.

To learn about:	Read:
Requirements for Report Output Application, and how Visual FoxPro uses Report Output Applications	_REPORTOUTPUT System Variable
Features of the default Report Output Application	Understanding the Report Output Application
Specifying custom output handlers using the default Report Output Application	How to: Specify an Alternate Report Output Registry Table How to: Register Custom ReportListeners and Custom OutputTypes in the Report Output Registry Table Considerations for Creating New Report Output Types
Understanding and configuring the Visual FoxPro Foundation Classes providing default ReportListener behavior for object-assisted preview and printing	ReportListener User Feedback Foundation Class
Understanding and configuring the Visual FoxPro Foundation Classes responsible for default XML and HTML output	ReportListener XML Foundation Class ReportListener HTML Foundation Class
Leveraging the full set of supported Report Output Foundation Classes and VFP Report Output XML format	ReportListener Foundation Classes Using VFP Report Output XML
How to specify and distribute Report Output components with your applications	How to: Specify and Distribute Report Output Application Components Including Report Files for Distribution

Migration Strategies and Changes in Output Rendering

You can use the design-time changes to improve all reports and labels, whether you choose backward-compatible or object-assisted reporting mode at run time.

When evaluating whether to switch to object-assisted reporting mode at run time, first consider items on the Reporting list of Important Changes in the Changes in Functionality for the Current Release topic, some of which are specific to this new method of creating output. .The topic includes a table of minor differences between backward-compatible and object-assisted reporting output. You can examine what effects these changes might have on individual existing reports, and use the recommendations in the table to address them. You will find additional details in the topic Using GDI+ in Reports.

Once you have experimented with your current reports, you can decide on a migration strategy for output:

• You can switch applications over to use object-assisted reporting mode completely, by using the command SET REPORTBEHAVIOR 90.

• You can use SET REPORTBEHAVIOR 90 but preface specific REPORT FORM commands for reports with formatting issues with SET REPORTBEHAVIOR 80, returning your application to object-assisted mode afterwards.

• You can use object-assisted mode all the time, but adjust your ReportListener-derived classes' behavior to suit specific needs. For example, you could change the default setting of the ReportListener's DynamicLineHeight Property to False (.F.).

• You can leave SET REPORTBEHAVIOR at its default setting of 80, and add an explicit OBJECT clause to specific reports at your leisure, as you have the opportunity to evaluate and adjust individual report and label layouts.

Printing, Rendering, and Character-set-handling Improvements

General changes to Visual FoxPro's use of Windows' printing, rendering and font-handling support the improvements in the Report System's output. These changes enhance your ability to support multiple printers and multiple languages in reports.

To learn about:	Read:
GDI+ features and their impact on native Visual FoxPro output	Using GDI+ in Reports
Visual FoxPro reporting enhancements that allow your code to use GDI+ in object-assisted reporting mode, and Visual FoxPro Foundation Classes to get you started	GDIPlusGraphics Property Render Method GDI Plus API Wrapper Foundation Classes
Making full use of multiple character sets, or language scripts, in reports, for single report layout elements, for report defaults, or globally in Visual FoxPro	GETFONT( ) Function Style Tab, Report Control Properties Dialog Box (Report Builder) How to: Change Page Settings for Reports Reports Tab, Options Dialog Box Reporting Features for International Applications
Changes to page setup dialog boxes in Visual FoxPro, improvements in your programmatic access to them, and providing overrides to Printer Environment settings in report and label files	SYS(1037) - Page Setup Dialog Box
Receiving improved information about the user's installed printers	APRINTERS( ) Function
Limiting a list of fonts to those appropriate for printer user	GETFONT( ) Function

Extensible Use of Report and Label Definition Files

Underneath all the changes to the Visual FoxPro Report System, the Report Designer and Report Engine handle your report and label definitions using the same .frx and .lbx file structures as they did in previous versions. They change the way they use certain fields, without making these reports and labels invalid in previous versions, and they also allow you to extend your use of existing fields or add custom fields.

Tip

This change is critical to your ability to create extensions of the new reporting features. For example, you might store two sets of ToolTips in two report extension fields, one set for use by developers and one for use by end-users. In a Report Builder extension, you could evaluate whether the Designer was working in protected or standard mode, and replace the actual set of ToolTips from the appropriate extension field. In previous versions, you could not add fields to report or label structure; the Designer and Engine would consider the table invalid. You also could not add custom content to unused, standard fields in various report and label records safely, because the Report Designer removed such content.

Visual FoxPro 9 provides a revised FILESPEC table for report and label files, with extensive information on the use of each column in earlier versions as well as current enhancements.

Visual FoxPro 9 also establishes a new, structured metadata format for use with reports. This format is an XML document schema shared with the Class Designer's XML MemberData.

The XML document format allows you to pack custom reporting information into a single report or label field. The default Report Builder Application makes it easy to add Report XML MemberData to report and label records.

To learn about:	Read:
How Visual FoxPro uses .frx and .lbx tables, and how to extend these structures	Understanding and Extending Report Structure
How to find and display the contents of the revised FILESPEC table, 60FRX.dbf	Table Structures of Table Files (.dbc, .frx, .lbx, .mnx, .pjx, .scx, .vcx)
How you can edit the XML data using the Report Builder Application	How to: Assign Structured Metadata to Report Controls
How you can use Report XML MemberData	Report XML MemberData Extensions
The shared MemberData document schema	MemberData Extensibility

See Also

Reference

Data and XML Feature Enhancements
SQL Language Improvements
Class Enhancements
Language Enhancements
Interactive Development Environment (IDE) Enhancements
Enhancements to Visual FoxPro Designers
Miscellaneous Enhancements
Changes in Functionality for the Current Release

Other Resources

What's New in Visual FoxPro