Структура PRINTDLGEXA (commdlg.h)

Статья
07/21/2023

Содержит сведения, которые функция PrintDlgEx использует для инициализации страницы свойств Print. После закрытия пользователем страницы свойств система использует эту структуру для возврата сведений о выбранных пользователем параметрах.

Синтаксис

typedef struct tagPDEXA {
  DWORD            lStructSize;
  HWND             hwndOwner;
  HGLOBAL          hDevMode;
  HGLOBAL          hDevNames;
  HDC              hDC;
  DWORD            Flags;
  DWORD            Flags2;
  DWORD            ExclusionFlags;
  DWORD            nPageRanges;
  DWORD            nMaxPageRanges;
  LPPRINTPAGERANGE lpPageRanges;
  DWORD            nMinPage;
  DWORD            nMaxPage;
  DWORD            nCopies;
  HINSTANCE        hInstance;
  LPCSTR           lpPrintTemplateName;
  LPUNKNOWN        lpCallback;
  DWORD            nPropertyPages;
  HPROPSHEETPAGE   *lphPropertyPages;
  DWORD            nStartPage;
  DWORD            dwResultAction;
} PRINTDLGEXA, *LPPRINTDLGEXA;

Члены

lStructSize

Тип: DWORD

Размер структуры в байтах.

hwndOwner

Тип: HWND

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

hDevMode

Тип: HGLOBAL

Дескриптор перемещаемого объекта глобальной памяти, содержащего структуру DEVMODE . Если для входных данных hDevMode не задано значение NULL , необходимо выделить перемещаемый блок памяти для структуры DEVMODE и инициализировать ее элементы. Функция PrintDlgEx использует входные данные для инициализации элементов управления на странице свойств. Когда Функция PrintDlgEx возвращается, члены DEVMODE указывают входные данные пользователя.

Если для входных данных hDevMode имеет значение NULL , PrintDlgEx выделяет память для структуры DEVMODE , инициализирует ее члены, чтобы указать входные данные пользователя, и возвращает дескриптор, который идентифицирует его.

Дополнительные сведения об элементах hDevMode и hDevNames см. в разделе Примечания в конце этой статьи.

hDevNames

Тип: HGLOBAL

Дескриптор перемещаемого объекта глобальной памяти, содержащего структуру DEVNAMES . Если hDevNames не имеет значение NULL для входных данных, необходимо выделить перемещаемый блок памяти для структуры DEVNAMES и инициализировать его члены. Функция PrintDlgEx использует входные данные для инициализации элементов управления на странице свойств. При возврате PrintDlgEx члены DEVNAMES содержат сведения о принтере, выбранном пользователем. Эти сведения можно использовать для создания контекста устройства или контекста сведений.

Член hDevNames может иметь значение NULL. В этом случае PrintDlgEx выделяет память для структуры DEVNAMES , инициализирует ее члены, чтобы указать входные данные пользователя, и возвращает дескриптор, который идентифицирует его.

Дополнительные сведения об элементах hDevMode и hDevNames см. в разделе Примечания в конце этой статьи.

hDC

Тип: HDC

Дескриптор контекста устройства или контекста сведений в зависимости от того, указывает ли элемент Flags флаг PD_RETURNDC или флаг PC_RETURNIC . Если ни флаг не указан, то значение этого элемента не определено. Если указаны оба флага, PD_RETURNDC имеет приоритет. Если hDC не имеет значение NULL, необходимо вызвать DeleteDC , чтобы освободить объект GDI после того, как он больше не нужен. В противном случае при вызове API PrintDlgw будет происходить утечка объектов GDI.

Flags

Тип: DWORD

Набор битовых флагов, которые можно использовать для инициализации страницы свойств Print . Когда функция PrintDlgEx возвращается, она устанавливает эти флаги для указания входных данных пользователя. Этот элемент может быть одним или несколькими из следующих значений.

