Description

The PMode property specifies a pointer to the DevMode structure associated with a certain Printer, and can be used to control DevMode-specific properties. Note that it is no longer necessary to fill in a value for this property, since the Crystal component will obtain this information internally provided a valid value is specified in the Name property.

The Retrieve method will also fill the PMode property with a value from the Printer settings saved with the current Report, or the GetCurrent method can be used right after showing the Delphi PrintDialog to obtain the Printer information and fill the Printer properties with values.

Example

The following example shows how to use the PMode property to check DevMode settings for the Printer properties saved with the Report (Orientation in this case):

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

{Get Printer settings from Report} Crpe1.Printer.Retrieve;

{Check the Orientation}

case Crpe1.Printer.PMode^.dmOrientation of DMORIENT_PORTRAIT : ShowMessage('Orientation is Portrait');

DMORIENT_LANDSCAPE : ShowMessage('Orientation is Landscape'); end;

Printer Port Property

Declaration

property Port: TCrPrinterName;

Type

TCrPrinterName = string[80];

Description

The Port property contains the Port name of the Printer.

Traditionally, the Crystal VCL used to require the Name, Driver, Port and Mode properties to be set before it would change the Printer for a Report. With the new Crystal component, however, this is not required. The only property that needs to be specified is the Name. The component will automatically fill in the other values (if the Printer Name is valid), when the component's Execute method is called.

VCL Reference

495

If the Retrieve method is used, the Port property will contain the Port name for the Printer that was specified in the Report (or the default printer if the Printer specified in the Report is not valid). Alternatively, the GetCurrent method can be called right after showing Delphi's PrintDialog, and it will also fill the Printer properties with values corresponding to the selected Printer.

NOTE: Do not attempt to set the Port property to 'FILE:' if the Printer Driver has not been set up that way. It will not work. Crystal Reports 7 has built-in support for printing to FILE via the OutputFileName property of the PrintOptions class. For Crystal 5 and 6 users, see Setting Port to FILE.

Example

This code uses the Printer properties to change Printers to one selected via the Print Dialog. It also makes sure that the Orientation defined in the Report is preserved.

procedure RunReport; var

lpPrinter, lpDriver, lpPort : pChar;

hMode	: THandle;
pMode	: PDevMode;
nOrientation	: integer;
begin

{Set ReportName}

Crpe1.ReportName := 'C:\Company.rpt' {Get Printer settings from Report} Crpe1.Printer.Retrieve;

{Check the Orientation} hMode := Crpe1.Printer.Mode; pMode := GlobalLock(hMode);

case pMode^.dmOrientation of DMORIENT_PORTRAIT : nOrientation := 0; DMORIENT_LANDSCAPE : nOrientation := 1;

end; GlobalUnlock(hMode);

{Allocate memory for Printer property variables} try

lpPrinter := StrAlloc(255); lpDriver := StrAlloc(255); lpPort := StrAlloc(255);

except

if lpPrinter <> nil then StrDispose(lpPrinter);

if lpDriver <> nil then StrDispose(lpDriver);

if lpPort <> nil then

StrDispose(lpPort);

Exit; end;

VCL Reference

496

{Show the PrintDialog}

if PrintDialog1.Execute then {if OK was clicked} begin

{Get Selected Printer; could also use Crpe1.SelectPrinter} Printer.GetPrinter(lpPrinter, lpDriver, lpPort, hMode); {Set PrinterName}

Crpe1.Printer.Name := StrPas(lpPrinter);

{Set PrinterDriver: Check for Null - Win95 32-bit problem} if Length(StrPas(lpDriver)) <> 0 then

Crpe1.Printer.Driver := StrPas(lpDriver) else

Crpe1.Printer.Driver := StrPas(lpPrinter); {Set PrinterPort}

Crpe1.Printer.Port := StrPas(lpPort); {Set PrinterMode}

Crpe1.Printer.Mode := hMode;

