PrintOpen

Description

Opens a print job and assigns it a number, which you use in other printing statements.

Syntax

PrintOpen ( { jobname {, showprintdialog } } )

Argument

Description

jobname (optional)

A string specifying a name for the print job. The name is displayed in the Windows Print Manager dialog box and in the Spooler dialog box.

showprintdialog (optional)

A boolean value indicating whether you want to display the system Print dialog box that allows the user to select a printer or set print properties. Values are:

TRUE -- Display the dialog box

FALSE -- (default) Do not display the dialog box


Return value

Long. Returns the job number if it succeeds and -1 if an error occurs. If the Print dialog box displays and the user presses Cancel, PrintOpen returns -1. If any argument's value is null, PrintOpen returns null.

Usage

A new print job begins on a new page and the font is set to the default font for the printer. The print cursor is at the upper left corner of the print area.

If you specify true for the showprintdialog argument, the system Print dialog box displays allowing the user to cancel the print job. The option to specify a page range in the Print dialog box is disabled because PowerBuilder cannot determine the number of pages in the print job in advance. If you specify this argument in a component that runs on a server, the argument is ignored.

Use the job number that PrintOpen returns to identify this print job in all subsequent print functions.

Calling MessageBox after PrintOpen can cause undesirable behavior that is confusing to a user. Calling PrintOpen causes the currently active window in PowerBuilder to be disabled to allow Windows to handle printing. If you display a MessageBox after calling PrintOpen, Windows assigns the active window to be its parent, which is often another application, causing that application to become active.

Balancing PrintOpen and PrintClose

When you open a print job, you must close (or cancel) it. To avoid hung print jobs, process and close a print job in the same event in which you open it.

Examples

This example opens a job but does not give it a name:

ulong li_job
li_job = PrintOpen()

This example opens a job, gives it a name, and displays the Print dialog box:

ulong li_job
li_job = PrintOpen("Phone List", true)

See also

Print

PrintBitmap

PrintCancel

PrintClose

PrintDataWindow

PrintDefineFont

PrintLine

PrintOval

PrintPage

PrintRect

PrintRoundRect

PrintSend (obsolete)

PrintSetFont

PrintSetup

PrintText

PrintWidth

PrintX

PrintY