DEVMODEW structure (wingdi.h)
The DEVMODEW structure is used for specifying characteristics of display and print devices in the Unicode (wide) character set.
Syntax
typedef struct _devicemodeW {
WCHAR dmDeviceName[CCHDEVICENAME];
WORD dmSpecVersion;
WORD dmDriverVersion;
WORD dmSize;
WORD dmDriverExtra;
DWORD dmFields;
union {
struct {
short dmOrientation;
short dmPaperSize;
short dmPaperLength;
short dmPaperWidth;
short dmScale;
short dmCopies;
short dmDefaultSource;
short dmPrintQuality;
} DUMMYSTRUCTNAME;
POINTL dmPosition;
struct {
POINTL dmPosition;
DWORD dmDisplayOrientation;
DWORD dmDisplayFixedOutput;
} DUMMYSTRUCTNAME2;
} DUMMYUNIONNAME;
short dmColor;
short dmDuplex;
short dmYResolution;
short dmTTOption;
short dmCollate;
WCHAR dmFormName[CCHFORMNAME];
WORD dmLogPixels;
DWORD dmBitsPerPel;
DWORD dmPelsWidth;
DWORD dmPelsHeight;
union {
DWORD dmDisplayFlags;
DWORD dmNup;
} DUMMYUNIONNAME2;
DWORD dmDisplayFrequency;
DWORD dmICMMethod;
DWORD dmICMIntent;
DWORD dmMediaType;
DWORD dmDitherType;
DWORD dmReserved1;
DWORD dmReserved2;
DWORD dmPanningWidth;
DWORD dmPanningHeight;
} DEVMODEW, *PDEVMODEW, *NPDEVMODEW, *LPDEVMODEW;
Members
dmDeviceName[CCHDEVICENAME]
For a display, specifies the name of the display driver's DLL; for example, "perm3dd" for the 3Dlabs Permedia3 display driver.
For a printer, specifies the "friendly name"; for example, "PCL/HP LaserJet" in the case of PCL/HP LaserJet. If the name is greater than CCHDEVICENAME characters in length, the spooler truncates it to fit in the array.
dmSpecVersion
Specifies the version number of this DEVMODEW structure. The current version number is identified by the DM_SPECVERSION constant in wingdi.h.
dmDriverVersion
For a printer, specifies the printer driver version number assigned by the printer driver developer.
Display drivers can set this member to DM_SPECVERSION.
dmSize
Specifies the size in bytes of the public DEVMODEW structure, not including any private, driver-specified members identified by the dmDriverExtra member.
dmDriverExtra
Specifies the number of bytes of private driver data that follow the public structure members. If a device driver does not provide private DEVMODEW members, this member should be set to zero.
dmFields
Specifies bit flags identifying which of the following DEVMODEW members are in use. For example, the DM_ORIENTATION flag is set when the dmOrientation member contains valid data. The DM_XXX flags are defined in wingdi.h.
DUMMYUNIONNAME
DUMMYUNIONNAME.DUMMYSTRUCTNAME
DUMMYUNIONNAME.DUMMYSTRUCTNAME.dmOrientation
For printers, specifies the paper orientation. This member can be either DMORIENT_PORTRAIT or DMORIENT_LANDSCAPE.
This member is not used for displays.
DUMMYUNIONNAME.DUMMYSTRUCTNAME.dmPaperSize
For printers, specifies the size of the paper to be printed on. This member must be zero if the length and width of the paper are specified by the dmPaperLength and dmPaperWidth members. Otherwise, the dmPaperSize member must be one of the DMPAPER-prefixed constants defined in wingdi.h.
This member is not used for displays.
DUMMYUNIONNAME.DUMMYSTRUCTNAME.dmPaperLength
For printers, specifies the length of the paper, in units of 1/10 of a millimeter. This value overrides the length of the paper specified by the dmPaperSize member, and is used if the paper is of a custom size, or if the device is a dot matrix printer, which can print a page of arbitrary length.
This member is not used for displays.
DUMMYUNIONNAME.DUMMYSTRUCTNAME.dmPaperWidth
For printers, specifies the width of the paper, in units of 1/10 of a millimeter. This value overrides the width of the paper specified by the dmPaperSize member. This member must be used if dmPaperLength is used.
This member is not used for displays.
DUMMYUNIONNAME.DUMMYSTRUCTNAME.dmScale
For printers, specifies the percentage by which the image is to be scaled for printing. The image's page size is scaled to the physical page by a factor of dmScale/100. For example, a 17-inch by 22-inch image with a scale value of 100 requires 17x22-inch paper, while the same image with a scale value of 50 should print as half-sized and fit on letter-sized paper.
This member is not used for displays.
DUMMYUNIONNAME.DUMMYSTRUCTNAME.dmCopies
For printers, specifies the number of copies to be printed, if the device supports multiple copies.
This member is not used for displays.
DUMMYUNIONNAME.DUMMYSTRUCTNAME.dmDefaultSource
For printers, specifies the printer's default input bin. This must be one of the DMBIN-prefixed constants defined in wingdi.h. If the specified constant is DMBIN_FORMSOURCE, the input bin should be selected automatically.
This member is not used for displays.
DUMMYUNIONNAME.DUMMYSTRUCTNAME.dmPrintQuality
For printers, specifies the printer resolution. The following negative constant values are defined in wingdi.h:
- DMRES_HIGH
- DMRES_MEDIUM
- DMRES_LOW
- DMRES_DRAFT
If a positive value is specified, it represents the number of dots per inch (DPI) for the x resolution, and the y resolution is specified by dmYResolution.
This member is not used for displays.
DUMMYUNIONNAME.dmPosition
DUMMYUNIONNAME.DUMMYSTRUCTNAME2
DUMMYUNIONNAME.DUMMYSTRUCTNAME2.dmPosition
For displays, specifies a POINTL structure containing the x- and y-coordinates of upper-left corner of the display, in desktop coordinates. This member is used to determine the relative position of monitors in a multiple monitor environment.
This member is not used for printers.
DUMMYUNIONNAME.DUMMYSTRUCTNAME2.dmDisplayOrientation
This member is defined only for Windows XP and later.
For displays, specifies the orientation at which images should be presented. When the DM_DISPLAYORIENTATION bit is not set in the dmFields member, this member must be set to zero. When the DM_DISPLAYORIENTATION bit is set in the dmFields member, this member must be set to one of the following values:
| Value | Meaning |
|---|---|
| DMDO_DEFAULT | The current mode's display device orientation is the natural orientation of the device, and should be used as the default. |
| DMDO_90 | The display device orientation is 90 degrees (measured clockwise) from that of DMDO_DEFAULT. |
| DMDO_180 | The display device orientation is 180 degrees (measured clockwise) from that of DMDO_DEFAULT. |
| DMDO_270 | The display device orientation is 270 degrees (measured clockwise) from that of DMDO_DEFAULT. |
This member is not used for printers.
For more information, see Returning Display Modes: DrvGetModes.
DUMMYUNIONNAME.DUMMYSTRUCTNAME2.dmDisplayFixedOutput
This member is defined only for Windows XP and later.
For fixed-resolution displays, specifies how the device can present a lower-resolution mode on a higher-resolution display. For example, if a display device's resolution is fixed at 1024 X 768, and its mode is set to 640 x 480, the device can either display a 640 X 480 image within the 1024 X 768 screen space, or stretch the 640 X 480 image to fill the larger screen space.
When the DM_DISPLAYFIXEDOUTPUT bit is not set in the dmFields member, this member must be set to zero. When the DM_DISPLAYFIXEDOUTPUT bit is set in the dmFields member, this member must be set to one of the following values:
| Value | Meaning |
|---|---|
| DMDFO_CENTER | The display device presents a lower resolution mode image by centering it in the larger screen space. |
| DMDFO_STRETCH | The display device presents a lower-resolution mode image by stretching it to fill the larger screen space. |
This member is not used for printers.
For more information, see Returning Display Modes: DrvGetModes.
dmColor
For printers, specifies whether a color printer should print color or monochrome. This member can be one of DMCOLOR_COLOR or DMCOLOR_MONOCHROME.
This member is not used for displays.
dmDuplex
For printers, specifies duplex (double-sided) printing for duplex-capable printers. This member can be one of the following values:
DMDUP_HORIZONTAL
Print double-sided, using short edge binding.
DMDUP_SIMPLEX
Print single-sided.
DMDUP_VERTICAL
Print double-sided, using long edge binding.
This member is not used for displays.
dmYResolution
For printers, specifies the y resolution of the printer, in DPI. If this member is used, the dmPrintQuality member specifies the x resolution.
This member is not used for displays.
dmTTOption
For printers, specifies how TrueType fonts should be printed. This member must be one of the DMTT-prefixed constants defined in wingdi.h.
This member is not used for displays.
dmCollate
For printers, specifies whether multiple copies should be collated. This member can be one of the following values:
DMCOLLATE_TRUE
Collate when printing multiple copies.
DMCOLLATE_FALSE
Do not collate when printing multiple copies.
This member is not used for displays.
dmFormName[CCHFORMNAME]
For printers, specifies the name of the form to use; such as "Letter" or "Legal". This must be a name that can be obtain by calling the Win32 EnumForms function.
This member is not used for displays.
dmLogPixels
For displays, specifies the number of logical pixels per inch of a display device and should be equal to the ulLogPixels member of the GDIINFO structure.
This member is not used for printers.
dmBitsPerPel
For displays, specifies the color resolution, in bits per pixel, of a display device.
This member is not used for printers.
dmPelsWidth
For displays, specifies the width, in pixels, of the visible device surface.
This member is not used for printers.
dmPelsHeight
For displays, specifies the height, in pixels, of the visible device surface.
This member is not used for printers.
DUMMYUNIONNAME2
DUMMYUNIONNAME2.dmDisplayFlags
Specifies the device's display mode. This member can be a combination of the following values.
| Value | Meaning |
|---|---|
| DM_GRAYSCALE | Specifies that the display is a noncolor device. If this flag is not set, color is assumed. This flag is no longer valid. |
| DM_INTERLACED | Specifies that the display mode is interlaced. If the flag is not set, noninterlaced is assumed. |
Display drivers use this member; for example, in the ChangeDisplaySettings function. Printer drivers don't use this member.
DUMMYUNIONNAME2.dmNup
For printers, specifies whether the print system handles "N-up" printing (playing multiple EMF logical pages onto a single physical page). The value of this member can be one of the following:
| Value | Meaning |
|---|---|
| DMNUP_SYSTEM | The print system handles "N-up" printing. |
| DMNUP_ONEUP | The print system does not handle "N-up" printing. An application can set dmNup to DMNUP_ONEUP if it intends to carry out "N-up" printing on its own. |
This member is not used for displays.
dmDisplayFrequency
For displays, specifies the frequency, in hertz, of a display device in its current mode.
This member is not used for printers.
dmICMMethod
Specifies one of the DMICMMETHOD-prefixed constants defined in wingdi.h.
dmICMIntent
Specifies one of the DMICM-prefixed constants defined in wingdi.h.
dmMediaType
Specifies one of the DMMEDIA-prefixed constants defined in wingdi.h.
dmDitherType
Specifies one of the DMDITHER-prefixed constants defined in wingdi.h.
dmReserved1
Is reserved for system use and should be ignored by the driver.
dmReserved2
Is reserved for system use and should be ignored by the driver.
dmPanningWidth
Is reserved for system use and should be ignored by the driver.
dmPanningHeight
Is reserved for system use and should be ignored by the driver.
Remarks
The DEVMODEW structure is the Unicode version of the DEVMODE structure (described in the Microsoft Windows SDK documentation). While applications can use either the ANSI or Unicode version of the structure, drivers are required to use the Unicode version.
For printer drivers, the DEVMODEW structure is used for specifying printer characteristics required by a print document. It is also used for specifying a printer's default characteristics.
Immediately following a DEVMODEW structure's defined members (often referred to as its public members), there can be a set of driver-defined members (often referred to as private DEVMODEW members). The driver supplies the size, in bytes, of this private area in dmDriverExtra. Driver-defined private members are for exclusive use by the driver. The starting address for the private members can be referenced using the dmSize member as follows:
PVOID pvDriverData = (PVOID) (((BYTE *) pdm) + (pdm->dmSize));
A driver can rely on the spooler to pass a DEVMODEW buffer that is no smaller than (dmSize + dmDriverExtra) bytes. As a result, the driver can safely read that number of bytes starting from the beginning of the buffer without causing an access violation, and without needing to probe memory.
Prior to playing EMF, GDI calls the spooler to validate the contents of the public portion of the DEVMODEW buffer. If the DEVMODEW buffer does not pass the validation tests performed in the spooler, GDI does not pass the buffer on to the printer driver.
In Windows XP, a new struct member was added. This struct member contains an existing DEVMODEW structure member, dmPosition, together with two new members, dmDisplayOrientation and dmDisplayFixedOutput. These members are described in the preceding Members section.
Also for Windows XP, several members of the DEVMODEW structure were moved to different locations in this structure. The dmScale, dmCopies, dmDefaultSource, and dmPrintQuality members were appended to the struct member containing the dmOrientation, dmPaperSize, dmPaperLength, and dmPaperWidth members.
Note
The wingdi.h header defines DEVMODE as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Header | wingdi.h (include Wingdi.h) |