4.3.15 Reporting

Reporting

Output is the most important part of a business application. People don't key in megabytes of data because it's so much fun to do. They spend all that time in order to get valuable output. The classes in this category should help you provide better output.

Output Object

Class	_output
Base class	Container
Class library	_reports.vcx
Parent class	_container
Sample	...\Samples\Vfp98\Solution\Ffc\output.scx
Dependencies	_base.vcx, _reports.h

The Output object is a wrapper for the Visual FoxPro REPORT FORM command and a couple of other output options. The basic idea is simple. You instantiate the Output object, specify the report you want to print in the cReport property, define the output destination (such as the screen or a printer) in the cDestination property, and additional options in the cOptions property. The report is printed when you send an Output() message to the Output object. The beauty of the Output object comes into play as soon as you have to print a report more than once with different settings, or when you try to print different reports with the same settings.

As mentioned above, the cReport property is used to specify the report file. The report file can either be an FRX report, or an LBX label. The cDestination property specifies where to print. The aDestinations() array lists all possible output destinations. The default destinations are listed in Table 9. Depending on the current destination, you can set output options (see Table 10) in the cOption property. Again, all possible options are listed in the aOptions() array. Once you've set these properties, you can print your report by calling the Output() method like so:

oReport = NewObject("_output","_reports.vcx")

oReport.cReport = "MyReport.frx"

oReport.cDestination = "SCREEN"

oReport.cOption = "GRAPHICAL"

oReport.Output()

In this example, we print a screen preview in graphical format. This is a more flexible version of the following line of code:

REPORT FORM MyReport.frx PREVIEW

When looking at this simple line of code, it might seem easier to do it the old, non-objectified way. However, you give up a whole lot of flexibility this way. Let me give you an example. Let's assume the oReport object from the example above is still in memory. We could now print this report in HTML format and display it in Internet Explorer like so:

oReport.cDestination = "HTMLFILE"

oReport.cOption = "WEBVIEW"

oReport.Output

Note that we didn't have to reset the report file. The object remembered this setting and allowed us to print the same report multiple times. In fact, we could create a subclass of the Output object, specify a certain report right in the class, and then set only the destination.

Table 9. Possible output destinations.

Destination	Description
PRINTREPORT	Prints a report on paper.
PRINTLIST	Prints a text preview as shown in Figure 43.
SCREEN	Prints a screen preview of the report.
TEXTFILE	Creates an output text file in regular ASCII format.
PRINTFILE	Creates an output image representing the data sent to the printer in printer-specific format. The file could be copied to the printer later on.
EXPORT	Exports a table.
HTMLFILE	Creates an output file in HTML format.

 

Figure 43. Any Visual FoxPro data source can be used for text output
with the "LIST" option.

So far you've seen only printed report files, but as the name of the object suggests, it's a more generic output handler that can do more than printing reports. The Output handler can also use practically any Visual FoxPro data source and create output, either using a browse window, a text display window (Figure 43) or an HTML file that may or may not be displayed immediately in Internet Explorer.

Table 10. Available options for certain destinations.

Option	Available for destinations	Description
ASC	EXPORT	Exports table to file in ASCII format.
ASCII	SCREEN	Prints a screen preview in ASCII format.
BROWSE	SCREEN	Creates a screen preview in the form of a browse window.
CSV	EXPORT	Exports table to file in comma-separated-value format.
DIF	EXPORT	Exports table to file in VisiCalc DIF (data interchange format) format.
FILEONLY	HTMLFILE	Creates an HTML output file but doesn't display it.
FOX2X	EXPORT	Exports table to file in FoxPro 2.x format.
FOXPLUS	EXPORT	Exports table to file in FoxBase+ format.
GRAPHICAL	SCREEN	Prints a screen preview using the graphical Visual FoxPro report engine.
LIST	SCREEN	Displays a screen preview using a special text view window (see Figure 43).
SDF	EXPORT	Exports table to file in system data format.
SETVFPDEFAULT	PRINTREPORT, PRINTLIST, PRINTFILE	Creates a printed report and asks the user for a printer.
VFPDEFAULT	PRINTREPORT, PRINTLIST, PRINTFILE	Creates a printed report on the VFP default printer (as specified in the cVFPPrinterName property).
VIEWSOURCE	HTMLFILE	Creates an HTML output file and displays its source code.
WEBVIEW	HTMLFILE	Creates an HTML output file and displays it using Internet Explorer.
WINDEFAULT	PRINTREPORT, PRINTLIST, PRINTFILE	Creates a printed report on the Windows default printer.
WK1	EXPORT	Exports table to file in Lotus 1-2-3 (version 2.x) format.
WRK	EXPORT	Exports table to file in Lotus Symphony (version 1.10) format.
XL5	EXPORT	Exports table to file in Excel (version 5.0 and higher) format.
XLS	EXPORT	Exports table to file in Excel (up to version 4.0) format.