Чтобы гарантировать, что PrintDlg или PrintDlgEx возвращает правильные значения в членах dmCopies и dmCollate структуры DEVMODE , задайте PD_RETURNDC = TRUE и PD_USEDEVMODECOPIESANDCOLLATE = TRUE. При этом член nCopies структуры PRINTDLG всегда равен 1, а PD_COLLATE всегда имеет значение FALSE.

Чтобы гарантировать, что PrintDlg или PrintDlgEx возвращают правильные значения в nCopies и PD_COLLATE, задайте PD_RETURNDC = TRUE и PD_USEDEVMODECOPIESANDCOLLATE = FALSE. При этом dmCopies всегда имеет значение 1, а dmCollate всегда имеет значение FALSE.

Начиная с Windows Vista при вызове PrintDlg или PrintDlgEx с PD_RETURNDC задано значение TRUE , а PD_USEDEVMODECOPIESANDCOLLATE — false, функция PrintDlg или PrintDlgEx задает количество копий в элементе nCopies структуры PRINTDLG и количество копий в структуре, представленной элементом HDC структуры PRINTDLG .

При вызове GDI необходимо игнорировать значение nCopies, учитывать значение 1 и использовать возвращенный HDC , чтобы избежать печати повторяющихся копий.

Значение	Значение
PD_ALLPAGES 0x00000000	Флаг по умолчанию, указывающий, что переключатель Все изначально выбран. Этот флаг используется в качестве заполнителя, чтобы указать, что флаги PD_PAGENUMS, PD_SELECTION и PD_CURRENTPAGE не указаны.
PD_COLLATE 0x00000010	Если этот флаг установлен, выбрано поле Сортировка проверка. Если этот флаг установлен при возврате функции PrintDlgEx , приложение должно имитировать параметры сортировки нескольких копий. Дополнительные сведения см. в описании флага PD_USEDEVMODECOPIESANDCOLLATE . См . PD_NOPAGENUMS.
PD_CURRENTPAGE 0x00400000	Если этот флаг установлен, выбран переключатель Текущая страница . Если ни один из флагов PD_PAGENUMS, PD_SELECTION или PD_CURRENTPAGE не установлен, выбран переключатель Все .
PD_DISABLEPRINTTOFILE 0x00080000	Отключает поле Печать в файл проверка.
PD_ENABLEPRINTTEMPLATE 0x00004000	Указывает, что элементы hInstance и lpPrintTemplateName определяют замену шаблона диалогового окна по умолчанию в нижней части страницы Общие . Шаблон по умолчанию содержит элементы управления, аналогичные элементам диалогового окна Печать . Система использует указанный шаблон для создания окна, которое является дочерним элементом страницы Общие .
PD_ENABLEPRINTTEMPLATEHANDLE 0x00010000	Указывает, что элемент hInstance идентифицирует блок данных, содержащий предварительно загруженный шаблон диалогового окна. Этот шаблон заменяет шаблон диалогового окна по умолчанию в нижней части страницы Общие . Система использует указанный шаблон для создания окна, которое является дочерним элементом страницы Общие . Если этот флаг указан, система игнорирует элемент lpPrintTemplateName .
PD_EXCLUSIONFLAGS 0x01000000	Указывает, что элемент ExclusionFlags определяет элементы, которые должны быть исключены из страниц свойств драйвера принтера. Если этот флаг не установлен, элементы по умолчанию будут исключены из страниц свойств драйвера принтера. Исключения предотвращают дублирование элементов на странице Общие , на всех страницах, указанных приложением, и на страницах драйвера принтера.
PD_HIDEPRINTTOFILE 0x00100000	Скрывает поле Печать в файл проверка.
PD_NOCURRENTPAGE 0x00800000	Отключает переключатель Текущая страница .
PD_NOPAGENUMS 0x00000008	Отключает переключатель Страницы и связанные элементы управления редактированием. Кроме того, в диалоговом окне появляется поле Сортировка проверка.
PD_NOSELECTION 0x00000004	Отключает переключатель Выбор .
PD_NOWARNING 0x00000080	Предотвращает отображение предупреждающего сообщения при возникновении ошибки.
PD_PAGENUMS 0x00000002	Если этот флаг установлен, выбран переключатель Страницы . Если ни один из флагов PD_PAGENUMS, PD_SELECTION или PD_CURRENTPAGE не установлен, выбран переключатель Все . Если этот флаг установлен при возврате функции PrintDlgEx , то элемент lpPageRanges указывает диапазоны страниц, заданные пользователем.
PD_PRINTTOFILE 0x00000020	Если этот флаг установлен, будет выбрано поле Печать в файл проверка. Если этот флаг установлен при возврате PrintDlgEx , смещение, указанное членом wOutputOffset структуры DEVNAMES , содержит строку FILE:. При вызове функции StartDoc для запуска операции печати укажите эту строку FILE:в элементе lpszOutput структуры DOCINFO . Если указать эту строку, подсистема печати запрашивает у пользователя имя выходного файла.
PD_RETURNDC 0x00000100	Заставляет PrintDlgEx возвращать контекст устройства, соответствующий выбранным пользователем на странице свойств. Контекст устройства возвращается в HDC.
PD_RETURNDEFAULT 0x00000400	Если этот флаг установлен, функция PrintDlgEx не отображает страницу свойств. Вместо этого он задает элементы hDevNames и hDevMode для обработки в структурах DEVNAMES и DEVMODE , которые инициализируются для системного принтера по умолчанию. Значения hDevNames и hDevMode должны иметь значение NULL, иначе PrintDlgEx возвращает ошибку.
PD_RETURNIC 0x00000200	Аналогично флагу PD_RETURNDC , за исключением того, что этот флаг возвращает контекст сведений, а не контекст устройства. Если ни PD_RETURNDC , ни PD_RETURNIC не указаны, hDC не определен в выходных данных.
PD_SELECTION 0x00000001	Если этот флаг установлен, будет выбран переключатель Выбор . Если ни один из флагов PD_PAGENUMS, PD_SELECTION или PD_CURRENTPAGE не установлен, установлен переключатель Все .
PD_USEDEVMODECOPIES 0x00040000	То же, что и PD_USEDEVMODECOPIESANDCOLLATE.
PD_USEDEVMODECOPIESANDCOLLATE 0x00040000	Этот флаг указывает, поддерживает ли приложение несколько копий и параметров сортировки. Установите этот флаг для входных данных, чтобы указать, что приложение не поддерживает несколько копий и параметров сортировки. В этом случае элемент nCopies структуры PRINTDLGEX всегда возвращает значение 1, а PD_COLLATE никогда не устанавливается в элементе Flags . Если этот флаг не установлен, приложение отвечает за печать и сортировку нескольких копий. В этом случае элемент nCopies структуры PRINTDLGEX указывает количество копий, которые пользователь хочет напечатать, а флаг PD_COLLATE в элементе Flags указывает, требуется ли пользователю параметров сортировки. Независимо от того, установлен ли этот флаг, приложение может определить на основе nCopies и PD_COLLATE , сколько копий необходимо отобразить и следует ли печатать их с сортировкой. Если этот флаг установлен и драйвер принтера не поддерживает несколько копий, элемент управления редактирования копий отключен. Аналогичным образом, если этот флаг установлен и драйвер принтера не поддерживает параметры сортировки, поле Проверка сортировки отключается. Элементы dmCopies и dmCollate структуры DEVMODE содержат сведения о копировании и сортировке, используемые драйвером принтера. Если этот флаг установлен и драйвер принтера поддерживает несколько копий, элемент dmCopies указывает количество копий, запрошенных пользователем. Если этот флаг установлен и драйвер принтера поддерживает параметры сортировки, член dmCollate структуры DEVMODE указывает, требуется ли пользователю выполнять сортировку. Если этот флаг не задан, элемент dmCopies всегда возвращает значение 1, а член dmCollate всегда равен нулю. В версиях Windows, предшествующих Windows Vista, если этот флаг не задан вызывающим приложением и член dmCopies структуры DEVMODE больше 1, используйте это значение для количества копий; В противном случае используйте значение элемента nCopies структуры PRINTDLGEX .
PD_USELARGETEMPLATE 0x10000000	Заставляет страницу свойств использовать большой шаблон для страницы Общие . Более крупный шаблон предоставляет больше места для приложений, которые указывают пользовательский шаблон для нижней части страницы Общие .

