C O leServerDoc

COleServerDoc 是 OLE 服 务 器 文 档 的 基 类 。 服 务 器 文 档 可 包 含 COleServerItem

对 象 ， 这 些 对 象 表 示 提 供 给 嵌 入 或 链 接 项 的 服 务 器 接 口 。 当 服 务 器 应 用 程 序 由容 器 应 用 程 序 启 动 来 编 辑 嵌 入 项 时 ， 则 将 该 项 加 载 为 服 务 器 自 己 的 服 务 器 文档 ； COleServerDoc 对 象 只 包 含 一 个 COleServerItem 对 象 ， 构 成 了 整 个 文 档 。当 服 务 器 应 用 程 序 由 容 器 应 用 程 序 启 动 来 编 辑 链 接 项 时 ， 则 从 磁 盘 装 载 一 个 现有 的 文 档 ， 一 部 分 文 档 内 容 被 加 亮 以 指 示 链 接 项 。

COleServerDoc 对 象 也 可 包 含 COleClientItem 类 的 项 。 这 使 得 你 可 以 创 建 容 器

－ 服 务 器 应 用 程 序 。 框 架 在 为 COleServerDoc 对 象 提 供 服 务 的 同 时 ， 也 提 供 了用 于 存 储 COleClientItem 项 的 函 数 。

如 果 服 务 器 应 用 程 序 不 支 持 链 接 ， 则 服 务 器 程 序 文 档 将 总 是 只 包 含 一 个 服 务 器项 ， 该 项 将 整 个 嵌 入 对 象 表 示 为 一 个 文 档 。 如 果 服 务 器 应 用 程 序 支 持 链 接 ， 则每 当 将 一 个 选 择 拷 贝 到 剪 贴 板 中 时 ， 它 都 必 须 创 建 一 个 服 务 器 项 。

要 使 用 COleServerDoc ， 可 从 COleServerDoc 类 派 生 一 个 新 类 ， 并 实 现

OnGetEmbeddedItem 成 员 函 数 ， 该 函 数 使 得 服 务 器 应 用 程 序 能 够 支 持 嵌 入 项 。你 可 以 从 COleServerItem 派 生 一 个 新 类 来 实 现 文 档 中 的 嵌 入 项 ， 并 从OnGetEmbeddedItem 函 数 返 回 该 类 的 这 些 对 象 。

为 支 持 链 接 项 ， COleServerDoc 提 供 了 OnGetLinkedItem 成 员 函 数 。 应 用 程 序可 以 利 用 该 函 数 的 缺 省 实 现 ， 或 者 当 应 用 程 序 有 自 己 的 管 理 文 档 项 的 方 式 时 ， 可 以 重 载 这 个 函 数 。

应 用 程 序 需 要 为 它 所 支 持 的 每 种 服 务 器 文 档 类 型 派 生 一 个 COleServerDoc 派 生类 。 例 如 ， 如 果 服 务 器 应 用 程 序 支 持 工 作 表 格 和 图 表 ， 则 它 需 要 两 个COleServerDoc 派 生 类 。

#include <afxole.h>

请 参 阅 COleDocument ， COleLinkingDoc ， COleTemplateServer

CO leServerDoc 类 成 员

Construction

ColeServerDoc 构 造 一 个 COleServerDoc 对 象

Attribute s IsEmbedded 表 明 文 档 是 嵌 入 在 一 个 容 器 文 档 中 的 还 是 独 立 运

行 的

IsInPlaceActive 如 果 此 项 是 当 前 现 场 被 激 活 的 则 返 回 TRUE GetEmbeddedItem 返 回 一 个 指 向 代 表 整 个 文 档 的 项 的 指 针GetItemPosition 返 回 当 前 位 置 矩 形 用 于 现 场 编 辑 ， 该 矩 形 是 相 对

于 容 器 应 用 程 序 的 客 户 区 的GetItemClipRect 返 回 当 前 用 于 现 场 编 辑 的 剪 贴 板 矩 形GetZoomFactor 返 回 用 像 素 表 示 的 缩 放 因 子

Operations

OnExecOleCmd 执 行 一 个 指 定 的 命 令 或 显 示 与 该 命 令 相 关 的 帮 助NotifyChanged 通 知 容 器 应 用 程 序 用 户 已 经 改 变 了 文 档NotifyRename 通 知 容 器 应 用 程 序 用 户 已 经 将 文 档 改 名 了NotifySaved 通 知 容 器 应 用 程 序 用 户 已 经 保 存 了 文 档

NotifyClosed 通 知 容 器 应 用 程 序 用 户 已 经 关 闭 了 文 档

SaveEmbedding 通 知 容 器 应 用 程 序 保 存 文 档

ActivateInPlace 激 活 文 档 用 于 现 场 编 辑DeactivateAndUndo 使 服 务 器 的 用 户 界 面 不 再 是 活 动 的D iscardUndoState 丢 弃 取 消 状 态 信 息RequestPositionChange 改 变 现 场 可 编 辑 框 架 的 位 置ScrollContainerBy 滚 动 容 器 程 序 文 档

UpdateAllItems 通 知 容 器 应 用 程 序 用 户 已 经 改 变 了 文 档

Overridables

GetDocObjectServer 重 载 这 个 函 数 可 以 创 建 一 个 新 的 CDocObjectServer

对 象 ， 并 表 明 这 个 文 档 是 一 个 DocObject 容 器

OnUpdateDocument 当 保 存 一 个 作 为 嵌 入 项 的 服 务 器 文 档 时 ， 框 架 调

用 该 函 数 来 更 新 此 项 的 容 器 应 用 程 序 的 备 份

OnGetEmbeddedItem 调 用 此 函 数 可 获 取 一 个 表 示 整 个 文 档 的

COleServerItem ； 此 函 数 可 用 来 获 取 一 个 嵌 入 项 。需 要 实 现

OnClose 当 容 器 应 用 程 序 请 求 关 闭 文 档 时 ， 框 架 调 用 这 个函 数

OnSetHostNames 当 一 个 容 器 为 一 个 嵌 入 对 象 设 置 窗 口 标 题 时 ， 框

架 调 用 这 个 函 数