You can also use any kind of data source and export it in a number of standard formats (see Table 10). To do so, you set the destination to "EXPORT" and the option to your preferred export format. The data source is specified in the cAlias property. You have to open the data source yourself. Only the Output object uses it. When you create an output file (HTML output, or exported data), you can set the name of the destination file using the cTextFile property.

You can limit the number of records to be used for any kind of output by setting a scope in the cScope property. The scope has to be a valid Visual FoxPro expression. For special output options that handle data directly (such as "BROWSE" or "LIST"), you can also specify the fields you want to display. You can do this using the cFieldList property, which specifies a list of fields in comma-separated format.

The _GENHTML program handles any kind of HTML output created by the Output object. It allows you to specify various settings such as a special HTML class or an HTML style. You can set those options through the cHTMLClass and cHTMLStyleID properties.

In addition to the output behavior settings, the Output object features a couple of properties that are used to specify how an interface to this object could look, even though the Output object doesn't have an interface. (The Output control described below is a standard interface for the Output object.) One of these properties is cDisplayFontName, which specifies the font for all controls used in an interface. The aDestinations() and aOptions() arrays can be used as a source for drop-down lists. If you do that, you can specify whether you want to add the name of the source file to the drop-down list using the lAddSourceNameToDropdown property. Quite handy is the lPreventSourceChanges property, which sets the cReport and cAlias properties to read-only. However, I'm not sure that these properties should be in this class. I think this breaks the rules of encapsulation because we have properties belonging to an interface in a behavioral object.

Output Control

Class	_outputchoices
Base class	Container
Class library	_reports.vcx
Parent class	_output
Sample	...\Samples\Vfp98\Solution\Ffc\output.scx
Dependencies	_base.vcx, _reports.h

The Output Control is a direct subclass of the Output object (see above). It provides an interface for the most important options, such as the destination, print options and the file name if the destination requires an output file. The Output Control class doesn't have custom properties or methods.

The Output dialog box (see below) uses this object to give the user intuitive access to the most important settings (see Figure 30).

Output Dialog Box

Class	_outputdialog
Base class	Form
Class library	_reports.vcx
Parent class	_form
Sample	...\Samples\Vfp98\Solution\Ffc\output.scx
Dependencies	_base.vcx, _reports.h

The Output dialog box represents a standard interface for any kind of output operation. Figure 30 shows an example of this dialog.

The dialog has a large number of properties and methods that make it appear quite complex. Fortunately, it isn't. You must set only a few properties in order to use this dialog. In fact, you don't have to set any properties at all. In this case, the user is asked for all the missing information, such as an FRX file or another kind of data source. However, I don't recommend doing this because the chances to introduce problems are too great. Here's an example:

oReport = NewObject("_outputdialog","_reports.vcx")

oReport.cReport = "MyReport.frx"

oReport.lPreventSourceChanges = .T.

oReport.Show

The second line defines an FRX file as the source. I also specify that I don't want the user to change the source. Finally, the example displays the dialog shown in Figure 44. Compare this dialog to Figure 30 to see the changes caused by setting the lPreventSourceChanges property to .T.

Figure 44. The Output dialog configured to hide the source selection
controls (compare to Figure 30).

All properties you set in the Output dialog box object are default settings that will be used for the output operation later on. Most of these properties are similar to the ones I described for the Output object, because the dialog's properties are used to set the properties of the Output object (which is used by this dialog to create output).

I found it useful to subclass this object, mainly to change its look and feel. If you do that, make sure you understand that the object automatically resizes the dialog when certain properties are set (as in the example above). Those changes are usually triggered by the assign methods of those properties. If you change the dialog's dimensions or the layout of the controls, you also have to change those methods so they can handle your dialog.

Text Preview

Class	_showtext
Base class	Form
Class library	_reports.vcx
Parent class	_form
Sample	...\Samples\Vfp98\Solution\Ffc\output.scx
Dependencies	_base.vcx, _reports.h

This class is a simple text editor that allows you to open, edit and save text files. It is always displayed in a fixed font. The main purpose of Text Preview is to provide a controllable preview window for text files. This class is used by the Output object to display screen previews in "LIST" format (see Figure 43).

You can load a text file simply by setting the cSourceFile property like so:

oText = NewObject("_showtext","_reports.vcx")
oText.cSourceFile = "ReadMe.txt"
oText.Show

It takes a while to get used to loading the text by setting a property. The Text Preview class uses an assign method to do that.

The class has a number of properties and methods, but you can't influence much because almost all of them are reserved for internal use only. The only other property I found useful is cTargetFile. It specifies the file name in which the text will be saved if the user clicks the Save button. Unfortunately, there isn't a good way to trigger the Save method other than to fire the Save button's Click() method manually like so:

oText.cmdSave.Click()

If no destination file was specified, the class asks the user for a new file name using the standard Save As dialog.