Printer class

A Printer object encapsulates one Windows printer device, exposing a drawing surface that records the application’s graphics calls and forwards them to the spooler as a print job. The implicit Printer is mutable and tracks the system default printer; the entries of the Printers collection are read-only descriptors of the installed devices, useful for enumeration or for switching the active printer with Set Printer = Printers("HP LaserJet").

A print job begins implicitly the first time the application calls a drawing or text method on the Printer (Print, Line, Circle, PSet, PaintPicture, …), and is finalised by EndDoc. NewPage advances to a fresh page within the same job; KillDoc aborts the job without finishing the current page.

Printer.FontSize = 12
Printer.Print "Hello, world!"
Printer.NewPage
Printer.Print "Second page."
Printer.EndDoc

User code never instantiates a Printer directly — the class is marked [COMCreatable(False)] and its public API has no useful constructor. The two access paths are the implicit Printer global and the Printers collection.

The default Printer and the Printers collection
Print-job lifecycle
Coordinate system
Printing to a file
Properties
Methods
See Also

The default Printer and the Printers collection

twinBASIC exposes a single implicit Printer object, accessible by name from anywhere in user code, plus a Printers collection enumerating every printer installed on the system:

Dim p As Printer
For Each p In Printers
    Debug.Print p.DeviceName, p.DriverName, p.Port
Next

By default the implicit Printer has TrackDefault True: every property read consults the current system-default printer, so the application reflects changes the user makes in Settings → Printers without restarting. Writing to a settings property, calling Set Printer = Printers(i), or starting a print job locks TrackDefault to False and pins the object to a specific device.

The entries returned by Printers are immutable — assigning to one of their properties raises run-time error 383 (Property is read-only), and the document-control methods raise error 438 (Object doesn’t support this property or method). To print to one of them, copy it onto the implicit Printer with Set:

Set Printer = Printers("HP LaserJet")
Printer.Orientation = vbPRORLandscape
Printer.Print "Hello on landscape paper."
Printer.EndDoc

Set Printer = … does not replace the implicit instance — it forwards the new device’s identity onto the existing object, ending any active print job and discarding the cached device context in the process.

Print-job lifecycle

The methods that manage the job — EndDoc, KillDoc, NewPage — and the implicit “start-on-first-output” rule together form a small state machine:

State	How it advances
No job in progress	The next drawing or text method starts a new job and a fresh page.
Page in progress	NewPage emits the page and starts another; EndDoc emits it and finishes.
Anywhere	KillDoc aborts the job without emitting whatever is on the current page.

Page reports the current page number (starting at 1). Property setters that affect page geometry — PaperSize, Orientation, Copies, Width, Height, Duplex, PaperBin, ColorMode, PrintQuality, Zoom — must be assigned on a blank page; doing so mid-page raises error 396 (‘PropertyName’ cannot be set within a page).

Coordinate system

A Printer has its own coordinate system, configured through ScaleMode, the Scale* properties, and Scale. The default mode is vbTwips, with the surface spanning the physical paper area. Drawing primitives consume coordinates in the current units; ScaleX and ScaleY convert distances between any two scale modes without changing the active one.

Printer.ScaleMode = vbInches
Printer.Line (0.5, 0.5)-(8, 10.5), vbBlack, B   ' 1/2-inch margin rectangle

Printing to a file

Assigning a path to OutputFile before the job starts redirects the raw spool output to that file instead of the printer device. The file holds the printer-driver-specific bytes that would otherwise be sent over the port — typically a .prn file that can later be copied to a port with the COPY /B command.

Printer.OutputFile = "C:\Spool\report.prn"
Printer.Print "Captured to file"
Printer.EndDoc

Properties

ColorMode

Whether the printer should print in colour or monochrome.

Syntax: object.ColorMode [ = value ]

value: A member of PrinterObjectConstants_ColorMode: vbPRCMMonochrome (1) or vbPRCMColor (2). Other values raise error 380.

Copies

The number of copies to print. Integer. The maximum value supported by the driver is checked through the device-capabilities API: values greater than the maximum raise error 380, and a driver that does not advertise a maximum raises error 483 (Printer driver does not support specified property).

CurrentX

The horizontal pen position used by Print, Line, Circle, and PSet when they omit a starting coordinate. Double, in the current ScaleMode units. Updated automatically by each drawing call.

CurrentY