OnShowDocument 框 架 调 用 此 函 数 来 显 示 或 隐 藏 文 档

OnDeactivate 当 用 户 使 一 个 现 场 被 激 活 的 项 变 为 不 活 动 时 ， 框

架 调 用 此 函 数

OnDeactivateUI 框 架 调 用 此 函 数 来 销 毁 控 件 和 其 它 为 现 场 激 活 所创 建 的 用 户 界 面 元 素 。

OnSetItemRects 框 架 调 用 此 函 数 来 定 位 现 场 编 辑 框 架 窗 口 在 容 器应 用 程 序 窗 口 中 的 位 置

OnReactivateAndUndo 框 架 调 用 此 函 数 来 取 消 在 现 场 编 辑 期 间 所 做 的 改

变

OnFrameWindowActivat e

当 容 器 的 框 架 窗 口 被 激 活 或 成 为 不 活 动 时 ， 框 架调 用 这 个 函 数

OnDocWindowActivate 当 容 器 应 用 程 序 的 文 档 框 架 窗 口 被 激 活 或 成 为 不

活 动 时 ， 框 架 调 用 这 个 函 数

OnShowControlBars 框 架 调 用 此 函 数 来 显 示 或 隐 藏 用 于 现 场 编 辑 的 控

制 条

OnResizeBorder 当 容 器 应 用 程 序 的 框 架 窗 口 或 文 档 窗 口 被 改 变 大

小 时 ， 框 架 调 用 这 个 函 数

CreateInPlaceFrame 框 架 调 用 此 函 数 来 创 建 一 个 用 于 现 场 编 辑 的 框 架

窗 口

DestroyInPlaceFrame 框 架 调 用 此 函 数 来 销 毁 一 个 用 于 现 场 编 辑 的 框 架

窗 口

成 员 函 数

CO leServerDoc::ActivateInPlace

BOOL ActivateInPlace();

返 回 值

如 果 成 功 则 返 回 非 零 值 ； 否 则 返 回 0 ， 这 表 明 该 项 已 经 被 完 全 打 开 了 。

此 成 员 函 数 用 来 激 活 用 于 现 场 编 辑 的 项 。

此 函 数 执 行 在 现 场 激 活 中 必 须 的 所 有 操 作 。 它 创 建 一 个 现 场 框 架 窗 口 ， 激 活 它并 设 置 此 项 的 大 小 ， 设 置 共 享 菜 单 和 其 它 控 件 ； 将 此 项 滚 动 到 视 窗 中 ， 并 将 焦点 设 置 到 现 场 框 架 窗 口 。

COleServerItem::OnShow 的 缺 省 实 现 调 用 这 个 函 数 。 如 果 你 的 应 用 程 序 支 持 其它 用 于 现 场 激 活 的 动 词 （ 比 如 Play） ， 则 请 你 调 用 这 个 函 数 。

请 参 阅 COleServerItem::OnShow

CO leServerDoc::COleServerDoc

COleServerDoc();

当 不 与 OLE 系 统 DLLs 连 接 ， 此 成 员 函 数 用 来 构 造 一 个 COleServerDoc 对 象 。应 用 程 序 必 须 调 用 COleLinkingDoc::Register 函 数 来 打 开 与 OLE 的 通 讯 。 如 果应 用 程 序 中 使 用 的 是 COleTemplateServer ， 则 由 COleLinkingDoc 实 现 的OnNewDocument ， OnOpenDocument 和 OnSaveDo c ument 为 应 用 程 序 调 用COleLinkingDoc::Register 函 数 。

请 参 阅 COleServerItem::OnShow

CO leServerDoc::CreateInPlaceFrame

virtual COleIPFrame Wnd* CreatInPlaceFrame( CWnd* pParentWnd );

如 果 函 数 成 功 则 返 回 一 个 指 向 现 场 框 架 窗 口 的 指 针 ； 否 则 返 回 NULL 。

参 数

pParentWnd

指 向 容 器 应 用 程 序 的 父 窗 口 的 指 针 。

说 明

框 架 调 用 此 函 数 来 创 建 一 个 用 于 现 场 编 辑 的 框 架 窗 口 。 该 函 数 的 缺 省 实 现 是 使用 文 档 模 板 中 指 定 的 信 息 来 创 建 框 架 窗 口 。 所 使 用 的 视 是 为 文 档 创 建 的 第 一 个视 。 这 个 视 暂 时 从 原 来 的 框 架 分 离 ， 并 连 接 到 这 个 刚 创 建 的 框 架 窗 口 上 。

此 函 数 是 一 个 高 级 的 可 重 载 函 数 。

请 参 阅 COleServerDoc::DestroyInPlaceFrame

CO leServerDoc::DeactivateAndUndo

BOOL DeactivateAndUndo();

返 回 值

如 果 成 功 则 返 回 非 零 值 ； 否 则 返 回 0 。

说 明

如 果 你 的 应 用 程 序 支 持 Undo ， 并 且 用 户 在 激 活 一 个 项 之 后 ， 但 在 对 它 进 行 编辑 之 前 选 择 了 Undo ， 则 调 用 这 个 函 数 。 如 果 容 器 应 用 程 序 是 用 微 软 基 础 类 库编 写 的 ， 则 调 用 DeactivateAndUndo 函 数 会 导 致COleClientItem::OnDeactivateAndUndo 被 调 用 ， 后 者 使 服 务 器 应 用 程 序 的 用 户

请 参 阅 COleClientItem::OnDeactivateAndUndo

CO leServerDoc::DestroyInPlaceFrame

virtual void DestroyInPlaceFrame( COleIPFrameWnd* pFrame );

参 数

pFrame

指 向 将 要 被 销 毁 的 现 场 框 架 窗 口 的 指 针 。

说 明

框 架 调 用 这 个 函 数 来 销 毁 一 个 现 场 框 架 窗 口 ， 并 将 服 务 器 应 用 程 序 的 文 档 窗 口返 回 到 其 在 现 场 激 活 之 前 的 状 态 。

请 参 阅 COleServerDoc::CreateInPlaceFrame

CO leServerDoc::DiscardUndoState

BOOL DiscardUndoState();

返 回 值

如 果 成 功 则 返 回 非 零 值 ； 否 则 返 回 0 。

