COleControl 类

用于开发 OLE 控件的重要基类。

语法

class COleControl : public CWnd

成员

公共构造函数

名称	描述
COleControl::COleControl	创建一个 COleControl 对象。

公共方法

名称	描述
COleControl::AmbientAppearance	检索控件的当前外观。
COleControl::AmbientBackColor	返回环境 BackColor 属性的值。
COleControl::AmbientDisplayName	返回由容器指定的控件的名称。
COleControl::AmbientFont	返回环境 Font 属性的值。
COleControl::AmbientForeColor	返回环境 ForeColor 属性的值。
COleControl::AmbientLocaleID	返回容器的区域设置 ID。
COleControl::AmbientScaleUnits	返回容器使用的单元类型。
COleControl::AmbientShowGrabHandles	确定是否应显示抓取句柄。
COleControl::AmbientShowHatching	确定是否应显示阴影。
COleControl::AmbientTextAlign	返回容器指定的文本对齐类型。
COleControl::AmbientUIDead	确定控件是否应响应用户界面操作。
COleControl::AmbientUserMode	确定容器的模式。
COleControl::BoundPropertyChanged	通知容器绑定属性已更改。
COleControl::BoundPropertyRequestEdit	请求编辑属性值的权限。
COleControl::ClientToParent	将相对于控件的源的点转换为相对于其容器的源的点。
COleControl::ClipCaretRect	如果插入点矩形与控件重叠，则调整插入点矩形。
COleControl::ControlInfoChanged	在控件处理的助记键集更改后调用此函数。
COleControl::DisplayError	向控件的用户显示常用 Error 事件。
COleControl::DoClick	常用 DoClick 方法的实现。
COleControl::DoPropExchange	序列化 COleControl 对象的属性。
COleControl::DoSuperclassPaint	重绘已从 Windows 控件子类化的 OLE 控件。
COleControl::EnableSimpleFrame	启用对控件的简单框架支持。
COleControl::ExchangeExtent	序列化控件的宽度和高度。
COleControl::ExchangeStockProps	序列化控件的常用属性。
COleControl::ExchangeVersion	序列化控件的版本号。
COleControl::FireClick	触发常用 Click 事件。
COleControl::FireDblClick	触发常用 DblClick 事件。
COleControl::FireError	触发常用 Error 事件。
COleControl::FireEvent	触发自定义事件。
COleControl::FireKeyDown	触发常用 KeyDown 事件。
COleControl::FireKeyPress	触发常用 KeyPress 事件。
COleControl::FireKeyUp	触发常用 KeyUp 事件。
COleControl::FireMouseDown	触发常用 MouseDown 事件。
COleControl::FireMouseMove	触发常用 MouseMove 事件。
COleControl::FireMouseUp	触发常用 MouseUp 事件。
COleControl::FireReadyStateChange	当控件的就绪状态发生更改时触发事件。
COleControl::GetActivationPolicy	更改支持 IPointerInactive 接口的控件的默认激活行为。
COleControl::GetAmbientProperty	返回指定环境属性的值。
COleControl::GetAppearance	返回常用 Appearance 属性的值。
COleControl::GetBackColor	返回常用 BackColor 属性的值。
COleControl::GetBorderStyle	返回常用 BorderStyle 属性的值。
COleControl::GetCapture	确定无窗口的已激活控件对象是否具有鼠标捕获。
COleControl::GetClassID	检索控件的 OLE 类 ID。
COleControl::GetClientOffset	检索控件矩形区域的左上角与其工作区左上角之间的差异。
COleControl::GetClientRect	检索控件的工作区的大小。
COleControl::GetClientSite	查询指向其容器中的当前客户端站点的指针的对象。
COleControl::GetControlFlags	检索控件标志设置。
COleControl::GetControlSize	返回 OLE 控件的位置和大小。
COleControl::GetDC	提供可供无窗口控件从其容器获取设备上下文的方法。
COleControl::GetEnabled	返回常用 Enabled 属性的值。
COleControl::GetExtendedControl	检索一个指向属于容器的扩展控件对象的指针。
COleControl::GetFocus	确定控件是否具有焦点。
COleControl::GetFont	返回常用 Font 属性的值。
COleControl::GetFontTextMetrics	返回 CFontHolder 对象的指标。
COleControl::GetForeColor	返回常用 ForeColor 属性的值。
COleControl::GetHwnd	返回常用 hWnd 属性的值。
COleControl::GetMessageString	为菜单项提供状态栏文本。
COleControl::GetNotSupported	防止用户访问控件的属性值。
COleControl::GetReadyState	返回控件的就绪状态。
COleControl::GetRectInContainer	返回控件的矩形（相对于其容器）。
COleControl::GetStockTextMetrics	返回常用 Font 属性的指标。
COleControl::GetText	返回常用 Text 或 Caption 属性的值。
COleControl::GetWindowlessDropTarget	通过替代来允许无窗口控件成为拖放操作的目标。
COleControl::InitializeIIDs	向基类通知控件将使用的 IID。
COleControl::InternalGetFont	返回常用 Font 属性的 CFontHolder 对象。
COleControl::InternalGetText	检索常用的 Caption 或 Text 属性。
COleControl::InternalSetReadyState	设置控件的就绪状态并触发 ready-state-change 事件。
COleControl::InvalidateControl	使所显示控件的区域失效，导致其被重绘。
COleControl::InvalidateRgn	使容器窗口的工作区在给定区域中失效。 可用于重绘区域中的无窗口控件。
COleControl::IsConvertingVBX	允许对 OLE 控件进行专用加载。
COleControl::IsModified	确定控件状态是否已更改。
COleControl::IsOptimizedDraw	指示容器是否支持针对当前绘制操作的优化绘制。
COleControl::IsSubclassedControl	调用后可确定此控件是否为 Windows 控件的子类。
COleControl::Load	重置任何先前的异步数据，并启动对控件异步属性的新加载。
COleControl::LockInPlaceActive	确定控件是否可以由容器停用。
COleControl::OnAmbientPropertyChange	在更改环境属性时调用。
COleControl::OnAppearanceChanged	在常用 Appearance 属性改变时调用。
COleControl::OnBackColorChanged	在常用 BackColor 属性改变时调用。
COleControl::OnBorderStyleChanged	在常用 BorderStyle 属性改变时调用。
COleControl::OnClick	调用后可触发常用 Click 事件。
COleControl::OnClose	通知控件已调用 IOleControl::Close。
COleControl::OnDoVerb	在执行控件谓词后调用。
COleControl::OnDraw	在请求控件重绘自身时调用。
COleControl::OnDrawMetafile	在请求控件使用图元文件设备上下文重绘自身时由容器调用。
COleControl::OnEdit	由容器调用以对 OLE 控件进行 UI 激活。
COleControl::OnEnabledChanged	在常用 Enabled 属性改变时调用。
COleControl::OnEnumVerbs	由容器调用以枚举控件的谓词。
COleControl::OnEventAdvise	在事件处理程序与控件连接或断开连接时调用。
COleControl::OnFontChanged	在常用 Font 属性改变时调用。
COleControl::OnForeColorChanged	在常用 ForeColor 属性改变时调用。
COleControl::OnFreezeEvents	在控件的事件冻结或取消冻结时调用。
COleControl::OnGetColorSet	通知控件已调用 IOleObject::GetColorSet。
COleControl::OnGetControlInfo	向容器提供助记键信息。
COleControl::OnGetDisplayString	调用后可获取表示属性值的字符串。
COleControl::OnGetInPlaceMenu	请求将与容器菜单合并的控件菜单的句柄。
COleControl::OnGetNaturalExtent	通过替代来检索离建议的大小和盘区模式最近的控件的显示大小。
COleControl::OnGetPredefinedStrings	返回表示属性的可能值的字符串。
COleControl::OnGetPredefinedValue	返回与预定义字符串对应的值。
COleControl::OnGetViewExtent	通过替代来检索控件的显示区域的大小（可用于启用两遍绘制）。
COleControl::OnGetViewRect	通过替代将控件的大小转换为从特定位置开始的矩形。
COleControl::OnGetViewStatus	通过替代来检索控件的视图状态。
COleControl::OnHideToolBars	对控件进行 UI 停用时由容器调用。
COleControl::OnInactiveMouseMove	通过替代让鼠标指针下非活动控件的容器将 WM_MOUSEMOVE 消息调度到控件。
COleControl::OnInactiveSetCursor	通过替代让鼠标指针下非活动控件的容器将 WM_SETCURSOR 消息调度到控件。
COleControl::OnKeyDownEvent	在已触发常用 KeyDown 事件后调用。
COleControl::OnKeyPressEvent	在已触发常用 KeyPress 事件后调用。
COleControl::OnKeyUpEvent	在已触发常用 KeyUp 事件后调用。
COleControl::OnMapPropertyToPage	指示用于编辑属性的属性页。
COleControl::OnMnemonic	在按下控件的助记键时调用。
COleControl::OnProperties	在调用了控件的“Properties”谓词后调用。
COleControl::OnQueryHitPoint	通过替代来查询控件的显示是否与给定点重叠。
COleControl::OnQueryHitRect	通过替代来查询控件的显示是否与给定矩形中的任何点重叠。
COleControl::OnRenderData	由框架调用，以检索采用指定格式的数据。
COleControl::OnRenderFileData	由框架调用，用于检索文件中的指定格式的数据。
COleControl::OnRenderGlobalData	由框架调用，用于检索全局内存中的指定格式的数据。
COleControl::OnResetState	将控件的属性重置为默认值。
COleControl::OnSetClientSite	通知控件已调用 IOleControl::SetClientSite。
COleControl::OnSetData	将控件的数据替换为另一个值。
COleControl::OnSetExtent	在控件的盘区发生更改后调用。
COleControl::OnSetObjectRects	在控件的维度发生更改后调用。
COleControl::OnShowToolBars	在对控件进行 UI 激活后调用。
COleControl::OnTextChanged	在更改常用 Text 或 Caption 属性后调用。
COleControl::OnWindowlessMessage	处理无窗口控件的窗口消息（鼠标和键盘消息以外的消息）。
COleControl::ParentToClient	将相对于容器的源的点转换为相对于控件的源的点。
COleControl::PostModalDialog	通知容器已关闭模式对话框。
COleControl::PreModalDialog	通知容器将显示模式对话框。
COleControl::RecreateControlWindow	销毁并重新创建控件的窗口。
COleControl::Refresh	强制重绘控件的外观。
COleControl::ReleaseCapture	释放鼠标捕获。
COleControl::ReleaseDC	释放无窗口控件的容器的显示设备上下文。
COleControl::ReparentControlWindow	重置控件窗口的父级。
COleControl::ResetStockProps	将 COleControl 常用属性初始化为其默认值。
COleControl::ResetVersion	将版本号初始化为给定值。
COleControl::ScrollWindow	允许无窗口控件在显示器上滚动就地活动图像中的区域。
COleControl::SelectFontObject	将自定义 Font 属性选择到设备上下文中。
COleControl::SelectStockFont	将常用 Font 属性选择到设备上下文中。
COleControl::SerializeExtent	序列化或初始化控件的显示空间。
COleControl::SerializeStockProps	序列化或初始化 COleControl 常用属性。
COleControl::SerializeVersion	序列化或初始化控件的版本信息。
COleControl::SetAppearance	设置常用 Appearance 属性的值。
COleControl::SetBackColor	设置常用 BackColor 属性的值。
COleControl::SetBorderStyle	设置常用 BorderStyle 属性的值。
COleControl::SetCapture	使控件的容器窗口代表控件获取鼠标捕获。
COleControl::SetControlSize	设置 OLE 控件的位置和大小。
COleControl::SetEnabled	设置常用 Enabled 属性的值。
COleControl::SetFocus	使控件的容器窗口代表控件获取输入焦点。
COleControl::SetFont	设置常用 Font 属性的值。
COleControl::SetForeColor	设置常用 ForeColor 属性的值。
COleControl::SetInitialSize	在容器中首次显示时设置 OLE 控件的大小。
COleControl::SetModifiedFlag	更改控件的已修改状态。
COleControl::SetNotPermitted	指示编辑请求已失败。
COleControl::SetNotSupported	防止用户修改控件的属性值。
COleControl::SetRectInContainer	设置控件的矩形（相对于其容器）。
COleControl::SetText	设置常用 Text 或 Caption 属性的值。
COleControl::ThrowError	指示 OLE 控件中发生了错误。
COleControl::TransformCoords	转换容器与控件之间的坐标值。
COleControl::TranslateColor	将 OLE_COLOR 值转换为 COLORREF 值。
COleControl::WillAmbientsBeValidDuringLoad	确定下次加载控件时环境属性是否可用。
COleControl::WindowProc	为 COleControl 对象提供 Windows 过程。

受保护方法

名称	描述
COleControl::DrawContent	在需要更新控件外观时由框架调用。
COleControl::DrawMetafile	在使用图元文件设备上下文时由框架调用。
COleControl::IsInvokeAllowed	启用自动化方法调用。
COleControl::SetInitialDataFormats	由框架调用以初始化控件支持的数据格式列表。

备注

此类从 CWnd 派生，它继承了 Windows 窗口对象的所有功能以及其他特定于 OLE 的功能，例如事件触发以及为方法和属性提供支持的功能。

OLE 控件可以插入到 OLE 容器应用程序中，并使用一个进行事件触发和向容器公开方法和属性的双向系统与容器通信。 请注意，标准 OLE 容器仅支持 OLE 控件的基本功能。 它们无法支持 OLE 控件的扩展功能。 当事件由于控件中发生某些操作而被发送到容器时，将发生事件触发。 反过来，容器使用一组公开的方法和属性（类似于 C++ 类的成员函数和数据成员）与控件通信。 此方法允许开发人员控制控件的外观，并在发生某些操作时通知容器。

无窗口控件

OLE 控件处于就地活动状态，可以在没有窗口的情况下使用。 无窗口控件具有显著优势：

• 无窗口控件可以是透明的和非矩形的

• 无窗口控件可缩小对象的实例并缩短对象的创建时间

控件不需要窗口。 可以通过单个共享窗口（通常是容器的）和一点调度代码轻松提供窗口提供的服务。 设置一个窗口大多数情况下会给对象带来不必要的复杂情况。

使用无窗口激活时，容器（有窗口）负责提供本应由控件自己的窗口提供的服务。 例如，如果控件需要查询键盘焦点、查询鼠标捕获或获取设备上下文，这些操作将由容器管理。 COleControl 无窗口操作成员函数在容器中调用这些操作。