The vertical pen position. Double. See CurrentX.

DeviceName

The friendly name of the bound printer, as it appears in the Windows printer dialog. String, read-only. While TrackDefault is True, this returns the current default printer rather than a cached value.

DrawMode

The raster operation applied when drawing-method output is combined with the page. A member of DrawModeConstants, default vbCopyPen (opaque overwrite). Re-applied automatically after a printer change.

DrawStyle

The pen pattern used by line-drawing methods. A member of DrawStyleConstants: vbSolid (0, default), vbDash, vbDot, vbDashDot, vbDashDotDot, vbInvisible, or vbInsideSolid. Solid is forced when DrawWidth is greater than 1.

DrawWidth

The pen thickness, in pixels, used by Line, Circle, and PSet. Long, default 1.

DriverName

The name of the device driver that handles the bound printer. String, read-only. While TrackDefault is True, this returns the current default printer’s driver.

Duplex

Whether the printer should print on one or both sides of the paper.

Syntax: object.Duplex [ = value ]

value: A member of PrinterObjectConstants_Duplex: vbPRDPSimplex (1), vbPRDPHorizontal (2), or vbPRDPVertical (3). Values that exceed the driver’s reported duplex capability raise error 380. Simplex is always accepted, even when the driver does not advertise duplex support.

FillColor

The colour used to fill closed shapes drawn by Line (with the F flag) and Circle, as an OLE_COLOR. Default 0 (black). Honoured only when FillStyle is not vbFSTransparent.

FillStyle

The pattern used to fill closed shapes. A member of FillStyleConstants: vbFSTransparent (1, default), vbFSSolid (0), or one of the hatched styles. Transparent suppresses fill entirely, so only the outline is drawn.

Font

The StdFont used to render Print output and measured by TextWidth / TextHeight. The convenience properties FontName, FontSize, FontBold, FontItalic, FontStrikethru, FontUnderline, and FontTransparent read or write members of this object. Assigning a string to Font is a shortcut for assigning to Font.Name; assigning an StdFont with Set replaces the underlying font object.

On a printer obtained from Printers, Font can still be read (a fresh, mutable StdFont is returned), but reassigning it raises error 383.

FontBold

Shortcut for Font.Bold. Boolean.

FontCount

The number of typefaces installed on the printer. Long, read-only. Used together with Fonts to enumerate them.

FontItalic

Shortcut for Font.Italic. Boolean.

FontName

Shortcut for Font.Name. String.

Fonts

Indexed access to the names of the typefaces installed on the printer.

Syntax: object.Fonts( Index ) As String

Index: required A zero-based Long in the range 0 .. FontCount - 1. Out-of-range indices return an empty string rather than raising an error.

FontStrikethru

Shortcut for Font.Strikethrough. Boolean.

FontTransparent

When True (default), text drawn by Print leaves the background pixels untouched between glyphs; when False, the glyphs’ background is filled with the printer’s drawn background colour. Boolean.

FontUnderline

Shortcut for Font.Underline. Boolean.

ForeColor

The colour used by the drawing-method pen (lines, circles, points) and by Print text. OLE_COLOR.

hDC

The Win32 device-context handle for the printer’s drawing surface, as a LongPtr. Read-only.

Reading hDC the first time creates the device context — calling the driver’s CreateDC and preparing the surface for drawing — but does not start the spool job. The spooler is engaged only when the first drawing call runs, so reading hDC for, say, a GetDeviceCaps query is non-committal: nothing is printed if the application never calls a drawing method afterwards.

Height

The physical page height, in twips. Long. Assigning a value overrides the driver’s reported paper height and forces PaperSize to a custom size; the new value can be read back through Height itself.

Orientation

The page orientation.

Syntax: object.Orientation [ = value ]

value: A member of PrinterObjectConstants_Orientation: vbPRORPortrait (1) or vbPRORLandscape (2). Assigning landscape on a driver that does not advertise the DC_ORIENTATION capability raises error 380; portrait is always accepted.

OutputFile

The path of a file to capture the raw spooled bytes into, instead of sending them to the printer device. String. New in twinBASIC. Must be set before the first drawing call; assigning while a job is active has no effect on the running job. Read-only on a printer obtained from Printers.

Page

The page currently being composed, starting at 1 when the job begins. Long, read-only. Reset to 1 by EndDoc and KillDoc; incremented by NewPage.

