diff --git a/docs/xml/lcl/printers.xml b/docs/xml/lcl/printers.xml index 6caf982ef4..1b878288bd 100644 --- a/docs/xml/lcl/printers.xml +++ b/docs/xml/lcl/printers.xml @@ -2,1270 +2,3064 @@ + ==================================================================== + Printers + ==================================================================== + --> - Defines Printers to be used as output from Lazarus applications - + Defines printer output devices for Lazarus applications + +

+ Printers.pas implements basic facilities needed for the TPrinter print device. A TPrinterCanvas class is included to position, format, and render pages for the print device. +

+

+ Printers.pas is a required unit for use with the printer4lazarus package. See the Lazarus Wiki for more information about the printer4lazarus package: +

+
+
Printing
+
+ + https://wiki.lazarus.freepascal.org/Printing + +
+
Using the Printer
+
+ + https://wiki.lazarus.freepascal.org/Using_the_printer + +
+
+ + - - - - - - - - - - - - - - - - - - + + + + + - - EPrinter - Exception handler for printer error + Exception raised for errors in TPrinter methods - - + + + - + - - - + Represents page orientations for printers + +

+ TPrinterOrientation is an enumerated type with values that represent page orientations used for print devices and their canvases. TPrinterOrientation is the type used to implement TPrinter.Orientation and TPrinterCanvas.Orientation properties. +

+ + + + + - - + Output uses Portrait orientation - - + Output uses Landscape orientation - - + Output uses Landscape orientation with coordinates rotated 180 degrees - - + Output uses Portrait orientation with coordinates rotated 180 degrees - + - - + Represents capabilities for print devices + +

+ Not implemented in the current LCL version. +

+ - - + Devices supports copy mode - - + Device supports page orientations - - + Device supports custom collation for printed pages - + - - + Stores a set of capability values for a print device + +

+ Not implemented in the current LCL version. +

+ - + - + Represents state values for a print device - - + State is not defined or unknown - - + Device is ready - - + Device is printing - - + Device has been stopped - + - + Represents connection types for a print device - - + Device is attached to the local computer system - - + Device is a network-enabled printer - + - - TPrinterCanvas - instance of TCanvas specially designed for printers - - - + Implements a canvas used for TPrinter device output + +

+ TPrinterCanvas is a TCanvas descendant which implements a canvas used to position, format, and output values from a TPrinter print device. The TPrinter instance which provides the capabilities for the device is passed as an argument to the constructor, and stored in the Printer property. +

+

+ TPrinterCanvas provides methods which mirror the operations performed in TPrinter, like: BeginDoc, NewPage, BeginPage, EndPage and EndDoc. Methods in the canvas are called from the corresponding methods in TPrinter when its RawMode property is set to False. +

+

+ A TPrinterCanvas (or descendant) class reference is used to implement the TPrinter.CanvasClass property. +

+ + + + + + - - - + + + + + + + + + + + + + + + + Gets the value for the Orientation property - + + + - - - - - + + Value for the property - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + - + Gets the value for the PageHeight property - - + + + - - + Value for the property - + - + Gets the value for the PageWidth property - - + + + - - + Value for the property - + + + Gets the value for the PaperHeight property + + + + + + + Value for the property + + + + Gets the value for the PaperWidth property + + + + + + + Value for the property + + - + Gets the value for the Title property - + + + - - + Value for the property - - - + + + Gets the value for the XDPI property - - + + + - - - + + Value for the property - - - + + + Gets the value for the YDPI property - - + + + - - - + + Value for the property - + + + Sets the value for the Orientation property + + + + + + + New value for the property + + + + Sets the value for the PaperHeight property + + + + + + + New value for the property + + + + Sets the value for the PaperWidth property + + + + + + + New value for the property + + - + Sets the value for the Title property - - + + + - - + New value for the property - - - - BeginDoc - method to start printing a document + + + Indicates if the default values are used for page margins + +

+ HasDefaultMargins is a Boolean function used to determine if the default values are being used in the page margin properties: LeftMargin, RightMargin, TopMargin, BottomMargin. The return value is True when each of the properties contains the value 0 (zero). +

+

+ HasDefaultMargins is used when getting the values for the PageHeight and PageWidth properties. When False, the page dimensions are adjusted to reserve space needed for the page margin properties. +

+ + + + + + + + + + + + + + + + True when the default values (0) are used in the page margin properties + + + + Sets the value for the XDPI property - - + + + - - - - NewPage - method to start printing a new page + + New value for the property + + + + Sets the value for the YDPI property - - + + + - - - - EndDoc - method to finish printing a document + + New value for the property + + + + Gets the value for the LeftMargin property - - + + + + + - + + Value for the property + + + + Gets the value for the TopMargin property + + + + + + + Value for the property + + + + Gets the value for the BottomMargin property + + + + + + + Value for the property + + + + Gets the value for the RightMargin property + + + + + + + Value for the property + + - - Create - constructor to make a canvas for the specified printer type, APrinter - - - - + Constructor for the class instance + +

+ Create is the constructor for the class instance, and calls the inherited constructor on entry. Create sets the value for the Printer property to the value in the APrinter parameter. +

+ + + + - - - - - Changing - method for dealing with changes in printing status - - - + + + Performs actions needed to start printing a document + +

+ BeginDoc performs actions needed to start printing a document using the printer canvas. BeginDoc sets the value in the PageNumber property to 1. The NewPage method is called when each subsequent page is started. +

+

+ BeginDoc is called from the TPrinter.BeginDoc method when its RawMode property is set to False. +

+ + + + + + - + + + Performs actions needed when a new page is started + +

+ NewPage is procedure used to perform actions needed when a new page is started. NewPage calls the BeginPage method which increments the value in PageNumber. EndPage is called when the page has been completed. +

+

+ NewPage is called from the TPrinter.NewPage method. +

+ + + + + + + + + + + Performs actions needed when a page is started + +

+ BeginPage is a procedure used to perform actions needed when page is started for the canvas. BeginPage increments the value in the PageNumber property. +

+

+ BeginPage is called from the TPrinter.BeginPage method. +

+ + + + + + + + + + Performs actions needed when a page is completed + +

EndPage has an empty implementation in TPrinterCanvas.

+

EndPage is called from the TPrinter.EndPage method.

+ + + + + + + + Performs actions needed when a document has finished printing + +

+ EndDoc is a procedure used to perform actions needed when a document has finished printing. EndDoc has an empty implementation in TPrinterCanvas. +

+

+ EndDoc is called from both the EndDoc and the Abort methods in TPrinter. +

+ + + + + + + + + + Signals the OnChanging event when the printer status is changed + + +

+ Changing is an overridden procedure used to signal the OnChanging event handler (when assigned) for the canvas. Changing is overridden to ensure that an assigned Printer in the class instance has the value pfPrinting in its internal Flags. This is done by calling the CheckPrinting method in TPrinter, which can raise an EPrinter exception if it does not have the expected value in its Printing property. +

+

+ Changing calls the inherited method to signal the OnChanging event handler prior to exiting from the method. +

+ + + + + + + + + - The type of Printer for which this canvas is preparing the document - - + Device which uses the canvas to print a document + +

+ Printer is a read-only TPrinter property which contains the printer device for the canvas. Printer is used to determine the capabilities selected/enabled for the output device, such as: +

+
+
Status
+
Ready, Printing, Stopped, et. al.
+
Paper Size
+
+ Printable area is determined by the page dimensions and values in the margin properties. +
+
Resolution
+
Number of DPI (Dots per Inch) for the device
+
+

+ The value for the property is passed as an argument to the Create constructor. +

+ + + + + - + - The Title of the current printer canvas - - + Title for the document rendered using the printer canvas + +

+ Title is a String property which contains the title for the current document. The value for the property is read from the corresponding property in Printer (when available). Setting a new value for the property causes the Title property in the assigned Printer to be updated. +

+ + + + + - + - The PageHeight to be used for the current canvas - - + Size of the printable area for the page on the vertical axis + +

+ PageHeight is a read-only Integer property with the size for the printable page area on the vertical axis of the page orientation. The value is expressed as the number of "Dots" on the device in Printer. +

+

+ When Printer has been assigned and HasDefaultMargins is True, the PageHeight property in the device is used. Otherwise, the property value is calculated by subtracting the values in TopMargin and BottomMargin from the PaperHeight for the printer Canvas. +

+

+ Use PageWidth to get size of the printable page on the horizontal axis for the page orientation. +

+

