lazarus/docs/xml/lcl/printers.xml

<?xml version="1.0" encoding="UTF-8"?>
<fpdoc-descriptions>
<package name="lcl">
<!--
====================================================================
Printers
====================================================================
-->
<module name="Printers">
<short>Defines printer output devices for Lazarus applications.</short>
<descr>
<p>
<file>Printers.pas</file> implements basic facilities needed for the 
<var>TPrinter</var> print device. A <var>TPrinterCanvas</var> class is 
included to position, format, and render pages for the print device.
</p>
<p>
<file>Printers.pas</file> is a required unit for use with the 
<file>printer4lazarus</file> package. See the Lazarus Wiki for more 
information about the <file>printer4lazarus</file> package:
</p>
<dl>
<dt>Printing</dt>
<dd>
<url href="https://wiki.lazarus.freepascal.org/Printing">
https://wiki.lazarus.freepascal.org/Printing
</url>
</dd>
<dt>Using the Printer</dt>
<dd>
<url href="https://wiki.lazarus.freepascal.org/Using_the_printer">
https://wiki.lazarus.freepascal.org/Using_the_printer
</url>
</dd>
</dl>
</descr>

<!-- unresolved type reference Visibility: default -->
<element name="Classes"/>
<element name="SysUtils"/>
<element name="LazLoggerBase"/>
<element name="LazUTF8"/>
<element name="LCLProc"/>
<element name="Graphics"/>

<element name="EPrinter">
<short>Exception raised for errors in TPrinter methods.</short>
<descr/>
<seealso>
<link id="TPrinter"/>
</seealso>
</element>

<element name="TPrinterOrientation">
<short>Represents page orientations for printers.</short>
<descr>
<p>
<var>TPrinterOrientation</var> is an enumerated type with values that 
represent page orientations used for print devices and their canvases. 
TPrinterOrientation is the type used to implement 
<var>TPrinter.Orientation</var> and <var>TPrinterCanvas.Orientation</var> 
properties.
</p>
</descr>
<seealso>
<link id="TPrinter.Orientation"/>
<link id="TPrinterCanvas.Orientation"/>
</seealso>
</element>
<element name="TPrinterOrientation.poPortrait">
<short>Output uses Portrait orientation.</short>
</element>
<element name="TPrinterOrientation.poLandscape">
<short>Output uses Landscape orientation.</short>
</element>
<element name="TPrinterOrientation.poReverseLandscape">
<short>
Output uses Landscape orientation with coordinates rotated 180 degrees.
</short>
</element>
<element name="TPrinterOrientation.poReversePortrait">
<short>
Output uses Portrait orientation with coordinates rotated 180 degrees.
</short>
</element>

<element name="TPrinterCapability">
<short>Represents capabilities for print devices.</short>
<descr>
<p>
Not implemented in the current LCL version.
</p>
</descr>
<seealso/>
</element>
<element name="TPrinterCapability.pcCopies">
<short>Devices supports copy mode.</short>
</element>
<element name="TPrinterCapability.pcOrientation">
<short>Device supports page orientations.</short>
</element>
<element name="TPrinterCapability.pcCollation">
<short>Device supports custom collation for printed pages.</short>
</element>

<element name="TPrinterCapabilities">
<short>Stores a set of capability values for a print device.</short>
<descr>
<p>
Not implemented in the current LCL version.
</p>
</descr>
<seealso/>
</element>

<element name="TPrinterState">
<short>Represents state values for a print device.</short>
<descr/>
<seealso/>
</element>
<element name="TPrinterState.psNoDefine">
<short>State is not defined or unknown.</short>
</element>
<element name="TPrinterState.psReady">
<short>Device is ready.</short>
</element>
<element name="TPrinterState.psPrinting">
<short>Device is printing.</short>
</element>
<element name="TPrinterState.psStopped">
<short>Device has been stopped.</short>
</element>

<element name="TPrinterType">
<short>Represents connection types for a print device.</short>
<descr/>
<seealso/>
</element>
<element name="TPrinterType.ptLocal">
<short>Device is attached to the local computer system.</short>
</element>
<element name="TPrinterType.ptNetWork">
<short>Device is a network-enabled printer.</short>
</element>

<element name="TPrinterCanvas">
<short>Implements a canvas used for TPrinter device output.</short>
<descr>
<p>
<var>TPrinterCanvas</var> is a <var>TCanvas</var> 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 
<var>Printer</var> property.
</p>
<p>
TPrinterCanvas provides methods which mirror the operations performed in 
TPrinter, like: <var>BeginDoc</var>, <var>NewPage</var>, 
<var>BeginPage</var>, <var>EndPage</var> and <var>EndDoc</var>. Methods in 
the canvas are called from the corresponding methods in TPrinter when its 
RawMode property is set to <b>False</b>.
</p>
<p>
A TPrinterCanvas (or descendant) class reference is used to implement the 
<var>TPrinter.CanvasClass</var> property.
</p>
</descr>
<seealso>
<link id="TFilePrinterCanvas"/>
<link id="TPrinter"/>
<link id="TPrinter.CanvasClass"/>
</seealso>
</element>

<element name="TPrinterCanvas.fPrinter"/>
<element name="TPrinterCanvas.fTitle"/>
<element name="TPrinterCanvas.fPageNum"/>
<element name="TPrinterCanvas.fTopMargin"/>
<element name="TPrinterCanvas.fLeftMargin"/>
<element name="TPrinterCanvas.fBottomMargin"/>
<element name="TPrinterCanvas.fRightMargin"/>
<element name="TPrinterCanvas.fPaperWidth"/>
<element name="TPrinterCanvas.fPaperHeight"/>
<element name="TPrinterCanvas.fOrientation"/>
<element name="TPrinterCanvas.fXDPI"/>
<element name="TPrinterCanvas.fYDPI"/>

<element name="TPrinterCanvas.GetOrientation">
<short>Gets the value for the Orientation property.</short>
<descr/>
<seealso>
<link id="TPrinterCanvas.Orientation"/>
</seealso>
</element>
<element name="TPrinterCanvas.GetOrientation.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinterCanvas.GetPageHeight">
<short>Gets the value for the PageHeight property.</short>
<descr/>
<seealso>
<link id="TPrinterCanvas.PageHeight"/>
</seealso>
</element>
<element name="TPrinterCanvas.GetPageHeight.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinterCanvas.GetPageWidth">
<short>Gets the value for the PageWidth property.</short>
<descr/>
<seealso>
<link id="TPrinterCanvas.PageWidth"/>
</seealso>
</element>
<element name="TPrinterCanvas.GetPageWidth.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinterCanvas.GetPaperHeight">
<short>Gets the value for the PaperHeight property.</short>
<descr/>
<seealso>
<link id="TPrinterCanvas.PaperHeight"/>
</seealso>
</element>
<element name="TPrinterCanvas.GetPaperHeight.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinterCanvas.GetPaperWidth">
<short>Gets the value for the PaperWidth property.</short>
<descr/>
<seealso>
<link id="TPrinterCanvas.PaperWidth"/>
</seealso>
</element>
<element name="TPrinterCanvas.GetPaperWidth.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinterCanvas.GetTitle">
<short>Gets the value for the Title property.</short>
<descr/>
<errors/>
<seealso>
<link id="TPrinterCanvas.Title"/>
</seealso>
</element>
<element name="TPrinterCanvas.GetTitle.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinterCanvas.GetXDPI">
<short>Gets the value for the XDPI property.</short>
<descr/>
<seealso>
<link id="TPrinterCanvas.XDPI"/>
</seealso>
</element>
<element name="TPrinterCanvas.GetXDPI.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinterCanvas.GetYDPI">
<short>Gets the value for the YDPI property.</short>
<descr/>
<seealso>
<link id="TPrinterCanvas.YDPI"/>
</seealso>
</element>
<element name="TPrinterCanvas.GetYDPI.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinterCanvas.SetOrientation">
<short>Sets the value for the Orientation property.</short>
<descr/>
<seealso>
<link id="TPrinterCanvas.Orientation"/>
</seealso>
</element>
<element name="TPrinterCanvas.SetOrientation.AValue">
<short>New value for the property.</short>
</element>

<element name="TPrinterCanvas.SetPaperHeight">
<short>Sets the value for the PaperHeight property.</short>
<descr/>
<seealso>
<link id="TPrinterCanvas.PaperHeight"/>
</seealso>
</element>
<element name="TPrinterCanvas.SetPaperHeight.AValue">
<short>New value for the property.</short>
</element>

<element name="TPrinterCanvas.SetPaperWidth">
<short>Sets the value for the PaperWidth property.</short>
<descr/>
<seealso>
<link id="TPrinterCanvas.PaperWidth"/>
</seealso>
</element>
<element name="TPrinterCanvas.SetPaperWidth.AValue">
<short>New value for the property.</short>
</element>

<element name="TPrinterCanvas.SetTitle">
<short>Sets the value for the Title property.</short>
<descr/>
<seealso>
<link id="TPrinterCanvas.Title"/>
</seealso>
</element>
<element name="TPrinterCanvas.SetTitle.AValue">
<short>New value for the property.</short>
</element>

<element name="TPrinterCanvas.HasDefaultMargins">
<short>Indicates if the default values are used for page margins.</short>
<descr>
<p>
<var>HasDefaultMargins</var> is a <var>Boolean</var> function used to 
determine if the default values are being used in the page margin properties: 
<var>LeftMargin</var>, <var>RightMargin</var>, <var>TopMargin</var>, 
<var>BottomMargin</var>. The return value is <b>True</b> when each of the 
properties contains the value <b>0</b> (<b>zero</b>).
</p>
<p>
HasDefaultMargins is used when getting the values for the 
<var>PageHeight</var> and <var>PageWidth</var> properties. When <b>False</b>, 
the page dimensions are adjusted to reserve space needed for the page margin 
properties.
</p>
</descr>
<seealso>
<link id="TPrinterCanvas.PageWidth"/>
<link id="TPrinterCanvas.PageHeight"/>
<link id="TPrinterCanvas.LeftMargin"/>
<link id="TPrinterCanvas.RightMargin"/>
<link id="TPrinterCanvas.TopMargin"/>
<link id="TPrinterCanvas.BottomMargin"/>
<link id="TPrinterCanvas.PaperHeight"/>
<link id="TPrinterCanvas.PaperWidth"/>
<link id="TPrinter.PageHeight"/>
<link id="TPrinter.PageWidth"/>
</seealso>
</element>
<element name="TPrinterCanvas.HasDefaultMargins.Result">
<short>
<b>True</b> when the default values (0) are used in the page margin 
properties.
</short>
</element>

<element name="TPrinterCanvas.SetXDPI">
<short>Sets the value for the XDPI property.</short>
<descr/>
<seealso>
<link id="TPrinterCanvas.XDPI"/>
</seealso>
</element>
<element name="TPrinterCanvas.SetXDPI.AValue">
<short>New value for the property.</short>
</element>

<element name="TPrinterCanvas.SetYDPI">
<short>Sets the value for the YDPI property.</short>
<descr/>
<seealso>
<link id="TPrinterCanvas.YDPI"/>
</seealso>
</element>
<element name="TPrinterCanvas.SetYDPI.AValue">
<short>New value for the property.</short>
</element>

<element name="TPrinterCanvas.GetLeftMargin">
<short>Gets the value for the LeftMargin property.</short>
<descr/>
<seealso>
<link id="TPrinterCanvas.LeftMargin"/>
<link id="TPrinterCanvas.Printer"/>
<link id="TPrinter.PaperSize"/>
</seealso>
</element>
<element name="TPrinterCanvas.GetLeftMargin.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinterCanvas.GetTopMargin">
<short>Gets the value for the TopMargin property.</short>
<descr/>
<seealso>
<link id="TPrinterCanvas.TopMargin"/>
</seealso>
</element>
<element name="TPrinterCanvas.GetTopMargin.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinterCanvas.GetBottomMargin">
<short>Gets the value for the BottomMargin property.</short>
<descr/>
<seealso>
<link id="TPrinterCanvas.BottomMargin"/>
</seealso>
</element>
<element name="TPrinterCanvas.GetBottomMargin.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinterCanvas.GetRightMargin">
<short>Gets the value for the RightMargin property.</short>
<descr/>
<seealso>
<link id="TPrinterCanvas.RightMargin"/>
</seealso>
</element>
<element name="TPrinterCanvas.GetRightMargin.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinterCanvas.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
<var>Create</var> is the constructor for the class instance, and calls the 
inherited constructor on entry. Create sets the value for the 
<var>Printer</var> property to the value in the <var>APrinter</var> parameter.
</p>
</descr>
<seealso>
<link id="TPrinterCanvas.Printer"/>
</seealso>
</element>
<element name="TPrinterCanvas.Create.APrinter">
<short>
Printer where the canvas class instance is used.
</short>
</element>

<element name="TPrinterCanvas.BeginDoc">
<short>Performs actions needed to start printing a document.</short>
<descr>
<p>
<var>BeginDoc</var> performs actions needed to start printing a document 
using the printer canvas. BeginDoc sets the value in the 
<var>PageNumber</var> property to <b>1</b>. The <var>NewPage</var> method is 
called when each subsequent page is started.
</p>
<p>
BeginDoc is called from the <var>TPrinter.BeginDoc</var> method when its 
<var>RawMode</var> property is set to <b>False</b>.
</p>
</descr>
<seealso>
<link id="TPrinterCanvas.PageNumber"/>
<link id="TPrinterCanvas.NewPage"/>
<link id="TPrinterCanvas.EndDoc"/>
</seealso>
</element>

<element name="TPrinterCanvas.NewPage">
<short>Performs actions needed when a new page is started.</short>
<descr>
<p>
<var>NewPage</var> is procedure used to perform actions needed when a new 
page is started. NewPage increments the value in the <var>PageNumber</var> 
property, and calls the <var>BeginPage</var> method prior to exit.
</p>
<p>
NewPage is called from the <var>TPrinter.NewPage</var> method.
</p>
</descr>
<seealso>
<link id="TPrinterCanvas.BeginPage"/>
<link id="TPrinterCanvas.EndPage"/>
<link id="TPrinterCanvas.PageNumber"/>
<link id="TPrinter.NewPage"/>
</seealso>
</element>

<element name="TPrinterCanvas.BeginPage">
<short>Performs actions needed when a page is started.</short>
<descr>
<p>
<var>BeginPage</var> is a procedure used to perform actions needed when a 
page is started for the canvas.
</p>
<p>
BeginPage is called from the TPrinter.BeginPage method.
</p>
</descr>
<seealso>
<link id="TPrinterCanvas.PageNumber"/>
<link id="TPrinterCanvas.NewPage"/>
<link id="TPrinter.BeginPage"/>
</seealso>
</element>

<element name="TPrinterCanvas.EndPage">
<short>Performs actions needed when a page is completed.</short>
<descr>
<p>EndPage has an empty implementation in TPrinterCanvas.</p>
<p>EndPage is called from the TPrinter.EndPage method.</p>
</descr>
<seealso>
<link id="TPrinter.EndPage"/>
</seealso>
</element>

<element name="TPrinterCanvas.EndDoc">
<short>Performs actions needed when a document has finished printing.</short>
<descr>
<p>
<var>EndDoc</var> is a procedure used to perform actions needed when a 
document has finished printing. EndDoc has an empty implementation in 
<var>TPrinterCanvas</var>.
</p>
<p>
EndDoc is called from both the <var>EndDoc</var> and the <var>Abort</var> 
methods in <var>TPrinter</var>.
</p>
</descr>
<seealso>
<link id="TPrinter.EndDoc"/>
<link id="TPrinter.Abort"/>
</seealso>
</element>

<element name="TPrinterCanvas.Changing">
<short>
Signals the OnChanging event when the printer status is changed.
</short>
<descr>
<p>
<var>Changing</var> is an overridden procedure used to signal the 
<var>OnChanging</var> event handler (when assigned) for the canvas. Changing 
is overridden to ensure that an assigned <var>Printer</var> in the class 
instance has the value <var>pfPrinting</var> in its internal Flags. This is 
done by calling the <var>CheckPrinting</var> method in <var>TPrinter</var>, 
which can raise an <var>EPrinter</var> exception if it does not have the 
expected value in its <var>Printing</var> property.
</p>
<p>
Changing calls the inherited method to signal the <var>OnChanging</var> event 
handler prior to exiting from the method.
</p>
</descr>
<seealso>
<link id="TPrinter.Printing"/>
<link id="EPrinter"/>
<link id="#lcl.graphics.TCanvas.Changing">TCanvas.Changing</link>
<link id="#lcl.graphics.TCanvas.OnChanging">TCanvas.OnChanging</link>
</seealso>
</element>