启用无窗口激活后，容器会将输入消息委托给控件的 IOleInPlaceObjectWindowless 接口（IOleInPlaceObject 的扩展，用于无窗口支持）。 在相应地调整鼠标坐标后，COleControl 的此接口的实现会通过控件的消息映射调度这些消息。 你可以通过将对应的项添加到消息映射来处理这些消息（例如普通窗口消息）。

在无窗口控件中，应总是使用 COleControl 成员函数而不是对应的 CWnd 成员函数或其相关的 Windows API 函数。

OLE 控件对象也能创建一个窗口，前提是变为活动状态，但进行非活动-活动转换所需的工作量会增加，转换速度会下降。 某些情况下，这是一个问题：例如，在使用文本框网格的情况下。 通过列上下移动光标时，每个控件必须先就地激活，然后停用。 非活动/活动转换的速度将直接影响滚动速度。

有关开发 OLE 控件框架的详细信息，请参阅 MFC ActiveX 控件和概述：创建 MFC ActiveX 控件程序这两篇文章。 有关优化 OLE 控件（包括无窗口控件和无闪烁控件）的信息，请参阅 MFC ActiveX 控件：优化。

继承层次结构

CObject

CCmdTarget

CWnd

COleControl

要求

标头：afxctl.h

COleControl::AmbientBackColor

返回环境 BackColor 属性的值。

OLE_COLOR AmbientBackColor();

返回值

容器的环境 BackColor 属性的当前值（如果有）。 如果不支持此属性，则此函数返回系统定义的 Windows 背景色。

注解

环境 BackColor 属性可用于所有控件，由容器定义。 请注意，容器不需要支持此属性。

COleControl::AmbientDisplayName

容器分配给控件的名称可用在向用户显示的错误消息中。

CString AmbientDisplayName();

返回值

OLE 控件的名称。 默认值为零长度字符串。

备注

请注意，容器不需要支持此属性。

COleControl::AmbientFont

返回环境 Font 属性的值。

LPFONTDISP AmbientFont();

返回值

指向容器的环境 Font 调度接口的指针。 默认值为 NULL。 如果返回值不等于 NULL，则由你负责通过调用 IUnknown::Release 成员函数来释放字体。

备注

环境 Font 属性由容器定义，可供所有控件使用。请注意，容器不需要支持此属性。

COleControl::AmbientForeColor

返回环境 ForeColor 属性的值。

OLE_COLOR AmbientForeColor();

返回值

容器的环境 ForeColor 属性的当前值（如果有）。 如果不受支持，此函数将返回系统定义的 Windows 文本颜色。

备注

环境 ForeColor 属性可用于所有控件，由容器定义。 请注意，容器不需要支持此属性。

COleControl::AmbientLocaleID

返回容器的区域设置 ID。

LCID AmbientLocaleID();

返回值

容器的 LocaleID 属性的值（如果有）。 如果此属性不受支持，此函数将返回 0。

注解

此控件可以使用 LocaleID，根据特定区域设置来调整其用户界面。 请注意，容器不需要支持此属性。

COleControl::AmbientAppearance

检索控件对象的当前外观设置。

short AmbientAppearance();

返回值

控件的外观：

• 0 平面外观

• 1 3D 外观

注解

调用此函数以检索控件的 DISPID_AMBIENT_APPEARANCE 属性的当前值。

COleControl::AmbientScaleUnits

返回容器使用的单元类型。

CString AmbientScaleUnits();

返回值

一个包含容器的环境 ScaleUnits 的字符串。 如果此属性不受支持，此函数将返回长度为零的字符串。

备注

容器的环境 ScaleUnits 属性可用于显示标有所选单位（例如缇或厘米）的位置或维度。 请注意，容器不需要支持此属性。

COleControl::AmbientShowGrabHandles

确定容器是否允许控件在活动时显示自身抓取句柄。

BOOL AmbientShowGrabHandles();

返回值

如果应显示抓取句柄，则为非零值；否则为 0。 如果此属性不受支持，此函数将返回非零值。

备注

请注意，容器不需要支持此属性。

COleControl::AmbientShowHatching

确定容器是否允许控件在 UI 处于活动状态时使用带阴影的图案显示自身。

BOOL AmbientShowHatching();

返回值

如果应显示带阴影的图案，则为非零值；否则为 0。 如果此属性不受支持，此函数将返回非零值。

备注

请注意，容器不需要支持此属性。

COleControl::AmbientTextAlign

确定控件容器首选的环境文本对齐方式。

short AmbientTextAlign();

返回值

容器的环境 TextAlign 属性的状态。 如果此属性不受支持，此函数将返回 0。

以下是有效返回值的列表：

返回值	含义
0	一般对齐方式（数字对齐到右侧，文本对齐到左侧）。
1	左对齐
2	中心
3	右对齐

注解

此属性适用于所有嵌入控件，由容器定义。 请注意，容器不需要支持此属性。

COleControl::AmbientUIDead

确定容器是否想要控件响应用户界面操作。

BOOL AmbientUIDead();

返回值

如果控件应响应用户界面操作，则为非零值；否则为 0。 如果此属性不受支持，此函数将返回 0。

备注

例如，容器可能会在设计模式下将此设置为 TRUE。

COleControl::AmbientUserMode

确定容器是处于设计模式还是用户模式。

BOOL AmbientUserMode();

返回值

如果容器处于用户模式，则为非零值；否则为 0（处于设计模式）。 如果此属性不受支持，此函数将返回 TRUE。

注解

例如，容器可能会在设计模式下将此设置为 FALSE。

COleControl::BoundPropertyChanged

指示绑定属性值已更改。

void BoundPropertyChanged(DISPID dispid);

参数

dispid
控件的绑定属性的调度 ID。

备注

每当属性值发生更改时，都必须调用此值，即使未通过属性 Set 方法进行更改。 特别请注意映射到成员变量的绑定属性。 每当此类成员变量发生更改时，必须调用 BoundPropertyChanged。

COleControl::BoundPropertyRequestEdit

请求来自 IPropertyNotifySink 接口的权限以更改控件提供的绑定属性值。

BOOL BoundPropertyRequestEdit(DISPID dispid);

参数

dispid
控件的绑定属性的调度 ID。

返回值

如果允许更改，则为非零值；否则为 0。 默认值为非零值。

注解

如果权限被拒绝，则控件不得让属性的值发生更改。 可以通过忽略尝试更改属性值的操作或让其失败来实现这一点。

COleControl::ClientToParent

将 pPoint 的坐标转换为父坐标。

virtual void ClientToParent(
    LPCRECT lprcBounds,
    LPPOINT pPoint) const;

参数

lprcBounds
指向容器中 OLE 控件的边界的指针。 不是工作区，而是整个控件的区域，包括边框和滚动条。

pPoint
指向 OLE 工作区点的指针，该点将转换为父级（容器）的坐标。

备注

在输入时，pPoint 是相对于 OLE 控件工作区原点（控件工作区左上角）的。 在输出时，pPoint 是相对于父级的原点（容器左上角）的。

COleControl::ClipCaretRect

如果插入点矩形被重叠的不透明对象完全或部分覆盖，则调整插入点矩形。

BOOL ClipCaretRect(LPRECT lpRect);

参数

lpRect
在输入时指向 RECT 结构的指针，该结构包含要调整的插入点区域。 在输出时已调整的插入点区域；如果插入点矩形被完全覆盖，则为 NULL。

返回值

如果成功，则不为 0；否则为 0。

备注

插入点是闪烁的线条、块或位图，通常指示将插入文本或图形的位置。

在不先检查插入点是被重叠对象部分隐藏还是完全隐藏的情况下，无窗口对象无法安全地显示插入点。 为了使之成为可能，对象可使用 ClipCaretRect 来获取调整的（变小的）插入点，以确保它适合剪切区域。

创建插入点的对象应将插入点矩形提交到 ClipCaretRect，对插入点使用调整后的矩形。 如果插入点完全隐藏，此方法将返回 FALSE，在这种情况下，根本不应显示插入点。

COleControl::COleControl

构造 COleControl 对象。

COleControl();

备注

通常不直接调用此函数， 而是改由类工厂创建 OLE 控件。

COleControl::ControlInfoChanged

在控件支持的助记键集更改后调用此函数。

void ControlInfoChanged();

备注

收到此通知后，控件的容器通过调用 IOleControl::GetControlInfo 来获取新的助记键集。 请注意，此容器不需要响应此通知。

COleControl::DisplayError

在处理常用 Error 事件后由框架调用（除非事件处理程序已禁止显示错误）。

virtual void DisplayError(
    SCODE scode,
    LPCTSTR lpszDescription,
    LPCTSTR lpszSource,
    LPCTSTR lpszHelpFile,
    UINT nHelpID);

参数

scode
要报告的状态代码值。 有关可能代码的完整列表，请参阅 ActiveX 控件：高级主题一文。

lpszDescription
所报告的错误的说明。

lpszSource
生成错误的模块的名称（通常为 OLE 控件模块的名称）。

lpszHelpFile
包含错误说明的帮助文件的名称。

nHelpID
所报告的错误的帮助上下文 ID。

备注

默认行为显示一个消息框，其中包含错误的说明，该消息框包含在 lpszDescription 中。

替代此函数以自定义错误显示方式。

COleControl::DoClick

模拟控件上的鼠标单击操作。

void DoClick();

注解

将调用可替代 COleControl::OnClick 成员函数，并将在控件支持的情况下触发常用 Click 事件。

COleControl 基类支持将此函数作为名为 DoClick 的常用方法。 有关详细信息，请参阅 ActiveX 控件：方法一文。

COleControl::DoPropExchange

从持久性存储表示形式（如流或属性集）加载或存储控件时由框架调用。

virtual void DoPropExchange(CPropExchange* pPX);

参数

pPX
一个指向 CPropExchange 对象的指针。 框架提供了此对象以建立属性交换的上下文，包括其方向。

备注

此函数通常调用 PX_ 系列函数来加载或存储 OLE 控件的特定的用户定义属性。

如果控件向导已用于创建 OLE 控件项目，则此函数的替代版本将通过调用基类函数 COleControl::DoPropExchange 来序列化 COleControl 所支持的常用属性。 将用户定义的属性添加到 OLE 控件时，需要修改此函数以序列化新属性。 有关序列化的详细信息，请参阅 ActiveX 控件：序列化一文。

COleControl::DoSuperclassPaint

重绘已从 Windows 控件子类化的 OLE 控件。

void DoSuperclassPaint(
    CDC* pDC,
    const CRect& rcBounds);

参数

pDC
指向控件容器的设备上下文的指针。

rcBounds
要在其中绘制控件的区域。

备注

调用此函数以正确处理非活动 OLE 控件的绘制。 仅当 OLE 控件子类是 Windows 控件，并且应在控件的 OnDraw 函数中调用时，才应使用此函数。

若要详细了解此函数以及如何对 Windows 控件进行子类化，请参阅 ActiveX 控件：子类化 Windows 控件一文。

COleControl::DrawContent

在需要更新控件外观时由框架调用。

void DrawContent(
    CDC* pDC,
    CRect& rc);

参数

pDC
指向设备上下文的指针。

rc
要在其中进行绘制的矩形区域。

备注

此函数直接调用可替代 OnDraw 函数。

COleControl::DrawMetafile

在使用图元文件设备上下文时由框架调用。

void DrawMetafile(
    CDC* pDC,
    CRect& rc);

参数

pDC
指向图元文件设备上下文的指针。

rc
要在其中进行绘制的矩形区域。

COleControl::EnableSimpleFrame

启用 OLE 控件的简单框架特征。

void EnableSimpleFrame();

备注

此特征允许控件支持其他控件的视觉包含，但不支持真正的 OLE 包含。 例如，一个分组框，其中包含多个控件。 这些控件不是 OLE 包含的，但位于同一分组框中。

COleControl::ExchangeExtent

序列化或初始化控件的盘区（其以 HIMETRIC 单位表示的维度）的状态。

BOOL ExchangeExtent(CPropExchange* pPX);

参数

pPX
指向 CPropExchange 对象的指针。 框架提供了此对象以建立属性交换的上下文，包括其方向。

返回值

如果函数成功，则为非零值；否则为 0。

备注

此函数通常由 COleControl::DoPropExchange 的默认实现调用。

COleControl::ExchangeStockProps

序列化或初始化控件的常用属性的状态。

void ExchangeStockProps(CPropExchange* pPX);

参数

pPX
指向 CPropExchange 对象的指针。 框架提供了此对象以建立属性交换的上下文，包括其方向。

备注

此函数通常由 COleControl::DoPropExchange 的默认实现调用。

COleControl::ExchangeVersion

序列化或初始化控件的版本信息的状态。

BOOL ExchangeVersion(
    CPropExchange* pPX,
    DWORD dwVersionDefault,
    BOOL bConvert = TRUE);

参数

pPX
一个指向 CPropExchange 对象的指针。 框架提供了此对象以建立属性交换的上下文，包括其方向。

dwVersionDefault
控件的当前版本号。

bConvert
指示在保存持久性数据时是应将其转换为最新格式，还是应保持加载时的格式。

返回值

如果函数成功，则为非零值；否则为 0。

备注

通常情况下，这将是由控件的 COleControl::DoPropExchange 替代调用的第一个函数。 加载时，此函数读取持久性数据的版本号，并相应地设置 CPropExchange 对象的版本属性。 保存时，此函数将写入持久性数据的版本号。

有关持久性和版本控制的详细信息，请参阅 ActiveX 控件：序列化一文。

COleControl::FireClick

在活动控件上单击鼠标时由框架调用。

void FireClick();

注解

如果将此事件定义为自定义事件，则由你确定事件何时触发。

若要自动触发某个将发生的 Click 事件，控件的事件映射必须定义常用 Click 事件。

COleControl::FireDblClick

在活动控件上双击鼠标时由框架调用。

void FireDblClick();

备注

如果将此事件定义为自定义事件，则由你确定事件何时触发。

若要自动触发某个将发生的 DblClick 事件，控件的事件映射必须定义常用 DblClick 事件。

COleControl::FireError

触发常用 Error 事件。

void FireError(
    SCODE scode,
    LPCTSTR lpszDescription,
    UINT nHelpID = 0);

参数

scode
要报告的状态代码值。 有关可能代码的完整列表，请参阅 ActiveX 控件：高级主题一文。

lpszDescription
所报告的错误的说明。

nHelpID
所报告的错误的帮助 ID。

注解

此事件提供在代码中的适当位置发出信号的方式，该信号指出控件中发生了错误。 与其他常用事件（如 Click 或 MouseMove）不同，框架永远不会触发 Error。

若要报告在属性 get 函数、属性 set 函数或自动化方法执行期间发生的错误，请调用 COleControl::ThrowError。

