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 物件之後釋出 GDI 物件;否則，每當您呼叫 PrintDlgw API 時，就會洩漏 GDI 物件。

Flags

類型： DWORD

一組位旗標，可用來初始化 Print 屬性工作表。 當 PrintDlgEx 函式傳回時，它會設定這些旗標來指出使用者的輸入。 這個成員可以是下列一或多個值。

若要確保PrintDlg 或 PrintDlgEx會傳回DEVMODE結構之 dmCopies和dmCollate成員中的正確值，請設定PD_RETURNDC = TRUE，並PD_USEDEVMODECOPIESANDCOLLATE = TRUE。 如此一來，PRINTDLG結構的nCopies成員一律為 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函式會設定PRINTDLG結構的nCopies成員中的複本數目，並設定PRINTDLG結構hDC成員所代表的結構中的複本數目。

呼叫 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
 停用 Pages 選項按鈕和相關聯的編輯控制項。 此外，它會導致 [ 定序 ] 核取方塊出現在對話方塊中。
PD_NOSELECTION
0x00000004
 停用 [ 選取範圍 ] 選項按鈕。
PD_NOWARNING
0x00000080
 防止在發生錯誤時顯示警告訊息。
PD_PAGENUMS
0x00000002
 如果設定此旗標，則會選取 [頁面 ] 選項按鈕。 如果未設定 任何PD_PAGENUMS、 PD_SELECTION或 PD_CURRENTPAGE 旗標，則會選取 [ 所有 ] 選項按鈕。 如果 PrintDlgEx 函式傳回時設定此旗標， lpPageRanges 成員會指出使用者指定的頁面範圍。
PD_PRINTTOFILE
0x00000020
 如果設定此旗標，則會選取 [ 列印至檔案 ] 核取方塊。 如果在PrintDlgEx傳回時設定此旗標，DEVNAMES結構的wOutputOffset成員所表示的位移會包含字串 「FILE：」。 當您呼叫StartDoc函式以啟動列印工作時，請在DOCINFO結構的lpszOutput成員中指定這個 「FILE：」 字串。 指定此字串會導致列印子系統查詢使用者輸入輸出檔的名稱。
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
 此旗標指出您的應用程式是否支援多個複本和定序。 在輸入上設定此旗標，表示您的應用程式不支援多個複本和定序。 在此情況下，PRINTDLGEX結構的nCopies成員一律會傳回 1，而且永遠不會在Flags成員中設定PD_COLLATE。

如果未設定此旗標，應用程式會負責列印和定序多個複本。 在此情況下，PRINTDLGEX結構的nCopies成員會指出使用者想要列印的複本數目，而 Flags成員中的PD_COLLATE旗標會指出使用者是否想要定序。

無論是否已設定此旗標，應用程式都可以從 nCopies 判斷，並 PD_COLLATE 要轉譯的複本數目，以及是否要列印它們定序。

如果已設定此旗標，且印表機驅動程式不支援多個複本，則會停用 [複製 ] 編輯控制項。 同樣地，如果已設定此旗標，且印表機驅動程式不支援定序，則會停用 [定序 ] 核取方塊。

DEVMODE結構的dmCopies和dmCollate成員包含印表機驅動程式所使用的複本和定序資訊。 如果已設定此旗標，且印表機驅動程式支援多個複本， dmCopies 成員會指出使用者所要求的複本數目。 如果已設定此旗標，且印表機驅動程式支援定序，DEVMODE結構的dmCollate成員會指出使用者是否想要定序。 如果未設定此旗標， dmCopies 成員一律會傳回 1，而 dmCollate 成員一律為零。

在 Windows Vista 之前的 Windows 版本中，如果呼叫的應用程式未設定此旗標，且DEVMODE結構的dmCopies成員大於 1，請將該值用於複本數目;否則，請使用PRINTDLGEX結構的nCopies成員值。
PD_USELARGETEMPLATE
0x10000000
 強制屬性表使用 [ 一般 ] 頁面的大型範本。 較大的範本為應用程式提供更多空間，這些應用程式會針對 [一般 ] 頁面的下半部指定自訂範本。

Flags2

類型： DWORD

ExclusionFlags

類型： DWORD

一組位旗標，可從 Print 屬性工作表中的印表機驅動程式屬性頁中排除專案。 只有在Flags成員中設定PD_EXCLUSIONFLAGS旗標時，才會使用此值。 只有在要排除的專案會包含在 [一般 ] 頁面或 [列印 ] 屬性工作表中應用程式定義的頁面上時，才應該使用排除旗標。 這個成員可以指定下列旗標。

PD_EXCL_COPIESANDCOLLATE

從Print屬性工作表中的印表機驅動程式屬性頁排除[複製] 和 [定序] 控制項。 當應用程式使用Print屬性工作表之 [一般] 頁面下方部分所提供的預設 [複製] 和 [定序] 控制項時，應該一律設定此旗標。