说 明

如 果 用 户 执 行 一 个 不 能 被 取 消 的 编 辑 操 作 ， 则 调 用 该 函 数 来 强 制 容 器 应 用 程 序丢 弃 它 的 取 消 状 态 信 息 。

这 个 函 数 使 得 支 持 Undo 的 服 务 器 应 用 程 序 可 以 释 放 资 源 ， 否 则 这 些 资 源 就 要

请 参 阅 COleServerDoc::OnReactivateAndUndo

CO leServerDoc::GetDocObjectServer

virtual CDocObjectServer* GetDocObjectServer( LPOLEDOCUMENTSITE pSite );

返 回 值

如 果 操 作 成 功 则 返 回 一 个 指 向 CDocObjectServer 的 指 针 ； 否 则 返 回 NULL 。

参 数

pSite

指向 IOleDocumentSite 界 面 的 指 针 ， 此 界 面 将 这 个 文 档 与 服 务 器 连 接 起 来 。

说 明

重 载 这 个 函 数 可 以 创 建 一 个 新 的 CDocObjectServer 项 ， 并 返 回 一 个 指 向 这 个 项的 指 针 。 当 一 个 DocObject 服 务 器 被 激 活 时 ， 就 返 回 一 个 非 NULL 指 针 ， 它 表明 客 户 可 以 支 持 DocObjects 。 函 数 的 缺 省 实 现 返 回 NULL 。

一 个 支 持 DocObjects 的 文 档 的 典 型 实 现 将 简 单 地 分 配 一 个 新 的

CDocObjectServer 对 象 ， 并 将 它 返 回 给 调 用 者 。 例 如 ：

CDocObjectServer*

COleServerDoc::GetDocObjectServer( LPOLEDOCUMENTSITE pSite )

{

return new CDocObjectServer( this,pSite);

}

请 参 阅 CDocObjectServer::CDocObjectServer

CO leServerDoc::GetEmbeddedItem COleServerItem* GetEmbeddedItem(); 返 回 值

如 果 成 功 则 返 回 一 个 指 向 代 表 整 个 文 档 的 项 的 指 针 ； 否 则 返 回 NULL 。

说 明

此 函 数 用 来 获 取 一 个 指 向 代 表 整 个 文 档 的 项 的 指 针 。 它 调 用 了

COleServerDoc::OnGetEmb- eddedItem 函 数 ， 这 是 一 个 没 有 缺 省 实 现 的 虚 函 数 。

请 参 阅 COleServerDoc::OnGetEmbeddedItem

CO leServerDoc::GetItemClipRect

void GetItemClipRect( LPRECT lpClipRect ) const;

参 数

lpClipRect

指 向 一 个 RECT 结 构 或 CRect 对 象 的 指 针 ， 此 结 构 或 对 象 用 来 接 收 此 项的 剪 贴 矩 形 坐 标 。

说 明

调 用 这 个 函 数 来 获 取 正 在 进 行 现 场 编 辑 的 项 的 剪 贴 矩 形 坐 标 。 坐 标 是 相 对 于 容器 应 用 程 序 窗 口 的 客 户 区 ， 用 像 素 表 示 的 。

绘 制 不 应 该 发 生 在 剪 贴 矩 形 之 外 。 通 常 ， 绘 制 会 自 动 受 到 限 制 ， 利 用 这 个 函 数可 以 确 定 用 户 是 否 滚 动 到 了 文 档 的 可 见 部 分 之 外 ； 如 果 是 ， 则 通 过 调 用ScrollContainerBy 函 数 按 需 要 滚 动 容 器 文 档 。

请 参 阅 COleServerDoc::GetItemPosition ， COleServerDoc::ScrollContainerBy

CO leServerDoc::GetItemPosition

void GetItemPosition( LPRECT lpPosRect ) const;

参 数

lpPosRect

指 向 一 个 RECT 结 构 或 CRect 对 象 的 指 针 ， 此 结 构 或 对 象 用 来 接 收 此 项 的坐 标 。

说 明

调 用 这 个 成 员 函 数 来 获 取 正 被 现 场 编 辑 的 项 的 坐 标 。 坐 标 相 对 于 容 器 应 用 程 序窗 口 的 客 户 区 ， 用 像 素 表 示 。

项 的 位 置 可 以 与 当 前 剪 贴 矩 形 相 比 较 ， 用 于 确 定 此 项 在 屏 幕 上 可 见（ 或 不 可 见 ） 的 程 度 。

请 参 阅 COleSe rverDoc::GetItemClipRect

CO leServerDoc::GetZoomFactor

BOOL GetZoomFactor( LPSIZE lpSizeNum = NULL, LPSIZE lpSizeDenom = NULL,

LPCRECT lpPosRect = NULL ) const;

返 回 值

如 果 此 项 是 为 现 场 编 辑 而 被 激 活 的 ， 并 且 它 的 缩 放 因 子 不 是 100% （ 1:1 ） ， 则返 回 一 个 非 零 值 ； 否 则 返 回 值 为 0 。

参 数

lpSizeNum

指 向 一 个 CSize 类 对 象 的 指 针 ， 此 对 象 将 用 来 保 存 缩 放 因 子 的 分 子 。 该参 数 可 为 NULL 。

lpSizeDenom

指 向 一 个 CSize 类 对 象 的 指 针 ， 此 对 象 将 用 来 保 存 缩 放 因 子 的 分 母 。 该参 数 可 为 NULL 。

lpPosRect

指 向 一 个 CRect 类 对 象 的 指 针 ， 此 对 象 用 于 描 述 此 项 的 新 位 置 。 如 果 该参 数 为 NULL ， 则 该 函 数 使 用 此 项 的 当 前 位 置 。

说 明

GetZoomFactor 成 员 函 数 确 定 一 个 为 现 场 编 辑 而 激 活 的 “ 缩 放 因 子 ” 。 缩 放 因子 是 此 项 的 大 小 与 其 当 前 范 围 之 比 （ 用 像 素 表 示 ） ， 如 果 容 器 应 用 程 序 没 有 设置 此 项 的 范 围 ， 则 使 用 它 的 固 有 范 围 （由 COleServerItem::OnGetExtent 函 数 确定 ） 。

