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

Содержит сведения, которые функция 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 , чтобы избежать печати повторяющихся копий.

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 для получения сведений о состоянии текущего принтера.

Требования

См. также раздел

Общая библиотека диалоговых окон

Основные понятия

DEVMODE

DEVNAMES

IPrintDialogCallback

IPrintDialogServices

PrintDlgEx

Справочные материалы