%WPR_PRINT

Perform print operation to selected printer

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows

 

 

return = %WPR_PRINT(report_handle, operation[, arguments])

Return value

return

Defined by the specified operation.

Arguments

report_handle

The report handle returned by the DWP_GETPRINTER subfunction of %WPR_INFO. See DWP_GETPRINTER. (n)

operation

One of the following printer operations: (n)

DWP_BEGINJOB = Open document for printing.

DWP_ENDJOB = Close document.

DWP_ADDFILE = Send file to current document.

DWP_BEGINPAGE = Start new page.

DWP_ENDPAGE = End current page.

DWP_WRITEOUT = Output text at specified location.

DWP_LINE = Draw a line.

DWP_FILL = Fill a region with color.

DWP_BITMAP = Output graphical image at specified location.

DWP_SETPAGES = Specify range of pages.

DWP_TRANSPARENCY = Specify transparent color.

arguments

(optional) Any arguments used by the specified operation.

Discussion

If an invalid report_handle, filename, printer name, etc., is passed, the runtime generates a trappable error. If the routine returns false or generates a trappable error such as $ERR_IOFAIL or $ERR_WNFNCERR, %SYSERR returns the status code from the last system call. (A status code of 1223 means the user canceled the print operation.) Refer to the Windows winerror.h file or check MSDN for more error codes.

DWP_BEGINJOB

DWP_BEGINJOB, [document_name][, enhanced_preview]

Opens a document for printing. Document_name is the name of the metafile to create. The metafile cannot be an xfServer remote file specification. We don’t recommend using a remote file in this situation for performance reasons, but if you must use one, it must be specified with a UNC path. If document_name is not passed, a temporary metafile is created. If the keep_file flag from %WPR_EXECUTE’s DWP_PRINT operation is passed and is true, the file is not deleted after printing.

If enhanced_preview is passed and is true, the text is output to a metafile just like any other GDI operation. This mode correctly scales fixed-pitch TrueType fonts when using the print previewer, and playing it back to a different device (the screen, for instance) scales the output along with all other GDI operations in a consistent manner. However, this enhanced preview mode creates a metafile that may be up to six times larger than when this mode is not set.

If enhanced_preview is not passed or if it is passed as false, text is not output to the metafile. Instead, a special comment record containing the text is written to the metafile, and this sets a flag on playback to output the text to the destination device using GDI commands. The difference is that the font is thereby scaled to the final device based on point size, rather than on how it fit into the original device context. Thus, if the devices are different in scale there will likely be a difference in the text size, due to rounding of the font point size. This difference is particularly noticeable in non-TrueType fonts, because they don’t scale well anyway.

In summary, passing enhanced_preview as true ensures graphical precision of the text, whereas not passing it or passing it as false saves disk space on the metafile. For more information, see Print previewer.

DWP_BEGINJOB returns true if successful. We recommend that you call DWP_BEGINJOB after you set printer properties. Once DWP_BEGINJOB is called, you can only change characteristics within a page, such as font and color.

DWP_ENDJOB

DWP_ENDJOB

Closes a document.

DWP_ENDJOB returns true if successful.

DWP_ADDFILE

DWP_ADDFILE, filename 

Sends the specified file to the current document. This subfunction starts on a new page and ends its last page. Filename cannot be an xfServer remote file specification. We don’t recommend using a remote file in this situation for performance reasons, but if you must use one, it must be specified with a UNC path.

DWP_ADDFILE returns the number of pages added.

DWP_BEGINPAGE

DWP_BEGINPAGE

Starts a new page on the current document.

DWP_BEGINPAGE returns true if successful.

DWP_ENDPAGE

DWP_ENDPAGE

Ends the current page on the current document.

DWP_ENDPAGE returns true if successful.

DWP_WRITEOUT

DWP_WRITEOUT, x, y, text

Outputs text on the current page at the specified x, y pixel coordinates.

DWP_WRITEOUT returns the X pixel coordinate where text ends.

DWP_LINE

DWP_LINE, pen_handle, startx, starty, endx, endy

Draws a line to the specified device starting at startx, starty and ending at endx, endy. The pen_handle is returned by the DWP_GETPEN subfunction of %WPR_INFO.

DWP_LINE returns true if successful.

DWP_FILL

DWP_FILL, left, top, width, height, color[, hatch]

Fills a rectangular region of a report page with a color, which can be solid or hatched. Anything (text, graphics, etc.) that’s in the fill region when %WPR_PRINT is called with DWP_FILL will be covered with this color. If text is subsequently displayed over the filled region, the DWP_BACKCOLOR setting for %WPR_SETDEVICE determines the color of the background area of each text cell.

The region for the fill is defined with the following arguments. Note that if the rectangle coordinates are outside the boundaries of the page, results will vary depending on the device.

The fill color is defined by the color argument, which must be an RGB triplet as constructed by the M_RGB macro (in DBLDIR:winprint.def):

M_RGB(red,green,blue)

If color contains a nonzero value in bit 24 or higher, results will vary depending on the device.

By default the fill is solid, but you can fill the region with a pattern by passing one of the following options as hatch. (Any other value will cause a runtime error.) The DWP_BACKCOLOR setting for %WPR_SETDEVICE determines the background for a hatch pattern.

DWPH_SOLID

