Printer Retrieve Method

Declaration

function Retrieve: boolean;

Description

The Retrieve method obtains the Printer information from the Report. If the Printer specified in the Report does not exist on the current computer, the default Printer information will be returned. Returns True if the call succeeded.

Example

The following example retrieves the Printer settings from a Report, and changes the Orientation setting if needed:

Crpe1.ReportName := 'C:\Company.rpt'; Crpe1.Destination := toPrinter; Crpe1.Printer.Retrieve;

if Crpe1.Printer.Orientation <> orPortrait then Crpe1.Printer.Orientation := orPortrait;

Crpe1.Execute;

Printer Send Method

Declaration

function Send: TCrBoolean;

Type

TCrBoolean = (cFalse, cTrue, cDefault);

Description

The Send method sends the Printer values to the Crystal Reports Print Engine. This method is called automatically when the Execute method is called, provided that SendOnExecute is set to True. It can be called manually in order to force a display of the Print Dialog if ShowDialog is set to True, but it would be better to use the ShowPrintDlg method instead. There are three possible return values for Send:

●cFalseCancel was chosen on the Print Dialog (ShowDialog is set to True).

●cTrueThe Printer properties were sent to the Print Engine successfully.

VCL Reference

504

●cDefaultThe Printer properties were not sent because the properties had not changed from the Report settings, or there was an error (an error would normally raise an exception).

NOTE: We strongly recommend that you leave SendOnExecute to True, and let the Crystal Reports component send the values to the Print Engine. If you set the SendOnExecute property to False, each Sub-class and each property that does not belong to a Sub-class must be manually sent before calling the Execute method. This feature is mainly provided for debugging purposes.

Example

In this example, the Printer settings are sent from the Crystal component to the Crystal Reports Print Engine DLL. This is normally not necessary since it is handled automatically in the Execute method:

Crpe1.ReportName := 'C:\Company.rpt';

Crpe1.Printer.Name := 'HP Laserjet 4';

Crpe1.Printer.Send;

Crpe1.Execute;

Printer ShowPrintDlg Method

Declaration

function ShowPrintDlg: boolean;

Description

The ShowPrintDlg method causes the Printer dialog box to appear so that the user can select the Printer options directly from the dialog. The dialog box looks like this:

VCL Reference

505

Any options selected on the dialog box will automatically update the components Printer and PrintOptions properties when the OK button is clicked. If Cancel is chosen, the Crystal component will not be updated.

Another way of doing the same thing is to set the ShowDialog property to True. This will cause the same dialog box to appear, but it will not appear until the Execute method for the main component is called. If this method is used, and Cancel is selected from the Dialog, the Report will not be processed (i.e. Execute will be exited before running the Report to completion).

If you do not want the user to see the PrintOptions part of the dialog, run the Delphi PrintDialog instead, and use the GetCurrent method after the dialog is closed. If you only want them to change the PrintOptions properties and not the Printer properties, set the PrintOptions property PromptForOptions to True.

Example

The following code illustrates one way of using the ShowPrintDlg method:

Crpe1.ReportName := 'C:\Company.rpt'; Crpe1.Output := toPrinter;

if Crpe1.Printer.ShowPrintDlg then Crpe1.Execute;

PrintOptions Properties

PrintOptions Collation property

Declaration

property Collation: TCrCollation;

Type

TCrCollation = (Uncollated, Collated, DefaultCollation);

Description

Collation is applicable when printing out more than one copy of a Report. It determines if the pages will be printed out by Report, or by page.

For example, if printing out two copies of a 3-page Report, setting Collation to Collated will cause all the pages to be printed out for the first copy, then all the pages for the next copy. Setting Collation to Uncollated will cause two copies of page 1 to be printed, then two copies of page 2, then two copies of page 3.

The default VCL setting for Collation is DefaultCollation.

NOTE: This property only applies if Output is toPrinter.

VCL Reference

506

Example

This code example changes the PrintOption properties to print out two copies of pages 2 & 3 from the Report, collated:

Crpe1.ReportName := 'MyReport.rpt'; Crpe1.Output := toPrinter;

with Crpe1.PrintOptions do begin

Collation := Collated; Copies := 2;

StartPage := 2;

StopPage := 3; end; Crpe1.Execute;

PrintOptions Copies property

Declaration

property Copies: Word;

Description

Copies determines how many copies of a Report will be printed.

The default VCL setting for Copies is 1.

To leave Copies unchanged from the Report setting, set Copies to 0.

NOTE: This property only applies if Output is toPrinter.

Example

This code example changes the PrintOption properties to print out two copies of pages 2 & 3 from the Report, collated:

Crpe1.ReportName := 'MyReport.rpt'; Crpe1.Output := toPrinter;

with Crpe1.PrintOptions do begin

Collation := Collated; Copies := 2;

StartPage := 2;

StopPage := 3; end; Crpe1.Execute;

VCL Reference

507