{Make sure the Orientation remains as in Report} pMode := GlobalLock(hMode);

case nOrientation of

0:pMode^.dmOrientation := DMORIENT_PORTRAIT;

1:pMode^.dmOrientation := DMORIENT_LANDSCAPE;

end; GlobalUnlock(hMode);

{Run the Report} Crpe1.Execute;

end; StrDispose(lpPort); StrDispose(lpDriver); StrDispose(lpPrinter);

end;

The above code can be greatly simplified by using some of the other Printer object methods & properties:

procedure RunReport; begin

{Set ReportName}

Crpe1.ReportName := 'C:\Company.rpt'; {Preserve Orientation from Report}

Crpe1.Printer.PreserveRptSettings[prOrientation]; {Prompt for Printer at Execute} Crpe1.Printer.ShowDialog := True;

{Run the Report} Crpe1.Execute;

end;

VCL Reference

497

Printer PreserveRptSettings property

Declaration

property PreserveRptSettings: TCrPreserveRptSettings;

Type

TCrPreserveRptSettings = set of TCrPreserveRptSet; TCrPreserveRptSet = (prOrientation, prPaperSize, prPaperSource);

Description

PreserveRptSettings is used to keep certain Printer-related settings (Orientation, Paper Size, Paper Source) as they were when the Report was designed, even though another Printer is specified which may not have the same values specified by default. To take full advantage of this property (and the Orientation property) requires some understanding of the Printer Setup dialog box in the Crystal Reports designer:

Orientation

This section of the Printer Setup dialog box determines whether the Report is Portrait or Landscape. This setting can be preserved as it is in the Report by adding prOrientation to the PreserveRptSettings set:

Crpe1.Printer.PreserveRptSettings := [prOrientation];

VCL Reference

498

Paper Size

This section of the Printer Setup dialog box determines what the Paper Size of the Report will be. This setting can be preserved as it is in the Report by adding prPaperSize to the PreserveRptSettings set:

Crpe1.Printer.PreserveRptSettings := [prPaperSize];

Paper Source

This section of the Printer Setup dialog box determines what the Paper Source on the Printer will be (i.e. which Paper bin is used). This setting can be preserved as it is in the Report by adding prPaperSource to the PreserveRptSettings set:

Crpe1.Printer.PreserveRptSettings := [prPaperSource];

Preserving Paper Source may not function correctly yet on Windows NT 4.0 (see the Note below).

Default Properties

This checkbox specifies whether the Report will obtain the DevMode properties from the specified Printer, of whether it will save it's own specific settings. It is important if you plan to control or preserve Orientation, Paper Size, and Paper Source, that this box is UNchecked. Notice that if any of the Orientation or Paper items (in the Print Setup dialog box) are changed or edited, Default Properties will automatically be unchecked.

No Printer

This checkbox specifies whether the Report will have any specific Printer information saved with it or not. If this box is checked, it will be impossible to obtain any Printer specific information from the Report at runtime. Make sure it is UNchecked, or PreserveRptSettings and Retrieve will not work as expected.

NOTE: There is currently a small problem with PreserveRptSettings for prPaperSource and Windows NT 4.0. In NT4, the dmDefaultSource property of the DevMode structure cannot be modified. The Paper Source (Bin) can be associated with a certain Page Size by the NT Administrator (in the Windows Control Panel Printer Setup). Thereafter, any documents printed with that Page Size automatically go to the Bin associated with that size, regardless of any other bin setting. Therefore, it appears that Paper Source has to be changed using other Windows API calls, which we have not yet implemented in the VCL.

Example

The following code example uses the PreserveRptSettings property to preserve the PaperSize as defined in the Report, regardless of which Printer is chosen (note: this will only work if the Printer chosen supports that Page Size):

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

with Crpe1.Printer do begin

{Set Name to 3rd Printer in Printers list} Name := Printer.Printers[2];

{Set Orientation to Landscape}

VCL Reference

499