OLE 控件的常用 Error 事件的实现使用 SCODE 值。 如果控件使用此事件，而你打算在 Visual Basic 4.0 中使用该控件，则会收到错误，因为 Visual Basic 不支持 SCODE 值。

若要解决此问题，请将控件的 .ODL 文件中的 SCODE 参数手动更改为 long。 此外，任何使用 SCODE 参数的自定义事件、方法或属性也都会导致相同的问题。

COleControl::FireEvent

使用任意数量的可选参数从控件触发用户定义的事件。

void AFX_CDECL FireEvent(
    DISPID dispid,
    BYTE* pbParams,
...);

参数

dispid
要触发的事件的调度 ID。

pbParams
事件的参数类型的描述符。

备注

通常不应直接调用此函数， 而需在控件的类声明的事件映射部分调用事件触发函数。

pbParams参数是 VTS_ 的以空格分隔的列表。 其中一个或多个值（由空格（而不是逗号）分隔）指定函数的参数列表。 可能的值如下所示：

符号	参数类型
VTS_COLOR	OLE_COLOR
VTS_FONT	IFontDisp*
VTS_HANDLE	HWND
VTS_PICTURE	IPictureDisp*
VTS_OPTEXCLUSIVE	OLE_OPTEXCLUSIVE*
VTS_TRISTATE	OLE_TRISTATE
VTS_XPOS_HIMETRIC	OLE_XPOS_HIMETRIC
VTS_YPOS_HIMETRIC	OLE_YPOS_HIMETRIC
VTS_XPOS_PIXELS	OLE_XPOS_PIXELS
VTS_YPOS_PIXELS	OLE_YPOS_PIXELS
VTS_XSIZE_PIXELS	OLE_XSIZE_PIXELS
VTS_YSIZE_PIXELS	OLE_XSIZE_PIXELS
VTS_XSIZE_HIMETRIC	OLE_XSIZE_HIMETRIC
VTS_YSIZE_HIMETRIC	OLE_XSIZE_HIMETRIC

注意

已为所有变体类型定义了其他变体常量，但 VTS_FONT 和 VTS_PICTURE 除外，它们提供了指向变体数据常量的指针。 这些常量使用 VTS_P<CONSTANT-NAME> 约定命名。 例如，VTS_PCOLOR 是指向 VTS_COLOR 常量的指针。

COleControl::FireKeyDown

在按下键时由框架调用，此时控件处于 UI 活动状态。

void FireKeyDown(
    USHORT* pnChar,
    short nShiftState);

参数

pnChar
指向所按下键的虚拟键代码值的指针。 有关标准虚拟键代码的列表，请参阅 Winuser.h

nShiftState
包含以下标志的组合：

• SHIFT_MASK：已在操作期间按下 Shift 键。

• CTRL_MASK：已在操作期间按下 Ctrl 键。

• ALT_MASK：已在操作期间按下 Alt 键。

注解

如果将此事件定义为自定义事件，则由你确定事件何时触发。

若要自动触发某个将发生的 KeyDown 事件，控件的事件映射必须定义常用 KeyDown 事件。

COleControl::FireKeyPress

在按下和松开键时由框架调用，此时自定义控件在容器中处于 UI 活动状态。

void FireKeyPress(USHORT* pnChar);

参数

pnChar
指向所按下键的字符值的指针。

备注

如果将此事件定义为自定义事件，则由你确定事件何时触发。

事件的收件人可以修改 pnChar，例如，将所有小写字符转换为大写。 如果要检查修改的字符，请替代 OnKeyPressEvent。

若要自动触发某个将发生的 KeyPress 事件，控件的事件映射必须定义常用 KeyPress 事件。

COleControl::FireKeyUp

在松开键时由框架调用，此时自定义控件在容器中处于 UI 活动状态。

void FireKeyUp(
    USHORT* pnChar,
    short nShiftState);

参数

pnChar
指向所松开键的虚拟键代码值的指针。 有关标准虚拟键代码的列表，请参阅 Winuser.h

nShiftState
包含以下标志的组合：

• SHIFT_MASK：已在操作期间按下 Shift 键。

• CTRL_MASK：已在操作期间按下 Ctrl 键。

• ALT_MASK：已在操作期间按下 Alt 键。

备注

如果将此事件定义为自定义事件，则由你确定事件何时触发。

若要自动触发某个将发生的 KeyUp 事件，控件的事件映射必须定义常用 KeyUp 事件。

COleControl::FireMouseDown

在活动自定义控件上按下鼠标按钮时由框架调用。

void FireMouseDown(
    short nButton,
    short nShiftState,
    OLE_XPOS_PIXELS x,
    OLE_YPOS_PIXELS y);

参数

nButton
按下的鼠标按钮的数值。 它可能包含下列值之一：

• LEFT_BUTTON：鼠标左按钮已按下。

• MIDDLE_BUTTON：鼠标中按钮已按下。

• RIGHT_BUTTON：鼠标右按钮已按下。

nShiftState
包含以下标志的组合：

• SHIFT_MASK：已在操作期间按下 Shift 键。

• CTRL_MASK：已在操作期间按下 Ctrl 键。

• ALT_MASK：已在操作期间按下 Alt 键。

x
按下鼠标按钮时光标的 x 坐标。 该坐标是相对于控件窗口的左上角的。

y
按下鼠标按钮时光标的 y 坐标。 该坐标是相对于控件窗口的左上角的。

注解

如果将此事件定义为自定义事件，则由你确定事件何时触发。

若要自动触发某个将发生的 MouseDown 事件，控件的事件映射必须定义常用 MouseDown 事件。

COleControl::FireMouseMove

在活动自定义控件上移动光标时由框架调用。

void FireMouseMove(
    short nButton,
    short nShiftState,
    OLE_XPOS_PIXELS x,
    OLE_YPOS_PIXELS y);

参数

nButton
按下的鼠标按钮的数值。 包含以下值的组合：

• LEFT_BUTTON：鼠标左按钮已在操作期间按下。

• MIDDLE_BUTTON：鼠标中按钮已在操作期间按下。

• RIGHT_BUTTON：鼠标右按钮已在操作期间按下。

nShiftState
包含以下标志的组合：

• SHIFT_MASK：已在操作期间按下 Shift 键。

• CTRL_MASK：已在操作期间按下 Ctrl 键。

• ALT_MASK：已在操作期间按下 Alt 键。

x
光标的 x 坐标。 该坐标是相对于控件窗口的左上角的。

y
光标的 y 坐标。 该坐标是相对于控件窗口的左上角的。

备注

如果将此事件定义为自定义事件，则由你确定事件何时触发。

若要自动触发某个将发生的 MouseMove 事件，控件的事件映射必须定义常用 MouseMove 事件。

COleControl::FireMouseUp

在活动自定义控件上松开鼠标按钮时由框架调用。

void FireMouseUp(
    short nButton,
    short nShiftState,
    OLE_XPOS_PIXELS x,
    OLE_YPOS_PIXELS y);

参数

nButton
松开的鼠标按钮的数值。 它可以具有以下值之一：

• LEFT_BUTTON：鼠标左按钮已松开。

• MIDDLE_BUTTON：鼠标中按钮已松开。

• RIGHT_BUTTON：鼠标右按钮已松开。

nShiftState
包含以下标志的组合：

• SHIFT_MASK：已在操作期间按下 Shift 键。

• CTRL_MASK：已在操作期间按下 Ctrl 键。

• ALT_MASK：已在操作期间按下 Alt 键。

x
松开鼠标按钮时光标的 x 坐标。 该坐标是相对于控件窗口的左上角的。

y
松开鼠标按钮时光标的 y 坐标。 该坐标是相对于控件窗口的左上角的。

注解

如果将此事件定义为自定义事件，则由你确定事件何时触发。

若要自动触发某个将发生的 MouseUp 事件，控件的事件映射必须定义常用 MouseUp 事件。

COleControl::FireReadyStateChange

触发一个具有控件就绪状态的当前值的事件。

void FireReadyStateChange();

备注

就绪状态可以是以下值之一：

名称	描述
READYSTATE_UNINITIALIZED	默认初始化状态
READYSTATE_LOADING	控件当前正在加载其属性
READYSTATE_LOADED	控件已初始化
READYSTATE_INTERACTIVE	控件有足够的数据来交互，但尚未加载所有异步数据
READYSTATE_COMPLETE	控件具有其所有数据

使用 GetReadyState 确定控件的当前就绪情况。

InternalSetReadyState 将就绪状态更改为提供的值，然后调用 FireReadyStateChange。

COleControl::GetActivationPolicy

更改支持 IPointerInactive 接口的控件的默认激活行为。

virtual DWORD GetActivationPolicy();

返回值

POINTERINACTIVE 枚举中的标志的组合。 可能的标志包括：

名称	描述
POINTERINACTIVE_ACTIVATEONENTRY	当鼠标在鼠标移动操作期间进入对象时，应该会就地激活该对象。
POINTERINACTIVE_DEACTIVATEONLEAVE	当鼠标在鼠标移动操作期间离开对象时，应该会停用该对象。
POINTERINACTIVE_ACTIVATEONDRAG	当鼠标在拖放操作期间被拖到该对象上时，应该会就地激活该对象。

备注

启用 IPointerInactive 接口后，容器会将 WM_SETCURSOR 和 WM_MOUSEMOVE 消息委托给它。 在相应地调整鼠标坐标后，COleControl 的此接口的实现会通过控件的消息映射调度这些消息。

每当容器在支持 IPointerInactive 的非活动对象上收到带有鼠标指针的 WM_SETCURSOR 或 WM_MOUSEMOVE 消息时，它都应调用接口上的 GetActivationPolicy 并从 POINTERINACTIVE 枚举返回标志。

可以通过将对应的项添加到消息映射来处理这些消息，就像处理普通窗口消息一样。 在处理程序中，应避免在使用 m_hWnd 成员变量（或任何使用它的成员函数）时不首先检查它的值是否不为 NULL。

任何对象，如果其用途不仅仅是设置鼠标光标和/或触发鼠标移动事件（如提供特殊视觉反馈），则都应返回 POINTERINACTIVE_ACTIVATEONENTRY 标志，仅在活动时绘制反馈。 如果对象返回此标志，容器应立即就地激活它，然后为它转发一条触发了对 GetActivationPolicy 的调用的消息。

如果返回 POINTERINACTIVE_ACTIVATEONENTRY 和 POINTERINACTIVE_DEACTIVATEONLEAVE 标志，则仅当鼠标悬停在对象上时，才会激活该对象。 如果只返回 POINTERINACTIVE_ACTIVATEONENTRY 标志，则仅当鼠标首次进入对象时，才会激活该对象一次。

你可能还希望非活动控件是 OLE 拖放操作的目标。 这需要在用户将对象拖动到控件上方时激活控件，以便可以将控件的窗口注册为放置目标。 若要在拖动过程中引发激活，请返回 POINTERINACTIVE_ACTIVATEONDRAG 标志：

DWORD CMyAxCtrl::GetActivationPolicy()
{
   return POINTERINACTIVE_ACTIVATEONDRAG;
}

不应由容器缓存 GetActivationPolicy 所传达的信息， 而应在每次鼠标进入非活动对象时调用此方法。

如果非活动对象没有在鼠标进入时请求就地激活，则只要鼠标指针停留在此对象上，其容器就应通过调用 OnInactiveSetCursor 将后续 WM_SETCURSOR 消息调度到此对象。

启用 IPointerInactive 接口通常意味着你希望控件能够随时处理鼠标消息。 若要在不支持 IPointerInactive 接口的容器中获取此行为，需要在控件可见时始终激活控件，这意味着控件应在其杂项标志中包含 OLEMISC_ACTIVATEWHENVISIBLE 标志。 但是，若要防止此标志在支持 IPointerInactive 的容器中生效，还可以指定 OLEMISC_IGNOREACTIVATEWHENVISIBLE 标志：

static const DWORD BASED_CODE _dwMyOleMisc =
    OLEMISC_ACTIVATEWHENVISIBLE |
    OLEMISC_IGNOREACTIVATEWHENVISIBLE |
    OLEMISC_SETCLIENTSITEFIRST |
    OLEMISC_INSIDEOUT |
    OLEMISC_CANTLINKINSIDE |
    OLEMISC_RECOMPOSEONRESIZE;

COleControl::GetAmbientProperty

获取容器的环境属性的值。

BOOL GetAmbientProperty(
    DISPID dispid,
    VARTYPE vtProp,
    void* pvProp);

参数

dwDispid
所需环境属性的调度 ID。

vtProp
一个变体类型标志，指定要在 pvProp 中返回的值的类型。

pvProp
一个指针，指向将接收属性值或返回值的变量的地址。 此指针的实际类型必须与 vtProp 指定的类型匹配。

vtProp	pvProp 的类型
VT_BOOL	BOOL*
VT_BSTR	CString*
VT_I2	short*
VT_I4	long*
VT_R4	float*
VT_R8	double*
VT_CY	CY*
VT_COLOR	OLE_COLOR*
VT_DISPATCH	LPDISPATCH*
VT_FONT	LPFONTDISP*

返回值

如果支持环境属性，则为非零值；否则为 0。

注解

如果使用 GetAmbientProperty 检索环境 DisplayName 属性和 ScaleUnits 属性，请将 vtProp 设置为 VT_BSTR，并将 pvProp 设置为 CString*。 如果要检索环境 Font 属性，请将 vtProp 设置为 VT_FONT，将 pvProp 设置为 LPFONTDISP*。

请注意，已为通用环境属性（如 AmbientBackColor 和 AmbientFont）提供函数。

COleControl::GetAppearance

实现控件的常用 Appearance 属性的 Get 函数。

short GetAppearance ();

返回值

如果成功，返回值会将当前外观设置指定为 short (VT_I2) 值。 如果控件的外观为平面，则此值为零；如果控件的外观为 3D，则此值为 1。

COleControl::GetBackColor

实现控件的常用 BackColor 属性的 Get 函数。

OLE_COLOR GetBackColor();

返回值

如果成功，返回值会将当前背景色指定为 OLE_COLOR 值。 此值可以转换为一个可以调用 TranslateColor 的 COLORREF 值。

COleControl::GetBorderStyle

实现控件的常用 BorderStyle 属性的 Get 函数。

short GetBorderStyle();

返回值

如果控件有普通边框，则为 1；如果控件没有边框，则为 0。

COleControl::GetCapture

确定 COleControl 对象是否具有鼠标捕获。

CWnd* GetCapture();

返回值

如果控件已激活且无窗口，则返回 this 的前提是控件当前有鼠标捕获（取决于控件的容器）；返回 NULL 的前提是没有捕获。

其他情况会返回有鼠标捕获的 CWnd 对象（与 CWnd::GetCapture 相同）。

