As you might expect, the first object you need to be aware of is the report object itself. The report object is the "big container" for everything. In this sense it is very similar to the form object, but with different properties, events and methods.

While it may appear the report object contains the "whole report", it actually contains only the following six objects:

  1. The printer object

  2. An elements array

  3. A reportGroup object

  4. The streamSource (there can be multiple streamSources) -- these will be discussed in detail as a separate object.

  5. The pageTemplate (there can be multiple pageTemplates) -- these will be discussed in detail as a separate object.

  6. The database objects (Query, Datamodule ...)

All other Report objects are contained by the pageTemplate, streamSource, and other objects.

You should familiarize yourself with the following properties, events and methods:

The autoSort property is designed to automatically set the appropriate sort sequence (the ORDER BY clause) in the SQL statement of the controlling rowset for the report. The problem is, it does this without asking you and may override a sequence you need.

Tip: ALWAYS SET THE autoSort property TO FALSE! This will be discussed again in other sections of this chapter.

The baseClassName property for the report object is always "REPORT". This is very important when creating reports: the className property may be assigned any value, but the baseClassName property is always "REPORT".

The className property is the name of the report class. When you create a report and name it, dBASE Plus streams out a statement that gives a name to the report. This name is reflected by the className property.

The elements property is an object reference to an array that contains all of the elements on the report object.

The endPage property defaults to negative one (-1) which means that there is no "end page". The point of this and the startPage property (below) is to allow you to print only the pages you want to print. If the value is -1, the report engine is told to "print everything". If the endPage property has any other value, the report engine will check the page number (the reportPage property), and if this property and the endPage property are equal, it will stop printing upon completion of the current page.

The firstPageTemplate property is normally set automatically for you if you are using the designer. This property tells the report engine which pageTemplate is the one to start with when rendering the report. This will be covered in more detail when we get to the pageTemplate object.

The inDesign property is a logical property that can be tested to see if you are in the designer, or running the report.

The mdi property is a logical property used to determine if the preview window is a MDI or non-MDI form when running the report (DO reportname.rep or double-clicking the report in the Navigator, etc.).

The metric property determines the units of measure for the position and size of objects used when designing a report. The metrics property defaults to "TWIPS". A TWIP is a "Twentieth of a point". A "point" is a very small value (there are 72 points to the inch), and a TWIP is even smaller (there are 1440 twips to the inch). The human brain doesn't normally think that way (although there are some developers who prefer using TWIPs ...). There are a variety of options for metrics, and using Inches, Millimeters or Centimeters might prove easier to work with.

Note: There may be situations where using the metric setting of "chars" is useful -- specifically when using monospaced fonts -- because it can allow very precise alignment of the Text objects (you’ll find it somewhat similar to the @ SAY commands)

The output property determines where your report is going to go. The default is to a window. You can output to a file but the output is not ASCII, as you might expect, but rather a printer file -- it contains all the formatting codes necessary to generate the report for the printer defined in the printer driver. There is no option to output directly to a text file unless you set up the "Generic/Text" driver that comes with Windows, and output your report to that driver. You can output to an HTML file, which is a really spiffy ability. You can also, of course, output to a printer.

The outputFilename property is only necessary when you are outputting to a file -- otherwise any value you set is ignored.

The printer property is actually a pointer to an object associated with the report. This object has several settings you may find useful, such as "orientation" which allows you to set your report to landscape or portrait.

Note: Making settings in reportname.printer should never affect the global _app.printer settings. However, _app.printer settings will be the defaults unless you make changes in your report.

The reportGroup property is another object pointer to the report's group. This is used to handle aggregate calculations for the whole report, and to set a report header using the headerBand (prints at the beginning of the report only) and/or a report footer using the footerBand (prints at the end of the report only). The headerBand and footerBands for the reportGroup object have the same properties as their counterparts for the standard group object.

The reportGroup object has the same properties, events and methods as the group object (discussed later), with the exception that the parent of the reportGroup is the report itself, rather than the streamSource.

The reportPage property is the current page of the report as it is being displayed, or rendered. This property is read-only.

The reportViewer property is the name of the reportViewer object that is being used to view the report. This is a way of referencing the reportViewer object from the report, and check, or modify, it’s properties. This property is read-only.

The scaleFontBold property determines whether the font used for the character metric is boldfaced (see Help for more details).

The scaleFontName property is the base font used for the character metric (see Help for more details).

The scaleFontSize property is the size of the base font used for the character metric (see Help for more details).

The startPage property can be used to set a starting page other than page 1.

The title property displays a report title at the top of the preview window.

The onPage event fires when a report page has been rendered, just prior to rendering the next page. This allows you to program code you may wish to execute before rendering the subsequent page (such as setting page totals to zero).

The isLastPage method returns a logical value based on whether we are on the last page of the report.

The render method is what actually causes the report to render and is similar to the form’s open( ) and readModal( ) methods. When we get to the Text and other objects, we will introduce two events related to the render method, canRender and onRender.

Later in this chapter there is a section that shows the relationships between the various objects by discussing the sequence of events as a Report is rendered.

It is possible to programmatically control all of the above properties, events and methods, as well as use some of them in special code to test for specific conditions (such as isLastPage).