Flags2

Тип: DWORD

ExclusionFlags

Тип: DWORD

Набор битовых флагов, которые могут исключать элементы из страниц свойств драйвера принтера на странице свойств Печать . Это значение используется только в том случае, если флаг PD_EXCLUSIONFLAGS установлен в элементе Flags . Флаги исключения следует использовать только в том случае, если исключенный элемент будет включен на страницу Общие или на страницу, определяемую приложением, на странице свойств Печать . Этот член может указать следующий флаг.

PD_EXCL_COPIESANDCOLLATE

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

nPageRanges

Тип: DWORD

На входных данных задайте для этого элемента начальное число диапазонов страниц, указанное в массиве lpPageRanges . Когда функция PrintDlgEx возвращает значение nPageRanges , указывает количество заданных пользователем диапазонов страниц, хранящихся в массиве lpPageRanges . Если указан флаг PD_NOPAGENUMS , это значение недопустимо.

nMaxPageRanges

Тип: DWORD

Размер буфера lpPageRanges в элементах массива. Это значение указывает максимальное количество диапазонов страниц, которые могут храниться в массиве. Если указан флаг PD_NOPAGENUMS , это значение недопустимо. Если флаг PD_NOPAGENUMS не указан, это значение должно быть больше нуля.

lpPageRanges