注解

调用 SetCapture 时，激活的无窗口控件接收鼠标捕获。

COleControl::GetClassID

由框架调用，可检索控件的 OLE 类 ID。

virtual HRESULT GetClassID(LPCLSID pclsid) = 0;

参数

pclsid
指向类 ID 的位置的指针。

返回值

如果调用未成功，则为非零值；否则为 0。

注解

通常由 IMPLEMENT_OLECREATE_EX 实现。

COleControl::GetClientOffset

检索控件矩形区域的左上角与其工作区左上角之间的差异。

virtual void GetClientOffset(long* pdxOffset, long* pdyOffset) const;

参数

pdxOffset
指向 OLE 控件工作区的水平偏移量的指针。

pdyOffset
指向 OLE 控件工作区的垂直偏移量的指针。

备注

OLE 控件在其容器中有矩形区域。 控件的工作区是控制区，不包括边框和滚动条。 通过 GetClientOffset 检索的偏移量是控件矩形区域的左上角与其工作区左上角之间的差异。 如果控件具有标准边框和滚动条以外的非客户端元素，请替代此成员函数以指定偏移量。

COleControl::GetClientRect

检索控件的工作区的大小。

virtual void GetClientRect(LPRECT lpRect) const;

参数

lpRect
指向 RECT 结构的指针，其中包含无窗口控件工作区的维度；也就是控件的大小减去窗口边框、框架、滚动条等。 lpRect 参数指示控件的客户端矩形的大小，而不指示其位置。

COleControl::GetClientSite

查询指向其容器中的当前客户端站点的指针的对象。

LPOLECLIENTSITE GetClientSite();

返回值

指向控件的当前客户端站点（在其容器中）的指针。

备注

返回的指针指向 IOleClientSite 的实例。 由容器实现的 IOleClientSite 接口是对象的上下文的视图：它定位在文档中的何处；它在何处获取其存储、用户界面和其他资源。

COleControl::GetControlFlags

检索控件标志设置。

virtual DWORD GetControlFlags();

返回值

ControlFlags 枚举中的标志的 ORed 组合：

enum ControlFlags {
    fastBeginPaint = 0x0001,
    clipPaintDC = 0x0002,
    pointerInactive = 0x0004,
    noFlickerActivate = 0x0008,
    windowlessActivate = 0x0010,
    canOptimizeDraw = 0x0020,
    };

备注

默认情况下，GetControlFlags 返回 fastBeginPaint | clipPaintDC。

名称	描述
fastBeginPaint	如果设置，请使用为 OLE 控件定制的 begin-paint 函数，而不使用 BeginPaint API（默认设置）。
clipPaintDC	如果未设置，则禁用由 COleControl 对 IntersectClipRect 进行的调用，获得较小的速度优势。 如果使用无窗口激活，则此标志不起作用。
pointerInactive	如果设置，则在控件处于非活动状态时提供鼠标交互，方法是启用 COleControl 的 IPointerInactive 接口实现（默认禁用）。
noFlickerActivate	如果设置，则消除额外的绘制操作和随附的视觉闪烁。 当控件在非活动状态和活动状态都以相同的方式绘制自身时使用。 如果使用无窗口激活，则此标志不起作用。
windowlessActivate	如果设置，则表明控件使用无窗口激活。
canOptimizeDraw	如果设置，则表明控件将执行优化的绘制（如果容器支持它）。

有关 GetControlFlags 和其他 OLE 控件优化的详细信息，请参阅 ActiveX 控件：优化。

COleControl::GetControlSize

检索 OLE 控件窗口的大小。

void GetControlSize(
    int* pcx,
    int* pcy);

参数

pcx
指定控件的宽度（以像素为单位）。

pcy
指定控件的高度（以像素为单位）。

备注

请注意，控件窗口的所有坐标都是相对于控件的左上角的。

COleControl::GetDC

为无窗口对象提供，目的是从其容器获取屏幕的（或兼容的）设备上下文。

CDC* GetDC(
    LPCRECT lprcRect = NULL,
    DWORD dwFlags = OLEDC_PAINTBKGND);

参数

lprcRect
一个指向无窗口控件希望以控件客户端坐标重绘的矩形的指针。 NULL 表示整个对象的盘区。

dwFlags
绘制设备上下文的属性。 选项有：

• OLEDC_NODRAW 指示对象不会使用设备上下文来执行任何绘制操作，而只是为了获取有关显示设备的信息。 容器应仅传递窗口的 DC，而不进行进一步处理。

• OLEDC_PAINTBKGND 请求容器在返回 DC 之前绘制背景。 如果某个对象请求 DC 来重新绘制具有透明背景的区域，则该对象应使用此标志。

• OLEDC_OFFSCREEN 通知容器，对象希望呈现为一个屏幕外位图，该位图随后应复制到屏幕。 当某个对象要执行的绘制操作产生大量闪烁时，该对象应使用此标志。 容器可以自由决定是否执行此请求。 但是，如果未设置此标志，容器必须返回屏幕 DC。 这样，对象就可以执行直接的屏幕操作，例如显示所选内容（通过异或运算）。

返回值

如果成功，则返回值为一个指向容器 CWnd 工作区显示设备上下文的指针；否则，返回值为 NULL。 显示设备上下文可用于后续 GDI 函数，以在容器窗口的工作区中进行绘制。

备注

必须调用 ReleaseDC 成员函数才能在绘制后释放上下文。 调用 GetDC 时，对象会传递矩形，该矩形是对象希望在其自己的客户端坐标中绘制的。 GetDC 将它们转换为容器工作区的坐标。 该对象不应请求大于其自己的工作区矩形的所需绘制矩形，其大小可以使用 GetClientRect 进行检索。 这可以防止对象在不应绘制的位置无意中进行绘制。

COleControl::GetEnabled

实现控件的常用 Enabled 属性的 Get 函数。

BOOL GetEnabled();

返回值

如果已启用控件，则返回非零值；否则返回 0。

COleControl::GetExtendedControl

获取一个指向对象的指针，该对象由容器维护，代表具有一组扩展属性的控件。

LPDISPATCH GetExtendedControl();

返回值

一个指向容器的扩展控件对象的指针。 如果没有可用的对象，则值为 NULL。

可以通过此对象的 IDispatch 接口对其进行操作。 还可以使用 QueryInterface 来获取对象提供的其他可用接口。 但是，该对象不需支持特定的接口集。 请注意，如果依赖于容器的扩展控件对象的特定功能，则控件的可移植性会局限于其他任意容器。

备注

调用此函数的函数负责在用完对象后释放指针。 请注意，容器不需要支持此对象。

COleControl::GetFocus

确定 COleControl 对象是否有焦点。

CWnd* GetFocus();

返回值

如果控件已激活且无窗口，则返回 this 的前提是控件当前有键盘焦点（取决于控件的容器）；返回 NULL 的前提是没有焦点。

其他情况会返回有焦点的 CWnd 对象（与 CWnd::GetFocus 相同）。

备注

调用 SetFocus 时，激活的无窗口控件接收焦点。

COleControl::GetFont

实现常用 Font 属性的 Get 函数。

LPFONTDISP GetFont();

返回值

一个指向控件常用 Font 属性的字体调度接口的指针。

备注

请注意，调用方必须在完成后释放对象。 在控件的实现中，请使用 InternalGetFont 来访问控件的常用 Font 对象。 若要详细了解如何在控件中使用字体，请参阅 ActiveX 控件：在 ActiveX 控件中使用字体一文。

COleControl::GetFontTextMetrics

度量控件拥有的任何 CFontHolder 对象的文本指标。

void GetFontTextMetrics(
    LPTEXTMETRIC lptm,
    CFontHolder& fontHolder);

参数

lptm
指向 TEXTMETRIC 结构的指针。

fontHolder
对 CFontHolder 对象的引用。

注解

可以使用 COleControl::SelectFontObject 函数选择此类字体。 如果成功，GetFontTextMetrics 将使用有关 fontHolder 的字体的有效指标信息来初始化 lptm 所指向的 TEXTMETRIC 结构；如果不成功，则使用零来填充该结构。 在绘制控件时，应使用此函数而不是 GetTextMetrics，因为控件（如任何嵌入的 OLE 对象）可能需要将自己呈现为图元文件。

调用 SelectFontObject 函数时，将刷新默认字体的 TEXTMETRIC 结构。 只有在选择常用 Font 属性以确保它提供的信息有效后，才应调用 GetFontTextMetrics。

COleControl::GetForeColor

实现常用 ForeColor 属性的 Get 函数。

OLE_COLOR GetForeColor();

返回值

如果成功，返回值会将当前前景色指定为 OLE_COLOR 值。 此值可以转换为一个可以调用 TranslateColor 的 COLORREF 值。

COleControl::GetHwnd

实现常用 hWnd 属性的 Get 函数。

OLE_HANDLE GetHwnd();

返回值

OLE 控件的窗口句柄（如果有）；否则为 NULL。

COleControl::GetMessageString

由框架调用，以获取一个描述 nID 所标识的菜单项用途的短字符串。

virtual void GetMessageString(
    UINT nID,
    CString& rMessage) const;

参数

nID
菜单项 ID。

rMessage
对 CString 对象的引用，将通过该对象返回一个字符串。

注解

这可用于在突出显示菜单项时获取在状态栏中显示的消息。 默认实现尝试加载 nID 所标识的字符串资源。

COleControl::GetNotSupported

防止用户访问控件的属性值。

void GetNotSupported();

备注

请在不支持由控件的用户检索属性的情况下，调用此函数来代替任何属性的 Get 函数。 例如，只写属性。

COleControl::GetReadyState

返回控件的就绪状态。

long GetReadyState();

返回值

控件的就绪状态，以下值之一：

名称	描述
READYSTATE_UNINITIALIZED	默认初始化状态
READYSTATE_LOADING	控件当前正在加载其属性
READYSTATE_LOADED	控件已初始化
READYSTATE_INTERACTIVE	控件有足够的数据来交互，但尚未加载所有异步数据
READYSTATE_COMPLETE	控件具有其所有数据

备注

大多数简单的控件从不需要区分 LOADED 和 INTERACTIVE。 但是，至少在异步接收某些数据之前，支持数据路径属性的控件可能尚无法成为交互式控件。 应尝试尽快让控件成为交互式控件。

COleControl::GetRectInContainer

获取控件矩形相对于容器的坐标，以设备单位表示。

BOOL GetRectInContainer(LPRECT lpRect);

参数

lpRect
一个指向矩形结构的指针，控件的坐标将会复制到该结构中。

返回值

如果控件处于就地活动状态，则为非零值；否则为 0。

注解

仅当控件处于就地活动状态时，该矩形才有效。

COleControl::GetStockTextMetrics

度量控件的常用 Font 属性的文本指标，该属性可以使用 SelectStockFont 函数进行选择。

void GetStockTextMetrics(LPTEXTMETRIC lptm);

参数

lptm
一个指向 TEXTMETRIC 结构的指针。

备注

如果成功，GetStockTextMetrics 函数将使用有效指标信息来初始化 lptm 所指向的 TEXTMETRIC 结构；如果不成功，则使用零来填充该结构。 在绘制控件时，请使用此函数而不是 GetTextMetrics，因为控件（如任何嵌入的 OLE 对象）可能需要将自己呈现为图元文件。

调用 SelectStockFont 函数时，将刷新默认字体的 TEXTMETRIC 结构。 只有在选择常用字体以确保它提供的信息有效后，才应调用此函数。

COleControl::GetText

实现常用 Text 或 Caption 属性的 Get 函数。

BSTR GetText();

返回值

控件文本字符串的当前值；如果不存在字符串，则为长度为零的字符串。

注意

有关 BSTR 数据类型的详细信息，请参阅“宏和全局函数”部分中的数据类型。

注解

请注意，此函数的调用方必须对返回的字符串调用 SysFreeString 才能释放资源。 在控件的实现中，请使用 InternalGetText 来访问控件的常用 Text 或 Caption 属性。

COleControl::GetWindowlessDropTarget

在希望无窗口控件是 OLE 拖放操作的目标时替代 GetWindowlessDropTarget。

virtual IDropTarget* GetWindowlessDropTarget();

返回值

指向对象的 IDropTarget 接口的指针。 由于没有窗口，无窗口对象无法注册 IDropTarget 接口。 但是，若要参与拖放，无窗口对象仍可以实现该接口并在 GetWindowlessDropTarget 中将其返回。

注解

通常，这需要将该控件的窗口注册为放置目标。 但是，由于该控件没有自己的窗口，容器将使用自己的窗口作为放置目标。 该控件只需提供 IDropTarget 接口的实现，容器可在适当时向其委托调用。 例如：

IDropTarget *CMyAxCtrl::GetWindowlessDropTarget()
{
   m_xDropTarget.AddRef();
   return &m_xDropTarget;
}

COleControl::InitializeIIDs

向基类通知控件将使用的 IID。

void InitializeIIDs(
    const IID* piidPrimary,
    const IID* piidEvents);

参数

piidPrimary
指向控件的主调度接口的接口 ID 的指针。

piidEvents
指向控件事件接口的接口 ID 的指针。

备注

在控件的构造函数中调用此函数，以将控件要使用的接口 ID 告知基类。

COleControl::InternalGetFont

访问控件的常用 Font 属性

CFontHolder& InternalGetFont();

返回值

对包含常用 Font 对象的 CFontHolder 对象的引用。

COleControl::InternalGetText

访问控件的常用 Text 或 Caption 属性。

const CString& InternalGetText();

返回值

对控件文本字符串的引用。

COleControl::InternalSetReadyState

设置控件的就绪状态。

void InternalSetReadyState(long lNewReadyState);

参数

lNewReadyState
要为控件设置的就绪状态，以下值之一：

名称	描述
READYSTATE_UNINITIALIZED	默认初始化状态
READYSTATE_LOADING	控件当前正在加载其属性
READYSTATE_LOADED	控件已初始化
READYSTATE_INTERACTIVE	控件有足够的数据来交互，但尚未加载所有异步数据
READYSTATE_COMPLETE	控件具有其所有数据

备注

大多数简单的控件从不需要区分 LOADED 和 INTERACTIVE。 但是，至少在异步接收某些数据之前，支持数据路径属性的控件可能尚无法成为交互式控件。 应尝试尽快让控件成为交互式控件。

COleControl::InvalidateControl

强制控件重绘自身。

void InvalidateControl(
    LPCRECT lpRect = NULL,
    BOOL bErase = TRUE);

参数

lpRect
一个指针，指向要失效的控件的区域。

bErase
指定在处理更新区域时是否要擦除更新区域中的背景。

注解