<element name="TPrinterCanvas.Printer">
<short>Device which uses the canvas to print a document.</short>
<descr>
<p>
<var>Printer</var> is a read-only <var>TPrinter</var> property which contains 
the printer device for the canvas. Printer is used to determine the 
capabilities selected/enabled for the output device, such as:
</p>
<dl>
<dt>Status</dt>
<dd>Ready, Printing, Stopped, et. al.</dd>
<dt>Paper Size</dt>
<dd>
Printable area is determined by the page dimensions and values in the margin 
properties.
</dd>
<dt>Resolution</dt>
<dd>Number of DPI (Dots per Inch) for the device.</dd>
</dl>
<p>
The value for the property is passed as an argument to the <var>Create</var> 
constructor.
</p>
</descr>
<seealso>
<link id="TPrinter"/>
<link id="TPrinterCanvas.Create"/>
</seealso>
</element>

<element name="TPrinterCanvas.Title">
<short>Title for the document rendered using the printer canvas.</short>
<descr>
<p>
<var>Title</var> is a <var>String</var> property which contains the title for 
the current document. The value for the property is read from the 
corresponding property in <var>Printer</var> (when available). Setting a new 
value for the property causes the Title property in the assigned Printer to 
be updated.
</p>
</descr>
<seealso>
<link id="TPrinterCanvas.Printer"/>
<link id="TPrinter.Title"/>
</seealso>
</element>

<element name="TPrinterCanvas.PageHeight">
<short>Size of the printable area for the page on the vertical axis.</short>
<descr>
<p>
<var>PageHeight</var> is a read-only <var>Integer</var> 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 <b>"Dots"</b> on the 
device in <var>Printer</var>.
</p>
<p>
When Printer has been assigned and <var>HasDefaultMargins</var> is 
<b>True</b>, the PageHeight property in the device is used. Otherwise, the 
property value is calculated by subtracting the values in 
<var>TopMargin</var> and <var>BottomMargin</var> from the 
<var>PaperHeight</var> for the printer <var>Canvas</var>.
</p>
<p>
Use <var>PageWidth</var> to get size of the printable page on the horizontal 
axis for the page orientation.
</p>
<p>
Use <var>PaperHeight</var> and <var>PaperWidth</var> to get the dimensions 
for the selected paper in Printer.
</p>
</descr>
<seealso>
<link id="TPrinterCanvas.TopMargin"/>
<link id="TPrinterCanvas.BottomMargin"/>
<link id="TPrinterCanvas.PaperHeight"/>
<link id="TPrinterCanvas.PageWidth"/>
<link id="TPrinterCanvas.Orientation"/>
<link id="TPrinterCanvas.YDPI"/>
<link id="TPrinterCanvas.XDPI"/>
<link id="TPrinter.PageHeight"/>
<link id="TPrinter.PageWidth"/>
</seealso>
</element>

<element name="TPrinterCanvas.PageWidth">
<short>Size of the printable area for the page on the horizontal axis.</short>
<descr>
<p>
<var>PageWidth</var> is a read-only <var>Integer</var> 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 <b>"Dots"</b> on the device in 
<var>Printer</var>.
</p>
<p>
When Printer has been assigned and <var>HasDefaultMargins</var> is 
<b>True</b>, the PageWidth property in the device is used. Otherwise, the 
property value is calculated by subtracting the values in 
<var>LeftMargin</var> and <var>RightMargin</var> from the 
<var>PaperWidth</var> for the printer <var>Canvas</var>.
</p>
<p>
Use <var>PageHeight</var> to get size of the printable page on the vertical 
axis for the page orientation.
</p>
<p>
Use <var>PaperHeight</var> and <var>PaperWidth</var> to get the dimensions 
for the selected paper in Printer.
</p>
</descr>
<seealso>
<link id="TPrinterCanvas.LeftMargin"/>
<link id="TPrinterCanvas.RightMargin"/>
<link id="TPrinterCanvas.PaperHeight"/>
<link id="TPrinterCanvas.PageWidth"/>
<link id="TPrinterCanvas.Orientation"/>
<link id="TPrinterCanvas.YDPI"/>
<link id="TPrinterCanvas.XDPI"/>
<link id="TPrinter.PageHeight"/>
<link id="TPrinter.PageWidth"/>
</seealso>
</element>

<element name="TPrinterCanvas.PaperWidth">
<short>Horizontal size for the paper selected in the print device.</short>
<descr>
<p>
<var>PaperWidth</var> is an <var>Integer</var> property which contains the 
width for the current paper as the number of <b>"Dots"</b> along its 
horizontal axis.
</p>
<p>
When <var>Printer</var> has been assigned, the <var>Width</var> in its 
<var>PaperSize</var> property is used as the property value. Otherwise, the 
existing property value is returned. If the existing value is <b>0</b> 
(<b>zero</b>), the width (in Dots) for the "A4" paper size (in portrait 
orientation) is used as the property value.
</p>
<p>
Use <var>PaperHeight</var> to get the height for the paper in Dots along its 
vertical axis.
</p>
</descr>
<seealso>
<link id="TPrinterCanvas.Printer"/>
<link id="TPrinterCanvas.PaperHeight"/>
<link id="TPrinter.PaperSize"/>
</seealso>
</element>

<element name="TPrinterCanvas.PaperHeight">
<short>Vertical size for the paper selected in the print device.</short>
<descr>
<p>
<var>PaperHeight</var> is an <var>Integer</var> property which contains the 
height for the current paper as the number of <b>"Dots"</b> along its 
vertical axis.
</p>
<p>
When <var>Printer</var> has been assigned, the <var>Height</var> in its 
<var>PaperSize</var> property is used as the property value. Otherwise, the 
existing property value is returned. If the existing value is <b>0</b> 
(<b>zero</b>), the height (in Dots) for the "A4" paper size (in portrait 
orientation) is used as the property value.
</p>
<p>
Use <var>PaperWidth</var> to get the width for the paper in Dots along its 
horizontal axis.
</p>
</descr>
<seealso>
<link id="TPrinterCanvas.Printer"/>
<link id="TPrinterCanvas.PaperWidth"/>
<link id="TPrinter.PaperSize"/>
</seealso>
</element>

<element name="TPrinterCanvas.PageNumber">
<short>The number for the current page in the printer canvas.</short>
<descr>
<p>
<var>PageNumber</var> is a read-only <var>Integer</var> 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 
<var>BeginPage</var> method is called for the printer canvas.
</p>
</descr>
<seealso>
<link id="TPrinterCanvas.NewPage"/>
<link id="TPrinterCanvas.BeginPage"/>
</seealso>
</element>

<element name="TPrinterCanvas.TopMargin">
<short>The size of the margin at the top of the canvas.</short>
<descr>
<p>
<var>TopMargin</var> is an <var>Integer</var> 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 (<var>YDPI</var>). To achieve a .5in margin on a 300DPI 
laser printer, use the value <b>150</b>.
</p>
<p>
The value for the property is normally provided by the <var>Printer</var> 
using the canvas to render document pages. When the property contains 
<b>0</b> (<b>zero</b>)  and the Printer is assigned, its <var>PaperRect</var> 
property is examined to get the <var>Top</var> of the printable area for the 
paper size. Otherwise, the existing value in the property is used.
</p>
<p>
Changes to the property value are not applied to the Printer device.
</p>
<p>
Use <var>BottomMargin</var> for the unused area at the bottom edge of the 
canvas. Values in TopMargin, BottomMargin, and <var>PaperHeight</var> are 
used to calculate the <var>PageHeight</var> for the printer canvas.
</p>
</descr>
<seealso>
<link id="TPrinterCanvas.Printer"/>
<link id="TPrinterCanvas.BottomMargin"/>
<link id="TPrinterCanvas.PaperHeight"/>
<link id="TPrinterCanvas.PageHeight"/>
<link id="TPrinterCanvas.YDPI"/>
<link id="TPrinter.YDPI"/>
<link id="TPaperRect"/>
</seealso>
</element>

<element name="TPrinterCanvas.LeftMargin">
<short>The size of the margin at the left edge of the canvas.</short>
<descr>
<p>
<var>LeftMargin</var> is an <var>Integer</var> 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 (<var>XDPI</var>). To achieve a .5in margin on 
a 300DPI laser printer, use the value <b>150</b>.
</p>
<p>
The value for the property is normally provided by the <var>Printer</var> 
using the canvas to render document pages. When the property contains 
<b>0</b> (<b>zero</b>)  and the Printer is assigned, its <var>PaperRect</var> 
property is examined to get the <var>Left</var> of the printable area for the 
paper size. Otherwise, the existing value in the property is used.
</p>
<p>
Changes to the property value are not applied to the Printer device.
</p>
<p>
Use <var>RightMargin</var> for the unused area at the right edge of the 
canvas. Values in LeftMargin, RightMargin, and <var>PaperWidth</var> are used 
to calculate the <var>PageWidth</var> for the printer canvas.
</p>
</descr>
<seealso>
<link id="TPrinterCanvas.Printer"/>
<link id="TPrinterCanvas.RightMargin"/>
<link id="TPrinterCanvas.PaperWidth"/>
<link id="TPrinterCanvas.PageWidth"/>
<link id="TPrinterCanvas.XDPI"/>
<link id="TPrinter.XDPI"/>
<link id="TPaperRect"/>
</seealso>
</element>

<element name="TPrinterCanvas.BottomMargin">
<short>The size of the margin at the bottom edge of the canvas.</short>
<descr>
<p>
<var>BottomMargin</var> is an <var>Integer</var> 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 (<var>YDPI</var>). To achieve a .5in margin on a 
300DPI laser printer, use the value <b>150</b>.
</p>
<p>
The value for the property is normally provided by the <var>Printer</var> 
using the canvas to render document pages. When the property contains 
<b>0</b> (<b>zero</b>)  and the Printer is assigned, its <var>PaperRect</var> 
property is examined to get the <var>Top</var> of the printable area for the 
paper size. Otherwise, the existing value in the property is used.
</p>
<p>
Changes to the property value are not applied to the Printer device.
</p>
<p>
Use <var>TopMargin</var> for the unused area at the top edge of the canvas. 
Values in TopMargin, BottomMargin, and <var>PaperHeight</var> are used to 
calculate the <var>PageHeight</var> for the printer canvas.
</p>
</descr>
<seealso>
<link id="TPrinterCanvas.Printer"/>
<link id="TPrinterCanvas.TopMargin"/>
<link id="TPrinterCanvas.PaperHeight"/>
<link id="TPrinterCanvas.PageHeight"/>
<link id="TPrinterCanvas.YDPI"/>
<link id="TPrinter.YDPI"/>
<link id="TPaperRect"/>
</seealso>
</element>

<element name="TPrinterCanvas.RightMargin">
<short>The size of the margin at the right edge of the canvas.</short>
<descr>
<p>
<var>RightMargin</var> is an <var>Integer</var> 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 (<var>XDPI</var>). To achieve a .5in margin on 
a 300DPI laser printer, use the value <b>150</b>.
</p>
<p>
The value for the property is normally provided by the <var>Printer</var> 
using the canvas to render document pages. When the property contains 
<b>0</b> (<b>zero</b>)  and the Printer is assigned, its <var>PaperRect</var> 
property is examined to get the <var>Left</var> of the printable area for the 
paper size. Otherwise, the existing value in the property is used.
</p>
<p>
Changes to the property value are not applied to the Printer device.
</p>
<p>
Use <var>LeftMargin</var> for the unused area at the left edge of the canvas. 
Values in LeftMargin, RightMargin, and <var>PaperWidth</var> are used to 
calculate the <var>PageWidth</var> for the printer canvas.
</p>
</descr>
<seealso>
<link id="TPrinterCanvas.Printer"/>
<link id="TPrinterCanvas.LeftMargin"/>
<link id="TPrinterCanvas.PaperWidth"/>
<link id="TPrinterCanvas.PageWidth"/>
<link id="TPrinterCanvas.XDPI"/>
<link id="TPrinter.XDPI"/>
<link id="TPaperRect"/>
</seealso>
</element>

<element name="TPrinterCanvas.Orientation">
<short>Orientation of the page on the selected paper.</short>
<descr>
<p>
<var>Orientation</var> is a <var>TPrinterOrientation</var> property which 
indicates the orientation for the content on a page (canvas). For example:
</p>
<dl>
<dt>poPortrait</dt>
<dd>Long edge of the canvas is oriented to the vertical axis.</dd>
<dt>poReversePortrait</dt>
<dd>
Long edge of the canvas is oriented to the vertical axis with coordinates 
rotated 180 degrees. This is often referred to as "Mirror Printing".
</dd>
<dt>poLandscape</dt>
<dd>Long edge of the canvas is oriented to the horizontal axis.</dd>
<dt>poReverseLandscape</dt>
<dd>
Long edge of the canvas is oriented to the horizontal axis with coordinates 
rotated 180 degrees. This is often referred to as "Mirror Printing".
</dd>
</dl>
<p>
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.
</p>
<p>
If the value for the property is changed, it is applied to the Printer device 
(when assigned).
</p>
</descr>
<seealso>
<link id="TPrinter.Orientation"/>
<link id="TPrinterOrientation"/>
</seealso>
</element>

<element name="TPrinterCanvas.XDPI">
<short>
DPI (Dots per Inch) in the horizontal direction for the print device.
</short>
<descr>
<p>
<var>XDPI</var> is an <var>Integer</var> property which indicates the DPI 
(Dots per Inch) resolution for the horizontal axis on the print device.
</p>
<p>
The value for the property is normally provided by the <var>Printer</var> 
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 <b>0</b> (<b>zero</b>) or a negative number, the value 
<b>300</b> is assumed.
</p>
<p>
A new value assigned to the property is not applied to the Printer device.
</p>
<p>
XDPI is used to calculate the default value for the <var>PaperWidth</var> 
property.
</p>
<p>
Use YDPI for the resolution of the print device along the vertical axis.
</p>
</descr>
<seealso>
<link id="TPrinterCanvas.Printer"/>
<link id="TPrinterCanvas.PaperWidth"/>
<link id="TPrinterCanvas.YDPI"/>
<link id="TPrinter.XDPI"/>
<link id="TPrinter.YDPI"/>
</seealso>
</element>

<element name="TPrinterCanvas.YDPI">
<short>
DPI (Dots per Inch) in the vertical direction for the print device.
</short>
<descr>
<p>
<var>YDPI</var> is an <var>Integer</var> property which indicates the DPI 
(Dots per Inch) resolution for the vertical axis on the print device.
</p>
<p>
The value for the property is normally provided by the <var>Printer</var> 
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 <b>0</b> (<b>zero</b>) or a negative number, the value 
<b>300</b> is assumed.
</p>
<p>
A new value assigned to the property is not applied to the Printer device.
</p>
<p>
YDPI is used to calculate the default value for the <var>PaperHeight</var> 
property.
</p>
<p>
Use XDPI for the resolution of the print device along the horizontal axis.
</p>
</descr>
<seealso>
<link id="TPrinterCanvas.Printer"/>
<link id="TPrinterCanvas.PaperHeight"/>
<link id="TPrinterCanvas.XDPI"/>
<link id="TPrinter.XDPI"/>
<link id="TPrinter.YDPI"/>
</seealso>
</element>

<element name="TPrinterCanvasRef">
<short>
Reference to the <var>TPrinterCanvas</var> class.
</short>
<descr/>
<seealso/>
</element>

<element name="TFilePrinterCanvas">
<short>
Defines a printer canvas with an associated file for its output.
</short>
<descr>
<p>
<var>TFilePrinterCanvas</var> is a <var>TPrinterCanvas</var> descendant which 
defines a printer canvas with an associated file name for its output.
</p>
<p>
Please note that 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: 
<var>TPostscriptPrinterCanvas</var>, <var>TCairoPrinterCanvas</var>, 
<var>TCocoaPrinterCanvas</var>, et. al. Theses classes are available in the 
<file>Printer4Lazarus</file> package found in the 
<file>components/printers</file> directory.
</p>
</descr>
<seealso/>
</element>