Тип: LPPRINTPAGERANGE

Указатель на буфер, содержащий массив структур PRINTPAGERANGE . Во входных данных массив содержит начальные диапазоны страниц, отображаемые в элементе управления "Редактирование страниц". При возврате функции PrintDlgEx массив содержит диапазоны страниц, указанные пользователем. Если указан флаг PD_NOPAGENUMS , это значение недопустимо. Если флаг PD_NOPAGENUMS не указан, lpPageRanges должен иметь значение, отличное от NULL.

nMinPage

Тип: DWORD

Минимальное значение для диапазонов страниц, указанных в элементе управления "Редактирование страниц". Если указан флаг PD_NOPAGENUMS , это значение недопустимо.

nMaxPage

Тип: DWORD

Максимальное значение для диапазонов страниц, указанных в элементе управления Редактирование Страницы . Если указан флаг PD_NOPAGENUMS , это значение недопустимо.

nCopies

Тип: DWORD

Содержит начальное количество копий для элемента управления редактирования Копий , если hDevMode имеет значение NULL; В противном случае элемент dmCopies структуры DEVMODE содержит начальное значение. При возврате PrintDlgExnCopies содержит фактическое количество копий, которые приложение должно напечатать. Это значение зависит от того, отвечает ли приложение или драйвер принтера за печать нескольких копий. Если флаг PD_USEDEVMODECOPIESANDCOLLATE установлен в элементе Flags , nCopies всегда равно 1 при возврате, а драйвер принтера отвечает за печать нескольких копий. Если флаг не задан, приложение отвечает за печать количества копий, указанного nCopies. Дополнительные сведения см. в описании флага PD_USEDEVMODECOPIESANDCOLLATE .

hInstance

Тип: HINSTANCE

Если флаг PD_ENABLEPRINTTEMPLATE задан в элементе Flags , hInstance — это дескриптор экземпляра приложения или модуля, который содержит шаблон диалогового окна с именем члена lpPrintTemplateName . Если флаг PD_ENABLEPRINTTEMPLATEHANDLE установлен в элементе Flags , hInstance — это дескриптор объекта памяти, содержащего шаблон диалогового окна. Если ни один из флагов шаблона не задан в элементе Flags , параметр hInstance должен иметь значение NULL.

lpPrintTemplateName

Тип: LPCTSTR

Имя ресурса шаблона диалогового окна в модуле, определяемом элементом hInstance . Этот шаблон заменяет шаблон диалогового окна по умолчанию в нижней части страницы Общие . Шаблон по умолчанию содержит элементы управления, аналогичные элементам диалогового окна Печать . Этот элемент игнорируется, если в элементе Flags не установлен флаг PD_ENABLEPRINTTEMPLATE.