GetZoomFactor 函 数 将 它 的 前 两 个 参 数 设 为 此 项 的 “ 缩 放 因 子 ” 的 分 子 和 分 母 。

如 果 此 项 未 被 现 场 编 辑 ， 则 该 函 数 将 这 些 参 数 设 置 为 缺 省 值 100% （ 或 1:1 ）， 并 返 回 零 。 如 果 要 获 取 更 进 一 步 的 信 息 ， 请 参 见 联 机 技 术 注 释 40 ，“ MFC/OLE 现 场 改 变 大 小 和 缩 放 ” 。

请 参 阅 COleServerDoc::GetItemPosition ， COleServerDoc::GetItemClipRect， COleServerDoc::OnSetItemRects

CO leServerDoc::IsEmbedded

BOOL IsEmbedded() const;

返 回 值

如 果 COleServerDoc 对 象 是 一 个 代 表 容 器 中 的 嵌 入 对 象 的 文 档 ， 则 返 回 非 零 值 ； 否 则 返 回 0 。

说 明

调 用 IsEmbedded 成 员 函 数 来 确 定 文 档 表 示 的 是 否 是 一 个 嵌 入 在 容 器 应 用 程 序中 的 对 象 。 从 文 件 装 载 的 文 档 不 是 嵌 入 式 的 ， 尽 管 它 可 以 由 容 器 应 用 程 序 链 接来 操 作 。 嵌 入 在 容 器 文 档 中 的 文 件 被 认 为 是 嵌 入 式 的 。

CO leServerDoc::IsInPlaceActive

BOOL IsInPlaceActive() const;

返 回 值

如 果 COleServerDoc 对 象 是 现 场 活 动 的 ， 则 返 回 非 零 值 ； 否 则 返 回 0 。

说 明

调 用 IsInPlaceActive 成 员 函 数 来 确 定 此 项 当 前 是 否 处 于 现 场 活 动 状 态 。

请 参 阅 COleServerDoc::ActiveInPlace ， COleServerDoc::OnReactivateAndUndo ， COleServerDoc::ActivateInPlace

CO leServerDoc::NotifyChanged

void NotifyChanged();

说 明

此 函 数 将 文 档 改 变 了 的 信 息 通 知 给 与 此 文 档 链 接 的 所 有 链 接 项 ， 一 般 的 ， 应 用程 序 在 用 户 改 变 某 些 全 局 属 性 （ 比 如 服 务 器 文 档 的 大 小 ） 之 后 ， 调 用NotifyChanged 函 数 。 如 果 用 一 个 自 动 链 接 将 一 个 OLE 项 链 接 到 此 文 档 上 ， 则将 更 新 此 项 以 反 映 这 些 改 变 。 在 用 微 软 基 础 类 库 编 写 的 容 器 应 用 程 序 中 ， 将 调用 COleClientItem 的 OnChange 函 数 。

注 意 这 个 函 数 是 为 与 OLE 兼 容 而 提 供 的 。 新 应 用 程 序 应 该 使 用

UpdateAllItems 函 数 。

请 参 阅 COleServerDoc::NotifyClosed ， COleServerDoc::NotifySaved ， C O leServerDoc::OnChange

CO leServerDoc::NotifyClosed

void NotifyClosed();

说 明

此 函 数 通 知 容 器 应 用 程 序 文 档 已 经 关 闭 。 当 用 户 从 File 菜 单 中 选 择 Close 命 令时 ， 由 COleServerDoc 实 现 的 OnCloseDocument 成 员 函 数 调 用 NotifyClosed 函数 。 在 用 微 软 基 础 类 库 编 写 的 容 器 应 用 程 序 中 ， 将 调 用 COleClientItem 的OnChange 成 员 函 数 。

请 参 阅 COleServerDoc::NotifyChanged ， COleServerDoc::NotifySaved ，

COleServerDoc::OnChange ， COleServerDoc::OnCloseDocument

CO leServerDoc::NotifyRename

void NotifyRename( LPCTSTR lpszNewName );

参 数

lpszNewName

• 个 字 符 串 指 针 ， 此 字 符 串 指 定 服 务 器 文 档 的 新 名 字 ；

  它 通 常 是 一 个 全 路

径 。

说 明

在 用 户 改 换 服 务 器 文 档 的 名 字 之 后 ，调 用 此 函 数 。当 用 户 从 File 菜 单 中 选 择 Save As 命 令 时 ， 由 COleServerDoc 实 现 的 OnSaveDocument 成 员 函 数 调 用NotifyRename 函 数 。 NotifyRename 函 数 通 知 OLE 系 统 DLLs ， 后 者 再 接 着 通 知

容 器 应 用 程 序 。 在 用 微 软 基 础 类 库 容 器 应 用 程 序 中 ， 将 调 用 COleClientItem 的

OnChange 成 员 函 数 。

请 参 阅 COleServerDoc::NotifySaved ， CDocument::OnSaveDocument

CO leServerDoc::NotifySaved

void NotifySaved();

说 明

在 用 户 保 存 了 服 务 器 文 档 之 后 ， 调 用 该 函 数 。 当 用 户 从 File 菜 单 中 选 择 Save 命 令 时 ， 由 COleServerDoc 实 现 的 OnSaveDocument 成 员 函 数 为 应 用 程 序 调 用NotifySaved 函 数 。 NotifySaved 函 数 通 知 OLE 系 统 DLL ， 后 者 再 接 着 通 知 容 器应 用 程 序 。 在 用 微 软 基 础 类 库 编 写 的 容 器 应 用 程 序 中 ， 将 调 用 COleClientItem 的 OnChange 成 员 函 数 。

请 参 阅 COleServerDoc::NotifyChanged ， COleServerDoc::NotifyClosed ， COleClientItem::OnChange ， CDocument::OnSaveDocument

CO leServerDoc::OnClose

virtual void OnClose( OLECLOSE dwCloseOption );

参 数

dwCloseOption

一 个 OLECLOSE 枚 举 值 。 这 个 参 数 的 值 可 以 是 下 列 值 之 一 ：

• OLECLOSE_SAVEIFD IRTY 如 果 文 件 已 被 修 改 则 将 该 文 件 保 存

  。

