Структура DEVMODEW (wingdi.h)

Статья
06/13/2023

Структура DEVMODEW используется для указания характеристик устройств отображения и печати в кодировке Юникод (широкий).

Синтаксис

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;

Члены

dmDeviceName[CCHDEVICENAME]

Для отображения указывает имя библиотеки DLL драйвера отображения; например, "perm3dd" для драйвера дисплея 3Dlabs Permedia3.

Для принтера указывает "понятное имя"; например, "PCL/HP LaserJet" в случае PCL/HP LaserJet. Если длина имени превышает длину символов CCHDEVICENAME, очередь очереди усекает его в соответствии с массивом.

dmSpecVersion

Указывает номер версии этой структуры DEVMODEW. Текущий номер версии определяется константой DM_SPECVERSION в wingdi.h.

dmDriverVersion

Для принтера указывает номер версии драйвера принтера, назначенный разработчиком драйвера принтера.

Драйверы отображения могут задать для этого элемента значение DM_SPECVERSION.

dmSize

Указывает размер в байтах общедоступной структуры DEVMODEW, не включая частные члены, заданные драйвером, идентифицируемые членом dmDriverExtra .

dmDriverExtra

Указывает количество байтов данных частного драйвера, которые следуют за элементами общедоступной структуры. Если драйвер устройства не предоставляет частные члены DEVMODEW, для этого элемента должно быть задано значение 0.

dmFields

Задает битовые флаги, определяющие, какие из следующих элементов DEVMODEW используются. Например, флаг DM_ORIENTATION устанавливается, если член dmOrientation содержит допустимые данные. Флаги DM_XXX определены в wingdi.h.

DUMMYUNIONNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.dmOrientation

Для принтеров задает ориентацию бумаги. Это может быть DMORIENT_PORTRAIT или DMORIENT_LANDSCAPE.

Этот элемент не используется для дисплеев.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.dmPaperSize

Для принтеров указывает размер бумаги для печати. Этот элемент должен быть равен нулю, если длина и ширина бумаги указаны членами dmPaperLength и dmPaperWidth . В противном случае член dmPaperSize должен быть одной из констант с префиксом DMPAPER, определенных в wingdi.h.

Этот элемент не используется для дисплеев.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.dmPaperLength

Для принтеров указывает длину бумаги в единицах 1/10 миллиметра. Это значение переопределяет длину бумаги, заданной членом dmPaperSize , и используется, если бумага имеет пользовательский размер или устройство является принтером точечной матрицы, который может печатать страницу произвольной длины.

Этот элемент не используется для дисплеев.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.dmPaperWidth

Для принтеров задает ширину бумаги в единицах 1/10 миллиметра. Это значение переопределяет ширину бумаги, заданной членом dmPaperSize . Этот член необходимо использовать, если используется dmPaperLength .

Этот элемент не используется для дисплеев.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.dmScale

Для принтеров указывает процент масштабирования изображения для печати. Размер страницы изображения масштабируется до физической страницы с коэффициентом dmScale/100. Например, для изображения размером 17 на 22 дюйма со значением масштаба 100 требуется бумага размером 17 x 22 дюйма, в то время как одно и то же изображение со значением масштаба 50 должно печатать как неполное и помещаться на бумаге размером с буквы.

Этот элемент не используется для дисплеев.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.dmCopies

Для принтеров указывает количество копий для печати, если устройство поддерживает несколько копий.

Этот элемент не используется для дисплеев.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.dmDefaultSource

Для принтеров указывает входную корзину принтера по умолчанию. Это должна быть одна из констант с префиксом DMBIN, определенных в wingdi.h. Если указанная константа DMBIN_FORMSOURCE, входная ячейка должна быть выбрана автоматически.

Этот элемент не используется для дисплеев.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.dmPrintQuality

Для принтеров указывает разрешение принтера. В wingdi.h определены следующие отрицательные значения констант:

DMRES_HIGH
DMRES_MEDIUM
DMRES_LOW
DMRES_DRAFT

Если указано положительное значение, оно представляет количество точек на дюйм (DPI) для разрешения x , а разрешение y задается dmYResolution.

Этот элемент не используется для дисплеев.

DUMMYUNIONNAME.dmPosition

DUMMYUNIONNAME.DUMMYSTRUCTNAME2

DUMMYUNIONNAME.DUMMYSTRUCTNAME2.dmPosition

Для дисплеев задает структуру POINTL , содержащую координаты X и Y левого верхнего угла экрана в координатах рабочего стола. Этот элемент используется для определения относительного положения мониторов в среде с несколькими мониторами.

Этот элемент не используется для принтеров.

DUMMYUNIONNAME.DUMMYSTRUCTNAME2.dmDisplayOrientation

Этот член определяется только для Windows XP и более поздних версий.

