Print When controls… well… when the object prints. Each of the different types of Report objects has a Print When… button on its associated dialog, which invokes the Print When dialog shown in Figure 17.
Figure 17. The Print When dialog allows you to tell the VFP Report Writer when an object should or shouldn’t be printed.
The “Print repeated values” option group and the Also print check boxes work together to determine when an item prints. Their combined behavior depends on whether the object is a Field object or one of the other objects, and it gets pretty complicated to sort out. Figures 18-20 show a three-page report that demonstrates the difference in behavior between a Rectangle object and a Field object with the various combinations selected. Use these examples as you read through the following explanations to help sort it all out.
Print repeated values
This option tells the Report Writer what to do when the value of this object is exactly the same as the previous record that was processed. A Yes indicates that you want this object printed each and every time, even if it’s the same as the previous record. However, the meaning of No changes, depending on whether this is a Field object or one of the other Report objects. For a Field object only, No indicates you want this object suppressed if its value is exactly the same as the previous record. You can see the difference between these two objects in the sample report shown in Figure 18. The first Customer ID column has the “Print repeated values”
option set to Yes and the second Customer ID column has it set to No.
A No option for all non-Field objects, such as a line or rectangle, means this object never prints—that is, unless one of the Also print check boxes triggers the object to print. So if you use the No option and forget to check any of the Also print check boxes,
the object never prints, as shown in the sample report in Figure 18. The report definition for this sample is included in the source code for this book and is named PrintWhen1.FRX.
Figure 18. The “Suppress repeated values” option controls whether or not a Field object prints if its value is the same as the previous record. However, for non-Field objects, it controls whether the object prints at all.
Also print
There are three Also print check boxes, and each one offers another opportunity for the object to print, even if the “Print repeated values” option has suppressed it. Consider it an override feature to Print repeated values. This can be very confusing to understand, so bear with me here. You can refer to Figures 19-20 and Figure 21 as you read through the following explanation and hopefully, they’ll help you grasp the whole concept a little better.
In first whole band of new page/column
Checking this check box tells the Report Writer to go ahead and print this object in the first band that prints in its entirety on a new page (or column, if applicable). That’s the official definition. But what really happens is slightly different. Besides printing the object in the first full band on a page, it also prints when a band has been continued from the previous page.
To understand how this works, follow the fourth column of boxes through all three pages shown in the sample report (Figures 19-21). The report definition for this report is included in the source code for this book and is named PrintWhen.FRX. On page 1, the word Hello prints for the first record because it’s the first occurrence of the value Hello.
The box also prints on page 1, but for a different reason. It’s printing because the “In first whole band of new page/column” option is selected, which means that because this is the first record of the page, the box prints.
Now look at the second page of the report (Figure 20). The box and text print for the first record—even though this band is not printing in its entirety (it overflowed from the previous page). This is where the official definition doesn’t quite match the behavior. The box and text print for the second record of page 2 (Figure 20) and for the first record on page 3 (Figure 21) because they’re the first full band on their respective pages.
When this group changes
This option is only enabled when Data Grouping (discussed later in Chapter 7, “Data
Grouping”) has been used on the report. It tells the Report Writer to print this object whenever the selected Data Group changes. You can use this option, combined with the “Suppress repeated values” option, to only print an item for the first record in each Data Group.
When detail overflows to new page/column
Checking this check box tells the Report Writer to go ahead and print this object on the next page when a Detail band overflows. The fifth column of boxes on page 2 (Figure 20) demonstrates this overriding feature. The first row of data was started on the previous page (Figure 19) and overflowed to this page. Because the “When detail overflows to new page/column” check box is checked, the box and the word Hello are printed for this row again.
Figure 19. On page 1 of this sample report, the last customer is about to overflow to the next page.
Figure 20. On page 2 of this sample report, the last customer from page 1 has overflowed to this page.
Figure 21. On the third page of this sample report, all three customers are fully contained on this page. No previous customer has overflowed to this page and the last customer completely fit on this page.
Remove line if blank
Checking this check box tells the Report Writer to completely remove this item from the band if it has no value or is not being printed because of any of the Print When settings. It then checks to see whether any other objects occupy the same horizontal space that this object would have occupied. If no other objects are being printed within the same horizontal space, the Report Writer collapses the band to reclaim the unused space.
A classic example of when you would use this feature is when you’re printing names and addresses. Assume your table has the following fields: Name, Address1, Address2, City, State, and Zip. When stacking the fields, you place the Name first, followed by the first address line, followed by the second address line, and finish up with the City, State, and Zip combined on the last line. However, many addresses in the table don’t have a second address line filled in and appear as follows:
Mary Smith 100 Main Street Anytown, MI 49341
Not only does this look funny, but it also wastes a lot of space on the report. By marking the second address line as Remove line if blank, the empty second address line is removed and the space is reclaimed as follows:
Mary Smith 100 Main Street Anytown, MI 49341
This looks much more professional and it doesn’t use as much room on the report.
Print only when expression is true
This feature allows you to tell the Report Writer to only print this object when the expression entered in the “Print only when expression is true” text box evaluates to true. The expression can be any valid VFP expression from a simple .t. to something as complex as a method call, within another method call, using a form property as a parameter.
If you need help with building the expression, you may press the ellipse (…) button to the right of the text box. This displays the Expression Builder dialog discussed earlier in this chapter.
Note: Using the “Print only when expression is true” feature negates the settings of the “Print repeated values” option group and the Print also check boxes. This expression becomes the sole determination of whether or not this object is printed.
Note: It’s important to realize that “Print only when expression is true” is evaluated after Report Variables but prior to the On Entry expression of the band. So don’t plan to use On Entry to set any variables used in the “Print only when expression is true” expression.