+ Use PaperHeight and PaperWidth to get the dimensions for the selected paper in Printer. +

+ + + + + + + + + + + + - + - The PageWidth to be used for the current canvas - - + Size of the printable area for the page on the horizontal axis + +

+ PageWidth is a read-only Integer property with the size for the printable page area on the horizontal axis of the page orientation. The value is expressed as the number of "Dots" on the device in Printer. +

+

+ When Printer has been assigned and HasDefaultMargins is True, the PageWidth property in the device is used. Otherwise, the property value is calculated by subtracting the values in LeftMargin and RightMargin from the PaperWidth for the printer Canvas. +

+

+ Use PageHeight to get size of the printable page on the vertical axis for the page orientation. +

+

+ Use PaperHeight and PaperWidth to get the dimensions for the selected paper in Printer. +

+ + + + + + + + + + + + - + + + Horizontal size for the paper selected in the print device + +

+ PaperWidth is an Integer property which contains the width for the current paper as the number of "Dots" along its horizontal axis. +

+

+ When Printer has been assigned, the Width in its PaperSize property is used as the property value. Otherwise, the existing property value is returned. If the existing value is 0 (zero), the width (in Dots) for the "A4" paper size (in portrait orientation) is used as the property value. +

+

+ Use PaperHeight to get the height for the paper in Dots along its vertical axis. +

+ + + + + + + + + + Vertical size for the paper selected in the print device + +

+ PaperHeight is an Integer property which contains the height for the current paper as the number of "Dots" along its vertical axis. +

+

+ When Printer has been assigned, the Height in its PaperSize property is used as the property value. Otherwise, the existing property value is returned. If the existing value is 0 (zero), the height (in Dots) for the "A4" paper size (in portrait orientation) is used as the property value. +

+

+ Use PaperWidth to get the width for the paper in Dots along its horizontal axis. +

+ + + + + + + + - - PageNumber - the number of the current page being prepared for printing - - + The number for the current page in the printer canvas + +

+ PageNumber is a read-only Integer property which contains the current page number for the document being rendered to the printer canvas. The value in the property is incremented each time the BeginPage method is called for the printer canvas. +

+ + + + + - - - - TopMarging - the size of the margin at the top of each page - - + + + The size of the margin at the top of the canvas + +

+ TopMargin is an Integer property which contains the size for the area between the edge of the paper and the top of the content on the page. Margin values are expressed as the number of "Dots" for the native printer resolution (YDPI). To achieve a .5in margin on a 300DPI laser printer, use the value 150. +

+

+ The value for the property is normally provided by the Printer using the canvas to render document pages. When the property contains 0 (zero) and the Printer is assigned, its PaperRect property is examined to get the Top of the printable area for the paper size. Otherwise, the existing value in the property is used. +

+

+ Changes to the property value are not applied to the Printer device. +

+

+ Use BottomMargin for the unused area at the bottom edge of the canvas. Values in TopMargin, BottomMargin, and PaperHeight are used to calculate the PageHeight for the printer canvas. +

+ + + + + + + + + + + + - - - - LeftMarging - the size of the margin at the left of each page - - + + + The size of the margin at the left edge of the canvas + +

+ LeftMargin is an Integer property which contains the size for the area between the edge of the paper and the left edge of the content on the page. Margin values are expressed as the number of "Dots" for the native printer resolution (XDPI). To achieve a .5in margin on a 300DPI laser printer, use the value 150. +

+

+ The value for the property is normally provided by the Printer using the canvas to render document pages. When the property contains 0 (zero) and the Printer is assigned, its PaperRect property is examined to get the Left of the printable area for the paper size. Otherwise, the existing value in the property is used. +

+

+ Changes to the property value are not applied to the Printer device. +

+

+ Use RightMargin for the unused area at the right edge of the canvas. Values in LeftMargin, RightMargin, and PaperWidth are used to calculate the PageWidth for the printer canvas. +

+ + + + + + + + + + + + - + + + The size of the margin at the bottom edge of the canvas + +

+ BottomMargin is an Integer property which contains the size for the area between the edge of the paper and the bottom of the content on the page. Margin values are expressed as the number of "Dots" for the native printer resolution (YDPI). To achieve a .5in margin on a 300DPI laser printer, use the value 150. +

+

+ The value for the property is normally provided by the Printer using the canvas to render document pages. When the property contains 0 (zero) and the Printer is assigned, its PaperRect property is examined to get the Top of the printable area for the paper size. Otherwise, the existing value in the property is used. +

+

+ Changes to the property value are not applied to the Printer device. +

+

+ Use Topargin for the unused area at the top edge of the canvas. Values in TopMargin, BottomMargin, and PaperHeight are used to calculate the PageHeight for the printer canvas. +

+ + + + + + + + + + + + + + + + The size of the margin at the right edge of the canvas + +

+ RightMargin is an Integer property which contains the size for the area between the edge of the paper and the right edge of the content on the page. Margin values are expressed as the number of "Dots" for the native printer resolution (XDPI). To achieve a .5in margin on a 300DPI laser printer, use the value 150. +

+

+ The value for the property is normally provided by the Printer using the canvas to render document pages. When the property contains 0 (zero) and the Printer is assigned, its PaperRect property is examined to get the Left of the printable area for the paper size. Otherwise, the existing value in the property is used. +

+

+ Changes to the property value are not applied to the Printer device. +

+

+ Use LeftMargin for the unused area at the left edge of the canvas. Values in LeftMargin, RightMargin, and PaperWidth are used to calculate the PageWidth for the printer canvas. +

+ + + + + + + + + + + + + + + + Orientation of the page on the selected paper + +

+ Orientation is a TPrinterOrientation property which indicates the orientation for the content on a page (canvas). For example: +

+
+
poPortrait
+
Long edge of the canvas is oriented to the vertical axis.
+
poReversePortrait
+
Long edge of the canvas is oriented to the vertical axis with coordinates rotated 180 degrees. This is often referred to as "Mirror Printing".
+
poLandscape
+
Long edge of the canvas is oriented to the horizontal axis.
+
poReverseLandscape
+
Long edge of the canvas is oriented to the horizontal axis with coordinates rotated 180 degrees. This is often referred to as "Mirror Printing".
+
+

+ The value for the property is supplied by the Printer using the canvas to render document pages (when assigned). If Printer has not been assigned, an existing value in the property is used. +

+

+ If the value for the property is changed, it is applied to the Printer device (when assigned). +

+ + + + + + + + + DPI (Dots per Inch) in the horizontal direction for the print device + +

+ XDPI is an Integer property which indicates the DPI (Dots per Inch) resolution for the horizontal axis on the print device. +

+

+ The value for the property is normally provided by the Printer device using the canvas to render document pages. When Printer is assigned, the XDPI value in the print device is used as the property value. If Printer is not assigned, the existing value in the property is used. When the existing value is 0 (zero) or a negative number, the value 300 is assumed. +

+

+ A new value assigned to the property is not applied to the Printer device. +

+

+ XDPI is used to calculate the default value for the PaperWidth property. +

+

+ Use YDPI for the resolution of the print device along the vertical axis. +

+ + + + + + + + + + + + DPI (Dots per Inch) in the vertical direction for the print device + +

+ YDPI is an Integer property which indicates the DPI (Dots per Inch) resolution for the vertical axis on the print device. +

+

+ The value for the property is normally provided by the Printer device using the canvas to render document pages. When Printer is assigned, the YDPI value in the print device is used as the property value. If Printer is not assigned, the existing value in the property is used. When the existing value is 0 (zero) or a negative number, the value 300 is assumed. +

+

+ A new value assigned to the property is not applied to the Printer device. +

+

+ YDPI is used to calculate the default value for the PaperHeight property. +

+

+ Use XDPI for the resolution of the print device along the horizontal axis. +

+ + + + + + + + + + TPrinterCanvasRef - class of TPrinterCanvas: referenced class - - - - TPaperRect - a record holding details of physical and working dimensions for paper - - - - - - - - - - - - - - - - - - - TPaperSize - the size of the paper to be used for the current document with the current printer + + + Defines a printer canvas with an associated file for its output

- TPaperSize - the size of paper to be used for the current document with the current printer

-

The width and length are in points; there are 72 points per inch.

+ TFilePrinterCanvas is a TPrinterCanvas descendant which defines a printer canvas with an associated file name for its output. +

+