如果 lpRect 具有 NULL 值，则将重绘整个控件。 如果 lpRect 不为 NULL，则表示控件矩形的要失效的部分。 如果控件没有窗口或当前未处于活动状态，则忽略矩形，并对客户端站点的 IAdviseSink::OnViewChange 成员函数进行调用。 请使用此函数，而不要使用 CWnd::InvalidateRect 或 InvalidateRect。

COleControl::InvalidateRgn

使容器窗口的工作区在给定区域中失效。

void InvalidateRgn(CRgn* pRgn, BOOL bErase = TRUE);

参数

pRgn
一个指向 CRgn 对象的指针，该对象标识要失效的 OLE 对象的显示区域（以包含窗口的客户端坐标表示）。 如果此参数为 NULL，则盘区是整个对象。

bErase
指定是否要擦除已失效区域中的背景。 如果为 TRUE，则清除背景。 如果为 FALSE，则背景保持不变。

备注

这可用于重绘容器中的无窗口控件。 在发送下一条 WM_PAINT 消息时，会将失效区域以及更新区域中的所有其他区域标记为进行绘制。

对于更新区域的任何部分，如果 bErase 为 TRUE，则会清除整个区域（而不仅仅是给定部分）中的背景。

COleControl::IsConvertingVBX

允许对 OLE 控件进行专用加载。

BOOL IsConvertingVBX();

返回值

如果正在转换控件，则为非零值；否则为 0。

备注

将使用 VBX 控件的窗体转换为使用 OLE 控件的窗体时，可能需要对 OLE 控件使用特殊加载代码。 例如，如果要加载 OLE 控件的实例，则可以在 DoPropExchange 中调用 PX_Font：

PX_Font(pPX, _T("Font"), *m_pMyFont, &DefaultFont);

但是，VBX 控件没有 Font 对象；每个字体属性是单独保存的。 在这种情况下，你将使用 IsConvertingVBX 来区分这两种情况：

if (!IsConvertingVBX())
{
   PX_Font(pPX, _T("Font"), *m_pMyFont, &DefaultFont);
}
else
{
   PX_String(pPX, _T("FontName"), tempString, DefaultName);
   m_pMyFont->m_pFont->put_Name(tempString.AllocSysString());
   PX_Bool(pPX, _T("FontUnderline"), tempBool, DefaultValue);
   m_pMyFont->m_pFont->put_Underline(tempBool);
}

另一种情况是，VBX 控件（在其 VBM_SAVEPROPERTY 消息处理程序中）保存了专有二进制数据，而 OLE 控件则以另一种格式保存其二进制数据。 如果希望 OLE 控件与 VBX 控件后向兼容，可以使用 IsConvertingVBX 函数通过区分加载的是 VBX 控件还是 OLE 控件来同时读取旧格式和新格式。

在控件的 DoPropExchange 函数中，可以检查此条件，如果为 true，则执行特定于此转换的加载代码（例如前面的示例）。 如果未转换控件，可以执行正常的加载代码。 此功能仅适用于从 VBX 对应项转换的控件。

COleControl::IsInvokeAllowed

启用自动化方法调用。

BOOL IsInvokeAllowed(DISPID dispid);

返回值

如果已初始化控件，则为非零值；否则为 0。

注解

框架的 IDispatch::Invoke 实现会调用 IsInvokeAllowed，以确定是否可以调用给定函数（由 dispid 标识）。 OLE 控件的默认行为是，仅当控件已初始化时，才允许调用自动化方法；但是，IsInvokeAllowed 是虚拟函数，必要时可能需要将其替代（例如，将控件用作自动化服务器时）。

COleControl::IsModified

确定控件的状态是否已修改。

BOOL IsModified();

返回值

如果控件的状态自上次保存后进行过修改，则为非零值；否则为 0。

备注

当属性更改值时，将修改控件的状态。

COleControl::IsOptimizedDraw

确定容器是否支持针对当前绘制操作的优化绘制。

BOOL IsOptimizedDraw();

返回值

如果容器支持针对当前绘制操作的优化绘制，则为 TRUE；否则为 FALSE。

备注

如果支持优化的绘制，则控件无需在绘制完成后将旧对象（笔、画笔、字体等）选择到到设备上下文中。

COleControl::IsSubclassedControl

由框架调用后可确定此控件是否为 Windows 控件的子类。

virtual BOOL IsSubclassedControl();

返回值

如果控件已子类化，则为非零值；否则为 0。

注解

如果 OLE 控件子类是 Windows 控件，则必须替代此函数并返回 TRUE。

COleControl::Load

重置任何先前的异步加载数据，并启动对控件异步属性的新加载。

void Load(LPCTSTR strNewPath, CDataPathProperty& prop);

参数

strNewPath
一个指向字符串的指针，该字符串包含引用异步控件属性绝对位置的路径。

prop
一个实现异步控件属性的 CDataPathProperty 对象。

COleControl::LockInPlaceActive

阻止容器停用控件。

BOOL LockInPlaceActive(BOOL bLock);

参数

bLock
如果要锁定控件的就地活动状态，则为 TRUE；如果要解锁它，则为 FALSE。

返回值

如果成功锁定，则为非零值；否则为 0。

注解

请注意，对控件的每个锁定都必须与完成后对控件的解锁配对。 应仅短时间锁定控件，例如在触发事件时这样做。

COleControl::OnAmbientPropertyChange

当容器的环境属性更改值时由框架调用。

virtual void OnAmbientPropertyChange(DISPID dispid);

参数

dispID
已更改的环境属性的调度 ID，或者 DISPID_UNKNOWN（如果多个属性已更改）。

COleControl::OnAppearanceChanged

当常用 Appearance 属性值已更改时由框架调用。

virtual void OnAppearanceChanged ();

备注

如果你想要此属性更改后的通知，请替代此函数。 默认实现调用 InvalidateControl。

COleControl::OnBackColorChanged

当常用 BackColor 属性值已更改时由框架调用。

virtual void OnBackColorChanged();

注解

如果你想要此属性更改后的通知，请替代此函数。 默认实现调用 InvalidateControl。

COleControl::OnBorderStyleChanged

当常用 BorderStyle 属性值已更改时由框架调用。

virtual void OnBorderStyleChanged();

注解

默认实现调用 InvalidateControl。

如果你想要此属性更改后的通知，请替代此函数。

COleControl::OnClick

在单击鼠标按钮或调用 DoClick 常用方法时由框架调用。

virtual void OnClick(USHORT iButton);

参数

iButton
鼠标按钮的索引。 可以是下列值之一：

• LEFT_BUTTON：已单击鼠标左按钮。

• MIDDLE_BUTTON：已单击鼠标中按钮。

• RIGHT_BUTTON：已单击鼠标右按钮。

备注

默认实现调用 COleControl::FireClick。

替代此成员函数以修改或扩展默认处理。

COleControl::OnClose

在容器已调用控件的 IOleControl::Close 函数时由框架调用。

virtual void OnClose(DWORD dwSaveOption);

参数

dwSaveOption
指示是否应在加载之前保存对象的标志。 有效值为：

• OLECLOSE_SAVEIFDIRTY

• OLECLOSE_NOSAVE

• OLECLOSE_PROMPTSAVE

备注

默认情况下，如果控件对象已被修改且 dwSaveOption 为 OLECLOSE_SAVEIFDIRTY 或 OLECLOSE_PROMPTSAVE，则 OnClose 会保存控件对象。

COleControl::OnDoVerb

在容器调用 IOleObject::DoVerb 成员函数时由框架调用。

virtual BOOL OnDoVerb(
    LONG iVerb,
    LPMSG lpMsg,
    HWND hWndParent,
    LPCRECT lpRect);

参数

iVerb
要调用的控件谓词的索引。

lpMsg
一个指向 Windows 消息的指针，该消息导致谓词被调用。

hWndParent
控件的父窗口的句柄。 如果执行谓词时创建了窗口，则应将 hWndParent 用作父级。

lpRect
一个指向 RECT 结构的指针，相对于容器的控件的坐标会复制到该结构中。

返回值

如果调用成功，则为非零值；否则为 0。

备注

默认实现使用 ON_OLEVERB 和 ON_STDOLEVERB 消息映射条目来确定要调用的正确函数。

替代此函数以更改默认谓词处理。

COleControl::OnDraw

由框架调用，以使用指定的设备上下文在指定的边框中绘制 OLE 控件。

virtual void OnDraw(
    CDC* pDC,
    const CRect& rcBounds,
    const CRect& rcInvalid);

参数

pDC
在其中进行绘制的设备上下文。

rcBounds
控件的矩形区域，包括边框。

rcInvalid
控件的无效矩形区域。

备注

OnDraw 通常为屏幕显示调用，将屏幕设备上下文作为 pDC 传递。 rcBounds 参数标识目标设备上下文中的矩形（相对于其当前映射模式）。 rcInvalid 参数是无效的实际矩形。 在某些情况下，这将是一个比 rcBounds 小的区域。

COleControl::OnDrawMetafile

由框架调用，以使用指定的图元文件设备上下文在指定的边框中绘制 OLE 控件。

virtual void OnDrawMetafile(
    CDC* pDC,
    const CRect& rcBounds);

参数

pDC
在其中进行绘制的设备上下文。

rcBounds
控件的矩形区域，包括边框。

备注

默认实现调用 OnDraw 函数。

COleControl::OnEdit

导致对控件进行 UI 激活。

virtual BOOL OnEdit(
    LPMSG lpMsg,
    HWND hWndParent,
    LPCRECT lpRect);

参数

lpMsg
一个指向已调用谓词的 Windows 消息的指针。

hWndParent
控件的父窗口的句柄。

lpRect
一个指向容器中控件使用的矩形的指针。

返回值

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

备注

这与调用控件的 OLEIVERB_UIACTIVATE 谓词的效果相同。

此函数通常用作 ON_OLEVERB 消息映射条目的处理程序函数。 这使得“编辑”谓词在控件的“对象”菜单上可用。 例如：

ON_OLEVERB(AFX_IDS_VERB_EDIT, OnEdit)

COleControl::OnEnabledChanged

当常用 Enabled 属性值已更改时由框架调用。

virtual void OnEnabledChanged();

备注

如果你想要此属性更改后的通知，请替代此函数。 默认实现调用 InvalidateControl。

COleControl::OnEnumVerbs

在容器调用 IOleObject::EnumVerbs 成员函数时由框架调用。

virtual BOOL OnEnumVerbs(LPENUMOLEVERB* ppenumOleVerb);

参数

ppenumOleVerb
一个指向枚举控件谓词的 IEnumOLEVERB 对象的指针。

返回值

如果谓词可用，则为非零值；否则为 0。

备注

默认实现会枚举消息映射中的 ON_OLEVERB 条目。

替代此函数以更改枚举谓词的默认方式。

COleControl::OnEventAdvise

当事件处理程序连接到 OLE 控件或断开与它的连接时，由框架调用。

virtual void OnEventAdvise(BOOL bAdvise);

参数

bAdvise
TRUE 表示事件处理程序已连接到控件。 FALSE 表示事件处理程序已与控件断开连接。

COleControl::OnFontChanged

当常用 Font 属性值已更改时由框架调用。

virtual void OnFontChanged();

注解

默认实现调用 COleControl::InvalidateControl。 如果控件对 Windows 控件进行子类化，则默认实现还会向控件的窗口发送 WM_SETFONT 消息。

如果你想要此属性更改后的通知，请替代此函数。

示例

void CMyAxCtrl::OnFontChanged()
{
   // Always set it to the container's font
   if (m_MyEdit.m_hWnd != NULL)
   {
      IFontDisp *pFontDisp = NULL;
      IFont *pFont = NULL;
      HRESULT hr;

      // Get the container's FontDisp interface
      pFontDisp = AmbientFont();
      if (pFontDisp)
      {
         hr = pFontDisp->QueryInterface(IID_IFont, (LPVOID*)&pFont);
         if (FAILED(hr))
         {
            pFontDisp->Release();
            return;
         }
      }

      HFONT hFont = NULL;
      if (pFont)
      {
         pFont->get_hFont(&hFont);
         m_MyEdit.SendMessage(WM_SETFONT, (WPARAM)hFont, 0L);
      }

      pFontDisp->Release();
   }

   // Invalidate the control
   m_MyEdit.Invalidate();
   m_MyEdit.UpdateWindow();

   COleControl::OnFontChanged();
}

COleControl::OnForeColorChanged

当常用 ForeColor 属性值已更改时由框架调用。

virtual void OnForeColorChanged();

备注

默认实现调用 InvalidateControl。

如果你想要此属性更改后的通知，请替代此函数。

COleControl::OnFreezeEvents

在容器调用 IOleControl::FreezeEvents 后由框架调用。

virtual void OnFreezeEvents(BOOL bFreeze);

参数

bFreeze
如果控件的事件处理已冻结，则为 TRUE；否则为 FALSE。

备注

默认实现不执行任何操作。

如果希望在事件处理冻结或取消冻结时出现其他行为，请替代此函数。

COleControl::OnGetColorSet

在容器调用 IViewObject::GetColorSet 成员函数时由框架调用。

virtual BOOL OnGetColorSet(
    DVTARGETDEVICE* ptd,
    HDC hicTargetDev,
    LPLOGPALETTE* ppColorSet);

参数

ptd
指向应为其呈现图片的目标设备。 如果此值为 NULL，则应为默认目标设备（通常是显示设备）呈现图片。

hicTargetDev
指定 ptd 所指示的目标设备上的信息上下文。 此参数可以是设备上下文，但不一定是设备上下文。 如果 ptd 为 NULL，则 hicTargetDev 也应为 NULL。

ppColorSet
一个指向位置的指针，应将要使用的颜色集复制到该位置。 如果函数未返回颜色集，则返回 NULL。

返回值

如果返回有效的颜色集，则为非零值；否则为 0。

备注

容器调用此函数以获取绘制 OLE 控件所需的所有颜色。 容器可以将获取的颜色集与设置整体调色板所需的颜色结合使用。 默认实现返回 FALSE。

替代此函数以执行对此请求的任何特殊处理。

COleControl::OnGetControlInfo

当控件的容器请求有关控件的信息时，由框架调用。

virtual void OnGetControlInfo(LPCONTROLINFO pControlInfo);

参数

pControlInfo
指向要填充的 CONTROLINFO 结构的指针。

注解

此信息主要包括控件的助记键的说明。 默认实现使用默认信息填充 pControlInfo。

如果控件需要处理助记键，请替代此函数。

COleControl::OnGetDisplayString

由框架调用以获取一个字符串，该字符串表示 由 dispid 标识的属性的当前值。

virtual BOOL OnGetDisplayString(
    DISPID dispid,
    CString& strValue);

