:Revision=4
:html
<<
128.142
Printer-Object|Printer
$nosort
--
The IP-Object <!RW>Printer enables the Low-Level-Access to the printer. The printers should be registered in the Windows-System as 'Generic-Text' or similar and are associated in the basic setup to a printer numbers. The charcaters are transferred during the output directly to the printer.

<hr width=30% align=left>
<h4>Extension Revision 2: Output redirection</h4>
Instead of the name of an installe printer, some other targets can be specified in the basic setup:

<!SW><b>(DEFAULT)</b> will redirect the output to the default printer

<b><!SW>(FILE)Filename</b> will redirect the data into the specified file. the filename may use a <a href="128.115.205">path template</a>.

<b><!SW>(FILE)LPT1, <!SW>(FILE)LPT2</b> ... redirect the output to the specified printer port

<b><!SW>(FILE)COM1, <!SW>(FILE)COM2</b> ... redirect the output to the specified serial port


<hr width=30% align=left>
<h4>Extension Revision 3: Print jobs</h4>
The object <!RW>Printer supports now a kind of high-level access. It is possible to define any page layout, even including different font, images and graphical objects. This works only with real printers, not with the redirect ones.

Routines for page-wise printing are to be found in <a href="128.142.3">Printer.Job</a>

>>

<<
128.142.1
Functions of the Printer-Object|Functions
--
>>
<<
128.142.1.1
Printer.Exists|Exists
--
<!DEF>
function <!TW>Printer.Exists (rPrinterNr : real) : real;
<!TXT>
Returns <!RW>TRUE, if the printer <!PW>rPrinterNr exists in the system.
>>
<<
128.142.1.2
Printer.Name|Name
--
<!DEF>
function <!TW>Printer.Name (rPrinterNr : real) : string;
<!TXT>
Returns the name of the printer <!PW>rPrinterNr.
>>
<<
128.142.1.2
Printer.IsActive|IsActive
--
<!DEF>
function <!TW>Printer.IsActive : real;
<!TXT>
Returns <!RW>TRUE, if "<!RW>Printer" is activated globally.


<!DEF>
function <!TW>Printer.IsActive (rPrinterNr : real) :real;
<!TXT>
Returns <!RW>TRUE, if the Printer is globally activated and the Printer <!PW>rPrinterNr is also active.
>>

<<
128.142.1.3
Printer.Error|Error
!128.142.4
--
<!DEF>
function <!TW>Printer.Error (rPrinterNr : real) : real;
<!TXT>
Returns the error code of the last print operation on printer <!PW>rPrinterNr.
>>


<<
128.142.2
Procedures of the Printer-Object|Procedures
--
>>

<<
128.142.2.1
Printer.Print|Print
!128.142.2.2
--
<!DEF>
procedure <!TW>Printer.Print (rPrinterNr : real; .Value : string|real|vector [; ... ]);
<!TXT>
Consecutive output of values to printer <!PW>rPrinterNr. The <!PW>Value can be <!RW>Real, <!RW>String or <!RW>Vector. Between the values there is a space.
>>