+ Please note, TFilePrinterCanvas does not perform any output to the specified file. It is used as a base class for descendants which use a page description language or other printer-related technologies, like: TPostscriptPrinterCanvas, TCairoPrinterCanvas, TCocoaPrinterCanvas, et. al. +

- - - - + + + + + File name where output for the printer canvas is stored - - - + + + Class reference used to create instances of the TFilePrinterCanvas class - - - + + + Holds the physical and working dimensions for a paper size + +

+ TPaperRect is a record type with members used to store the physical and working rectangles for a paper size. Coordinates values in the physical and working rectangles are expressed in Points (1/72 of an Inch). +

+

+ TPaperRect is the type used to implement PaperRect, PaperRectOf and GetDefaultPaperRect in TPaperSize. +

+ + + + + + + + + + Rectangle for the physical paper size - + + + Rectangle for the usable print area on the paper + + + + + + Represents a paper size definition used for print devices + + + + + + Common name for the paper size + +

+ Contains values like: "Letter", "Legal" or "A4". Limited to 40 characters maximum. +

+ + + + + + Contains boundaries for the physical paper size and its available working area + + + + + + Contains a custom paper size defined in TPaperSize + + + + + + True when a TPaperItem instance is in the Item member + + + + + + Contains physical and work area rectangles for a custom paper size + + + + + + + Size for a paper used for the current document with the current printer + + +

+ TPaperSize represents the size of the paper used for the current document with the current printer. The width and length are represented in Points (72 points per inch). +

+

+

+ + + + + + + + - + Gets the value for the DefaultPaperName property - - + Value for the property - + + + Gets the value for the Height property + + + + + + + Value for the property + + - + Gets the value for the PaperName property - + + + - - + Value for the property - + - + Gets the value for the PaperRect property - - + + + - - + Value for the property - + + + Gets the value for the Width property + + + + + + + Value for the property + + - + Gets the value for the SupportedPapers property - - + + + - - + Value for the property - + - + Sets the value for the PaperName property - - + + + - - + New value for the property - + - - - + Provides indexed access to the rectangle for the specified paper name + +

+ PaperRectOfName is an indexed TPaperRect property which provides access to the rectangle for the specified paper name. aName contains the name for the requested paper. The property value contain rectangles with both the physical dimensions for the paper and the available work area for the page. +

+

+ If a custom paper size has been defined with the name in aName, its rectangle is used as the value for the property. Otherwise, the papers defined in the SupportedPapers property are search for the requested name. +

+

+ An EPrinter exception is raised when aName contains a value not located in SupportedPapers. An EPrinter exception is also raised when a rectangle cannot be determined for the specified name. +

+ + +

+ Raises an EPrinter exception with the message ''The paper "%s" has no defined rectangle!''. +

+

+ Raises an EPrinter exception with the message 'Paper "%s" is not supported!'. +

+ - - + TPaperRect value for the paper with the given name - - + + Paper name to locate in the SupportedPapers property or a custom Paper defined in the paper size + - - - + + + Ensures that a printer is selected and the default paper sizes are available - - + + + + + + + + + + Gets the rectangles for the specified default paper name + +

+ GetDefaultPaperRect is an Integer function used to get a TPaperRect with the dimensions for the default paper name specified in AName. The return value contains the ordinal position in the default paper sizes defined in the class, or -1 when a default paper size with the specified name could not be located. The rectangles for the requested paper name are returned in the APaperRect parameter. +

+

+ The Orientation for the printer device is used to determine if the rectangle bounds must be translated to the selected orientation. No actions are needed for poPortrait or poReversePortrait orientations. For poLandscape and poReverseLandscape orientations, the value in Left and Right become the values in Top and Bottom (respectively). The values in Top and Bottom become the values in Left and Right (respectively). +

+

+ GetDefaultPaperRect is called from the implementation of the PaperRectOfName method. +

+ + + + + Position for the requested paper name in the list of default papers + + + Name for the default paper size located in the method + + + Contains the physical and working areas for the paper + + + + Gets the ordinal position for a default paper size with the specified name + + + + + Ordinal position in the list of default papers for the specified paper name + + + Paper name to locate in the method + + + + Sets the value for the PaperRect property + + + + + + + New value for the property + + + + Constructor for the class instance + +

+ Create is the overloaded constructor for the class instance. +

+

+ AOwner is the TPrinter device which owns the class instance. It is used to get device capabilities such as DPI (Dots per Inch), and to calculate the page rectangle for the paper size. An exception is raised if AOwner has not been assigned (contains Nil). +

+

+ Create calls the inherited constructor. +

+

+ Create allocates resources and initializes internal members used in the class instance. +

+ + +
+
Exception
+
+ Raised with the message 'TMediaSize.Create, aOwner must be defined!' when AOwner has not been assigned. +
+
+ + + + + Exception message text does not match the actual name for the method. Refactoring oversight? + + + - + Owner of the class instance - - - + + + Destructor for the class instance + +

+ Destroy is the overridden destructor for the class instance. Destroy frees resources allocated to internal members in the class instance, and calls the inherited destructor. +

