Set and retrieve extended device capabilities
|
WTSupported in traditional Synergy on Windows
|
WNSupported in Synergy .NET on Windows
|
|
|
return = %WPR_INFO(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 the Discussion below. (D_HANDLE)
operation
One of the following printer operations: (n)
DWP_PRINTDLG = Pop up printer selection dialog
DWP_GETPRINTER = Allocate and return report handle
DWP_DELPRINTER = Delete report handle
DWP_GETFILENAME = Get filename for report handle
DWP_GETPEN = Create pen or brush for drawing lines
DWP_DELPEN = Delete pen or brush
DWP_X_FROM_COL = Return X pixel coordinate for a column
DWP_Y_FROM_ROW = Return Y pixel coordinate for a row
DWP_TEXTWIDTH = Return average character width
DWP_TEXTHEIGHT = Return row height
DWP_LARGESTFONT = Return largest point size available
DWP_TEXTMETRICS = Return basic font information
DWP_GETSTATUS = Return printer status
arguments
(optional) Any arguments used by the specified operation.
If an invalid report_handle is passed, the runtime generates a trappable error. If a Win32 function fails, the DWP_ subfunction returns false and %SYSERR returns the status code from the last system call. Refer to the Windows winerror.h file or check MSDN for the error codes.
Limitations of %WPR_INFO
When using the DWP_X_FROM_COL and DWP_Y_FROM_ROW or the DWP_TEXTWIDTH and DWP_TEXTHEIGHT subfunctions to compute the distance between characters, the returned values are usually correct but may have small inaccuracies in some cases:
- The Microsoft Platform SDK warns that certain devices kern characters, which means the width of a string may not equal the sum of the widths of each of the characters.
- Some devices report incorrect information for fonts that are not device independent and scalable. Usually the fonts are reported as being slightly smaller than they are, but we have also seen reports that the fonts are larger.
- If you do not pass the enhanced_preview flag to the DWP_BEGINJOB subfunction of %WPR_PRINT, no intercharacter spacing information is preserved in the metafile. Instead, the natural spacing for that font in the given device is used. This mostly affects the spacing of characters in the previewer, but we have observed cases where the printed output can be affected as well. This phenomenon primarily applies to fonts that are not device independent and scalable.
Given the above information, if you must position text and graphics (for example, lines) close to one another, use the following guidelines:
- Use only device-independent, scalable fonts, such as TrueType or OpenType. A number of TrueType fixed-pitch fonts are available (Courier New, Lucida Console, Arial Monospaced, and so forth), as well as many proportional fonts.
- Pass the enhancement flag to DWP_BEGINJOB. Doing so significantly increases the size of the metafile, but it also ensures the best scaling of fonts.
- If any text lies to the right of a line or other graphic, position that text independently. Don’t rely on a given number of spaces (or other characters) to push the text far enough (or not too far) to the right.
- If possible, add a couple of extra pixels into the equation. For instance, if you are drawing a line between each row of text, use the text height plus the pen width for the row size.
- Draw lines and graphics last. When text is output, it can overwrite the entire rectangle for the characters, so lines that intersect that rectangle are erased.
DWP_PRINTDLG[, dialog_specs]
Pops up a printer selection dialog box that enables the user to select many of the features described under %WPR_GETDEVICE and specifies information about the dialog. You must call DWP_GETPRINTER before DWP_PRINTDLG.
Dialog_specs is the structure provided below. This structure is defined in DBLDIR:winprint.def. If dialog_specs is not passed, all structure elements are treated as 0, with the following exceptions:
- flags. The DWP_PRINTDLG_COLLATE flag is set or cleared based on the previous setting for the print job as specified by %WPR_SETDEVICE(DWP_COLLATE), or the default for the device if not previously specified. All other flags are treated as not set.
- copies. The copies field defaults to the previous setting for the print job as specified by %WPR_SETDEVICE(DWP_COPIES), or 1 if not previously specified.
structure dialog_specs ;Structure of Print dialog info
flags ,i4 ;Flags to control dialog behavior:
;DWP_PRINTDLG_STYLEPRINT, use "Print" dialog instead of "Print Setup"
;And one or more of the following if DWP_PRINTDLG_STYLEPRINT is used:
; DWP_PRINTDLG_SHOWTOFILE, show and enable "Print to file” check box
; DWP_PRINTDLG_TOFILE, check "Print to file” check box
; DWP_PRINTDLG_DISABLECURPAGE, disable “Current page” radio button
; DWP_PRINTDLG_DISABLEPAGENUMS, disable “Pages” radio button and edit control
; DWP_PRINTDLG_DISABLESELECT, disable "Selection" radio
; control button and edit control
; DWP_PRINTDLG_COLLATE, check "Collate" check box
; DWP_PRINTDLG_APPPAGE, application processes all page selections
pages ,i4 ;Type of page selection to print. May be one of the following:
; DWP_PRINTDLG_ALLPAGES, all pages (default)
; DWP_PRINTDLG_CURRENT, current page
; DWP_PRINTDLG_PAGES, page range(s)
; DWP_PRINTDLG_SELECTION, selection
npagerange ,i4 ;Number of page ranges
group pagerange ,[256] i8 ;Page ranges
from_page ,i4 ;Beginning of a page range
to_page ,i4 ;End of a page range
endgroup
copies ,i4 ;Number of copies
dialog_filler ,a64 ;Reserved for future use
DWP_PRINTDLG returns one of the following values:
|
DWP_PRINTDLG_CANCEL |
The user either clicked Cancel or closed the dialog box. |
|
DWP_PRINTDLG_PRINT |
The user clicked OK (or Print if using DWP_PRINTDLG_STYLEPRINT) in the dialog box. |
|
DWP_PRINTDLG_APPLY |
The user clicked Apply, then Cancel in the dialog box. |
All fields in the dialog_specs structure are both passed and returned. The values in flags can be combined using .BOR. to combine the desired behaviors.
|
To use the DWP_PRINTDLG_STYLEPRINT flag in Synergy .NET, include the [STAThread] attribute above the Main method. |
If DWP_PRINTDLG_APPPAGE is specified, it is the responsibility of the calling application to submit only the pages requested in this case or to programmatically specify the ranges of pages to print. (See DWP_SETPAGES for information about programmatically setting a range of pages.) If DWP_PRINTDLG_APPPAGE is not specified, and the user selects “All” or “Pages” in the Print dialog, the application must print the entire report, and the Synergy Windows printing API automatically prints only the requested pages, both in the previewer and when printing.
|
|
DWP_PRINTDLG_APPPAGE is normally only used if an application’s logical page numbers do not correspond to physical page numbers. For instance, if physical page 1 is a title page, then logical page 1 may be physical page 2, and so forth. In this type of scenario, DWP_PRINTDLG_APPPAGE would be used when DWP_PRINTDLG is called immediately after DWP_GETPRINTER, so the application knows which pages to generate. In most cases, this flag is not used at all. |
If the user selects “Current page” or “Selection,” it is the responsibility of the calling application to print only the pages specified, or to programmatically specify the range of pages, regardless of whether or not DWP_PRINTDLG_APPPAGE is specified.
Pages can be one of the following values:
|
If pages is |
The selected radio button is |
|---|---|
|
DWP_PRINTDLG_ALLPAGES |
All |
|
DWP_PRINTDLG_CURRENT |
Current page |
|
DWP_PRINTDLG_PAGES |
Pages |
|
DWP_PRINTDLG_SELECTION |
Selection |
The reverse of this table is true for the value returned in pages; if the user selects the All radio button, DWP_PRINTDLG_ALLPAGES is returned in pages, and so forth.
When passed, the entries in the pagerange array, up to npagerange, are used to populate the Pages field in the dialog. Upon return, if the user entered or left a value in the Pages field, the specified ranges are returned in the pagerange array, and npagerange is returned with the number of those ranges. A maximum of 256 independent page ranges can be entered.
If the user entered a number into the Number of copies spin edit control, that number is returned in copies, even though your application is not expected to handle copies or collation. The Synergy Windows printing API will print the specified number of copies when the DWP_PRINT subfunction of %WPR_EXECUTE is called.
DWP_GETPRINTER[, device_name]
Allocates and returns a report handle (in both the return value and the report_handle argument) that you can pass to subsequent %WPR_ functions. DWP_GETPRINTER must be called before any other %WPR_ function. The device_name is the name of the printer. If device_name is not passed, it is set to the Windows default printer. If there is no default printer and device_name is not passed, 0 is returned and %SYSERR returns 4104.
DWP_DELPRINTER[, keep_file]
Deletes this report handle and all associated objects created with DWP_GETPRINTER. If DWP_DELPRINTER is not called, the objects are released during runtime shutdown. If keep_file is true, the metafile will not be deleted by this subfunction. If keep_file is false, the metafile will be deleted, regardless of any previously specified argument passed to the DWP_PRINT subfunction of %WPR_EXECUTE. If keep_file is not specified, any previously specified keep_file argument on the DWP_PRINT subfunction of %WPR_EXECUTE will apply. If that argument wasn’t specified, the metafile will be deleted.
DWP_DELPRINTER returns true if the operation is successful.
DWP_GETFILENAME, filename
Retrieves the metafile name that corresponds to the passed report handle and returns it in filename. If document_name was passed in %WPR_PRINT’s DWP_BEGINJOB call, this name is returned. If document_name was not passed, the temporary filename is returned.
DWP_GETFILENAME returns true if successful.
DWP_GETPEN[, pen_specs]
Create a pen or brush for drawing lines. DWP_GETPEN without the optional structure returns a DWP_GEOMETRIC pen one pixel wide. To create thicker pens or brushes, pass pen_specs, which is the structure provided below. This structure is defined in DBLDIR:winprint.def.
|
|
Any memory handle created for the pen_specs structure must be initialized with DM_NULL. See winprt1.dbl (distributed in the dbl\examples directory) for an example. |
structure pen_specs
pen_style ,i4 ;Pen style
; DWP_GEOMETRIC creates a pen with extended
; attributes
; DWP_COSMETIC creates a single-pixel pen
line_style ,i4 ;Line Style -- can contain any combination of
; DWP_ALTERNATE, every other pixel (cosmetic pens only)
; DWP_SOLID, solid
; DWP_DASH, dashed
; DWP_DOT, dotted
; DWP_DASHDOT, alternating dashes and dots
; DWP_DASHDOTDOT, alternating dashes and double dots
;A pen_style value of DWP_GEOMETRIC allows for end caps and
; line joining specifications:
; DWP_ENDCAP_ROUND, round end caps
; DWP_ENDCAP_SQUARE, square end caps
; DPW_ENDCAP_FLAT, flat end caps
; DWP_JOIN_BEVEL, beveled joins
; DWP_JOIN_ROUND, round joins
line_width ,i4 ;Line width. If pen_style is DWP_GEOMETRIC, the width is
; specified in logical units. If pen_style is DWP_COSMETIC,
; the default value 1 is used.
brush_style ,i4 ;If pen_style is DWP_GEOMETRIC, the brush style must
; be defined as one of the following:
; DWP_BS_HATCHED, hatched brush
; DWP_BS_HOLLOW, hollow brush
; DWP_BS_SOLID, solid brush
; If pen_style is DWP_COSMETIC, the default value
; DWP_BS_SOLID is used
brush_color ,i4 ;The brush color can be defined by M_RGB()
hatch_style ,i4 ;If pen_style is DWP_GEOMETRIC and the brush style
; is DWP_BS_HATCHED, the brush hatch can be defined
; as DWP_HS_BDIAGONAL, 45-degree upward, left-to-
; right hatch
; DWP_HS_CROSS, horizontal and vertical cross-hatch
; DWP_HS_DIAGCROSS, 45-degree crosshatch
; DWP_HS_FDIAGONAL, 5-degree downward, left-to-right
; hatch
; DWP_HS_HORIZONTAL, horizontal hatch
; DWP_HS_VERTICAL, vertical hatch
pen_filler ,a16 ;Pen filler
DWP_GETPEN returns a pen handle.
DWP_DELPEN, pen_handle
Deletes the pen created with DWP_GETPEN. If DWP_DELPEN is not called, the objects are released during runtime shutdown.
DWP_DELPEN returns true if successful or false if an invalid pen handle is passed.
DWP_X_FROM_COL, column
Returns the X pixel coordinate for a column in the current font on the current printer. The pixel returned for an integer column is the origin of that column. A fractional column may be specified by passing an implied-decimal value. See DWP_GETSTATUS.
DWP_Y_FROM_ROW, row
Returns the Y pixel coordinate for a row in the current font on the current printer. The pixel returned for an integer row is the origin of that row. A fractional row may be specified by passing an implied-decimal value. See DWP_GETSTATUS.
DWP_TEXTWIDTH[, string]
Returns the average character width as defined by the font if nothing is passed or the width of the passed string if string is passed. The return value is in pixels. See DWP_GETSTATUS.
DWP_TEXTHEIGHT[, string]
If string is passed, returns the actual row height of the string. If nothing is passed, returns the row height, in pixels, calculated as
height + external leading
See DWP_GETSTATUS.
DWP_LARGESTFONT, height
Returns the largest point size available in the current font that fits the specified height in pixels.
DWP_TEXTMETRICS, text_specs
Returns a structure containing basic information about the current font. Text_specs is the structure provided below. This structure is defined in DBLDIR:winprint.def.
structure text_specs
height ,i4 ;Character height (ascender + descender)
ascent ,i4 ;Character ascent (units above the base line)
descent ,i4 ;Character descent (units below the base line)
intleading ,i4 ;Leading inside height
extleading ,i4 ;Character leading outside the font
avewidth ,i4 ;Average character width (usually x)
maxwidth ,i4 ;Width of the widest character
weight ,i4 ;Font weight
overhang ,i4 ;Extra width per string that may be added to
; synthesized fonts, such as bold or italic
digitizedX ,i4 ;Horizontal aspect of device font was designed for
digitizedY ,i4 ;Vertical aspect of device font was designed for
firstchar ,a1 ;Value of the first character defined in the font
lastchar ,a1 ;Value of the last character defined in the font
defaultchar ,a1 ;Value of the character to be substituted for
; characters not in the font
breakchar ,a1 ;Value of the character used to define word breaks
; for text justification
italic ,i4 ;True if font is an italic font
underlined ,i4 ;True if font is an underlined font
strikeOut ,i4 ;True if font is a strikeout font
pitch ,i4 ;Font pitch, technology, and family
; DWP_VARIABLE_PITCH, variable pitch font
; DWP_VECTOR, vector font
; DWP_TRUE_TYPE, true type font
; DWP_DEVICE, device font
charset ,i4 ;Font character set
text_filler ,a32 ;Text spec filler
DWP_GETSTATUS
Returns one or more of the following values (defined in winprint.def), which indicates the status of the printer:
|
Values Returned by DWP_GETSTATUS |
||
|---|---|---|
|
Mnemonic |
Value |
Printer status |
|
DWPST_PAUSED |
^x(1) |
Paused |
|
DWPST_PENDING_DELETION |
^x(4) |
About to be deleted from the user’s profile |
|
DWPST_PAPER_JAM |
^x(8) |
Paper jam |
|
DWPST_PAPER_OUT |
^x(10) |
Out of paper |
|
DWPST_MANUAL_FEED |
^x(20) |
Awaiting manual paper feed |
|
DWPST_PAPER_PROBLEM |
^x(40) |
There is a paper problem other than a jam or out of paper |
|
DWPST_OFFLINE |
^x(80) |
Offline |
|
DWPST_IO_ACTIVE |
^x(100) |
In an active input/output state |
|
DWPST_BUSY |
^x(200) |
Busy |
|
DWPST_PRINTING |
^x(400) |
Printing |
|
DWPST_OUTPUT_BIN_FULL |
^x(800) |
Output bin is full; needs to be cleared |
|
DWPST_NOT_AVAILABLE |
^x(1000) |
Not available for printing |
|
DWPST_WAITING |
^x(2000) |
Waiting |
|
DWPST_PROCESSING |
^x(4000) |
Processing a command to change settings |
|
DWPST_INITIALIZING |
^x(8000) |
Initializing |
|
DWPST_WARMING_UP |
^x(10000) |
Warming up |
|
DWPST_TONER_LOW |
^x(20000) |
Low on toner |
|
DWPST_NO_TONER |
^x(40000) |
Out of toner |
|
DWPST_PAGE_PUNT |
^x(80000) |
Unable to print the current page |
|
DWPST_USER_INTERVENTION |
^x(100000) |
Waiting for user to respond to an error |
|
DWPST_OUT_OF_MEMORY |
^x(200000) |
Out of memory |
|
DWPST_DOOR_OPEN |
^x(400000) |
Printer door is open |
|
DWPST_SERVER_UNKNOWN |
^x(800000) |
Unable to report status |
|
DWPST_POWER_SAVE |
^x(1000000) |
Power save mode |
|
— |
0 |
Not experiencing a problem |
|
— |
-1 |
Attempt to query printer status failed. Use %SYSERR to retrieve the system error code associated with this failure. |
If you use ^VARARGARRAY, operation is the last declared argument for this routine.
Examples
See Sample programs.