<element name="TFilePrinterCanvas.FOutputFileName"/>

<element name="TFilePrinterCanvas.OutputFileName">
<short>File name where output for the printer canvas is stored.</short>
<descr/>
<seealso/>
</element>

<element name="TFilePrinterCanvasClass">
<short>
Class reference used to create instances of the TFilePrinterCanvas class.
</short>
<descr/>
<seealso/>
</element>

<element name="TPaperRect">
<short>Holds the physical and working dimensions for a paper size.</short>
<descr>
<p>
<var>TPaperRect</var> 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 Dots.
</p>
<p>
TPaperRect is the type used to implement <var>PaperRect</var>, 
<var>PaperRectOf</var> and <var>GetDefaultPaperRect</var> in 
<var>TPaperSize</var>.
</p>
</descr>
<seealso>
<link id="TPaperSize.PaperRect"/>
<link id="TPaperSize.PaperRectOf"/>
</seealso>
</element>

<element name="TPaperRect.PhysicalRect">
<short>Rectangle for the physical paper size.</short>
<descr/>
<seealso/>
</element>

<element name="TPaperRect.WorkRect">
<short>Rectangle for the usable print area on the paper.</short>
<descr/>
<seealso/>
</element>

<element name="TPaperItem">
<short>Represents a paper size definition used for print devices.</short>
<descr/>
<seealso/>
</element>

<element name="TPaperItem.PaperName">
<short>Common name for the paper size.</short>
<descr>
<p>
Contains values like: "Letter", "Legal" or "A4". Limited to 40 characters 
maximum.
</p>
</descr>
<seealso/>
</element>

<element name="TPaperItem.PaperRect">
<short>
Contains the boundaries for the physical paper size and its available working 
area.
</short>
<descr/>
<seealso/>
</element>

<element name="TCustomPaperItem">
<short>Contains a custom paper size defined in TPaperSize.</short>
<descr/>
<seealso/>
</element>

<element name="TCustomPaperItem.PaperSet">
<short><b>True</b> when a TPaperItem instance is in the Item member.</short>
<descr/>
<seealso/>
</element>

<element name="TCustomPaperItem.Item">
<short>
Contains physical and work area rectangles for a custom paper size.
</short>
<descr/>
<seealso/>
</element>

<element name="TPaperSize">
<short>Size for a paper used on an attached printer device.</short>
<descr>
<p>
<var>TPaperSize</var> represents paper size information for an attached 
printer device. It provides an internal reference to the printer device 
passed to the Create constructor, and allows the TPrinter instance to be 
queried to retrieve its supported paper names and sizes.
</p>
<p>
TPaperSize provides properties which identify the paper by name, a list of 
paper names supported for the printer device, and provides access to the 
physical and logical size information for each. The physical size contains 
the bounds for the paper size. The logical paper size (or work rectangle) 
contains the bounds for the usable print area for the paper size. Bounds 
values are expressed as dots per inch (DPI).
</p>
<p>
TPaperSize is the type used to implement the PaperSize property in TPrinter.
</p>
</descr>
<seealso>
<link id="TPrinter.PaperSize"/>
</seealso>
</element>

<element name="TPaperSize.fOwnedPrinter"/>
<element name="TPaperSize.fSupportedPapers"/>
<element name="TPaperSize.fLastPrinterIndex"/>

<element name="TPaperSize.GetDefaultPaperName">
<short>Gets the value for the DefaultPaperName property.</short>
<descr/>
<errors/>
<seealso/>
</element>
<element name="TPaperSize.GetDefaultPaperName.Result">
<short>Value for the property.</short>
</element>

<element name="TPaperSize.GetPhysPaperHeight">
<short>Gets the value for the Height property.</short>
<descr/>
<seealso>
<link id="TPaperSize.Height"/>
</seealso>
</element>
<element name="TPaperSize.GetPhysPaperHeight.Result">
<short>Value for the property.</short>
</element>

<element name="TPaperSize.GetPaperName">
<short>Gets the value for the PaperName property.</short>
<descr/>
<errors/>
<seealso>
<link id="TPaperSize.PaperName"/>
</seealso>
</element>
<element name="TPaperSize.GetPaperName.Result">
<short>Value for the property.</short>
</element>

<element name="TPaperSize.GetPaperRect">
<short>Gets the value for the PaperRect property.</short>
<descr/>
<seealso>
<link id="TPaperSize.PaperRect"/>
</seealso>
</element>
<element name="TPaperSize.GetPaperRect.Result">
<short>Value for the property.</short>
</element>

<element name="TPaperSize.GetPhysPaperWidth">
<short>Gets the value for the Width property.</short>
<descr/>
<seealso>
<link id="TPaperSize.Width"/>
</seealso>
</element>
<element name="TPaperSize.GetPhysPaperWidth.Result">
<short>Value for the property.</short>
</element>

<element name="TPaperSize.GetSupportedPapers">
<short>Gets the value for the SupportedPapers property.</short>
<descr/>
<seealso>
<link id="TPaperSize.SupportedPapers"/>
</seealso>
</element>
<element name="TPaperSize.GetSupportedPapers.Result">
<short>Value for the property.</short>
</element>

<element name="TPaperSize.SetPaperName">
<short>Sets the value for the PaperName property.</short>
<descr/>
<seealso>
<link id="TPaperSize.PaperName"/>
</seealso>
</element>
<element name="TPaperSize.SetPaperName.AName">
<short>New value for the property.</short>
</element>

<element name="TPaperSize.PaperRectOfName">
<short>
Provides indexed access to the rectangle for the specified paper name.
</short>
<descr>
<p>
<var>PaperRectOfName</var> is an indexed <var>TPaperRect</var> 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.
</p>
<p>
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.
</p>
<p>
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.
</p>
</descr>
<errors>
<p>
Raises an EPrinter exception with the message ''The paper "%s" has no defined 
rectangle!''.
</p>
<p>
Raises an EPrinter exception with the message 'Paper "%s" is not supported!'.
</p>
</errors>
<seealso>
<link id="TPaperRect"/>
</seealso>
</element>
<element name="TPaperSize.PaperRectOfName.Result">
<short>TPaperRect value for the paper with the given name.</short>
</element>
<element name="TPaperSize.PaperRectOfName.AName">
<short>
Paper name to locate in the SupportedPapers property or a custom Paper 
defined in the paper size.
</short>
</element>

<element name="TPaperSize.CheckSupportedPapers">
<short>
Ensures that a printer is selected and the default paper sizes are available.
</short>
<descr/>
<seealso/>
</element>

<element name="TPaperSize.fInternalPapers"/>
<element name="TPaperSize.fDefaultPapers"/>
<element name="TPaperSize.fDefaultPaperIndex"/>
<element name="TPaperSize.fCustomPaper"/>
<element name="TPaperSize.CreateInternalPapers"/>
<element name="TPaperSize.FillDefaultPapers"/>

<element name="TPaperSize.GetDefaultPaperRect">
<short>Gets the rectangles for the specified default paper name.</short>
<descr>
<p>
<var>GetDefaultPaperRect</var> is an <var>Integer</var> function used to get 
a <var>TPaperRect</var> with the dimensions for the default paper name 
specified in <var>AName</var>. 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 <var>APaperRect</var> parameter.
</p>
<p>
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 <var>poPortrait</var> or <var>poReversePortrait</var> orientations. For 
<var>poLandscape</var> and <var>poReverseLandscape</var> orientations, the 
value in <var>Left</var> and <var>Right</var> become the values in 
<var>Top</var> and <var>Bottom</var> (respectively). The values in Top and 
Bottom become the values in Left and Right (respectively).
</p>
<p>
GetDefaultPaperRect is called from the implementation of the 
<var>PaperRectOfName</var> method.
</p>
</descr>
<seealso/>
</element>
<element name="TPaperSize.GetDefaultPaperRect.Result">
<short>
Position for the requested paper name in the list of default papers.
</short>
</element>
<element name="TPaperSize.GetDefaultPaperRect.AName">
<short>Name for the default paper size located in the method.</short>
</element>
<element name="TPaperSize.GetDefaultPaperRect.APaperRect">
<short>Contains the physical and working areas for the paper.</short>
</element>

<element name="TPaperSize.IndexOfDefaultPaper">
<short>
Gets the ordinal position for a default paper size with the specified name.
</short>
<descr/>
<seealso/>
</element>
<element name="TPaperSize.IndexOfDefaultPaper.Result">
<short>
Ordinal position in the list of default papers for the specified paper name.
</short>
</element>
<element name="TPaperSize.IndexOfDefaultPaper.AName">
<short>Paper name to locate in the method.</short>
</element>

<element name="TPaperSize.SetPaperRect">
<short>Sets the value for the PaperRect property.</short>
<descr/>
<seealso>
<link id="TPaperSize.PaperRect"/>
</seealso>
</element>
<element name="TPaperSize.SetPaperRect.AValue">
<short>New value for the property.</short>
</element>

<element name="TPaperSize.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
<var>Create</var> is the overloaded constructor for the class instance.
</p>
<p>
<var>AOwner</var> is the <var>TPrinter</var> 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 <b>Nil</b>).
</p>
<p>
Create calls the inherited constructor.
</p>
<p>
Create allocates resources and initializes internal members used in the class 
instance.
</p>
</descr>
<errors>
<dl>
<dt>Exception</dt>
<dd>
Raised with the message 'TMediaSize.Create, aOwner must be defined!' when 
<var>AOwner</var> has not been assigned.
</dd>
</dl>
</errors>
<seealso/>
</element>
<element name="TPaperSize.Create.aOwner">
<short>Owner of the class instance.</short>
</element>

<element name="TPaperSize.Destroy">
<short>Destructor for the class instance.</short>
<descr>
<p>
<var>Destroy</var> is the overridden destructor for the class instance. 
Destroy frees resources allocated to internal members in the class instance, 
and calls the inherited destructor.
</p>
</descr>
<seealso/>
</element>

<element name="TPaperSize.DefaultPapers">
<short>
Indicates if default paper sizes have been defined and added to 
SupportedPapers.
</short>
<descr>
<p>
<var>DefaultPapers</var> is set to <b>True</b> when internal TPaperItem 
entries are created for valid papers sizes and the SupportedPapers property 
is updated. When <b>True</b>, SupportedPapers will always contain entries for 
the "Letter", "Legal", and "A4" paper sizes.
</p>
</descr>
<seealso>
<link id="TPaperSize.SupportedPapers"/>
<link id="TPaperItem"/>
<link id="TCustomPaperItem"/>
</seealso>
</element>

<element name="TPaperSize.Width">
<short>Physical width for the paper size.</short>
<descr>
<p>
<var>Width</var> is a read-only <var>Integer</var> property which contains 
the width, in dots, for the physical paper size. Its value is read from the 
PhysicalRect member in PaperRect, and calculated as the difference between 
the Right and Left values for the physical page.
</p>
</descr>
<seealso>
<link id="TPaperSize.PaperRect"/>
<link id="TPaperRect"/>
</seealso>
</element>

<element name="TPaperSize.Height">
<short>Physical height for the paper size.</short>
<descr>
<p>
<var>Height</var> is a read-only <var>Integer</var> property with the height, 
in dots, for the physical paper size. The property value is calculated using 
PaperRect as the difference between the Bottom and Top values for the 
physical page.
</p>
</descr>
<seealso>
<link id="TPaperSize.PaperRect"/>
<link id="TPaperRect"/>
</seealso>
</element>

<element name="TPaperSize.PaperName">
<short>The name used for the paper size, like Legal or Letter.</short>
<descr>
<p>
Reading a value for the property causes the SupportedPapers and DefaultPapers 
to be initialized if default paper sizes do not already exist. It also occurs 
when a new printer device is selected. If a custom paper size is set, its 
name is returned as the property value. Otherwise, the selected paper name 
for the printer device is returned. If the property value cannot be 
determined, the value in DefaultPaperName is used.
</p>
</descr>
<seealso>
<link id="TPaperSize.SupportedPapers"/>
<link id="TPaperSize.DefaultPapers"/>
<link id="TPaperSize.DefaultPaperName"/>
<link id="TPrinter.DoEnumPapers"/>
<link id="TPrinter.DoGetPaperName"/>
</seealso>
</element>

<element name="TPaperSize.DefaultPaperName">
<short>
The default paper name used when not selected or available in the printer 
device.
</short>
<descr>
<p>
Reading a value for the property causes the SupportedPapers and DefaultPapers 
to be initialized if the paper sizes do not already exist. It also occurs 
when a new printer device is selected. When DefaultPapers is <b>True</b>, the 
first value in SupportedPapers is used as the property value. Otherwise, the 
default paper name for the printer device is returned.
</p>
<p>
DefaultPaperName is used when getting the value for the PaperName property.
</p>
</descr>
<seealso>
<link id="TPaperSize.PaperName"/>
<link id="TPaperSize.SupportedPapers"/>
<link id="TPaperSize.DefaultPapers"/>
<link id="TPrinter.DoGetDefaultPaperName"/>
</seealso>
</element>

<element name="TPaperSize.PaperRect">
<short>
The physical and logical dimension rectangles for the paper size.
</short>
<descr>
<p>
Use the PhysicalRect member to access the rectangle for the physical paper 
size. Use the WorkRect member to access the rectangle for the usable print 
area for the paper size.
</p>
</descr>
<seealso>
<link id="TPaperSize.PaperRectOf"/>
<link id="TPaperSize.PaperName"/>
<link id="TPaperSize.DefaultPaperName"/>
<link id="TPaperRect"/>
</seealso>
</element>

<element name="TPaperSize.SupportedPapers">
<short>
The list of supported paper names for the attached printer device.
</short>
<descr>
<p>
<var>SupportedPapers</var> is a read-only <var>TStrings</var> property with 
the list of paper names available for the attached printer device. It 
contains the common names for the paper sizes, like: "Letter", "Legal", or 
"A4".
</p>
<p>
Values in the property are loaded when no existing entries are found, or when 
the selected printer device has been changed. The printer device is queried 
to get the supported paper names and sizes. It if does not return any values, 
the three (3) paper sizes mentioned above are added to the list of available 
paper sizes. The first value in the list is the default paper size, and the 
DefaultPapers property is set to <b>True</b>.
</p>
<p>
SupportedPapers is used to validate a new value assigned to the PaperName 
property. The new PaperName value must exist in SupportedPapers before it is 
applied to the printer device. It serves a similar purpose when a values is 
retrieved for the indexed PaperRectOf property.
</p>
</descr>
<seealso>
<link id="TPaperSize.PaperName"/>
<link id="TPaperSize.DefaultPaperName"/>
<link id="TPaperSize.PaperRect"/>
<link id="TPaperSize.PaperRectOf"/>
<link id="TPrinter.DoEnumPapers"/>
</seealso>
</element>

<element name="TPaperSize.PaperRectOf">
<short>
Gets the dimension for a supported paper with the specified name.
</short>
<descr>
<p>
PaperRectOf is a read-only indexed TPaperRect property which provides access 
to the physical and logical dimensions for a paper size by its name. For 
example:
</p>
<code>ARect := Printer.PaperSize.PaperRectOf('Letter');</code>
<p>
Use the PhysicalRect member in the TPaperRect property value to get the 
physical bounds for the paper size. Use the WorkRect member to get the usable 
bounds for the paper size. The coordinates in the property value are 
expressed as dots (or printer pixels - if you will).
</p>
<p>
Use the Width and Height properties to get the physical paper size calculated 
for the paper size.
</p>
</descr>
<seealso>
<link id="TPaperSize.SupportedPapers"/>
<link id="TPaperSize.PaperRect"/>
<link id="TPaperSize.PaperName"/>
<link id="TPaperSize.Height"/>
<link id="TPaperSize.Width"/>
<link id="TPaperRect"/>
</seealso>
</element>
<element name="TPaperSize.PaperRectOf.aName">
<short>Name of the paper to located in the list of supported papers.</short>
</element>

