CPropertyPage

类 CPropertyPage 的 对 象 表 示 一 张 属 性 表 的 各 页 ， 或 者 说 是 被 看 作 是 标 签 对 话框 。 同 标 准 对 话 框 一 样 ， 要 为 属 性 表 中 每 一 页 从 CPropertyPage 类 中 派 生 一 个新 类 。 要 使 用 CPropertyPage 派 生 对 象 ， 首 先 要 创 建 一 个 CPropertySheet 对 象 ，

然 后 为 属 性 表 中 的 每 一 页 创 建 一 个 对 象 。 为 表 中 的 每 一 页 调 用CPropertySheet::AddPage 函 数 ， 然 后 对 一 个 模 式 属 性 表 调 用CPropertySheet::DoModal 函 数 来 显 示 此 属 性 表 。 对 一 个 非 模 式 属 性 表 调 用CPropertySheet::Create 来 显 示 此 属 性 表 。

你 可 以 创 建 一 种 被 称 为 向 导 的 标 签 对 话 框 ， 这 种 对 话 框 包 括 一 个 属 性 表 ， 该 表有 一 系 列 属 性 页 来 引 导 用 户 进 行 一 项 操 作 的 每 一 个 步 骤 ， 比 如 说 设 置 一 个 设 备或 创 建 一 个 时 事 通 讯 。 在 一 个 向 导 类 型 的 标 签 对 话 框 中 属 性 页 没 有 标 签 ， 每 次只 有 一 个 属 性 页 是 可 见 的 。而 且 ，一 个 向 导 类 型 的 对 话 框 没 有 O K 和 Apply Now 按 钮 ， 代 替 它 们 的 是 一 个 Back 按 钮 ， 一 个 Next 或 Finish 按 钮 和 一 个 Cancel 按钮 。

如 果 要 获 取 更 多 有 关 建 立 一 个 作 为 向 导 的 属 性 表 的 信 息 ， 请 参 见

CPropertySheet::SetWizard- Mode。 要 获 取 更 多 有 关 使 用 CPropertyPage 对 象 的

信 息 ， 请 参 见 “ V isual C++ 程 序 员 指 南 ” 中 的 文 章 “ 属 性 表 ” 。

#indlude <afxdlgs.h>

请 参 阅 CPropertyShee t， CDialog ， CPropertySheet::SetWizardMode

CPropertyPage 类 成 员

Data M embers

m_psp W indows PROPSHEETPAGE 结 构 。 提 供 对 基 本 属性 页 参 数 的 访 问

Construction

CpropertyPage 构 造 有 关 CPropertyPage 对 象

Construct 构 造 有 关 CPropertyPage 对 象 。 如 果 你 想 指 定 在 运行 时 的 参 数 ， 或 者 是 你 使 用 的 是 数 组 ， 就 使 用Construct 函 数

Operat ions

CancelToClose 将 O K 按 钮 改 变 为 读 取 Close ， 并 在 一 个 模 式 属 性

表 的 页 中 进 行 了 一 次 不 可 恢 复 的 改 变 之 后 ， 使

Cancel 按 钮 无 效

SetModified 用 来 激 活 一 个 Apply Now 按 钮 ， 或 使 它 成 为 不 活

动

QuerySiblings 向 前 传 送 消 息 到 属 性 表 的 每 一 页

Overridables

OnCancel 当 单 击 Cancel 按 钮 时 由 框 架 调 用

OnKillActive 当 当 前 页 不 再 是 活 动 页 时 由 框 架 调 用 。 在 此 执 行

数 据 确 认

OnOK 当 OK ， Apply Now 或 Close 按 钮 被 单 击 时 由 框 架调 用

OnSetActive 当 某 页 成 为 活 动 页 时 由 框 架 调 用

OnApply 当 Apply Now 按 钮 被 单 击 时 由 框 架 调 用

OnReset 当 Cancel 按 钮 被 单 击 时 由 框 架 调 用

OnQueryCancel 当 Cancel 按 钮 被 单 击 ， 并 在 发 生 取 消 操 作 之 前 由

框 架 调 用

续 表

OnWizardFinish 在 使 用 一 个 向 导 类 型 的 属 性 表 的 情 况 下 ， 当 Finish