nPageRanges

類型： DWORD

在輸入時，將此成員設定為 lpPageRanges 陣列中指定的頁面範圍初始數目。 當 PrintDlgEx 函式傳回時， nPageRanges 會指出 儲存在 lpPageRanges 陣列中的使用者指定頁面範圍數目。 如果指定 PD_NOPAGENUMS 旗標，這個值無效。

nMaxPageRanges

類型： DWORD

lpPageRanges緩衝區的大小，以陣列元素為單位。 這個值表示可以儲存在陣列中的頁面範圍數目上限。 如果指定 PD_NOPAGENUMS 旗標，這個值無效。 如果未指定 PD_NOPAGENUMS 旗標，這個值必須大於零。

lpPageRanges

類型： LPPRINTPAGERANGE

緩衝區的指標，其中包含 PRINTPAGERANGE 結構的陣列。 在輸入時，陣列包含要顯示在 Pages 編輯控制項中的初始頁面範圍。 當 PrintDlgEx 函式傳回時，陣列會包含使用者指定的頁面範圍。 如果指定 PD_NOPAGENUMS 旗標，這個值無效。 如果未指定 PD_NOPAGENUMS 旗標， lpPageRanges 必須是非Null。

nMinPage

類型： DWORD

Pages編輯控制項中指定的頁面範圍的最小值。 如果指定 PD_NOPAGENUMS 旗標，這個值無效。

nMaxPage

類型： DWORD

Pages編輯控制項中指定的頁面範圍最大值。 如果指定 PD_NOPAGENUMS 旗標，這個值無效。

nCopies

類型： DWORD

如果hDevMode為Null，則包含複製編輯控制項的初始複本數目;否則，DEVMODE結構的dmCopies成員會包含初始值。 當 PrintDlgEx 傳回時， nCopies 包含應用程式必須列印的實際複本數目。 此值取決於應用程式或印表機驅動程式是否負責列印多個複本。 如果在Flags成員中設定PD_USEDEVMODECOPIESANDCOLLATE旗標，則 nCopies一律會傳回 1，印表機驅動程式負責列印多個複本。 如果未設定旗標，應用程式會負責列印 nCopies所指定的複本數目。 如需詳細資訊，請參閱 PD_USEDEVMODECOPIESANDCOLLATE 旗標的描述。

hInstance

類型： HINSTANCE

如果旗標成員中設定了PD_ENABLEPRINTTEMPLATE旗標，hInstance是應用程式或模組實例的控制碼，其中包含lpPrintTemplateName成員所命名的對話方塊範本。 如果在Flags成員中設定PD_ENABLEPRINTTEMPLATEHANDLE旗標，hInstance是包含對話方塊範本的記憶體物件控制碼。 如果旗標成員中未設定任一範本旗 標 ， 則 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*

包含要加入至 Print 屬性工作表的屬性頁控制碼陣列。 其他屬性頁遵循 [一般 ] 頁面。 使用 CreatePropertySheetPage 函式來建立這些額外的頁面。 當PrintDlgEx函式傳回時，lphPropertyPages陣列中的所有HPROPSHEETPAGE控制碼都已經終結。 如果 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 會使用目前的預設印表機初始化屬性工作表。 若要初始化不同印表機的屬性工作表，請使用DEVNAMES結構的wDeviceOffset成員來指定印表機的名稱。

請注意，DEVMODE結構的dmDeviceName成員也會指定印表機名稱。 不過， dmDeviceName 限制為 32 個字元， wDeviceOffset 名稱則不是。 如果 wDeviceOffset 和 dmDeviceName 名稱不相同， PrintDlgEx 會使用 wDeviceOffset指定的印表機初始化屬性工作表。

如果已設定PD_RETURNDEFAULT旗標，且 hDevMode 和 hDevNames 都是 Null， PrintDlgEx 會使用 hDevNames 和 hDevMode 成員傳回目前預設印表機的相關資訊，而不顯示對話方塊。

在執行PrintDlgEx期間，您在PRINTDLGEX結構中指定的DEVMODE和DEVNAMES結構不一定會包含目前的資料。 基於這個理由，初始頁面的應用程式特定屬性頁和 IPrintDialogCallback 常式應該使用 IPrintDialogServices 介面來擷取目前印表機狀態的相關資訊。

注意

commdlg.h 標頭會將 PRINTDLGEX 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程式碼，可能會導致編譯或執行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。

規格需求

   
最低支援的用戶端 Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器 Windows 2000 Server [僅限傳統型應用程式]
標頭 commdlg.h (包含 Windows.h)

另請參閱

通用對話方塊程式庫

概念

DEVMODE

DEVNAMES

IPrintDialogCallback

IPrintDialogServices

PrintDlgEx

參考