Print

Sends data to the current printer (or spooler, if the user has a spooler set up). There are several syntaxes.

For syntax for DataWindows or DataStores, see the Print method for DataWindows in the section called “Print” in DataWindow Reference.

To

Use

Include a visual object, such as a window or a graph control in a print job

Syntax 1

Send one or more lines of text as part of a print job

Syntax 2

Print the contents of an RTE control

Syntax 3


Syntax 1: For printing a visual object in a print job

Description

Includes a visual object, such as a window or a graph control, in a print job that you have started with the PrintOpen function.

Applies to

Any object

Syntax

objectname.Print ( printjobnumber, x, y {, width, height } )

Argument

Description

objectname

The name of the object that you want to print. The object must either be a window or an object whose ancestor type is DragObject, which includes all the controls that you can place in a window.

printjobnumber

The number the PrintOpen function assigns to the print job.

x

An integer whose value is the x coordinate on the page of the left corner of the object, in thousandths of an inch.

y

An integer whose value is the y coordinate on the page of the left corner of the object, in thousandths of an inch.

width (optional)

An integer specifying the printed width of the object in thousandths of an inch. If omitted, PowerBuilder uses the object's original width.

height (optional)

An integer specifying the printed height of the object in thousandths of an inch. If omitted, PowerBuilder uses the object's original height.


Return value

Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument's value is null, Print returns null.

Usage

PowerBuilder manages print jobs by opening the job, sending data, and closing the job. When you use Syntax 2 or 3, you must call the PrintOpen function and the PrintClose or PrintCancel functions yourself to manage the process.

PowerBuilder copies the area of the screen occupied by the control to the printer. If any other window or application displays on the screen in that area in front of the control while the control is being printed, that window or application will also be printed.

Print area and margins

The print area is the physical page size minus any margins in the printer itself.

Examples

This example prints the CommandButton cb_close in its original size at location 500, 1000:

long Job
Job = PrintOpen( )
cb_close.Print(Job, 500,1000)
PrintClose(Job)

This example opens a print job, which defines a new page, then prints a title using the third syntax of Print. Then it uses this syntax of Print to print a graph on the first page and a window on the second page:

long Job
Job = PrintOpen( )
Print(Job, "Report of Year-to-Date Sales")
gr_sales1.Print(Job, 1000,PrintY(Job)+500, &
   6000,4500)
PrintPage(Job)
w_sales.Print(Job, 1000,500, 6000,4500)
PrintClose(Job)

See also

PrintCancel

PrintClose

PrintOpen

PrintScreen

Syntax 2: For printing text in a print job

Description

Sends one or more lines of text as part of a print job that you have opened with the PrintOpen function. You can specify tab settings before or after the text. The tab settings control the text's horizontal position on the page.

Applies to

Not object-specific

Syntax

Print ( printjobnumber, { tab1, } string {, tab2 } )

Argument

Description

printjobnumber

The number the PrintOpen function assigned to the print job.

tab1 (optional)

The position, measured from the left edge of the print area in thousandths of a inch, to which the print cursor should move before string is printed. If the print cursor is already at or beyond the position or if you omit tab1, Print starts printing at the current position of the print cursor.

string

The string you want to print. If the string includes carriage return-newline character pairs (~r~n), the string will print on multiple lines. However, the initial tab position is ignored on subsequent lines.

tab2 

(optional)

The new position, measured from the left edge of the print area in thousandths of a inch, of the print cursor after string printed. If the print cursor is already at or beyond the specified position, Print ignores tab2 and the print cursor remains at the end of the text. If you omit tab2, Print moves the print cursor to the beginning of a new line.


Return value

Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument's value is null, Print returns null.

Usage

PowerBuilder manages print jobs by opening the job, sending data, and closing the job. When you use Syntax 2 or 3, you must call the PrintOpen function and the PrintClose or PrintCancel functions yourself to manage the process.

Print cursor

In a print job, PowerBuilder uses a print cursor to keep track of the print location. The print cursor stores the coordinates of the upper-left corner of the location at which print will being. PowerBuilder updates the print cursor after printing text with Print.

Line spacing when printing text

Line spacing in PowerBuilder is proportional to character height. The default line spacing is 1.2 times the character height. When Print starts a new line, it sets the x coordinate of the cursor to 0 and increases the y coordinate by the current line spacing. You can change the line spacing with the PrintSetSpacing function, which lets you specify a new factor to be multiplied by the character height.

