Класс `CPrintDialog`

Статья
10/12/2023

Инкапсулирует службы, предоставляемые стандартным диалоговым окном Windows для печати.

Синтаксис

class CPrintDialog : public CCommonDialog

Участники

Открытые конструкторы

Имя	Описание
`CPrintDialog::CPrintDialog`	Формирует объект `CPrintDialog`.

Открытые методы

Имя	Описание
`CPrintDialog::CreatePrinterDC`	Создает контекст устройства принтера без отображения диалогового окна "Печать".
`CPrintDialog::DoModal`	Отображает диалоговое окно и позволяет пользователю выбирать.
`CPrintDialog::GetCopies`	Извлекает количество запрошенных копий.
`CPrintDialog::GetDefaults`	Извлекает значения по умолчанию устройства без отображения диалогового окна.
`CPrintDialog::GetDeviceName`	Извлекает имя выбранного устройства принтера.
`CPrintDialog::GetDevMode`	Извлекает структуру `DEVMODE` .
`CPrintDialog::GetDriverName`	Извлекает имя выбранного драйвера принтера.
`CPrintDialog::GetFromPage`	Извлекает начальную страницу диапазона печати.
`CPrintDialog::GetPortName`	Извлекает имя выбранного порта принтера.
`CPrintDialog::GetPrinterDC`	Извлекает дескриптор контекста устройства принтера.
`CPrintDialog::GetToPage`	Извлекает конечную страницу диапазона печати.
`CPrintDialog::PrintAll`	Определяет, следует ли печатать все страницы документа.
`CPrintDialog::PrintCollate`	Определяет, запрашиваются ли сортировка копий.
`CPrintDialog::PrintRange`	Определяет, следует ли печатать только указанный диапазон страниц.
`CPrintDialog::PrintSelection`	Определяет, следует ли печатать только выбранные в данный момент элементы.

Открытые члены данных

Имя	Описание
`CPrintDialog::m_pd`	Структура, используемая для настройки `CPrintDialog` объекта.

Замечания

Распространенные диалоговые окна печати предоставляют простой способ реализации диалоговых окон настройки печати и печати в соответствии со стандартами Windows.

Примечание.

Класс CPrintDialogEx инкапсулирует службы, предоставляемые листом свойств Windows Print. Дополнительные сведения см. в обзоре CPrintDialogEx .

CPrintDialogФункциональные возможности заменяются CPageSetupDialogтем, что предназначено для предоставления общего диалогового окна для настройки печати и настройки страницы.

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

Если вы хотите, чтобы приложение обрабатывало печать без участия платформы, можно использовать CPrintDialog класс "как есть" с предоставленным конструктором, или вы можете наследить собственный класс диалогов от CPrintDialog и написать конструктор в соответствии с вашими потребностями. В любом случае эти диалоговые окна будут вести себя как стандартные диалоговые окна MFC, так как они являются производными от класса CCommonDialog.

Чтобы использовать CPrintDialog объект, сначала создайте объект с помощью конструктора CPrintDialog . После создания диалогового окна можно задать или изменить любые значения в m_pd структуре, чтобы инициализировать значения элементов управления диалогового окна. Структура m_pd имеет тип PRINTDLG. Дополнительные сведения об этой структуре см. в пакете SDK для Windows.

Если вы не предоставляете собственные дескрипторы m_pd для элементов и hDevNames элементов, обязательно вызовите функцию GlobalFree Windows для этих дескрипторов при завершении работы с диалоговым hDevMode окном. При использовании реализации программы установки печати платформы, предоставленной CWinApp::OnFilePrintSetupне требуется освободить эти дескрипторы. Деструктор поддерживает деструктор и освобождает CWinAppдеструкторCWinApp. При использовании CPrintDialog автономных дескрипторов необходимо освободить только эти дескрипторы.

После инициализации элементов управления диалогового окна вызовите DoModal функцию-член, чтобы отобразить диалоговое окно и разрешить пользователю выбрать параметры печати. DoModalвозвращает значение, выбранное пользователем кнопкой "ОК" (IDOK) или "Отмена" (IDCANCEL).

Если DoModal возвращается IDOK, можно использовать одну из CPrintDialogфункций-членов для получения входных данных пользователем.

Функция-член CPrintDialog::GetDefaults полезна для получения текущего принтера по умолчанию без отображения диалогового окна. Эта функция-член не требует взаимодействия с пользователем.

Функцию Windows CommDlgExtendedError можно использовать, чтобы определить, произошла ли ошибка во время инициализации диалогового окна и узнать больше об ошибке. Дополнительные сведения об этой функции см. в пакете SDK для Windows.