PaperBin

The paper source the printer should pull from.

Syntax: object.PaperBin [ = value ]

value: A member of PrinterObjectConstants_PaperBin — for example vbPRBNUpper, vbPRBNManual, vbPRBNCassette. The value must be one of the bins the driver enumerates through DC_BINS; an unsupported value raises error 380.

PaperSize

The paper size to print on.

Syntax: object.PaperSize [ = value ]

value: A member of PrinterObjectConstants_PaperSize — for example vbPRPSLetter, vbPRPSA4, vbPRPSEnv10. Assigning to Width or Height forces this property to vbPRPSUser (256).

Port

The name of the port that connects to the printer (e.g. LPT1:, USB001, IP_192.168.1.50). String, read-only. While TrackDefault is True, this returns the current default printer’s port.

PrintQuality

The print resolution.

Syntax: object.PrintQuality [ = value ]

value: An Integer — either a positive DPI value supported by the driver, or a member of PrinterObjectConstants_PrintQuality: vbPRPQDraft (-1), vbPRPQLow (-2), vbPRPQMedium (-3), or vbPRPQHigh (-4). Zero, or values below -4, raise error 380.

RightToLeft

Note

Reserved for compatibility with VB6; not currently implemented in twinBASIC.

ScaleHeight

The vertical extent of the printer’s drawing surface in ScaleMode units. Double. Assigning a value switches ScaleMode to vbUser and rescales the vertical axis so the page maps to the new height.

ScaleLeft

The X coordinate that maps to the left edge of the printable area. Double, default 0. Assigning a value switches ScaleMode to vbUser.

ScaleMode

The unit used by CurrentX, CurrentY, and every drawing method. A member of ScaleModeConstants: vbUser (0), vbTwips (1, default), vbPoints, vbPixels, vbCharacters, vbInches, vbMillimeters, or vbCentimeters. Switching away from vbUser resets ScaleLeft and ScaleTop to 0.

ScaleTop

The Y coordinate that maps to the top edge of the printable area. Double, default 0. Assigning a value switches ScaleMode to vbUser.

ScaleWidth

The horizontal extent of the printer’s drawing surface in ScaleMode units. Double. Assigning a value switches ScaleMode to vbUser.

TrackDefault

When True, every property read consults the current system-default printer; when False, the Printer is locked to the specific device identified by DeviceName, DriverName, and Port. Boolean.

Setting TrackDefault to False captures the current default device into the cached identifiers so subsequent reads stop drifting. Setting it back to True finishes any active print job (as if EndDoc had been called) and clears the cached device context. Always False on a printer obtained from Printers, and read-only there.

TwipsPerPixelX

The number of twips that correspond to one device pixel, horizontally — useful for custom DPI-aware sizing. Double, read-only.

TwipsPerPixelY

The vertical counterpart of TwipsPerPixelX. Double, read-only.

Width

The physical page width, in twips. Long. Assigning a value overrides the driver’s reported paper width and forces PaperSize to a custom size; the new value can be read back through Width itself.

Zoom

The print-scaling percentage applied by the driver. Integer, default 100. Values greater than 100 enlarge the output; values less than 100 shrink it. Zero and negative values raise error 380.

Methods

Circle

Draws a circle, ellipse, or elliptical arc on the current page.

Syntax: object.Circle [ Step ] ( X, Y ), Radius [, Color [, Start [, End [, Aspect ] ] ] ]

X, Y: required Coordinates of the centre in ScaleMode units. Single. Step makes them relative to CurrentX / CurrentY.
Radius: required The radius along the X axis. Single.
Color: optional An OLE_COLOR for the outline. Defaults to ForeColor.
Start, End: optional Start and end angles in radians (0 to 2π). Negative values connect the arc end-point to the centre with a chord. Omitted draws a full circle.
Aspect: optional The Y/X aspect ratio. 1.0 for a circle (default); other values give an ellipse.

If no job is in progress, Circle implicitly starts one.

EndDoc

Finalises the current print job, sending whatever is on the current page to the spooler and releasing the underlying GDI document. Has no effect when no job is in progress.

Syntax: object.EndDoc

KillDoc

Aborts the current print job, discarding any in-progress page output. Releases the device context immediately, without further interaction with the spooler beyond an AbortDoc call.

Syntax: object.KillDoc

Line

Draws a straight line, a rectangle outline, or a filled rectangle.

