From 31bb502be4b02b4c05b4cf1b47cabcd4113632d2 Mon Sep 17 00:00:00 2001 From: dsiders Date: Sat, 11 Jun 2022 00:46:23 +0100 Subject: [PATCH] Docs: LCL/printers. Removes extra spaces in topics. Fixes tagging for True and False values. --- docs/xml/lcl/printers.xml | 129 +++++++++++++++++++++++--------------- 1 file changed, 79 insertions(+), 50 deletions(-) diff --git a/docs/xml/lcl/printers.xml b/docs/xml/lcl/printers.xml index 7fd8597344..3aa9924f8f 100644 --- a/docs/xml/lcl/printers.xml +++ b/docs/xml/lcl/printers.xml @@ -138,7 +138,7 @@ TPrinterCanvas is a TCanvas descendant which implements a canvas used to position, format, and output values from a TPrinter print device. The TPrinter instance which provides the capabilities for the device is passed as an argument to the constructor, and stored in the Printer property.

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

A TPrinterCanvas (or descendant) class reference is used to implement the TPrinter.CanvasClass property. @@ -304,7 +304,7 @@ HasDefaultMargins is a Boolean function used to determine if the default values are being used in the page margin properties: LeftMargin, RightMargin, TopMargin, BottomMargin. The return value is True when each of the properties contains the value 0 (zero).

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

@@ -321,7 +321,9 @@ - True when the default values (0) are used in the page margin properties. + + True when the default values (0) are used in the page margin properties. + @@ -428,7 +430,7 @@ Performs actions needed when a new page is started.

- NewPage is procedure used to perform actions needed when a new page is started. NewPage increments the value in the PageNumber property, and calls the BeginPage method prior to exit. + NewPage is procedure used to perform actions needed when a new page is started. NewPage increments the value in the PageNumber property, and calls the BeginPage method prior to exit.

NewPage is called from the TPrinter.NewPage method. @@ -446,7 +448,7 @@ Performs actions needed when a page is started.

- BeginPage is a procedure used to perform actions needed when page is started for the canvas. + BeginPage is a procedure used to perform actions needed when a page is started for the canvas.

BeginPage is called from the TPrinter.BeginPage method. @@ -520,7 +522,7 @@ Printable area is determined by the page dimensions and values in the margin properties.

Resolution
-
Number of DPI (Dots per Inch) for the device
+
Number of DPI (Dots per Inch) for the device.

The value for the property is passed as an argument to the Create constructor. @@ -581,7 +583,7 @@ PageWidth is a read-only Integer property with the size for the printable page area on the horizontal axis of the page orientation. The value is expressed as the number of "Dots" on the device in Printer.

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

Use PageHeight to get size of the printable page on the vertical axis for the page orientation. @@ -774,11 +776,15 @@

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

The value for the property is supplied by the Printer using the canvas to render document pages (when assigned). If Printer has not been assigned, an existing value in the property is used. @@ -851,7 +857,8 @@ - TPrinterCanvasRef - class of TPrinterCanvas: referenced class. + Reference to the TPrinterCanvas class. + @@ -928,7 +935,9 @@ - Contains boundaries for the physical paper size and its available working area. + + Contains the boundaries for the physical paper size and its available working area. + @@ -940,7 +949,7 @@ - True when a TPaperItem instance is in the Item member. + True when a TPaperItem instance is in the Item member. @@ -1104,7 +1113,7 @@ GetDefaultPaperRect is an Integer function used to get a TPaperRect with the dimensions for the default paper name specified in AName. The return value contains the ordinal position in the default paper sizes defined in the class, or -1 when a default paper size with the specified name could not be located. The rectangles for the requested paper name are returned in the APaperRect parameter.

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

