class printer

superclass(es) object
subclass(es) -
description The printer class is used to control printing of documents, the class has the methods to start, abort and end printing of a document.
see also printerCanvas - printerSetupDialog - printJobDialog - canvas

tasks

Before an instance of the printer class can be used it must have been used for a printer setup dialog or a print job dialog, the correct driver, port and printer name are then set (if the dialogs are closed by pressing on the "OK" button).

To start printing the method startDoc/4 can be used, to finish the printing of a document use endDoc/1, to abort printing of a document the method abortDoc/1 must be used. Printing a document is like painting on a canvas, the subclass printerCanvas  of canvas must be used for this. The class printerCanvas extends the interface of the class canvas with several methods to scale the output.
After the printing of a document was started each page must be started with a call to startPage/1 and ended with a call to endPage/1. After each call to startPage/1 an internal counter is incremented that stores the page number of the current page, the value of this page counter can be retrieved by pageCounter/1.

There are three callbacks to which can responded, the onEndDoc/1 event is executed if printing a document has finished, if printing is aborted the callback onAbortDoc/1 is executed. During printing a dialog is displayed that lets the user press a button to abort printing, if a dialog different than the default "print abort" dialog must be displayed then a handler for the onShowPrintAbortDialog/1 event must be registered. This event is executed after printing has started.

methods

executePrintJobDialog(Parent, Dialog)

func Use the supplied print job dialog and the printer instance to show the standard print job dialog.
pre The variable Parent must refer to an instance of the window class, this window will become the parent window for the dialog. The Dialog variable must refer to an instance of the class printJobDialog.
post The print job dialog was shown and if the "OK" button was pressed the data about the printer and the print job were assigned to the printer instance. After this the printer instance can be used to start printing of a document.

executePrintJobDialog(Parent)

func Create a new print job dialog and show it, the printer instance for which the method is called is used to store the print job settings.
pre The variable Parent must refer to an instance of the window class, this window will become the parent window for the dialog.
post A print job dialog was shown and if the "OK" button was pressed the data about the printer and the print job were assigned to the printer instance. After this the printer instance can be used to start printing of a document.

executePrinterSetupDialog(Parent, Dialog)

func Use the supplied printer setup dialog and the printer instance to show the standard printer setup dialog.
pre The variable Parent must refer to an instance of the window class, this window will become the parent window for the dialog. The Dialog variable must refer to an instance of the class printerSetupDialog.
post The printer setup job dialog was shown and if the "OK" button was pressed the data about the printer and the print job were assigned to the printer instance. After this the printer instance can be used to start printing of a document.

executePrinterSetupDialog(Parent)

func Create a new printer setup dialog, the printer instance for which the method is called is used to store the printer setup settings.
pre The variable Parent must refer to an instance of the window class, this window will become the parent window for the dialog.
post A printer setup job dialog was shown and if the "OK" button was pressed the data about the printer and the print job were assigned to the printer instance. After this the printer instance can be used to start printing of a document.

putDriverName(Name)

func Set the name of the driver to use for printing.
pre The variable Name must contain a string value.
post The name of the driver was stored.

driverName(Name)

func Get the name of the driver to use for printing.
pre TRUE
post The name of the driver was assigned to the variable Name.

putPrinterName(Name)

func Set the name of the printing to use for printing.
pre The variable Name must contain a string value.
post The name of the printer was stored.

printerName(Name)

func Get the name of the printer to use for printing.
pre TRUE
post The name of the printer was assigned to the variable Name.

putPortName(Name)

func Set the name of the port to use for printing.
pre The variable Name must contain a string value.
post The name of the port was stored.

portName(Name)

func Get the name of the port to use for printing.
pre TRUE
post The name of the port was assigned to the variable Name.

canvas(Output)

func Get the printercanvas instance used for drawing.
pre TRUE
post The printer canvas instance was assigned to the variable Output, if there was no printer canvas instance then no value was assigned to Output.

startDoc(PrinterCanvas, Name, File, Output)

func Start printing a document, the printer canvas to use must be supplied. The name of the printjob must also be set, the name of the print job will be visible in the "abort printing" dialog. If the output of the printing process must be send to a file then the parameter File must not be an empty string.
pre The variable PrinterCanvas must refer to an instance of the class printerCanvas, the variables Name and File must contain string values. File may be an empty string, for instance:
startDoc(PCanvas, 'Name of print-job', '', Output).
post The boolean value true was assigned to the variable Output if starting the printing process was successful, else was false assigned.

startPage(Output)

func Start printing a new page.
pre The method startDoc/4 must have been called successfully.
post The boolean value true was assigned to the variable Output if starting a new page was successful, else was false assigned.

endPage(Output)

func Finish printing of a page.
pre The method startPage/1 must have been called successfully.
post The boolean value true was assigned to the variable Output if finishing the printing of a page was successful, else was false assigned.

endDoc(Output)

func Finish printing of a document.
pre The method startDoc/4 must have been called successfully.
post The boolean value true was assigned to the variable Output if finishing the printing of a page was successful, else was false assigned.

abortDoc(Output)

func Abort printing of a document, the print job will be canceled.
pre The method startDoc/4 must have been called successfully.
post If aborting printing was successful then true was assigned to Output, else was false assigned.

aborted(Output)

func Determine if printing was aborted or not.
pre TRUE
post If printing was aborted then true was assigned to Output, else was false assigned.

pageCounter(Output)

func Return the count of the current page, the first page has count 1.
pre TRUE
post The current value of the counter was assigned to the variable Output.

lastError(Output)

func Return the last error code generated.
pre TRUE
post The last error code detected was assigned to the variable Output.

putLastError(Error)

func Set the last error code.
pre The variable Error must contain an integer value.
post The value of the variable Error was stored as the last error code.

callbacks

onEndDoc(Sender)

func This event is executed if printing a document was successfully finished.
pre The Sender argument refers to the printer instance that has printed the document.
post TRUE

onAbortDoc(Sender)

func This event is executed if printing a document was aborted.
pre The Sender argument refers to the printer instance that has aborted printing.
post TRUE

onShowPrintAbortDialog(Sender)

func This event is executed if a dialog must be shown that will allow the user to abort printing. If there is no handler for this event the default "print abort" dialog is shown.
pre The Sender argument refers to the printer instance that is printing a document.
post TRUE