CPrintDialogCOMMDLG.DLL использует файл, который поставляется с Windows версии 3.1 и более поздних версий.

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

Чтобы обрабатывать одно и то же сообщение по-разному в зависимости от того, является ли диалоговое окно "Печать" или "Настройка печати", необходимо наследовать класс для каждого диалогового окна. Кроме того, необходимо переопределить функцию Windows AttachOnSetup , которая обрабатывает создание нового диалогового окна при выборе кнопки "Настройка печати" в диалоговом окне "Печать".

Дополнительные сведения об использовании CPrintDialogсм. в разделе "Общие классы диалогов".

Иерархия наследования

CPrintDialog

Требования

Заголовок.afxdlgs.h

`CPrintDialog::CPrintDialog`

Создает диалоговое окно "Печать Windows" или "Настройка печати".

CPrintDialog(
    BOOL bPrintSetupOnly,
    DWORD dwFlags = PD_ALLPAGES | PD_USEDEVMODECOPIES | PD_NOPAGENUMS | PD_HIDEPRINTTOFILE | PD_NOSELECTION,
    CWnd* pParentWnd = NULL);

Параметры

bPrintSetupOnly
Указывает, отображается ли стандартное диалоговое окно "Печать Windows" или диалоговое окно "Настройка печати". Установите этот параметр для TRUE отображения стандартного диалогового окна установки печати Windows. Установите его для FALSE отображения диалогового окна "Печать Windows". Если bPrintSetupOnly это FALSEтак, кнопка "Настройка печати" по-прежнему отображается в диалоговом окне "Печать".

dwFlags
Один или несколько флагов, которые можно использовать для настройки параметров диалогового окна, в сочетании с побитовым оператором OR. Например, PD_ALLPAGES флаг задает диапазон печати по умолчанию для всех страниц документа. PRINTDLG Дополнительные сведения об этих флагах см. в структуре пакета SDK для Windows.

pParentWnd
Указатель на окно родительского или владельца диалогового окна.

Замечания

Эта функция-член создает только объект. Используйте функцию-член для DoModal отображения диалогового окна.

Обратите внимание, что при вызове конструктора с bPrintSetupOnly заданным значением FALSEPD_RETURNDC флаг используется автоматически. После вызова DoModalконтроллера GetDefaultsGetPrinterDCдомена принтера будет возвращен.m_pd.hDC Этот контроллер домена должен быть освобожден с вызовом DeleteDC вызывающего объекта CPrintDialog.

Пример

// Display the Windows Print dialog box with "All" radio button 
// initially selected. All other radio buttons are disabled.
CPrintDialog dlg1(FALSE);

// Display the Windows Print dialog box with Collate check box checked.  
CPrintDialog dlg2(FALSE, PD_ALLPAGES | PD_COLLATE | PD_NOPAGENUMS | PD_HIDEPRINTTOFILE);

// Display the Windows Print dialog box with "Selection" radio
// button initially selected. "All" radio button is enabled
// but "Pages" radio button is disabled.
CPrintDialog dlg3(FALSE, PD_SELECTION | PD_USEDEVMODECOPIES);

`CPrintDialog::CreatePrinterDC`

Создает контекст устройства принтера (DC) из DEVMODE структур и DEVNAMES структур.

HDC CreatePrinterDC();

Возвращаемое значение

Обработайте только что созданный контекст устройства принтера.

Замечания

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

Пример

// Display the Windows Print dialog box with "All" radio button 
// initially selected. All other radio buttons are disabled.
CPrintDialog dlg(FALSE);
if (dlg.DoModal() == IDOK)
{
   // Create a printer device context (DC) based on the information
   // selected from the Print dialog.
   HDC hdc = dlg.CreatePrinterDC();
   ASSERT(hdc);
}

`CPrintDialog::DoModal`

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

virtual INT_PTR DoModal();

Возвращаемое значение

IDOK или IDCANCEL. Если IDCANCEL возвращается, вызовите функцию Windows CommDlgExtendedError , чтобы определить, произошла ли ошибка.

IDOK и IDCANCEL являются константами, указывающими, выбран ли пользователь кнопку "ОК " или "Отмена ".

Замечания

Если вы хотите инициализировать различные параметры диалогового окна печати, задав элементы структуры, необходимо сделать это перед вызовомDoModal, но после создания объекта диалогового m_pd окна.

После вызова DoModalможно вызвать другие функции-члены, чтобы получить параметры или данные, введенные пользователем в диалоговом окне.

Пример

Пример см. в примере CPrintDialog::CreatePrinterDC.

