diff --git a/zh-cn/native_sdk/ace/native_interface_xcomponent.h b/zh-cn/native_sdk/ace/native_interface_xcomponent.h new file mode 100644 index 0000000000000000000000000000000000000000..db373fd701d6241593f209b0ec7187a6f8704774 --- /dev/null +++ b/zh-cn/native_sdk/ace/native_interface_xcomponent.h @@ -0,0 +1,228 @@ +/* + * Copyright (c) 2021-2022 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup OH_NativeXComponent Native XComponent + * @{ + * + * @brief OH_NativeXComponent描述了ArkUI XComponent组件持有的Surface和Touch事件，可用于EGL/OpenGLES和媒体数据输入，并显示在ArkUI XComponent组件上。 + * + * @since 8 + * @version 1.0 + */ + +/** + * @file native_interface_xcomponent.h + * + * @brief API for accessing a Native XComponent. + * + * @since 8 + * @version 1.0 + */ + +#ifndef _NATIVE_INTERFACE_XCOMPONENT_H_ +#define _NATIVE_INTERFACE_XCOMPONENT_H_ + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 接口访问状态码。 + * + * @since 8 + * @version 1.0 + */ +enum { + /** Success result. */ + OH_NATIVEXCOMPONENT_RESULT_SUCCESS = 0, + /** Failed result. */ + OH_NATIVEXCOMPONENT_RESULT_FAILED = -1, + /** Invalid parameters. */ + OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER = -2, +}; + +enum OH_NativeXComponent_TouchEventType { + /** Trigger a touch event when a finger is pressed. */ + OH_NATIVEXCOMPONENT_DOWN = 0, + /** Trigger a touch event when a finger is lifted. */ + OH_NATIVEXCOMPONENT_UP, + /** Trigger a touch event when a finger moves on the screen in pressed state. */ + OH_NATIVEXCOMPONENT_MOVE, + /** Trigger an event when a touch event is canceled. */ + OH_NATIVEXCOMPONENT_CANCEL, + /** Invalid touch type. */ + OH_NATIVEXCOMPONENT_UNKNOWN, +}; + +#define OH_NATIVE_XCOMPONENT_OBJ ("__NATIVE_XCOMPONENT_OBJ__") +const uint32_t OH_XCOMPONENT_ID_LEN_MAX = 128; +const uint32_t OH_MAX_TOUCH_POINTS_NUMBER = 10; + +struct OH_NativeXComponent_TouchPoint { + /** Unique identifier of a finger. */ + int32_t id = 0; + /** X coordinate of the touch point relative to the left edge of the screen. */ + float screenX = 0.0; + /** Y coordinate of the touch point relative to the upper edge of the screen. */ + float screenY = 0.0; + /** X coordinate of the touch point relative to the left edge of the element to touch. */ + float x = 0.0; + /** Y coordinate of the touch point relative to the upper edge of the element to touch. */ + float y = 0.0; + /** Touch type of the touch event. */ + OH_NativeXComponent_TouchEventType type = OH_NativeXComponent_TouchEventType::OH_NATIVEXCOMPONENT_UNKNOWN; + /** 手指和屏幕的接触面积。 */ + double size = 0.0; + /** The current pressure of this touch event. */ + float force = 0.0; + /** 当前Touch事件的时间戳。 */ + long long timeStamp = 0; + /** Checks if the current point is pressed. */ + bool isPressed = false; +}; + +// the active changed point info. +struct OH_NativeXComponent_TouchEvent { + /** Unique identifier of a finger. */ + int32_t id = 0; + /** X coordinate of the touch point relative to the left edge of the screen. */ + float screenX = 0.0; + /** Y coordinate of the touch point relative to the upper edge of the screen. */ + float screenY = 0.0; + /** X coordinate of the touch point relative to the left edge of the element to touch. */ + float x = 0.0; + /** Y coordinate of the touch point relative to the upper edge of the element to touch. */ + float y = 0.0; + /** Touch type of the touch event. */ + OH_NativeXComponent_TouchEventType type = OH_NativeXComponent_TouchEventType::OH_NATIVEXCOMPONENT_UNKNOWN; + /** 手指和屏幕的接触面积。 */ + double size = 0.0; + /** The current pressure of this touch event. */ + float force = 0.0; + /** The ID for the device that the current event came from. */ + int64_t deviceId = 0; + /** 当前Touch事件的时间戳。 */ + long long timeStamp = 0; + /** 当前Touch Pointer集合。 */ + OH_NativeXComponent_TouchPoint touchPoints[OH_MAX_TOUCH_POINTS_NUMBER]; + /** 当前Touch Pointer数量。 */ + uint32_t numPoints = 0; +}; + +/** + * @brief 结构体NativeXComponent, 提供一个封装的OH_NativeXComponent实例对象。 + * + * @since 8 + * @version 1.0 + */ +typedef struct OH_NativeXComponent OH_NativeXComponent; + +/** + * @brief 结构体OH_NativeXComponent_Callback，用于注册Surface生命周期和Touch事件回调。 + * + * @since 8 + * @version 1.0 + */ +typedef struct OH_NativeXComponent_Callback { + /** Called when the surface is created. */ + void (*OnSurfaceCreated)(OH_NativeXComponent* component, void* window); + /** + * Called when the surface is changed.\n + * 本接口在OpenHarmony3.1Release版本仅为接口定义，暂不支持使用。接口将在OpenHarmony3.1MR版本中提供使用支持。\n + */ + void (*OnSurfaceChanged)(OH_NativeXComponent* component, void* window); + /** Called when the surface is destroyed. */ + void (*OnSurfaceDestroyed)(OH_NativeXComponent* component, void* window); + /** Called when touch event is triggered. */ + void (*DispatchTouchEvent)(OH_NativeXComponent* component, void* window); +} OH_NativeXComponent_Callback; + +/** + * @brief 获得ArkUI XComponent组件的ID。 + * + * @param component Indicates the pointer to this OH_NativeXComponent instance. + * @param id Indicates the char buffer to keep the ID of the xcomponent.\n + * Notice that a null-terminator will be append to the char buffer, so the size of the + * char buffer should be at least as large as the size of the real id length plus 1.\n + * The size of the char buffer is recommend to be [OH_XCOMPONENT_ID_LEN_MAX + 1]. + * @param size is an in-out param. + * [in] Indicates the length of the id char buffer (including null-terminator). + * The referenced value of 'size' should be in the range (0, OH_XCOMPONENT_ID_LEN_MAX + 1]. + * [out] Receives the length of the id (not include null-terminator). + * @return 返回接口执行的状态码。 + * @since 8 + * @version 1.0 + */ +int32_t OH_NativeXComponent_GetXComponentId(OH_NativeXComponent* component, char* id, uint64_t* size); + +/** + * @brief 获得ArkUI XComponent组件持有Surface的大小。 + * + * @param component Indicates the pointer to this OH_NativeXComponent instance. + * @param window Indicates the native window handler. + * @param width 表示当前Surface的宽度。 + * @param height 表示当前Surface的高度。 + * @return 返回接口执行的状态码。 + * @since 8 + * @version 1.0 + */ +int32_t OH_NativeXComponent_GetXComponentSize( + OH_NativeXComponent* component, const void* window, uint64_t* width, uint64_t* height); + +/** + * @brief 获得ArkUI XComponent组件持有Surface的偏移量。 + * + * @param component Indicates the pointer to this OH_NativeXComponent instance. + * @param window Indicates the native window handler. + * @param x 表示当前Surface的x坐标。 + * @param y 表示当前Surface的y坐标。 + * @return 返回接口执行的状态码。 + * @since 8 + * @version 1.0 + */ +int32_t OH_NativeXComponent_GetXComponentOffset( + OH_NativeXComponent* component, const void* window, double* x, double* y); + +/** + * @brief 获得ArkUI XComponent组件派发的Touch事件。 + * + * @param component Indicates the pointer to this OH_NativeXComponent instance. + * @param window Indicates the native window handler. + * @param touchEvent 表示当前Touch事件。 + * @return 返回接口执行的状态码。 + * @since 8 + * @version 1.0 + */ +int32_t OH_NativeXComponent_GetTouchEvent( + OH_NativeXComponent* component, const void* window, OH_NativeXComponent_TouchEvent* touchEvent); + +/** + * @brief 提供OH_NativeXComponent回调注册接口。 + * + * @param component Indicates the pointer to this OH_NativeXComponent instance. + * @param callback 表示Surface生命周期和Touch事件回调实现。 + * @return 返回接口执行的状态码。 + * @since 8 + * @version 1.0 + */ +int32_t OH_NativeXComponent_RegisterCallback(OH_NativeXComponent* component, OH_NativeXComponent_Callback* callback); + +#ifdef __cplusplus +}; +#endif +#endif // _NATIVE_INTERFACE_XCOMPONENT_H_