+ + + + + + + + Indicates if default paper sizes have been defined and added to SupportedPapers - - + + + Physical width for the selected paper size + + + + + + Physical height for the selected paper size + + + + PaperName - the name for the paper being used - + DefaultPaperName - the default name for this size of paper - + PaperRect - the rectangle dimensions for this paper - + SupportedPapers - the list of supported papers for this paper size - + PaperRectOf - the Paper Rect corresponding to the given name - - + + + Represents status flag values used for printer devices + + + + + Device is printing + + + Abort process + + + Printer object is being destroyed + + + Printer list is valid + + + Printer is in raw mode + + - TPrinter - class defining printer to be used in Lazarus applications - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - SelectCurrentPrinterOrDefault method for selecting either the current printer or the default - - - - - - - - GetCanvasRef - returns a reference to a printer canvas - - - - - - - - - - - - DoBeginDoc - method to begin printing the document - - - - - - - - DoNewPage - method for beginning a new page - - - - - - - - DoEndDoc - method for finishing printing document. aAborded is True if printing has been aborted (e.g. by operator) - - - - - - - - - - - - DoAbort - method for aborting the printing - - - - - - - - DoResetPrintersList - method for resetting the list of printers - - - - - - - - DoResetFontsList - method for resetting the list of fonts - - - - - - - - DoEnumPrinters - method for producing an enumerated list of printers - - - - - - - - - - - - DoEnumFonts - method for producing an enumerated list of fonts - - - - - - - - - - - - DoEnumPapers - method for producing an enumerated list of papers - - - - - - - - - - - - DoSetPrinter - returns integer corresponding to specified named printer - - - - - - - - - - - - - - - - DoGetCopies - returns the number of copies required - - - - - - - - - - - - DoSetCopies - specifies the number of copies required - - - - - - - - - - - - DoGetOrientation - returns the required orientation for printing (landscape of portrait) - - - - - - - - - - - - DoSetOrientation - specifies the orientation for printing (landscape or portrait) - - - - - - - - - - - - DoGetDefaultPaperName - returns the default name for the paper - - - - - - - - - - - - DoGetPaperName - returns the name of the current paper - - - - - - - - - - - - DoSetPaperName - specifies the name of the paper - - - - - - - - - - - - DoGetPaperRect - returns the dimensions of the rectangle for the named paper - - - - - - - - - - - - - - - - - - - - DoGetPrinterState - returns the printer state - - - - - - - - - - - - GetPrinterType - returns the printer type - - - - - - - - - - - - GetCanPrint - returns True if the printer is able to print - - - - - - - - - - - - - - - - - - - - - - - - - - Abort - terminate the current printing event (even if it hasn't finished) - - - - - - - - BeginDoc - start printing the currently selected document - - - - - - - - EndDoc - finish printing the current document - - - - - - - - NewPage - start printing on a new page - - - - - - - - Refresh the data for printing, e.g. after a change - - - - - - - - SetPrinter - specify use of the named printer - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - PrinterIndex - the printer's index in the list of printers - - - - - - - PaperSize - the size of paper to be used for the current document - - - - - - The Orientation - for printing the current document (landscape or portrait, normal or reversed) - - - - - - - PrinterState - ready, printing, stopped or undefined - - - - - - Number of Copies of the current document - - - - - - - Printers - the list of available printers for printing the current document - - - - - - the list of available Fonts for the current printer - - - - - - The Canvas to be used for laying out the current document ready for printing - - - - - - - PageHeight - for printing the current document with the defined PaperSize + TPrinter - class defining printer to be used in Lazarus applications - - - - - - The PageWidth for the current document with the defined PaperSize - - - - - - - - PageNumber - the number of the current page being printed - - - - - - - Aborted - True if printing of the document has been prematurely terminated by operator command - - - - - - - Printing - True if document is in process of being printed - - - - - - - Title - name for this printer - - - - - - - PrinterType - whether a local or network printer - - - - - - - CanPrint - True if printing is enabled or not disabled - - - - - - - - - - - - CanRenderCopies - True if the printer device can render copies - - CanRenderCopies - True if the printer device can render copies, i.e. if TPrinterCapability includes pcCopies - - - - - XDPI - number of dots per inch in X-direction - - - - YDPI - number of dots per inch in Y direction - - - - RawMode - true if printer operates in Raw Mode (as opposed to PostScript or some other page description language)

- RawMode - true if printer operates in Raw Mode (as opposed to PostScript or some other page description language)

-

If Raw Mode is being used, text is sent directly to the printer device without formatting, and the Canvas is not used for setting up the pages

+ TPrinter is a TObject descendant which defines an API for a printer device. +

+

+ TPrinter provides properties and methods used to select, configure, and control the printer device. Most of the methods are declared as virtual, and can be overridden in descendent classes which implement specific features like: page description languages, networking protocols, support for graphics libraries, etc. +

+

+ TPrinter uses a Canvas to position, format, and render output for the print device. A TPrinterCanvas class is provided which extends the familiar TCanvas class with features for printer-specific usage. The CanvasClass property allows the printer to create instances of TPrinterCanvas or descendent classes. +

+

+ TPrinter also provides a RawMode property which indicates that output does not use formatting or a page description language, and bypasses use of the Canvas class. Think of this as "Dot Matrix Mode". +

+

+ Properties are provided which allow the printer device to be configure its output resolution, paper selection, page margins, etc. Methods are provided to perform printer control when processing print jobs, documents, and pages. +

+

+ TPrinter is a base class. Do not create instances of TPrinter; an exception is raised when the ClassType for the class instance is TPrinter (and not one of its descendants). Use one of the descendants provided in the printer4lazarus package, like: TWinPrinter, TCarbonPrinter, TQtPrinters, TCUPSPrinter, et. al. +

+ - + + + + + + + + + + + + + + + Gets the value for the Aborted property + + + + + Value for the property + + + + Gets the value for the Canvas property + + + + + Value for the property + + + + Ensures that the Printing property contains the specified value + + + + + + Value required for the property + + + + Gets the value for the CanvasClass property + + + + + Value for the property + + + + Gets the value for the Copies property + + + + + Value for the property + + + + Gets the value for the Fonts property + + + + + Value for the property + + + + Gets the value for the Orientation property + + + + + Value for the property + + + + Gets the value for the PageHeight property + + + + + Value for the property + + + + Gets the value for the PageWidth property + + + + + Value for the property + + + + Gets the value for the PaperSize property + + + + + + Value for the property + + + + Gets the value for the BinName property + + + + + Value for the property + + + + Gets the value for the DefaultBinName property + + + + + Value for the property + + + + Gets the value for the PrinterIndex property + + + + + Value for the property + + + + Gets the value for the PrinterName property + + + + + Value for the property + + + + Gets the value for the Printers property + + + + + Value for the property + + + + Gets the value for the Printing property + + + + + Value for the property + + + + Gets the value for the RawMode property + + + + + Value for the property + + + + Sets the value for the CanvasClass property + + + + + New value for the property + + + + Sets the value for the Copies property + + + + + New value for the property + + + + Sets the value for the Orientation property + + + + + New value for the property + + + + Sets the value for the PrinterIndex + + + + + New value for the property + + + + Sets the value for the RawMode property + + + + + New value for the property + + + + Sets the value for the BinName property + + + + + New value for the property + + + - GetLeftMargin - returns the size of the left margin + Selects the default printer when a printer has not been selected + + +

+ SelectCurrentPrinterOrDefault ensures that a valid print device is selected. The default printer (the first device in Printers) is used when PrinterIndex has not been assigned and the number of devices in Printers is not 0 + (zero). +

+

+ SelectCurrentPrinterOrDefault is called from the implementation of the BeginDoc method, and when the list in Printers is loaded in the GetPrinters method. It is also called when the paper size for a print device is validated in the TPaperSize.CheckSupportedPapers method. +

+ + - + + + Performs actions needed when printing is started for a document + +

+ DoBeginDoc is a virtual procedure which performs actions needed when printing is started for a document. DoBeginDoc is called from the BeginDoc method, and occurs after checking the printer status and updating values in PrinterFlags. When RawMode is False, the Canvas has already been refreshed and its BeginDoc method has been called. +

+ + Please note: In TPrinter, DoBeginDoc has an empty implementation. It must be overridden in a desendent class to perfom actions needed for the operating system / widgetset / printer-related technology used in the implementation. + + + + + + + + + + + + + + + Performs actions needed to start a new page for the print device + +

+ DoNewPage is a virtual procedure used to perform actions needed to start a new page for the print device. DoNewPage is called from the NewPage method when an overridden method has been provided in the class implementation. It occurs after checking the printer status and incrementing the value in PageNumber. +

+ + Please note: In TPrinter, DoNewPage has an empty implementation. It must be overridden in a desendent class to perfom actions needed for the operating system / widgetset / printer-related technology used in the implementation. + + + + + + + Performs actions needed to begin a page for the print device + +

+ DoBeginPage is a virtual procedure used to perform actions needed to begin a page for the selected print device. DoBeginPage is called from the BeginPage method, and occurs after checking the printer status and incrementing the PageNumber. +

+ + Please note: In TPrinter, DoBeginPage has an empty implementation. It must be overridden in a desendent class to perfom actions needed for the operating system / widgetset / printer-related technology used in the implementation. + + + + + + + + Performs actions needed to end the current page for the print device + +

+ DoEndPage is a virtual procedure used to perform actions needed to end the current page for the print device. DoEndPage is called from the EndPage method, and occurs after synchronizing the printer canvas when RawMode is False. +

+ + Please note: In TPrinter, DoEndPage has an empty implementation. It must be overridden in a desendent class to perfom actions needed for the operating system / widgetset / printer-related technology used in the implementation. + + + + + + + + + + + Performs actions need to end printing for the current document + +

+ DoEndDoc is a vitual method used to finishing printing the current document. aAborted is True if printing has been halted by calling the Abort method. +

+ + Please note: In TPrinter, DoEndDoc has an empty implementation. It must be overridden in a desendent class to perfom actions needed for the operating system / widgetset / printer-related technology used in the implementation. + + + + + + True if document printing was aborted rather than ended normally + + + - GetTopMargin - returns the size of the top margin + Performs actions needed to abort printing for the current document + + +

+ DoAbort is a virutal procedure used to perform actions needed to abort printing for the current document. DoAbort is called from the Abort method, and occurs after checking the printer status and before setting values in PrinterFlags. +

+ + Please note: In TPrinter, DoAbort has an empty implementation. It must be overridden in a desendent class to perfom actions needed for the operating system / widgetset / printer-related technology used in the implementation. + + + - + + - GetBottomMargin - returns the size of the bottom margin + Performs actions needed to reset the status for the list of Printers + + +

+ DoResetPrintersList is a virtual method which performs actions needed to reset the status for the list of available devices in the Printers property. DoResetPrintersList removes the value pfPrintersValid from the PrinterFlags property. +

+

+ DoResetPrintersList is called from the Refresh method, and occurs prior to clearing and re-populating values in the Printers property. It is also called from the DoDestroy method when the class instance is freed. +

+ + Please note: DoResetPrintersList can be overridden in a descendent class to perform actions needed for the operating system / widgetset / printer-related technology used in the implementation. + + + - + + - GetRightMargin - returns the size of the right margin - - - The size of the TopMargin + Performs actions needed to reset the list of Fonts for the selected printer + +

+ DoResetFontsList is a virtual method used to perform actions needed to reset the list of Fonts for the selected print device. DoResetFontsList clears any values stored in the Fonts property (when assigned). +

+

+ DoResetFontsList is called from the Refresh method, and from DoDestroy when the class instance is freed. +

+ + Please note: DoResetFontsList can be overridden in a descendent class to perform actions needed for the operating system / widgetset / printer-related technology used in the implementation. + + + - - The size of the LeftMargin + + + + Performs actions needed to populate the specified list with available printers + +

+ DoEnumPrinters is a virtual procedure used to performs actions needed to populate the list in Lst with the printers available in the class instance. DoEnumPrinters has an empty implementation in TPrinter. It must be overridden in a descendent class to perform the actions required for the implementation. +

+ + Please note: The method must ensure that the first printer (stored at position 0) in Lst is the "default" printer for the operating system / widgetset / printer-related technology. + +

+ DoEnumPrinters is called from the GetPrinters method, and passes the member for the Printers property as the list storage for the method. +

+ + + + + - - The size of the BottomMargin + + TStrings instance where names for defined printers are stored + + + + + Performs actions needed to get a list of fonts supported for a print device + +

+ DoEnumFonts is a virtual method used to perform actions needed to populate the specified list with font names supported for the selected print device. DoEnumFonts is called from the GetFonts method when the Fonts property is empty. +

+ + Please note: In TPrinter, DoEnumFonts has an empty implementation. It must be overridden in a descendent class to perform actions needed to get the list of font names using the facilities available for the operating system / widgetset / printer-related technology. + + + - - the size of the RightMargin - + + TStrings instance where the list of font names is stored + + + Performs actions needed to get the supported papers for the print device + +

+ DoEnumPapers has an empty implementation in TPrinter; it must be overridden in a descendent class to implement the functionality. +

+ + + + + + + + + TStrings instance with the list of paper supported for the print device + + + + Performs action needed to get the Paper Bins for the printer device + +

+ DoEnumBins has an empty implementation in TPrinter; it must be overridden in a descendent class to implement the functionality. +

+ + + + + + + + + TStrings instance with the Paper Bins for the printer + + - DoInitialization - method for performing initialization + Performs intializations after the list of Printers has been populated + + +

+ DoInitialization is a method used to initialize the class instance after the list of supported Printers has been retrieved. DoInitialization has an empty implementation in TPrinter, and must overridden in a descendent class to implement the functionality. +

+

+ DoInitialization is called from the GetPrinters method, and occurs only once when the PrinterFlags does NOT include the values pfPrintersValid and pfDestroying. When called, the DoEnumPrinters method has successfully completed and the default printer has been selected using the SelectCurrentPrinterOrDefault method. +

+ + + + + + + + + + + + + Performs actions needed to select the specified printer name + +

+ DoSetPrinter is a virtual Integer function used to perform actions needed to set the selected printer to the name specified in aName. The return value contains the ordinal position in Printers where the name is located, or -1 when the specified name was not found. +

+ + Please note: In TPrinter, DoSetPrinter always returns the value -1. It must be overridden in a descendent class to perform the actions needed for the operating system / widgetset / printer-related technology used in the implementation. + +

+ DoSetPrinter is called from the SetPrinter method. +

+ + + + + + + + + Ordinal position for the specified printer name, or -1 when not found + + + Printer name to use as the selected print device + + + + + Performs actions needed to get the number of copies currently set for the print device + + +

+ DoGetCopies is a virtual Integer function used to perform actions needed to get the number of copies currently set for the print device. DoGetCopies is called when the value for the Copies property is read. +

+ + Please note: In TPrinter, DoGetCopies always returns the value 1. It must be overridden in a descendent class to perform actions needed for the operating system / widgetset / printer-related technology used to implement the printer capability. + + + + + + + + + Number of copies currently in use + + + + Performs actions needed to set the number of copies for each printed page + +

+ DoSetCopies is a virtual procedure used to perform actions needed to set the number of copies for each page printed on the device. DoSetCopies is called when a new value is assigned to the Copies property. +

+ + Please note: In TPrinter, DoSetCopies has an empty implementation. It must be overridden in a descendent class to perform actions needed for the operating system / widgetset / printer-related technology used to implement the printer capability. + + + + + + + + + Number of copies to use for the print device + + + + + Performs actions needed to get the page orientation for the print device + + +

+ DoGetOrientation is a virtual TPrinterOrientation function used to perform actions needed to get the page orientation for the print device. DoGetOrientation is called when the value for the Orientation property is retrieved, and provides the value used in the property. +

+ + Please note: In TPrinter, DoGetOrientation always returns the value poPortrait. It must be overridden in a descendent class to perform the actions needed for the operating system / widgetset / printer-related technology used in the implementation. + + + + + + + + TPrinterOrientation value for the page orientation + + + + Sets the page orientation for a printer device + +

+ DoSetOrientation is a virtual procedure used to perform actions needed to set the page orientation for a print device. AValue is a value from the TPrinterOrientation enumeration applied to the print device. See TPrinterOrientation for more information about the enumeration values and their meanings. DoSetOrientation is called when a new value is assigned to the Orientation property. +

+ + Please note: In TPrinter, DoSetOrientation has an empty implementation. It must be overridden in a descendent class to perform actions needed for the operating system / widgetset / printer-related technology used in the implementation. + + + + + + + + + + Page orientation applied to the print device + + + + + Performs actions needed to get the name for the default paper on the print device + + +

+ DoGetDefaultPaperName is a virtual String function which performs action needed to get the name for the default paper on the selected print device. The return value contains the name for the default paper, such as: "Letter", "Legal", or "A4". DoGetDefaultPaperName is called when the value for the TPaperSize.DefaultPaperName property is read. +

+ + Please note: In TPrinter, DoGetDefaultPaperName always returns an empty string (''). It must be overridden in a descendent class to perform the actions needed for the operating system / widgetset / printer-related technology used in the implementation. + + + + + + + + + + Name for the default paper on the selected print device + + + + + Performs action needed to get the selected paper name for the current printer + + +

+ DoGetPaperName is a virtual String function which performs action needed to get the selected paper name for the current printer. DoGetPaperName is called when the value for the TPaperSize.PaperName property in the printer is read. +

+ + Please note: In TPrinter, DoGetPaperName always returns an empty string (''). It must be overridden in a descendent class to perform actions needed for the operating system / widgetset / printer-related technology used in the implementation. + + + + + + + + + + Name of the paper selected for the current printer + + + + + Performs actions needed to set the paper for the current printer to the specified name + + +

+ DoSetPaperName performs actions needed to set the paper for the current printer to the specified name. DoSetPaperName is called when the paper name is assigned to the PaperName property in PaperSize. +

+ + Please note: In TPrinter, DoSetPaperName has an empty implementation. It must be overridden in a descendent class to perform actions needed for the operating system / widgetset / printer-related technology used in the implementation. + + + + + + Paper name selected for the printer + + + + Performs actions needed to get the name for the default bin on the selected printer + + + Please note: In TPrinter, DoGetDefaultBinName always returns an empty string(''). It must be overridden in a descendent class to perform actions needed for the operating system / widgetset / printer-related technology used in the implementation. + + + + + + Name for the default paper bin on the current printer + + + + Performs actions needed to get the current paper bin selected for the print device + + + Please note: In TPrinter, DoGetBinName always returns an empty string(''). It must be overridden in a descendent class to perform actions needed for the operating system / widgetset / printer-related technology used in the implementation. + + + + + + Name for the paper bin selected on the current printer + + + + Performs actions needed to set the selected paper bin for the current printer + + + Please note: In TPrinter, DoSetBinName has an empty implementation. It must be overridden in a descendent class to perform actions needed for the operating system / widgetset / printer-related technology used in the implementation. + + + + ??? Includes DebugLn output. + + + Name for the paper bin selected in the method + + + + + Performs actions needed to get the dimensions (rectangle) for the specified paper + + +

+ DoGetPaperRect is an Integer function used to get the dimensions (or rectangle) for the specified paper name. The return value indicates whether the rectangle represents the margins or the actual work area for the specified paper name. +

+
+
0
+
aPaperRc is the margins for the specified paper name.
+
1
+
aPaperRc is the physical dimensions for the work area in the paper.
+
-1
+
A paper with the specified name was not found, or its dimension are not known.
+
+ + Please note: In TPrinter, DoGetPaperRect always returns -1. It must be overridden in a descendant class to use the facilities for the printer type to get page areas. + + + + + + + + 0 for margins, 1 for physical paper, -1 when not found + + + Paper name to locate for the selected printer + + + Rectangle with the dimensions for the paper + + + + Performs actions needed to set the dimensions for the paper + + + Please note: In TPrinter, DoSetPaperRect always returns False. It must be overridden in a descendent class to perform actions needed for the operating system / widgetset / printer-related technology used in the implementation. + + + + + + True if the dimension for the paper were successfully applied + + + Rectangle with the physical dimensions for the paper + + + + Gets the value for the PrinterState property + +

+ DoGetPrinterState returns the printer state. DoGetPrinterState is declared as a virtual method so that it may be overridden in a descendent class to perform the actions needed to determine the printer state for the implementation. +

+ + Please note: In TPrinter, DoGetPrinterState always returns the value psNoDefine. It must be overridden in a descendent class to perform actions needed for the operating system / widgetset / printer-related technology used in the implementation. + + + + + + + + Value for the property + + + + Performs actions needed when the print device is freed + +

+ DoDestroy is a virtual procedure used to perform actions needed when the print device is freed. In TPrinter, the following actions are performed: +

+
    +
  • When Printing is True, Abort is called.
    • +
  • Frees resources allocated to the internal member used for Paper Bins.
    • +
  • Frees the Canvas (when assigned).
    • +
  • Frees PaperSize (when assigned).
    • +
  • Resets and frees the list of Printers (when assigned).
    • +
  • Resets and frees Fonts (when assigned).
    • +
+

+ DoDestroy is normally overridden in a descendent class to perform additional actions required for the implementation. +

+

+ DoDestroy is called from the Destroy destructor. +

+ + + + + + + + Gets the value for the PrinterType property + + + + + + + Value for the property + + + + Gets the value for the CanPrint property + + + + + + + Value for the property + + - - GetCanRenderCopies - returns True if the printer is able to render copies + Gets the value for the CanRenderCopies property + + + + + + Value for the property + + - - GetXDPI - returns the number of Dots Per Inch in the X plane + Gets the value for the XDPI property + + + + + + Value for the property + + - - GetYDPI - returns the number of Dots Per Inch in the Y plane + Gets the value for the YDPI property + + + + + + Value for the property + + + + Gets the value for the SupportedBins property + + + + + + + Value for the property + + - - CheckRawMode - check whether the printer operates in Raw mode (as opposed to PostScript etc) + Ensures that RawMode contains the specified value + +

+ CheckRawMode is a procedure used to ensure that the RawMode property contains the specified Value. If RawMode does not have the requested value, an EPrinter exception is raised. Msg contains the message text for the exception. When Msg is not specified, or contains an empty strng (''), a default message is used: +

+
+
Value is True
+
Msg contains 'Printer is in Raw Mode'
+
Value is False
+
Msg contains 'Printer is not in Raw Mode'
+
+

+ CheckRawMode is called when getting the value for the Canvas property. +

+ + +

+ Raises an EPrinter exception when RawMode does not contain the required value. +

+ + + + + + + + + Value required in the RawMode property + + + Message text for an exception raised in the method + + - RawModeChanging - the raw mode is changing (e.g. PostScript is being invoked) + Performs actions needed when a new value is assigned to RawMode + + +

+ RawModeChanging is a virtual procedure used to perform actions needed when a new value is assigned for the RawMode property. RawModeChanging is called from the SetRawMode method, and occurs after checking the value in Printing and before changing values in PrinterFlags. It is useful when switching from RawMode (which does not require a printer Canvas) to using a page description language like Postscript (which requires a specialized printer Canvas). +

+ + Please note: In TPrinter, RawModeChanging has an empty implementation. It must be overridden in a desecendent class to perform actions needed for the operating system / widgetset / printer-related technology used in the implementation. + + + + + + + + + + + - PrinterSelected - method for dealing with a printer that has been selected + Performs actions needed when a new printer has been selected + + +

+ PrinterSelected is a virtual procedure used to perform actions needed when a new printer has been selected in the class instance. PrinterSelected is called from the SetPrinter method to signal that a printer has been successfully selected from the list of Printers, and that the value in PrinterIndex has been updated. +

+ + Please note: In TPrinter, PrinterSelected has an empty implementation. It must be overridden in a descendent class to perform actions needed for the operating system / widgetset / printer-related technology used in the implementation. + + + + + + + - + + + Performs actions to get the default class used for the Canvas property + + + + + Class reference used to create new instances of the Canvas for the print device + + + + Status flags currently enabled for the print device + +

+ PrinterFlags is a TPrinterFlags property which contains the flags currently enabled for a print device. Flag values are removed from PrinterFlags when they are disabled. +

+
+
pfDestroying
+
Set in Destroy.
+
pfAborted
+
+ Set in Aborted. Removed in BeginDoc, EndDoc. Provides the value for the Aborted property. +
+
pfPrinting
+
+ Set in BeginDoc. Removed in EndDoc. Provides the value for the Printing property. +
+
pfPrintersValid
+
Set in GetPrinters. Removed in DoResetPrintersList.
+
pfRawMode
+
+ Set or removed when the value for RawMode is changed. Provides the value for the RawMode property. +
+
+ + + ' + ' + ' + ' + ' + ' + ' + + + + + Constructor for the class instance + +

+ Create is the constructor for the class instance, and calls the inherited constructor on entry. +

+

+ Create sets the value in PrinterIndex to -1 which indicates that the default printer in Printers should be used. +

+

+ Create stores an unassigned value (Nil) in the Canvas, PaperSize, and Bins properties. The Title property is set to an empty String (''). +

+ + Please note: TPrinter is an abstract base class, and an exception is raised if an instance of the class is created. Use one of the descendant classes defined in the printer4lazarus package. + + + +

+ Raises an exception with the message 'TPrinter is an abstract base class.' when TPrinter is the ClassType for the new instance. +

+ + + + + + Destructor for the class instance + +

+ Destroy is the overridden destructor for the class instance. Destroy updates the status flags for the device to include the value pfDestroying. It calls the DoDestroy method to cancel an active print job and free resources allocated in the class instance. Destroy calls the inherited destructor prior to exit. +

+ + + + + - Write to a specified Buffer: Count contains the number of bytes for writing, Written contains the number that have been written. Returns True if successful + Terminates printing of the current document (when active) + + +

+ Abort is a procedure used to terminate printing of the current document (when active). Aborts calls CheckPrinting to ensure that Printing contains True. CheckPrinting raises an exception if Abort is called when BeginDoc has not been called. +

+

+ Abort calls the DoAbort method to perform any actions needed for the class implementation. +

+

+ Abort updates the PrinterFlags property to include the value pfAborted, and calls the EndDoc method to end printing for the current document. +

+ + + + + + + + + + + + + Starts printing for the current document + +

+ BeginDoc is a procedure used to start printing for the current document. BeginDoc calls CheckPrinting to ensure that the print device has not already started printing for the document. CheckPrinting raises an exception if the value in Printing is True. +

+

+ BeginDoc calls SelectCurrentPrinterOrDefault to ensure a valid printer is selected for the class instance. If the current selection is invalid, the "default" printer is selected. The default printer is the first one in Printers. +

+

+ BeginDoc updates PrinterFlags to include the value pfPrinting, and removes the value pfAborted (if present). The PageNumber property is set to 1 (one) for the newly started printing operation. +

+

+ BeginDoc uses the value in RawMode to determine if a printer canvas is in used for the class instance. When RawMode is False, a TPrinterCanvas instance exists in Canvas. Its Refresh method is called, and the BeginDoc method in the printer canvas is called to synchronize the canvas. The value in YDPI is assigned to the PPI (Pixels per Inch) setting for the canvas font. No actions are performed for the printer canvas when RawMode is True. +

+

+ BeginDoc calls the DoBeginDoc method to perform any actions specific to the current class implementation. BeginPage is called to increment the PageNumber for the print device. +

+

+ Use EndDoc to finish printing for the current document. +

+ + + + + + + + + + + + + + + + + + + Ends printing for the current document + +

+ EndDoc is a procedure used to end printing for the current document. EndDoc calls CheckPrinting to ensure that Printing contains True. An exception is raised in CheckPrinting if Printing contains False. +

+

+ EndDoc calls the EndPage method to synchronize the printer Canvas (when used) and to perform any actions required for the class implementation. The EndDoc method for the Canvas is called when RawMode is False. +

+

+ DoEndDoc is called using the value in Aborted as an argument, and allows any actions needed for the class implementation to be performed. +

+

+ EndDoc updates values in the PrinterFlags property to reflect the current printer and document state. The values pfPrinting and pfAborted are removed from PrinterFlags. +

+

+ The value in the PageNumber is reset to 0 (zero). +

+

+ Use BeginDoc to start printing a document. Use Abort to abandon printing the current document. +

+ + + + + + + + + + + + + + + + + + Creates a new page for the current document + +

+ NewPage is a procedure used to create a new page for the document currently printing on the selected device. +

+

+ NewPage checks the current class instance to see if it is a TPrinter descendant with an overriden DoNewPage method. If it has not been overridden, the following methods are called: +

+
    +
  • EndPage
    • +
  • BeginPage
    • +
+

+ When it has been overridden, the following actions are performed: +

+
    +
  • Call CheckPrinting to ensure that Printing is True.
    • +
  • Increment the value in PageNumber.
    • +
  • Call the NewPage method in Canvas when RawMode is False.
    • +
  • Call DoNewPage to execute the code for the class implementation.
    • +
+ + + + + + + + + + + + + Begins a page on the print device + +

+ BeginPage is a procedure used to perform action when a page is started on the print device. BeginPage calls CheckPrinting to ensure that Printing contains True. An exception is raised in CheckPrinting when Printing contains False. +

+

+ BeginPage increments the value in the PageNumber property. When RawMode is False, the BeginPage method in Canvas is called to synchronize the printer canvas. +

+

+ BeginPage calls the DoBeginPage method to perform any actions needed for the class implementation. +

+

+ BeginPage is called from the BeginDoc method, and from the NewPage method when DoNewPage has not been overridden. +

+ + + + + + Ends the current page for the document + +

+ EndPage is a procedure used to end the current page for the document. +

+

+ EndPage uses the value in RawMode to determine if a printer canvas is used. When RawMode is False, the EndPage method in Canvas is called to synchronize the printer canvas. +

+

+ EndPage calls the DoEndPage method to perform actions needed for the class implementation. +

+ + + + + + Refreshes the printer list, fonts, and current device selection + +

+ Refresh performs actions needed to update the list or printers or fonts when the SetPrinter method is used to change the selected printer, such as: +

+
    +
  • Raises an exception if the printer is currently Printing.
    • +
  • Clears and reloads values in the Printers property.
    • +
  • Clears and reloads values in the Fonts property.
    • +
  • Saves and restores the current printer selection when possible.
    • +
+

+ PrinterIndex is set to -1 if the previous printer cannot be re-selected after loading values in Printers. The selects the default printer when the previous selection becomes unavailable. +

+ + + + + + Makes the device with the specified name the current printer + +

+ aName contains the name of the printer to use as the active print device. It can contain a "wild-card" value '*' which selects the default printer (the first one in the list of available printers) as the active print device. +

+ + + + + Name of the print device selected in the method + + + + Restores the selected Bin for the device to the default value + + + + + + Writes the specified values to the print device + +

+ Write is an Boolean function used to write the specified values to the printer device. Overloaded variants of the method allow the values to be specified as an AnsiString data type or an untyped buffer. +

+

+ Buffer is the untyped buffer written in the method. +

+

+ Count indicates the number of bytes in Buffer to use in the write operation. +

+

+ Written contains the actual number of bytes handled in the write operation. +

+

+ S is the AnsiString value written in the method. +

+

+ The return value is True when the specified values are successfully written in the method. +

+ + Please note: Neither variant of the Write method actually performs any output in TPrinter. The return value is always False, and Written always contains the value 0 (zero). Write must be re-implemented in a descendent class to perform the actions needed for the implementation. + + + + + + True when the specified value are successfully written in the method + + + Untyped buffer written in the method + + + Number of bytes from the buffer written in the method + + + Number of bytes actually written in the method + + + AnsiString value written in the method + + + + + Contains the ordinal position in Printers for the selected print device + + +

+ PrinterIndex is an Integer property which contains the ordinal position in Printers for the selected print device. The default value for the property is -1, and indicates that a print device has not been selected and that the default printer should be used. (Nota bene: The default printer is the first one in the Printers property). +

+

+ Setting a new value in PrinterIndex causes the CheckPrinting method to be called to ensure that the value in Printing is False. An exception is raised in CheckPrinting when Printing is set to True. Set the value for the property prior to calling the BeginDoc method. +

+

+ An exception may also be raised for the following conditions: +

+
    +
  • PrinterIndex is set to a value &= 0 and the list of Printers is empty.
    • +
  • PrinterIndex is set to a value larger than the number of values in Printers.
    • +
+

+ The SetPrinter method is called to make the named device the selected print device. DoResetFontsList is called to reload the values in the Fonts property. +

+ + +
+
EPrinter
+
Raised with the message 'Printer is printing'.
+
Raised with the message 'No printers defined!'.
+
Raised with the message 'Printer index out of range!'.
+
+ + + + + + + + + + + + + + + Name for the selected print device + +

+ PrinterName is a read-only String property which contains the name for the currently selected print device. The property value is retrieved from Printers using the value in PrinterIndex. When PrinterIndex contains a negative value, an empty string ('') is returned as the value for the property. +

+

+ Use SetPrinter to select a print device with a given name in Printers. Or, assign a new value to the PrinterIndex property. +

+ + + + + + + + + + Contains paper sizes available and/or selected for the print device + +

+ PaperSize is a read-only TPaperSize property which contains information about papers names and sizes available and/or selected for the print device. PaperSize is used to get a rectangle with the physical size of the paper, or its working area. The rectangle is used to calculate the vales for the PageHeight and PageWidth properties. +

+

+ PaperSize always contains common page sizes like "Letter", "Legal" and "A4". Other papers may be available depending on the printer selection or the implementation for the print device in a descendent class. +

+ + + + + + + + + + Orientation for the page on the paper + +

+ Orientation is a TPrinterOrientation property which indicates the orientation for the page content on its paper. For example: +

+
+
poPortrait
+
Long edge of the canvas is oriented to the vertical axis.
+
poReversePortrait
+
Long edge of the canvas is oriented to the vertical axis with coordinates rotated 180 degrees. This is often referred to as "Mirror Printing".
+
poLandscape
+
Long edge of the canvas is oriented to the horizontal axis.
+
poReverseLandscape
+
Long edge of the canvas is oriented to the horizontal axis with coordinates rotated 180 degrees. This is often referred to as "Mirror Printing".
+
+

+ For TPrinter, the property value is always poPortrait. The DoGetOrientation and DoSetOrientation methods are called when the property value is read/written. They are declared as virtual methods, and must be overridden in a descendent class to perform actions specific to the implementation. +

+

+ Orientation determines how the rectangle coordinate values in a paper size are interpreted. The paper size gives it coordinates in a portrait orientation. When one of the Landscape orientations is used, the values must be translated (or rotated) to reflection the page orientation. +

+ + + + + + + + + + Indicates the current state for the print device + +

+ PrinterState is a read-only TPrinterState property which contains a value with the current state for the print device. See TPrinterState for the enumeration values and their meanings. +

+

+ The read access specifier for the property is declared as a virtual method. It may be overridden in a descendent class to perform actions needed to determine the printer state for the implementation. +

+

+ In TPrinter, the value for the property is always psNoDefine. +

+ + + + + + + + + Number of Copies of the current document + +

+ Copies is an Integer property which indicates the number of times a page is duplicated during the printing process. Copies is one the TPrinterCapabilities which may be supported for a print device. +

+

+ In TPrinter, Copies always contains the value 1. The DoGetCopies and DoSetCopies methods are used to provide support for the printer capability. They are declared as virtual methods, and must be overridden in a descendent class to implement the feature. +

+ + + + + + Contains the names for devices that can be selected for printing + +

+ Printers is a read-only TStrings property which contains the names for print devices that can be selected in the class instance. By convention, the first print device in Printers is the "default" printer. +

+

+ Values in Printers are retrieved and stored using the DoEnumPrinters method. This method is called when the property value is retrieved and PrinterFlags does not include the pfPrintersValid flag. It is normally called only once - unless the Refresh or DoResetPrintersList methods are called. +

+

+ Printers is used in the SetPrinter method to validate the name for the selected printer device. Its Count property is used in other methods to ensure that valid printer devices exist in the class instance. +

+

+ Use SetPrinter to select a print device by its name. Use PrinterIndex to change the selected device to the printer at the specified ordinal position in Printers. +

+ + + + + + File name used to store output from the print device + +

+ FileName is a String property which contains the path and file name on the local file system where output from the print device is stored. +

+ + Please note: FileName is not used in the implementation of TPrinter. It is provided for use in descendent classes. + + + + + + + the list of available Fonts for the current printer + +

+ Fonts is a read-only TStrings property which contains a list of font names available for the selected print device. Values in Fonts are retrieved and stored using the DoEnumFonts method. It is called when the number of items in Fonts is 0, and when Refresh or DoResetFontsList is called. +

+ + Please note: DoEnumFonts has an empty implementation in TPrinter. It must be overridden in a descendant to implement the functionality for the operating system / widgetset / printer-related technology. + + + + + + + + The Canvas to be used for laying out the current document ready for printing + + +

+ Canvas is a read-only TCanvas property which provides properties and methods used to position and format content on a page. +

+

+ In TPrinter, and descendants, a printer-aware class derived from TCanvas is used: TPrinterCanvas. A descendent class may also introduce its own canvas class with specific features for the page description language, or printer-related technology used in its implementation. The CanvasClass property identifies the class reference used to create the member for the Canvas property. +

+

+ Canvas is used in methods like BeginDoc, EndDoc, BeginPage, and EndPage to synchronized the rendering surface to the current state for the print device. Canvas is used only when RawMode is set to False. +

+ + + + + + Class reference used to create new instances of the printer canvas + +

+ CanvasClass is a TPrinterCanvasRef property which contains the class reference used to create new instances of the class for the Canvas property. In TPrinter, the TPrinterCanvas class is used for the Canvas property. In a descendent class, a different printer canvas may be needed. CanvasClass allows the descendant to determine the correct class type in its DoGetDefaultCanvasClass method. The property value is always returns Nil when RawMode is set to True. +

+

+ CanvasClass is used in the read access specifier for the Canvas property to create a new instance of the class reference and assign it to the Canvas member (when needed). +

+ + + + + + + + + + + Height of the usable area on the selected paper size in "Dots" + +

+ PageHeight is a read-only Integer property which contains the usable height for the selected paper size as a number of "Dots" for the native printer resolution. +

+

+ PageHeight uses the PaperSize property to retrieve the work area for the selected paper size. The property value contains the difference between the Bottom and Top coordinates in the work area rectangle. +

+

+ The property value is 0 (zero) when the Printers property is empty. You cannot access a selected paper size without a selected printer. +

+

+ PageHeight is used to derive the page height in TPrinterCanvas when a TPrinter instance has been assigned. +

+ + + + + + + + + + + + + + Width of the usable area on the selected paper size in "Dots" + +

+ PageWidth is a read-only Integer property which contains the usable width for the selected paper size as a number of "Dots" for the native printer resolution. +

+

+ PageWidth uses the PaperSize property to retrieve the work area for the selected paper size. The property value contains the difference between the Right and Left coordinates in the work area rectangle. +

+

+ The property value is 0 (zero) when the Printers property is empty. You cannot access a selected paper size without a selected printer. +

+

+ PageWidth is used to derive the page width in TPrinterCanvas when a TPrinter instance has been assigned. +

+ + + + + + + + + + + + + + Current page number in the document being printed to the device + +

+ PageNumber is a read-only Integer property which contains the current page number in the document being printed to the device. The value in the property is maintained in methods which process the document or its pages, like: BeginDoc, EndDoc, NewPage and BeginPage. +

+ + + + + + + + + + + + + Aborted - True if printing of the document has been prematurely terminated by operator command + + +

+ Aborted is a read-only Boolean property which indicates if the current print job has been terminated. The value for the property is determined by examining the values in the PrinterFlags property. When PrinterFlags includes the value pfAborted, the property value is True. +

+

+ The status value is included in PrinterFlags when the Abort method is called. It is removed from PrinterFlags when the BeginDoc method is called. +

+ + + + + + + + + + + + Printing - True if document is in process of being printed + + +

+ Printing is a read-only Boolean property which indicates if the device is currently printing a document. The value for the property is determined by examining the PrinterFlags for the device. When PrinterFlags includes the value pfPrinting, the property value is True. +

+

+ The status value is included in PrinterFlags when the BeginDoc method is called, and removed from PrinterFlags when the EndDoc method is called. +

+

+ Use Abort to halt the current printing process. +

+ + + + + + + + + + + + Title of the current document for the print device + +

+ Title is a String property which contains the title of the current document for the print device. The default value assigned in the constructor is an empty string (''). +

+

+ Set the value in Title prior to calling the BeginDoc method. It may also be assigned using the Title property in the Canvas (TPrinterCanvas) for the print device. In this case, the value is applied to the print device as well. +

+ + + + + + + + Indicates whether the print device is a local or a network printer + +

+ PrinterType is a TPrinterType property which indicates whether the print device is locally attached, or network enabled. In TPrinter, the value for the property is always ptLocal. A descendent class (like TCUPSPrinter) may return another value from the TPrinterType enumeration. +

+ + + + + + + + + CanPrint - True if printing is enabled or not disabled + + +

+ CanPrint is a read-only Boolean property which indicates if the print device is enabled and ready to print. +

+ + Please note: In TPrinter, the property value is always True. The read access specifier (GetCanPrint) can be overridden in a descendnet class to use the facilities for the operating system / widgetset / printer-related technology in the implementation. + + + + + + + + + + CanRenderCopies - True if the printer device can render copies + + +

+ CanRenderCopies is a read-only Boolean property which indicates if the print device can print more than one copy of pages in the document. The property value is True when the print device includes the pcCopies printer capability. +

+ + Please note: In TPrinter, the property value is always True. The read access speciifer (GetCanRenderCopies) can be overridden in a descendent class to use the facilities in the operating system / widgetset / printer-related technology in the implementation. + + + + + + + + + + + Number of DPI (Dots per Inch) on the horizontal axis for the selected device + + +

+ XDPI is a read-only Integer property that contains the horizontal resolution for the print device in DPI (Dots per Inch). The value in XDPI is passed to the Canvas for the print device, and used to determine the paper width for the printer canvas. +

+ + Please note: In TPrinter, the value for the property is always 1. The read access specifier (GetXDPI) must be overridden in a descendent class to get the property value using the facilities available in the operating system / widgetset / printer-related technology for the implementation. + + + + + + + + + + + + + Number of DPI (Dots per Inch) on the vertical axis for the selected device + + +

+ YDPI is a read-only Integer property that contains the vertical resolution for the print device in DPI (Dots per Inch). The value in YDPI is passed to the Canvas for the print device, and used to determine the paper width for the printer canvas and the PPI (Pixels per Inch) value for its Font. +

+ + Please note: In TPrinter, the value for the property is always 1. The read access specifier (GetYDPI) must be overridden in a descendent class to get the property value using the facilities available in the operating system / widgetset / printer-related technology for the implementation. + + + + + + + + + + + + + + Indicates if raw output is used for the device (as opposed to a page description language) + + +

+ Set RawMode to True if the printer operates in Raw Mode (as opposed to PostScript or some other page description language). +

+

+ When RawMode is True, text is sent directly to the printer device without formatting and the Canvas is not used to layout or position content on the page. +

+ + + + + Name for the default Paper Bin on the print device + +

+ DefaultBinName is a read-only String property which contains the name for the defauilt Paper Bin on the selected print device. The value for the property is retrieved using the DoGetDefaultBinName method. +

+

+ DefaultBinName is used in the implementation of the RestoreDefaultBin method. +

+

+ Use BinName to read or write the value for the selected paper bin on the print device. +

+ + Please note: The property value is always an empty string ('') in TPrinter. The DoGetDefaultBinName method must be overridden in a descendent class to provide a property value using the facilities available in the operating system / widgetset / printer-related technology. + + + + + + + + + + + Name of the Paper Bin currently selected for the print device + +

+ BinName is a String property with the name for the Paper Bin selected for the print device. BinName contains one of the values found in the SupportedBins property. +

+

+ The value for the property is retrieved using the DoGetBinName method. Setting a new value for the property requires Printing to be set to False; an exception is raised in CheckPrinting when Printing contains True. The property value is applied using the DoSetBinName method. +

+ + + + + + + + + + + + Names for the Paper Bins supported on the print device + +

+ SupportedBins is a read-only TStrings property which contains the names for the Paper Bins supported on the selected print device. The value for the property is retrieved in the GetBins method by calling DoEnumBins. +

+

+ Assign a value from SupportedBins to the BinName property to select a specific paper bin. +

+ + + + + + + + + + Provides access to a TPrinter instance + +

+ Printer is a TPrinter variable which can be used to store a unit global printer instance. The value in Printer may contain a derived class instance which implements a specific page description language or printer-related technologies like CUPS. Its value may be assigned in classes which have a specific implementation for a printer device. The value in Printer is freed (when assigned) during finalization of the unit. +

+

+ Additional printer types and OS-specific implementations are available in the components/printers/ directory in the printer4lazarus package. +

+ + + +