• 图形学
• 桌面应用

导读

tagGESTURENOTIFYSTRUCT是 RGF 仓颉版（RGF_CJ）在rgf.win_def子包中提供的一个与 Win32 手势触控机制直接相关的原生结构体，用于承载WM_GESTURENOTIFY（0x011A）消息的附加数据——包括触控设备实例、目标窗口句柄、设备坐标位置与标志位等。本篇以该结构体的 API 参考文档为骨架，结合 hwinuser.cj 的源码定义、rgf_proc.cj 的事件封装实现，逐字段讲解其类型、默认值与底层含义，并演示它如何通过EvGestureNotify接入 RGF 的事件体系，让熟悉 Win32 的开发者能够快速定位、读懂并在自己的窗口中处理手势通知数据。

结构体定位：Win32 手势通知消息的数据载体

在 RGF 的rgf.win_def子包中，hwinuser.cj 定义了手势相关的两条窗口消息常量：

• WM_GESTURE（0x0119）：实际的手势动作消息；
• WM_GESTURENOTIFY（0x011A）：手势通知消息，在触控设备到达/移除等场景下由系统向窗口发送，用于告知应用当前手势状态并允许其配置手势。

tagGESTURENOTIFYSTRUCT正是WM_GESTURENOTIFY消息中lParam所指向的数据结构。其声明如下：

@C public struct tagGESTURENOTIFYSTRUCT

@C注解表明该结构体被标记为 C 兼容（extern C ABI）类型，保证其在内存中的布局与 Win32 原生 SDK 结构体一致，从而可以通过指针安全地与系统消息进行互操作。完整的定义位于 src/win_def/hwinuser.cj#L1237-L1245。

五个字段逐一解析

API 参考文档中罗列了该结构体的五个公开字段，各字段的声明、类型与默认值如下：

cbSize：结构体大小

public var cbSize: UINT = 0

• 类型UINT在 wintype.cj 中定义为UInt32的类型别名；
• 该字段用于存放结构体自身的字节大小，是 Win32 消息结构体的惯用约定，系统据此校验传入指针的合法长度；
• 在 RGF 封装层中，该值直接由系统填充，解析侧无需主动维护。

dwFlags：标志位

public var dwFlags: DWORD = 0

• 类型DWORD同样在 wintype.cj 中定义为UInt32；
• 该字段承载本次通知的标志信息。仓库在 hwinuser.cj 中同时提供了与之配套的两个标志常量：GIDC_ARRIVAL = 1（触控设备到达）与GIDC_REMOVAL = 2（触控设备移除），可用于与dwFlags比对以判断触控设备的变化类型。

hwndTarget：目标窗口句柄

public var hwndTarget: HWND = HWND()

• 类型HWND在 hwindef.cj 中定义为CPointer<UNUSED>，即窗口句柄的指针形式；
• 该字段标识手势通知所指向的目标窗口。

ptsLocation：设备坐标位置

public var ptsLocation: POINTS = POINTS()

• 类型POINTS在 hwindef.cj 中定义为tagPOINTS结构体；
• tagPOINTS 内部包含两个SHORT（Int16）类型的成员x、y，表示屏幕坐标点。值得注意：此处使用POINTS（短整型坐标）而非POINT（长整型坐标），可见该字段用于承载压缩后的位置信息。

dwInstanceID：设备实例标识

public var dwInstanceID: DWORD = 0

• 类型DWORD，即UInt32；
• 该字段标识发起通知的触控输入设备实例 ID，可用于区分多个触控设备。

字段速查表

关于字段顺序与内存布局的一点说明

需要留意：API 参考文档（tagGESTURENOTIFYSTRUCT.md）中字段的罗列顺序为cbSize → dwFlags → dwInstanceID → hwndTarget → ptsLocation，而源码 hwinuser.cj#L1237-L1245 中实际定义的成员顺序为cbSize → dwFlags → hwndTarget → ptsLocation → dwInstanceID。

由于该结构体带有@C注解，其真实内存布局以源码定义顺序为准，该顺序与 Win32 原生GESTURENOTIFYSTRUCT的标准布局保持一致。在通过指针读取（如ptr.read()）或跨 FFI 边界传递时，务必以源码中的成员顺序作为唯一依据，文档罗列顺序仅作字段清单参考。

类型别名与指针类型

除结构体本体外，hwinuser.cj 还提供了两个配套类型别名，也收录在 类型别名.md 与 类型别名.md#L860-L862 中：

