事件接收器映射

  • 项目

当嵌入 OLE 控件触发事件时，控件的容器将使用 MFC 提供的名为“事件接收器映射”的机制接收事件。 此事件接收器映射为每个特定事件指定处理程序函数，以及这些事件的参数。 有关事件接收器映射的详细信息，请参阅文章 ActiveX 控件容器。

事件接收器映射

名称 描述
BEGIN_EVENTSINK_MAP 启动事件接收器映射的定义。
DECLARE_EVENTSINK_MAP 声明事件接收器映射。
END_EVENTSINK_MAP 结束事件接收器映射的定义。
ON_EVENT 为特定事件定义事件处理程序。
ON_EVENT_RANGE 为一组 OLE 控件触发的特定事件定义事件处理程序。
ON_EVENT_REFLECT 在控件的容器处理控件触发的事件之前接收这些事件。
ON_PROPNOTIFY 定义处理程序来处理来自 OLE 控件的属性通知。
ON_PROPNOTIFY_RANGE 定义处理程序来处理来自一组 OLE 控件的属性通知。
ON_PROPNOTIFY_REFLECT 在控件的容器处理控件发送的属性通知之前接收这些通知。

BEGIN_EVENTSINK_MAP

启动事件接收器映射的定义。

BEGIN_EVENTSINK_MAP(theClass, baseClass)

参数

theClass
指定其事件接收器映射的控件类的名称。

baseClass
指定 theClass 的基类的名称。

备注

在为类定义成员函数的实现 (.cpp) 文件中，使用 BEGIN_EVENTSINK_MAP 宏启动事件接收器映射，然后为要通知的每个事件添加宏条目，并使用 END_EVENTSINK_MAP 宏完成事件接收器映射。

有关事件接收器映射和 OLE 控件容器的详细信息，请参阅文章 ActiveX 控件容器。

要求

标头 afxdisp.h

DECLARE_EVENTSINK_MAP

OLE 容器可以提供事件接收器映射，以指定容器将收到通知的事件。

DECLARE_EVENTSINK_MAP()

注解

在类声明末尾使用 DECLARE_EVENTSINK_MAP 宏。 然后，在定义类的成员函数的 .CPP 文件中，使用 BEGIN_EVENTSINK_MAP 宏、要通知的每个事件的宏条目以及 END_EVENTSINK_MAP 宏来声明事件接收器列表的末尾。

有关事件接收器映射的详细信息，请参阅文章 ActiveX 控件容器。

要求

标头 fxwin.h

END_EVENTSINK_MAP

结束事件接收器映射的定义。

END_EVENTSINK_MAP()

要求

标头 afxdisp.h

ON_EVENT

使用 ON_EVENT 宏可以为 OLE 控件触发的事件定义事件处理程序函数。

ON_EVENT(theClass, id, dispid, pfnHandler,  vtsParams)

参数

theClass
此事件接收器映射所属的类。

id
OLE 控件的控件 ID。

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

pfnHandler
指向处理事件的成员函数的指针。 此函数应具有 BOOL 返回类型以及与事件参数匹配的参数类型（请参阅 vtsParams）。 函数应返回 TRUE 以指示事件已处理；否则返回 FALSE。

vtsParams
VTS_ 常量序列，用于指定事件的参数类型。 这些常量与调度映射条目（如 DISP_FUNCTION）中使用的常量相同。

备注

vtsParams 参数是一个由 VTS_ 常量的值组成的以空格分隔的列表。 用空格（而不是逗号）分隔的其中一个或多个值指定函数的参数列表。 例如：

VTS_I2 VTS_BOOL

指定一个列表，其中包含短整数，后跟 BOOL。

有关 VTS_ 常量的列表，请参阅 EVENT_CUSTOM。

要求

标头 afxdisp.h

ON_EVENT_RANGE

使用 ON_EVENT_RANGE 宏可以为由任何 OLE 控件触发的事件定义事件处理程序函数，该控件的控件 ID 在连续的 ID 范围内。

ON_EVENT_RANGE(theClass, idFirst, idLast, dispid, pfnHandler,  vtsParams)

参数

theClass
此事件接收器映射所属的类。

idFirst
区域中第一个 OLE 控件的控件 ID。

idLast
区域中最后一个 OLE 控件的控件 ID。

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

pfnHandler
指向处理事件的成员函数的指针。 此函数应具有 BOOL 返回类型、UINT 类型的第一个参数（用于控件 ID），以及与事件参数匹配的其他参数类型（请参阅 vtsParams）。 函数应返回 TRUE 以指示事件已处理；否则返回 FALSE。

vtsParams
VTS_ 常量序列，用于指定事件的参数类型。 对于控件 ID，第一个常量的类型应为 VTS_I4。 这些常量与调度映射条目（如 DISP_FUNCTION）中使用的常量相同。

备注

vtsParams 参数是一个由 VTS_ 常量的值组成的以空格分隔的列表。 用空格（而不是逗号）分隔的其中一个或多个值指定函数的参数列表。 例如：

VTS_I2 VTS_BOOL

指定一个列表，其中包含短整数，后跟 BOOL。

有关 VTS_ 常量的列表，请参阅 EVENT_CUSTOM。

示例

下面的示例演示为三个控件（IDC_MYCTRL1 到 IDC_MYCTRL3）实现的 MouseDown 事件的事件处理程序。 事件处理程序函数 OnRangeMouseDown 在对话框类 (CMyDlg) 的头文件中声明为：

