Printer Function Summary
PowerBASIC provides a large number of commands with which to control printing. Most are part of the XPRINT family of commands (XPRINT ATTACH, XPRINT CLOSE, ..., etc.).

The commands can be broken into the following categories. Note that all of these commands are preceded by XPrint (except for Printer$, PrinterCount, XPrint, and XPrint$).

Printing Text
In general, printing under PowerBASIC requires three steps.

  1. Select a Printer
    The XPrint Attach statement is used to pick a printer. The printer can be selected from a dialog, the default printer can be used, or the program can declare the name of the printer explicitly. The following code shows all three. 

        XPrint Attach Default       'uses default printer
    XPrint Attach Choose        'open printer select dialog
    XPrint Attach PrinterName$  'explicitly select a printer

  2. Send text to printer
    To send text to the attached printer, simply use the XPrint statement, as shown in these examples. 

       XPrint "hello"    'print text and move print position to next line
   XPrint "hello";   'print text and do not move print position

  3. Detach Printer
    Anything printed by the XPrint statement is saved in a buffer and is not sent to the printer until an XPrint Close statement is executed. The next example shows a complete printing session. 

        XPrint Attach Default    'use the default printer
    XPrint "hello"           'print one line of text
    XPrint "goodbye"         'print a second line of text
    XPrint Close             'send content to printer

In PowerBASIC, when the printer is detached, all buffer content is sent to the printer

Fonts
The font and font properties used for printing may be controlled by an application. In general, the Font New command is used to create one or more fonts. Each is given a handle. Then, the Set Font statement can be used to select from any of the available handles. 

    Font New - create a font
    XPrint Set Font - select a font 
    XPrint Text Size - get height/width of text string
    XPrint Chr Size - get height/width of a single character

Font New is used to define a font and its properties. It also gives the font a handle.

XPrint Set Font can select any font created by Font New. The selected font will be used

XPrint Text Size and XPrint Chr Size return string and character size (height/width) information for the selected font.

Printer Job Control
To print on a new page, use the XPrint FormFeed statement.

To cancel print statement not yet released to the printer, use the XPrint Cancel statement. Content released to the printer cannot be stopped by PowerBASIC. 

    XPrint FormFeed    'printing starts at 0,0 on new page
    Xprint Cancel      'cancel all buffered printing statements

Printing Graphics (Drawing Primitives)
PowerBASIC provides tools to create graphics. Both drawing primitives and bitmap images may be sent to the selected printer.

There are seven primitives - arc, box, ellipse, line, pie, polygon, and polyline. Setting of individual pixels is also supported.

The primitives can be roughly categorized by the way in which they use page coordinates for defining where a drawing takes place.

Examples of all the drawing functions are included in the reference table at the bottom of this page.

Graphics Properties
When drawing the primitives discussed in the previous section there are several properties which can be set to adjust how the drawing looks. 

    XPRINT SCALE - define custom coordinate system
    XPRINT GET SCALE - get scale settings
    XPRINT SCALE PIXELS - Reset coordinate system to default
    XPRINT STYLE - Set line style
    XPRINT WIDTH - Set line width

XPrint Scale allows defining the upper/left and lower/right coordinates of the printable area of the selected printer.

XPrint Scale Pixel resets the coordinate system to pixels, returning from the custom coordinates set by XPrint Scale.

XPrint Style selects from 0-solid, 1-dash, 2-dot, 3-dashdot and 4-dashdotdot for drawing lines and borders of primitives.

XPrint Width set the line width in pixels (regardless of XPrint Scale settings). Default is 1 pixel. If set greater than 1, style 0-solid is always used.

Examples of all the drawing functions are included in the reference table at the bottom of this page.

Pixels, Pixels, Pixels
In addition to drawing primitives, PowerBASIC can work at the pixel level - setting the pixel color at a specific location. 

XPrint Color - sets default fg/bg colors
XPrint Set Pixel - set pixel color at x,y
XPrint Get Pixel - get pixel color at x,y
XPrint Set POS

XPrint Color can set the foreground color, which XPrint Set Pixel uses as a default color.

XPrint Set Color sets the color at x,y. Uses default foreground color if a color is not explicitly specified. If a STEP option is invoke, the x,y dimension are relative to POS.

XPrint Get Pixel support depends on the printer driver's ability to provide the information. If not supported, -1 is returned.

XPrint Set POS changes the default position, which XPrint Set Color uses if invoked with the STEP option.

Printing Images
PowerBASIC supports several methods of printing images onto a page, a shown in the next listing. 

    XPrint Copy - send bitmap to printer (all or partial)
    XPrint ImageList - print image from ImageList (all)
    XPrint Stretch - copy/resize bitmap (all or partial, with resize)
    XPrint Render - print image (all, with resize)

With Copy, ImageList and Stretch, a preloaded image from a control, window, bitmap structure or imagelist structure is used. Using preloaded images significantly speeds up image display operations, especially animated displays.

With Render, an image from a resource file or disk file is used.

Two of the functions, Stretch and Render can resize the image.

Two of the functions, Copy and Stretch, can be used to print only a portion of the original image.

The Printer
In addition to selecting a printer when using the XPrint command, there are three other statements useful in managing the selection of a printer for attachment. 

    Printer$ - get printer names, one at a time
    PrinterCount - get quantity of installed printers
    XPrint$ - get name of attached printer

Printercount tells how many printers are available. Printer$ takes a number from 1 to PrinterCount and returns the name of the printer. XPrint$ returns the name of the currently attached printer.

Also, PowerBASIC also enables a programmer to get or set various properties (over 18) of the attached printer. The specific functions were listed in the table at the top of the page. Examples of each are provided in the reference table at the bottom of this page.

Printing Commands - One Line Descriptions
All of these commands apply to attached host printers. The use of line printer commands is discouraged and the commands are not shown here.

Line Printers
PowerBASIC also supports line printers, where printing content is sent directly to a port, rather than through a Windows device driver. See the PowerBASIC Help file for more information on the LPRINT family of functions which provides this capability. Using printers which connect through Windows printer drivers is recommended for the greater capabilities they offer. The line printer family of commands (LPRINT) are not covered in this tutorial.

Function Reference
Here's a quick reference of the available array functions, in alphabetical order.

If you have any suggestions or corrections, please let me know.