参数

dispid
该控件的属性的调度 ID。

strValue
对 CString 对象的引用，将通过该对象返回一个字符串。

返回值

如果已在 strValue 中返回字符串，则为非零值；否则为 0。

备注

如果控件具有其值无法直接转换为字符串的属性，并且你希望该属性的值显示在容器提供的属性浏览器中，则替代此函数。

COleControl::OnGetInPlaceMenu

对控件进行 UI 激活以获取要合并到容器的现有菜单中的菜单时，由框架调用。

virtual HMENU OnGetInPlaceMenu();

返回值

控件的菜单的句柄；如果控件什么也没有，则为 NULL。 默认实现返回 NULL。

备注

若要详细了解如何合并 OLE 资源，请参阅菜单和资源 (OLE) 一文。

COleControl::OnGetNaturalExtent

由框架调用以响应容器的 IViewObjectEx::GetNaturalExtent 请求。

virtual BOOL OnGetNaturalExtent(
    DWORD dwAspect,
    LONG lindex,
    DVTARGETDEVICE* ptd,
    HDC hicTargetDev,
    DVEXTENTINFO* pExtentInfo,
    LPSIZEL psizel);

参数

dwAspect
指定要如何表示该对象。 表示形式包括内容、图标、缩略图或打印的文档。 有效值取自枚举 DVASPECT 或 DVASPECT2。

lindex
有关的对象部分。 目前仅 -1 有效。

ptd
指向的 DVTARGETDEVICE 结构定义应当为其返回该对象的大小的目标设备。

hicTargetDev
指定 ptd 参数指示的目标设备的信息上下文，对象可从该参数提取设备指标并测试设备的功能。 如果 ptd 为 NULL，则对象应忽略 hicTargetDev 参数中的值。

pExtentInfo
指向的 DVEXTENTINFO 结构指定大小调整数据。 DVEXTENTINFO 结构为：

typedef struct tagExtentInfo
{
    UINT cb;
    DWORD dwExtentMode;
    SIZEL sizelProposed;
}   DVEXTENTINFO;

结构成员 dwExtentMode 可以采用以下两个值之一：

• DVEXTENT_CONTENT：询问控件应多大才能与内容完全拟合（对齐大小）

• DVEXTENT_INTEGRAL：重设大小时，向控件传递建议的大小

psizel
指向控件返回的大小调整数据。 对于未调整的任何维度，将返回的大小调整数据设置为 -1。

返回值

如果成功返回或调整大小，则为非零值；否则为 0。

注解

替代此函数以返回对象的与 DVEXTENTINFO 结构中建议的大小和盘区模式最接近的显示大小。 默认实现返回 FALSE，不调整大小。

COleControl::OnGetPredefinedStrings

由框架调用，以获取一组表示属性的可能值的预定义字符串。

virtual BOOL OnGetPredefinedStrings(
    DISPID dispid,
    CStringArray* pStringArray,
    CDWordArray* pCookieArray);

参数

dispid
该控件的属性的调度 ID。

pStringArray
要用返回值填充的字符串数组。

pCookieArray
要用返回值填充的 DWORD 数组。

返回值

如果已将元素添加到 pStringArray 和 pCookieArray，则为非零值。

备注

如果控件的属性具有一组可由字符串表示的可能值，则替代此函数。 对于添加到 pStringArray 的每个元素，应向 pCookieArray 添加相应的“cookie”元素。这些“cookie”值以后可能会由框架传递到 COleControl::OnGetPredefinedValue 函数。

COleControl::OnGetPredefinedValue

由框架调用，以获取与之前由 COleControl::OnGetPredefinedStrings 的替代返回的预定义字符串之一对应的值。

virtual BOOL OnGetPredefinedValue(
    DISPID dispid,
    DWORD dwCookie,
    VARIANT* lpvarOut);

参数

dispid
该控件的属性的调度 ID。

dwCookie
以前由 COleControl::OnGetPredefinedStrings 的替代返回的 Cookie 值。

lpvarOut
指向 VARIANT 结构的指针，将通过该结构返回属性值。

返回值

如果已在 lpvarOut 中返回值，则为非零值；否则为 0。

COleControl::OnGetViewExtent

由框架调用以响应容器的 IViewObject2::GetExtent 请求。

virtual BOOL OnGetViewExtent(
    DWORD dwDrawAspect,
    LONG lindex,
    DVTARGETDEVICE* ptd,
    LPSIZEL lpsizel);

参数

dwDrawAspect
DWORD，描述要显示对象的哪个形式或方面。 有效值取自枚举 DVASPECT 或 DVASPECT2。

lindex
有关的对象部分。 目前仅 -1 有效。

ptd
指向的 DVTARGETDEVICE 结构定义应当为其返回该对象的大小的目标设备。

lpsizel
指向返回对象大小的位置。

返回值

如果成功返回盘区信息，则为非零值；否则为 0。

注解

如果控件使用两遍绘制，并且其不透明部件和透明部件具有不同的维度，则替代此函数。

COleControl::OnGetViewRect

由框架调用以响应容器的 IViewObjectEx::GetRect 请求。

virtual BOOL OnGetViewRect(DWORD dwAspect, LPRECTL pRect);

参数

dwAspect
DWORD，描述要显示对象的哪个形式或方面。 有效值取自枚举 DVASPECT 或 DVASPECT2：

• DVASPECT_CONTENT：整个对象的边框。 对象原点处的左上角和大小等于 GetViewExtent 返回的盘区。

• DVASPECT_OPAQUE：具有矩形不透明区域的对象返回该矩形。 其他会失败。

• DVASPECT_TRANSPARENT：矩形覆盖所有透明的或不规则的部件。

pRect
指向 RECTL 结构，该结构指定应在其中绘制对象的矩形。 此参数控制对象的定位和拉伸。

返回值

如果成功返回对象大小的矩形，则为非零值；否则为 0。

备注

OnGetViewRect 将对象的大小转换为从特定位置（默认值为显示器的左上角）开始的矩形。 如果控件使用两遍绘制，并且其不透明部件和透明部件具有不同的维度，则替代此函数。

COleControl::OnGetViewStatus

由框架调用以响应容器的 IViewObjectEx::GetViewStatus 请求。

virtual DWORD OnGetViewStatus();

返回值

如果成功，则为 VIEWSTATUS 枚举的值之一；否则为 0。 可能的值是以下项的任意组合：

名称	描述
VIEWSTATUS_OPAQUE	对象完全不透明。 如果未设置此位，则对象包含透明部件。 此位仅适用于与内容相关的方面，不适用于 DVASPECT_ICON 或 DVASPECT_DOCPRINT。
VIEWSTATUS_SOLIDBKGND	对象具有纯色背景（由纯色而不是画笔图案组成）。 此位仅在设置 VIEWSTATUS_OPAQUE 时有意义，仅适用于与内容相关的方面，而不适用于 DVASPECT_ICON 或 DVASPECT_DOCPRINT。
VIEWSTATUS_DVASPECTOPAQUE	对象支持 DVASPECT_OPAQUE。 可以通过此方面调用所有采用绘制方面作为参数的 IViewObjectEx 方法。
VIEWSTATUS_DVASPECTTRANSPARENT	对象支持 DVASPECT_TRANSPARENT。 可以通过此方面调用所有采用绘制方面作为参数的 IViewObjectEx 方法。

注解

如果控件使用两遍绘制，请替代此函数。 默认实现返回 VIEWSTATUS_OPAQUE。

COleControl::OnHideToolBars

对控件进行 UI 停用时由框架调用。

virtual void OnHideToolBars();

注解

实现应隐藏由 OnShowToolbars 显示的所有工具栏。

COleControl::OnInactiveMouseMove

在收到 WM_MOUSEMOVE 消息时，由容器在鼠标指针下为非活动对象调用。

virtual void OnInactiveMouseMove(
    LPCRECT lprcBounds,
    long x,
    long y,
    DWORD dwKeyState);

参数

lprcBounds
对象边框，采用包含窗口的客户端坐标。 在收到 WM_MOUSEMOVE 消息时，告知对象其在屏幕上的确切位置和大小。

x
包含窗口的客户端坐标中鼠标位置的 x 坐标。

y
包含窗口的客户端坐标中鼠标位置的 y 坐标。

dwKeyState
标识键盘上的键盘修改键的当前状态。 有效值可以是以下标志的任意组合：MK_CONTROL、MK_SHIFT、MK_ALT、MK_BUTTON、MK_LBUTTON、MK_MBUTTON 和 MK_RBUTTON。

注解

请注意，窗口客户端坐标（像素）用于传递鼠标光标位置。 这可以通过在同一坐标系中另外传递对象的边框来实现。

COleControl::OnInactiveSetCursor

在收到 WM_SETCURSOR 消息时，由容器在鼠标指针下为非活动对象调用。

virtual BOOL OnInactiveSetCursor(
    LPCRECT lprcBounds,
    long x,
    long y,
    DWORD dwMouseMsg,
    BOOL bSetAlways);

参数

lprcBounds
对象边框，采用包含窗口的客户端坐标。 在收到 WM_SETCURSOR 消息时，告知对象其在屏幕上的确切位置和大小。

x
包含窗口的客户端坐标中鼠标位置的 x 坐标。

y
包含窗口的客户端坐标中鼠标位置的 y 坐标。

dwMouseMsg
发生 WM_SETCURSOR 的鼠标消息的标识符。

bSetAlways
指定对象是否必须设置光标。 如果为 TRUE，则对象必须设置光标；如果为 FALSE，则不强制对象设置光标，在这种情况下应返回 S_FALSE。

返回值

如果成功，则不为 0；否则为 0。

备注

请注意，窗口客户端坐标（像素）用于传递鼠标光标位置。 这可以通过在同一坐标系中另外传递对象的边框来实现。

COleControl::OnKeyDownEvent

在处理常用 KeyDown 事件后由框架调用。

virtual void OnKeyDownEvent(
    USHORT nChar,
    USHORT nShiftState);

参数

nChar
所按下键的虚拟键代码值。 有关标准虚拟键代码的列表，请参阅 Winuser.h

nShiftState
包含以下标志的组合：

• SHIFT_MASK：已在操作期间按下 Shift 键。

• CTRL_MASK：已在操作期间按下 Ctrl 键。

• ALT_MASK：已在操作期间按下 Alt 键。

备注

如果控件需要访问触发事件后的关键信息，请替代此函数。

COleControl::OnKeyPressEvent

在触发常用 KeyPress 事件后由框架调用。

virtual void OnKeyPressEvent(USHORT nChar);

参数

nChar
包含所按下键的虚拟键代码值。 有关标准虚拟键代码的列表，请参阅 Winuser.h

备注

请注意，nChar 值可能已被容器修改。

如果你想要此事件发生后的通知，请替代此函数。

COleControl::OnKeyUpEvent

在处理常用 KeyDown 事件后由框架调用。

virtual void OnKeyUpEvent(
    USHORT nChar,
    USHORT nShiftState);

参数

nChar
所按下键的虚拟键代码值。 有关标准虚拟键代码的列表，请参阅 Winuser.h

nShiftState
包含以下标志的组合：

• SHIFT_MASK：已在操作期间按下 Shift 键。

• CTRL_MASK：已在操作期间按下 Ctrl 键。

• ALT_MASK：已在操作期间按下 Alt 键。

备注

如果控件需要访问触发事件后的关键信息，请替代此函数。

COleControl::OnMapPropertyToPage

由框架调用以获取属性页的类 ID，该页实现指定属性的编辑。

virtual BOOL OnMapPropertyToPage(
    DISPID dispid,
    LPCLSID lpclsid,
    BOOL* pbPageOptional);

参数

dispid
该控件的属性的调度 ID。

lpclsid
指向 CLSID 结构的指针，将通过该结构返回类 ID。

pbPageOptional
返回一个指示符，指示使用指定属性页的操作是否为可选。

返回值

如果在 lpclsid 中返回了类 ID，则为非零值；否则为 0。

备注

替代此函数，以提供从容器的属性浏览器调用控件的属性页的方法。

COleControl::OnMnemonic

在容器检测到已按下 OLE 控件的助记键时，由框架调用。

virtual void OnMnemonic(LPMSG pMsg);

参数

pMsg
一个指针，指向由助记键按键操作生成的 Windows 消息。

COleControl::OnProperties

在容器调用控件的属性谓词时由框架调用。

virtual BOOL OnProperties(
    LPMSG lpMsg,
    HWND hWndParent,
    LPCRECT lpRect);

参数

lpMsg
一个指向已调用谓词的 Windows 消息的指针。

hWndParent
控件的父窗口的句柄。

lpRect
一个指向容器中控件使用的矩形的指针。

返回值

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

注解

默认实现显示模式属性对话框。

还可以使用此函数来显示控件的属性页。 调用 OnProperties 函数，在 hWndParent 参数中传递控件父级的句柄。 在这种情况下，将忽略 lpMsg 和 lpRect 参数的值。

COleControl::OnQueryHitPoint

由框架调用以响应容器的 IViewObjectEx::QueryHitPoint 请求。

virtual BOOL OnQueryHitPoint(
    DWORD dwAspect,
    LPCRECT pRectBounds,
    POINT ptlLoc,
    LONG lCloseHint,
    DWORD* pHitResult);

参数

dwAspect
指定如何表示该对象。 有效值取自枚举 DVASPECT 或 DVASPECT2。

pRectBounds
一个指向 RECT 结构的指针，该结构指定 OLE 控件工作区的边框。

ptlLoc
指向 POINT 结构的指针，该结构指定要检查命中情况的点。 该点在 OLE 工作区坐标中指定。

lCloseHint
距离，定义离检查命中情况的点有“多近”。

pHitResult
指向命中查询结果的指针。 以下值之一：

• HITRESULT_OUTSIDE：ptlLoc 位于 OLE 对象之外，不近。

• HITRESULT_TRANSPARENT：ptlLoc 位于 OLE 对象的边界内，但不靠近图像。 例如，透明圆中间的点可能是 HITRESULT_TRANSPARENT。

• HITRESULT_CLOSE：ptlLoc 位于 OLE 对象内部或外部，但足够接近对象，因此可以认为是在对象内。 小型、精简或详细对象可以使用此值。 即使某个点位于对象的边框之外，它仍可能离对象很近（这是命中小型对象所必需的）。

• HITRESULT_HIT：ptlLoc 位于对象的图像中。

返回值

如果成功返回命中结果，则为非零值；否则为 0。 命中是指与 OLE 控件显示区域重叠。

注解

查询对象的显示矩形是否与给定点重叠（命中该点）。 可以替代 QueryHitPoint 以测试非矩形对象的命中。

COleControl::OnQueryHitRect