Для дисплеев задает ориентацию, с которой должны быть представлены изображения. Если бит DM_DISPLAYORIENTATION не задан в элементе dmFields , этот элемент должен иметь нулевое значение. Если бит DM_DISPLAYORIENTATION задан в элементе dmFields , этому элементу должно быть присвоено одно из следующих значений:

Значение	Значение
DMDO_DEFAULT	Ориентация устройства отображения в текущем режиме является естественной ориентацией устройства и должна использоваться по умолчанию.
DMDO_90	Ориентация устройства дисплея составляет 90 градусов (измеряется по часовой стрелке) от ориентации DMDO_DEFAULT.
DMDO_180	Ориентация устройства отображения составляет 180 градусов (измеряется по часовой стрелке) от ориентации DMDO_DEFAULT.
DMDO_270	Ориентация устройства дисплея составляет 270 градусов (измеряется по часовой стрелке) от ориентации DMDO_DEFAULT.

Этот элемент не используется для принтеров.

Дополнительные сведения см. в разделе Возврат режимов отображения: DrvGetModes.

DUMMYUNIONNAME.DUMMYSTRUCTNAME2.dmDisplayFixedOutput

Этот член определяется только для Windows XP и более поздних версий.

Для дисплеев с фиксированным разрешением указывает, как устройство может представить режим более низкого разрешения на дисплее с более высоким разрешением. Например, если разрешение устройства с дисплеем фиксированное на уровне 1024 X 768, а для его режима задано значение 640 x 480, устройство может отображать изображение размером 640 X 480 в пределах экранного пространства 1024 X 768 или растянуть изображение размером 640 X 480 для заполнения большего пространства экрана.

Если бит DM_DISPLAYFIXEDOUTPUT не задан в элементе dmFields , этот элемент должен иметь нулевое значение. Если бит DM_DISPLAYFIXEDOUTPUT задан в элементе dmFields , этому элементу должно быть присвоено одно из следующих значений:

Значение	Значение
DMDFO_CENTER	Устройство отображения представляет изображение в режиме более низкого разрешения, выравая его по центру в большем пространстве экрана.
DMDFO_STRETCH	Устройство отображения представляет изображение в режиме более низкого разрешения, растягивая его для заполнения большего пространства экрана.

Этот элемент не используется для принтеров.

Дополнительные сведения см. в разделе Возврат режимов отображения: DrvGetModes.

dmColor

Для принтеров указывает, должен ли цветной принтер печатать цветным или монохромным. Этот элемент может быть одним из DMCOLOR_COLOR или DMCOLOR_MONOCHROME.

Этот элемент не используется для дисплеев.

dmDuplex

Для принтеров указывает дуплексную (двустороннюю) печать для принтеров с поддержкой дуплексов. Этот элемент может иметь одно из следующих значений:

DMDUP_HORIZONTAL

Печать двусторонняя с использованием привязки к коротким краям.

DMDUP_SIMPLEX

Печать односторонняя.

DMDUP_VERTICAL

Печать на двух сторонах с помощью привязки длинных ребер.

Этот элемент не используется для дисплеев.

dmYResolution

Для принтеров указывает разрешение принтера по Y в DPI. Если используется этот элемент, то член dmPrintQuality задает разрешение x .

Этот элемент не используется для дисплеев.

dmTTOption

Для принтеров указывает способ печати шрифтов TrueType. Этот член должен быть одной из констант с префиксом DMTT, определенных в wingdi.h.

Этот элемент не используется для дисплеев.

dmCollate

Для принтеров указывает, следует ли выполнять сортировку нескольких копий. Этот элемент может иметь одно из следующих значений:

DMCOLLATE_TRUE

Сортировка при печати нескольких копий.

DMCOLLATE_FALSE

Не выполнять сортировку при печати нескольких копий.

Этот элемент не используется для дисплеев.

dmFormName[CCHFORMNAME]

Для принтеров указывает имя используемой формы; например "Letter" или "Legal". Это должно быть имя, которое можно получить, вызвав функцию Win32 EnumForms .

Этот элемент не используется для дисплеев.

dmLogPixels

Для дисплеев указывает количество логических пикселей на дюйм устройства отображения и должно быть равно члену ulLogPixels структуры GDIINFO .

Этот элемент не используется для принтеров.

dmBitsPerPel

Для дисплеев задает разрешение цвета (в битах на пиксель) устройства отображения.

Этот элемент не используется для принтеров.

dmPelsWidth

Для дисплеев задает ширину видимой поверхности устройства (в пикселях).

Этот элемент не используется для принтеров.

dmPelsHeight

Для дисплеев задает высоту видимой поверхности устройства (в пикселях).

Этот элемент не используется для принтеров.

DUMMYUNIONNAME2

DUMMYUNIONNAME2.dmDisplayFlags

