PrintEnded

Declaration

property PrintEnded: Boolean;

Description

PrintEnded is a run-time, read-only property that indicates when the Print Job is finished processing. The value of this property is True when the Engine is done running the report. When Output is set to go toWindow, this property will not return True until you have gone to the last page of the Report (use Status instead in this case).

NOTE: You can also use the OnPrintEnded event to the same effect.

Example

This example sends the Report to the Printer. It will not allow the program to close the current Form until the printing is finished.

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

while not Crpe1.PrintEnded do Application.ProcessMessages;

Close;

Printer

Declaration

property Printer: TCrpePrinter;

Type

TCrpePrinter = class(TPersistent)

Description

The Printer object contains all of the properties that relate to setting the Printer to be used for printing the Report.

●The Name property takes the name of the Printer that is to be selected for the Report.

●The Driver property takes the Printer Driver associated with that printer.

VCL Reference

68

●The Port property takes the Printer Port associated with that printer.

●The Mode property takes the Handle to the DevMode pointer for that printer.

●The PMode property (which is a pointer to the DevMode, rather than a handle) gives direct access to the DevMode structure, which can be used to manipulate other printer-related settings. See DevMode Structure, Page 70, for more info on the members of the DevMode structure. Mode and PMode are both updated if either one is changed.

●The Retrieve method can be used to get the Printer and its settings from the Report and automatically fill the Name, Driver, Port, and Mode properties with the values.

Traditionally we required all four of those properties to have values before the Printer could be changed. This is no longer necessary. The only property that actually needs to be set now is the Name property, which can be set directly:

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

or from the Printers object in Delphi:

Crpe1.Printer.Name := Printer.Printers[2];

Alternatively, the GetCurrent method can be called to retrieve the currently selected printer. If GetCurrent is used after the PrintDialog is called, it will pick up the selected Printer and automatically fill the Name, Driver, Port, Mode, and PMode properties.

●The Orientation property controls the orientation of the Report, and can be set to orDefault, orPortrait, or orLandscape.

●The PreserveRptSettings set contains three properties that can be used to make sure certain settings are preserved from the Report when the Printer is changed: prOrientation, prPaperSize, prPaperSource (bin). If you desire the Orientation to be preserved as it was when the Report was designed, include the prOrientation value as part of the PreserveRptSettings set. Likewise with the other two set properties.

●The ShowDialog property replaces the previous UserPrinterSetup property. If ShowDialog is true, a PrintDialog is displayed when the Send method is called. This normally happens within the component's Execute method; it is not normally necessary to call the Send method in code.

●Another way of invoking the PrintDialog at any time (not only when Send or Execute is called), is to use the ShowPrintDlg method.

●The Clear method can be used to clear the string properties of the Printer object and to set the other properties to default.

Printer Example

The following code example illustrates how to use some of the Printer object properties:

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

with Crpe1.Printer do

VCL Reference

69

begin

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

{Set Orientation to Landscape} Orientation := orLandscape;

{Preserve PaperSize as set in Report} PreserveRptSettings := [prPaperSize]; {Do not show the PrintDialog on Execute} ShowDialog := False;

end; Crpe1.Execute;

DevMode Structure

The following information describes the 32-bit DevMode structure for Delphi. Note that dmDefaultSource cannot be changed via the DevMode structure for WindowsNT 4.0. Different Windows API calls are required, for which we do not have a sample at this time.

Type

PDeviceMode = PDeviceModeA;

dmDeviceName: array[0..CCHDEVICENAME - 1] of AnsiChar; dmSpecVersion: Word;

dmDriverVersion: Word; dmSize: Word; dmDriverExtra: Word; dmFields: DWORD; dmOrientation: SHORT; dmPaperSize: SHORT; dmPaperLength: SHORT; dmPaperWidth: SHORT; dmScale: SHORT; dmCopies: SHORT; dmDefaultSource: SHORT; dmPrintQuality: SHORT; dmColor: SHORT; dmDuplex: SHORT; dmYResolution: SHORT; dmTTOption: SHORT; dmCollate: SHORT;