`CPrintDialog::GetCopies`

Извлекает количество запрошенных копий.

int GetCopies() const;

Возвращаемое значение

Количество запрошенных копий.

Замечания

Вызовите эту функцию после вызова DoModal , чтобы получить количество запрошенных копий.

Пример

Пример см. в примере CPrintDialog::PrintCollate.

`CPrintDialog::GetDefaults`

Извлекает значения по умолчанию устройства принтера по умолчанию без отображения диалогового окна.

BOOL GetDefaults();

Возвращаемое значение

Ненулевое значение, если функция была успешной; в противном случае — 0.

Замечания

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

В некоторых случаях вызов этой функции вызывает конструктор с CPrintDialogbPrintSetupOnly заданным значением FALSE. В таких случаях контроллер домена принтера и hDevNameshDevMode (два дескриптора, расположенные в элементе m_pd данных), автоматически выделяются.

Если конструктор CPrintDialog для вызова был вызван с bPrintSetupOnly заданным значениемFALSE, эта функция не только возвращается hDevNames и hDevMode находится в m_pd.hDevNamesm_pd.hDevModeвызывающем объекте, но и возвращает контроллер домена принтера.m_pd.hDC Он несет ответственность за удаление контроллера домена принтера и вызов функции Windows GlobalFree на дескрипторах после завершения работы с CPrintDialog объектом.

Пример

Этот фрагмент кода получает контекст устройства принтера по умолчанию и сообщает пользователю разрешение принтера в точках на дюйм. (Этот атрибут возможностей принтера часто называется DPI.)

CPrintDialog dlg(FALSE);

if (!dlg.GetDefaults())
{
   AfxMessageBox(_T("You have no default printer!"));
}
else
{
   // attach to the DC we were given
   CDC dc;
   dc.Attach(dlg.m_pd.hDC);

   // ask for the measurements
   int nHorz = dc.GetDeviceCaps(LOGPIXELSX);
   int nVert = dc.GetDeviceCaps(LOGPIXELSY);

   // almost always the same in both directions, but sometimes not!
   CString str;
   if (nHorz == nVert)
   {
      str.Format(_T("Your printer supports %d pixels per inch"), nHorz);
   }
   else
   {
      str.Format(_T("Your printer supports %d pixels per inch ")
         _T("horizontal resolution, and %d pixels per inch vertical ")
         _T("resolution"), nHorz, nVert);
   }

   // tell the user
   AfxMessageBox(str);

   // Note: no need to call Detach() because we want the CDC destructor
   // to call FreeDC() on the DC we borrowed from the common dialog
}

`CPrintDialog::GetDeviceName`

Извлекает имя выбранного устройства принтера.

CString GetDeviceName() const;

Возвращаемое значение

Имя выбранного принтера.

Замечания

Вызовите эту функцию после вызова DoModal , чтобы получить имя выбранного принтера или после вызова GetDefaults для получения текущего устройства по умолчанию принтера. Используйте указатель на CString объект, возвращаемый GetDeviceName в качестве значения lpszDeviceName в вызове CDC::CreateDC.

Пример

В этом фрагменте кода показаны имя принтера пользователя по умолчанию и порт, к которому он подключен, а также имя spooler, к которому используется принтер. В коде может отображаться окно сообщения, которое говорит: "Принтер по умолчанию — HP LaserJet IIIP на \\server\server\share с помощью winspool". Например.

CPrintDialog dlg(FALSE);

if (!dlg.GetDefaults())
{
   AfxMessageBox(_T("You have no default printer!"));
}
else
{
   CString strDescription;

   strDescription.Format(_T("Your default printer is %s on %s using %s."),
      (LPCTSTR)dlg.GetDeviceName(),
      (LPCTSTR)dlg.GetPortName(),
      (LPCTSTR)dlg.GetDriverName());

   AfxMessageBox(strDescription);
}

`CPrintDialog::GetDevMode`

Извлекает структуру DEVMODE .

LPDEVMODE GetDevMode() const;

Возвращаемое значение

Структура DEVMODE данных, содержащая сведения об инициализации устройства и среде драйвера печати. Необходимо разблокировать память, взятую этой структурой, с помощью функции Windows GlobalUnlock , которая описана в пакете SDK для Windows.

Замечания

Вызовите эту функцию после вызова DoModal или GetDefaults получения сведений о устройстве печати.

Пример

Пример см. в примере CPrintDialog::PrintCollate.

`CPrintDialog::GetDriverName`

Извлекает имя выбранного драйвера принтера.

CString GetDriverName() const;