Syntax: object.Line [ [ Step ] ( X1, Y1 ) ] - [ Step ] ( X2, Y2 ) [, Color [, B [F] ] ]

X1, Y1: optional Start coordinates. Single. If omitted, the line starts at CurrentX / CurrentY. Step makes them relative to the pen.
X2, Y2: required End coordinates. Single. Step makes them relative to the start point.
Color: optional An OLE_COLOR for the line. Defaults to ForeColor.
B: optional Draws a rectangle whose opposite corners are (X1, Y1) and (X2, Y2) instead of a line.
F: optional Only valid with B. Fills the rectangle with FillColor at the current FillStyle.

If no job is in progress, Line implicitly starts one.

NewPage

Emits the current page to the spooler and begins a new blank page. Page is incremented; CurrentX and CurrentY are reset to 0. If no job is in progress, NewPage implicitly starts one before emitting the first page break.

Syntax: object.NewPage

PaintPicture

Draws a picture onto the current page, optionally scaling, clipping, or applying a raster operation.

Syntax: object.PaintPicture Picture, X1, Y1 [, Width1 [, Height1 [, X2 [, Y2 [, Width2 [, Height2 [, Opcode ] ] ] ] ] ] ]

Picture: required An IPictureDisp to paint.
X1, Y1: required Destination top-left in ScaleMode units.
Width1, Height1: optional Destination size. Defaults to the picture’s natural size.
X2, Y2, Width2, Height2: optional Source rectangle within Picture. Defaults to the whole picture.
Opcode: optional A raster-operation code passed through to BitBlt — for example &HCC0020 (vbSrcCopy, default) or &H660046 (vbSrcInvert).

If no job is in progress, PaintPicture implicitly starts one.

Print

Writes text to the current page using Font, starting at CurrentX / CurrentY and advancing them as it goes. Dispatched through the Print statement so multiple expressions can be separated by ; (no spacing) or , (tab to next print zone). Spc(n) inserts n spaces and Tab(n) moves to print column n.

Syntax: object.Print [ expressionlist ] [ ; | , ]

A trailing ; or , suppresses the newline so the next Print call continues on the same line. If no job is in progress, Print implicitly starts one.

PSet

Sets a single pixel on the current page.

Syntax: object.PSet [ Step ] ( X, Y ) [, Color ]

X, Y: required Coordinates in ScaleMode units. Single. Step makes them relative to CurrentX / CurrentY.
Color: optional An OLE_COLOR. Defaults to ForeColor.

If no job is in progress, PSet implicitly starts one.

Scale

Defines a user coordinate system for the page. Calling Scale with no arguments resets ScaleMode to vbTwips and clears ScaleLeft / ScaleTop.

Syntax: object.Scale [ ( X1, Y1 ) - ( X2, Y2 ) ]

X1, Y1: required (with the second pair) The coordinate that maps to the top-left corner — sets ScaleLeft and ScaleTop.
X2, Y2: required The coordinate that maps to the bottom-right corner — sets ScaleWidth = X2 - X1 and ScaleHeight = Y2 - Y1. ScaleMode becomes vbUser.

Calling Scale with coordinates implicitly starts a print job (matching VB6 behaviour); calling it without arguments does not.

ScaleX

Converts a horizontal distance from one scale mode to another, without changing the printer’s ScaleMode.

Syntax: object.ScaleX( Width, FromScale [, ToScale ] ) As Double

Width: required The value to convert. Double.
FromScale: required A ScaleModeConstants member identifying the unit of Width. Unlike on a PictureBox or Form, this argument has no default on a Printer — omitting it raises error 448 (Named argument not found).
ToScale: optional A ScaleModeConstants member identifying the unit of the result; defaults to the printer’s current ScaleMode.

ScaleY

The vertical counterpart of ScaleX, for heights.

Syntax: object.ScaleY( Height, FromScale [, ToScale ] ) As Double

TextHeight

Measures the height of the given string when rendered in the current Font, in ScaleMode units — including the line-spacing leading, so the result is suitable for advancing CurrentY between rows of text. Embedded line breaks are honoured.

Syntax: object.TextHeight( Str As String ) As Double

TextWidth

Measures the width of the given string when rendered in the current Font, in ScaleMode units. Returns the longest line width when Str contains embedded line breaks.

Syntax: object.TextWidth( Str As String ) As Double