dmFormName: array[0..CCHFORMNAME - 1] of AnsiChar; dmLogPixels: Word;

dmBitsPerPel: DWORD; dmPelsWidth: DWORD; dmPelsHeight: DWORD; dmDisplayFlags: DWORD;

VCL Reference

70

dmDisplayFrequency: DWORD; dmICMMethod: DWORD; dmICMIntent: DWORD; dmMediaType: DWORD; dmDitherType: DWORD; dmReserved1: DWORD; dmReserved2: DWORD;

end;

dmDeviceName

Specifies the name of the device the driver supports: for example, "PCL/HP LaserJet" in the case of the Hewlett-Packard LaserJet. Each driver has a unique string.

dmSpecVersion

Specifies the version number of the DEVMODE structure. For Windows version 3.1, this value should be 0x30A.

dmDriverVersion

Specifies the printer driver version number assigned by the printer driver developer.

dmSize

Specifies the size, in bytes, of the DEVMODE structure. (This value does not include the optional dmDriverData member for device-specific data, which can follow the structure.) If an application manipulates only the driver-independent portion of the data, it can use this member to find out the length of the structure without having to account for different versions.

dmDriverExtra

Specifies the size, in bytes, of the optional dmDriverData member for device-specific data, which can follow the structure. If an application does not use device-specific information, it should set this member to zero.

dmFields

Specifies a set of flags that indicate which of the remaining members in the DEVMODE structure have been initialized. It can be any combination (or it can be none) of the following values:

Constant	Value
DM_ORIENTATION	1
DM_PAPERSIZE	2
DM_PAPERLENGTH	4
DM_PAPERWIDTH	8
DM_SCALE	$10
DM_COPIES	$100
DM_DEFAULTSOURCE	$200
DM_PRINTQUALITY	$400

VCL Reference

71

Constant	Value
DM_COLOR	$800
DM_DUPLEX	$1000
DM_YRESOLUTION	$2000
DM_TTOPTION	$4000
DM_COLLATE	$8000
DM_FORMNAME	$10000
DM_LOGPIXELS	$20000
DM_BITSPERPEL	$40000
DM_PELSWIDTH	$80000
DM_PELSHEIGHT	$100000
DM_DISPLAYFLAGS	$200000
DM_DISPLAYFREQUENCY	$400000
DM_RESERVED1	$800000
DM_RESERVED2	$1000000
DM_ICMMETHOD	$2000000
DM_ICMINTENT	$4000000
DM_MEDIATYPE	$8000000
DM_DITHERTYPE	$10000000

NOTE: A printer driver supports only those members that are appropriate for the printer technology.

dmOrientation

Specifies the orientation of the paper. It can be either of the following:

Constant	Value
DMORIENT_PORTRAIT	1
DMORIENT_LANDSCAPE	2

dmPaperSize

Specifies the size of the paper to print on. This member may be set to zero if the length and width of the paper are specified by the dmPaperLength and dmPaperWidth members, respectively. Otherwise, the dmPaperSize member can be set to one of the following predefined values:

Constant	Value	Description
DMPAPER_LETTER	1	{Letter 8 12 x 11 in}
DMPAPER_FIRST		DMPAPER_LETTER
DMPAPER_LETTERSMALL	2	{Letter Small 8 12 x 11 in}

VCL Reference

72

