CDialog

屏幕上显示的对话框基类

CDialog类是在屏幕上显示的对话框基类。对话框有两类：模态对话框和非模态对话框。模态对话框在应用继续进行之前必须关闭。

信息介绍

一个CDialog对象是对话框模板与一个CDialog派生类的组合。使用对话框编辑器创建对话框并存入资源之中，然后使用ClassWizard创建一个CDialog派生类。

同其它窗口一样，对话框从Windows 中获取信息。在对话框中你会对来自对话框控件的处理消息感兴趣，因为它说明了对话框是如何与用户交互的。ClassWizard观察对话框每个控件可能产生的消息，可以选择你所希望处理的消息。ClassWizard 将适当的消息映射器入口和消息处理成员函数加到一个新类中。你只需为成员函数编写应用的代码。

如果喜欢，在使用ClassWizard时可以编写自己的消息映射器入口和成员函数。

对于大多数普通对话框，可以向对话框派生类中添加成员变量以存储数据。数据是用户向对话框中输入的，或者为用户显示数据。ClassWizard观察对话框中与数据映射的控件并提示为每一控件创建一个成员变量。同时，为每一变量选择变量类型和取值范围。ClassWizard将成员变量加入对话框派生类中。

然后，ClassWizard写入成员函数与对话框控件之间的交换数据自动映射的数据。数据映射使函数可以为对话框控件提供适当的初始值。检索数据并对数据进行有效性检测。

要建立模态对话框，先使用构造程序为对话框派生类构造一个对象。然后调用DoModal创建对话框窗口及其控件。如果要建立非模态对话框，在构造程序中为对话框类调用Create即可。

还可使用DLGTEMPLATE数据结构在内存中建立模板，该结构在联机文档“Win32 SDK”中有描述。当构造了一个CDialog对象之后，调用CreateIndirect创建非模态对话框，或调用InitModalIndirect和DoModal来创建模态对话框。

ClassWizard在覆盖它为新对话框类加入的CWnd::DoDataExchange之后写入交换和有效性规则的数据映射。请参阅CWnd中的DoDataExchange成员函数。

程序和框架都通过调用CWnd::UpdateData间接调用DoDataExchange。当用户单击OK按钮关闭模态对话框时，框架调用UpdateData（如果单击了Cancel按钮，将不能获得数据）。OnInitDialog的缺省方式也是设置控件的初始值。为得到初始控件，通常要覆盖OnInitDialog。在所有对话框控件建立且在对话框显示之前，调用OnInitDialog。

在模态对话框与非模态对话框执行的任意时刻都可以调用CWnd::UpdateData。

如果要手工创建对话框，应为对话框派生类添加必需的成员变量，并添加已获得数据值的成员函数。

关于ClassWizard的更多信息，请参阅联机文档“Visual C++程序员指南”中的“使用 ClassWizard”。

在应用中调用CWinApp::SetDialogBkColor为对话框设置背景色。

当用户按下OK或Cancel按钮，或者调用EndDialog时，模态对话框自动关闭。

当实现一个非模态对话框时，总是覆盖OnCancel函数并从中调用DestroyWindows。不要调用CDialog::OnCancel基类。因为它会调用EndDialog，那会使对话框虽然存在但并不可视。模态对话框还应覆盖PostNcDestory以防止删除自身。模态对话框厂在框架中构造，不需要用PostNcDestory清除。

关于CDialog的更多信息，请参阅联机文档“Visual C++程序员指南”的“对话框主题”。

所需头文件：#include

成员函数

构造函数

CDialog 构造CDialog对象

初始化

Create 初始化CDialog对象。创建非模态对话框和附在其上的对话框控件

CreateIndirect 从内存中的对话框模板创建非模态对话框

InitModalIndirect 从内存中的对话框模板创建模态对话框。保存参数直到调用DoModal函数

操作 DoModal 调用模态对话框，使用后返回

MapDialogRect 将对话框的矩形单位转换为屏幕单位

NextDlgCtrl 在对话框中将焦点移到下一个对话框控件上

PrevDlgCtrl 在对话框中将焦点移到前一个对话框控件上

GotoDlgCtrl 在对话框中将焦点移到指定的对话框控件上

SetDefID 改变对话框的缺省按钮

GetDefID 获得对话框的缺省按钮

SetHelpID 为对话框设置上下文的help ID

EndDialog 关闭模态对话框

