DEVMODE

The DEVMODE data structure contains information about the device initialization and environment of a printer.

typedef struct _devicemode { // dvmd

BCHAR dmDeviceName[CCHDEVICENAME];

WORD dmSpecVersion;

WORD dmDriverVersion;

WORD dmSize;

WORD dmDriverExtra;

DWORD dmFields;

short dmOrientation;

short dmPaperSize;

short dmPaperLength;

short dmPaperWidth;

short dmScale;

short dmCopies;

short dmDefaultSource;

short dmPrintQuality;

short dmColor;

short dmDuplex;

short dmYResolution;

short dmTTOption;

short dmCollate;

BCHAR dmFormName[CCHFORMNAME];

WORD dmLogPixels;

DWORD dmBitsPerPel;

DWORD dmPelsWidth;

DWORD dmPelsHeight;

DWORD dmDisplayFlags;

DWORD dmDisplayFrequency;

#if(WINVER >= 0x0400)

DWORD dmICMMethod; // Windows 95 only

DWORD dmICMIntent; // Windows 95 only

DWORD dmMediaType; // Windows 95 only

DWORD dmDitherType; // Windows 95 only

DWORD dmReserved1; // Windows 95 only

DWORD dmReserved2; // Windows 95 only

#endif /* WINVER >= 0x0400 */

} DEVMODE;

Members

dmDeviceName

Specifies the the "friendly" name of the printer; for example, "PCL/HP LaserJet" in the case of PCL/HP LaserJet®. This string is unique among device drivers. Note that this name may be truncated to fit in the dmDeviceName array.

dmSpecVersion

Specifies the version number of the initialization data specification on which the structure is based.

dmDriverVersion

Specifies the printer driver version number assigned by the printer driver developer.

dmSize

Specifies the size, in bytes, of the DEVMODE structure, not including any private driver-specific data that might follow the structure's public members. You can use this member to determine the number of bytes of public data regardless of the version of the DEVMODE structure being used.

dmDriverExtra

Contains the number of bytes of private driver-data that follow this structure. If a device driver does not use device-specific information, set this member to zero.

dmFields

A set of bit flags that specify whether certain members of the DEVMODE structure have been initialized. If a field is initialized, its corresponding bit flag is set, otherwise the bit flag is clear. A printer driver supports only those DEVMODE structure members that are appropriate for the printer technology.

The following bit flags are defined, and are listed here with the corresponding structure members:

dmOrientation

Selects the orientation of the paper. This member can be either DMORIENT_PORTRAIT (1) or DMORIENT_LANDSCAPE (2).

dmPaperSize

Selects the size of the paper to print on. This member can be set to zero if the length and width of the paper are both set by the dmPaperLength and dmPaperWidth members. Otherwise, the dmPaperSize member can be set to one of the following predefined values:

dmPaperLength

Overrides the length of the paper specified by the dmPaperSize member, either for custom paper sizes or for devices such as dot-matrix printers, which can print on a page of arbitrary length. These values, along with all other values in this structure that specify a physical length, are in tenths of a millimeter.

dmPaperWidth

Overrides the width of the paper specified by the dmPaperSize member.

dmScale

Specifies the factor by which the printed output is to be scaled. The apparent page size is scaled from the physical page size by a factor of dmScale/100. For example, a letter-sized page with a dmScale value of 50 would contain as much data as a page of 17- by 22-inches because the output text and graphics would be half their original height and width.

dmCopies

Selects the number of copies printed if the device supports multiple-page copies.

dmDefaultSource

Reserved; must be zero.

dmPrintQuality

Specifies the printer resolution. There are four predefined device-independent values:

DMRES_HIGH
DMRES_MEDIUM
DMRES_LOW
DMRES_DRAFT

If a positive value is given, it specifies the number of dots per inch (DPI) and is therefore device dependent.

dmColor

Switches between color and monochrome on color printers. Following are the possible values:

DMCOLOR_COLOR
DMCOLOR_MONOCHROME

dmDuplex

Selects duplex or double-sided printing for printers capable of duplex printing. Following are the possible values:

DMDUP_SIMPLEX
DMDUP_HORIZONTAL
DMDUP_VERTICAL

dmYResolution

