Perform print operation to selected printer
|
WSupported on Windows
|
|
|
NSupported in Synergy .NET
|
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.
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, [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
Closes a document.
DWP_ENDJOB returns true if successful.
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
Starts a new page on the current document.
DWP_BEGINPAGE returns true if successful.
DWP_ENDPAGE
Ends the current page on the current document.
DWP_ENDPAGE returns true if successful.
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, 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, 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.
- left, the leftmost x-axis pixel coordinate
- top, the topmost y-axis pixel coordinate
- width, the width, in pixels, of the region
- height, the height, in pixels, of the region
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, 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:
- BMP – Windows bitmap format
- GIF – Graphics Interchange Format
- JPEG – Joint Photographic Experts Group, stored in JFIF (JPEG File Interchange Format)
- Exif – Exchangeable image file
- PNG – Portable Network Graphics
- TIFF – Tag Image File Format
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.
|
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, 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, 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.