覆盖函数

OnInitDialog 覆盖该函数可改变对话框初始设置

OnSetFont 覆盖该函数可指定在对话框控件中输入文本时使用的字体

OnOK 覆盖该函数可在对话框中进行OK按钮操作。缺省值是关闭对话框，DoModal返回IDOK

OnCancel 覆盖该函数可在对话框中进行Cancel按钮操作或按ESC键。缺省值是关闭对话框，DoModal返回IDCANCEL

详细介绍

参数：

lpszTemplateName: 包含一个对话框模板资源的空终止字符串。

nIDTemplate: 包含对话框模板资源的ID号。

pParentWnd: 包含对话框的父窗口或所有者窗口对象的指针。如果其为NULL，则对话框对象的父窗口设置为主要应用程序窗口。

说明：

构造一个基于资源的模态对话框。调用构造程序的窗体，其中一个窗体通过模板便可访问对话框。另一个一般使用带IDD_前缀（如IDD_DIALOG1）的模板ID号实现访问。

从内存中模板来构造模态对话框，首先需要参数和受保护的构造程序，然后调用InitModalIndirect。

使用上述方法之一构造好对话框之后，调用DoModal。

构造非模态对话框，使用CDialog构造程序中受保护的窗体。构造程序受到保护，因为必须从自己的对话框类中派生得到一个非模态对话框。

构造非模态对话框分两步进行：首先调用构造程序，然后调用Create成员函数创建基于资源的对话框，或者从内存模板中调用CreateIndirect来创建对话框。

返回值：

如果对话框创建和初始化成功，则返回非零值，否则为0。

参数：

lpszTemplateName:包含一个对话框模板资源的空终止字符串。

nIDTemplate: 包含对话框模板资源的ID数。

说明：

调用Create，使用资源中对话框模板来创建非模态对话框。可将调用置于构造程序内部或者在构造程序启动之后调用。

Create成员函数为访问对话框模板资源提供了两种方法，既可以通过模板名称，也可以模板ID号（如IDD_DIALOG1）。

每种访问方法都会给父窗口传递一个指针。如果pParentWnd为NULL，则应用的主窗口作为其父窗口或所有者窗口来进行创建。

当创建对话框后，Create成员函数应立即返回。

在父窗口中创建之后，如果要求对话框出现，则使用模板中的WS_VISIBLE风格。否则，必须调用ShowWindow。其它对话框风格及应用，请参阅联机文档“Win32 SDK”中的DIGTEMPLATE结构和“Microsoft Visual C++ 6.0 MFC类库参考手册（二）”中的“Windows风格”。使用CWnd::DestroyWindow函数来删除由Create函数创建的对话框。

返回值：

如果对话框创建和初始化成功，则返回非零值，否则为0。

参数：

lpDialogTemplate：包含用于创建对话框的对话框模板的指针。该模板位于DLGTEMPLATE结构和控件信息表单中。有关结构的更多信息，请参阅联机文档“Win32 SDK”。

hDialogTemplate：包含对话框模板的全局内存的句柄。模板使用DLGTEMPLATE结构的形式。

说明：

调用该成员函数从对话框模板中创建一个非模态对话框。

当创建对话框后，CreateIndirect成员函数立即返回。

在父窗口中创建之后，如果要求对话框出现，则使用模板中的WS_VISIBLE风格。否则，必须调用ShowWindow。其它对话框风格及应用，请参阅联机文档“Win32 SDK”中的DIATEMPLATE结构和“Microsoft Visual C++ 6.0 MFC类库参考（二）”中的“Windows风格”。使用CWnd::DestroyWindow函数删除由CreateIndirect创建的对话框。

返回值：

整数值，指定了传递给CDialog::EndDialog 的nResult参数值。该函数用于关闭对话框。如果函数不能创建对话框，则返回-1；如果出现其它错误，则返回IDABORT。

说明：

调用该成员函数使用模态对话框并返回对话框结果。当对话框处于活动状态时，该函数处理与用户的交互。这使得对话框是模态的，使用户在关闭对话框之前不能与其它窗口交互。

如果用户单击了对话框中的按钮，如OK或Cancel，那么消息处理函数如OnOK或OnCancel被调用，从而关闭对话框。缺省的OnOK成员函数会对对话框数据进行有效性检验和更新，并关闭它得到结果IDOK。缺省OnCancel函数关闭对话框得到结果IDCANCEL，而不对对话框数据检验或更新，可以覆盖这些消息函数并改变它们的行为。注意 PreTransMessage被调用来处理模态对话框的消息。