Specifies the y-resolution, in dots per inch, of the printer. If the printer initializes this member, the dmPrintQuality member specifies the x-resolution, in dots per inch, of the printer.

dmTTOption

Specifies how TrueType® fonts should be printed. This member can be one of the following values:

dmUnusedPadding

Used to align the structure to a DWORD boundary. This should not be used or referenced. Its name and usage is reserved, and can change in future releases.

dmCollate

Specifies whether collation should be used when printing multiple copies. (This member is ignored unless the printer driver indicates support for collation by setting the dmFields member to DM_COLLATE.) This member can be be one of the following values:

Using DMCOLLATE_TRUE provides faster, more efficient output for collation, since the data is sent to the device driver just once, no matter how many copies are required. The printer is told to simply print the page again.

dmFormName

Windows NT: Specifies the name of the form to use; for example, "Letter" or "Legal". A complete set of names can be retrieved by using the EnumForms function.

Windows 95: Printer drivers do not use this member.

dmLogPixels

Specifies the number of pixels per logical inch. Printer drivers do not use this member.

dmBitsPerPel

Specifies the color resolution, in bits per pixel, of the display device (for example: 4 bits for 16 colors, 8 bits for 256 colors, or 16 bits for 65536 colors). Display drivers use this member, for example, in the ChangeDisplaySettings function. Printer drivers do not use this member.

dmPelsWidth

Specifies the width, in pixels, of the visible device surface. Display drivers use this member, for example, in the ChangeDisplaySettings function. Printer drivers do not use this member.

dmPelsHeight

Specifies the height, in pixels, of the visible device surface. Display drivers use this member, for example, in the ChangeDisplaySettings function. Printer drivers do not use this member.

dmDisplayFlags

Specifies the device's display mode. This member can be one of the following values:

Display drivers use this member, for example, in the ChangeDisplaySettings function. Printer drivers do not use this member.

dmDisplayFrequency

Specifies the frequency, in hertz (cycles per second), of the display device in a particular mode. This value is also known as the display device's vertical refresh rate. Display drivers use this member. It is used, for example, in the ChangeDisplaySettings function. Printer drivers do not use this member.

When you call the EnumDisplaySettings function, the dmDisplayFrequency member may return with the value 0 or 1. These values represent the display hardware's default refresh rate. This default rate is typically set by switches on a display card or computer motherboard, or by a configuration program that does not use Win32 display functions such as ChangeDisplaySettings.

dmICMMethod

Windows 95:

Specifies how ICM is handled. For a non-ICM application, this member determines if ICM is enabled or disabled. For ICM applications, Windows examines this member to determine how to handle ICM support. This member can be one of the following predefined values, or a driver-defined value greater than the value of DMICMMETHOD_USER:

The printer driver must provide a user interface for setting this member. Most printer drivers support only the DMICMMETHOD_SYSTEM or DMICMMETHOD_NONE value. Drivers for PostScript printers support all values.

Windows NT:

This member is not supported on Windows NT.

dmICMIntent

Windows 95:

Specifies which of the three possible color matching methods, or intents, should be used by default. This member is primarily for non-ICM applications. ICM applications can establish intents by using the ICM functions. This member can be one of the following predefined values, or a driver defined value greater than the value of DMICM_USER:

Windows NT:

This member is not supported on Windows NT.

dmMediaType

Windows 95:

Specifies the type of media being printed on. The member can be one of the following predefined values, or a driver-defined value greater than the value of DMMEDIA_USER:

Windows NT:

This member is not supported on Windows NT.

dmDitherType

Windows 95:

Specifies how dithering is to be done. The member can be one of the following predefined values, or a driver-defined value greater than the value of DMDITHER_USER:

Windows NT:

This member is not supported on Windows NT.

dmReserved1

Windows 95: Not used; must be zero.

Windows NT: This member is not supported on Windows NT.

dmReserved2

Windows 95: Not used; must be zero.

Windows NT: This member is not supported on Windows NT.

Remarks

A device driver's private data follows the public portion of the DEVMODE structure. The size of the public data can vary for different versions of the structure. The dmSize member specifies the number of bytes of public data, and the dmDriverExtra member specifies the number of bytes of private data.

See Also

AdvancedDocumentProperties, CreateDC, CreateIC, DeviceCapabilities, DocumentProperties, OpenPrinter