diff --git a/zh-cn/application-dev/reference/apis-arkui/capi-oh-window-h.md b/zh-cn/application-dev/reference/apis-arkui/capi-oh-window-h.md index 049f486688b303b55807a1847c7172fbd9097869..fba565380ce5068793fec67b561266695475973c 100644 --- a/zh-cn/application-dev/reference/apis-arkui/capi-oh-window-h.md +++ b/zh-cn/application-dev/reference/apis-arkui/capi-oh-window-h.md @@ -36,7 +36,7 @@ | [int32_t OH_WindowManager_Snapshot(int32_t windowId, OH_PixelmapNative* pixelMap)](#oh_windowmanager_snapshot) | 获取指定窗口截图。 | | [int32_t OH_WindowManager_GetAllWindowLayoutInfoList(int64_t displayId,WindowManager_Rect** windowLayoutInfoList, size_t* windowLayoutInfoSize)](#oh_windowmanager_getallwindowlayoutinfolist) | 获取指定屏幕上可见的窗口布局信息数组，按当前窗口层级排列，层级最高的对应数组下标为0。 | | [void OH_WindowManager_ReleaseAllWindowLayoutInfoList(WindowManager_Rect* windowLayoutInfoList)](#oh_windowmanager_releaseallwindowlayoutinfolist) | 释放窗口布局信息数组占用的内存。 | -| [int32_t OH_WindowManager_InjectTouchEvent(int32_t windowId, Input_TouchEvent* touchEvent, int32_t windowX, int32_t windowY)](#oh_windowmanager_injecttouchevent) | 将多模触摸事件注入给目标窗口，该注入不会触发窗口焦点和层级变化，直接发送给ArkUI。 | +| [int32_t OH_WindowManager_InjectTouchEvent(int32_t windowId, Input_TouchEvent* touchEvent, int32_t windowX, int32_t windowY)](#oh_windowmanager_injecttouchevent) | 将多模触摸事件注入给目标窗口，仅支持注入同进程窗口，且该注入不会触发窗口焦点和层级变化，不支持窗口拖拽，事件会直接发送给ArkUI。该接口需要在指定窗口loadcontent之后调用。 | ## 函数说明 @@ -461,7 +461,7 @@ int32_t OH_WindowManager_InjectTouchEvent(int32_t windowId, Input_TouchEvent* to **描述** -将多模触摸事件注入给目标窗口，该注入不会触发窗口焦点和层级变化，直接发送给ArkUI。 +将多模触摸事件注入给目标窗口，仅支持注入同进程窗口，且该注入不会触发窗口焦点和层级变化，不支持窗口拖拽，事件会直接发送给ArkUI。该接口需要在指定窗口loadcontent之后调用。 **起始版本：** 20 @@ -470,7 +470,7 @@ int32_t OH_WindowManager_InjectTouchEvent(int32_t windowId, Input_TouchEvent* to | 参数项 | 描述 | | -- | -- | | int32_t windowId | 创建窗口时的窗口id。默认值为0。该参数为整数。 | -| [Input_TouchEvent](../apis-input-kit/capi-input-input-touchevent.md)* touchEvent | 多模触摸事件，具体可见[Input_TouchEvent](../apis-input-kit/capi-input-input-touchevent.md)，事件定义在oh_input_manager.h中。 | +| [Input_TouchEvent](../apis-input-kit/capi-input-input-touchevent.md)* touchEvent | 多模触摸事件，具体可见[Input_TouchEvent](../apis-input-kit/capi-input-input-touchevent.md)，事件定义在oh_input_manager.h中。该参数包含部分字段有参数限制，其中，action应为大于等于0且小于等于3的整数；id,displayX,displayY和actionTime应为不小于0的整数。以上参数不符合限制条件会返回错误码1300003。 | | int32_t windowX | 注入事件相对于注入窗口的落点横坐标。该参数为整数。 | | int32_t windowY | 注入事件相对于注入窗口的落点纵坐标。该参数为整数。 | diff --git a/zh-cn/application-dev/windowmanager/Readme-CN.md b/zh-cn/application-dev/windowmanager/Readme-CN.md index 3d14aca2dc691e167597462ae2d0d8c7d32d5bee..87e626507a563c2899df795adfb9e3fe6486d93b 100644 --- a/zh-cn/application-dev/windowmanager/Readme-CN.md +++ b/zh-cn/application-dev/windowmanager/Readme-CN.md @@ -7,4 +7,5 @@ - [管理系统窗口（仅Stage模型支持）](system-window-stage.md) - [WindowExtensionAbility（仅对系统应用开放）](windowextensionability.md) -- [使用NativeWindowEventFilter过滤多模输入事件（C/C++）](native-window-event-filter.md) \ No newline at end of file +- [使用NativeWindowEventFilter过滤多模输入事件（C/C++）](native-window-event-filter.md) +- [使用OH_WindowManager_InjectTouchEvent将多模触摸事件注入给目标窗口（C/C++）](inject-touch-event.md) \ No newline at end of file diff --git a/zh-cn/application-dev/windowmanager/inject-touch-event.md b/zh-cn/application-dev/windowmanager/inject-touch-event.md new file mode 100644 index 0000000000000000000000000000000000000000..c4fd22ea77b64efba3441c0f3eb354523abb130e --- /dev/null +++ b/zh-cn/application-dev/windowmanager/inject-touch-event.md @@ -0,0 +1,115 @@ +# 使用OH_WindowManager_InjectTouchEvent将多模触摸事件注入给目标窗口（C/C++） + +## 场景介绍 + +开发者可以WindowManager模块提供的能力去将多模触摸事件注入给目标窗口，仅支持注入同进程窗口，且该注入不会触发窗口焦点和层级变化，不支持窗口拖拽，事件会直接发送给ArkUI。该接口需要在指定窗口loadcontent之后调用。 + + +## 接口说明 + +| 接口名 | 描述 | +| -------- | -------- | +| int32_t OH_WindowManager_InjectTouchEvent(int32_t windowId, Input_TouchEvent* touchEvent, int32_t windowX, int32_t windowY) | 为指定的窗口注入触摸事件 | + +## 开发步骤 +### 在CMake脚本中链接动态库 +``` +target_link_libraries(entry PUBLIC libnative_window_manager.so libohinput.so) +``` + +### 添加头文件 +``` +#include "window_manager/oh_window.h" +#include "multimodalinput/oh_input_manager.h" +``` + +### 接口使用说明 +- 应用通过构造相应的事件参数，向绑定的注入窗口ID注入事件。 +- 窗口和多模校验构造事件参数正确性后，才可触发事件注入到ArkUI，具体参数说明如下： + +| 参数名 | 描述 | +| -------- | -------- | +| windowId | 目标窗口ID，限制同进程窗口，否则返回错误码1300002；且该窗口需完成loadcontent，否则返回错误码1300003 | +| touchEvent | 多模触摸事件，具体可见[Input_TouchEvent](../reference/apis-input-kit/capi-input-input-touchevent.md)，事件定义在oh_input_manager.h中。调用OH_Input_CreateTouchEvent()接口可以创建touchevent对象，使用完需要调用OH_Input_DestroyTouchEvent()接口销毁touchevent对象。touchevent包含多个参数，在下表会展开说明 | +| windowX | 注入事件相对于注入窗口的落点横坐标。该参数应为大于等于0的整数，否则返回错误码1300003 | +| windowY | 注入事件相对于注入窗口的落点纵坐标。该参数应为大于等于0的整数，否则返回错误码1300003 | + +- touchEvent多模触摸事件具体参数说明如下： + +| 参数名 | 方法 | 描述 | 默认值 | 限制 | +| -------- | -------- | -------- | -------- | -------- | +| action | OH_Input_SetTouchEventAction(struct Input_TouchEvent* touchEvent, int32_t action) | 事件行为 | 0:cancel | 当前只支持0-3的行为，分别为1:down,2:move,3:up其他行为会返回错误码1300003 | +| id | OH_Input_SetTouchEventFingerId(struct Input_TouchEvent* touchEvent, int32_t id) | 手指ID | 0 | 应为大于等于0的整数，否则返回错误码1300003 | +| displayX | OH_Input_SetTouchEventDisplayX(struct Input_TouchEvent* touchEvent, int32_t displayX) | 相对于屏幕的事件落点横坐标 | 0 | 应为大于等于0的整数，否则返回错误码1300003。其它无限制，但是应该尽量保证与windowX(相对于窗口的事件落点横坐标)有相互对应关系 | +| displayY | OH_Input_SetTouchEventDisplayY(struct Input_TouchEvent* touchEvent, int32_t displayY) | 相对于屏幕的事件落点纵坐标 | 0 | 应为大于等于0的整数，否则返回错误码1300003。其它无限制，但是应该尽量保证与windowY(相对于窗口的事件落点纵坐标)有相互对应关系 | +| actionTime | OH_Input_SetTouchEventActionTime(struct Input_TouchEvent* touchEvent, int64_t actionTime) | 时间戳 | -1 | 应为大于等于0的整数，否则返回错误码1300003 | +| windowId | OH_Input_SetTouchEventWindowId(struct Input_TouchEvent* touchEvent, int32_t windowId) | 事件注入窗口ID | -1 | 若该参数为默认值，则后续赋值为接口参数windowId；若该参数不为默认值且不等于接口参数windowId，校验传入参数错误 | +| displayId | OH_Input_SetTouchEventDisplayId(struct Input_TouchEvent* touchEvent, int32_t displayId) | 事件注入屏幕ID | -1 | 其它无限制，但是应该尽量保证与接口参数windowId有相互对应关系 | +| 其它 | - | - | - | 无 | + +- 仅支持注入同进程窗口，且该注入不会触发窗口焦点和层级变化，不支持窗口拖拽，事件会直接发送给ArkUI。 +- 该接口需要在指定窗口loadcontent之后调用。 + +## 示例代码 +以下示例代码中介绍了如何将多模触摸事件注入给目标窗口，以注入一次事件为例。 +``` +#include "window_manager/oh_window.h" +#include "multimodalinput/oh_input_manager.h" + +static napi_value injectEvent(napi_env env, napi_callback_info info) { + size_t argc = 1; + napi_value args[1] = {nullptr}; + napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); + + int32_t windowId; + napi_get_value_int32(env, args[0], &windowId); + + int32_t displayId; + napi_get_value_int32(env, args[1], &displayId); + + int32_t windowX; + napi_get_value_int32(env, args[2], &windowX); + + int32_t windowY; + napi_get_value_int32(env, args[3], &windowY); + + int32_t action; + napi_get_value_int32(env, args[4], &action); + + int32_t fingerId; + napi_get_value_int32(env, args[5], &fingerId); + + int32_t displayX; + napi_get_value_int32(env, args[6], &displayX); + + int32_t displayY; + napi_get_value_int32(env, args[7], &displayY); + + int32_t actionTime; + napi_get_value_int32(env, args[8], &actionTime); + + int32_t TE_WindowId; + napi_get_value_int32(env, args[9], &TE_WindowId); + + // 构造多模事件touchEvent + Input_TouchEvent* touchEvent = OH_Input_CreateTouchEvent(); + OH_Input_SetTouchEventAction(touchEvent, action); + OH_Input_SetTouchEventFingerId(touchEvent, fingerId); + OH_Input_SetTouchEventDisplayX(touchEvent, displayX); + OH_Input_SetTouchEventDisplayY(touchEvent, displayY); + OH_Input_SetTouchEventActionTime(touchEvent, actionTime); + OH_Input_SetTouchEventWindowId(touchEvent, TE_WindowId); + OH_Input_SetTouchEventDisplayId(touchEvent, displayId); + + // 向windowId对应的窗口注入多模触摸事件 + auto res = OH_WindowManager_InjectTouchEvent(windowId, touchEvent, windowX, windowY); + + // 使用完touchEvent后销毁对象 + OH_Input_DestroyTouchEvent(&touchEvent); + + napi_value errCode; + napi_create_int32(env, res, &errCode); + return errCode; +} + +``` \ No newline at end of file