GetDefaultPaperRect is called from the implementation of the PaperRectOfName method. @@ -1123,12 +1132,16 @@ - Gets the ordinal position for a default paper size with the specified name. + + Gets the ordinal position for a default paper size with the specified name. + - Ordinal position in the list of default papers for the specified paper name. + + Ordinal position in the list of default papers for the specified paper name. + Paper name to locate in the method. @@ -1152,7 +1165,7 @@ Create is the overloaded constructor for the class instance.

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

Create calls the inherited constructor. @@ -1186,10 +1199,12 @@ - Indicates if default paper sizes have been defined and added to SupportedPapers. + + Indicates if default paper sizes have been defined and added to SupportedPapers. +

- DefaultPapers is set to True when internal TPaperItem entries are created for valid papers sizes and the SupportedPapers property is updated. When True, SupportedPapers will always contain entries for the "Letter", "Legal", and "A4" paper sizes. + DefaultPapers is set to True when internal TPaperItem entries are created for valid papers sizes and the SupportedPapers property is updated. When True, SupportedPapers will always contain entries for the "Letter", "Legal", and "A4" paper sizes.

@@ -1242,7 +1257,9 @@ - The default paper name used when not selected or available in the printer device. + + The default paper name used when not selected or available in the printer device. +

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 True, the first value in SupportedPapers is used as the property value. Otherwise, the default paper name for the printer device is returned. @@ -1357,7 +1374,7 @@ TPrinter provides properties and methods used to select, configure, and control the printer device. Most of the methods are declared as virtual, and can be overridden in descendent classes which implement specific features like: page description languages, networking protocols, support for graphics libraries, etc.

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

TPrinter also provides a RawMode property which indicates that output does not use formatting or a page description language, and bypasses use of the Canvas class. Think of this as "Dot Matrix Mode". @@ -1688,7 +1705,7 @@ - True if document printing was aborted rather than ended normally. + True if document printing was aborted rather than ended normally. @@ -1718,7 +1735,7 @@ DoResetPrintersList is called from the Refresh method, and occurs prior to clearing and re-populating values in the Printers property. It is also called from the DoDestroy method when the class instance is freed.

- DoResetPrintersList can be overridden in a descendent class to perform actions needed for the operating system / widgetset / printer-related technology used in the implementation. + DoResetPrintersList can be overridden in a descendent class to perform actions needed for the operating system / widgetset / printer-related technology used in the implementation. @@ -1885,7 +1902,9 @@ - Performs actions needed to set the number of copies for each printed page. + + Performs actions needed to set the number of copies for each printed page. +

