%WPR_GETDEVICE

Retrieve printer settings

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

 

 

status = %WPR_GETDEVICE(report_handle, capability[, setting])

Return value

status

Returns true if the printer supports the specified capability or false if the printer does not support the capability or a Windows system call failed. (n)

Arguments

report_handle

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

capability

One of the following printer capabilities: (n)

DWP_ORIENTATION = Document orientation

DWP_PAPERSIZE = Paper size

DWP_PAPERLENGTH = Paper length

DWP_PAPERWIDTH = Paper width

DWP_SCALE = Scaling factor

DWP_COPIES = Number of copies

DWP_QUALITY = Print quality

DWP_COLOR = Color vs. monochrome

DWP_DUPLEX = Duplex mode

DWP_RESOLUTIONX = X pixel resolution

DWP_RESOLUTIONY = Y pixel resolution

DWP_COLLATE = Collation

DWP_FORMNAME = Form to use

DWP_PIXELWIDTH = Printable width of the device’s page

DWP_PIXELHEIGHT = Printable height of the device’s page

DWP_PHYSICALWIDTH = Physical width of the device’s page

DWP_PHYSICALHEIGHT = Physical height of the device’s page

DWP_XOFFSET = Horizontal offset from device page to printable page

DWP_YOFFSET = Vertical offset from device page to printable page

DWP_FONT = Font characteristics

DWP_TEXTCOLOR = Text color

DWP_BACKCOLOR = Background color

DWP_PAPERSOURCE = Paper source

DWP_SPECS = All printer capabilities

setting

(optional) Returned with the current printer setting if that capability is supported for the device. If the capability is not supported, setting is undefined. (a or n)

Discussion

If an invalid report_handle is passed, the runtime generates a trappable error. If the printer does not support the capability, status is false and %SYSERR returns 0. If a Win32 function fails, status is 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.

DWP_ORIENTATION

Gets the orientation for the document. Setting values are as follows:

DWPO_PORTRAIT

DWPO_LANDSCAPE

DWP_PAPERSIZE

Gets the paper size for the document. Overrides both DWP_PAPERLENGTH and DWP_PAPERWIDTH. Setting values are as follows (additional values may be added as Microsoft expands its list):

DWPP_LETTER

DWPP_LETTERSMALL

DWPP_TABLOID

DWPP_LEDGER

DWPP_LEGAL

DWPP_STATEMENT

DWPP_EXECUTIVE

DWPP_A3

DWPP_A4

DWPP_A4SMALL

DWPP_A5

DWPP_B4

DWPP_B5

DWPP_FOLIO

DWPP_QUARTO

DWPP_10X14

DWPP_11X17

DWPP_NOTE

DWPP_ENV_9

DWPP_ENV_10

DWPP_ENV_11

DWPP_ENV_12

DWPP_ENV_14

DWPP_CSHEET

DWPP_DSHEET

DWPP_ESHEET

DWPP_ENV_DL

DWPP_ENV_C5

DWPP_ENV_C3

DWPP_ENV_C4

DWPP_ENV_C6

DWPP_ENV_C65

DWPP_ENV_B4

DWPP_ENV_B5

DWPP_ENV_B6

DWPP_ENV_ITALY

DWPP_ENV_MONARCH

DWPP_ENV_PERSONAL

DWPP_FANFOLD_US

DWPP_FANFOLD_STD_GERMAN

DWPP_FANFOLD_LGL_GERMAN

DWPP_ISO_B4

DWPP_JAPANESE_POSTCARD

DWPP_9X11

DWPP_10X11

DWPP_15X11

DWPP_ENV_INVITE

DWPP_RESERVED_48

DWPP_RESERVED_49

DWPP_LETTER_EXTRA

DWPP_LEGAL_EXTRA

DWPP_TABLOID_EXTRA

DWPP_A4_EXTRA

DWPP_LETTER_TRANSVERSE

DWPP_A4_TRANSVERSE

DWPP_LETTER_EXTRA_TRANSV

DWPP_A_PLUS

DWPP_B_PLUS