<element name="TPrinterFlags">
<short>Represents status flag values used for printer devices.</short>
<descr>
<p>
<var>TPrinterFlags</var> is a set type which contains values representing 
printer status flags, and includes the following values and meanings:
</p>
<dl>
<dt>pfPrinting</dt>
<dd>Device is printing</dd>
<dt>pfAborted</dt>
<dd>Abort process</dd>
<dt>pfDestroying</dt>
<dd>Printer object is being destroyed</dd>
<dt>pfPrintersValid</dt>
<dd>Printer list is valid</dd>
<dt>pfRawMode</dt>
<dd>Printer is in raw mode</dd>
</dl>
</descr>
<seealso/>
</element>

<element name="TPrinter">
<short>
<var>TPrinter</var> defines a printer object used in Lazarus applications.
</short>
<descr>
<p>
<var>TPrinter</var> is a <var>TObject</var> descendant which defines an API 
for a printer device.
</p>
<p>
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.
</p>
<p>
TPrinter uses a <var>Canvas</var> to position, format, and render output for 
the print device. A <var>TPrinterCanvas</var> class is provided which extends 
the familiar TCanvas class with features for printer-specific usage. The 
<var>CanvasClass</var> property allows the printer to create instances of 
TPrinterCanvas or descendent classes.
</p>
<p>
TPrinter also provides a <var>RawMode</var> 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".
</p>
<p>
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.
</p>
<p>
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). Normally, one of the descendants provided in the 
<file>printer4lazarus</file> package, like: <var>TWinPrinter</var>, 
<var>TCarbonPrinter</var>, <var>TQtPrinters</var>, <var>TCUPSPrinter</var>, 
et. al. is created and assigned to the unit global <var>Printer</var> 
variable when <file>printer4lazarus</file> is initialized for a given 
platform (widgetset) or operating system.
</p>
</descr>
<seealso>
<link id="Printer"/>
</seealso>
</element>

<element name="TPrinter.fCanvas"/>
<element name="TPrinter.fFilename"/>
<element name="TPrinter.fFonts"/>
<element name="TPrinter.fPageNumber"/>
<element name="TPrinter.fPrinters"/>
<element name="TPrinter.fPrinterIndex"/>
<element name="TPrinter.fTitle"/>
<element name="TPrinter.fPaperSize"/>
<element name="TPrinter.fCanvasClass"/>
<element name="TPrinter.fBins"/>
<element name="TPrinter.fFlags"/>

<element name="TPrinter.GetAborted">
<short>Gets the value for the Aborted property.</short>
<descr/>
<seealso/>
</element>
<element name="TPrinter.GetAborted.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinter.GetCanvas">
<short>Gets the value for the Canvas property.</short>
<descr/>
<seealso/>
</element>
<element name="TPrinter.GetCanvas.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinter.CheckPrinting">
<short>
Ensures that the Printing property contains the specified value.
</short>
<descr/>
<errors/>
<seealso/>
</element>
<element name="TPrinter.CheckPrinting.Value">
<short>Value required for the property.</short>
</element>

<element name="TPrinter.GetCanvasClass">
<short>Gets the value for the CanvasClass property.</short>
<descr/>
<seealso/>
</element>
<element name="TPrinter.GetCanvasClass.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinter.GetCopies">
<short>Gets the value for the Copies property.</short>
<descr/>
<seealso/>
</element>
<element name="TPrinter.GetCopies.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinter.GetFonts">
<short>Gets the value for the Fonts property.</short>
<descr/>
<seealso/>
</element>
<element name="TPrinter.GetFonts.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinter.GetOrientation">
<short>Gets the value for the Orientation property.</short>
<descr/>
<seealso/>
</element>
<element name="TPrinter.GetOrientation.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinter.GetPageHeight">
<short>Gets the value for the PageHeight property.</short>
<descr/>
<seealso/>
</element>
<element name="TPrinter.GetPageHeight.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinter.GetPageWidth">
<short>Gets the value for the PageWidth property.</short>
<descr/>
<seealso/>
</element>
<element name="TPrinter.GetPageWidth.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinter.GetPaperSize">
<short>Gets the value for the PaperSize property.</short>
<descr/>
<errors/>
<seealso/>
</element>
<element name="TPrinter.GetPaperSize.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinter.GetBinName">
<short>Gets the value for the BinName property.</short>
<descr/>
<seealso/>
</element>
<element name="TPrinter.GetBinName.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinter.GetDefaultBinName">
<short>Gets the value for the DefaultBinName property.</short>
<descr/>
<seealso/>
</element>
<element name="TPrinter.GetDefaultBinName.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinter.GetPrinterIndex">
<short>Gets the value for the PrinterIndex property.</short>
<descr/>
<seealso/>
</element>
<element name="TPrinter.GetPrinterIndex.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinter.GetPrinterName">
<short>Gets the value for the PrinterName property.</short>
<descr/>
<seealso/>
</element>
<element name="TPrinter.GetPrinterName.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinter.GetPrinters">
<short>Gets the value for the Printers property.</short>
<descr/>
<seealso/>
</element>
<element name="TPrinter.GetPrinters.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinter.GetPrinting">
<short>Gets the value for the Printing property.</short>
<descr/>
<seealso/>
</element>
<element name="TPrinter.GetPrinting.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinter.GetRawMode">
<short>Gets the value for the RawMode property.</short>
<descr/>
<seealso/>
</element>
<element name="TPrinter.GetRawMode.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinter.SetCanvasClass">
<short>Sets the value for the CanvasClass property.</short>
<descr/>
<seealso/>
</element>
<element name="TPrinter.SetCanvasClass.AValue">
<short>New value for the property.</short>
</element>

<element name="TPrinter.SetCopies">
<short>Sets the value for the Copies property.</short>
<descr/>
<seealso/>
</element>
<element name="TPrinter.SetCopies.AValue">
<short>New value for the property.</short>
</element>

<element name="TPrinter.SetOrientation">
<short>Sets the value for the Orientation property.</short>
<descr/>
<seealso/>
</element>
<element name="TPrinter.SetOrientation.AValue">
<short>New value for the property.</short>
</element>

<element name="TPrinter.SetPrinterIndex">
<short>Sets the value for the PrinterIndex.</short>
<descr/>
<seealso/>
</element>
<element name="TPrinter.SetPrinterIndex.AValue">
<short>New value for the property.</short>
</element>

<element name="TPrinter.SetRawMode">
<short>Sets the value for the RawMode property.</short>
<descr/>
<seealso/>
</element>
<element name="TPrinter.SetRawMode.AValue">
<short>New value for the property.</short>
</element>

<element name="TPrinter.SetBinName">
<short>Sets the value for the BinName property.</short>
<descr/>
<seealso/>
</element>
<element name="TPrinter.SetBinName.aName">
<short>New value for the property.</short>
</element>

<element name="TPrinter.SelectCurrentPrinterOrDefault">
<short>
Selects the default printer when a printer has not been selected.
</short>
<descr>
<p>
<var>SelectCurrentPrinterOrDefault</var> ensures that a valid print device is 
selected. The default printer (the first device in Printers) is used when 
<var>PrinterIndex</var> has not been assigned and the number of devices in 
<var>Printers</var> is not <b>0</b>
(<b>zero</b>).
</p>
<p>
SelectCurrentPrinterOrDefault is called from the implementation of the 
<var>BeginDoc</var> method, and when the list in Printers is loaded in the 
<var>GetPrinters</var> method. It is also called when the paper size for a 
print device is validated in the <var>TPaperSize.CheckSupportedPapers</var> 
method.
</p>
</descr>
<seealso/>
</element>

<element name="TPrinter.DoBeginDoc">
<short>
Performs actions needed when printing is started for a document.
</short>
<descr>
<p>
<var>DoBeginDoc</var> is a virtual procedure which performs actions needed 
when printing is started for a document. DoBeginDoc is called from the 
<var>BeginDoc</var> method, and occurs after checking the printer status and 
updating values in <var>PrinterFlags</var>. When <var>RawMode</var> is 
<b>False</b>, the <var>Canvas</var> has already been refreshed and its 
BeginDoc method has been called.
</p>
<remark>
In <var>TPrinter</var>, DoBeginDoc 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.
</remark>
</descr>
<seealso>
<link id="TPrinter.Printing"/>
<link id="TPrinter.PrinterFlags"/>
<link id="TPrinter.Canvas"/>
<link id="TPrinter.RawMode"/>
<link id="TPrinter.Refresh"/>
<link id="TPrinterCanvas.BeginDoc"/>
</seealso>
</element>

<element name="TPrinter.DoNewPage">
<short>
Performs actions needed to start a new page for the print device.
</short>
<descr>
<p>
<var>DoNewPage</var> is a virtual procedure used to perform actions needed to 
start a new page for the print device. DoNewPage is called from the 
<var>NewPage</var> method when an overridden method has been provided in the 
class implementation. It occurs after checking the printer status and 
incrementing the value in <var>PageNumber</var>.
</p>
<remark>
In <var>TPrinter</var>, DoNewPage 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.
</remark>
</descr>
<seealso/>
</element>

<element name="TPrinter.DoBeginPage">
<short>Performs actions needed to begin a page for the print device.</short>
<descr>
<p>
<var>DoBeginPage</var> is a virtual procedure used to perform actions needed 
to begin a page for the selected print device. DoBeginPage is called from the 
<var>BeginPage</var> method, and occurs after checking the printer status and 
incrementing the <var>PageNumber</var>.
</p>
<remark>
In <var>TPrinter</var>, DoBeginPage 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.
</remark>
</descr>
<seealso>
</seealso>
</element>

<element name="TPrinter.DoEndPage">
<short>
Performs actions needed to end the current page for the print device.
</short>
<descr>
<p>
<var>DoEndPage</var> is a virtual procedure used to perform actions needed to 
end the current page for the print device. DoEndPage is called from the 
<var>EndPage</var> method, and occurs after synchronizing the printer canvas 
when <var>RawMode</var> is <b>False</b>.
</p>
<remark>
In <var>TPrinter</var>, DoEndPage 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.
</remark>
</descr>
<seealso>
<link id="TPrinter.EndPage"/>
<link id="TPrinter.Canvas"/>
<link id="TPrinter.RawMode"/>
</seealso>
</element>

<element name="TPrinter.DoEndDoc">
<short>Performs actions need to end printing for the current document.</short>
<descr>
<p>
<var>DoEndDoc</var> is a virtual method used to finishing printing the 
current document. <var>aAborted</var> is <b>True</b> if printing has been 
halted by calling the <var>Abort</var> method.
</p>
<remark>
In <var>TPrinter</var>, DoEndDoc 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.
</remark>
</descr>
<seealso/>
</element>
<element name="TPrinter.DoEndDoc.aAborted">
<short>
<b>True</b> if document printing was aborted rather than ended normally.
</short>
</element>

<element name="TPrinter.DoAbort">
<short>
Performs actions needed to abort printing for the current document.
</short>
<descr>
<p>
<var>DoAbort</var> is a virtual procedure used to perform actions needed to 
abort printing for the current document. DoAbort is called from the 
<var>Abort</var> method, and occurs after checking the printer status and 
before setting values in <var>PrinterFlags</var>.
</p>
<remark>
In <var>TPrinter</var>, DoAbort 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.
</remark>
</descr>
<seealso/>
</element>

<element name="TPrinter.DoResetPrintersList">
<short>
Performs actions needed to reset the status for the list of Printers.
</short>
<descr>
<p>
<var>DoResetPrintersList</var> is a virtual method which performs actions 
needed to reset the status for the list of available devices in the 
<var>Printers</var> property. DoResetPrintersList removes the value 
<var>pfPrintersValid</var> from the <var>PrinterFlags</var> property.
</p>
<p>
DoResetPrintersList is called from the <var>Refresh</var> method, and occurs 
prior to clearing and re-populating values in the Printers property. It is 
also called from the <var>DoDestroy</var> method when the class instance is 
freed.
</p>
<remark>
DoResetPrintersList can be overridden in a descendent class to perform 
actions needed for the operating system / widgetset / printer-related 
technology used in the implementation.
</remark>
</descr>
<seealso/>
</element>

<element name="TPrinter.DoResetFontsList">
<short>
Performs actions needed to reset the list of Fonts for the selected printer.
</short>
<descr>
<p>
<var>DoResetFontsList</var> 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).
</p>
<p>
DoResetFontsList is called from the Refresh method, and from DoDestroy when 
the class instance is freed.
</p>
<remark>
DoResetFontsList can be overridden in a descendent class to perform actions 
needed for the operating system / widgetset / printer-related technology used 
in the implementation.
</remark>
</descr>
<seealso/>
</element>

<element name="TPrinter.DoEnumPrinters">
<short>
Performs actions needed to populate the specified list with available 
printers.
</short>
<descr>
<p>
<var>DoEnumPrinters</var> is a virtual procedure used to performs actions 
needed to populate the list in <var>Lst</var> with the printers available in 
the class instance. DoEnumPrinters has an empty implementation in 
<var>TPrinter</var>. It must be overridden in a descendent class to perform 
the actions required for the implementation.
</p>
<remark>
The method must ensure that the first printer (stored at position <b>0</b>) 
in Lst is the "<b>default</b>" printer for the operating system / widgetset / 
printer-related technology.
</remark>
<p>
DoEnumPrinters is called from the <var>GetPrinters</var> method, and passes 
the member for the <var>Printers</var> property as the list storage for the 
method.
</p>
</descr>
<seealso>
<link id="TPrinter.Printers"/>
</seealso>
</element>
<element name="TPrinter.DoEnumPrinters.Lst">
<short>TStrings instance where names for defined printers are stored.</short>
</element>

<element name="TPrinter.DoEnumFonts">
<short>
Performs actions needed to get a list of fonts supported for a print device.
</short>
<descr>
<p>
<var>DoEnumFonts</var> 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.
</p>
<remark>
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.
</remark>
</descr>
<seealso/>
</element>
<element name="TPrinter.DoEnumFonts.Lst">
<short>TStrings instance where the list of font names is stored.</short>
</element>

<element name="TPrinter.DoEnumPapers">
<short>
Performs actions needed to get the supported papers for the print device.
</short>
<descr>
<p>
<var>DoEnumPapers</var> has an empty implementation in TPrinter; it must be 
overridden in a descendent class to implement the functionality.
</p>
</descr>
<seealso>
<link id="TPrinter.PaperSize"/>
<link id="TPaperSize"/>
</seealso>
</element>
<element name="TPrinter.DoEnumPapers.Lst">
<short>
TStrings instance with the list of paper supported for the print device.
</short>
</element>

<element name="TPrinter.DoEnumBins">
<short>
Performs action needed to get the Paper Bins for the printer device.
</short>
<descr>
<p>
<var>DoEnumBins</var> has an empty implementation in TPrinter; it must be 
overridden in a descendent class to implement the functionality.
</p>
</descr>
<seealso>
<link id="TPrinter.SupportedBins"/>
<link id="TPrinter.BinName"/>
<link id="TPrinter.DefaultBinName"/>
</seealso>
</element>
<element name="TPrinter.DoEnumBins.Lst">
<short>TStrings instance with the Paper Bins for the printer.</short>
</element>

<element name="TPrinter.DoInitialization">
<short>
Performs initializations after the list of Printers has been populated.
</short>
<descr>
<p>
<var>DoInitialization</var> is a method used to initialize the class instance 
after the list of supported <var>Printers</var> has been retrieved. 
DoInitialization has an empty implementation in <var>TPrinter</var>, and must 
overridden in a descendent class to implement the functionality.
</p>
<p>
DoInitialization is called from the <var>GetPrinters</var> method, and occurs 
only once when the <var>PrinterFlags</var> does <b>NOT</b> include the values 
<var>pfPrintersValid</var> and <var>pfDestroying</var>. When called, the 
<var>DoEnumPrinters</var> method has successfully completed and the default 
printer has been selected using the <var>SelectCurrentPrinterOrDefault</var> 
method.
</p>
</descr>
<seealso>
<link id="TPrinter.Printers"/>
<link id="TPrinter.Printers"/>
<link id="TPrinter.PrinterFlags"/>
<link id="TPrinter.DoEnumPrinters"/>
<link id="TPrinter.SelectCurrentPrinterOrDefault"/>
<link id="TPrinterFlags"/>
</seealso>
</element>

