CDialog 類別

用於在螢幕上顯示對話方塊的基類。

語法

class CDialog : public CWnd

成員

公用建構函式

名稱 描述
CDialog::CDialog 建構 CDialog 物件。

公用方法

名稱 描述
CDialog::Create 初始化 CDialog 物件。 建立無強制回應對話方塊,並將它附加至 CDialog 物件。
CDialog::CreateIndirect 從記憶體中的對話方塊範本建立無強制回應對話方塊(而非以資源為基礎)。
CDialog::D oModal 呼叫強制回應對話方塊,並在完成時傳回。
CDialog::EndDialog 關閉強制回應對話方塊。
CDialog::GetDefID 取得對話方塊的預設按鈕控制項識別碼。
CDialog::GotoDlgCtrl 將焦點移至對話方塊中的指定對話方塊控制項。
CDialog::InitModalIndirect 從記憶體中的對話方塊範本建立強制回應對話方塊(而非以資源為基礎)。 參數會儲存在呼叫函式 DoModal 之前。
CDialog::MapDialogRect 將矩形的對話方塊單位轉換成螢幕單位。
CDialog::NextDlgCtrl 將焦點移至對話方塊中的下一個對話方塊控制項。
CDialog::OnInitDialog 覆寫以增強對話方塊初始化。
CDialog::OnSetFont 覆寫 以指定對話方塊控制項在繪製文字時要使用的字型。
CDialog::P revDlgCtrl 將焦點移至對話方塊中的上一個對話方塊控制項。
CDialog::SetDefID 將對話方塊的預設按鈕控制項變更為指定的按鈕。
CDialog::SetHelpID 設定對話方塊的內容相關說明識別碼。

受保護的方法

名稱 描述
CDialog::OnCancel 覆寫以執行 [取消] 按鈕或 ESC 鍵動作。 預設值會關閉對話方塊,並 DoModal 傳回 IDCANCEL。
CDialog::OnOK 覆寫以在強制回應對話方塊中執行 [確定] 按鈕動作。 預設值會關閉對話方塊並 DoModal 傳回 IDOK。

備註

對話方塊有兩種類型:強制回應和無模式。 使用者必須先關閉強制回應對話方塊,應用程式才會繼續。 無強制回應對話方塊可讓使用者顯示對話方塊,並返回另一個工作,而不取消或移除對話方塊。

CDialog物件是對話範本和 CDialog 衍生類別的組合。 使用對話方塊編輯器來建立對話範本,並將其儲存在資源中,然後使用 [新增類別精靈] 建立衍生自 CDialog 的類別。

對話方塊和任何其他視窗一樣,會從 Windows 接收訊息。 在對話方塊中,您特別想要處理來自對話方塊控制項的通知訊息,因為這是使用者與對話方塊互動的方式。 使用 [ 類別精靈 ] 選取您想要處理的訊息,並將適當的訊息對應專案和訊息處理常式成員函式新增至類別。 您只需要在處理常式成員函式中撰寫應用程式特定的程式碼。

如果您想要的話,您一律可以手動撰寫訊息對應專案和成員函式。

除了最簡單對話方塊外,您還可以將成員變數新增至衍生對話方塊類別,以儲存使用者所輸入對話方塊控制項中的資料,或顯示使用者的資料。 您可以使用 [新增變數精靈] 來建立成員變數,並將其與控制項產生關聯。 同時,您可以選擇變數類型和每個變數允許的值範圍。 程式碼精靈會將成員變數新增至衍生的對話類別。

會產生資料對應,以自動處理成員變數與對話方塊控制項之間的資料交換。 資料對應會提供函式,以適當的值初始化對話方塊中的控制項、擷取資料,以及驗證資料。

若要建立強制回應對話方塊,請使用衍生對話方塊類別的建構函式,在堆疊上建構 物件,然後呼叫 DoModal 以建立對話方塊視窗及其控制項。 如果您想要建立無模式對話,請在對話類別的建構函式中呼叫 Create

您也可以使用 DLGTEMPLATE 資料結構在記憶體中建立範本,如 Windows SDK 中所述。 建構 CDialog 物件之後,請呼叫 CreateIndirect 來建立無強制回應對話方塊,或呼叫 InitModalIndirect DoModal 來建立強制回應對話方塊。