• OLECLOSE_NOSAVE 将 文 件 关 闭 而 不 保 存 。

• OLECLOSE_PROMPTSAVE 如 果 文 件 已 被 修 改 ， 则 向 用 户 提 示 保

  存文 件 。

说 明

当 容 器 应 用 程 序 请 求 关 闭 服 务 器 文 档 时 ， 框 架 调 用 此 函 数 。 函 数 的 缺 省 实 现 调用 CDocument::OnCloseDocument 函 数 。 要 获 取 更 多 有 关 OLECLOSE 和 其 它 值的 信 息 ， 请 参 见 OLE 文 档 的 OLECLOSE 。

请 参 阅 COleException ， CDocument::OnCloseDocument

CO leServerDoc::OnDeactivate

virtual void OnDeactivate();

说 明

当 用 户 使 一 个 当 前 现 场 活 动 的 嵌 入 或 链 接 项 变 为 不 活 动 的 时 候 ， 框 架 调 用 此 函数 。 该 函 数 将 容 器 应 用 程 序 的 用 户 界 面 恢 复 到 其 原 始 状 态 ， 并 销 毁 视 窗 为 现 场

激 活 所 创 建 的 任 何 菜 单 和 其 它 控 件 。

此 时 ， 取 消 状 态 信 息 应 当 被 无 条 件 释 放 。

要 获 取 更 多 的 信 息 ， 请 参 见 “ V isual C++ 程 序 员 指 南 ” 中 的 文 章 “ 激 活 ” 。

请 参 阅 COleServerDoc::ActivateInPlace ， COleServerDoc::OnDeactivateU I， COleServerDoc::DestroyInPlaceFrame

CO leServerDoc::OnDeactivateUI

virtual void OnDeactivateUI( BOOL bUndoable );

参 数

bUndoable

指 示 编 辑 改 变 是 否 可 以 被 取 消 。

当 用 户 使 一 个 现 场 活 动 的 项 变 为 不 活 动 时 ， 调 用 此 函 数 。 函 数 将 容 器 应 用 程 序的 用 户 界 面 恢 复 到 其 原 始 状 态 ， 隐 藏 由 现 场 激 活 所 创 建 的 任 何 菜 单 和 其 它 控件 。

框 架 总 是 设 置 bUndoable 为 FALSE 。 如 果 服 务 器 应 用 程 序 支 持 取 消 操 作 ， 但 是不 存 在 一 个 可 被 取 消 的 操 作 ， 则 bUndoable 设 置 为 TRUE 来 调 用 由 基 类 实 现 的OnDeactivateUI 函 数 。

请 参 阅 COleServerDoc::OnDeactivate

CO leServerDoc::OnDoc W indowActivate

virtual void OnDocWindowActivate( BOOL bActivate );

bActivate

指 示 是 将 文 档 窗 口 激 活 还 是 使 它 成 为 不 活 动 的 。

说 明

框 架 调 用 这 个 函 数 来 激 活 用 于 现 场 编 辑 的 一 个 文 档 窗 口 ， 或 使 此 窗 口 变 成 不 活动 的 。 该 函 数 的 缺 省 实 现 是 删 除 或 增 加 相 应 的 框 架 顶 层 用 户 界 面 元 素 。 如 果 当包 含 项 的 文 档 被 激 活 或 成 为 不 活 动 时 ， 应 用 程 序 希 望 执 行 附 加 的 动 作 ， 则 可 以重 载 这 个 函 数 。

请 参 阅 COleServerDoc::ActivateInPlace ，

COleServerDoc::OnReactivateAndUndo ，

COleServerDoc::OnShowControlBars ，

COleServerDoc::OnDeactivateU I， COleServerDoc::OnFrameWindowActivate ， COleIPFrameWnd

CO leServerDoc::OnExecOleCmd

HRESULT OnExecOleCmd( const GUID* pGroup , DWORD nCmdID ,

DWORD nCmdExecOu t , VARIANTARG* pvaIn , VARIANTARG* pvaOut );

返 回 值

如 果 成 功 则 返 回 S_OK ； 否 则 ， 返 回 下 列 错 误 代 码 之 一 ：

Value Description

E_UNEXPECTED 发 生 了 意 外 的 错 误

E_FAIL 发 生 了 错 误

E_NOTIMPL 表明 MFC 自 身 要 尝 试 翻 译 和 分 派 命 令

Value Description

OLECMDERR_E_UNKNOWNG ROUP

pGroup 不 是 NULL ， 但 是 不 表 示 一 个 被认 可 的 命 令 组

OLECMDERR_E_NOTSUPPOR TED

续 表

nCmdID 不 被 认 可 为 是 pGroup 群 中 的 有效 命 令

OLECMDERR_DISABLED 由 nCmdID 标 识 的 命 令 被 变 为 无 效 ， 不 能

被 执 行

OLECMDERR_NOHELP 调 用 者 请 求 有 关 由 nCmdID 标 识 的 命 令 的

帮 助 ， 但 是 没 有 可 用 的 帮 助

OLECMDERR_CANCELED 用 户 取 消 了 执 行

参 数

pGroup

一 个 指 向 GUID 的 指 针 ，这 个 GUID 标 识 了 一 个 命 令 集 。它 可 以 是 NULL ， 这 表 示 缺 省 的 命 令 组 。

nCmdID

要 执 行 的 命 令 。 必 须 是 在 由 pGroup 标 识 的 组 中 。

nCmdExecOut

对 象 执 行 命 令 的 方 式 ， 可 以 是 下 列 OLE C MDEXECOPT 枚 举 值 中 的 一 个或 某 几 个 ：

pvaIn

• OLECMDEXECOPT_DODEFAULT

• OLECMDEXECOPT_PROMPTUSER

• OLECMDEXECOPT_DONTPROMPTUSER

• OLECMDEXECOPT_SHOWHELP

指 向 一 个 V A R IANTARG 的 指 针 ， 这 个 VARIANTARG 包 含 了 命 令 的 输入 参 数 。 它 可 以 是 NULL 。

pvaOut

指 向 一 个 V A R IANTARG 的 指 针 ， 这 个 VARIANTARG 用 来 接 收 来 自 命令 的 输 出 返 回 值 。 它 可 以 是 NULL 。

