PRINTER Object +
Updated: Sep 6, 2007

The PRINTER Object provides graphic printing of text, font control and drawing
methods for document design and images.

To create and print a document, use (1) .BeginDoc (for the default printer and
settings), (2) methods to draw text or graphics and (3) .EndDoc to start the
print job.  Optionally, the document may be divided into pages with .NewPage
and .EndPage.

Related printing components include LPRINT for text only (please see
Statements) and the PRINTDIALOG and PAGEDIALOG objects (please see DIALOGS).

The PRINTER object also supports all Read/Write PRINTDIALOG "integer variables"
in the PRINTDIALOG Object (please see PRINTDIALOG in DIALOGS).  These include
.Copies, .DC (device context), .DevMode, .DevNames, .Flags, .FromPage,
.MaxPage, .MinPage and .ToPage.


PROPERTIES (Read/Write):
~~~~~~~~~~ ~~~~~~~~~~~~~
Copies     Sets number of copies to print.  PRINTER.copies = nCopies

           Use .Copies before .BeginDoc and/or .Dialog.  After, the .Copies
           numeric function provides feedback as described below.

           Gets number of copies to print.

           Some printers support multiple-copy printing.  After use of .Dialog
           or .BeginDoc, a .Copies value greater than one indicates the printer
           does not support multiple-copy printing and the application will
           need to generate the requested copies.

Title      Sets print job title.  PRINTER.Title = "Hot Top Secret"
           Gets title of print job.  MyJob$ = PRINTER.Title


PROPERTIES (Read Only Numeric):
~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~
DC         The device context handle of the printer, defined 
           after .Dialog or .BeginDoc.  MyPrtDC = PRINTER.DC

Execute    Display dialog box and return True/False and results in the
           object properties

JobID      Print job identifier returned by .BeginDoc.

           MyPrtJob = PRINTER.JobID

           .JobID may be used as an argument in API calls to identify
           the print job.

TextHeight Height in pixels of text string argument.

           MyHeight = PRINTER.TextHeight(MyString$)

TextWidth  Width in pixels of text string argument.

           MyWidth = PRINTER.TextWidth(MyString$)

  Note:  .TextHeight and .TextWidth may help an application determine if text
  will "fit" at a location on the page when .TextOut is used.  The values
  returned take into account the current .Font of the PRINTER document and the
  text string.  MyString$ above may be a string variable or expression.
  

METHODS    Arguments & Comments
~~~~~~~    ~~~~~~~~~~~~~~~~~~~~
Abort      Aborts print job.  PRINTER.Abort

BeginDoc   Starts new print job.  PRINTER.BeginDoc

           If the .Dialog method is not used, .BeginDoc uses the
           default printer and settings.

BeginPage  Starts new page in document.  PRINTER.BeginPage

Circle     Draws circle of radius r centered at x, y with specified color.

           PRINTER.Circle x, y, r, rgb_color

CopyRect   Copies source RECT (r1) of a BITMAP object (bmp1) to a destination
           RECT (r2).  PRINTER.CopyRect(r2,bmp1,r1)

           If image dimensions defined by RECT r1 <> RECT r2, then the copied
           image should be stretched or compressed to "fit" r2.  How .CopyRect
           copies the bitmap data is determined by source BITMAP bmp1.Mode.

Dialog     Displays a print dialog box to select printer device and settings
           before .BeginDoc.  PRINTER.Dialog

Draw       Draws BITMAP object at x, y position

           PRINTER.Draw 10,10,MyBitmap  'draw at PRINTER position 10, 10  

           The drawn rectangle of MyBitmap is determined by its properties. 

Ellipse    Draws ellipse (or circle) with the specified color.

           PRINTER.Ellipse x1, y1, x2, y2, rgb_color

EndDoc     Marks document end and starts print job.  PRINTER.EndDoc

EndPage    Marks end of page in document.  PRINTER.EndPage

FillCircle Draws circle of radius r centered at x, y filled with color.

           PRINTER.FillCircle x, y, r, rgb_color

FillEllipse 
           Draws ellipse (or circle) filled with the specified color.

           PRINTER.FillEllipse x1, y1, x2, y2, rgb_color

FillRect   Draws rectangle (or square) filled with the specified color.

           PRINTER.FillRect x1, y1, x2, y2, rgb_color

Font       Sets font for subsequent text output.  PRINTER.Font = MyFont1

           .Font may be changed during document creation.

Line       Draws line from x1, y1 to x2, y2 with rgb color.

           PRINTER.Line x1, y1, x2, y2, rgb_color

NewPage    Starts new page in document.  Same as .BeginPage

           For one page documents, .NewPage or .EndPage may be omitted,
           but may be required by W9x systems.

Paint      Fills region with rgb_border color containing x, y with rgb_fill.

           PRINTER.Paint x, y, rgb_fill, rgb_border 

Pixel      Draws pixel; same as Pset.  PRINTER.Pixel(x,y)=rgb_color

Pset       Draws pixel at x, y with color.  PRINTER.Pset(x,y)=rgb_color

Rectangle  Draws rectangle (or square) with the specified color.

           PRINTER.Rectangle x1, y1, x2, y2, rgb_color

TextOut    Draws text string at x, y with text and background colors.

           PRINTER.TextOut x, y, "HotBasic Artist", text_color, bk_color

           After .Abort, .BeginDoc, .Dialog, .EndDoc, .NewPage, .EndPage,
           applications may check for errors.  E.g.,

           PRINTER.BeginDoc
           IF RETFUNC <= 0 THEN Goto PrinterError  'no default printer defined


###########
hotprint.bas in HotThing and PrintDev.bas show coding examples.


+ PentHouse (registered) version

Copyright 2004-2005 James J Keene PhD
Original Publication: July 4, 2004