Constant	Value	Description
DMPAPER_TABLOID	3	{Tabloid 11 x 17 in}
DMPAPER_LEDGER	4	{Ledger 17 x 11 in
DMPAPER_LEGAL	5	{Legal 8 12 x 14 in}
DMPAPER_STATEMENT	6	{Statement 5 12 x 8 12 in}
DMPAPER_EXECUTIVE	7	{Executive 7 14 x 10 12 in}
DMPAPER_A3	8	{A3 297 x 420 mm
DMPAPER_A4	9	{A4 210 x 297 mm
DMPAPER_A4SMALL	10	{A4 Small 210 x 297 mm}
DMPAPER_A5	11	{A5 148 x 210 mm}
DMPAPER_B4	12	{B4 (JIS) 250 x 354}
DMPAPER_B5	13	{B5 (JIS) 182 x 257 mm}
DMPAPER_FOLIO	14	{Folio 8 12 x 13 in}
DMPAPER_QUARTO	15	{Quarto 215 x 275 mm}
DMPAPER_10X14	16	{10x14 in}
DMPAPER_11X17	17	{11x17 in}
DMPAPER_NOTE	18	{Note 8 12 x 11 in}
DMPAPER_ENV_9	19	{Envelope #9 3 78 x 8 78}
DMPAPER_ENV_10	20	{Envelope #10 4 18 x 9 12}
DMPAPER_ENV_11	21	{Envelope #11 4 12 x 10 38}
DMPAPER_ENV_12	22	{Envelope #12 4 \276 x 11}
DMPAPER_ENV_14	23	{Envelope #14 5 x 11 12}
DMPAPER_CSHEET	24	{C size sheet}
DMPAPER_DSHEET	25	{D size sheet}
DMPAPER_ESHEET	26	{E size sheet}
DMPAPER_ENV_DL	27	{Envelope DL 110 x 220mm}
DMPAPER_ENV_C5	28	{Envelope C5 162 x 229 mm}
DMPAPER_ENV_C3	29	{Envelope C3 324 x 458 mm}
DMPAPER_ENV_C4	30	{Envelope C4 229 x 324 mm}
DMPAPER_ENV_C6	31	{Envelope C6 114 x 162 mm}
DMPAPER_ENV_C65	32	{Envelope C65 114 x 229 mm}
DMPAPER_ENV_B4	33	{Envelope B4 250 x 353 mm}
DMPAPER_ENV_B5	34	{Envelope B5 176 x 250 mm}
DMPAPER_ENV_B6	35	{Envelope B6 176 x 125 mm}
DMPAPER_ENV_ITALY	36	{Envelope 110 x 230 mm}

VCL Reference

73

Constant	Value	Description
DMPAPER_ENV_MONARCH	37	{Envelope Monarch 3.875 x 7.5 in}
DMPAPER_ENV_PERSONAL	38	{6 34 Envelope 3 58 x 6 12 in}
DMPAPER_FANFOLD_US	39	{S Std Fanfold 14 78 x 11 in}
DMPAPER_FANFOLD_STD_GERMAN	40	{German Std Fanfold 8 12 x 12 in}
DMPAPER_FANFOLD_LGL_GERMAN	41	{German Legal Fanfold 8 12 x 13 in}
DMPAPER_ISO_B4	42	{B4 (ISO) 250 x 353 mm}
DMPAPER_JAPANESE_POSTCARD	43	{Japanese Postcard 100 x 148 mm}
DMPAPER_9X11	44	{9 x 11 in}
DMPAPER_10X11	45	{10 x 11 in}
DMPAPER_15X11	46	{15 x 11 in}
DMPAPER_ENV_INVITE	47	{Envelope Invite 220 x 220 mm}
DMPAPER_RESERVED_48	48	{RESERVED--DO NOT USE}
DMPAPER_RESERVED_49	49	{RESERVED--DO NOT USE}
DMPAPER_LETTER_EXTRA	50	{Letter Extra 9 \275 x 12 in}
DMPAPER_LEGAL_EXTRA	51	{Legal Extra 9 \275 x 15 in}
DMPAPER_TABLOID_EXTRA	52	{Tabloid Extra 11.69 x 18 in}
DMPAPER_A4_EXTRA	53	{A4 Extra 9.27 x 12.69 in}
DMPAPER_LETTER_TRANSVERSE	54	{Letter Transverse 8 \275 x 11 in}
DMPAPER_A4_TRANSVERSE	55	{A4 Transverse 210 x 297 mm}
DMPAPER_LETTER_EXTRA_TRANSVERSE	56	{Letter Extra Transverse 9\275x12 in}
DMPAPER_A_PLUS	57	{SuperASuperAA4 227 x 356 mm}
DMPAPER_B_PLUS	58	{SuperBSuperBA3 305 x 487 mm}
DMPAPER_LETTER_PLUS	59	{Letter Plus 8.5 x 12.69 in}
DMPAPER_A4_PLUS	60	{A4 Plus 210 x 330 mm}
DMPAPER_A5_TRANSVERSE	61	{A5 Transverse 148 x 210 mm}
DMPAPER_B5_TRANSVERSE	62	{B5 (JIS) Transverse 182 x 257 mm}
DMPAPER_A3_EXTRA	63	{A3 Extra 322 x 445 mm}
DMPAPER_A5_EXTRA	$40	{A5 Extra 174 x 235 mm}
DMPAPER_B5_EXTRA	65	{B5 (ISO) Extra 201 x 276 mm}
DMPAPER_A2	66	{A2 420 x 594 mm}
DMPAPER_A3_TRANSVERSE	67	{A3 Transverse 297 x 420 mm}
DMPAPER_A3_EXTRA_TRANSVERSE	68	{A3 Extra Transverse 322 x 445 mm}
DMPAPER_LAST		DMPAPER_A3_EXTRA_TRANSVERSE
DMPAPER_USER		$100

VCL Reference

74

dmOrientation

Specifies the orientation of the paper. It can be either of the following: DMORIENT_PORTRAIT (1) or DMORIENT_LANDSCAPE (2).

dmPaperLength

Specifies a paper length in tenths of a millimeter. This parameter overrides the paper length specified by the dmPaperSize member either for custom paper sizes or for such devices as dot-matrix printers that can print on a variety of page sizes.

dmPaperWidth

Specifies a paper width in tenths of a millimeter. This parameter overrides the paper width specified by the dmPaperSize member.

dmScale

Specifies the factor by which the printed output is to be scaled. The apparent page size is scaled from the physical page size by a factor of dmScale/100. For example, a letter-size paper with a dmScale value of 50 would contain as much data as a page of size 17 by 22 inches, because the output text and graphics would be half their original height and width.

dmCopies

Specifies the number of copies printed if the device supports multiple-page copies.

dmDefaultSource

Specifies the default bin from which the paper is fed. The application can override this value by using the GETSETPAPERBINS escape. This member can be one of the following values:

Constant	Value
DMBIN_UPPER	1
DMBIN_FIRST	DMBIN_UPPER
DMBIN_ONLYONE	1
DMBIN_LOWER	2
DMBIN_MIDDLE	3
DMBIN_MANUAL	4
DMBIN_ENVELOPE	5
DMBIN_ENVMANUAL	6
DMBIN_AUTO	7
DMBIN_TRACTOR	8
DMBIN_SMALLFMT	9
DMBIN_LARGEFMT	10

VCL Reference

75

Constant	Value
DMBIN_LARGECAPACITY	11
DMBIN_CASSETTE	14
DMBIN_FORMSOURCE	15
DMBIN_LAST	DMBIN_FORMSOURCE
DMBIN_USER	$100 {device specific bins start here}

NOTE: A range of values is reserved for device-specific bins. To be consistent with initialization information, the GETSETPAPERBINS and ENUMPAPERBINS escapes use these values.

dmPrintQuality

Specifies the printer resolution. Following are the four predefined device-independent values:

Constant	Value
DMRES_DRAFT	(-1)
DMRES_LOW	(-2)
DMRES_MEDIUM	(-3)
DMRES_HIGH	(-4)

NOTE: If a positive value is given, it specifies the number of dots per inch (DPI) and is therefore devicedependent.

NOTE: If the printer initializes the dmYResolution member, the dmPrintQuality member specifies the x- resolution of the printer in dots per inch.

dmColor

Specifies whether a color printer is to render color or monochrome output. Possible values are:

Constant	Value
DMCOLOR_MONOCHROME	1
DMCOLOR_COLOR	2

dmDuplex

Specifies duplex (double-sided) printing for printers capable of duplex printing. This member can be one of the following values:

Constant	Value
DMDUP_SIMPLEX	(1)
DMDUP_VERTICAL	(2)
DMDUP_HORIZONTAL	(3)

VCL Reference

76

dmYResolution

Specifies the y-resolution of the printer, in dots per inch. If the printer initializes this member, the dmPrintQuality member specifies the x-resolution of the printer, in dots per inch.

dmTTOption

Specifies how TrueType fonts should be printed. It can be one of the following values:

Constant	Value	Description
DMTT_BITMAP	1	{print TT fonts as graphics}
DMTT_DOWNLOAD	2	{download TT fonts as soft fonts}
DMTT_SUBDEV	3	{substitute device fonts for TT fonts}
DMTT_DOWNLOAD_OUTLINE	4	{download TT fonts as outline soft fonts}

dmCollate

Specifies whether collation should be used when printing multiple copies. (This member is ignored unless the printer driver indicates support for collation by setting the dmFields member to DM_COLLATE.) This member can be one of the following values:

Constant	Value
DMCOLLATE_FALSE	0
DMCOLLATE_TRUE	1

NOTE: Using DMCOLLATE_TRUE provides faster, more efficient output for collation, since the data is sent to the device driver just once, no matter how many copies are required. The printer is told to simply print the page again.

dmFormName

Windows NT: Specifies the name of the form to use; for example, "Letter" or "Legal". A complete set of names can be retrieved by using the EnumForms function. Windows 95: Printer drivers do not use this member.

dmLogPixels

Specifies the number of pixels per logical inch.

dmBitsPerPel

Windows NT: Specifies the color resolution, in bits per pixel, of the display device (for example: 4 bits for 16 colors, 8 bits for 256colors, or 16 bits for 65536 colors). Windows 95: Display drivers use this member, for example, in the ChangeDisplaySettings function. Printer drivers do not use this member.

dmPelsWidth

Windows NT: Specifies the width, in pixels, of the visible device surface. Windows 95: Display drivers use this member, for example, in the ChangeDisplaySettings function. Printer drivers do not use this member.

VCL Reference

77

dmPelsHeight

Windows NT: Specifies the height, in pixels, of the visible device surface. Windows 95: Display drivers use this member, for example, in the ChangeDisplaySettings function. Printer drivers do not use this member.

dmDisplayFlags

Windows NT: Specifies the device's display mode. This member can be one of the following values:

l

Constant	Value	Description
DM_GRAYSCALE	1	Specifies that the display is a NON-color device. If this flag is not set,
		color is assumed.
DM_INTERLACED	2	Specifies that the display mode is interlaced. If the flag is not set,
		NON-interlaced is assumed. Windows 95: Display drivers use this
		member, for example, in the ChangeDisplaySettings function. Printer
		drivers do not use this member.

dmDisplayFrequency

Windows NT: Specifies the frequency, in hertz (cycles per second), of the display device in a particular mode. Windows 95: Display drivers use this member, for example, in the ChangeDisplaySettings function. Printer drivers do not use this member.

dmICMMethod

Windows 95: Specifies how ICM is handled. For a non-ICM application, this member determines if ICM is enabled or disabled. For ICM applications, Windows examines this member to determine how to handle ICM support. This member can be one of the following predefined values, or a driver-defined value greater than the value of DMICMMETHOD_USER:Windows NT: This member is not supported on Windows NT.

Constant	Value	Description
DMICMMETHOD_NONE	1	Windows 95 only: Specifies that ICM is disabled.
DMICMMETHOD_SYSTEM	2	Windows 95 only: Specifies that ICM is handled by Windows.
DMICMMETHOD_DRIVER	3	Windows 95 only: Specifies that ICM is handled by the device
		driver.
DMICMMETHOD_DEVICE	4	Windows 95 only: Specifies that ICM is handled by the
		destination device. The printer driver must provide a user
		interface for setting this member. Most printer drivers
		support only the DMICMMETHOD_SYSTEM or
		DMICMMETHOD_NONE value. Drivers for PostScript
		printers support all values.
DMICMMETHOD_USER	$100	Device-specific methods start here

VCL Reference

78

dmICMIntent

Windows 95: Specifies which of the three possible color matching methods, or intents, should be used by default. This member is primarily for non-ICM applications. ICM applications can establish intents by using the ICM functions. This member can be one of the following predefined values, or a driver defined value greater than the value of DMICM_USER:Windows NT: This member is not supported on Windows NT.

DMICM_SATURATE	1	{Maximize color saturation}
DMICM_CONTRAST	2	{Maximize color contrast}
DMICM_COLORMETRIC	3	{Use specific color metric}
DMICM_USER	$100	{Device-specific intents start here}

dmMediaType

Windows 95: Specifies the type of media being printed on. The member can be one of the following predefined values, or a driver-defined value greater than the value of DMMEDIA_USER:Windows NT: This member is not supported on Windows NT.

Constant	Value	Description
DMMEDIA_STANDARD	1	Standard paper
DMMEDIA_TRANSPARENCY	2	Transparency
DMMEDIA_GLOSSY	3	Glossy paper

dmDitherType

Windows 95: Specifies how dithering is to be done. The member can be one of the following predefined values, or a driver-defined value greater than the value of DMDITHER_USER: Windows NT: This member is not supported on Windows NT.

Constant	Value	Description
DMDITHER_NONE	1	No dithering
DMDITHER_COARSE	2	Dither with a coarse brush
DMDITHER_FINE	3	Dither with a fine brush
DMDITHER_LINEART	4	LineArt dithering
DMDITHER_ERRORDIFFUSION	5	LineArt dithering
DMDITHER_RESERVED6	6	LineArt dithering
DMDITHER_RESERVED7	7	LineArt dithering
DMDITHER_RESERVED8	8	LineArt dithering
DMDITHER_RESERVED9	9	LineArt dithering
DMDITHER_GRAYSCALE	10	Device does gray-scaling
DMDITHER_USER	256	Device-specific dithers start here

VCL Reference

79

dmReserved1

Windows 95: Not used; must be zero.Windows NT: This member is not supported on Windows NT.

dmReserved2

Windows 95: Not used; must be zero.Windows NT: This member is not supported on Windows NT.

Remarks

A device driver's private data follows the public portion of the DEVMODE structure. The size of the public data can vary for different versions of the structure. The dmSize member specifies the number of bytes of public data, and the dmDriverExtra member specifies the number of bytes of private data.

Setting Port to FILE

A request we get quite often is that developers would like to set the Port to something other than what is specified in the Printer driver. The most common use of this is to set the output to FILE. This used to work with earlier Crystal versions, but in 5.x.x.108 and 6.0 of the Print Engine this no longer works. The reason for the change is that the previous method was not reliable. This issue has been addressed in Seagate Crystal Reports 7, by the addition of an OutputFileName property to the PrintOptions object.

For users of Crystal 5.0 and 6.0, the only work-around is to create another Printer Driver in Windows that is set to go to the desired Port, and then switch to that Driver when a different Port setting is desired. This however raises another question. When a Report is printed to FILE, a prompt dialog box appears requesting the user to enter the destination Filename. This is not always convenient, especially in cases where Reports must be run in batches, and possibly overnight when there is no one around to enter the destination Filenames. This problem can be worked around by using Windows API calls to obtain the handle to the prompting dialog box and then using that handle to pass the Filename in via code. Here is an example of how this could be done in Delphi:

{SendFilename is called after "Print To File" dialog appears} procedure SendFilename;

var

aFile: array[0..255] of char; hDlg : Hwnd;

begin

{Get the "Print To File" Dialog handle} hDlg := FindWindow(nil, 'Print To File'); {If it was found...}

if hDlg > 0 then begin

{Copy the new Filename to the buffer} StrCopy(aFile, 'C:\Reports\Report1.prn');

{Send the Text to the Edit field of the Dialog} SendDlgItemMessage(hDlg, 1152, WM_SETTEXT, 0, LongInt(@aFile));

{Show the Dialog: If this isn't done, WM_LBUTTONDOWN needs to be sent twice}

SendMessage(hDlg, WM_SHOWWINDOW,0,0);

{Send a Button Down to the OK button of the Dialog}

VCL Reference

80