<<
128.142.2.2
Printer.Print|PrintLn
!128.142.2.1
--
<!DEF>
procedure <!TW>Printer.PrintLn (rPrinterNr : real; .Value : string|real|vector [; ... ]);
<!TXT>
As <!RW>Printer.Print, however CR LF (#13#10) is appended automatically.
>>

<<
128.142.3
Printer.Job
--

The sub object <!RW>Printer.Job provides routines, to define any kind of page layout and print it on an installed wimndows printer.

Documents may consist of any combination of text, images, graphical objects and lines.

The unit for the output is always millimeter, regardless of the resolution of the output device. 

Documents are handed over to the windows system as print jobs. A job is started with <!RW>Printer.Job.Start and will show up in the print queue of the selected printer. Now the elements of the page are defined and  <!RW>Printer.Job.Print starts the printout.

A print job can be canceled with <!RW>Printer.Job.Abort. Only one print job can be active at a time. Unfinished jobs are canceled at the end of a test, on every reset and on the program end.

Example:
<!CODE>
Printer.Job.Start (1, 'Printer-Demo');
Printer.Job.SetFont (12, 'Arial', 'BU');
Printer.Job.Lebel (10, 10, 'Hello World!');
Printer.Job.Print;
<!TXT>
>>

<<
128.142.3.1
Printer.Job.Start|Start
--
<!DEF>
procedure <!TW>Printer.Job.Start (rPrinterNr : real [; sTitle : string [; sOptions : string]]);
<!TXT>
Starts a new print job on the printer <!PW>rPrinterNr.

This printer MUST be a Windows-printer - not a file redirection or a LPT or COM port.

An already existing, but unfinished print job will be canceled

If <!PW>sTitle is specified, this name is used as title in the print queue, otherwise a dummy title is generated.

 <!PW>sOptions allows to make additional settings for the print job. 
 <!PW>sOptions consists of parts, separated by <tt>';'</tt>, that have the structure: <tt>'Option=Value'</tt>.
The following options and values are allowed:
<!STBL>
<!+>Option<!+>Value<!>
<!c>PAPERWIDTH<!>Width of the page in mm<br>Sets PAPERSIZE to 0<!>
<!c>PAPERLENGTH<!>Length of the page in mm<br>Sets PAPERSIZE to 0<!>
<!c>ORIENTATION<!>Orientation<br>1 = Portrait<br>2 = Landscape<!>
<!c>PAPERSIZE<!>Page format<br>
 00 = free format
 01 = Letter 8.12 x 11 inch
 02 = Letter Small 8.12 x 11 inch
 03 = Tabloid 11 x 17 inch
 04 = Ledger 17 x 11 inch
 05 = Legal 8.12 x 14 inch
 06 = Statement 5.12 x 8 12 inch
 07 = Executive 7.14 x 10 12 inch
 08 = A3 297 x 420 mm
 09 = A4 210 x 297 mm
 10 = A4 Small 210 x 297 mm
 11 = A5 148 x 210 mm
 12 = B4 (JIS) 250 x 354
 13 = B5 (JIS) 182 x 257 mm
 and some...<!>
<!c>SCALE<!>Scaling factor in %, 100% = normal, 50%=half size...<!>
<!c>COPIES<!>Number of copies<!>
<!c>PRINTQUALITY<!>Quality<br>1 = Draft<br>2 = Low<br>3 = Medium (normal)<br>4 = High (best)<!>
<!c>COLOR<!>Color<br>1 = monochrome<br>2 = color<!>
<!c>DUPLEX<!>Duplex print<br>1 = only one side<br>2 = vertical<br>3 = horizontal<!>
<!c>TTOPTION<!>True-Type-Option<br>1 = print as graphic<br>2 = load as softfont<br>3 = replace by device font<br>4 = load as Outline Softfont<!>
<!ETBL>

If and how this options have any effect depends on the printer and the printer driver.
>>

<<
128.142.3.2
Printer.Job.Abort|Abort
--
<!DEF>
procedure <!TW>Printer.Job.Abort;
<!TXT>
Cancels the active print job.

If no print job is active, only an errorcode is set.
>>

<<
128.142.3.3
Printer.Job.Print|Print
--
<!DEF>
procedure <!TW>Printer.Job.Print;
<!TXT>
Finishes the active print job and starts the print out.
After this command, no actiove print job exists.

If no print job is active, only an errorcode is set.
>>

<<
128.142.3.4
Printer.Job.Error|Error
!128.142.4
--
<!DEF>
function <!TW>Printer.Job.Error : real;
<!TXT>
Returns the errorcode of the last <!RW>Print.Job operation.
>>

<<
128.142.4
Error codes
--
<h4>Printer error codes</h4>
<!STBL>
<!+>Code<!+>Meaning<!>
<!c>0<!>no error<!>
<!c>1<!>Port (LPT or COM) is not accessible<!>
<!c>2<!>Unable to set timeout of the port<!>
<!c>3<!>Unable to open file<!>
<!c>4<!>Can't sent the text (timeout?)<!>
<!c>5<!>Exception<!>
<!c>6<!>Printer is not active<!>
<!c>7<!>Can't access the windows printer<!>
<!ETBL>


<h4>Printer.Job error codes</h4>
<!STBL>
<!+>Code<!+>Meaning<!>
<!c>0<!>no error<!>
<!c>101<!>Print.Job can't print into a file<!>
<!c>102<!>Printer is unknown<!>
<!c>103<!>No active print job<!>
<!c>104<!>File not found<!>
<!ETBL>
>>

<<
128.142.3.5
Printer.Job.Label|Label
!128.142.3.11
!128.142.3.10
--
<!DEF>
procedure <!TW>Printer.Job.Label (rX, rY : real; sText : string [; rWidth, rAlign : real]);
<!TXT>
Displays the string <!PW>sText at the position <!PW>rX|<!PW>rY (in mm, left upper corner) in the print job.

The orientation can be controlled with <!PW>rWidth and <!PW>rAlign.

<!STBL>
<!+>rAlign<!+>Alignment<!>
<!c>0<!>left justified (default), <!PW>rWidth is not used<!>
<!c>1<!>centered in a <!PW>rWidth mm wide area<!>
<!c>2<!>right justified in a <!PW>rWidth mm wide area<br><!REM>(the last character will end at <!PW>rX+<!PW>rWidth)<!TXT><!>
<!ETBL>
>>

<<
128.142.3.6
Printer.Job.Frame|Frame
!128.154.9
!128.142.3.9
--
<!DEF>
procedure <!TW>Printer.Job.Frame (rX, rY, rW, rH, rStyle, rColor : real);
<!TXT>
Displays a graphical object at the position <!PW>rX|<!PW>rY (in mm, left upper corner) in the print job.

The width and height of the object are defined by <!PW>rW and <!PW>rH (in mm).

<!PW>rStyle select the shape of the object:
<!STBL>
<!+>rStyle<!+>Shape<!>
<!c>0<!>Rectangle<!>
<!c>1<!>Square<!>
<!c>2<!>rounded Rectangle<!>
<!c>3<!>rounded Squara<!>
<!c>4<!>Ellipse<!>
<!c>5<!>Circle<!>
<!ETBL>

The color of the border is defined with <!RW>Printer.Job.Line.Setup.

The fill-color is selected by <!PW>rColor:
<!STBL>
<!+>rColor<!+>Meaning<!>
<!c>-2<!>transparent, not filled<!>
<!c>-1<!>same as the border<!>
<!c>0..15<!>DOS - Farbcode<!>
<!c>16..$FFFFFF<!>RGB Farb Trippel<!>
<!ETBL>
>>

<<
128.142.3.7
Printer.Job.Bitmap|Bitmap
!128.115.205
--
<!DEF>
procedure <!TW>Printer.Job.Bitmap (rX, rY : real; sFile : string [; rW : real]);
<!TXT>
Displays the bitmap in the given in <!PW>sFile in the print job at the position  <!PW>rX|<!PW>rY (in mm, left upper Ecke). The width is specified with <!PW>rW (in mm). The height is calculated proportionally.
 If <!PW>rW is not specified, the bitmap will be printed with the printer resolution, which may yield some unwanted results.

The file may of BMP or JPG format and <!PW>sFile may use a path template.
>>

<<
128.142.3.8
Printer.Job.Line|Line
!128.142.3.9
--
<!DEF>
procedure <!TW>Printer.Job.Line (rX1, rY1, rX2, rY2 : real);
<!TXT>
Displays a line from the coordinates <!PW>rX1|<!PW>rY1 to the coordinates  <!PW>rX2|<!PW>rY2 (all in mm) in the print job.

The style of the line is defined with <!RW>Printer.Job.Line.Setup.
>>

<<
128.142.3.9
Printer.Job.Line.Setup|Line.Setup
!128.142.3.8
!128.142.3.6
--
<!DEF>
procedure <!TW>Printer.Job.Line.Setup (rWidth, rColor, rStyle : real);
<!TXT>
Defines the style of the line display as line in the <!RW>Printer.Job.Line command and as border line in the <!RW>Printer.Job.Frame command.

 <!PW>rWidth specifies the width of the line
<!STBL>
<!+>rWidth<!+>Function<!>
<!c>-1<!>one pixel of the device<!>
<!c>0<!>Hairline - finest line the device can produce<br><!REM>may look different than <!PW>rWidth=-1<!TXT><!>
<!c>&gt;0<!>Width of the line in mm<!>
<!ETBL>
>>

<<
128.142.3.10
Printer.Job.SetFont|SetFont
!128.142.3.5
--
<!DEF>
procedure <!TW>Printer.Job.SetFont (rSize : real [; sName : string [; sStyle : string [; rAngle : real]]]);
<!TXT>
Defines the style of the font used by <!RW>Printer.Job.Label.

 <!PW>rSize specifies the type size. Unit is <!SW>Point (1 Point = 1/72 Inch = ca. 0.35 mm). If <!PW>rSize=-1, the type size will not be changed.

 <!PW>sName is the name of the windows font. If <!PW>sName='', the font will not be changed.

 <!PW>sStyle defines the style of the characters. The following characters can be used in the string:

<!STBL>
<!+>Character<!+>Function<!+>Example<!>
<!c>-<!>no change (must be used alone)<!c><font size=-2 color=#707070>(no change)</font><!>
<!c><font size=-2 color=#707070>(empty string)</font><!TXT><!>default style<!c>Example<!>
<!c>B<!>Bold<!c><b>Example</b><!>
<!c>U<!>Underlined<!c><u>Example</u><!>
<!c>I<!>Italic<!c><i>Example</i><!>
<!c>S<!>StrikeOut<!c><s>Example</s><!>
<!ETBL>

The characters in <!PW>sStyle can be combined:
<!STBL>
<!+>Characters<!+>Example<!>
<!c>BU<!c><b><u>Example</u></b><!>
<!c>IU<!c><i><u>Example</u></i><!>
<!c>BI<!c><b><i>Example</i></b><!>
<!c>BIUS<!c><b><u><i><s>Example</s></i></u></b><!>
<!ETBL>

 <!PW>rAngle defines the rotation of the text in degrees counter clockwise. Allowed range: 0..359. An angle of -1 does not change the rotation. Pivot is the upper left point of a rectangle around the text. Only True-Type-Fonts can be rotated.
>>
<<
128.142.3.11
Printer.Job.SetColor|SetColor
!128.154.9
!128.142.3.5
--
<!DEF>
procedure <!TW>Printer.Job.SetColor (rColor : real);
<!TXT>
Defines the color of the text displayed by <!RW>Printer.Job.Label.

 <!PW>rColor may be a DOS-color code or a RGB triplet.
>>