由框架调用以响应容器的 IViewObjectEx::QueryHitRect 请求。

virtual BOOL OnQueryHitRect(
    DWORD dwAspect,
    LPCRECT pRectBounds,
    LPCRECT prcLoc,
    LONG lCloseHint,
    DWORD* pHitResult);

参数

dwAspect
指定要如何表示该对象。 有效值取自枚举 DVASPECT 或 DVASPECT2。

pRectBounds
一个指向 RECT 结构的指针，该结构指定 OLE 控件工作区的边框。

prcLoc
指向 RECT 结构的指针，该结构指定要检查命中情况（与对象矩形重叠）的矩形（相对于对象的左上角而言）。

lCloseHint
未使用。

pHitResult
指向命中查询结果的指针。 以下值之一：

• HITRESULT_OUTSIDE：矩形中没有点被 OLE 对象命中。

• HITRESULT_HIT：矩形中至少有一个点会命中对象。

返回值

如果成功返回命中结果，则为非零值；否则为 0。

备注

查询对象的显示矩形是否与给定矩形中的任何点重叠（命中矩形）。 可以替代 QueryHitRect 以测试非矩形对象的命中。

COleControl::OnRenderData

由框架调用，以检索采用指定格式的数据。

virtual BOOL OnRenderData(
    LPFORMATETC lpFormatEtc,
    LPSTGMEDIUM lpStgMedium);

参数

lpFormatEtc
指向 FORMATETC 结构，该结构指定请求的信息的格式。

lpStgMedium
指向要在其中返回数据的 STGMEDIUM 结构。

返回值

如果成功，则不为 0；否则为 0。

备注

指定的格式是先前使用用于延迟呈现的 DelayRenderData 或 DelayRenderFileData 成员函数放入控件对象中的一种格式。 如果提供的存储介质是文件或内存，则此函数的默认实现将分别调用 OnRenderFileData 或 OnRenderGlobalData。 如果请求的格式是 CF_METAFILEPICT 或持久性属性集格式，则默认实现将呈现相应的数据并返回非零值。 否则，它将返回 0，不执行任何操作。

如果 lpStgMedium->tymed 为 TYMED_NULL，则应按照 lpFormatEtc->tymed 的指定分配和填充 STGMEDIUM。 如果不是 TYMED_NULL，则应就地使用数据填充 STGMEDIUM。

替代此函数以便以请求的格式和介质提供数据。 根据数据，可能需要改为替代此函数的其他版本之一。 如果数据很小且大小固定，请替代 OnRenderGlobalData。 如果数据在文件中或大小可变，请重写 OnRenderFileData。

有关详细信息，请参阅 Windows SDK 中的 FORMATETC 和 STGMEDIUM 结构。

COleControl::OnRenderFileData

当存储介质为文件时由框架调用，以检索采用指定格式的数据。

virtual BOOL OnRenderFileData(
    LPFORMATETC lpFormatEtc,
    CFile* pFile);

参数

lpFormatEtc
指向 FORMATETC 结构，该结构指定请求的信息的格式。

pFile
指向要在其中呈现数据的 CFile 对象。

返回值

如果成功，则不为 0；否则为 0。

备注

指定的格式是先前使用用于延迟呈现的 DelayRenderData 成员函数放入控件对象中的一种格式。 此函数的默认实现只会返回 FALSE。

替代此函数以便以请求的格式和介质提供数据。 根据数据，可能需要改为替代此函数的其他版本之一。 如果你想要处理多个存储介质，请替代 OnRenderData。 如果数据在文件中或大小可变，请重写 OnRenderFileData。

有关详细信息，请参阅 Windows SDK 中的 FORMATETC 结构。

COleControl::OnRenderGlobalData

当指定的存储媒体为全局内存时由框架调用，以检索采用指定格式的数据。

virtual BOOL OnRenderGlobalData(
    LPFORMATETC lpFormatEtc,
    HGLOBAL* phGlobal);

参数

lpFormatEtc
指向 FORMATETC 结构，该结构指定请求的信息的格式。

phGlobal
指向要在其中返回数据的全局内存的句柄。 如果未分配内存，则此参数可为 NULL。

返回值

如果成功，则不为 0；否则为 0。

备注

指定的格式是先前使用用于延迟呈现的 DelayRenderData 成员函数放入控件对象中的一种格式。 此函数的默认实现只会返回 FALSE。

如果 phGlobal 为 NULL，则应分配并在 phGlobal 中返回一个新的 HGLOBAL。 否则，应使用数据填充 phGlobal 指定的 HGLOBAL。 放在 HGLOBAL 中的数据量不得超过内存块的当前大小。 此外，不能将块重新分配为更大的大小。

替代此函数以便以请求的格式和介质提供数据。 根据数据，可能需要改为替代此函数的其他版本之一。 如果你想要处理多个存储介质，请替代 OnRenderData。 如果数据在文件中或大小可变，请重写 OnRenderFileData。

有关详细信息，请参阅 Windows SDK 中的 FORMATETC 结构。

COleControl::OnResetState

当控件的属性应设置为其默认值时，由框架调用。

virtual void OnResetState();

注解

默认实现调用 DoPropExchange，传递导致属性设置为其默认值的 CPropExchange 对象。

控件编写器可以在这个可替代函数中插入 OLE 控件的初始化代码。 如果 IPersistStream::Load 或 IPersistStorage::Load 失败，或者在调用 IPersistStreamInit::InitNew 或 IPersistStorage::InitNew 时没有先调用 IPersistStream::Load 或 IPersistStorage::Load，则会调用此函数。

COleControl::OnSetClientSite

在容器已调用控件的 IOleControl::SetClientSite 函数时由框架调用。

virtual void OnSetClientSite();

备注

默认情况下，OnSetClientSite 会检查是否加载了数据路径属性，并会在答案为是的情况下调用 DoDataPathPropExchange。

替代此函数以执行对此通知的任何特殊处理。 具体而言，此函数的替代应调用基类。

COleControl::OnSetData

由框架调用，以将控件的数据替换为指定的数据。

virtual BOOL OnSetData(
    LPFORMATETC lpFormatEtc,
    LPSTGMEDIUM lpStgMedium,
    BOOL bRelease);

参数

lpFormatEtc
指向用于指定数据格式的 FORMATETC 结构的指针。

lpStgMedium
指向数据所在的 STGMEDIUM 结构的指针。

bRelease
如果控件应释放存储介质，则为 TRUE；如果控件不应释放存储介质，则为 FALSE。

返回值

如果成功，则不为 0；否则为 0。

备注

如果数据采用持久性属性集格式，则默认实现会相应地修改控件的状态。 否则，默认实现不执行任何操作。 如果 bRelease 为 TRUE，则调用 ReleaseStgMedium；否则不调用它。

替代此函数可将控件的数据替换为指定的数据。

有关详细信息，请参阅 Windows SDK 中的 FORMATETC 和 STGMEDIUM 结构。

COleControl::OnSetExtent

当因调用 IOleObject::SetExtent 而需要更改控件的盘区时，由框架调用。

virtual BOOL OnSetExtent(LPSIZEL lpSizeL);

参数

lpSizeL
一个指向 SIZEL 结构的指针，该结构使用长整型来表示控件的宽度和高度（以 HIMETRIC 单位表示）。

返回值

如果已接受大小更改，则为非零值；否则为 0。

注解

默认实现处理控件的盘区的重设大小。 如果控件处于就地活动状态，则会调用容器的 OnPosRectChanged。

替代此函数以更改控件的默认重设大小。

COleControl::OnSetObjectRects

由框架调用以实现对 IOleInPlaceObject::SetObjectRects 的调用。

virtual BOOL OnSetObjectRects(
    LPCRECT lpRectPos,
    LPCRECT lpRectClip);

参数

lpRectPos
一个指向 RECT 结构的指针，该结构指示控件相对于容器的新位置和大小。

lpRectClip
一个指向 RECT 结构的指针，该结构指示要将控件剪切成的矩形区域。

返回值

如果已接受重新定位，则为非零值；否则为 0。

注解

默认实现会自动处理控件窗口的重新定位和重设大小，并返回 TRUE。

替代此函数以更改此函数的默认行为。

COleControl::OnShowToolBars

当控件已进行 UI 激活时由框架调用。

virtual void OnShowToolBars();

备注

默认实现不执行任何操作。

COleControl::OnTextChanged

当常用 Caption 或 Text 属性值已更改时由框架调用。

virtual void OnTextChanged();

注解

默认实现调用 InvalidateControl。

如果你想要此属性更改后的通知，请替代此函数。

COleControl::OnWindowlessMessage

由框架调用以响应容器的 IOleInPlaceObjectWindowless::OnWindowMessage 请求。

virtual BOOL OnWindowlessMessage(
    UINT msg,
    WPARAM wParam,
    LPARAM lParam,
    LRESULT* plResult);

参数

msg
Windows 传递的消息标识符。

wParam
由 Windows 传递。 指定其他的消息特定信息。 此参数的内容取决于 msg 参数的值。

lParam
由 Windows 传递。 指定其他的消息特定信息。 此参数的内容取决于 msg 参数的值。

plResult
Windows 结果代码。 指定消息处理的结果，取决于所发送的消息。

返回值

如果成功，则不为 0；否则为 0。

备注

处理无窗口控件的窗口消息。 COleControl 的 OnWindowlessMessage 应该用于鼠标消息和键盘消息以外的窗口消息。 COleControl 提供 SetCapture 和 SetFocus，专用于获取无窗口 OLE 对象的鼠标捕获和键盘焦点。

由于无窗口对象没有窗口，因此它们需要一种机制来让容器向其调度消息。 无窗口 OLE 对象通过 IOleInPlaceObjectWindowless 接口（IOleInPlaceObject 的扩展，用于无窗口支持）上的 OnWindowMessage 方法从其容器获取消息。 OnWindowMessage 不采用 HWND 参数。

COleControl::ParentToClient

将 pPoint 的坐标转换为客户端坐标。

virtual UINT ParentToClient(
    LPCRECT lprcBounds,
    LPPOINT pPoint,
    BOOL bHitTest = FALSE) const;

参数

lprcBounds
指向容器中 OLE 控件的边界的指针。 不是工作区，而是整个控件的区域，包括边框和滚动条。

pPoint
指向父级（容器）点的指针，该点将转换为控件的工作区的坐标。

bHitTest
指定是否要在此点上完成命中测试。

返回值

如果 bHitTest 为 FALSE，则返回 HTNOWHERE。 如果 bHitTest 为 TRUE，则返回父级（容器）点落在 OLE 控件的工作区且是以下鼠标命中测试值之一时所处的位置：

• HTBORDER：在没有调整大小边框的窗口的边框中。

• HTBOTTOM：在窗口的下部水平边框中。

• HTBOTTOMLEFT：在窗口边框的左下角。

• HTBOTTOMRIGHT：在窗口边框的右下角。

• HTCAPTION：在标题栏区域中。

• HTCLIENT：在工作区中。

• HTERROR：在屏幕背景上，或在窗口之间的分割线上（与 HTNOWHERE 相同，区别是 DefWndProc Windows 函数会生成系统蜂鸣音来指示错误）。

• HTGROWBOX：在大小框中。

• HTHSCROLL：在水平滚动条中。

• HTLEFT：在窗口的左边框中。

• HTMAXBUTTON：在最大化按钮中。

• HTMENU：在菜单区域中。

• HTMINBUTTON：在最小化按钮中。

• HTNOWHERE：在屏幕背景上，或在窗口之间的分隔线上。

• HTREDUCE：在最小化按钮中。

• HTRIGHT：在窗口的右边框中。

• HTSIZE：在大小框中（与 HTGROWBOX 相同）。

• HTSYSMENU：在“控件”菜单中，或在子窗口的“关闭”按钮中。

• HTTOP：在窗口的上部水平边框中。

• HTTOPLEFT：在窗口边框的左上角。

• HTTOPRIGHT：在窗口边框的右上角。

• HTTRANSPARENT：在目前被另一个窗口覆盖的窗口中。

• HTVSCROLL：在垂直滚动条中。

• HTZOOM：在最大化按钮中。

注解

在输入时，pPoint 是相对于父级的原点（容器左上角）的。 在输出时，pPoint 是相对于 OLE 控件工作区原点（控件工作区左上角）的。

COleControl::PostModalDialog

通知容器已关闭模式对话框。

void PostModalDialog(HWND hWndParent = NULL);

参数

hWndParent
模式对话框的父窗口的句柄。

备注

在显示任何模式对话框后调用此函数。 必须调用此函数，使容器能够启用 PreModalDialog 所禁用的任何顶级窗口。 此函数应与对 PreModalDialog 的调用配对。

COleControl::PreModalDialog

通知容器将显示模式对话框。

void PreModalDialog(HWND hWndParent = NULL);

参数

hWndParent
模式对话框的父窗口的句柄。

注解

在显示任何模式对话框之前调用此函数。 必须调用此函数，以便容器可以禁用其所有顶级窗口。 显示模式对话框后，必须调用 PostModalDialog。

COleControl::RecreateControlWindow

销毁并重新创建控件的窗口。

void RecreateControlWindow();

注解

如果需要更改窗口的样式位，可能需要这样做。

COleControl::Refresh

强制重绘 OLE 控件。

void Refresh();

注解

COleControl 基类支持将此函数作为名为 Refresh 的常用方法。 这样，OLE 控件的用户就可以在特定时间重绘控件。 有关此方法的详细信息，请参阅 ActiveX 控件：方法一文。

COleControl::ReleaseCapture

释放鼠标捕获。

BOOL ReleaseCapture();

返回值

如果成功，则不为 0；否则为 0。

注解

如果控件当前具有鼠标捕获，则会释放捕获。 否则，此函数将不起作用。

COleControl::ReleaseDC

释放无窗口控件的容器的显示设备上下文，从而释放可供其他应用程序使用的设备上下文。

int ReleaseDC(CDC* pDC);

参数

pDC
标识要释放的容器设备上下文。

返回值

如果成功，则不为 0；否则为 0。

备注

每次调用 GetDC 时，应用程序必须调用 ReleaseDC。

COleControl::ReparentControlWindow

设置控件的父级。

virtual void ReparentControlWindow(
    HWND hWndOuter,
    HWND hWndParent);

参数

hWndOuter
控件窗口的句柄。

hWndParent
新父级窗口的句柄。

备注

调用此函数以重置控件窗口的父级。

COleControl::ResetStockProps

将 COleControl 常用属性的状态初始化为其默认值。

void ResetStockProps();

备注

属性包括：Appearance、BackColor、BorderStyle、Caption、Enabled、Font、ForeColor、hWnd 和 Text。 有关常用属性的说明，请参阅 ActiveX 控件：添加常用属性。