说 明

框 架 调 用 这 个 函 数 来 执 行 一 个 指 定 的 命 令 ， 或 为 命 令 显 示 帮 助 。

COleCmdUI 可 以 用 来 使 能 ， 更 新 和 设 置 DocObject 用 户 界 面 命 令 的 其 它 属 性 。在 命 令 被 初 始 化 之 后 ， 你 可 以 用 OnExecOleCmd 来 执 行 它 们 。 在 框 架 尝 试 翻 译和 分 派 一 个 OLE 文 档 命 令 之 前 ， 它 调 用 这 个 函 数 。 在 处 理 标 准 的 OLE 文 档 命令 时 ， 你 不 必 重 载 这 个 函 数 。 但 是 如 果 你 想 处 理 你 自 己 的 定 制 命 令 ， 或 处 理 需要 接 收 参 数 或 返 回 结 果 的 命 令 时 ， 你 必 须 要 重 载 这 个 函 数 。

大 多 数 命 令 不 需 要 接 收 参 数 或 返 回 结 果 。 对 于 大 多 数 的 命 令 来 说 ， 调 用 者 可 以将 NULL 赋 给 pvaIn 和 pvaOu t。 对 于 那 些 需 要 接 收 输 入 参 数 的 命 令 ， 调 用 者 可以 声 明 和 初 始 化 一 个 VARIANTARG 变 量 ， 并 将 一 个 指 针 传 递 给 pvaIn 中 的 变量 。 对 需 要 一 个 单 一 值 的 命 令 ， 参 数 被 直 接 保 存 在 VARIANTARG 中 ， 并 传 递

给 函 数 。 而 多 个 参 数 则 必 须 要 在 VARIANTARG 中 使 用 某 个 允 许 的 类 型 （ 如

ID ispatch 和 SAFEARRAY ） 来 打 包 。

类 似 的 ， 如 果 一 个 命 令 要 返 回 参 数 ， 则 调 用 者 需 要 定 义 一 个 VARIANTARG ， 将 它 初 始 化 为 VT_EMPTY ， 并 将 它 的 地 址 传 递 给 pvaOut 。 如 果 命 令 返 回 一 个单 一 的 值 ， 则 对 象 可 以 将 这 个 值 直 接 保 存 在 pvaOut 中 。 如 果 有 多 个 输 出 值 则必 须 用 某 种 适 用 于 VARIANTARG 的 方 法 来 打 包 。

这 个 函 数 的 基 类 实 现 将 使 OLE COMMAND_MAP 结 构 与 命 令 目 标 相 联 系 ， 并尝 试 为 命 令 分 派 一 个 合 适 的 句 柄 。 函 数 的 基 类 实 现 只 处 理 不 接 收 参 数 和 不 返 回结 果 的 命 令 。 如 果 你 需 要 处 理 接 收 参 数 或 返 回 结 果 的 命 令 ， 你 就 必 须 重 载 这 个函 数 ， 并 且 自 己 来 处 理 pvaIn 和 pvaOu t。

请 参 阅 COleCmdUI

CO leServerDoc::OnFrame W indowActivate

virtual void OnFrameWindowActivate( BOOL bActivate );

参 数

bActivate

指 示 框 架 窗 口 是 要 被 激 活 还 是 变 为 不 活 动 的 。

说 明

当 容 器 应 用 程 序 的 框 架 窗 口 被 激 活 或 变 为 不 活 动 时 ， 框 架 调 用 这 个 函 数 。 此 函数 的 缺 省 实 现 是 取 消 框 架 窗 口 可 能 处 于 的 任 何 帮 助 方 式 。 如 果 当 框 架 窗 口 被 激活 或 成 为 不 活 动 时 ， 应 用 程 序 想 要 执 行 特 定 的 处 理 ， 则 可 以 重 载OnFrameWindowActive 函 数 。

如 果 要 获 取 更 多 的 信 息 ， 请 参 见 “ Visual C++ 程 序 员 指 南 ” 中 的 文 章 “ 激 活 ” 。

请 参 阅 COleServerDoc::OnDocWindowActivate

CO leServerDoc::OnGetEmbeddedItem

virtual COleServerItem* OnGetEmbeddedItem() = 0;

返 回 值

如 果 成 功 则 返 回 一 个 指 向 代 表 着 整 个 文 档 的 项 的 指 针 ； 否 则 返 回 NULL 。

说 明

当 容 器 应 用 程 序 调 用 服 务 器 应 用 程 序 来 创 建 或 编 辑 一 个 嵌 入 项 时 ， 框 架 调 用 该函 数 。 该 函 数 没 有 缺 省 实 现 。 应 用 程 序 必 须 重 载 这 个 函 数 以 返 回 一 个 表 示 整 个文 档 的 项 。 这 个 返 回 值 应 该 是 一 个 COleServerItem 派 生 类 对 象 。

请 参 阅 COleLinkingDoc::OnGetLinkedItem ， COleServerItem

CO leServerDoc::OnReactivateAndUndo

virtual BOOL OnReactivateAndUndo();

返 回 值

如 果 成 功 则 返 回 一 个 非 零 值 ； 否 则 返 回 0 。

说 明

当 用 户 选 择 取 消 对 一 个 已 被 现 场 激 活 ， 后 来 又 变 为 不 活 动 的 项 所 作 的 改 变 时 ， 框 架 调 用 这 个 函 数 。 该 函 数 的 缺 省 实 现 除 了 返 回 FALSE 来 表 明 失 败 之 外 ， 它不 做 任 何 事 情 。

如 果 你 的 应 用 程 序 要 支 持 取 消 ， 请 重 载 这 个 函 数 。 通 常 应 用 程 序 会 执 行 取 消 操作 ， 然 后 调 用 ActivateInPlace 函 数 来 激 活 项 。 如 果 容 器 应 用 程 序 是 用 微 软 基 础类 库 编 写 的 ， 则 调 用 COleClientItem::ReactivateAndUndo 会 导 致 调 用

OnReactivateAndUndo 函 数 。

请 参 阅 COleServerDoc::ActivateInPlace ， COleServerDoc::IsInPlaceActive， COleClientItem::ReactivateAndUndo