Указывает режим отображения устройства. Этот элемент может быть сочетанием следующих значений.

Значение	Значение
DM_GRAYSCALE	Указывает, что дисплей является нецветным устройством. Если этот флаг не задан, предполагается цвет. Этот флаг больше недействителен.
DM_INTERLACED	Указывает, что режим отображения чередуется. Если флаг не задан, предполагается неинтерлейс.

Драйверы отображения используют этот элемент; например, в функции ChangeDisplaySettings . Драйверы принтеров не используют этот элемент.

DUMMYUNIONNAME2.dmNup

Для принтеров указывает, обрабатывает ли система печати печать "N-up" (воспроизведение нескольких логических страниц EMF на одной физической странице). Значение этого элемента может быть одним из следующих:

Значение	Значение
DMNUP_SYSTEM	Система печати обрабатывает "N-up" печать.
DMNUP_ONEUP	Система печати не обрабатывает печать "N-up". Приложение может настроить dmNup на DMNUP_ONEUP, если оно намерено выполнять печать "N-up" самостоятельно.

Этот элемент не используется для дисплеев.

dmDisplayFrequency

Для дисплеев указывает частоту (в герцах) устройства отображения в текущем режиме.

Этот элемент не используется для принтеров.

dmICMMethod

Указывает одну из констант с префиксом DMICMMETHOD, определенных в wingdi.h.

dmICMIntent

Указывает одну из констант с префиксом DMICM, определенных в wingdi.h.

dmMediaType

Указывает одну из констант с префиксом DMMEDIA, определенных в wingdi.h.

dmDitherType

Указывает одну из констант с префиксом DMDITHER, определенных в wingdi.h.

dmReserved1

Зарезервировано для системного использования и должно игнорироваться драйвером.

dmReserved2

Зарезервировано для системного использования и должно игнорироваться драйвером.

dmPanningWidth

Зарезервировано для системного использования и должно игнорироваться драйвером.

dmPanningHeight

Зарезервировано для системного использования и должно игнорироваться драйвером.

Структура DEVMODEW — это версия структуры DEVMODE в Юникоде (описанная в документации по Microsoft Windows SDK). Хотя приложения могут использовать версию структуры ANSI или Юникод, драйверы должны использовать версию Юникода.

Для драйверов принтеров структура DEVMODEW используется для указания характеристик принтера, необходимых для печатного документа. Он также используется для указания характеристик принтера по умолчанию.

Сразу после определенных элементов структуры DEVMODEW (часто называемых ее общедоступными членами) может быть набор элементов, определенных драйвером (часто называемых частными элементами DEVMODEW). Драйвер предоставляет размер этой частной области в байтах в dmDriverExtra. Определенные драйвером частные члены предназначены для исключительного использования драйвером. Начальный адрес для закрытых членов можно указать с помощью члена dmSize следующим образом:

PVOID pvDriverData = (PVOID) (((BYTE *) pdm) + (pdm->dmSize));

Драйвер может полагаться на очередь очереди очереди для передачи буфера DEVMODEW размером не меньше байтов (dmSize + dmDriverExtra). В результате драйвер может безопасно считывать это количество байтов, начиная с начала буфера, не вызывая нарушения доступа и не пробуя память.

Перед воспроизведением EMF GDI вызывает диспетчер очереди очереди для проверки содержимого общедоступной части буфера DEVMODEW. Если буфер DEVMODEW не проходит проверочные тесты, выполненные в очереди очереди, GDI не передает буфер в драйвер принтера.

Предупреждение Windows только подтверждает, что общедоступная часть DEVMODEW действительна. Однако поврежденные данные в частной части структуры могут привести к сбою кода драйвера в приложении или в процессе очереди очереди. Следовательно, перед каждым использованием данных DEVMODEW драйвер должен убедиться, что частная часть DEVMODEW правильно сформирована.

В Windows 2000 в структуру DEVMODEW был добавлен новый член профсоюза . Этот член объединения содержит существующий член структуры DEVMODEW dmDisplayFlags вместе с новым членом dmNup. Этот элемент описан в предыдущем разделе Члены.

В Windows XP добавлен новый член структуры . Этот элемент структуры содержит существующий элемент структуры DEVMODEW dmPosition вместе с двумя новыми элементами: dmDisplayOrientation и dmDisplayFixedOutput. Эти элементы описаны в предыдущем разделе Члены.

Кроме того, для Windows XP несколько членов структуры DEVMODEW были перемещены в разные расположения в этой структуре. Члены dmScale, dmCopies, dmDefaultSource и dmPrintQuality были добавлены в элемент структуры , содержащий элементы dmOrientation, dmPaperSize, dmPaperLength и dmPaperWidth .

Примечание

Заголовок wingdi.h определяет DEVMODE как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.