参数：

nResult：对话框返回的值，用于调用者DoModal。

说明：

调用该成员函数来中止一个模态对话框。该函数返回nResult。无论模态对话框是何时被创建的，必须使用EndDialog来结束处理。

可以随时调用EndDialog，即使在使用OnInitDialog时，即在对话框显示或获得输入焦点之前就关闭它。

EndDialog不会立即关闭对话框。它设置了一个标记，用以指定在当前消息处理程序返回时就关闭对话框。

返回值：

32位值（DWORD）。如果缺省按钮具有ID值，则高位字包括DC_HASDEFID ，低位字包含ID值。如果缺省按钮不具有ID值，则返回0。

说明：

调用该GetDefID成员函数获得对话框缺省按钮的ID值。通常是一个OK按钮。

参数：

pWndCtrl：接收焦点的窗口（控件）标识。

说明：

在对话框内移动焦点至指定的控件。

要得到作为pWndCtrl传递的控件（子窗口）的指针。调用CWnd::GetDlgItem成员函数，它返回一个CWnd 对象指针。

返回值：

如果对话框对象创建和初始化成功，则返回非零值，否则为0。

说明：

调用该成员函数，使用内存中构造的对话框模板初始化模态对话框。

要间接创建一个模态对话框，首先应分配一块全局内存用于存放对话框模板，然后调用空的CDialog构造程序构造对话框对象，再调用InitModalIndirect将句柄存入内存中的对话框模板。当调用DoModal成员函数后，Windows 对话框被创建并显示。

说明：

将对话框单位转换为屏幕单位。对话框单位是用当前对话框基本单位表示的。基本单位是从对话框文本的字符平均高度和宽度得到的。1个水平单位是1/4个对话框基本宽度单位，1个垂直单位是1/4个对话框基本高度单位。

GetDialogBaseUnits 返回系统字体的尺寸信息，但如果在资源定义文件中使用了DS_SETFONT风格，便可以为每个对话框指定不同的字体。MapDialogRect函数对话框使用适当的字体。

MapDialogRect用屏幕单位（像素）替代了lpRect中的对话框单位，以便矩形能用于创建对话框或者在框内为控件确定位置。

说明：

在对话框内将焦点移到下一个控件。如果焦点位于最后一个控件，则移到第一个控件上。

说明：

当用户在模态对话框或非模态对话框内单击Cancel按钮或按ESC键时，窗体调用这个成员函数。

覆盖该成员函数，执行Cancel按钮动作，缺省方式是调用EndDialog来简单中止模态对话框，并使DoModal 返回IDCANCEL。

如果在非模态对话框中实现Cancel按钮，必须覆盖OnCancel成员函数，并在其中调用DestoryWindow。不能调用基类成员函数，那将会调用EndDialog，使对话框虽然存在但不可视。

返回值：

指定对话框是否对它的一个控件设置输入焦点。如果OnInitDialog返回非零值，Windows将输入焦点设在对话框的第一个控件上，只有在对话框明确将输入焦点设在某控件上，应用返回0。

说明：

调用这个成员函数是对WM_INITDIALOG消息作出的反应。这条消息是在对话框即将显示之前，在Create ，CreateIndirect或DoModal调用期间发出的。

如果在对话框初始化后需要执行特别处理，覆盖该函数。首先调用基类OnInitDialog，但不考虑其返回值。正常情况下，覆盖的函数返回TRUE。Windows调用OnInitDialog函数是通过标准的全局对话框过程（它们对于所有的Microsoft基础类库的对话框是通用的），而不是通过消息映射。因此该函数不需要消息映射入口。

说明：

当用户按OK按钮（ID是IDOK）时调用。

覆盖该函数执行OK按钮动作。如果对话框包括自动数据检验和交换，缺省方式是对应用的某些变量进行数据的检验和更新。

参数：

说明：

书写文本时为对话框控件指定字体。对话框控件使用指定字体作为所有对话框控件的缺省值。

对话框编辑器设置字体，将其作为对话框模板资源的一部分。

说明：

把对话框中的焦点移到前一个控件。如果焦点在第一个控件上，则移到对话框中最后一个控件上。

参数：

说明：为对话框改变缺省按钮。

参数：