DoSetCopies is a virtual procedure used to perform actions needed to set the number of copies for each page printed on the device. DoSetCopies is called when a new value is assigned to the Copies property. @@ -2003,10 +2022,12 @@ - Performs actions needed to get the name for the default bin on the selected printer. + + Performs actions needed to get the name for the default bin on the selected printer. + - In TPrinter, DoGetDefaultBinName always returns an empty string(''). It must be overridden in a descendent class to perform actions needed for the operating system / widgetset / printer-related technology used in the implementation. + In TPrinter, DoGetDefaultBinName always returns an empty string(''). It must be overridden in a descendent class to perform actions needed for the operating system / widgetset / printer-related technology used in the implementation. @@ -2016,10 +2037,12 @@ - Performs actions needed to get the current paper bin selected for the print device. + + Performs actions needed to get the current paper bin selected for the print device. + - In TPrinter, DoGetBinName always returns an empty string(''). It must be overridden in a descendent class to perform actions needed for the operating system / widgetset / printer-related technology used in the implementation. + In TPrinter, DoGetBinName always returns an empty string(''). It must be overridden in a descendent class to perform actions needed for the operating system / widgetset / printer-related technology used in the implementation. @@ -2029,7 +2052,9 @@ - Performs actions needed to set the selected paper bin for the current printer. + + Performs actions needed to set the selected paper bin for the current printer. + In TPrinter, DoSetBinName has an empty implementation. It must be overridden in a descendent class to perform actions needed for the operating system / widgetset / printer-related technology used in the implementation. @@ -2079,13 +2104,13 @@ Performs actions needed to set the dimensions for the paper. - In TPrinter, DoSetPaperRect always returns False. It must be overridden in a descendent class to perform actions needed for the operating system / widgetset / printer-related technology used in the implementation. + In TPrinter, DoSetPaperRect always returns False. It must be overridden in a descendent class to perform actions needed for the operating system / widgetset / printer-related technology used in the implementation. - True if the dimension for the paper were successfully applied. + True if the dimension for the paper were successfully applied. Rectangle with the physical dimensions for the paper. @@ -2116,7 +2141,7 @@ DoDestroy is a virtual procedure used to perform actions needed when the print device is freed. In TPrinter, the following actions are performed:

    -
  • When Printing is True, Abort is called.
    • +
  • When Printing is True, Abort is called.
  • Frees resources allocated to the internal member used for Paper Bins.
  • Frees the Canvas (when assigned).
  • Frees PaperSize (when assigned).
    • @@ -2208,9 +2233,9 @@ CheckRawMode is a procedure used to ensure that the RawMode property contains the specified Value. If RawMode does not have the requested value, an EPrinter exception is raised. Msg contains the message text for the exception. When Msg is not specified, or contains an empty string (''), a default message is used:

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

    @@ -2276,7 +2301,9 @@ - Performs actions to get the default class used for the Canvas property. + + Performs actions to get the default class used for the Canvas property. + @@ -2295,7 +2322,7 @@

    Set in Destroy.
    pfAborted
    - Set in Aborted. Removed in BeginDoc, EndDoc. Provides the value for the Aborted property. + Set in Aborted. Removed in BeginDoc, EndDoc. Provides the value for the Aborted property.
    pfPrinting
    @@ -2383,7 +2410,7 @@ Starts printing for the current document.

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

    BeginDoc calls SelectCurrentPrinterOrDefault to ensure a valid printer is selected for the class instance. If the current selection is invalid, the "default" printer is selected. The default printer is the first one in Printers. @@ -2468,9 +2495,9 @@ When it has been overridden, the following actions are performed:

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

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

    - When RawMode is False, the BeginPage method in Canvas is called to synchronize the printer canvas. + When RawMode is False, the BeginPage method in Canvas is called to synchronize the printer canvas.

    BeginPage calls the DoBeginPage method to perform any actions needed for the class implementation. @@ -2509,7 +2536,7 @@ EndPage is a procedure used to end the current page for the document.

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

    EndPage calls the DoEndPage method to perform actions needed for the class implementation. @@ -2584,7 +2611,9 @@ - True when the specified value are successfully written in the method. + + True when the specified value are successfully written in the method. + Untyped buffer written in the method. @@ -2648,7 +2677,7 @@ Name for the selected print device.

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

    Use SetPrinter to select a print device with a given name in Printers. Or, assign a new value to the PrinterIndex property. @@ -2807,7 +2836,7 @@ Class reference used to create new instances of the printer canvas.

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

    CanvasClass is used in the read access specifier for the Canvas property to create a new instance of the class reference and assign it to the Canvas member (when needed). @@ -2891,7 +2920,7 @@ - Aborted - True if printing of the document has been prematurely terminated by operator command. + True if printing of the document has been prematurely terminated by operator command.

    @@ -2911,7 +2940,7 @@ - Printing - True if document is in process of being printed. + True if the document is currently being printed.

    @@ -2962,7 +2991,7 @@ - CanPrint - True if printing is enabled or not disabled. + True if printing is enabled (or not disabled).

    @@ -2979,7 +3008,7 @@ - CanRenderCopies - True if the printer device can render copies. + True if the printer device can render copies.

    @@ -3021,7 +3050,7 @@

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

    In TPrinter, the value for the property is always 1. The read access specifier (GetYDPI) must be overridden in a descendent class to get the property value using the facilities available in the operating system / widgetset / printer-related technology for the implementation. @@ -3095,7 +3124,7 @@ Names for the Paper Bins supported on the print device.

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

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