<element name="TPrinter.DoSetPrinter">
<short>Performs actions needed to select the specified printer name.</short>
<descr>
<p>
<var>DoSetPrinter</var> is a virtual <var>Integer</var> function used to 
perform actions needed to set the selected printer to the name specified in 
<var>aName</var>. The return value contains the ordinal position in 
<var>Printers</var> where the name is located, or <b>-1</b> when the 
specified name was not found.
</p>
<remark>
In <var>TPrinter</var>, DoSetPrinter always returns the value <b>-1</b>. 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.
</remark>
<p>
DoSetPrinter is called from the <var>SetPrinter</var> method.
</p>
</descr>
<seealso>
<link id="TPrinter.Printers"/>
<link id="TPrinter.SetPrinter"/>
<link id="TPrinter.PrinterIndex"/>
</seealso>
</element>
<element name="TPrinter.DoSetPrinter.Result">
<short>
Ordinal position for the specified printer name, or -1 when not found.
</short>
</element>
<element name="TPrinter.DoSetPrinter.aName">
<short>Printer name to use as the selected print device.</short>
</element>

<element name="TPrinter.DoGetCopies">
<short>
Performs actions needed to get the number of copies currently set for the 
print device.
</short>
<descr>
<p>
<var>DoGetCopies</var> is a virtual <var>Integer</var> 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 <var>Copies</var> 
property is read.
</p>
<remark>
In <var>TPrinter</var>, DoGetCopies always returns the value <b>1</b>. 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.
</remark>
</descr>
<seealso>
<link id="TPrinter.Copies"/>
</seealso>
</element>
<element name="TPrinter.DoGetCopies.Result">
<short>Number of copies currently in use.</short>
</element>

<element name="TPrinter.DoSetCopies">
<short>
Performs actions needed to set the number of copies for each printed page.
</short>
<descr>
<p>
<var>DoSetCopies</var> 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 <var>Copies</var> property.
</p>
<remark>
In <var>TPrinter</var>, 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.
</remark>
</descr>
<seealso>
<link id="TPrinter.Copies"/>
</seealso>
</element>
<element name="TPrinter.DoSetCopies.aValue">
<short>Number of copies to use for the print device.</short>
</element>

<element name="TPrinter.DoGetOrientation">
<short>
Performs actions needed to get the page orientation for the print device.
</short>
<descr>
<p>
<var>DoGetOrientation</var> is a virtual <var>TPrinterOrientation</var> 
function used to perform actions needed to get the page orientation for the 
print device. DoGetOrientation is called when the value for the 
<var>Orientation</var> property is retrieved, and provides the value used in 
the property.
</p>
<remark>
In <var>TPrinter</var>, DoGetOrientation always returns the value 
<var>poPortrait</var>. 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.
</remark>
</descr>
<seealso>
<link id="TPrinter.Orientation"/>
</seealso>
</element>
<element name="TPrinter.DoGetOrientation.Result">
<short>TPrinterOrientation value for the page orientation.</short>
</element>

<element name="TPrinter.DoSetOrientation">
<short>Sets the page orientation for a printer device.</short>
<descr>
<p>
<var>DoSetOrientation</var> is a virtual procedure used to perform actions 
needed to set the page orientation for a print device. <var>AValue</var> is a 
value from the <var>TPrinterOrientation</var> enumeration applied to the 
print device. See <link id="TPrinterOrientation">TPrinterOrientation</link> 
for more information about the enumeration values and their meanings. 
DoSetOrientation is called when a new value is assigned to the 
<var>Orientation</var> property.
</p>
<remark>
In <var>TPrinter</var>, 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.
</remark>
</descr>
<seealso>
<link id="TPrinter.Orientation"/>
<link id="TPrinterOrientation"/>
</seealso>
</element>
<element name="TPrinter.DoSetOrientation.aValue">
<short>Page orientation applied to the print device.</short>
</element>

<element name="TPrinter.DoGetDefaultPaperName">
<short>
Performs actions needed to get the name for the default paper on the print 
device.
</short>
<descr>
<p>
<var>DoGetDefaultPaperName</var> is a virtual <var>String</var> 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 <var>TPaperSize.DefaultPaperName</var> property is 
read.
</p>
<remark>
In <var>TPrinter</var>, DoGetDefaultPaperName always returns an empty string 
(<b>''</b>). 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.
</remark>
</descr>
<seealso>
<link id="TPrinter.PaperSize"/>
<link id="TPaperSize.DefaultPaperName"/>
<link id="TPaperSize.DefaultPapers"/>
</seealso>
</element>
<element name="TPrinter.DoGetDefaultPaperName.Result">
<short>Name for the default paper on the selected print device.</short>
</element>

<element name="TPrinter.DoGetPaperName">
<short>
Performs action needed to get the selected paper name for the current printer.
</short>
<descr>
<p>
<var>DoGetPaperName</var> is a virtual <var>String</var> function which 
performs action needed to get the selected paper name for the current 
printer. DoGetPaperName is called when the value for the 
<var>TPaperSize.PaperName</var> property in the printer is read.
</p>
<remark>
In <var>TPrinter</var>, DoGetPaperName always returns an empty string 
(<b>''</b>). It must be overridden in a descendent class to perform actions 
needed for the operating system /  widgetset / printer-related technology 
used in the implementation.
</remark>
</descr>
<seealso>
<link id="TPrinter.PaperSize"/>
<link id="TPaperSize.PaperName"/>
</seealso>
</element>
<element name="TPrinter.DoGetPaperName.Result">
<short>Name of the paper selected for the current printer.</short>
</element>

<element name="TPrinter.DoSetPaperName">
<short>
Performs actions needed to set the paper for the current printer to the 
specified name.
</short>
<descr>
<p>
<var>DoSetPaperName</var> 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 <var>PaperName</var> property in 
<var>PaperSize</var>.
</p>
<remark>
In <var>TPrinter</var>, 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.
</remark>
</descr>
<seealso/>
</element>
<element name="TPrinter.DoSetPaperName.aName">
<short>Paper name selected for the printer.</short>
</element>

<element name="TPrinter.DoGetDefaultBinName">
<short>
Performs actions needed to get the name for the default bin on the selected 
printer.
</short>
<descr>
<remark>
In <var>TPrinter</var>, 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.
</remark>
</descr>
<seealso/>
</element>
<element name="TPrinter.DoGetDefaultBinName.Result">
<short>Name for the default paper bin on the current printer.</short>
</element>

<element name="TPrinter.DoGetBinName">
<short>
Performs actions needed to get the current paper bin selected for the print 
device.
</short>
<descr>
<remark>
In <var>TPrinter</var>, 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.
</remark>
</descr>
<seealso/>
</element>
<element name="TPrinter.DoGetBinName.Result">
<short>Name for the paper bin selected on the current printer.</short>
</element>

<element name="TPrinter.DoSetBinName">
<short>
Performs actions needed to set the selected paper bin for the current printer.
</short>
<descr>
<remark>
In <var>TPrinter</var>, 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.
</remark>
</descr>
<seealso/>
</element>
<element name="TPrinter.DoSetBinName.aName">
<short>Name for the paper bin selected in the method.</short>
</element>

<element name="TPrinter.DoGetPaperRect">
<short>
Performs actions needed to get the dimensions (rectangle) for the specified 
paper.
</short>
<descr>
<p>
<var>DoGetPaperRect</var> is an <var>Integer</var> 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.
</p>
<dl>
<dt>0</dt>
<dd>aPaperRc is the margins for the specified paper name.</dd>
<dt>1</dt>
<dd>aPaperRc is the physical dimensions for the work area in the paper.</dd>
<dt>-1</dt>
<dd>A paper with the specified name was not found, or its dimension are not 
known.</dd>
</dl>
<remark>
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.
</remark>
</descr>
<seealso>
<link id="TPaperSize.SupportedPapers"/>
</seealso>
</element>
<element name="TPrinter.DoGetPaperRect.Result">
<short>0 for margins, 1 for physical paper, -1 when not found.</short>
</element>
<element name="TPrinter.DoGetPaperRect.aName">
<short>Paper name to locate for the selected printer.</short>
</element>
<element name="TPrinter.DoGetPaperRect.aPaperRc">
<short>Rectangle with the dimensions for the paper.</short>
</element>

<element name="TPrinter.DoSetPaperRect">
<short>Performs actions needed to set the dimensions for the paper.</short>
<descr>
<remark>
In <var>TPrinter</var>, DoSetPaperRect always returns <b>False</b>. It must 
be overridden in a descendent class to perform actions needed for the 
operating system / widgetset / printer-related technology used in the 
implementation.
</remark>
</descr>
<seealso/>
</element>
<element name="TPrinter.DoSetPaperRect.Result">
<short>
<b>True</b> if the dimension for the paper were successfully applied.
</short>
</element>
<element name="TPrinter.DoSetPaperRect.aPaperRc">
<short>Rectangle with the physical dimensions for the paper.</short>
</element>

<element name="TPrinter.DoGetPrinterState">
<short>Gets the value for the PrinterState property.</short>
<descr>
<p>
<var>DoGetPrinterState</var> 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.
</p>
<remark>
In <var>TPrinter</var>, 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.
</remark>
</descr>
<seealso>
<link id="TPrinter.PrinterState"/>
</seealso>
</element>
<element name="TPrinter.DoGetPrinterState.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinter.DoDestroy">
<short>Performs actions needed when the print device is freed.</short>
<descr>
<p>
<var>DoDestroy</var> is a virtual procedure used to perform actions needed 
when the print device is freed. In <var>TPrinter</var>, the following actions 
are performed:
</p>
<ul>
<li>When Printing is <b>True</b>, Abort is called.</li>
<li>Frees resources allocated to the internal member used for Paper Bins.</li>
<li>Frees the Canvas (when assigned).</li>
<li>Frees PaperSize (when assigned).</li>
<li>Resets and frees the list of Printers (when assigned).</li>
<li>Resets and frees Fonts (when assigned).</li>
</ul>
<p>
DoDestroy is normally overridden in a descendent class to perform additional 
actions required for the implementation.
</p>
<p>
DoDestroy is called from the Destroy destructor.
</p>
</descr>
<seealso>
<link id="TPrinter.Destroy"/>
</seealso>
</element>

<element name="TPrinter.GetPrinterType">
<short>Gets the value for the PrinterType property.</short>
<descr/>
<seealso>
<link id="TPrinter.PrinterType"/>
</seealso>
</element>
<element name="TPrinter.GetPrinterType.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinter.GetCanPrint">
<short>Gets the value for the CanPrint property.</short>
<descr/>
<seealso>
<link id="TPrinter.CanPrint"/>
</seealso>
</element>
<element name="TPrinter.GetCanPrint.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinter.GetCanRenderCopies">
<short>Gets the value for the CanRenderCopies property.</short>
<descr/>
<seealso>
<link id="TPrinter.CanRenderCopies"/>
</seealso>
</element>
<element name="TPrinter.GetCanRenderCopies.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinter.GetXDPI">
<short>Gets the value for the XDPI property.</short>
<descr/>
<seealso>
<link id="TPrinter.XDPI"/>
</seealso>
</element>
<element name="TPrinter.GetXDPI.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinter.GetYDPI">
<short>Gets the value for the YDPI property.</short>
<descr/>
<seealso>
<link id="TPrinter.YDPI"/>
</seealso>
</element>
<element name="TPrinter.GetYDPI.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinter.GetBins">
<short>Gets the value for the SupportedBins property.</short>
<descr/>
<seealso>
<link id="TPrinter.SupportedBins"/>
</seealso>
</element>
<element name="TPrinter.GetBins.Result">
<short>Value for the property.</short>
</element>

<element name="TPrinter.CheckRawMode">
<short>Ensures that RawMode contains the specified value.</short>
<descr>
<p>
<var>CheckRawMode</var> is a procedure used to ensure that the 
<var>RawMode</var> property contains the specified <var>Value</var>. If 
RawMode does not have the requested value, an <var>EPrinter</var> exception 
is raised. <var>Msg</var> contains the message text for the exception. When 
Msg is not specified, or contains an empty string (<b>''</b>), a default 
message is used:
</p>
<dl>
<dt>Value is <b>True</b></dt>
<dd>Msg contains 'Printer is in Raw Mode'</dd>
<dt>Value is <b>False</b></dt>
<dd>Msg contains 'Printer is not in Raw Mode'</dd>
</dl>
<p>
CheckRawMode is called when getting the value for the <var>Canvas</var> 
property.
</p>
</descr>
<errors>
<p>
Raises an <var>EPrinter</var> exception when <var>RawMode</var> does not 
contain the required value.
</p>
</errors>
<seealso>
<link id="TPrinter.RawMode"/>
<link id="TPrinter.Canvas"/>
<link id="EPrinter"/>
</seealso>
</element>
<element name="TPrinter.CheckRawMode.Value">
<short>Value required in the RawMode property.</short>
</element>
<element name="TPrinter.CheckRawMode.Msg">
<short>Message text for an exception raised in the method.</short>
</element>

<element name="TPrinter.RawModeChanging">
<short>
Performs actions needed when a new value is assigned to RawMode.
</short>
<descr>
<p>
<var>RawModeChanging</var> is a virtual procedure used to perform actions 
needed when a new value is assigned for the <var>RawMode</var> property. 
RawModeChanging is called from the <var>SetRawMode</var> method, and occurs 
after checking the value in <var>Printing</var> and before changing values in 
<var>PrinterFlags</var>. It is useful when switching from RawMode (which does 
not require a printer <var>Canvas</var>) to using a page description language 
like Postscript (which requires a specialized printer Canvas).
</p>
<remark>
In <var>TPrinter</var>, 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.
</remark>
</descr>
<seealso>
<link id="TPrinter.RawMode"/>
<link id="TPrinter.Printing"/>
<link id="TPrinter.PrinterFlags"/>
<link id="TPrinter.Canvas"/>
<link id="TPrinterCanvas"/>
</seealso>
</element>

<element name="TPrinter.PrinterSelected">
<short>
Performs actions needed when a new printer has been selected.
</short>
<descr>
<p>
<var>PrinterSelected</var> 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 <var>SetPrinter</var> method to signal 
that a printer has been successfully selected from the list of 
<var>Printers</var>, and that the value in <var>PrinterIndex</var> has been 
updated.
</p>
<remark>
In <var>TPrinter</var>, 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.
</remark>
</descr>
<seealso>
<link id="TPrinter.SetPrinter"/>
<link id="TPrinter.PrinterIndex"/>
<link id="TPrinter.Printers"/>
</seealso>
</element>

<element name="TPrinter.DoGetDefaultCanvasClass">
<short>
Performs actions to get the default class used for the Canvas property.
</short>
<descr/>
<seealso/>
</element>
<element name="TPrinter.DoGetDefaultCanvasClass.Result">
<short>
Class reference used to create new instances of the Canvas for the print 
device.
</short>
</element>

<element name="TPrinter.PrinterFlags">
<short>Status flags currently enabled for the print device.</short>
<descr>
<p>
<var>PrinterFlags</var> is a <var>TPrinterFlags</var> property which contains 
the flags currently enabled for a print device. Flag values are removed from 
PrinterFlags when they are disabled.
</p>
<dl>
<dt>pfDestroying</dt>
<dd>Set in Destroy.</dd>
<dt>pfAborted</dt>
<dd>
Set in Aborted. Removed in BeginDoc, EndDoc. Provides the value for the 
Aborted property.
</dd>
<dt>pfPrinting</dt>
<dd>
Set in BeginDoc. Removed in EndDoc. Provides the value for the Printing 
property.
</dd>
<dt>pfPrintersValid</dt>
<dd>Set in GetPrinters. Removed in DoResetPrintersList.</dd>
<dt>pfRawMode</dt>
<dd>
Set or removed when the value for RawMode is changed. Provides the value for 
the RawMode property.
</dd>
</dl>
</descr>
<seealso>
<link id="TPrinterFlags"/>'
<link id="TPrinter.Destroy"/>'
<link id="TPrinter.DoResetPrintersList"/>'
<link id="TPrinter.Printers"/>'
<link id="TPrinter.RawMode"/>'
<link id="TPrinter.BeginDoc"/>'
<link id="TPrinter.EndDoc"/>'
</seealso>
</element>