CO leServerDoc::OnResizeBorder

virtual void OnResizeBorder( LPCRECT lpRectBorder , LPOLEINPLACEUIWINDOW lpUIWindow , BOOL bFrame );

参 数

lpRectBorder

指 向 一 个 RECT 结 果 或 CRect 对 象 的 指 针 ， 此 结 构 或 对 象 指 定 边 框 的 坐 标 。

lpUIWindow

指 向 一 个 IOleInPlaceUIWindow 类 对 象 ， 此 对 象 拥 有 当 前 的 现 场 编 辑 会 话 。

bFrame

如 果 lpUIWindow 指 向 容 器 应 用 程 序 的 顶 层 框 架 窗 口 ， 则 设 该 参 数 为

TRUE ； 如 果 lpUIWindow 指 向 容 器 应 用 程 序 的 文 档 顶 层 框 架 窗 口 ， 则 设该 参 数 为 FALSE 。

说 明

当 容 器 应 用 程 序 的 框 架 窗 口 改 变 大 小 时 ， 框 架 调 用 这 个 函 数 。 该 函 数 根 据 新 的窗 口 大 小 来 改 变 和 调 整 工 具 条 和 其 它 用 户 界 面 元 素 的 大 小 。

此 函 数 是 一 个 高 级 的 可 重 载 函 数 。

请 参 阅 COleServerDoc::OnShowControlBars

CO leServerDoc::OnSetHostNames

virtual void OnSetHostNames( LPCTSTR lpszHost , LPCTSTR lpszHostObj );

参 数

lpszHost

指 向 一 个 字 符 串 的 指 针 ， 该 字 符 串 指 定 了 容 器 应 用 程 序 的 名 字 。

lpszHostObj

指 向 一 个 字 符 串 的 指 针 ， 该 字 符 串 指 定 了 文 档 的 容 器 名 称 。

说 明

当 容 器 应 用 程 序 设 置 或 改 变 此 文 档 的 主 机 名 时 ， 框 架 调 用 此 函 数 。 此 函 数 的 缺省 实 现 改 变 所 有 引 用 此 文 档 的 视 的 文 档 标 题 。

如 果 你 的 应 用 程 序 想 通 过 一 种 不 同 的 机 制 来 设 置 标 题 ， 则 需 要 重 载 这 个 函 数 。

请 参 阅 COleClientItem::SetHostNames

CO leServerDoc::OnSetItemRects

virtual void OnSetItemRects( LPCRECT lpPosRect , LPCRECT lpClipRect );

参 数

lpPosRect

指 向 一 个 RECT 结 构 或 CRect 对 象 的 指 针 ， 此 结 构 或 对 象 指 定 框 架 窗 口相 对 于 容 器 应 用 程 序 的 客 户 区 的 位 置 。

lpClipRect

指 向 一 个 RECT 结 构 或 CRect 对 象 的 指 针 ， 此 结 构 或 对 象 指 定 在 适 当 位置 的 框 架 窗 口 的 剪 贴 矩 形 （ 相 对 于 容 器 应 用 程 序 的 客 户 区 ） 。

说 明

框 架 调 用 这 个 函 数 来 在 容 器 应 用 程 序 的 框 架 窗 口 内 定 位 现 场 编 辑 创 建 窗 口 。 如

果 有 必 要 更 新 视 的 缩 放 因 子 ， 则 可 以 重 载 这 个 函 数 。

尽 管 OnSsetItemRects 可 以 在 任 何 时 候 由 容 器 应 用 程 序 调 用 来 请 求 改 变 现 场 可编 辑 项 的 位 置 ， 但 它 通 常 还 是 用 于 响 应 RequestPositionChange 调 用 。

请 参 阅 CO leServerDoc::RequestPositionChange ，

COleIPFrameWnd::RepositionFram e，

COleClientItem::SetItemRects ， COleServerDoc::GetZoomFactor

CO leServerDoc::OnShowControlBars

virtual void OnShowControlBars( CFrameWnd * pFrameWnd , BOOL bShow );

参 数

pFrameWnd

指 向 框 架 窗 口 的 指 针 ， 此 框 架 窗 口 的 控 制 条 将 被 隐 藏 或 显 示 。

bShow

确 定 控 制 条 是 显 示 还 是 隐 藏 。

说 明

框 架 调 用 这 个 函 数 来 显 示 或 隐 藏 与 pFrameWnd 所 标 识 的 框 架 窗 口 相 关 联 的 服务 器 应 用 程 序 的 控 制 条 。 该 函 数 的 缺 省 实 现 是 枚 举 该 框 架 窗 口 所 拥 有 的 所 有 控制 条 ， 并 隐 藏 或 显 示 它 们 。

请 参 阅 COleServerDoc::ActivateInPlace ，

COleServerDoc::OnReactivateAndUndo ， COleServerDoc::OnFrameWindowActivate ，

COle S erverDoc::IsInPlaceActive

CO leServerDoc::OnShowDocument

virtual void OnShowDocument( BOOL bShow );

参 数

bShow

指 示 是 显 示 还 是 隐 藏 文 档 的 用 户 界 面 。

说 明

当 服 务 器 文 档 必 须 被 隐 藏 或 显 示 时 ， 框 架 调 用 OnShowDocument 函 数 。 如 果bShow 为 TRU E ， 则 该 函 数 的 缺 省 实 现 是 在 响 应 时 激 活 服 务 器 拥 有 的 程 序 ， 并使 容 器 应 用 程 序 滚 动 它 的 窗 口 以 使 此 项 可 见 。 如 果 bShow 为 FALSE ， 则 函 数的 缺 省 实 现 是 通 过 一 个 OnDeactivate 调 用 使 此 项 不 活 动 ， 然 后 销 毁 或 隐 藏 为 该文 档 创 建 的 所 有 框 架 窗 口 （ 除 了 第 一 个 ） 。 如 果 没 有 可 见 文 档 ， 则 该 函 数 的 缺

省 实 现 隐 藏 服 务 器 应 用 程 序 。

请 参 阅 COleServerDoc::ActivateInPlace ， COleServerItem::OnDoVerb ， COleServerDoc::IsInPlaceActive， COleServerDoc::OnDeactivateUI