Возвращаемое значение

Указание CString системного имени драйвера.

Замечания

Вызовите эту функцию после вызова DoModal или GetDefaults получения имени драйвера устройства принтера, определенного системой. Используйте указатель на CString объект, возвращаемый GetDriverName в качестве значения lpszDriverName в вызове CDC::CreateDC.

Пример

Пример см. в примере CPrintDialog::GetDeviceName.

`CPrintDialog::GetFromPage`

Извлекает начальную страницу диапазона печати.

int GetFromPage() const;

Возвращаемое значение

Начальный номер страницы в диапазоне страниц для печати.

Замечания

Вызовите эту функцию после вызова DoModal , чтобы получить начальный номер страницы в диапазоне страниц для печати.

Пример

Пример см. в примере CPrintDialog::m_pd.

`CPrintDialog::GetPortName`

Извлекает имя выбранного порта принтера.

CString GetPortName() const;

Возвращаемое значение

Имя выбранного порта принтера.

Замечания

Вызовите эту функцию после вызова DoModal или GetDefaults получения имени выбранного порта принтера.

Пример

См. пример CPrintDialog ::GetDeviceName.

`CPrintDialog::GetPrinterDC`

Извлекает дескриптор контекста устройства принтера.

HDC GetPrinterDC() const;

Возвращаемое значение

Дескриптор контекста устройства принтера в случае успешного выполнения; в противном случае NULL.

Замечания

bPrintSetupOnly Если параметр конструктора CPrintDialog (указывает, что отображается диалоговое окно печати), возвращает GetPrinterDC дескриптор FALSE контексту устройства принтера. Чтобы удалить контекст устройства, необходимо вызвать функцию Windows DeleteDC , когда она будет выполнена.

Пример

CPrintDialog dlg(FALSE);
CPrintDialog dlg(FALSE);
if (dlg.DoModal() == IDOK)
{
   // Get a handle to the printer device context (DC).
   HDC hdc = dlg.GetPrinterDC();
   ASSERT(hdc);

   // Do something with the HDC...

   // Clean up.
   CDC::FromHandle(hdc)->DeleteDC();
}

`CPrintDialog::GetToPage`

Извлекает конечную страницу диапазона печати.

int GetToPage() const;

Возвращаемое значение

Конечный номер страницы в диапазоне страниц для печати.

Замечания

Вызовите эту функцию после вызова DoModal , чтобы получить конечный номер страницы в диапазоне страниц для печати.

Пример

Пример см. в примере CPrintDialog::m_pd.

`CPrintDialog::m_pd`

Структура, члены которой хранят характеристики объекта диалогового окна.

PRINTDLG& m_pd;

Замечания

После создания CPrintDialog объекта можно задать m_pd различные аспекты диалогового окна перед вызовом DoModal функции-члена. Дополнительные сведения о m_pd структуре см PRINTDLG . в пакете SDK для Windows.

При непосредственном m_pd изменении элемента данных вы переопределите любое поведение по умолчанию.

Пример

// Display the Windows Print dialog box with "Pages" radio button
// initially selected. "All" and "Pages" radio buttons are
// enabled as well.
CPrintDialog dlg(FALSE, PD_PAGENUMS | PD_USEDEVMODECOPIES);
dlg.m_pd.nMinPage = dlg.m_pd.nFromPage = 1;
dlg.m_pd.nMaxPage = dlg.m_pd.nToPage = 10;
if (dlg.DoModal() == IDOK)
{
   // Determine the starting and ending page numbers for the range 
   // of pages to be printed.

   int from_page = -1, to_page = -1;
   if (dlg.PrintAll())              // print all pages in the document
   {
      from_page = dlg.m_pd.nMinPage;
      to_page = dlg.m_pd.nMaxPage;
   }
   else if (dlg.PrintRange())       // print only a range of pages 
   {                                // in the document 
      from_page = dlg.GetFromPage();
      to_page = dlg.GetToPage();
   }
   else if (dlg.PrintSelection())   // print only the currently selected 
                                    // items
   {
      from_page = to_page = -1;     // -1 to denote unknown yet
   }

   TRACE(_T("Print from %d to %d\n"), from_page, to_page);
}

`CPrintDialog::PrintAll`

Определяет, следует ли печатать все страницы документа.

BOOL PrintAll() const;

Возвращаемое значение

Ненулевое значение, если все страницы в документе должны быть напечатаны; в противном случае — 0.

Замечания

Вызовите эту функцию после вызова DoModal , чтобы определить, следует ли печатать все страницы в документе.

Пример

Пример см. в примере CPrintDialog::m_pd.