<element name="TPrinter.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
<var>Create</var> is the constructor for the class instance, and calls the 
inherited constructor on entry.
</p>
<p>
Create sets the value in <var>PrinterIndex</var> to <b>-1</b> which indicates 
that the default printer in <var>Printers</var> should be used.
</p>
<p>
Create stores an unassigned value (<b>Nil</b>) in the <var>Canvas</var>, 
<var>PaperSize</var>, and <var>Bins</var> properties. The <var>Title</var> 
property is set to an empty String (<b>''</b>).
</p>
<remark>
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 
<file>printer4lazarus</file> package.
</remark>
</descr>
<errors>
<p>
Raises an exception with the message 'TPrinter is an abstract base class.' 
when TPrinter is the ClassType for the new instance.
</p>
</errors>
<seealso/>
</element>

<element name="TPrinter.Destroy">
<short>Destructor for the class instance.</short>
<descr>
<p>
<var>Destroy</var> is the overridden destructor for the class instance. 
Destroy updates the status flags for the device to include the value 
<var>pfDestroying</var>. It calls the <var>DoDestroy</var> method to cancel 
an active print job and free resources allocated in the class instance. 
Destroy calls the inherited destructor prior to exit.
</p>
</descr>
<seealso/>
</element>

<element name="TPrinter.Abort">
<short>
Terminates printing of the current document (when active).
</short>
<descr>
<p>
<var>Abort</var> is a procedure used to terminate printing of the current 
document (when active). Aborts calls <var>CheckPrinting</var> to ensure that 
<var>Printing</var> contains <b>True</b>. CheckPrinting raises an exception 
if Abort is called when <var>BeginDoc</var> has not been called.
</p>
<p>
Abort calls the <var>DoAbort</var> method to perform any actions needed for 
the class implementation.
</p>
<p>
Abort updates the <var>PrinterFlags</var> property to include the value 
<var>pfAborted</var>, and calls the <var>EndDoc</var> method to end printing 
for the current document.
</p>
</descr>
<seealso>
<link id="TPrinter.Printing"/>
<link id="TPrinter.PrinterFlags"/>
<link id="TPrinter.DoAbort"/>
<link id="TPrinter.BeginDoc"/>
<link id="TPrinter.EndDoc"/>
<link id="TPrinterFlags"/>
</seealso>
</element>

<element name="TPrinter.BeginDoc">
<short>Starts printing for the current document.</short>
<descr>
<p>
<var>BeginDoc</var> is a procedure used to start printing for the current 
document. BeginDoc calls <var>CheckPrinting</var> to ensure that the print 
device has not already started printing for the document. CheckPrinting 
raises an exception if the value in <var>Printing</var> is <b>True</b>.
</p>
<p>
BeginDoc calls <var>SelectCurrentPrinterOrDefault</var> 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.
</p>
<p>
BeginDoc updates <var>PrinterFlags</var> to include the value 
<var>pfPrinting</var>, and removes the value <var>pfAborted</var> (if 
present). The <var>PageNumber</var> property is reset for the newly started 
printing operation.
</p>
<p>
BeginDoc uses the value in <var>RawMode</var> to determine if a printer 
canvas is in used for the class instance. When RawMode is <b>False</b>, a 
<var>TPrinterCanvas</var> instance exists in <var>Canvas</var>. Its 
<var>Refresh</var> method is called, and the <var>BeginDoc</var> method in 
the printer canvas is called to synchronize the canvas. The value in 
<var>YDPI</var> is assigned to the PPI (Pixels per Inch) setting for the 
canvas font. No actions are performed for the printer canvas when RawMode is 
<b>True</b>.
</p>
<p>
BeginDoc calls the <var>DoBeginDoc</var> method to perform any actions 
specific to the current class implementation. <var>BeginPage</var> is called 
to increment the <var>PageNumber</var> for the print device.
</p>
<p>
Use <var>EndDoc</var> to finish printing for the current document.
</p>
</descr>
<seealso>
<link id="TPrinter.RawMode"/>
<link id="TPrinter.Printing"/>
<link id="TPrinter.PrinterFlags"/>
<link id="TPrinter.Canvas"/>
<link id="TPrinter.SelectCurrentPrinterOrDefault"/>
<link id="TPrinter.PrinterIndex"/>
<link id="TPrinter.PageNumber"/>
<link id="TPrinter.BeginPage"/>
<link id="TPrinter.SetPrinter"/>
<link id="TPrinter.EndDoc"/>
<link id="TPrinterCanvas"/>
</seealso>
</element>

<element name="TPrinter.EndDoc">
<short>Ends printing for the current document.</short>
<descr>
<p>
<var>EndDoc</var> is a procedure used to end printing for the current 
document. EndDoc calls <var>CheckPrinting</var> to ensure that 
<var>Printing</var> contains <b>True</b>. An exception is raised in 
CheckPrinting if Printing contains <b>False</b>.
</p>
<p>
EndDoc calls the <var>EndPage</var> method to synchronize the printer 
<var>Canvas</var> (when used) and to perform any actions required for the 
class implementation. The EndDoc method for the Canvas is called when 
<var>RawMode</var> is <b>False</b>.
</p>
<p>
<var>DoEndDoc</var> is called using the value in <var>Aborted</var> as an 
argument, and allows any actions needed for the class implementation to be 
performed.
</p>
<p>
EndDoc updates values in the <var>PrinterFlags</var> property to reflect the 
current printer and document state. The values <var>pfPrinting</var> and 
<var>pfAborted</var> are removed from PrinterFlags.
</p>
<p>
The value in the <var>PageNumber</var> is reset to <b>0</b> (<b>zero</b>).
</p>
<p>
Use <var>BeginDoc</var> to start printing a document. Use <var>Abort</var> to 
abandon printing the current document.
</p>
</descr>
<seealso>
<link id="TPrinter.Printing"/>
<link id="TPrinter.PrinterFlags"/>
<link id="TPrinter.RawMode"/>
<link id="TPrinter.Canvas"/>
<link id="TPrinter.PageNumber"/>
<link id="TPrinter.Aborted"/>
<link id="TPrinter.Abort"/>
<link id="TPrinter.BeginDoc"/>
<link id="TPrinterFlags"/>
</seealso>
</element>

<element name="TPrinter.NewPage">
<short>Creates a new page for the current document.</short>
<descr>
<p>
<var>NewPage</var> is a procedure used to create a new page for the document 
currently printing on the selected device.
</p>
<p>
NewPage checks the current class instance to see if it is a 
<var>TPrinter</var> descendant with an overridden <var>DoNewPage</var> 
method. If it has <b>not</b> been overridden, the following methods are 
called:
</p>
<ul>
<li>EndPage</li>
<li>BeginPage</li>
</ul>
<p>
When it has been overridden, the following actions are performed:
</p>
<ul>
<li>Call CheckPrinting to ensure that Printing is <b>True</b>.</li>
<li>Increment the value in PageNumber.</li>
<li>Call the NewPage method in Canvas when RawMode is <b>False</b>.</li>
<li>Call DoNewPage to execute the code for the class implementation.</li>
</ul>
</descr>
<seealso>
<link id="TPrinter.PageNumber"/>
<link id="TPrinter.Canvas"/>
<link id="TPrinter.RawMode"/>
<link id="TPrinter.BeginPage"/>
<link id="TPrinter.EndPage"/>
</seealso>
</element>

<element name="TPrinter.BeginPage">
<short>Begins a page on the print device.</short>
<descr>
<p>
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 
<b>True</b>. An exception is raised in CheckPrinting when Printing contains 
<b>False</b>.
</p>
<p>
When RawMode is <b>False</b>, the BeginPage method in Canvas is called to 
synchronize the printer canvas.
</p>
<p>
BeginPage calls the DoBeginPage method to perform any actions needed for the 
class implementation.
</p>
<p>
BeginPage is called from the BeginDoc method, and from the NewPage method 
when DoNewPage has not been overridden.
</p>
</descr>
<seealso/>
</element>

<element name="TPrinter.EndPage">
<short>Ends the current page for the document.</short>
<descr>
<p>
EndPage is a procedure used to end the current page for the document.
</p>
<p>
EndPage uses the value in RawMode to determine if a printer canvas is used. 
When RawMode is <b>False</b>, the EndPage method in Canvas is called to 
synchronize the printer canvas.
</p>
<p>
EndPage calls the DoEndPage method to perform actions needed for the class 
implementation.
</p>
</descr>
<seealso/>
</element>

<element name="TPrinter.Refresh">
<short>
Refreshes the printer list, fonts, and current device selection.
</short>
<descr>
<p>
<var>Refresh</var> performs actions needed to update the list or printers or 
fonts when the <var>SetPrinter</var> method is used to change the selected 
printer, such as:
</p>
<ul>
<li>Raises an exception if the printer is currently Printing.</li>
<li>Clears and reloads values in the Printers property.</li>
<li>Clears and reloads values in the Fonts property.</li>
<li>Saves and restores the current printer selection when possible.</li>
</ul>
<p>
<var>PrinterIndex</var> is set to <b>-1</b> if the previous printer cannot be 
re-selected after loading values in Printers. The selects the default printer 
when the previous selection becomes unavailable.
</p>
</descr>
<seealso/>
</element>

<element name="TPrinter.SetPrinter">
<short>Makes the device with the specified name the current printer.</short>
<descr>
<p>
<var>aName</var> contains the name of the printer to use as the active print 
device. It can contain a "wild-card" value <b> '*'</b> which selects the 
default printer (the first one in the list of available printers) as the 
active print device.
</p>
</descr>
<seealso/>
</element>
<element name="TPrinter.SetPrinter.aName">
<short>Name of the print device selected in the method.</short>
</element>

<element name="TPrinter.RestoreDefaultBin">
<short>Restores the selected Bin for the device to the default value.</short>
<descr/>
<seealso/>
</element>

<element name="TPrinter.Write">
<short>Writes the specified values to the print device.</short>
<descr>
<p>
<var>Write</var> is an <var>Boolean</var> function used to write the 
specified values to the printer device. Overloaded variants of the method 
allow the values to be specified as an <var>AnsiString</var> data type or an 
untyped buffer.
</p>
<p>
<var>Buffer</var> is the untyped buffer written in the method.
</p>
<p>
<var>Count</var> indicates the number of bytes in Buffer to use in the write 
operation.
</p>
<p>
<var>Written</var> contains the actual number of bytes handled in the write 
operation.
</p>
<p>
<var>S</var> is the AnsiString value written in the method.
</p>
<p>
The return value is <b>True</b> when the specified values are successfully 
written in the method.
</p>
<remark>
Neither variant of the Write method actually performs any output in TPrinter. 
The return value is always <b>False</b>, and Written always contains the 
value <b>0</b> (<b>zero</b>). Write must be re-implemented in a descendent 
class to perform the actions needed for the implementation.
</remark>
</descr>
<seealso/>
</element>
<element name="TPrinter.Write.Result">
<short>
<b>True</b> when the specified value are successfully written in the method.
</short>
</element>
<element name="TPrinter.Write.Buffer">
<short>Untyped buffer written in the method.</short>
</element>
<element name="TPrinter.Write.Count">
<short>Number of bytes from the buffer written in the method.</short>
</element>
<element name="TPrinter.Write.Written">
<short>Number of bytes actually written in the method.</short>
</element>
<element name="TPrinter.Write.s">
<short>AnsiString value written in the method.</short>
</element>

<element name="TPrinter.PrinterIndex">
<short>
Contains the ordinal position in Printers for the selected print device.
</short>
<descr>
<p>
<var>PrinterIndex</var> is an <var>Integer</var> property which contains the 
ordinal position in <var>Printers</var> for the selected print device. The 
default value for the property is <b>-1</b>, and indicates that a print 
device has not been selected and that the default printer should be used. The 
default printer is the first one in the Printers property.
</p>
<p>
Setting a new value in PrinterIndex causes the <var>CheckPrinting</var> 
method to be called to ensure that the value in <var>Printing</var> is 
<b>False</b>. An exception is raised in CheckPrinting when Printing is set to 
<b>True</b>. Set the value for the property prior to calling the 
<var>BeginDoc</var> method.
</p>
<p>
An exception may also be raised for the following conditions:
</p>
<ul>
<li>
PrinterIndex is set to a value greater than or equal to 0 and the list of 
Printers is empty.
</li>
<li>PrinterIndex is set to a value larger than the number of entries in 
Printers.</li>
</ul>
<p>
The <var>SetPrinter</var> method is called to make the named device the 
selected print device. <var>DoResetFontsList</var> is called to reload the 
values in the <var>Fonts</var> property.
</p>
</descr>
<errors>
<dl>
<dt>EPrinter</dt>
<dd>
Raised with the message 'Printer is printing'.
Raised with the message 'No printers defined!'.
Raised with the message 'Printer index out of range!'.
</dd>
</dl>
</errors>
<seealso>
<link id="TPrinter.BeginDoc"/>
<link id="TPrinter.DoResetFontsList"/>
<link id="TPrinter.Fonts"/>
<link id="TPrinter.Printing"/>
<link id="TPrinter.Printers"/>
<link id="TPrinter.SetPrinter"/>
<link id="EPrinter"/>
</seealso>
</element>

<element name="TPrinter.PrinterName">
<short>Name for the selected print device.</short>
<descr>
<p>
<var>PrinterName</var> is a read-only <var>String</var> property which 
contains the name for the currently selected print device. The property value 
is retrieved from <var>Printers</var> using the value in 
<var>PrinterIndex</var>. When PrinterIndex contains a negative value, an 
empty string (<b>''</b>) is returned as the value for the property.
</p>
<p>
Use <var>SetPrinter</var> to select a print device with a given name in 
Printers. Or, assign a new value to the PrinterIndex property.
</p>
</descr>
<seealso>
<link id="TPrinter.Printers"/>
<link id="TPrinter.PrinterIndex"/>
<link id="TPrinter.SetPrinter"/>
</seealso>
</element>

<element name="TPrinter.PaperSize">
<short>
Contains paper sizes available and/or selected for the print device.
</short>
<descr>
<p>
<var>PaperSize</var> is a read-only <var>TPaperSize</var> 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 <var>PageHeight</var> and <var>PageWidth</var> properties.
</p>
<p>
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.
</p>
</descr>
<seealso>
<link id="TPrinter.PageHeight"/>
<link id="TPrinter.PageWidth"/>
<link id="TPaperSize"/>
</seealso>
</element>

<element name="TPrinter.Orientation">
<short>Orientation for the page on the paper.</short>
<descr>
<p>
<var>Orientation</var> is a <var>TPrinterOrientation</var> property which 
indicates the orientation for the page content on its paper. For example:
</p>
<dl>
<dt>poPortrait</dt>
<dd>Long edge of the canvas is oriented to the vertical axis.</dd>
<dt>poReversePortrait</dt>
<dd>Long edge of the canvas is oriented to the vertical axis with coordinates 
rotated 180 degrees. This is often referred to as "Mirror Printing".</dd>
<dt>poLandscape</dt>
<dd>Long edge of the canvas is oriented to the horizontal axis.</dd>
<dt>poReverseLandscape</dt>
<dd>Long edge of the canvas is oriented to the horizontal axis with 
coordinates rotated 180 degrees. This is often referred to as "Mirror 
Printing".</dd>
</dl>
<p>
For TPrinter, the property value is always <var>poPortrait</var>. 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.
</p>
<p>
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.
</p>
</descr>
<seealso>
<link id="TPrinterOrientation"/>
<link id="TPrinterCanvas.Orientation"/>
<link id="TPrinterCanvas.Printer"/>
</seealso>
</element>

<element name="TPrinter.PrinterState">
<short>Indicates the current state for the print device.</short>
<descr>
<p>
<var>PrinterState</var> is a read-only TPrinterState property which contains 
a value with the current state for the print device. See <link 
id="TPrinterState">TPrinterState</link> for the enumeration values and their 
meanings.
</p>
<p>
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.
</p>
<p>
In TPrinter, the value for the property is always psNoDefine.
</p>
</descr>
<seealso>
<link id="TPrinter.DoGetPrinterState"/>
<link id="TPrinterState"/>
</seealso>
</element>

<element name="TPrinter.Copies">
<short>Number of <var>Copies</var> of the current document.</short>
<descr>
<p>
<var>Copies</var> is an <var>Integer</var> property which indicates the 
number of times a page is duplicated during the printing process. Copies is 
one the <var>TPrinterCapabilities</var> which may be supported for a print 
device.
</p>
<p>
In <var>TPrinter</var>, Copies always contains the value <b>1</b>. The 
<var>DoGetCopies</var> and <var>DoSetCopies</var> 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.
</p>
</descr>
<seealso/>
</element>