lpCallback

Тип: LPUNKNOWN

Указатель на объект обратного вызова, определяемый приложением.

Объект должен содержать класс IPrintDialogCallback для получения сообщений для дочернего диалогового окна в нижней части страницы Общие .

Объект обратного вызова также должен содержать класс IObjectWithSite для получения указателя на интерфейс IPrintDialogServices . Функция PrintDlgEx вызывает IUnknown::QueryInterface в объекте обратного вызова для IID_IPrintDialogCallback и IID_IObjectWithSite , чтобы определить, какие интерфейсы поддерживаются.

Если вы не хотите получать какие-либо сведения о обратном вызове, задайте для lpCallbackзначение NULL.

nPropertyPages

Тип: DWORD

Число дескрипторов страниц свойства в массиве lphPropertyPages .

lphPropertyPages

Тип: HPROPSHEETPAGE*

Содержит массив дескрипторов страниц свойств для добавления на страницу свойств Печать . Дополнительные страницы свойств следуют за страницей Общие . Используйте функцию CreatePropertySheetPage для создания этих дополнительных страниц. При возврате функции PrintDlgEx все дескрипторы HPROPSHEETPAGE в массиве lphPropertyPages были уничтожены . Если значение nPropertyPages равно нулю, значение lphPropertyPages должно иметь значение NULL.

nStartPage

Тип: DWORD

Страница свойств, которая отображается изначально. Чтобы отобразить страницу Общие , укажите START_PAGE_GENERAL. В противном случае укажите отсчитываемый от нуля индекс страницы свойств в массиве, указанном в элементе lphPropertyPages . Для обеспечения согласованности рекомендуется всегда запускать страницу свойств на странице Общие .

dwResultAction

Тип: DWORD

Во входных данных задайте для этого элемента нулевое значение. Если функция PrintDlgEx возвращает S_OK, dwResultAction содержит результат диалога. Если PrintDlgEx возвращает ошибку, этот элемент следует игнорировать. Элемент dwResultAction может быть одним из следующих значений.

PD_RESULT_APPLY

Пользователь нажал кнопку Применить , а затем кнопку Отмена . Это означает, что пользователь хочет применить изменения, внесенные на лист свойств, но пока не хочет печатать. Структура PRINTDLGEX содержит сведения, указанные пользователем во время нажатия кнопки Применить .

PD_RESULT_CANCEL

Пользователь нажал кнопку Отмена . Сведения в структуре PRINTDLGEX не изменяются.

PD_RESULT_PRINT

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

Если hDevMode и hDevNames имеют значение NULL, PrintDlgEx инициализирует лист свойств с помощью текущего принтера по умолчанию. Чтобы инициализировать страницу свойств для другого принтера, используйте элемент wDeviceOffset структуры DEVNAMES , чтобы указать имя принтера.

Обратите внимание, что элемент dmDeviceName структуры DEVMODE также указывает имя принтера. Однако длина dmDeviceName ограничена 32 символами, а имя wDeviceOffset — нет. Если имена wDeviceOffset и dmDeviceName не совпадают, PrintDlgEx инициализирует лист свойств с помощью принтера, указанного в wDeviceOffset.

Если флаг PD_RETURNDEFAULT установлен, а hDevMode и hDevNames имеют значение NULL, PrintDlgEx использует элементы hDevNames и hDevMode для возврата сведений о текущем принтере по умолчанию без отображения диалогового окна.

Во время выполнения PrintDlgEx структуры DEVMODE и DEVNAMES , указанные в структуре PRINTDLGEX , не всегда могут содержать текущие данные. По этой причине страницы свойств приложения, а также подпрограммы IPrintDialogCallback для начальной страницы должны использовать интерфейс IPrintDialogServices для получения сведений о состоянии текущего принтера.

Примечание

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

Требования


Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Верхняя часть	commdlg.h (включая Windows.h)