按 钮 被 单 击 时 由 框 架 调 用

成 员 函 数

CPropertyPage::CancelToClose

void CancelToClose();

说 明

在 对 一 个 模 式 属 性 表 的 页 中 的 数 据 进 行 了 不 可 恢 复 的 改 变 之 后 ， 调 用 此 函 数 。

此 函 数 将 把 O K 按 钮 改 变 为 Close 按 钮 ， 并 使 Cancel 按 钮 无 效 。 这 种 改 变 警 告用 户 ， 刚 才 所 作 的 改 变 是 永 久 性 的 ， 并 且 这 种 修 改 不 能 被 取 消 。

在 一 个 无 模 式 属 性 表 中 ， CancelToClose 成 员 函 数 不 做 任 何 事 情 ， 因 为 一 个 无模 式 属 性 表 不 会 有 一 个 缺 省 的 Cancel 按 钮 。

请 参 阅 CPropertyPage ::OnKillActive， CPropertyPage::SetModified

CPropertyPage::Construct

void Construct( UINT nIDTemplate , UINT nIDCaption = 0 );

void Construct( LPCTSTR lpszTemplateNam e, U INT nIDCaption = 0 );

参 数

nIDTemplate

用 于 这 个 页 的 模 板 ID 。

nIDCaption

用 来 放 在 此 页 的 标 签 中 的 名 字 的 ID 。 如 果 是 0 ， 则 将 从 对 话 框 模 板 中 取出 用 于 此 页 的 名 字 。

lpszTemplateName

包 含 一 个 空 结 尾 的 字 符 串 ， 该 字 符 串 是 模 板 资 源 的 名 字 。

说 明

此 成 员 函 数 用 来 构 造 一 个 CPropertyPage 对 象 。 在 满 足 了 下 列 所 有 条 件 后 ， 此对 象 会 被 显 示 ：

• 已 经 用 CPropertySheet::AddPage 将 此 页 添 加 到 一 个 属 性 表 中

  。

• 已 经 调 用 了 属 性 表 的 DoModal 或 Create 函 数 。

• 用 户 已 经 选 择 了 （ 调 整 到 ） 这 一 页 。

如 果 没 有 调 用 另 一 个 构 造 函 数 ，则调用 Construct 。Construct 成 员 函 数 是 灵 活 的 ，

因 为 你 可 以 让 参 数 为 空 ， 然 后 在 你 的 代 码 中 的 任 何 地 方 来 指 定 多 个 参 数 和 构造 。

当 你 是 在 处 理 数 组 时 ， 你 就 必 须 使 用 Construct ， 而 且 你 必 须 为 数 组 的 每 一 个 成员 调 用 Construc t， 以 使 数 据 成 员 可 以 被 分 配 适 当 的 值 。

请 参 阅 CPropertyPage:: CPropertyPage ， CPropertySheet::DoModal， CPropertySheet::AddPage

CPropertyPage::CPropertyPage

CPropertyPage();

CPropertyPage( UINT nIDTemplate , UINT nIDCaption = 0 ); CPropertyPage( LPCTSTR lpszTemplateNam e, UINT nIDCaption = 0 );

参 数

nIDTemplate

用 于 此 页 的 模 板 ID 。

nIDCaption

用 来 放 在 此 页 的 标 签 中 的 名 字 ID 。 如 果 是 0 ， 则 名 字 将 从 此 页 的 对 话 框 模板 中 取 得 。

lpszTemplateName

指 向 一 个 字 符 串 ， 该 字 符 串 包 含 了 用 于 此 页 的 模 板 的 名 字 。 不 可 以 是

NULL 。

说 明

此 函 数 用 来 构 造 一 个 CPropertyPage 对 象 。 在 满 足 下 列 条 件 之 后 ， 此 对 象 将 被显 示 ：

• 已 经 用 CPropertySheet::AddPage 将 此 页 添 加 到 一 个 属 性 表 中

  。

• 已 经 调 用 了 属 性 表 的 DoModal 或 Create 函 数 。

• 用 户 已 经 选 择 了 （ 调 整 到 ） 这 一 页 。