可以通过使用 ResetStockProps 和 ResetVersion 来替代 COleControl::OnResetState，改进控件的二进制初始化性能。 请参阅以下示例。 若要进一步了解如何优化初始化，请参阅 ActiveX 控件：优化。

示例

void CMyAxCtrl::OnResetState()
{
   ResetVersion(MAKELONG(_wVerMinor, _wVerMajor));
   ResetStockProps();

   // initialize custom properties here
}

COleControl::ResetVersion

将版本号初始化为指定值。

void ResetVersion(DWORD dwVersionDefault);

参数

dwVersionDefault
要分配给控件的版本号。

备注

可以通过使用 ResetVersion 和 ResetStockProps 来替代 COleControl::OnResetState，改进控件的二进制初始化性能。 请参阅 ResetStockProps 中的示例。 若要进一步了解如何优化初始化，请参阅 ActiveX 控件：优化。

COleControl::ScrollWindow

允许无窗口 OLE 对象在屏幕上滚动就地活动图像中的区域。

void ScrollWindow(
    int xAmount,
    int yAmount,
    LPCRECT lpRect = NULL,
    LPCRECT lpClipRect = NULL);

参数

xAmount
指定水平滚动的量（以设备单位表示）。 此参数必须是负值才能向左滚动。

yAmount
指定垂直滚动的量（以设备单位表示）。 此参数必须是负值才能向上滚动。

lpRect
指向 CRect 对象或 RECT 结构，该对象或结构指定要滚动的 OLE 对象的工作区部分（以包含窗口的客户端坐标表示）。 如果 lpRect 为 NULL，则会滚动整个 OLE 对象的工作区。

lpClipRect
指向 CRect 对象或 RECT 结构，该对象或结构指定要将控件剪切成的矩形。 仅滚动矩形内的像素。 即使矩形外部的位位于 lpRect 矩形中，也不会影响这些位。 如果 lpClipRect 为 NULL，则不会在滚动矩形上执行剪辑。

COleControl::SelectFontObject

将字体选择到设备上下文中。

CFont* SelectFontObject(
    CDC* pDC,
    CFontHolder& fontHolder);

参数

pDC
指向设备上下文对象的指针。

fontHolder
对表示要选择的字体的 CFontHolder 对象的引用。

返回值

一个指向先前选定的字体的指针。 调用方在完成所有使用 fontHolder 的绘制操作后，应重新选择先前选定的字体，方法是将它作为参数传递给 CDC::SelectObject。

COleControl::SelectStockFont

将常用 Font 属性选择到设备上下文中。

CFont* SelectStockFont(CDC* pDC);

参数

pDC
要将字体选择到其中的设备上下文。

返回值

一个指向先前选定的 CFont 对象的指针。 完成后，应使用 CDC::SelectObject 将此字体重新选回到设备上下文中。

COleControl::SerializeExtent

序列化或初始化分配给控件的显示空间的状态。

void SerializeExtent(CArchive& ar);

参数

ar
要序列化为它或从它进行序列化的 CArchive 对象。

备注

可以通过使用 SerializeExtent、SerializeStockProps 和 SerializeVersion 来替代 COleControl::Serialize，改进控件的二进制持久性性能。 请参阅以下示例。 若要进一步了解如何优化初始化，请参阅 ActiveX 控件：优化。

示例

void CMyAxCtrl::Serialize(CArchive &ar)
{
   SerializeVersion(ar, MAKELONG(_wVerMinor, _wVerMajor));
   SerializeExtent(ar);
   SerializeStockProps(ar);

   if (ar.IsStoring())
   { // storing code
   }
   else
   { // loading code
   }
}

COleControl::SerializeStockProps

序列化或初始化以下 COleControl 常用属性的状态：Appearance、BackColor、BorderStyle、Caption、Enabled、Font、ForeColor 和 Text。

void SerializeStockProps(CArchive& ar);

参数

ar
要序列化为它或从它进行序列化的 CArchive 对象。

备注

有关常用属性的说明，请参阅 ActiveX 控件：添加常用属性。

可以通过使用 SerializeStockProps、SerializeExtent 和 SerializeVersion 来替代 COleControl::Serialize，改进控件的二进制持久性性能。 有关示例，请参阅 SerializeExtent 上的代码。 若要进一步了解如何优化初始化，请参阅 ActiveX 控件：优化。

COleControl::SerializeVersion

序列化或初始化控件的版本信息的状态。

DWORD SerializeVersion(
    CArchive& ar,
    DWORD dwVersionDefault,
    BOOL bConvert = TRUE);

参数

ar
要序列化为它或从它进行序列化的 CArchive 对象。

dwVersionDefault
控件的当前版本号。

bConvert
指示在保存持久性数据时是应将其转换为最新格式，还是应保持加载时的格式。

返回值

控件的版本号。 如果正在加载指定的存档，则 SerializeVersion 会返回从该存档加载的版本。 否则，它会返回当前加载的版本。

备注

可以通过使用 SerializeVersion、SerializeExtent 和 SerializeStockProps 来替代 COleControl::Serialize，改进控件的二进制持久性性能。 有关示例，请参阅 SerializeExtent 上的代码。 若要进一步了解如何优化初始化，请参阅 ActiveX 控件：优化。

COleControl::SetAppearance

设置控件的常用 Appearance 属性值。

void SetAppearance (short sAppearance);

参数

sAppearance
要用于控件外观的 short (VT_I2) 值。 值为零会将控件的外观设置为平面，值为 1 会将控件的外观设置为 3D。

备注

有关常用属性的详细信息，请参阅 ActiveX 控件：属性。

COleControl::SetBackColor

设置控件的常用 BackColor 属性值。

void SetBackColor(OLE_COLOR dwBackColor);

参数

dwBackColor
要用于控件的背景绘制的 OLE_COLOR 值。

备注

若要详细了解如何使用此属性和其他相关属性，请参阅 ActiveX 控件：属性一文。

COleControl::SetBorderStyle

设置控件的常用 BorderStyle 属性值。

void SetBorderStyle(short sBorderStyle);

参数

sBorderStyle
控件的新边框样式；0 表示无边框，1 表示普通边框。

备注

然后，将重新创建控件窗口并调用 OnBorderStyleChanged。

COleControl::SetCapture

使控件的容器窗口代表控件获取鼠标捕获。

CWnd* SetCapture();

返回值

一个指向以前接收鼠标输入的 CWnd 窗口对象的指针。

注解

如果控件已激活且无窗口，则此函数会使控件的容器窗口代表控件获取鼠标捕获。 否则，此函数会使控件本身获取鼠标捕获（与 CWnd::SetCapture 相同）。

COleControl::SetControlSize

设置 OLE 控件窗口的大小，并通知容器：控件站点在变化。

BOOL SetControlSize(int cx, int cy);

参数

cx
指定控件的新宽度（以像素为单位）。

cy
指定控件的新高度（以像素为单位）。

返回值

如果调用已成功，则返回非零值；否则返回 0。

注解

不应在控件的构造函数中使用此函数。

请注意，控件窗口的所有坐标都是相对于控件的左上角的。

COleControl::SetEnabled

设置控件的常用 Enabled 属性值。

void SetEnabled(BOOL bEnabled);

参数

bEnabled
如果要启用控件，则为 TRUE；否则为 FALSE。

注解

设置此属性后，将调用 OnEnabledChange。

COleControl::SetFocus

使控件的容器窗口代表控件获取输入焦点。

CWnd* SetFocus();

返回值

一个指向以前有输入焦点的 CWnd 窗口对象的指针；如果没有此类窗口，则为 NULL。

备注

如果控件已激活且无窗口，则此函数会使控件的容器窗口代表控件获取输入焦点。 输入焦点将键盘输入定向到容器的窗口，容器会将所有后续键盘消息调度到调用 SetFocus 的 OLE 对象。 以前具有输入焦点的任何窗口都会失去它。

如果控件不是无窗口的，此函数将导致控件本身获取输入焦点（与 CWnd::SetFocus 相同）。

COleControl::SetFont

设置控件的常用 Font 属性。

void SetFont(LPFONTDISP pFontDisp);

参数

pFontDisp
一个指向 Font 调度接口的指针。

COleControl::SetForeColor

设置控件的常用 ForeColor 属性值。

void SetForeColor(OLE_COLOR dwForeColor);

参数

dwForeColor
要用于控件的前景绘制的 OLE_COLOR 值。

备注

若要详细了解如何使用此属性和其他相关属性，请参阅 ActiveX 控件：属性一文。

COleControl::SetInitialDataFormats

由框架调用以初始化控件支持的数据格式列表。

virtual void SetInitialDataFormats();

备注

默认实现指定两种格式：CF_METAFILEPICT 和持久性属性集。

COleControl::SetInitialSize

在容器中首次显示时设置 OLE 控件的大小。

void SetInitialSize(
    int cx,
    int cy);

参数

cx
OLE 控件的初始宽度（以像素为单位）。

cy
OLE 控件的初始高度（以像素为单位）。

注解

在构造函数中调用此函数以设置控件的初始大小。 初始大小以设备单位或像素进行衡量。 建议在控件的构造函数中进行此调用。

COleControl::SetModifiedFlag

更改控件的已修改状态。

void SetModifiedFlag(BOOL bModified = TRUE);

参数

bModified
控件的已修改标志的新值。 TRUE 指示控件的状态已修改；FALSE 指示控件的状态刚刚保存。

注解

在发生会影响控件持久状态的更改时调用此函数。 例如，如果持久性属性的值发生更改，请在将 bModified 设置为 TRUE 的情况下调用此函数。

COleControl::SetNotPermitted

指示编辑请求已失败。

void SetNotPermitted();

备注

当 BoundPropertyRequestEdit 失败时调用此函数。 此函数会引发类型为 COleDispScodeException 的异常来指示不允许设置操作。

COleControl::SetNotSupported

防止用户修改控件的属性值。

void SetNotSupported();

备注

请在不支持由控件的用户修改属性值的情况下，调用此函数来代替任何属性的 Set 函数。 例如，只读属性。

COleControl::SetRectInContainer

设置控件矩形相对于容器的坐标，以设备单位表示。

BOOL SetRectInContainer(LPCRECT lpRect);

参数

lpRect
一个指向矩形的指针，该矩形包含控件相对于容器的新坐标。

返回值

如果调用已成功，则返回非零值；否则返回 0。

注解

如果控件处于打开状态，则会重设其大小；否则，将调用容器的 OnPosRectChanged 函数。

COleControl::SetText

设置控件的常用 Caption 或 Text 属性的值。

void SetText(LPCTSTR pszText);

参数

pszText
指向字符串的指针。

备注

请注意，常用 Caption 和 Text 属性都映射到相同的值。 这意味着对任一属性所做的任何更改都会自动更改两个属性。 通常，控件应支持常用 Caption 或 Text 属性，但不应同时支持这两者。

COleControl::ThrowError

指示控件中出现错误。

void ThrowError(
    SCODE sc,
    UINT nDescriptionID,
    UINT nHelpID = -1);

void ThrowError(
    SCODE sc,
    LPCTSTR pszDescription = NULL,
    UINT nHelpID = 0);

参数

sc
要报告的状态代码值。 有关可能代码的完整列表，请参阅 ActiveX 控件：高级主题一文。

nDescriptionID
要报告的异常的字符串资源 ID。

nHelpID
要报告的主题的帮助 ID。

pszDescription
一个字符串，包含要报告的异常的说明。

备注

此函数只应从 OLE 属性的 Get 或 Set 函数内调用，或从 OLE 自动化方法的实现中调用。 如果需要指示在其他时间发生的错误，则应触发常用 Error 事件。

COleControl::TransformCoords

在 HIMETRIC 单位与容器的原生单位之间转换坐标值。

void TransformCoords(
    POINTL* lpptlHimetric,
    POINTF* lpptfContainer,
    DWORD flags);

参数

lpptlHimetric
指向 POINTL 结构的指针，该结构包含以 HIMETRIC 单位表示的坐标。

lpptfContainer
指向 POINTF 结构的指针，该结构包含容器的单位大小的坐标。

flags
以下值的组合：

• XFORMCOORDS_POSITION：容器中的一个位置。

• XFORMCOORDS_SIZE：容器中的一个大小。

• XFORMCOORDS_HIMETRICTOCONTAINER：将 HIMETRIC 单位转换为容器的单位。

• XFORMCOORDS_CONTAINERTOHIMETRIC：将容器的单位转换为 HIMETRIC 单位。

备注

前两个标志（XFORMCOORDS_POSITION 和 XFORMCOORDS_SIZE）指示坐标是应被视为位置，还是应被视为大小。 其余两个标志指示转换的方向。

COleControl::TranslateColor

将颜色值从 OLE_COLOR 数据类型转换为 COLORREF 数据类型。

COLORREF TranslateColor(
    OLE_COLOR clrColor,
    HPALETTE hpal = NULL);

参数

clrColor
OLE_COLOR 数据类型。 有关详细信息，请参阅 Windows OleTranslateColor 函数。

hpal
可选调色板的句柄；可以为 NULL。

返回值

一个 RGB（红、绿、蓝）32 位颜色值，用于定义最接近设备可以表示的 clrColor 值的纯色。

注解

此函数可用于将常用 ForeColor 和 BackColor 属性转换为 CDC 成员函数使用的 COLORREF 类型。

COleControl::WillAmbientsBeValidDuringLoad

确定控件是否应在随后从其持久性状态加载时使用环境属性的值作为默认值。

BOOL WillAmbientsBeValidDuringLoad();

返回值

非零值表示环境属性有效；其他值表示环境属性无效。

注解

在某些容器中，在初次调用 COleControl::DoPropExchange 的替代时，控件可能无权访问其环境属性。 如果容器在调用 IOleObject::SetClientSite 之前调用 IPersistStreamInit::Load 或 IPersistStorage::Load（即，它不认可 OLEMISC_SETCLIENTSITEFIRST 状态位），则可能会发生这种情况。

COleControl::WindowProc

为 COleControl 对象提供 Windows 过程。

virtual LRESULT WindowProc(
    UINT message,
    WPARAM wParam,
    LPARAM lParam);

参数

message
指定要处理的 Windows 消息。

wParam
提供处理消息时使用的其他信息。 参数值取决于消息。

lParam
提供处理消息时使用的其他信息。 参数值取决于消息。

返回值

已调度的消息的返回值。

备注

调用此函数以通过控件的消息映射来调度特定消息。

另请参阅

MFC 示例 CIRC3
MFC 示例 TESTHELP
COlePropertyPage 类
CWnd 类
层次结构图
CFontHolder 类
CPictureHolder 类