`CPrintDialog` 類別

發行項
07/05/2024

封裝 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。如需此結構的詳細資訊，請參閱 Windows SDK。

如果您未在中為 hDevMode 和 hDevNames 成員提供自己的句柄m_pd，請務必在完成對話框時，針對這些句柄呼叫 Windows 函GlobalFree式。使用所提供的 CWinApp::OnFilePrintSetup架構列印安裝實作時，您不需要釋放這些句柄。句柄會由 CWinApp 維護，並在的解構函式中 CWinApp釋出。只有在使用 CPrintDialog 獨立時，才需要釋放這些句柄。

初始化對話框控件之後，請呼叫 DoModal 成員函式以顯示對話框，並允許用戶選取列印選項。 DoModal會傳回使用者選取 [確定] 或IDOK [取消]IDCANCEL 按鈕。

如果 DoModal 傳 IDOK回，您可以使用其中 CPrintDialog一個成員函式來擷取使用者輸入的資訊。

成員 CPrintDialog::GetDefaults 函式適用於擷取目前的印表機預設值，而不顯示對話方塊。此成員函式不需要用戶互動。

您可以使用 Windows CommDlgExtendedError 函式來判斷對話方塊初始化期間是否發生錯誤，以及深入瞭解錯誤。如需此函式的詳細資訊，請參閱 Windows SDK。

CPrintDialog 依賴 COMMDLG.DLL 隨附於 Windows 3.1 版和更新版本的檔案。

若要自定義對話框，請從 CPrintDialog衍生類別、提供自定義對話框範本，以及新增訊息對應來處理擴充控件中的通知訊息。任何未處理的訊息都應該傳遞至基類。不需要自定義攔截函式。

若要根據對話框是 [列印] 或 [列印安裝程式] 而以不同的方式處理相同的訊息，您必須為每個對話框衍生類別。您也必須覆寫 Windows AttachOnSetup 函式，此函式會在 [列印安裝] 按鈕在 [列印] 對話框中選取時處理新對話框的建立。

如需使用 CPrintDialog的詳細資訊，請參閱通用對話框類別。

繼承階層架構

CPrintDialog

需求

標頭： afxdlgs.h

`CPrintDialog::CPrintDialog`

建構 Windows Print 或 Print Setup 對話框物件。

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如需這些旗標的詳細資訊，請參閱 Windows SDK 中的結構。

pParentWnd
對話框父視窗或擁有者視窗的指標。

備註

這個成員函式只會建構物件。 DoModal使用成員函式來顯示對話框。

請注意，當您呼叫設定為 FALSE的建構函式bPrintSetupOnly時，PD_RETURNDC會自動使用旗標。呼叫 DoModal、 GetDefaults或 GetPrinterDC之後，會在中 m_pd.hDC傳回印表機 DC。這個 DC 必須透過的呼叫者CPrintDialog呼叫 DeleteDC 來釋放。

範例

// 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`

從 DEVMODE 和 DEVNAMES 結構建立印表機裝置內容（DC）。

HDC CreatePrinterDC();

傳回值

處理新建立的印表機裝置內容。

備註

此 DC 假設為目前的印表機 DC，而且使用者必須刪除任何其他先前取得的印表機 DC。您可以呼叫此函式，並使用產生的 DC，而不會顯示 [列印] 對話方塊。

範例

// 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 是常數，指出使用者是否已選取 [ 確定 ] 或 [取消] 按鈕。

備註

如果您要藉由設定結構的成員 m_pd 來初始化各種列印對話框選項，您應該先執行此動作，再呼叫 DoModal，但在建構對話對象之後。

呼叫 DoModal之後，您可以呼叫其他成員函式，將用戶的設定或資訊輸入擷取到對話框中。

範例

請參閱 CPrintDialog::CreatePrinterDC 的範例。

`CPrintDialog::GetCopies`

擷取所要求的複本數目。