CO leServerDoc::OnUpdateDocument

virtual BOOL OnUpdateDocument();

返 回 值

如 果 文 档 被 成 功 地 更 新 则 返 回 非 零 值 ； 否 则 返 回 0 。

说 明

当 保 存 一 个 作 为 复 合 文 档 中 的 嵌 入 项 的 文 档 时 ， 框 架 调 用 该 函 数 。 该 函 数 的 缺省 实 现 调 用 COleServerDoc::NotifySaved 和 COleServerDoc::SaveEmbedding 成

员 函 数 ， 然 后 将 文 档 标 记 为 干 净 的 （ 未 修 改 的 ） 。 如 果 应 用 程 序 想 要 在 更 新 一个 嵌 入 项 时 执 行 特 定 的 处 理 ， 则 必 须 重 载 这 个 函 数 。

请 参 阅 COleServerDoc::NotifySaved ， COleServerDoc::SaveEmbedding ， CDocument::OnSaveDocument

CO leServerDoc::RequestPositionChange

void RequestPositionChange( LPCRECT lpPosRect );

参 数

lpPosRect

指 向 一 个 RECT 结 构 或 CRect 对 象 的 指 针 ， 此 结 构 或 对 象 中 包 含 此 项 的 新位 置 。

说 明

此 成 员 函 数 使 容 器 应 用 程 序 改 变 此 项 的 位 置 。 当 现 场 活 动 的 项 中 的 数 据 改 变时 ， 通 常 调 用 RequestPositionChange 函 数 （与 Upda te AllItems 一 起 调 用 ） 。 在此 调 用 之 后 ， 容 器 应 用 程 序 可 能 调 用 也 可 能 不 调 用 OnSetItemRects 函 数 来 执 行这 个 改 变 。 最 终 位 置 可 能 与 请 求 的 位 置 并 不 相 同 。

请 参 阅 COleServerDoc::ScrollContainerBy

CO leServerDoc::SaveEmbedding

void SaveEmbedding();

说 明

这 个 函 数 用 来 告 诉 容 器 应 用 程 序 保 存 嵌 入 对 象 。 OnUpdateDocument 会 自 动 调

用 此 函 数 。 值 得 注 意 的 是 这 个 函 数 会 导 致 项 被 在 磁 盘 上 更 新 ， 因 此 ， 它 通 常 只是 作 为 一 次 特 定 用 户 动 作 的 结 果 被 调 用 。

请 参 阅 COleServerDoc::NotifyClosed

CO leServerDoc::ScrollContainerBy

BOOL ScrollContainerBy ( CSize sizeScroll );

返 回 值

如 果 成 功 则 返 回 非 零 值 ； 否 则 返 回 0 。

参 数

sizeScroll

指 示 容 器 文 档 要 滚 动 多 远 。

说 明

ScrollContainerBy 成 员 函 数 将 容 器 文 档 滚 动 sizeScroll 中 所 指 定 的 像 素 数 量 。 正值 表 示 向 下 和 向 右 滚 动 ； 负 值 表 示 向 上 和 向 左 滚 动 。

请 参 阅 COleClientItem::OnScrollBy

CO leServerDoc::UpdateAllItems

void UpdateAllItems( COleServerItem* pSender , LPARAM lHint = 0L ，

CObject* pHint = NULL, DVASPECT nDrawAspect = DVASPECT_CONTENT );

参 数

pSender

指 向 修 改 文 档 的 项 的 指 针 ； 如 果 所 有 项 都 要 被 更 新 ， 则 设 置 该 参 数 为

NULL 。

lH int

包 含 了 有 关 修 改 的 信 息 。

pHint

指 向 一 个 包 含 有 关 修 改 的 信 息 的 对 象 的 指 针 。

nDrawAspect

确 定 如 果 绘 制 此 项 。 该 参 数 是 一 个 DVASPECT 枚 举 值 。 它 可 以 是 下 列值 之 一 ：

• DVASPECT_CONTENT 用 一 种 可 将 项 显 示 为 其 容 器 文 档 中 一 个

  嵌 入对 象 的 方 式 来 显 示 此 项 。

• DVASPECT_THUMBNAIL 以 “ 拇 指 甲 ” 的 方 式 来 显 示 项 ， 以 使

  它能 在 浏 览 工 具 中 显 示 。

• DVASPECT_ICON 将 项 显 示 为 一 个 图 标 。

• DVASPECT_DOCPRINT 将 项 显 示 为 就 好 象 是 在 利 用 File 菜 单 中

  的

Print 命 令 打 印 它 。

说 明

此 函 数 将 文 档 改 变 了 的 信 息 通 知 给 连 接 在 此 文 档 上 的 所 有 链 接 项 。 应 用 程 序 一般 在 用 户 改 变 服 务 器 文 档 之 后 调 用 这 个 函 数 。 如 果 一 个 OLE 项 以 一 个 自 动 链接 链 接 到 此 文 档 上 ， 则 该 项 被 更 新 以 反 映 这 些 变 化 。 在 用 微 软 基 础 类 库 编 写 的容 器 应 用 程 序 中 ， 将 调 用 COleClientItem 的 OnChange 成 员 函 数 。

除 了 发 送 项 外 ， Updat e AllItems 函 数 为 文 档 的 每 个 项 调 用 OnUpdate 成 员 函 数 ， 传 递 pHin t， lHint 和 nDrawAspect 参 数 。 利 用 这 些 参 数 将 有 关 对 文 档 所 做 修 改的 信 息 传 递 给 各 个 项 。 应 用 程 序 可 以 利 用 lHint 对 信 息 进 行 编 码 ， 或 者 定 义 一个 CObject 派 生 类 来 存 储 有 关 修 改 的 信 息 并 用 pHint 传 递 一 个 该 类 的 对 象 。 可

在 应 用 程 序 的 COleServerItem 派 生 类 中 重 载 OnUpdate 成 员 函 数 ， 根 据 每 个 项的 显 示 是 否 改 变 了 来 优 化 对 各 个 项 的 更 新 。

请 参 阅 COleServerDoc::NotifyChanged ， COleServerItem::OnUpdate ， COleServerDoc::NotifySaved， COleClientItem::OnChange