public type GESTURENOTIFYSTRUCT = tagGESTURENOTIFYSTRUCT public type PGESTURENOTIFYSTRUCT = CPointer<tagGESTURENOTIFYSTRUCT>

• GESTURENOTIFYSTRUCT：去掉tag前缀的别名，与 Win32 SDK 命名习惯一致，日常使用更简洁；
• PGESTURENOTIFYSTRUCT：指向该结构体的指针类型。由于WM_GESTURENOTIFY的lParam携带的正是结构体指针，该别名在消息解析场景中最为常用。

在 RGF 事件体系中的接入：EvGestureNotify 封装

tagGESTURENOTIFYSTRUCT的价值最终体现在 RGF 的事件体系中。在 rgf_proc.cj#L3259-L3290 中，RGF 将WM_GESTURENOTIFY封装为EvGestureNotify事件类（对应 EvGestureNotify.md），其核心解析逻辑如下：

public open class EvGestureNotify <: EvCore{ public var cbSize:UInt32; public var dwFlags:UInt32; public var hwndTarget:RgfHwnd; public var ptsLocation:Point; public var dwInstanceID:UInt32; internal let ptr:CPointer<GESTURENOTIFYSTRUCT>; internal var Obj:GESTURENOTIFYSTRUCT; @OverflowWrapping public init(wParam:UInt64, lParam:Int64) { super(0x011A /*WM_GESTURENOTIFY*/, wParam,lParam) ptr = CPointer<GESTURENOTIFYSTRUCT>(ruUllToPtr(ruInt64SafeToUIntNative(lParam))) Obj = unsafe{ ptr.read() } // 逐字段拷贝为 RGF 友好的类型 cbSize = Obj.cbSize dwFlags = Obj.dwFlags hwndTarget = Obj.hwndTarget.toUIntNative() ptsLocation = Point(Int32(Obj.ptsLocation.x),Int32(Obj.ptsLocation.y)) dwInstanceID = Obj.dwInstanceID } // postProcess() 反向写回原始结构体（此处略） }

这段实现清晰展示了结构体在框架中的实际用法：

1. 通过CPointer<GESTURENOTIFYSTRUCT>将lParam转换为结构体指针；
2. 用unsafe { ptr.read() }一次性读出原生结构体；
3. 逐字段转换为 RGF 更友好的类型——HWND转为RgfHwnd、POINTS转为Point（同时把SHORT提升为Int32），供上层业务直接使用；
4. 事件类还提供postProcess()方法，将修改后的字段反向写回原始结构体，用于需要回写系统参数的场景。

消息分发：onGestureNotify 与 bindGestureNotify

在 RGF 的消息分发层，WM_GESTURENOTIFY同时接入了两套事件 API：

• 继承式接口：IEvent接口提供onGestureNotify(e: EvGestureNotify): Unit，对应文档 IEvent.md#L714-L719 中标注的“本消息可设置手势配置”；分发实现在 rgf_proc.cj#L5300-L5304；
• 绑定式接口：IBindEvent接口提供bindGestureNotify: Option<(EvGestureNotify) -> Unit>属性，对应 IBindEvent.md#L378-L380，分发实现在 rgf_proc.cj#L7461-L7464。

两条分发路径的源码中都带有同一行关键注释：

// 本消息始终应该从 DefWindowProc 返回值

这意味着WM_GESTURENOTIFY是一个“只读通知 + 配置入口”性质的消息——应用在处理完EvGestureNotify（读取结构体字段、必要时修改配置）后，不应吞掉消息返回值，而是应当返回DefWindowProc的处理结果，让系统继续完成手势相关的默认处理。这也是tagGESTURENOTIFYSTRUCT相比普通消息结构体在使用上最需要注意的约定。

小结

tagGESTURENOTIFYSTRUCT是 RGF 仓颉版对接 Win32 手势触控机制的底层数据契约：它由@C注解保证 ABI 兼容，五个字段分别承担结构体大小、通知标志、目标窗口、设备坐标与设备实例 ID 的传递；配合 hwinuser.cj 中的GESTURENOTIFYSTRUCT/PGESTURENOTIFYSTRUCT别名，以及 rgf_proc.cj 中EvGestureNotify的指针解析与类型转换，开发者可以在不接触裸指针的情况下读取全部字段，并通过onGestureNotify/bindGestureNotify接入自己的窗口逻辑。需要进一步查阅完整定义与关联常量时，可参考 变量与常量.md 中的WM_GESTURENOTIFY说明及 readme.md 的结构体索引。

• 图形学
• 桌面应用