<element name="TPrinter.Printers">
<short>
Contains the names for devices that can be selected for printing.
</short>
<descr>
<p>
<var>Printers</var> is a read-only <var>TStrings</var> 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 
"<b>default</b>" printer.
</p>
<p>
Values in Printers are retrieved and stored using the 
<var>DoEnumPrinters</var> method. This method is called when the property 
value is retrieved and <var>PrinterFlags</var> does not include the 
<var>pfPrintersValid</var> flag. It is normally called only once - unless the 
<var>Refresh</var> or <var>DoResetPrintersList</var> methods are called.
</p>
<p>
Printers is used in the <var>SetPrinter</var> method to validate the name for 
the selected printer device. Its <var>Count</var> property is used in other 
methods to ensure that valid printer devices exist in the class instance.
</p>
<p>
Use <var>SetPrinter</var> to select a print device by its name. Use 
<var>PrinterIndex</var> to change the selected device to the printer at the 
specified ordinal position in Printers.
</p>
</descr>
<seealso/>
</element>

<element name="TPrinter.FileName">
<short>File name used to store output from the print device.</short>
<descr>
<p>
<var>FileName</var> is a <var>String</var> property which contains the path 
and file name on the local file system where output from the print device is 
stored.
</p>
<remark>
FileName is not used in the implementation of <var>TPrinter</var>. It is 
provided for use in descendent classes.
</remark>
</descr>
<seealso/>
</element>

<element name="TPrinter.Fonts">
<short>the list of available <var>Fonts</var> for the current printer.</short>
<descr>
<p>
<var>Fonts</var> is a read-only <var>TStrings</var> property which contains a 
list of font names available for the selected print device. Values in Fonts 
are retrieved and stored using the <var>DoEnumFonts</var> method. It is 
called when the number of items in Fonts is <b>0</b>, and when 
<var>Refresh</var> or <var>DoResetFontsList</var> is called.
</p>
<remark>
DoEnumFonts has an empty implementation in <var>TPrinter</var>. It must be 
overridden in a descendant to implement the functionality for the operating 
system / widgetset / printer-related technology.
</remark>
</descr>
<seealso/>
</element>

<element name="TPrinter.Canvas">
<short>
The <var>Canvas</var> to be used for laying out the current document ready 
for printing.
</short>
<descr>
<p>
<var>Canvas</var> is a read-only <var>TCanvas</var> property which provides 
properties and methods used to position and format content on a page.
</p>
<p>
In <var>TPrinter</var>, and descendants, a printer-aware class derived from 
TCanvas is used: <var>TPrinterCanvas</var>. 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 <var>CanvasClass</var> property identifies the class 
reference used to create the member for the Canvas property.
</p>
<p>
Canvas is used in methods like <var>BeginDoc</var>, <var>EndDoc</var>, 
<var>BeginPage</var>, and <var>EndPage</var> to synchronized the rendering 
surface to the current state for the print device. Canvas is used <b>only</b> 
when <var>RawMode</var> is set to <b>False</b>.
</p>
</descr>
<seealso/>
</element>

<element name="TPrinter.CanvasClass">
<short>
Class reference used to create new instances of the printer canvas.
</short>
<descr>
<p>
<var>CanvasClass</var> is a <var>TPrinterCanvasRef</var> property which 
contains the class reference used to create new instances of the class for 
the <var>Canvas</var> property. In <var>TPrinter</var>, the 
<var>TPrinterCanvas</var> 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 
<var>DoGetDefaultCanvasClass</var> method. The property value is always 
returns <b>Nil</b> when <var>RawMode</var> is set to <b>True</b>.
</p>
<p>
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).
</p>
</descr>
<seealso>
<link id="TPrinterCanvasRef"/>
<link id="TPrinter.Canvas"/>
<link id="TPrinter.RawMode"/>
<link id="TPrinter.DoGetDefaultCanvasClass"/>
</seealso>
</element>

<element name="TPrinter.PageHeight">
<short>Height of the usable area on the selected paper size in "Dots"</short>
<descr>
<p>
<var>PageHeight</var> is a read-only <var>Integer</var> property which 
contains the usable height for the selected paper size as a number of "Dots" 
for the native printer resolution.
</p>
<p>
PageHeight uses the <var>PaperSize</var> property to retrieve the work area 
for the selected paper size. The property value contains the difference 
between the <var>Bottom</var> and <var>Top</var> coordinates in the work area 
rectangle.
</p>
<p>
The property value is <b>0</b> (<b>zero</b>) when the <var>Printers</var> 
property is empty. You cannot access a selected paper size without a selected 
printer.
</p>
<p>
PageHeight is used to derive the page height in <var>TPrinterCanvas</var> 
when a <var>TPrinter</var> instance has been assigned.
</p>
</descr>
<seealso>
<link id="TPrinter.PaperSize"/>
<link id="TPrinter.Printers"/>
<link id="TPaperSize.PaperRect"/>
<link id="TPrinterCanvas.Printer"/>
<link id="TPrinterCanvas.PageHeight"/>
<link id="TPaperRect"/>
</seealso>
</element>

<element name="TPrinter.PageWidth">
<short>Width of the usable area on the selected paper size in "Dots"</short>
<descr>
<p>
<var>PageWidth</var> is a read-only <var>Integer</var> property which 
contains the usable width for the selected paper size as a number of "Dots" 
for the native printer resolution.
</p>
<p>
PageWidth uses the <var>PaperSize</var> property to retrieve the work area 
for the selected paper size. The property value contains the difference 
between the <var>Right</var> and <var>Left</var> coordinates in the work area 
rectangle.
</p>
<p>
The property value is <b>0</b> (<b>zero</b>) when the <var>Printers</var> 
property is empty. You cannot access a selected paper size without a selected 
printer.
</p>
<p>
PageWidth is used to derive the page width in <var>TPrinterCanvas</var> when 
a <var>TPrinter</var> instance has been assigned.
</p>
</descr>
<seealso>
<link id="TPrinter.PaperSize"/>
<link id="TPrinter.Printers"/>
<link id="TPaperSize.PaperRect"/>
<link id="TPrinterCanvas.Printer"/>
<link id="TPrinterCanvas.PageWidth"/>
<link id="TPaperRect"/>
</seealso>
</element>

<element name="TPrinter.PageNumber">
<short>
Current page number in the document being printed to the device.
</short>
<descr>
<p>
<var>PageNumber</var> is a read-only <var>Integer</var> 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: <var>BeginDoc</var>, <var>EndDoc</var>, 
<var>NewPage</var> and <var>BeginPage</var>.
</p>
</descr>
<seealso>
<link id="TPrinter.BeginDoc"/>
<link id="TPrinter.EndDoc"/>
<link id="TPrinter.NewPage"/>
<link id="TPrinter.BeginPage"/>
<link id="TPrinterCanvas.PageNumber"/>
</seealso>
</element>

<element name="TPrinter.Aborted">
<short>
<b>True</b> if printing of the document has been prematurely terminated by 
operator command.
</short>
<descr>
<p>
<var>Aborted</var> is a read-only <var>Boolean</var> property which indicates 
if the current print job has been terminated. The value for the property is 
determined by examining the values in the <var>PrinterFlags</var> property. 
When PrinterFlags includes the value <var>pfAborted</var>, the property value 
is <b>True</b>.
</p>
<p>
The status value is included in PrinterFlags when the <var>Abort</var> method 
is called. It is removed from PrinterFlags when the <var>BeginDoc</var> 
method is called.
</p>
</descr>
<seealso>
<link id="TPrinter.Abort"/>
<link id="TPrinter.BeginDoc"/>
<link id="TPrinter.PrinterFlags"/>
<link id="TPrinterFlags"/>
</seealso>
</element>

<element name="TPrinter.Printing">
<short>
<b>True</b> if the document is currently being printed.
</short>
<descr>
<p>
<var>Printing</var> is a read-only <var>Boolean</var> property which 
indicates if the device is currently printing a document. The value for the 
property is determined by examining the <var>PrinterFlags</var> for the 
device. When PrinterFlags includes the value <var>pfPrinting</var>, the 
property value is <b>True</b>.
</p>
<p>
The status value is included in PrinterFlags when the <var>BeginDoc</var> 
method is called, and removed from PrinterFlags when the <var>EndDoc</var> 
method is called.
</p>
<p>
Use <var>Abort</var> to halt the current printing process.
</p>
</descr>
<seealso>
<link id="TPrinter.PrinterFlags"/>
<link id="TPrinter.Abort"/>
<link id="TPrinter.BeginDoc"/>
<link id="TPrinter.EndDoc"/>
<link id="TPrinterFlags"/>
</seealso>
</element>

<element name="TPrinter.Title">
<short>Title of the current document for the print device.</short>
<descr>
<p>
<var>Title</var> is a <var>String</var> property which contains the title of 
the current document for the print device. The default value assigned in the 
constructor is an empty string (<b>''</b>).
</p>
<p>
Set the value in Title prior to calling the <var>BeginDoc</var> method. It 
may also be assigned using the Title property in the <var>Canvas</var> 
(<var>TPrinterCanvas</var>) for the print device. In this case, the value is 
applied to the print device as well.
</p>
</descr>
<seealso>
<link id="TPrinterCanvas.Title"/>
</seealso>
</element>

<element name="TPrinter.PrinterType">
<short>
Indicates whether the print device is a local or a network printer.
</short>
<descr>
<p>
<var>PrinterType</var> is a <var>TPrinterType</var> property which indicates 
whether the print device is locally attached, or network enabled. In 
TPrinter, the value for the property is always <var>ptLocal</var>. A 
descendent class (like <var>TCUPSPrinter</var>) may return another value from 
the TPrinterType enumeration.
</p>
</descr>
<seealso>
<link id="TPrinterType"/>
</seealso>
</element>

<element name="TPrinter.CanPrint">
<short>
<b>True</b> if printing is enabled (or not disabled).
</short>
<descr>
<p>
<var>CanPrint</var> is a read-only <var>Boolean</var> property which 
indicates if the print device is enabled and ready to print.
</p>
<remark>
In <var>TPrinter</var>, the property value is always <b>True</b>. The read 
access specifier (<var>GetCanPrint</var>) can be overridden in a descendent 
class to use the facilities for the operating system /  widgetset / 
printer-related technology in the implementation.
</remark>
</descr>
<seealso>
<link id="TPrinter.GetCanPrint"/>
</seealso>
</element>

<element name="TPrinter.CanRenderCopies">
<short>
<b>True</b> if the printer device can render copies.
</short>
<descr>
<p>
<var>CanRenderCopies</var> is a read-only <var>Boolean</var> property which 
indicates if the print device can print more than one copy of pages in the 
document. The property value is <b>True</b> when the print device includes 
the <var>pcCopies</var> printer capability.
</p>
<remark>
In <var>TPrinter</var>, the property value is always <b>True</b>. The read 
access specifier (<var>GetCanRenderCopies</var>) can be overridden in a 
descendent class to use the facilities in the operating system / widgetset / 
printer-related technology in the implementation.
</remark>
</descr>
<seealso>
<link id="TPrinter.GetCanRenderCopies"/>
<link id="TPrinterCapability"/>
</seealso>
</element>

<element name="TPrinter.XDPI">
<short>
Number of DPI (Dots per Inch) on the horizontal axis for the selected device.
</short>
<descr>
<p>
<var>XDPI</var> is a read-only <var>Integer</var> property that contains the 
horizontal resolution for the print device in DPI (Dots per Inch). The value 
in XDPI is passed to the <var>Canvas</var> for the print device, and used to 
determine the paper width for the printer canvas.
</p>
<remark>
In <var>TPrinter</var>, the value for the property is always <b>1</b>. The 
read access specifier (<var>GetXDPI</var>) 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.
</remark>
</descr>
<seealso>
<link id="TPrinter.GetXDPI"/>
<link id="TPrinter.YDPI"/>
<link id="TPrinterCanvas.Printer"/>
<link id="TPrinterCanvas.XDPI"/>
</seealso>
</element>

<element name="TPrinter.YDPI">
<short>
Number of DPI (Dots per Inch) on the vertical axis for the selected device.
</short>
<descr>
<p>
<var>YDPI</var> is a read-only <var>Integer</var> property that contains the 
vertical resolution for the print device in DPI (Dots per Inch). The value in 
YDPI is passed to the <var>Canvas</var> 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.
</p>
<remark>
In <var>TPrinter</var>, the value for the property is always <b>1</b>. The 
read access specifier (<var>GetYDPI</var>) 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.
</remark>
</descr>
<seealso>
<link id="TPrinter.GetYDPI"/>
<link id="TPrinter.XDPI"/>
<link id="TPrinterCanvas.YDPI"/>
<link id="TPrinterCanvas.Printer"/>
<link id="#lcl.graphics.TCanvas.Font">TCanvas.Font</link>
</seealso>
</element>

<element name="TPrinter.RawMode">
<short>
Indicates if raw output is used for the device (as opposed to a page 
description language).
</short>
<descr>
<p>
Set <var>RawMode</var> to <b>True</b> if the printer operates in Raw Mode (as 
opposed to PostScript or some other page description language).
</p>
<p>
When RawMode is <b>True</b>, text is sent directly to the printer device 
without formatting and the Canvas is not used to layout or position content 
on the page.
</p>
</descr>
</element>

<element name="TPrinter.DefaultBinName">
<short>Name for the default Paper Bin on the print device.</short>
<descr>
<p>
<var>DefaultBinName</var> is a read-only <var>String</var> property which 
contains the name for the default Paper Bin on the selected print device. The 
value for the property is retrieved using the <var>DoGetDefaultBinName</var> 
method.
</p>
<p>
DefaultBinName is used in the implementation of the 
<var>RestoreDefaultBin</var> method.
</p>
<p>
Use <var>BinName</var> to read or write the value for the selected paper bin 
on the print device.
</p>
<remark>
The property value is always an empty string (<b>''</b>) 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.
</remark>
</descr>
<seealso>
<link id="TPrinter.DoGetDefaultBinName"/>
<link id="TPrinter.RestoreDefaultBin"/>
<link id="TPrinter.BinName"/>
</seealso>
</element>

<element name="TPrinter.BinName">
<short>Name of the Paper Bin currently selected for the print device.</short>
<descr>
<p>
<var>BinName</var> is a <var>String</var> property with the name for the 
Paper Bin selected for the print device. BinName contains one of the values 
found in the <var>SupportedBins</var> property.
</p>
<p>
The value for the property is retrieved using the <var>DoGetBinName</var> 
method. Setting a new value for the property requires <var>Printing</var> to 
be set to <b>False</b>; an exception is raised in <var>CheckPrinting</var> 
when Printing contains <b>True</b>. The property value is applied using the 
<var>DoSetBinName</var> method.
</p>
</descr>
<seealso>
<link id="TPrinter.Printing"/>
<link id="TPrinter.DoGetBinName"/>
<link id="TPrinter.DoSetBinName"/>
<link id="TPrinter.SupportedBins"/>
</seealso>
</element>

<element name="TPrinter.SupportedBins">
<short>Names for the Paper Bins supported on the print device.</short>
<descr>
<p>
<var>SupportedBins</var> is a read-only <var>TStrings</var> property which 
contains the names for the Paper Bins supported on the selected print device. 
The value for the property is retrieved in the <var>GetBins</var> method by 
calling <var>DoEnumBins</var>.
</p>
<p>
Assign a value from <var>SupportedBins</var> to the <var>BinName</var> 
property to select a specific paper bin.
</p>
</descr>
<seealso>
<link id="TPrinter.GetBins"/>
<link id="TPrinter.DoEnumBins"/>
<link id="TPrinter.BinName"/>
</seealso>
</element>

<element name="Printer">
<short>Provides access to the TPrinter instance for an application.</short>
<descr>
<p>
<var>Printer</var> is a <var>TPrinter</var> 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.
</p>
<p>
Additional printer types and OS-specific printer implementations are 
available in the <file>components/printers/</file> directory in the 
<file>printer4lazarus</file> package. Add the <file>osPrinters.pas</file> 
unit to your program if an Access Violation error occurs when using the 
Printer variable.
</p>
</descr>
<seealso>
<link id="TPrinter"/>
<link id="using_the_printer">Using the Printer</link>
</seealso>
</element>