如 果 你 有 多 个 参 数 （ 例 如 ， 你 正 使 用 数 组 ） ， 则 使 用 CPropertySheet::Construct

来 代 替 CPropertyPage。

请 参 阅 CPropertySheet::Create ， CPropertySheet::DoModal ，

CPropertySheet::AddPage，

CPropertyPage::Construct

CPropertyPage::OnApply virtual BOOL OnApply(); 返 回 值

如 果 改 变 被 接 受 则 返 回 非 零 值 ； 否 则 返 回 0 。

说 明

当 用 户 选 择 O K 或 Apply Now 按 钮 后 ， 框 架 调 用 此 函 数 。 当 框 架 调 用 此 函 数 时 ， 对 属 性 表 中 的 所 有 属 性 页 做 的 改 变 都 被 接 受 了 ， 属 性 表 保 持 焦 点 ， OnApply 返回 TRU E（ 值 1 ）。在 框 架 可 以 调 用 OnApply 之 前 ，你 必 须 已 经 调 用 了 SetModified 并 将 它 的 参 数 设 置 为 TRU E 。 这 将 会 使 得 在 用 户 一 进 行 有 关 属 性 页 的 改 变 时 就激 活 Apply Now 按 钮 。

重 载 这 个 函 数 来 指 定 当 用 户 单 击 Apply Now 按 钮 时 ， 你 的 程 序 会 进 行 什 么 动作 。 在 重 载 时 ， 函 数 应 该 返 回 TRUE 来 表 示 接 受 改 变 ， 返 回 FALSE 来 表 示 禁止 改 变 。

OnApply 的 缺 省 实 现 调 用 OnOK 。

如 果 要 获 取 更 多 有 关 当 用 户 在 一 个 属 性 表 中 按 下 Apply Now 或 OK 按 钮 时 发 送

的 通 知 消 息 的 信 息 ， 请 参 见 W in32 文 档 中 的 PSN_APPLY 。

请 参 阅 CPropertyPage::SetModified ， CPropertyPage::OnOK

CPropertyPage::OnCancel

virtual void OnCancel();

说 明

当 选 择 Cancel 按 钮 时 ， 框 架 调 用 此 成 员 函 数 。 重 载 这 个 成 员 函 数 来 执 行 Cancel

按 钮 的 动 作 。 缺 省 的 实 现 忽 略 所 做 的 任 何 改 变 。

请 参 阅 CPropertyPage::OnApply ， CDialog::OnCance l， CPropertyPage::OnOK

C PropertyPage::OnKillActive

virtual BOOL OnKillActive();

返 回 值

如 果 数 据 被 成 功 更 新 则 返 回 非 零 值 ； 否 则 返 回 0 。

说 明

当 页 不 再 是 活 动 页 时 ， 框 架 调 用 此 函 数 。 重 载 这 个 成 员 函 数 来 执 行 指 定 的 数 据确 认 任 务 。

此 成 员 函 数 的 缺 省 实 现 将 对 属 性 页 中 的 控 件 所 做 的 设 置 拷 贝 到 属 性 页 的 成 员 变量 中 。 如 果 数 据 没 有 被 成 功 地 更 新 ， 则 属 于 一 个 对 话 框 数 据 确 认（ DDV ） 错 误 ， 该 页 保 持 焦 点 。

在 此 成 员 函 数 成 功 返 回 之 后 ， 框 架 将 调 用 此 页 的 OnOK 函 数 。

请 参 阅 CWnd::UpdateData ，CPropertyPage::OnOK ，CPropertyPage::OnSetActive

CPropertyPage::OnOK

virtual void OnOK();

说 明

当 用 户 选 择 了 O K 或 Apply Now 按 钮 时 ， 在 框 架 调 用 了 OnKillActive 之 后 ， 框架 立 即 调 用 此 函 数 。 重 载 这 个 成 员 函 数 来 实 现 当 用 户 解 散 整 个 属 性 表 时 ， 执 行对 当 前 活 动 页 指 定 的 行 为 。

此 成 员 函 数 的 缺 省 实 现 将 该 页 标 记 为 “ 清 除 （ clear ） ” 来 反 映 数 据 已 经 在

OnKillActive 函 数 中 更 新 了 。