交換和驗證資料對應是以 新增至新對話方塊類別的 CWnd::DoDataExchange 覆寫來撰寫。 如需交換和驗證功能的詳細資訊,請參閱 中的 CWnd DoDataExchange 成員函式。

程式設計人員和架構會透過對 CWnd::UpdateData 的呼叫間接呼叫。 DoDataExchange

當使用者按一下 [確定] 按鈕以關閉強制回應對話方塊時,架構會呼叫 UpdateData 。 (如果按一下 [取消] 按鈕,則不會擷取資料。OnInitDialog 的預設實作 也會呼叫 UpdateData 來設定控制項的初始值。 您通常會覆寫 OnInitDialog 以進一步初始化控制項。 OnInitDialog 會在建立所有對話方塊控制項之後呼叫,並在對話方塊顯示之前呼叫。

您可以在執行強制回應或無強制回應對話方塊期間隨時呼叫 CWnd::UpdateData

如果您手動開發對話方塊,您可以自行將必要的成員變數新增至衍生的對話方塊類別,並新增成員函式來設定或取得這些值。

當使用者按下 [確定] 或 [取消] 按鈕,或當您的程式碼呼叫 EndDialog 成員函式時,強制回應對話方塊會自動關閉。

當您實作無強制回應對話方塊時,請一律覆寫 OnCancel 成員函式並從中呼叫 DestroyWindow 。 請勿呼叫基類 CDialog::OnCancel ,因為它會呼叫 EndDialog ,這會讓對話方塊看不見,但不會終結它。 您也應該覆寫 PostNcDestroy 無強制回應對話方塊以刪除 this ,因為無強制回應對話方塊通常會使用 new 配置。 強制回應對話方塊通常會建構在框架上,而且不需要 PostNcDestroy 清除。

如需 的詳細資訊 CDialog ,請參閱 對話方塊

繼承階層架構

CObject

CCmdTarget

CWnd

CDialog

需求

標題: afxwin.h

CDialog::CDialog

若要建構以資源為基礎的強制回應對話方塊,請呼叫建構函式的任一公用形式。

explicit CDialog(
    LPCTSTR lpszTemplateName,
    CWnd* pParentWnd = NULL);

explicit CDialog(
    UINT nIDTemplate,
    CWnd* pParentWnd = NULL);

CDialog();

參數

lpszTemplateName
包含 Null 終止的字串,此字串是對話方塊範本資源的名稱。

nIDTemplate
包含對話方塊範本資源的識別碼。

pParentWnd
指向對話方塊物件所屬的父視窗物件或擁有者視窗物件(屬於 CWnd 類型 )。 如果是 Null,對話方塊物件的父視窗會設定為主要應用程式視窗。

備註

建構函式的一種形式會依範本名稱提供對話方塊資源的存取權。 另一 個建構函式會依範本識別碼提供存取權,通常具有IDD_ 前置詞(例如,IDD_DIALOG1)。

若要從記憶體中的範本建構強制回應對話方塊,請先叫用無參數、受保護的建構函式,然後呼叫 InitModalIndirect

使用上述其中一種方法建構強制回應對話方塊之後,請呼叫 DoModal

若要建構無強制回應對話方塊,請使用受保護的建構函式形式 CDialog 。 建構函式受到保護,因為您必須衍生自己的對話方塊類別,才能實作無強制回應對話方塊。 無強制回應對話方塊的建構是兩個步驟的程式。 先呼叫建構函式;然後呼叫 Create 成員函式來建立以資源為基礎的對話方塊,或呼叫 CreateIndirect 以從記憶體中的範本建立對話方塊。

CDialog::Create

呼叫 Create 以使用資源的對話方塊範本建立無強制回應對話方塊。

virtual BOOL Create(
    LPCTSTR lpszTemplateName,
    CWnd* pParentWnd = NULL);

virtual BOOL Create(
    UINT nIDTemplate,
    CWnd* pParentWnd = NULL);

參數

lpszTemplateName
包含 Null 終止的字串,此字串是對話方塊範本資源的名稱。

pParentWnd
指向對話方塊物件所屬的父視窗物件(屬於 CWnd 類型 )。 如果是 Null,對話方塊物件的父視窗會設定為主要應用程式視窗。

nIDTemplate
包含對話方塊範本資源的識別碼。

傳回值

如果對話方塊建立和初始化成功,這兩個表單都會傳回非零;否則為 0。

備註

您可以將 呼叫 Create 放在建構函式內,或在叫用建構函式之後呼叫它。

提供兩種成員函式形式 Create ,以便透過範本名稱或範本識別碼來存取對話方塊範本資源(例如,IDD_DIALOG1)。

針對任一表單,將指標傳遞至父視窗物件。 如果 pParentWnd 為 Null,則會建立對話方塊,並將其父視窗或擁有者視窗設定為主要應用程式視窗。

成員 Create 函式會在建立對話方塊之後立即傳回。

如果建立父視窗時應該顯示對話方塊,請使用對話方塊範本中的WS_VISIBLE樣式。 否則,您必須呼叫 ShowWindow 。 如需進一步的對話方塊樣式及其應用程式,請參閱 MFC 參考 中的 Windows SDK 和 視窗樣式 中的 DLGTEMPLATE 結構。

使用 函 CWnd::DestroyWindow 式終結函式所建立的 Create 對話方塊。

範例

void CMyDialog::OnMenuShowSimpleDialog()
{
   //m_pSimpleDialog initialized to NULL in the constructor of CMyDialog class
   m_pSimpleDlg = new CSimpleDlg();
   //Check if new succeeded and we got a valid pointer to a dialog object
   if (m_pSimpleDlg != NULL)
   {
      BOOL ret = m_pSimpleDlg->Create(IDD_SIMPLEDIALOG, this);

      if (!ret) //Create failed.
      {
         AfxMessageBox(_T("Error creating Dialog"));
      }

      m_pSimpleDlg->ShowWindow(SW_SHOW);
   }
   else
   {
      AfxMessageBox(_T("Error Creating Dialog Object"));
   }
}

CDialog::CreateIndirect

呼叫此成員函式,從記憶體中的對話方塊範本建立無強制回應對話方塊。

virtual BOOL CreateIndirect(
    LPCDLGTEMPLATE lpDialogTemplate,
    CWnd* pParentWnd = NULL,
    void* lpDialogInit = NULL);

virtual BOOL CreateIndirect(
    HGLOBAL hDialogTemplate,
    CWnd* pParentWnd = NULL);

參數

lpDialogTemplate
指向包含用來建立對話方塊之對話方塊範本的記憶體。 此範本的格式 為 DLGTEMPLATE 結構和控制項資訊,如 Windows SDK 中所述。

pParentWnd
指向對話方塊物件的父視窗物件 (類型 為 CWnd )。 如果是 Null,對話方塊物件的父視窗會設定為主要應用程式視窗。

lpDialogInit
指向 DLGINIT 資源。

hDialogTemplate
包含全域記憶體的控制碼,其中包含對話方塊範本。 此範本的形式 DLGTEMPLATE 是對話方塊中每個控制項的結構和資料。

傳回值

如果對話方塊已建立並成功初始化,則為非零;否則為 0。

備註

成員 CreateIndirect 函式會在建立對話方塊之後立即傳回。

如果建立父視窗時應該顯示對話方塊,請使用對話方塊範本中的WS_VISIBLE樣式。 否則,您必須呼叫 ShowWindow 來使其出現。 如需如何在範本中指定其他對話方塊樣式的詳細資訊,請參閱 Windows SDK 中的 DLGTEMPLATE 結構。

使用 函 CWnd::DestroyWindow 式終結函式所建立的 CreateIndirect 對話方塊。

包含 ActiveX 控制項的對話方塊需要 DLGINIT 資源中提供的其他資訊。

CDialog::D oModal

呼叫這個成員函式以叫用強制回應對話方塊,並在完成時傳回對話方塊結果。

virtual INT_PTR DoModal();

傳回值

int ,指定傳遞至 CDialog::EndDialog 成員函式的 nResult 參數值,用來關閉對話方塊。 如果函式無法建立對話方塊,則傳回值為 -1,如果發生其他錯誤,則為 IDABORT,在此情況下,輸出視窗會包含 GetLastError 的錯誤資訊

備註

此成員函式會在對話方塊作用中時處理與使用者的所有互動。 這就是對話方塊強制回應的內容;也就是說,在對話方塊關閉之前,使用者無法與其他視窗互動。

如果使用者按一下對話方塊中的其中一個按鈕,例如 OK 或 Cancel,則會呼叫訊息處理常式成員函式,例如 OnOK OnCancel ,嘗試關閉對話方塊。 預設 OnOK 成員函式會驗證及更新對話方塊資料,並使用結果 IDOK 關閉對話方塊,而預設 OnCancel 成員函式將會關閉具有結果 IDCANCEL 的對話方塊,而不需驗證或更新對話方塊資料。 您可以覆寫這些訊息處理常式函式來改變其行為。

注意

PreTranslateMessage 現在稱為強制回應對話方塊訊息處理。

範例

void CMyDialog::OnMenuShowAboutDialog()
{
   // Construct the dialog box passing the
   // ID of the dialog template resource
   CDialog aboutDlg(IDD_ABOUTBOX);

   // Create and show the dialog box
   INT_PTR nRet = -1;
   nRet = aboutDlg.DoModal();

   // Handle the return value from DoModal
   switch (nRet)
   {
   case -1:
      AfxMessageBox(_T("Dialog box could not be created!"));
      break;
   case IDABORT:
      // Do something
      break;
   case IDOK:
      // Do something
      break;
   case IDCANCEL:
      // Do something
      break;
   default:
      // Do something
      break;
   };
}

CDialog::EndDialog

呼叫此成員函式以終止強制回應對話方塊。

void EndDialog(int nResult);

參數

nResult
包含要從對話方塊傳回給 呼叫端的值 DoModal

備註

此成員函式會 傳回 nResult 做為 的 DoModal 傳回值。 每當建立強制回應對話方塊時,您必須使用 函 EndDialog 式來完成處理。

您可以隨時呼叫 EndDialog ,即使在 OnInitDialog ,在此情況下,您應該先關閉對話方塊,再顯示對話方塊或設定輸入焦點之前。

EndDialog 不會立即關閉對話方塊。 相反地,它會設定旗標,指示對話方塊在目前訊息處理常式傳回時立即關閉。

範例

void CMyDialog::OnMenuShowSimpleModal()
{
   CSimpleDlg myDlg;
   INT_PTR nRet = myDlg.DoModal();

   if (nRet == IDOK || nRet == 5)
   {
      AfxMessageBox(_T("Dialog closed successfully"));
   }
}

 

void CSimpleDlg::OnRButtonUp(UINT nFlags, CPoint point)
{
   UNREFERENCED_PARAMETER(nFlags);
   // Do something

   int nRet = point.x; // Just any value would do!
   EndDialog(nRet);    // This value is returned by DoModal!

   // Do something

   return; // Dialog closed and DoModal returns only here!
}

CDialog::GetDefID

GetDefID呼叫成員函式,以取得對話方塊的預設推播按鈕控制項識別碼。

DWORD GetDefID() const;

傳回值

32 位值 ( DWORD 。 如果預設推播按鈕具有識別碼值,高階單字會包含DC_HASDEFID,而低序字則包含識別碼值。 如果預設推播按鈕沒有識別碼值,則傳回值為 0。

備註

這通常是 [確定] 按鈕。

CDialog::GotoDlgCtrl

將焦點移至對話方塊中的指定控制項。

void GotoDlgCtrl(CWnd* pWndCtrl);

參數

pWndCtrl
識別要接收焦點的視窗(控制項)。

備註

若要取得要當做 pWndCtrl 傳遞的控制項指標(子視窗),請呼叫 CWnd::GetDlgItem 成員函式,該函式會傳回 CWnd 物件的指標

範例

請參閱 CWnd::GetDlgItem 範例。

CDialog::InitModalIndirect

呼叫這個成員函式,以使用您在記憶體中建構的對話方塊範本,初始化強制回應對話物件。

BOOL InitModalIndirect(
    LPCDLGTEMPLATE lpDialogTemplate,
    CWnd* pParentWnd = NULL,
    void* lpDialogInit = NULL);

    BOOL InitModalIndirect(
    HGLOBAL hDialogTemplate,
    CWnd* pParentWnd = NULL);

參數

lpDialogTemplate
指向包含用來建立對話方塊之對話方塊範本的記憶體。 此範本的格式 為 DLGTEMPLATE 結構和控制項資訊,如 Windows SDK 中所述。

hDialogTemplate
包含全域記憶體的控制碼,其中包含對話方塊範本。 此範本的形式 DLGTEMPLATE 是對話方塊中每個控制項的結構和資料。

pParentWnd
指向對話方塊物件所屬的父視窗物件或擁有者視窗物件(屬於 CWnd 類型 )。 如果是 Null,對話方塊物件的父視窗會設定為主要應用程式視窗。

lpDialogInit
指向 DLGINIT 資源。

傳回值

如果對話方塊物件已建立並成功初始化,則為非零;否則為 0。

備註

若要間接建立強制回應對話方塊,請先配置全域記憶體區塊,然後填入對話方塊範本。 然後呼叫空 CDialog 的建構函式來建構對話方塊物件。 接下來,呼叫 InitModalIndirect 以將控制碼儲存至記憶體內部對話方塊範本。 呼叫 DoModal 成員函式時 ,會建立及顯示 Windows 對話方塊。

包含 ActiveX 控制項的對話方塊需要 DLGINIT 資源中提供的其他資訊。

CDialog::MapDialogRect

呼叫 以將矩形的對話方塊單位轉換成螢幕單位。

void MapDialogRect(LPRECT lpRect) const;

參數

lpRect
指向包含要轉換之對話方塊座標的 RECT 結構或 CRect 物件。

備註

對話方塊單位會以目前對話方塊基底單位來表示,這些單位衍生自用於對話方塊文字之字型中字元的平均寬度和高度。 一個水準單位是對話方塊基底寬度單位的四分之一,而一個垂直單位是對話方塊基底高度單位的八分之一。

Windows 函 GetDialogBaseUnits 式會傳回系統字型的大小資訊,但是如果您使用資源定義檔案中的DS_SETFONT樣式,則可以為每個對話方塊指定不同的字型。 Windows 函 MapDialogRect 式會針對此對話方塊使用適當的字型。

成員 MapDialogRect 函式會將 lpRect 中的 對話方塊單位取代為螢幕單位(圖元),讓矩形可用來建立對話方塊或將控制項放置在方塊內。

CDialog::NextDlgCtrl

將焦點移至對話方塊中的下一個控制項。

void NextDlgCtrl() const;

備註

如果焦點位於對話方塊中的最後一個控制項,則會移至第一個控制項。

CDialog::OnCancel

當使用者按一下 [取消 ] 或按下強制回應或無強制回應對話方塊中的 ESC 鍵時,架構會呼叫此方法。

virtual void OnCancel();

備註

當使用者按一下 [取消 ] 或按 ESC 鍵來關閉對話方塊時,覆寫此方法以執行動作(例如還原舊資料)。 預設會藉由呼叫 EndDialog 並導致 DoModal 傳回 IDCANCEL 來關閉強制回應對話方塊。

如果您在無強制回應對話方塊中實作 [ 取消 ] 按鈕,則必須覆寫 OnCancel 方法,並在其中呼叫 DestroyWindow 。 請勿呼叫基類方法,因為它會呼叫 EndDialog ,這會讓對話方塊看不見,但不會終結它。

注意

當您在 Windows XP 下編譯的程式中使用 CFileDialog 物件時,無法覆寫此方法。 如需 的詳細資訊 CFileDialog ,請參閱 CFileDialog 類別

範例

void CSimpleDlg::OnCancel()
{
   // TODO: Add extra cleanup here

   // Ensure that you reset all the values back to the
   // ones before modification. This handler is called
   // when the user doesn't want to save the changes.

   if (AfxMessageBox(_T("Are you sure you want to abort the changes?"),
                     MB_YESNO) == IDNO)
   {
      // Give the user a chance if he has unknowingly hit the
      // Cancel button. If he says No, return. Don't reset. If
      // Yes, go ahead and reset the values and close the dialog.
      return;
   }

   m_nMyValue = m_nPrevValue;
   m_pMyString = NULL;

   CDialog::OnCancel();
}

CDialog::OnInitDialog

呼叫此方法以回應 WM_INITDIALOG 訊息。

virtual BOOL OnInitDialog();

傳回值

指定應用程式是否已將輸入焦點設定為對話方塊中的其中一個控制項。 如果 OnInitDialog 傳回非零,Windows 會將輸入焦點設定為預設位置,也就是對話方塊中的第一個控制項。 只有當應用程式已明確將輸入焦點設定為對話方塊中的其中一個控制項時,應用程式才能傳回 0。

備註

Windows 會在 WM_INITDIALOG 建立 CreateIndirect DoModal 呼叫期間 ,將訊息傳送至對話方塊,該呼叫會在對話方塊顯示之前立即發生。

如果您想要在對話方塊初始化時執行特殊處理,請覆寫此方法。 在覆寫的版本中,先呼叫基類 OnInitDialog ,但忽略其傳回值。 您通常會從覆寫的方法傳回 TRUE

Windows 會使用所有 Microsoft Foundation Class Library 對話方塊通用的標準全域對話方塊程式來呼叫 OnInitDialog 函式。 它不會透過訊息對應呼叫此函式,因此您不需要此方法的訊息對應專案。

注意

當您在 CFileDialog Windows Vista 或更新版本的作業系統下編譯的程式中使用 物件時,無法覆寫此方法。 如需 Windows Vista 和更新版本變更的詳細資訊 CFileDialog ,請參閱 CFileDialog 類別

範例

BOOL CSimpleDlg::OnInitDialog()
{
   CDialog::OnInitDialog();

   // TODO: Add extra initialization here
   m_cMyEdit.SetWindowText(_T("My Name")); // Initialize control values
   m_cMyList.ShowWindow(SW_HIDE);          // Show or hide a control, etc.

   return TRUE; // return TRUE unless you set the focus to a control
   // EXCEPTION: OCX Property Pages should return FALSE
}

CDialog::OnOK

當使用者按一下 [ 確定] 按鈕時呼叫 (識別碼為 IDOK 的按鈕)。

virtual void OnOK();

備註

覆寫這個方法,以在啟用 [確定 ] 按鈕時 執行動作。 如果對話方塊包含自動資料驗證和交換,此方法的預設實作會驗證對話方塊資料,並更新應用程式中的適當變數。

如果您在無強制回應對話方塊中實 作 [確定 ] 按鈕,則必須覆寫 OnOK 方法,並在其中呼叫 DestroyWindow 。 請勿呼叫基類方法,因為它會呼叫 EndDialog ,讓對話方塊看不見,但不會終結它。

注意

當您在 Windows XP 下編譯的程式中使用 CFileDialog 物件時,無法覆寫此方法。 如需 的詳細資訊 CFileDialog ,請參閱 CFileDialog 類別

範例

void CSimpleDlg::OnOK()
{
   // TODO: Add extra validation here

   // Ensure that your UI got the necessary input
   // from the user before closing the dialog. The
   // default OnOK will close this.
   if (m_nMyValue == 0) // Is a particular field still empty?
   {
      // Inform the user that he can't close the dialog without
      // entering the necessary values and don't close the
      // dialog.
      AfxMessageBox(_T("Please enter a value for MyValue"));
      return;
   }

   CDialog::OnOK(); // This will close the dialog and DoModal will return.
}

CDialog::OnSetFont

指定繪圖文字時,對話方塊控制項將使用的字型。

Virtual void OnSetFont(CFont* pFont);

參數

pFont
[in]指定將作為此對話方塊中所有控制項之預設字型的字型指標。

備註

對話方塊會使用指定字型做為其所有控制項的預設值。

對話方塊編輯器通常會將對話方塊字型設定為對話方塊範本資源的一部分。

注意

當您在 CFileDialog Windows Vista 或更新版本的作業系統下編譯的程式中使用 物件時,無法覆寫此方法。 如需 Windows Vista 和更新版本變更的詳細資訊 CFileDialog ,請參閱 CFileDialog 類別

CDialog::P revDlgCtrl

將焦點設定為對話方塊中上一個控制項。

void PrevDlgCtrl() const;

備註

如果焦點位於對話方塊中的第一個控制項,它會移至方塊中的最後一個控制項。

CDialog::SetDefID

變更對話方塊的預設按鈕控制項。

void SetDefID(UINT nID);

參數

nID
指定將成為預設值的按鈕控制項識別碼。

CDialog::SetHelpID

設定對話方塊的內容相關說明識別碼。

void SetHelpID(UINT nIDR);

參數

nIDR
指定內容相關說明識別碼。

另請參閱

MFC 範例DLGCBR32
MFC 範例 DLGTEMPL
CWnd 類別
階層架構圖表