<topic name="using_the_printer">
<short>Using the Printer</short>
<descr>
<p>
<b>The Basic Steps</b>
</p>
<p>
You must do the following to be able to use the <var>Printer</var> object 
found in the <file>printers.pas</file> unit:
</p>
<ul>
<li>Add the Printer4Lazarus package to your project requirements.</li>
<li>Add the Printers unit to the uses section of your unit.</li>
<li>Use the existing Printer object.</li>
</ul>
<p>
<b>Adding the Printer4Lazarus Package to a Project</b>
</p>
<p>
The Printer4Lazarus package defines a basic printer and provides platform 
independent printing. The following can thus be used on various platforms.
</p>
<p>
In the Lazarus IDE, do the following:
</p>
<ul>
<li>
In the Project menu, click Project Inspector. A window is shown with a tree 
view, one of the branches is named Required Packages. By default, the 
Required Packages branch shows the LCL package.
</li>
<li>
Click the Add button, the button with the plus sign at the top of the window.
</li>
<li>
Open the New Requirements page.
</li>
<li>
From the Package Name list box, select Printer4Lazarus.
</li>
<li>
Click OK.
</li>
</ul>
<p>
Printer4Lazarus is now shown in the Required Packages for the project.
</p>
<p>
<b>Adding the printers Unit to the uses section of your unit</b>
</p>
<p>
This step is simple and the result could look like this:
</p>

<code>
unit MainUnit;

{$mode objfpc}{$H+}

interface

uses
  Classes, SysUtils, Forms, Printers;
</code>

<p>
<b>Using the existing Printer object</b>
</p>
<p>
Let's assume you want to click a button to print a text. On your form, put a 
button called PrintBtn and in the OnClick event you can now use the following:
</p>

<code>
procedure TForm1.PrintBtnClick(Sender: TObject);
const
  LEFTMARGIN = 100;
  HEADLINE = 'I Printed My Very First Text On ';
var
  YPos, LineHeight, VerticalMargin: Integer;
  SuccessString: String;
begin
  with Printer do
  try
     BeginDoc;
     Canvas.Font.Name := 'Courier New';
     Canvas.Font.Size := 10;
     Canvas.Font.Color := clBlack;
     LineHeight := Round(1.2 * Abs(Canvas.TextHeight('I')));
     VerticalMargin := 4 * LineHeight;
     YPos := VerticalMargin;
     SuccessString := HEADLINE + DateTimeToStr(Now);
     Canvas.TextOut(LEFTMARGIN, YPos, SuccessString);
  finally
    EndDoc;
  end;
end;
</code>

<p>
While the above example seems somewhat complex, it demonstrates basic text 
output using formatting for your text. These are some the actions performed 
in the code:
</p>
<p>
Printer.BeginDoc starts the printing process. However, nothing is sent to the 
printer device until the Printer.EndDoc statement is used.
</p>
<p>
The Printer uses a Canvas to draw its output. It is this drawing that ends up 
on the printed page. Canvas.Font has the font object used to output text on 
the canvas. That is, the TextOut call we use later will output text using the 
settings of the font object of that moment.
</p>
<p>
Everything drawn on the canvas must be positioned using coordinates. So, we 
calculate a LineHeight to position text vertically. You could do the same for 
the horizontal position, which I left here to be LEFTMARGIN.
</p>
<p>
The text is drawn with the TextOut call.
</p>
<p>
This result is sent to the printer when Printer.EndDoc is executed.
</p>
<p>
In some forums it is suggested that the use of PrintDialog (the printer 
selection dialog) is required for good functioning, but I did not find this 
to be required (any more).
</p>
<p>
<b>Next Steps</b>
</p>
<p>
After the preceding basic steps, you can perform more complicated or creative 
tasks. Like:
</p>
<ul>
<li>
Draw on the page using the drawing methods in Canvas, like: Arc, Ellipse, 
FillRect, FloodFill, GradientFill, Pie, Polygon, Rectangle, Polyline, 
PolyBezier, and others.
</li>
<li>
Format text using the TextStyle for the Canvas. or Color for the canvas Font.
</li>
<li>
Select another printer and compare results.
</li>
</ul>
<p>
In the Lazarus distribution there is an example project that uses Raw 
printing to the printer. You can find this example with the following 
location 
<file>$(lazarusdir)\components\printers\samples\rawmode\rawmodetest.lpi</file>.
</p>
<p>
Another sample shows how to select another printer: 
<file>$(lazarusdir)\components\printers\samples\dialogs\selectprinter.lpi</file>.
</p>
<p>
<b>Advanced Steps: Printing Controls</b>
</p>
<p>
The printer object primarily allows you to draw on a canvas and send that 
canvas image to the printer. If we continue on the path shown above, then you 
would use the Printer canvas methods to draw text, ellipses, diamonds and 
what not.
</p>
<p>
However, this can hardly be interesting to any serious programmer. You are 
working on a more perfect CAD program or yet another image file sorter and 
want to print the wonderful result of your program to your printer. Trying to 
translate the perfect picture into canvas method calls is not the way: you 
already have the picture.
</p>
<p>
Each and every control you put on a form, also draws a picture on a TCanvas 
object just like the printer. We can use that to bring the picture from the 
screen to the printer.
</p>
<p>
Imagine you are going to make a preview program. You create a form and on 
this form you put a TPanel. This panel will provide the nice grayish 
background of the preview. On the panel, you put another TPanel object called 
page. This page will be white and represents the paper. You can nicely size 
the page.
</p>
<p>
On this page we put a TShape object, for example a nice red, rounded 
rectangle. Now try the following in the PrintBtnClick event method:
</p>

<code>
MyPrinter.BeginDoc;
page.PaintTo(myPrinter.Canvas, 0, 0);
MyPrinter.EndDoc;
</code>

<p>
What happens:
</p>
<p>
BeginDoc starts the printing (but nothing is sent yet).
</p>
<p>
page.PaintTo sends the output of our TPanel object that represents the page 
to the canvas of the printer.
</p>
<p>
Note the following:
</p>
<p>
You can use the PaintTo method found in any control in the control hierarchy. 
You could also send the output of the whole window to the printer if desired.
</p>
<p>
You can send the output of any control with a PaintTo method to the printer, 
so you can be creative. To send the output of your image sorter to the 
printer you may send the output of the TImage to the printer.
</p>
<p>
TCanvas has a method to copy rectangles from another canvas. However, you can 
only do that if an object really draws to a canvas. I think most controls 
rely on containers to provide a real canvas, so you cannot copy rectangles 
from just any control. It depends on the implementation for a specific 
control.
</p>
<p>
Make sure the control you want to paint to the printer is visible. If the 
control is not visible, nothing will be painted not even to the printer.
</p>
<p>
EndDoc sends the drawing to the printer.
</p>
<p>
<b>More Steps: Resizing</b>
</p>
<p>
The Printer uses a lot more pixels per inch on paper than the monitor uses 
pixels per inch on the screen. As a result, the output that is redirected 
from the screen to the printer ends up rather smallish on the paper. Scaling 
and controlling the layout is important for good looking output. It would be 
nice if you can have an exact sized copy of what you see on the screen.
</p>
<p>
For the moment we are not striving for the ideal, just for the idea. As said 
before, controls do not have their own canvas but rely on the canvas of a 
container or owner. However, there are components that have their own canvas. 
I chose TBitMap and then it works as follows.
</p>

<code>
procedure TForm1.PrintBtnClick(Sender: TObject);
var
  MyPrinter : TPrinter;
  myBitMap : TBitMap;
begin
    myBitMap := TBitMap.Create;
    myBitMap.Width := page.Width;
    myBitMap.Height := page.Height;
    page.BorderStyle:=bsNone;
    page.PaintTo(myBitMap.Canvas, 0, 0);
    page.BorderStyle:=bsSingle;
    //
    MyPrinter := Printer;
    MyPrinter.BeginDoc;
    //page.PaintTo(myPrinter.Canvas, 0, 0);
    //myPrinter.Canvas.Draw(0,0, myBitMap);
    myPrinter.Canvas.CopyRect(Classes.Rect(0, 0, myPrinter.PaperSize.Width, myPrinter.PaperSize.Height),
       myBitMap.Canvas, Classes.Rect(0, 0, myBitMap.Width, myBitMap.Height));
    MyPrinter.EndDoc;
    myBitMap.Free;
end;
</code>

<p>
For this to work, do not use the Windows unit. The Windows unit has other 
definitions for Rect. What you see in the example is the following:
</p>
<p>
A bitmap is created and made the same size as the page control.
</p>
<p>
To avoid the border to print, the BorderStyle of the page is switched off 
before painting it to the bitmap and set back to its old value afterwards.
</p>
<p>
Then printing is started and the BitMap canvas content is copied to the 
printer canvas.
</p>
<p>
But notice that in the process page is magnified. The Printer.papersize is 
considerably bigger than the the size of the bitmap, but the copy process 
fills the destination rectangle nicely. So, when we want to do this, we must 
make sure that the page dimensions have the same ratio as the paper 
dimension. You can figure out how to do it.
</p>
<p>
A problem with this way of working is of course that the pixels of the screen 
will show on the printed paper. As said, it is not ideal but it shows a 
principle. Controls do not have their own canvas; to print controls we first 
paint them on an object that does have its own canvas: the TBitMap. Now you 
know how it works, you can figure out a way to create fine artwork or 
documents. This will need objects that draw themselves properly in a TPanel 
with low resolution, but also on a TBitMap with high resolution. But, that is 
food for another article.
</p>
<p>
<b>Common Tasks</b>
</p>
<p>
Keep in mind that the Printer variable is a singleton. It's a single object 
that serves all printers installed in the system. A particular system 
implementation (WinAPI, Cocoa, etc) should implement the object.
</p>
<p>
<b>Enumerating Available Printers</b>
</p>
<p>
The list of system printers is available via Printer.Printers property. 
Printers property is TStrings containing the name of each printer.
</p>

<code>
procedure TForm1.FormShow(Sender: TObject);
begin
  ListBox1.Items.AddStrings(Printer.Printers);
end;
</code>

<p>
A printer name given by one of the lines in the property can be used to 
change the active printer via the SetPrinter() method.
</p>
<p>
Internals: any class implementing TPrinter class should implement 
DoEnumPrinters() method. DoEnumPrinters should populate the passed Lst 
parameters with the name of printers. It's expected that the name of the 
printer device is unique.
</p>
<p>
DoEnumPrinters() should return the system default printer as the first entry 
(index 0) in the list.
</p>
<p>
<b>Selecting or Changing the Printer</b>
</p>
<p>
By default, Printer should pre-select the "system default" printer.
</p>
<p>
When needed, the printer can be changed by the user either the PrinterDialogs 
or in program code.
To change the printer programmatically either call the SetPrinter method or 
assign a new value to the PrinterIndex property. Both methods are based on 
the printers available in the Printers property.
</p>
<p>
PrinterIndex uses the printer name found at the indicated position in 
Printers, and calls the SetPrinter method to make the printer with the given 
name the active one.
</p>

<code>
procedure TForm1.Button2Click(Sender: TObject);
begin
  Printer.SetPrinter(ListBox1.ItemIndex);
end;
</code>

<p>
If Index specified is -1 then the default printer is selected.
</p>
<p>
The SetPrinter method verifies whether the requested name exists in Printers 
property list.
</p>

<code>
procedure TForm1.Button2Click(Sender: TObject);
begin
  Printer.SetPrinter(ListBox1.GetSelectedText);
end;
</code>

<p>
Note, that there's a special name used for SetPrinter method. If name 
specified as '*' the first (default) printer available is selected.
</p>
<p>
Either of the methods can raise an exception, if specified name or index 
doesn't exist.
</p>
<p>
Internals: The TPrinter deriving class should implement DoSetPrinter() method 
using aName parameter as the name of the selected printer. The method doesn't 
need to do any special handling for '*' name, as it being take care at the 
higher level of TPrinter.
</p>

<p>
<b>Preparing Paper Size</b>
</p>
<p>
Note: if you're using multiple printer (especially if you're using 
specialized printers using non-standard paper size, such as "A4" (European) 
or "US Letter" (USA)), you always want to prepare the paper size. It is 
possible that a newly selected printer doesn't support the paper that has 
been supported by the previously selected printer. The paper size is not 
reset automatically and you want to do it explicitly.
</p>
<p>
There are three properties of PaperSize that can be called in to order to 
reset and prepare paper size:
</p>
<dl>
<dt>PaperName</dt>
<dd>
Returns currently selected paper name of the selected printer.
</dd>
<dt>DefaultPaperName</dt>
<dd>
Returns the default paper name for the selected printer.
</dd>
<dt>SupportedPapers</dt>
<dd>
Returns the list of paper sizes supported on the selected printer.
</dd>
</dl>
<p>
Here's an example of code that re-reads the list of selected papers:
</p>

<code>
procedure TForm1.ListBox1SelectionChange(Sender: TObject; User: boolean);
begin
  // printer changed. But the selected paper size might to be the right one
  Printer.PrinterIndex := ListBox1.ItemIndex;
  ListBox2.Clear;
  // calling SupportedPapers forcing validation of the paper size
  ListBox2.Items.AddStrings(Printer.PaperSize.SupportedPapers);
end;
</code>

<p>
Here's an example of resetting paper size, using default paper name property.
</p>

<code>
procedure TForm1.ListBox1SelectionChange(Sender: TObject; User: boolean);
begin
  // printer changed. But the selected paper size might to be the right one
  Printer.PrinterIndex := ListBox1.ItemIndex;
  // calling DefaultPaperName forcing validation of the paper size
  Printer.PaperSize.DefaultPaperName;
end;
</code>

<p>
Internals: A derived TPrinter class should properly implement :
</p>
<p>
<b>DoEnumPapers() method</b>
</p>
<p>
The method could use PrinterIndex or PrinterName property to determine the 
currently selected printer to which the paper sizes needs to be enumerated. 
If the internal method returns no paper sizes, TPrinter class substitutes a 
"default" paper sizes (assumed to be supported by most of printers).
</p>
<p>
Default sizes are: Letter, A4, Legal. However, a good TPrinter class 
implementation should populate the page sizes.
</p>
<p>
<b>DoGetPaperRect() method</b>
</p>
<p>
The method returns the physical size of the paper specified by the name for 
the current printer. The name of the paper is passed via aName property. The 
returned value should be populated to TPaperRect structure.
</p>
<p>
Two fields should be populated:
</p>
<dl>
<dt>
PhysicalRect
</dt>
<dd>
The actual size of the entire page. The size is given in dots. Left and Top 
are expected to be zeroes.
</dd>
<dt>
WorkRect
</dt>
<dd>
The rectangle where the printer can actually print (due to some mechanical 
limitations of the printer itself). The rectangle should always be the same 
or less than PhysicalRect. Left and Top are offsets from the top-left corner 
of the physical rect. The units are printer dots.
</dd>
</dl>
<p>
Number of dots is driven by the printer currently selected DPI. (Note that 
there are two different DPI for horizontal and vertical measurements).
</p>
<p>
Here's the table showing the difference in A4 paper size, using different DPI 
size values:
</p>
<table>
<th>
<td>DPI</td>
<td>Size returned in TPaperRect</td>
</th>
<tr>
<td>72</td>
<td>595 x 842</td>
</tr>
<tr>
<td>300</td>
<td>2480 x 3507</td>
</tr>
<tr>
<td>600</td>
<td>4960 x 7014</td>
</tr>
<tr>
<td>1200</td>
<td>9920 x 14028</td>
</tr>
</table>
<p>
<b>DoGetDefaultPaperName()</b>
</p>
<p>
The method should return the default paper size name of the currently 
selected printer.
</p>
<p>
<b>DoGetPaperName</b>
</p>
<p>
The method should return the currently selected paper size name of the 
currently selected printer.
</p>
<p>
<b>DoSetPaperName</b>
</p>
<p>
The method should set the paper size by its name for the selected printer.
</p>
</descr>
</topic>

</module>
<!-- Printers -->
</package>
</fpdoc-descriptions>