Because Syntax 3 of Print increments the y coordinate each time it creates a new line, it also handles page breaks automatically. When the y coordinate exceeds the page size, PowerBuilder automatically creates a new page in the print job. You do not need to call the PrintPage function, as you would if you were using the printing functions that control the cursor position (for example, PrintText or PrintLine).

Print area and margins

The print area is the physical page size minus any margins in the printer itself.

Using fonts

You can use PrintDefineFont and PrintSetFont to specify the font used by the Print function when you are printing a string.

Fonts for multiple languages

The default font for print functions is the system font, but multiple languages cannot be printed correctly using the system font. The Tahoma font typically produces good results. However, if the printer font is set to Tahoma and the Tahoma font is not installed on the printer, PowerBuilder downloads the entire font set to the printer when it encounters a multilanguage character. Use the PrintDefineFont and PrintSetFont functions to specify a font that is available on users' printers and supports multiple languages.

Examples

This example opens a print job, prints the string Appeon Corporation in the default font, and then starts a new line:

long Job
 
// Define a blank page and assign the job an ID
Job = PrintOpen( )
 
// Print the string and then start a new line
Print(Job, "Appeon Corporation")
...
PrintClose(Job)

This example opens a print job, prints the string Appeon Corporation in the default font, tabs 5 inches from the left edge of the print area but does not start a new line:

long Job
 
// Define a blank page and assign the job an ID
Job = PrintOpen( )
 
// Print the string but do not start a new line
Print(Job, "Appeon Corporation", 5000)
...
PrintClose(Job)

The first Print statement below tabs half an inch from the left edge of the print area, prints the string Appeon Corporation, and then starts a new line. The second Print statement tabs one inch from the left edge of the print area, prints the string Directors:, and then starts a new line:

long Job
// Define a blank page and assign the job an ID
Job = PrintOpen( )
// Print the string and start a new line
Print(Job, 500, "Appeon Corporation")
// Tab 1 inch from the left edge and print
Print(Job, 1000, "Directors:")
...
PrintClose(Job)

The first Print statement below tabs half an inch from the left edge of the print area prints the string Appeon Corporation, and then tabs 6 inches from the left edge of the print area but does not start a new line. The second Print statement prints the current date and then starts a new line:

long Job
// Define a blank page and assign the job an ID
Job = PrintOpen( )
// Print string and tab 6 inches from the left edge
Print(Job, 500, "Appeon Corporation", 6000)
// Print the current date on the same line
Print(Job, String(Today()))
...
PrintClose(Job)

In a window that displays a database error message in a MultiLineEdit mle_message, the following script for a Print button prints a title with the date and time and the message:

long li_prt
li_prt = PrintOpen("Database Error")
Print(li_prt, "Database error - " &
   + String(Today(), "mm/dd/yyyy") &
      + " - " &
      + String(Now(), "HH:MM:SS"))
Print(li_prt, " ")
Print(li_prt, mle_message.text)
PrintClose(li_prt)

See also

PrintCancel

PrintClose

PrintDataWindow

PrintOpen

PrintScreen

PrintSetFont

PrintSetSpacing

Syntax 3: For RichTextEdit controls

Description

Prints the contents of a RichTextEdit control.

Applies to

RichTextEdit controls

Syntax

rtename.Print ( copies, pagerange, collate, canceldialog )

Argument

Description

rtename

The name of the RichTextEdit control whose contents you want to print.

copies

An integer specifying the number of copies you want to print.

pagerange

A string describing the pages you want to print. To print all pages, specify an empty string (""). To specify a subset of pages, use dashes to specify a range and commas to separate ranges and individual page numbers, for example, "1-3" or "2,5,8-10".

When rtename shares data with a DataWindow, pagerange refers to pages based on the total number of pages in the control, not within each instance of the document.

collate

A boolean value indicating whether you want the copies collated. Values are:

TRUE -- Collate copies

FALSE -- Do not collate copies

canceldialog

A boolean value indicating whether you want to display a nonmodal dialog box that allows the user to cancel printing. Values are:

TRUE -- Display the dialog box

FALSE -- Do not display the dialog box


Return value

Integer. Returns 1 if it succeeds and -1 if an error occurs.

Usage

When the RichTextEdit control shares data with a DataWindow, the total number of pages contained in the control is the page count of the document multiplied by the row count of the DataWindow.

You can specify printed page numbers by including an input field in the header or footer of your document.

Examples

This statement prints one copy of pages 1 to 5 of the document in the RichTextEdit control rte_1. The output is not collated and a dialog box displays to allow the user to cancel the printing:

rte_1.Print(1, "1-5", FALSE, TRUE)

See also

Preview

PrintEx