DWPP_LETTER_PLUS

DWPP_A4_PLUS

DWPP_A5_TRANSVERSE

DWPP_B5_TRANSVERSE

DWPP_A3_EXTRA

DWPP_A5_EXTRA

DWPP_B5_EXTRA

DWPP_A2

DWPP_A3_TRANSVERSE

DWPP_A3_EXTRA_TRANSVERSE

DWP_PAPERLENGTH

Gets the paper length in tenths of a millimeter. Overrides the setting for DWP_PAPERSIZE.

DWP_PAPERWIDTH

Gets the paper width in tenths of a millimeter. Overrides the setting for DWP_PAPERSIZE.

DWP_SCALE

Gets the scaling factor, where 100 indicates no scaling.

DWP_COPIES

Gets the number of copies to print.

DWP_QUALITY

Gets the print quality. Setting values are as follows:

DWPQ_HIGH

DWPQ_MEDIUM

DWPQ_LOW

DWPQ_DRAFT

DWP_COLOR

Gets the color/monochrome mode:

DWPC_COLOR

DWPC_MONOCHROME

DWP_DUPLEX

Gets the duplex mode:

DWPD_SIMPLEX

DWPD_HORIZONTAL

DWPD_VERTICAL

Simplex indicates no duplexing. Horizontal indicates duplex for binding on the short side of the paper, while vertical indicates duplex for binding on the long side of the paper. That is, horizontal and vertical refer to the orientation of the long edge of the page when the binding is vertical.

The duplex orientation is distinct from the print orientation. Normally, one would use horizontal duplexing when printing in landscape mode and vertical duplexing when printing in portrait mode as the two examples on the left in figure 1 show. However, one can use horizontal duplexing when printing in portrait mode and vertical duplexing when printing in landscape mode as the two examples on the right demonstrate. .

1. Duplex and print orientation combinations

DWP_RESOLUTIONX

Gets the X pixel resolution (DPI).

DWP_RESOLUTIONY

Gets the Y pixel resolution (DPI).

DWP_COLLATE

Gets the collation of multiple copies. True indicates multiple copies are collated; false indicates no collation.

DWP_FORMNAME

Gets the name of the form to use. This option overrides DWP_PAPERSIZE, DWP_PAPERLENGTH, and DWP_PAPERWIDTH.

DWP_PIXELWIDTH

Gets the printable width of the device’s page, in pixels.

DWP_PIXELHEIGHT

Gets the printable height of the device’s page, in pixels.

DWP_PHYSICALWIDTH

Gets the physical (printable plus nonprintable) width of the device’s page, in pixels.

DWP_PHYSICALHEIGHT

Gets the physical (printable plus nonprintable) height of the device’s page, in pixels.

DWP_XOFFSET

Gets the offset, in pixels, from the left edge of the device’s page to the printable left edge.

DWP_YOFFSET

Gets the offset, in pixels, from the top edge of the device’s page to the printable top edge.

DWP_FONT

Gets the font characteristics. Setting can be mapped to the following structure:

structure font_specs
  facename     ,D_WPRFONTNAME   ;Name of typeface
  pointsize    ,i4    ;Point size
  weight       ,i4    ;Font weight (DWPFW_DONTCARE, DWPFW_THIN, 
                      ; DWPFW_EXTRALIGHT, DWPFW_LIGHT, DWPFW_NORMAL, 
                      ; DWPFW_MEDIUM, DWPFW_SEMIBOLD, DWPFW_BOLD, 
                      ; DWPFW_EXTRABOLD, DWPFW_HEAVY)
  italic       ,i1    ;True if italic
  underline    ,i1    ;True if underline
  strikeout    ,i1    ;True if strikeout
  fixed        ,i1    ;True if fixed–pitch
  font_fill    ,a32   ;Filler
  orientation  ,i4    ;Character orientation in tenths of a degree from x
  escapement   ,i4    ;Text baseline escapement in tenths of a degree

Note that orientation and escapement enable you to rotate characters and text strings:

The default for both is zero, which represents the normal horizontal orientation of a character. Positive values rotate text or characters counter‑clockwise, and negative values rotate them clockwise.

Generally, orientation and escapement will match, but a text string can, for example, be printed vertically while each character in the string is oriented horizontally. In this case, orientation would be 0 and escapement would be ‑900 (which is 90 degrees clockwise) or 2700 (which is 270 degrees counter‑clockwise).

This structure is defined in DBLDIR:winprint.def, along with D_WPRFONTNAME (a32).

DWP_TEXTCOLOR

Gets the text color as an RGB triplet. An RGB triplet can be constructed using the supplied macro (in DBLDIR:winprint.def):

M_RGB(red,green,blue)

where red, green, and blue are intensities (in the range 0–255) for each color component. If all three are 255, the color is white; if all are 0, the color is black.

DWP_BACKCOLOR

Gets the background color as an RGB triplet.

DWP_PAPERSOURCE

Gets the paper source for a printer. Setting is one of the following:

DWPS_UPPER

Upper bin (or the only one)

DWPS_LOWER

Lower bin

DWPS_MIDDLE

Middle bin

DWPS_MANUAL

Manual feed

DWPS_ENVELOPE

Envelope bin

DWPS_ENVMANUAL

Manual envelope feed

DWPS_AUTO

Auto‑select by paper size

DWPS_TRACTOR

Tractor feed

DWPS_SMALLFMT

Small format

DWPS_LARGEFMT

Large format

DWPS_LARGECAPACITY

Large capacity bin

DWPS_CASSETTE

Cassette

DWPS_FORMSOURCE

Source for selected form

DWPS_USER

User‑defined

DWP_SPECS

Gets all of the printer capabilities at once. Setting can be mapped to the following structure:

structure print_specs
  printer               ,D_PRINTERNAME          ;Name of the printer
  orientation           ,i4     ;DWPO_PORTRAIT/DWPO_LANDSCAPE
  paper_size            ,i4     ;Paper size for next document (see above)
  paper_length          ,i4     ;Paper length in tenths of a millimeter
  paper_width           ,i4     ;Paper width in tenths of a millimeter
  scale                 ,i4     ;Scaling factor
  copies                ,i4     ;Number of copies
  quality               ,i4     ;DWPQ_(HIGH, MEDIUM, LOW, DRAFT) or 0
  color                 ,i4     ;DWPC_(COLOR, MONOCHROME)
  duplex                ,i4     ;DWPD_(SIMPLEX, HORIZONTAL, VERTICAL)
  resolution_x          ,i4     ;X pixel resolution (or 0)
  resolution_y          ,i4     ;Y pixel resolution (or 0)
  collate               ,i4     ;Collation true or false
  formname              ,D_FORMNAME      ;Name of form
  pixelwidth            ,i4     ;Width of the page in pixels
  pixelheight           ,i4     ;Height of the page in pixels 
  physicalwidth         ,i4     ;Width (total) of page in pixels
  physicalheight        ,i4     ;Height (total) of page in pixels
  xoffset               ,i4     ;X offset of page in pixels
  yoffset               ,i4     ;Y offset of page in pixels
  paper_source          ,i4     ;Location of source of paper to print on
  ps_filler             ,a60    ;Print Spec filler
  extended_pr_name      ,D_PRINTERNAME_EX        ;Extended size printer name

This structure is defined in DBLDIR:winprint.def, along with D_PRINTERNAME (a128), D_PRINTERNAME_EX (a256), D_FORMNAME (a32), and D_FONT (a^size(font)). See the documentation for each of the individual capabilities for more information.

To change everything, retrieve the setting using %WPR_GETDEVICE with the print_specs structure and change what you want to change. Then call %WPR_SETDEVICE with the updated print_specs structure specified. Some printer capabilities cannot be modified. See %WPR_SETDEVICE for the list of modifiable capabilities.

Important

Depending on the supported features and settings, some printer drivers may not return all information or may return incorrect information. The accuracy of the information returned by %WPR_GETDEVICE depends on the accuracy of the information from the printer driver.

Examples

See Sample programs.