int GetCopies() const;

傳回值

要求的複本數目。

備註

呼叫之後呼叫 DoModal 此函式，以擷取所要求的複本數目。

範例

請參閱 CPrintDialog::PrintCollate 的範例。

`CPrintDialog::GetDefaults`

擷取預設印表機的裝置預設值，而不顯示對話框。

BOOL GetDefaults();

傳回值

如果函式成功，則為非零;否則為 0。

備註

擷取的值會放在結構中 m_pd 。

在某些情況下，對這個函式的呼叫將會呼叫的建構函式CPrintDialog，並將 bPrintSetupOnly 設定為 FALSE。在這些情況下，會自動配置印表機 DC 和 hDevNames 和 hDevMode （位於數據成員中的 m_pd 兩個句柄）。

如果的建構CPrintDialog函式已使用 bPrintSetupOnly 設為FALSE呼叫，則此函式不只會將和 hDevMode 中的 m_pd.hDevNames m_pd.hDevMode和傳回hDevNames給呼叫端，也會傳回中的m_pd.hDC印表機 DC。呼叫端負責刪除印表機 DC，並在完成CPrintDialog物件時呼叫句柄上的 Windows GlobalFree 函式。

範例

此代碼段會取得預設印表機的裝置內容，並向用戶報告每英吋點的印表機解析度。（印表機功能的這個屬性通常稱為 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 以擷取預設印表機的目前裝置預設值之後呼叫此函式。使用所GetDeviceName傳回之物件的指標CString做為呼叫CDC::CreateDC中的值lpszDeviceName。

範例

此代碼段會顯示使用者的預設印表機名稱和它所連接的埠，以及印表機所使用的多任務緩衝處理器名稱。例如，程式代碼可能會顯示消息框：「您的預設印表機是 \\server\share 上使用 winspool 的 HP LaserJet IIIP」。」。

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 函式來解除鎖定這個結構所取得的記憶體，Windows SDK 中所述。

備註

呼叫或 GetDefaults 之後DoModal呼叫此函式，以擷取列印裝置的相關信息。

範例

請參閱 CPrintDialog::PrintCollate 的範例。

`CPrintDialog::GetDriverName`

擷取目前選取的印表機驅動程序名稱。

CString GetDriverName() const;

傳回值

CString，指定系統定義的驅動程式名稱。

備註

呼叫或 GetDefaults 之後DoModal呼叫這個函式，以擷取系統定義的印表機設備驅動器的名稱。使用所GetDriverName傳回之物件的指標CString做為呼叫CDC::CreateDC中的值lpszDriverName。

範例

請參閱 CPrintDialog::GetDeviceName 的範例。

`CPrintDialog::GetFromPage`

擷取列印範圍的起始頁。

int GetFromPage() const;

傳回值

要列印之頁面範圍的起始頁碼。

備註

呼叫之後呼叫 DoModal 此函式，以擷取要列印之頁面範圍的起始頁碼。

範例

請參閱 CPrintDialog::m_pd 的範例。

`CPrintDialog::GetPortName`

擷取目前選取之印表機埠的名稱。

CString GetPortName() const;

傳回值

目前選取之印表機埠的名稱。

備註

呼叫或 GetDefaults 之後DoModal呼叫此函式，以擷取目前選取之印表機埠的名稱。

範例

請參閱 CPrintDialog：：GetDeviceName 的範例。

`CPrintDialog::GetPrinterDC`

擷取印表機裝置內容的句柄。

HDC GetPrinterDC() const;

傳回值

如果成功，則為印表機裝置內容的句柄;否則 NULL為。

備註

如果建 bPrintSetupOnly 構函式的參數 CPrintDialog 是 FALSE （表示顯示[列印] 對話框），則會 GetPrinterDC 傳回印表機裝置內容的句柄。當您完成使用 Windows 函式時，您必須呼叫 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 Windows SDK。

如果您直接修改 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`