请 参 阅 CDialog::OnOK， CPropertyPage::OnKillActive

CPropertyPage::OnQueryCancel

virtual BOOL OnQueryCancel();

返 回 值

如 果 禁 止 取 消 操 作 则 返 回 FALSE ； 如 果 允 许 取 消 操 作 则 返 回 TRUE 。

说 明

当 用 户 单 击 Cancel 时 ， 并 在 取 消 动 作 发 生 之 前 ， 框 架 调 用 此 成 员 函 数 。重 载 此 成 员 函 数 来 指 定 当 用 户 单 击 Cancel 按 钮 时 程 序 要 做 的 动 作 。OnQueryCancel 的 缺 省 实 现 返 回 TRU E 。

CPropertyPage::OnReset

virtual void OnReset();

当 用 户 选 择 Cancel 按 钮 时 ， 可 以 调 用 此 成 员 函 数 。 当 框 架 调 用 此 函 数 时 ， 用 户向 前 对 所 有 属 性 页 所 做 的 选 择 Apply Now 按 钮 确 认 的 改 变 都 将 被 放 弃 ， 而 属 性表 保 持 焦 点 。

重 载 这 个 成 员 函 数 来 指 定 当 用 户 单 击 Cancel 按 钮 时 程 序 将 执 行 的 动 作 。

OnReset 的 缺 省 实 现 不 做 任 何 事 情 。

请 参 阅 CPropertyPage::OnCancel ， CPropertyPage::OnApply

CPropertyPage::OnSetActive

virtual BOOL OnSetActive();

如 果 成 功 地 激 活 了 此 页 则 返 回 非 零 值 ； 否 则 返 回 0 。

说 明

当 用 户 选 择 了 此 页 并 将 其 变 为 活 动 页 时 ， 框 架 调 用 这 个 成 员 函 数 。 重 载 此 成 员函 数 来 执 行 当 一 个 页 被 激 活 时 要 执 行 的 任 务 。 你 的 关 于 这 个 成 员 函 数 的 重 载 应该 在 做 任 何 其 它 处 理 之 前 调 用 缺 省 的 版 本 。

缺 省 的 实 现 为 该 页 创 建 窗 口 （ 如 果 在 此 之 前 没 有 创 建 的 话 ） ， 并 使 它 成 为 活 动页 。

请 参 阅 CPropertyPage::OnKillActive

CPropertyPage::On W izardBack virtual LRESULT OnWizardBack(); 返 回 值

如 果 自 动 前 进 到 下 一 页 ， 则 返 回 0 ； 如 果 禁 止 页 改 变 ， 则 返 回 -1 。 如 果 所 到 的页 是 除 下 一 页 之 外 的 其 它 页 ， 则 返 回 要 显 示 的 对 话 框 的 标 识 符 。

说 明

当 用 户 在 一 个 向 导 中 单 击 Back 按 钮 时 ， 框 架 调 用 这 个 成 员 函 数 。重 载 此 成 员 函 数 来 指 定 当 按 下 Back 按 钮 时 用 户 必 须 做 的 一 些 操 作 。

要 获 取 更 多 有 关 如 何 创 建 一 个 向 导 类 型 的 属 性 表 的 信 息 ， 请 参 见

CPropertySheet::SetWizard- Mode 。

请 参 阅 CPropertySheet::SetWizardMode

CPropertyPage::On W izardFinish

virtual BOOL OnWizardFinish();

返 回 值

当 向 导 完 成 时 如 果 属 性 表 被 销 毁 ， 则 返 回 非 零 值 ； 否 则 返 回 零 。

说 明

当 用 户 在 一 个 向 导 中 单 击 Finish 按 钮 时 框 架 调 用 此 成 员 函 数 。 当 框 架 调 用 这 个成 员 函 数 时 ， 在 Finish 按 钮 被 按 下 并 且 OnWizardFinish 返 回 TRUE （ 一 个 非 零值 ） 时 ， 属 性 表 被 销 毁 。

重 载 这 个 函 数 来 指 定 当 Finish 按 钮 被 按 下 时 ， 用 户 必 须 执 行 的 一 些 动 作 。 当 重