BOOL OnRangeMouseDown(UINT CtlID, short MouseButton, short Shift,
   long x, long y);

下面的代码在对话框类的实现文件中定义。

BEGIN_EVENTSINK_MAP(CMyDlg, CDialog)
   ON_EVENT_RANGE(CMyDlg, IDC_MYCTRL1, IDC_MYCTRL3, -605, OnRangeMouseDown,
      VTS_I4 VTS_I2 VTS_I2 VTS_I4 VTS_I4)
END_EVENTSINK_MAP()

要求

标头 afxdisp.h

ON_EVENT_REFLECT

ON_EVENT_REFLECT 宏在 OLE 控件的包装类的事件接收器映射中使用时，在控件的容器处理这些事件之前接收控件触发的事件。

ON_EVENT_REFLECT(theClass,  dispid, pfnHandler,  vtsParams)

参数

theClass
此事件接收器映射所属的类。

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

pfnHandler
指向处理事件的成员函数的指针。 此函数应具有 BOOL 返回类型以及与事件参数匹配的参数类型（请参阅 vtsParams）。 函数应返回 TRUE 以指示事件已处理；否则返回 FALSE。

vtsParams
VTS_ 常量序列，用于指定事件的参数类型。 这些常量与调度映射条目（如 DISP_FUNCTION）中使用的常量相同。

备注

vtsParams 参数是一个由 VTS_ 常量的值组成的以空格分隔的列表。

用空格（而不是逗号）分隔的其中一个或多个值指定函数的参数列表。 例如：

VTS_I2 VTS_BOOL

指定一个列表，其中包含短整数，后跟 BOOL。

有关 VTS_ 常量的列表，请参阅 EVENT_CUSTOM。

要求

标头 afxdisp.h

ON_PROPNOTIFY

使用 ON_PROPNOTIFY 宏定义用于处理来自 OLE 控件的属性通知的事件接收器映射条目。

ON_PROPNOTIFY(theClass, id, dispid, pfnRequest, pfnChanged)

参数

theClass
此事件接收器映射所属的类。

id
OLE 控件的控件 ID。

dispid
通知中涉及的属性的调度 ID。

pfnRequest
指向处理此属性的 OnRequestEdit 通知的成员函数的指针。 此函数应具有 BOOL 返回类型和 BOOL* 参数。 此函数应将参数设置为 TRUE 以允许更改属性，设置为 FALSE 以禁止。 函数应返回 TRUE 以指示通知已处理；否则返回 FALSE。

pfnChanged
指向处理此属性的 OnChanged 通知的成员函数的指针。 该函数应具有 BOOL 返回类型和 UINT 参数。 函数应返回 TRUE 以指示通知已处理；否则返回 FALSE。

注解

vtsParams 参数是一个由 VTS_ 常量的值组成的以空格分隔的列表。 用空格（而不是逗号）分隔的其中一个或多个值指定函数的参数列表。 例如：

VTS_I2 VTS_BOOL

指定一个列表，其中包含短整数，后跟 BOOL。

有关 VTS_ 常量的列表，请参阅 EVENT_CUSTOM。

ON_PROPNOTIFY_RANGE

使用 ON_PROPNOTIFY_RANGE 宏可以定义一个事件接收器映射条目，用于处理来自任何 OLE 控件的属性通知，该控件的控件 ID 在连续的 ID 范围内。

ON_PROPNOTIFY_RANGE(theClass, idFirst, idLast, dispid, pfnRequest, pfnChanged)

参数

theClass
此事件接收器映射所属的类。

idFirst
区域中第一个 OLE 控件的控件 ID。

idLast
区域中最后一个 OLE 控件的控件 ID。

dispid
通知中涉及的属性的调度 ID。

pfnRequest
指向处理此属性的 OnRequestEdit 通知的成员函数的指针。 此函数应具有 BOOL 返回类型以及 UINT 和 BOOL* 参数。 此函数应将参数设置为 TRUE 以允许更改属性，设置为 FALSE 以禁止。 函数应返回 TRUE 以指示通知已处理；否则返回 FALSE。

pfnChanged
指向处理此属性的 OnChanged 通知的成员函数的指针。 该函数应具有 BOOL 返回类型和 UINT 参数。 函数应返回 TRUE 以指示通知已处理；否则返回 FALSE。

要求

标头 afxdisp.h

ON_PROPNOTIFY_REFLECT

ON_PROPNOTIFY_REFLECT 宏在 OLE 控件的包装类的事件接收器映射中使用时，在控件的容器处理属性通知之前接收控件发送的属性通知。

ON_PROPNOTIFY_REFLECT(theClass, dispid, pfnRequest, pfnChanged)

参数

theClass
此事件接收器映射所属的类。

dispid
通知中涉及的属性的调度 ID。

pfnRequest
指向处理此属性的 OnRequestEdit 通知的成员函数的指针。 此函数应具有 BOOL 返回类型和 BOOL* 参数。 此函数应将参数设置为 TRUE 以允许更改属性，设置为 FALSE 以禁止。 函数应返回 TRUE 以指示通知已处理；否则返回 FALSE。

pfnChanged
指向处理此属性的 OnChanged 通知的成员函数的指针。 该函数应具有 BOOL 返回类型，并且没有参数。 函数应返回 TRUE 以指示通知已处理；否则返回 FALSE。

要求

标头 afxdisp.h

另请参阅

宏和全局函数