Fill the entire rectangle with color.

DWPH_HORIZONTAL

Fill with horizontal hatch (----) of color.

DWPH_VERTICAL

Fill with vertical hatch (||||) of color.

DWPH_FDIAGONAL

Fill with 45-degree downward diagonal hatch (\\\\) of color.

DWPH_BDIAGONAL

Fill with 45-degree upward diagonal hatch (////) of color.

DWPH_CROSS

Fill with horizontal/vertical crosshatch (++++) of color.

DWPH_DIAGCROSS

Fill with diagonal crosshatch (XXXX) of color.

The fill will not be transparent, even if color meets the settings passed to the %WPR_PRINT subfunction DWP_TRANSPARENCY.

DWP_FILL returns true if successful.

DWP_BITMAP

DWP_BITMAP, graphic_file, [x, y], [cx, cy][, scale]

Outputs a graphical image in the specified location on the current page. The following file formats are supported:

If the specified graphic file does not exist or is not one of the supported types, no image will be output. Graphic_file cannot be an xfServer remote file specification. We don’t recommend using a remote file in this situation for performance reasons, but if you must use one, it must be specified with a UNC path.

The optional x and y coordinates designate where the image will be placed on the page. If they are not supplied, the default position is used. The optional cx and cy arguments specify the desired height and width of the image. If they are not supplied, the actual size of the image is used. If cx and cy are passed, and scale is not passed or is false, the image is clipped. If scale is passed and is true, the image is scaled to the specified cx, cy dimensions. If you specify a size for the image that is larger than the actual size, and scale is not set to true, the excess space is black by default.

If a transparent color has been defined using the SYN_TRANSPARENT_COLOR environment variable, DWP_BITMAP will recognize that color as transparent. Any pixel in the image that corresponds to the designated transparent color will remain unpainted, revealing whatever else was printed in that same location on the page instead.

DWP_BITMAP returns true if successful.

Tip

Because pixels are not universal, how an image appears is ultimately influenced by the printer driver. Thus, you may need to write a routine that sizes the image on the document, based on the pixel values returned by the driver with calls to the DWP_PIXELWIDTH and DWP_PIXELHEIGHT subfunctions of %WPR_GETDEVICE. Use those values in the routine to ensure the image is sized consistently. The routine must perform calculations to make the size fit to the desired portion of the page, with the scale arguments of DWP_BITMAP set to true. If you want to maintain the aspect ratio of the image, then scale appropriately.

Note that while most devices use the same pixel ratio horizontally and vertically, some don’t. For these exceptions, get the DWP_PAPERWIDTH and DWP_PAPERLENGTH values and do some additional calculations to compute the skew ratio.

DWP_SETPAGES

DWP_SETPAGES, npagerange, pagerange

Specifies a range of pages that can be selected for previewing and printing.

Npagerange is the number of page ranges contained in pagerange. Pagerange is an array of at least npagerange elements that contains the ranges of pages to print. Each entry in the array has the following form:

group pagerange         ,i8
  from_page             ,i4
  to_page               ,i4
endgroup

The first page submitted to the Windows printing API (via DWP_BEGINPAGE) is treated as page 1.

DWP_SETPAGES returns true if successful or false if one or more of the specified page ranges is invalid. (An invalid page range is any range containing a negative number or where the end page is less than the start page.)

DWP_TRANSPARENCY

DWP_TRANSPARENCY, transparent_color[, threshold]

Specifies a transparent color to enable you to print an image over text and have the text show through, as well as a threshold for how closely to match the transparent color. Whether rendered in the previewer or the printed page, any portion of any image that qualifies as transparent will not be printed at all.

If this subfunction is not called, color transparency settings will be set to those specified by the SYN_TRANSPARENT_COLOR and SYN_TRANSPARENCY_THRESHOLD environment variables or their corresponding default values (none and 0, respectively).

Transparent_color is a color to treat as transparent. It can be one of the following values:

DWP_TRANSPARENT_NONE (-1)

No color is treated as transparent and threshold is ignored.

DWP_TRANSPARENT_DEFAULT (-2)

The transparent color defaults to any value specified in SYN_TRANSPARENT_COLOR, and threshold is ignored, reverting to any value specified in SYN_TRANSPARENCY_THRESHOLD.

rgb

The RGB triplet for the color you want to designate as transparent. This is an integer value. Only the low-order 24 bits are considered.

Threshold is an optional value that can be added to or subtracted from each red, green, and blue component of the transparent color to constitute an acceptable transparency range. It can be one of the following values:

DWP_TRANSPARENT_NONE (-1) or 0

The transparent color must match exactly within the image. (default)

n

The threshold above or below each RGB component of the transparent color to accept as within the transparency range, where n is an integer value between 0 and 255. Only the low-order 8 bits of this value are used and treated as unsigned.

You can call this subfunction at any time for a valid report handle and the new settings will take effect for the entire report. Only one color can be designated as transparent, and the specified color will be transparent in all images that contain it; you cannot have different settings for different images in the same report.

Note that the transparency settings do not apply to the color of text (DWP_TEXTCOLOR) or its background (DWP_BACKCOLOR). Transparency only applies to images (DWP_BITMAP).

If you use ^VARARGARRAY, note that operation is the last declared argument for this routine.

Examples

See Sample programs.