Application Techniques
General Techniques

PowerScript provides predefined functions that you can use to generate simple and complex lists and reports. Using only three functions, you can create a tabular report in your printer's default font. Using additional functions, you can create a report with multiple text fonts, character sizes, and styles, as well as lines and pictures.

The following table lists the functions for printing.

For more information about printing functions, see the PowerScript Reference.

All printing is defined in terms of the print area. The print area is the physical page size less any margins. For example, if the page size is 8.5 inches by 11 inches, and the top, bottom, and side margins are all a half-inch, the print area is 7.5 inches by 10 inches.

Measurements

All measurements in the print area are in thousandths of an inch. For example, if the print area is 7.5 inches by 10 inches, then:

The upper-left corner is 0,0

The upper-right corner is 7500,0

The lower-left corner is 0,10000

The lower-right corner is 7500,10000

Print cursor

When printing, 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 printing begins. PowerBuilder updates the print cursor (including tab position if required) after each print operation except PrintBitmap, PrintLine, PrintRectangle, or PrintRoundRect. To position text, objects, lines, and pictures when you are creating complex reports, specify the cursor position as part of each print function call.

PrintOpen must be the first function call in every print job. The PrintOpen function defines a new blank page in memory, specifies that all printing be done in the printer's default font, and returns an integer. The integer is the print job number that is used to identify the job in all other function calls.

PrintOpen is followed by calls to one or more other printing functions, and then the job is ended with a PrintClose (or PrintCancel) call. The functions you call between the PrintOpen call and the PrintClose call can be simple print functions that print a string with or without tabs, or more complex functions that add lines and objects to the report or even include a picture in the report.

Here is a simple print request:

Int PrintJobNumber
// Start the print job and set PrintJobNumber to
// the integer returned by PrintOpen.
PrintJobNumber = PrintOpen()
// Print the string Atlanta.
Print(PrintJobNumber,"Atlanta")
// Close the job.
PrintClose(PrintJobNumber)

The Print function has several formats. The format shown in the previous example prints a string starting at the left edge of the print area and then prints a new line. In other formats of the Print function, you can use tabbing to specify the print cursor position before or after printing, or both.

Specifying tab values

Tab values are specified in thousandths of an inch and are relative to the left edge of the print area. If a tab value precedes the string in the Print call and no tab value follows the string, PowerBuilder tabs, prints, then starts a new line. If a tab value follows the string, PowerBuilder tabs after printing and does not start a new line; it waits for the next statement.

In these examples, Job is the integer print job number.

This statement tabs one inch from the left edge of the print area, prints Atlanta, and starts a new line:

Print(Job,1000,"Atlanta")

This statement prints Boston at the current print position, tabs three inches from the left edge of the print area, and waits for the next statement:

Print(Job,"Boston",3000)

This statement tabs one inch from the edge of the print area, prints Boston, tabs three inches from the left edge of the print area, and waits for the next statement:

Print(Job,1000,"Boston",3000)

Tabbing and the print cursor

When PowerBuilder tabs, it sets the x coordinate of the print cursor to a larger print cursor value (a specified value or the current cursor position). Therefore, if the specified value is less than the current x coordinate of the print cursor, the cursor does not move.

The first Print statement shown below tabs one inch from the left edge of the print area and prints Appeon, but it does not move to the next tab. (0.5 inches from the left edge of the print area is less than the current cursor position.) Since a tab was specified as the last argument, the first Print statement does not start a new line even though the tab was ignored. The next Print statement prints Inc. immediately after the n in Appeon (Appeon Inc.) and then starts a new line:

Print(Job,1000,"Appeon",500)
Print(Job," Inc.")

There are two ways to stop a print job. The normal way is to close the job by calling the PrintClose function at the end of the print job. The other way is to cancel the job by calling PrintCancel.

Using PrintClose

PrintClose sends the current page to the printer or spooler, closes the print job, and activates the window from which the printing started. After you execute a PrintClose function call, any function calls that refer to the job number fail.

Using PrintCancel

PrintCancel ends the print job and deletes any output that has not been printed. The PrintCancel function provides a way for the user to cancel printing before the process is complete. A common way to use PrintCancel is to define a global variable and then check the variable periodically while processing the print job.

Assume StopPrint is a boolean global variable. The following statements check the StopPrint global variable and cancel the job when the value of StopPrint is TRUE:

IntJobNbr
JobNbr = PrintOpen()
//Set the initial value of the global variable.
StopPrint = FALSE
//Perform some print processing.
Do While ...
.
.
.
// Test the global variable.
// Cancel the print job if the variable is TRUE.
// Stop executing the script.
      If StopPrint then
      PrintCancel(JobNbr)
      Return
      End If
Loop

Creating complex reports in PowerBuilder requires the use of additional functions but is relatively easy. You can use PowerScript functions to define fonts for a job, specify fonts and line spacing, place objects on a page, and specify exactly where you want the text or object to be placed.

Defining and setting fonts

The examples so far have used the default font for the printer. However, you can define as many as eight fonts for each print job and then switch among them during the job.

In addition, you can redefine the fonts as often as you want during the print job. This allows you to use as many fonts as you have available on your printer during a print job. Since there is a slight performance penalty for redefining fonts, you should define the fonts after the PrintOpen call and leave them unchanged for the duration of the print job.

To define a font, set an integer variable to the value returned by a call to the PrintDefineFont function and then use the PrintSetFont function to change the font in the job.

Example

Assume that JobNum is the integer print job number and that the current printer has a font named Helv. The following statements define Helv18BU as the Helv font, 18 point bold and underlined. The definition is stored as font 2 for JobNum. The company name is printed in font 2:

IntJob, Helv18BU
JobNum = PrintOpen()
Helv18BU = PrintDefineFont(JobNum,2,"Helv",250,700, &
      Variable!,Swiss!,FALSE,TRUE)
PrintSetFont(JobNum,2)
Print(JobNum,"Appeon, Inc.")

For more information about PrintDefineFont and PrintSetFont, see the section called “PrintDefineFont” in PowerScript Reference and the section called “PrintSetFont” in PowerScript Reference.

Setting line spacing

PowerBuilder takes care of line spacing automatically when you use the Print function. For example, after you print in an 18-point font and start a new line, PowerBuilder adds 1.2 times the character height to the Y coordinate of the print cursor.

The spacing factor 1.2 is not fixed. You can use the PrintSetSpacing function to control the amount of space between lines.

Examples

This statement results in tight single-line spacing. (Depending on the font and the printer, the bottoms of the lowest characters may touch the tops of the tallest characters):

PrintSetSpacing(JobNum,1)

This statement causes one-and-a-half-line spacing:

PrintSetSpacing(JobNum,1.5)

This statement causes double spacing:

PrintSetSpacing(JobNum,2)

Printing drawing objects

You can use the following drawing objects in a print job.

When you place drawing objects in a print job, place the objects first and then add the text. For example, you should draw a rectangle inside the print area and then add lines and text inside the rectangle. Although the objects appear as outlines, they are actually filled (contain white space); if you place an object over text or another object, it hides the text or object.

Be careful: PowerBuilder does not check to make sure that you have placed all the text and objects within the print area. PowerBuilder simply does not print anything that is outside the print area.

Example

These statements draw a 1-inch by 3-inch rectangle and then print the company address in the rectangle. The rectangle is at the top of the page and centered:

IntJob
JobNum = PrintOpen()
PrintRect(JobNum,2500,0,3000,1000,40)
Print(JobNum,2525,"")
 
Print(JobNum,2525,"25 Mountain Road")
Print(JobNum,2525,"Milton, MA 02186")
PrintClose(JobNum)