载 这 个 函 数 时 ， 返 回 FALSE 来 禁 止 属 性 表 被 销 毁 。

要 获 取 更 多 有 关 当 用 户 在 一 个 向 导 属 性 表 中 按 下 Finish 按 钮 时 发 送 的 通 知 消 息的 信 息 ， 请 参 见 W in32 文 档 中 的 PSN_WIZFINISH 。

如 果 要 获 取 更 多 关 于 如 何 创 建 一 个 向 导 类 型 的 属 性 表 的 信 息 ， 请 参 见

CPropertySheet::Set- WizardMode 。

请 参 阅 CPropertyPage::SetWizardMode

CPropertyPage::On W izardNext virtual LRESULT OnWizardNext(); 返 回 值

如 果 自 动 前 进 到 下 一 页 ， 则 返 回 0 ； 如 果 禁 止 页 改 变 ， 则 返 回 -1 。 如 果 所 到 的

页 是 除 下 一 页 之 外 的 其 它 页 ， 则 返 回 要 显 示 的 对 话 框 的 标 识 符 。

说 明

当 用 户 在 一 个 向 导 中 单 击 Next 按 钮 时 ， 框 架 调 用 这 个 成 员 函 数 。

重 载 这 个 成 员 函 数 来 指 定 当 Next 按 钮 被 按 下 时 用 户 必 须 做 的 某 些 动 作 。

如 果 要 获 取 更 多 关 于 如 何 创 建 一 个 向 导 类 型 的 属 性 表 的 信 息 ， 请 参 见

CPropertySheet::Set- WizardMode 。

请 参 阅 CPropertySheet::SetWizardMode

CPropertyPage::QuerySiblings

LRESULT QuerySiblings( WPARAM wParam , LPARAM lParam );

返 回 值

如 果 在 属 性 表 中 的 所 有 页 都 返 回 0 ， 则 函 数 返 回 0 ； 否 则 ， 返 回 属 性 表 中 的 每一 页 返 回 的 非 零 值 。

参 数

wParam

指 定 附 加 的 与 消 息 相 关 的 信 息 。

lParam

指 定 附 加 的 与 消 息 相 关 的 信 息 。

说 明

此 成 员 函 数 用 来 将 一 个 消 息 向 前 传 递 给 属 性 表 中 的 每 一 页 。 如 果 有 一 个 页 返 回一 个 非 零 值 ， 则 属 性 表 不 再 将 消 息 发 送 给 后 续 页 。

CPropertyPage::SetModified

void SetModified( BOOL bChanged = TRUE );

参 数

bChanged

如 果 是 TRUE ， 则 表 明 在 最 后 一 次 应 用 后 属 性 页 的 设 置 被 修 改 了 ； 如 果是 FALSE ， 则 表 明 属 性 页 的 设 置 被 应 用 或 被 忽 略 。

说 明

此 成 员 函 数 用 来 使 Apply Now 按 钮 有 效 或 无 效 ， 这 要 根 据 属 性 页 中 的 设 置 是 否应 该 被 应 用 到 适 当 的 外 部 对 象 。

框 架 知 道 哪 一 页 是 “ 脏 的 ” ， 就 是 那 些 你 对 它 们 调 用 了 SetModified(TRUE) 的属 性 页 。 如 果 你 对 某 一 属 性 页 调 用 了 SetModified(TRUE )， 则 Apply Now 按钮

按 钮 将 总 是 无 效 的 ， 但 是 只 有 在 没 有 任 何 一 个 属 性 页 是 “ 脏 的 ” 的 时 候 。

请 参 阅 CPropertyPage::CancelToClose

数 据 成 员

CPropertyPage::m_psp

说 明

m_psp 是 一 个 结 构 ， 它 的 成 员 保 存 了 PROPSHEETPAGE 的 特 征 。 在 一 个 属 性页 被 构 造 之 后 ， 使 用 这 个 结 构 来 初 始 化 该 属 性 页 的 外 观 。

如 果 要 获 取 更 多 关 于 这 个 结 构 的 消 息 ， 包 括 它 的 成 员 的 列 表 ， 请 参 见“ W indows

请 参 阅 CPropertyShee t， PROPSHEETPAGE