CDialog 類別

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

語法

class CDialog : public CWnd

成員

公用建構函式

公用方法

受保護的方法

備註

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

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

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

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

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

會產生數據對應，以自動處理成員變數與對話框控件之間的數據交換。 數據對應會提供函式，以適當的值初始化對話框中的控件、擷取數據，以及驗證數據。

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

您也可以使用 DLGTEMPLATE 數據結構在記憶體中建立範本，如 Windows SDK 中所述。 建構 CDialog 對象之後，請呼叫 CreateIndirect 來建立無模式對話框，或呼叫 InitModalIndirect 和 DoModal 來建立強制回應對話框。

交換和驗證數據對應是以 新增至新對話框類別的 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 的對話框，而不需驗證或更新對話框數據。 您可以覆寫這些訊息處理程式函式來改變其行為。

範例

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 傳遞的控件指標（子視窗），請呼叫成員函式，該函式會傳回 CWndCWnd::GetDlgItem。

範例

請參閱 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，這會讓對話框看不見，但不會終結它。

範例

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基礎類別庫對話框通用的標準全域對話框程式來呼叫 OnInitDialog 函式。 它不會透過訊息對應呼叫此函式，因此您不需要此方法的訊息對應專案。

範例

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 ，讓對話框看不見，但不會終結它。

範例

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]指定將作為此對話框中所有控件之預設字型的字型指標。

備註

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

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

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 類別
階層架構圖表