`CPrintDialog::PrintCollate`

Определяет, запрашиваются ли сортировка копий.

BOOL PrintCollate() const;

Возвращаемое значение

Ненулевое значение, если пользователь выбирает поле сортировки проверка в диалоговом окне; в противном случае — значение 0.

Замечания

Вызовите эту функцию после вызова DoModal , чтобы определить, должен ли принтер сворачивать все печатные копии документа.

Пример

// Display the Windows Print dialog box with Collate check box checked.
CPrintDialog dlg(FALSE, PD_ALLPAGES | PD_COLLATE | PD_NOPAGENUMS |
   PD_HIDEPRINTTOFILE);
if (dlg.DoModal() == IDOK)
{
   // If the collate check box is selected, then GetCopies() will return
   // the number of copies printed. Otherwise, GetCopies() always 
   // returns 1. Then, the number of copies printed can be found from the
   // DEVMODE structure of the printing device.
   if (dlg.PrintCollate())
   {
      int num = dlg.GetCopies();
      TRACE(_T("Number of copies printed = %d\n"), num);
   }
   else
   {
      LPDEVMODE devmode = dlg.GetDevMode();
      TRACE(_T("Number of copies printed = %d\n"), devmode->dmCopies);
   }
}

`CPrintDialog::PrintRange`

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

BOOL PrintRange() const;

Возвращаемое значение

Ненулевое значение, если печатаются только диапазон страниц в документе; в противном случае — 0.

Замечания

Вызовите эту функцию после вызова DoModal , чтобы определить, следует ли печатать только диапазон страниц в документе.

Пример

Пример см. в примере CPrintDialog::m_pd.

`CPrintDialog::PrintSelection`

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

BOOL PrintSelection() const;

Возвращаемое значение

Ненулевое значение, если печатаются только выбранные элементы; в противном случае — 0.

Замечания

Вызовите эту функцию после вызова DoModal , чтобы определить, следует ли печатать только выбранные в данный момент элементы.

Пример

Пример см. в примере CPrintDialog::m_pd.

См. также

Пример MFC DIBLOOK
CCommonDialog Класса
Диаграмма иерархии
CPrintInfo Структура

Класс CPrintDialog

Синтаксис

Участники

Открытые конструкторы

Открытые методы

Открытые члены данных

Замечания

Иерархия наследования

Требования

CPrintDialog::CPrintDialog

Параметры

Замечания

Пример

CPrintDialog::CreatePrinterDC

Возвращаемое значение

Замечания

Пример

CPrintDialog::DoModal

Возвращаемое значение

Замечания

Пример

CPrintDialog::GetCopies

Возвращаемое значение

Замечания

Пример

CPrintDialog::GetDefaults

Возвращаемое значение

Замечания

Пример

CPrintDialog::GetDeviceName

Возвращаемое значение

Замечания

Пример

CPrintDialog::GetDevMode

Возвращаемое значение

Замечания

Пример

CPrintDialog::GetDriverName

Возвращаемое значение

Замечания

Пример

CPrintDialog::GetFromPage

Возвращаемое значение

Замечания

Пример

CPrintDialog::GetPortName

Возвращаемое значение

Замечания

Пример

CPrintDialog::GetPrinterDC

Возвращаемое значение

Замечания

Пример

CPrintDialog::GetToPage

Возвращаемое значение

Замечания

Пример

CPrintDialog::m_pd

Замечания

Пример

CPrintDialog::PrintAll

Возвращаемое значение

Замечания

Пример

CPrintDialog::PrintCollate

Возвращаемое значение

Замечания

Пример

CPrintDialog::PrintRange

Возвращаемое значение

Замечания

Пример

CPrintDialog::PrintSelection

Возвращаемое значение

Замечания

Пример

См. также

Обратная связь

Обратная связь

Дополнительные ресурсы

Класс `CPrintDialog`

`CPrintDialog::CPrintDialog`

`CPrintDialog::CreatePrinterDC`

`CPrintDialog::DoModal`

`CPrintDialog::GetCopies`

`CPrintDialog::GetDefaults`

`CPrintDialog::GetDeviceName`

`CPrintDialog::GetDevMode`

`CPrintDialog::GetDriverName`

`CPrintDialog::GetFromPage`

`CPrintDialog::GetPortName`

`CPrintDialog::GetPrinterDC`

`CPrintDialog::GetToPage`

`CPrintDialog::m_pd`

`CPrintDialog::PrintAll`

`CPrintDialog::PrintCollate`

`CPrintDialog::PrintRange`

`CPrintDialog::PrintSelection`