From e76b082d1836dc9eecc7d124d031b19c2ff19e70 Mon Sep 17 00:00:00 2001 From: "DESKTOP-H8KLN8I\\lisitao" Date: Sun, 24 Mar 2024 11:34:33 +0800 Subject: [PATCH 1/2] [NDK] custom node interfaces Signed-off-by:lisitaolisitao3@huawei.com Signed-off-by: DESKTOP-H8KLN8I\lisitao --- arkui/ace_engine/native/native_node.h | 298 ++++++++++++++++++++++++-- arkui/ace_engine/native/native_type.h | 191 +++++++++++++++++ 2 files changed, 473 insertions(+), 16 deletions(-) diff --git a/arkui/ace_engine/native/native_node.h b/arkui/ace_engine/native/native_node.h index 05ca6d7ba..9bba40171 100644 --- a/arkui/ace_engine/native/native_node.h +++ b/arkui/ace_engine/native/native_node.h @@ -951,7 +951,7 @@ typedef enum { * Format of the {@link ArkUI_AttributeItem} parameter for setting the attribute, which supports five types of * shapes:\n * 1. Rectangle:\n - * .value[0].u32: fill color, in 0xARGB format. \n + * .value[0].u32 fill color, in 0xARGB format. \n * .value[1].u32: stroke color, in 0xARGB format. \n * .value[2].f32: stroke width, in vp. \n * .value[3].i32: mask type. The parameter type is {@link ArkUI_MaskType}. @@ -968,12 +968,12 @@ typedef enum { * The value is ARKUI_MASK_TYPE_CIRCLE for the circle shape.\n * .value[4].f32: width of the circle.\n * .value[5].f32: height of the circle.\n - * 3.Ellipse:\n + * 3. Ellipse:\n * .value[0].u32 fill color, in 0xARGB format. \n * .value[1].u32: stroke color, in 0xARGB format. \n * .value[2].f32: stroke width, in vp. \n - * .value[3].i32: mask type. The parameter type is {@link ArkUI_MaskType}. - * The value is ARKUI_MASK_TYPE_ELLIPSE for the ellipse shape.\n + * .value[3].i32: mask type. The parameter type is {@link ArkUI_MaskType}. + * The value is ARKUI_MASK_TYPE_ELLIPSE for the ellipse shape.\n * .value[4].f32: width of the ellipse.\n * .value[5].f32: height of the ellipse.\n * 4. Path:\n @@ -986,14 +986,11 @@ typedef enum { * .value[5].f32: height of the path.\n * .string: command for drawing the path.\n * 5. Progress:\n - * .value[0].u32 fill color, in 0xARGB format. \n - * .value[1].u32: stroke color, in 0xARGB format. \n - * .value[2].f32: stroke width, in vp. \n - * .value[3].i32: mask type. The parameter type is {@link ArkUI_MaskType}. + * .value[0].i32: mask type. The parameter type is {@link ArkUI_MaskType}. * The value is ARKUI_MASK_TYPE_PROSGRESS for the progress shape.\n - * .value[4].f32: current value of the progress indicator.\n - * .value[5].f32: maximum value of the progress indicator.\n - * .value[6].u32: color of the progress indicator.\n + * .value[1].f32: current value of the progress indicator.\n + * .value[2].f32: maximum value of the progress indicator.\n + * .value[3].u32: color of the progress indicator.\n * \n * Format of the return value {@link ArkUI_AttributeItem}, which supports five types of shapes:\n * 1. Rectangle:\n @@ -1012,14 +1009,14 @@ typedef enum { * .value[3].i32: mask type.\n * .value[4].f32: width of the circle.\n * .value[5].f32: height of the circle.\n - * 3.Ellipse:\n + * 3. Ellipse:\n * .value[0].u32 fill color, in 0xARGB format. \n * .value[1].u32: stroke color, in 0xARGB format. \n * .value[2].f32: stroke width, in vp. \n * .value[3].i32: mask type.\n * .value[4].f32: width of the ellipse.\n * .value[5].f32: height of the ellipse.\n - * 5. Path:\n + * 4. Path:\n * .value[0].u32 fill color, in 0xARGB format. \n * .value[1].u32: stroke color, in 0xARGB format. \n * .value[2].f32: stroke width, in vp. \n @@ -1027,7 +1024,7 @@ typedef enum { * .value[4].f32: width of the path.\n * .value[5].f32: height of the path.\n * .string: command for drawing the path.\n - * 4. Progress:\n + * 5. Progress:\n * .value[0].i32: mask type.\n * .value[1].f32: current value of the progress indicator.\n * .value[2].f32: maximum value of the progress indicator.\n @@ -1764,11 +1761,11 @@ typedef enum { * This attribute can be set, reset, and obtained as required through APIs. * * Format of the {@link ArkUI_AttributeItem} parameter for setting the attribute:\n - * .value[0].i32 to .value[19].i32: filter matrix array. \n + * .value[0].f32 to .value[19].f32: filter matrix array. \n * .size: 5 x 4 filter array size. \n * \n * Format of the return value {@link ArkUI_AttributeItem}:\n - * .value[0].i32 to .value[19].i32: filter matrix array. \n + * .value[0].f32 to .value[19].f32: filter matrix array. \n * .size: 5 x 4 filter array size. \n * */ @@ -4194,6 +4191,31 @@ typedef enum { NODE_NEED_RENDER, } ArkUI_NodeDirtyFlag; +/** + * @brief defines custom component event types. + * + * @since 12 + */ +typedef enum { + /** measure type. */ + ARKUI_NODE_CUSTOM_EVENT_ON_MEASURE = 1 << 0, + /** layout type. */ + ARKUI_NODE_CUSTOM_EVENT_ON_LAYOUT = 1 << 1, + /** draw type. */ + ARKUI_NODE_CUSTOM_EVENT_ON_DRAW = 1 << 2, + /** foreground type. */ + ARKUI_NODE_CUSTOM_EVENT_ON_FOREGROUND_DRAW = 1 << 3, + /** overlay type. */ + ARKUI_NODE_CUSTOM_EVENT_ON_OVERLAY_DRAW = 1 << 4, +} ArkUI_NodeCustomEventType; + +/** + * @brief defines the general structure type of custom component events. + * + * @since 12 + */ +struct ArkUI_NodeCustomEvent; + /** * @brief Declares a collection of native node APIs provided by ArkUI. * @@ -4381,8 +4403,252 @@ typedef struct { * @param dirtyFlag Indicates type of dirty area. */ void (*markDirty)(ArkUI_NodeHandle node, ArkUI_NodeDirtyFlag dirtyFlag); + + /** + * @brief Get the number of child nodes. + * + * When the component has been mounted and displayed on the window, it must be called on the main thread. + * + * @param node target node object. + * @return 0 - success. + * 401 - Function parameter exception. + */ + uint32_t (*getTotalChildCount)(ArkUI_NodeHandle node); + + /** + * @brief Get child nodes. + * + * When the component has been mounted and displayed on the window, it must be called on the main thread. + * + * @param node target node object. + * @param position The position of the subcomponent. + * @return Returns the pointer of the component, if not return NULL + */ + ArkUI_NodeHandle (*getChildAt)(ArkUI_NodeHandle node, int32_t position); + + /** + * @brief Get the first child node. + * + * When the component has been mounted and displayed on the window, it must be called on the main thread. + * + * @param node target node object. + * @return Returns the pointer of the component, if not return NULL + */ + ArkUI_NodeHandle (*getFirstChild)(ArkUI_NodeHandle node); + + /** + * @brief Get the last child node. + * + * When the component has been mounted and displayed on the window, it must be called on the main thread. + * + * @param node target node object. + * @return Returns the pointer of the component, if not return NULL + */ + ArkUI_NodeHandle (*getLastChild)(ArkUI_NodeHandle node); + + /** + * @brief Get the previous sibling node. + * + * When the component has been mounted and displayed on the window, it must be called on the main thread. + * + * @param node target node object. + * @return Returns the pointer of the component, if not return NULL + */ + ArkUI_NodeHandle (*getPreviousSibling)(ArkUI_NodeHandle node); + + /** + * @brief Get the next sibling node. + * + * When the component has been mounted and displayed on the window, it must be called on the main thread. + * + * @param node target node object. + * @return Returns the pointer of the component, if not return NULL + */ + ArkUI_NodeHandle (*getNextSibling)(ArkUI_NodeHandle node); + + /** + * @brief Register custom node event function. When the event is triggered, + * it is returned through the custom event entry function registered with registerNodeCustomEventReceiver. + * + * When the component has been mounted and displayed on the window, it must be called on the main thread. + * + * @param node The node object that needs to register the event. + * @param eventType The event type that needs to be registered. + * @param targetId Custom event ID, carried back in the callback parameter + * <@link ArkUI_NodeCustomEvent> when the event is triggered. + * @param userData Custom event parameters, which are carried back in the callback parameter + * <@link ArkUI_NodeCustomEvent> when the event is triggered. + * @return 0 - success. + * 401 - Function parameter exception. + * 106102 - The dynamic implementation library of the Native interface was not found in the system. + */ + int32_t (*registerNodeCustomEvent)( + ArkUI_NodeHandle node, ArkUI_NodeCustomEventType eventType, int32_t targetId, void* userData); + + /** + * @brief Unregister custom node event function. + * + * When the component has been mounted and displayed on the window, it must be called on the main thread. + * + * @param node The node object that needs to unregister the event. + * @param eventType The event type that needs to be deregistered. + */ + void (*unregisterNodeCustomEvent)(ArkUI_NodeHandle node, ArkUI_NodeCustomEventType eventType); + + /** + * @brief Register a custom node event callback unified entry function. + * + * The ArkUI framework will uniformly collect custom component events generated during the + * process and call back to the developer through the registered registerNodeCustomEventReceiver function. \n + * When called repeatedly, the previously registered function will be overwritten. + * + * @param eventReceiver Event callback unified entry function. + */ + void (*registerNodeCustomEventReceiver)(void (*eventReceiver)(ArkUI_NodeCustomEvent* event)); + + /** + * @brief Unregister custom node event callback unified entry function. + * + * When the component has been mounted and displayed on the window, it must be called on the main thread. + * + */ + void (*unregisterNodeCustomEventReceiver)(); + + /** + * @brief Set the width and height of the component after the calculation is completed in the calculation callback function. + * + * When the component has been mounted and displayed on the window, it must be called on the main thread. + * + * @param node target node object. + * @param width The width set. + * @param height The height set. + * @return 0 - success. + * 401 - Function parameter exception. + */ + int32_t (*setMeasuredSize)(ArkUI_NodeHandle node, int32_t width, int32_t height); + + /** + * @brief Set the position of the component in the layout callback function. + * + * When the component has been mounted and displayed on the window, it must be called on the main thread. + * + * @param node target node object. + * @param positionX x-axis coordinate. + * @param positionY y-axis coordinate. + * @return 0 - success. + * 401 - Function parameter exception. + */ + int32_t (*setLayoutPosition)(ArkUI_NodeHandle node, int32_t positionX, int32_t positionY); + + /** + * @brief Get the width and height dimensions of the component after calculation is completed. + * + * When the component has been mounted and displayed on the window, it must be called on the main thread. + * + * @param node target node object. + * @return ArkUI_IntSize The width and height of the component. + */ + ArkUI_IntSize (*getMeasuredSize)(ArkUI_NodeHandle node); + + /** + * @brief Gets the position of the component after layout is completed. + * + * When the component has been mounted and displayed on the window, it must be called on the main thread. + * + * @param node target node object. + * @return ArkUI_IntOffset The position of the component. + */ + ArkUI_IntOffset (*getLayoutPosition)(ArkUI_NodeHandle node); + + /** + * @brief To measure a specific component, you can obtain the calculated size through the getMeasuredSize interface. + * + * When the component has been mounted and displayed on the window, it must be called on the main thread. + * + * @param node target node object. + * @param Constraint constraint size. + * @return 0 - success. + * 401 - Function parameter exception. + */ + int32_t (*measureNode)(ArkUI_NodeHandle node, ArkUI_LayoutConstraint* Constraint); + + /** + * @brief Lays out a specific component and passes the component's desired position relative to its parent component. + * + * When the component has been mounted and displayed on the window, it must be called on the main thread. + * + * @param node target node object. + * @param positionX x-axis coordinate. + * @param positionY y-axis coordinate. + * @return 0 - success. + * 401 - Function parameter exception. + */ + int32_t (*layoutNode)(ArkUI_NodeHandle node, int32_t positionX, int32_t positionY); } ArkUI_NativeNodeAPI_1; +/** +* @brief Obtain the constrained size during the measurement process through custom component events. +* +* @param event Custom component event. +* @return Constraint size pointer. +* @since 12 +*/ +ArkUI_LayoutConstraint* OH_ArkUI_NodeCustomEvent_GetLayoutConstraintInMeasure(ArkUI_NodeCustomEvent* event); + +/** +* @brief Obtains the desired position relative to the parent component during the layout phase through custom component events. +* +* @param event Custom component event. +* @return Expected position relative to parent component. +* @since 12 +*/ +ArkUI_IntOffset OH_ArkUI_NodeCustomEvent_GetPositionInLayout(ArkUI_NodeCustomEvent* event); + +/** +* @brief Get the drawing context through custom component events. +* +* @param event Custom component event. +* @return drawing context. +* @since 12 +*/ +ArkUI_DrawContext* OH_ArkUI_NodeCustomEvent_GetDrawContextInDraw(ArkUI_NodeCustomEvent* event); + +/** +* @brief Get the custom event ID through the custom component event. +* +* @param event Custom component event. +* @return Custom event ID. +* @since 12 +*/ +int32_t OH_ArkUI_NodeCustomEvent_GetEventTargetId(ArkUI_NodeCustomEvent* event); + +/** +* @brief Get custom event parameters through custom component events. +* +* @param event Custom component event. +* @return Custom event parameters. +* @since 12 +*/ +void* OH_ArkUI_NodeCustomEvent_GetUserData(ArkUI_NodeCustomEvent* event); + +/** +* @brief Get the component object through custom component events. +* +* @param event Custom component event. +* @return component object. +* @since 12 +*/ +ArkUI_NodeHandle OH_ArkUI_NodeCustomEvent_GetNodeHandle(ArkUI_NodeCustomEvent* event); + +/** +* @brief Get the event type through custom component events. +* +* @param event Custom component event. +* @return component custom event type. +* @since 12 +*/ +ArkUI_NodeCustomEventType OH_ArkUI_NodeCustomEvent_GetEventType(ArkUI_NodeCustomEvent* event); + #ifdef __cplusplus }; #endif diff --git a/arkui/ace_engine/native/native_type.h b/arkui/ace_engine/native/native_type.h index cb57b5382..5f590aef7 100644 --- a/arkui/ace_engine/native/native_type.h +++ b/arkui/ace_engine/native/native_type.h @@ -56,6 +56,20 @@ struct ArkUI_Node; */ struct ArkUI_NativeDialog; +/** + * @brief constrains the size and limits the size range during component layout. + * + * @since 12 + */ +struct ArkUI_LayoutConstraint; + +/** + * @brief defines the component drawing context type structure. + * + * @since 12 + */ +struct ArkUI_DrawContext; + /** * @brief Defines the pointer to the ArkUI native component object. * @@ -1231,6 +1245,8 @@ typedef enum { ARKUI_LINEAR_GRADIENT_DIRECTION_RIGHT_BOTTOM, /** No gradient. */ ARKUI_LINEAR_GRADIENT_DIRECTION_NONE, + /** Customize the gradient direction. */ + ARKUI_LINEAR_GRADIENT_DIRECTION_CUSTOM, } ArkUI_LinearGradientDirection; /** @@ -1309,6 +1325,181 @@ typedef struct { float height; } ArkUI_Rect; +/** + * @brief Dimension type, used to describe the width and height of the component. + * + * @since 12。 + */ +typedef struct { + /** Width, unit is px. */ + int32_t width; + /** Height, unit is px. */ + int32_t height; +} ArkUI_IntSize; + +/** + * @brief location, used to describe the location of the component. + * + * @since 12. + */ +typedef struct { + /** Horizontal abscissa, unit is px. */ + int32_t x; + /** Vertical ordinate, unit is px. */ + int32_t y; +} ArkUI_IntOffset; + +/** +* @brief Create constrained dimensions. +* +* @since 12 +*/ +ArkUI_LayoutConstraint* OH_ArkUI_LayoutConstraint_Create(); + +/** +* @brief Constraint size deep copy. +* +* @param Constraint constraint size. +* @return new constraint size pointer. +* @since 12 +*/ +ArkUI_LayoutConstraint* OH_ArkUI_LayoutConstraint_Copy(const ArkUI_LayoutConstraint* Constraint); + +/** +* @brief Destroy the constraint size pointer. +* +* @param Constraint constraint size. +* @since 12 +*/ +void* OH_ArkUI_LayoutConstraint_Dispose(ArkUI_LayoutConstraint* Constraint); + +/** +* @brief Get the maximum width through constraint size, in px. +* +* @param Constraint constraint size. +* @return maximum width. +* @since 12 +*/ +int32_t OH_ArkUI_LayoutConstraint_GetMaxWidth(const ArkUI_LayoutConstraint* Constraint); + +/** +* @brief Get the minimum width through constraint size, in px. +* +* @param Constraint constraint size. +* @return minimum width. +* @since 12 +*/ +int32_t OH_ArkUI_LayoutConstraint_GetMinWidth(const ArkUI_LayoutConstraint* Constraint); + +/** +* @brief Get the maximum height through constraint size, in px. +* +* @param Constraint constraint size. +* @return maximum width. +* @since 12 +*/ +int32_t OH_ArkUI_LayoutConstraint_GetMaxHeight(const ArkUI_LayoutConstraint* Constraint); + +/** +* @brief Get the minimum height through constraint size, in px. +* +* @param Constraint constraint size. +* @return maximum width. +* @since 12 +*/ +int32_t OH_ArkUI_LayoutConstraint_GetMinHeight(const ArkUI_LayoutConstraint* Constraint); + +/** +* @brief Get the width percentage base through the constraint size, in px. +* +* @param Constraint constraint size. +* @return Width percentage base. +* @since 12 +*/ +int32_t OH_ArkUI_LayoutConstraint_GetPercentReferenceWidth(const ArkUI_LayoutConstraint* Constraint); + +/** +* @brief Get the height percentage base through the constraint size, in px. +* +* @param Constraint constraint size. +* @return height percentage base. +* @since 12 +*/ +int32_t OH_ArkUI_LayoutConstraint_GetPercentReferenceHeight(const ArkUI_LayoutConstraint* Constraint); + +/** +* @brief Set the maximum width. +* +* @param Constraint constraint size. +* @param value Maximum width, unit is px. +* @since 12 +*/ +void OH_ArkUI_LayoutConstraint_SetMaxWidth(ArkUI_LayoutConstraint* Constraint, int32_t value); + +/** +* @brief Set the minimum width. +* +* @param Constraint constraint size. +* @param value Minimum width, unit is px. +* @since 12 +*/ +void OH_ArkUI_LayoutConstraint_SetMinWidth(ArkUI_LayoutConstraint* Constraint, int32_t value); + +/** +* @brief Set the maximum height. +* +* @param Constraint constraint size. +* @param value Maximum height, unit is px. +* @since 12 +*/ +void OH_ArkUI_LayoutConstraint_SetMaxHeight(ArkUI_LayoutConstraint* Constraint, int32_t value); + +/** +* @brief Set the minimum height. +* +* @param Constraint constraint size. +* @param value Minimum height, unit is px. +* @since 12 +*/ +void OH_ArkUI_LayoutConstraint_SetMinHeight(ArkUI_LayoutConstraint* Constraint, int32_t value); + +/** +* @brief Set the width percentage base. +* +* @param Constraint constraint size. +* @param value Width percentage base, unit is px. +* @since 12 +*/ +void OH_ArkUI_LayoutConstraint_SetPercentReferenceWidth(ArkUI_LayoutConstraint* Constraint, int32_t value); + +/** +* @brief Set height percentage base. +* +* @param Constraint constraint size. +* @param value Height percentage reference, unit is px. +* @since 12 +*/ +void OH_ArkUI_LayoutConstraint_SetPercentReferenceHeight(ArkUI_LayoutConstraint* Constraint, int32_t value); + +/** +* @brief Gets the drawing canvas pointer, which can be converted to the +* OH_Drawing_Canvas pointer of the graphics library for drawing. +* +* @param context drawing context. +* @return Canvas pointer used for drawing. +* @since 12 +*/ +void* OH_ArkUI_DrawContext_GetCanvas(ArkUI_DrawContext* context); + +/** +* @brief Get the size of the drawable area. +* +* @param context drawing context. +* @return drawable area size. +* @since 12 +*/ +ArkUI_IntSize OH_ArkUI_DrawContext_GetSize(ArkUI_DrawContext* context); + #ifdef __cplusplus }; #endif -- Gitee From 3235cb53c847ebceac7ab45c091c3b93628953c6 Mon Sep 17 00:00:00 2001 From: "DESKTOP-H8KLN8I\\lisitao" Date: Sun, 24 Mar 2024 11:41:21 +0800 Subject: [PATCH 2/2] [NDK] custom node interfaces Signed-off-by:lisitaolisitao3@huawei.com Signed-off-by: DESKTOP-H8KLN8I\lisitao --- arkui/ace_engine/native/native_node.h | 438 +++++++++++++------------- arkui/ace_engine/native/native_type.h | 146 ++++----- 2 files changed, 293 insertions(+), 291 deletions(-) diff --git a/arkui/ace_engine/native/native_node.h b/arkui/ace_engine/native/native_node.h index 9bba40171..01469c964 100644 --- a/arkui/ace_engine/native/native_node.h +++ b/arkui/ace_engine/native/native_node.h @@ -4192,29 +4192,29 @@ typedef enum { } ArkUI_NodeDirtyFlag; /** - * @brief defines custom component event types. - * - * @since 12 - */ + * @brief Defines the custom component event type. + * + * @since 12 + */ typedef enum { - /** measure type. */ - ARKUI_NODE_CUSTOM_EVENT_ON_MEASURE = 1 << 0, - /** layout type. */ - ARKUI_NODE_CUSTOM_EVENT_ON_LAYOUT = 1 << 1, - /** draw type. */ - ARKUI_NODE_CUSTOM_EVENT_ON_DRAW = 1 << 2, - /** foreground type. */ - ARKUI_NODE_CUSTOM_EVENT_ON_FOREGROUND_DRAW = 1 << 3, - /** overlay type. */ - ARKUI_NODE_CUSTOM_EVENT_ON_OVERLAY_DRAW = 1 << 4, + /** Measure type. */ + ARKUI_NODE_CUSTOM_EVENT_ON_MEASURE = 1 << 0, + /** Layout type. */ + ARKUI_NODE_CUSTOM_EVENT_ON_LAYOUT = 1 << 1, + /** Draw type. */ + ARKUI_NODE_CUSTOM_EVENT_ON_DRAW = 1 << 2, + /** Foreground type. */ + ARKUI_NODE_CUSTOM_EVENT_ON_FOREGROUND_DRAW = 1 << 3, + /** Overlay type. */ + ARKUI_NODE_CUSTOM_EVENT_ON_OVERLAY_DRAW = 1 << 4, } ArkUI_NodeCustomEventType; /** - * @brief defines the general structure type of custom component events. - * - * @since 12 - */ -struct ArkUI_NodeCustomEvent; + * @brief Defines the general structure of a custom component event. + * + * @since 12 + */ +typedef struct ArkUI_NodeCustomEvent ArkUI_NodeCustomEvent; /** * @brief Declares a collection of native node APIs provided by ArkUI. @@ -4405,246 +4405,248 @@ typedef struct { void (*markDirty)(ArkUI_NodeHandle node, ArkUI_NodeDirtyFlag dirtyFlag); /** - * @brief Get the number of child nodes. - * - * When the component has been mounted and displayed on the window, it must be called on the main thread. - * - * @param node target node object. - * @return 0 - success. - * 401 - Function parameter exception. - */ - uint32_t (*getTotalChildCount)(ArkUI_NodeHandle node); - - /** - * @brief Get child nodes. - * - * When the component has been mounted and displayed on the window, it must be called on the main thread. - * - * @param node target node object. - * @param position The position of the subcomponent. - * @return Returns the pointer of the component, if not return NULL - */ - ArkUI_NodeHandle (*getChildAt)(ArkUI_NodeHandle node, int32_t position); - - /** - * @brief Get the first child node. - * - * When the component has been mounted and displayed on the window, it must be called on the main thread. - * - * @param node target node object. - * @return Returns the pointer of the component, if not return NULL - */ - ArkUI_NodeHandle (*getFirstChild)(ArkUI_NodeHandle node); - - /** - * @brief Get the last child node. - * - * When the component has been mounted and displayed on the window, it must be called on the main thread. - * - * @param node target node object. - * @return Returns the pointer of the component, if not return NULL - */ - ArkUI_NodeHandle (*getLastChild)(ArkUI_NodeHandle node); - - /** - * @brief Get the previous sibling node. - * - * When the component has been mounted and displayed on the window, it must be called on the main thread. - * - * @param node target node object. - * @return Returns the pointer of the component, if not return NULL - */ - ArkUI_NodeHandle (*getPreviousSibling)(ArkUI_NodeHandle node); - - /** - * @brief Get the next sibling node. - * - * When the component has been mounted and displayed on the window, it must be called on the main thread. - * - * @param node target node object. - * @return Returns the pointer of the component, if not return NULL - */ - ArkUI_NodeHandle (*getNextSibling)(ArkUI_NodeHandle node); - - /** - * @brief Register custom node event function. When the event is triggered, - * it is returned through the custom event entry function registered with registerNodeCustomEventReceiver. - * - * When the component has been mounted and displayed on the window, it must be called on the main thread. - * - * @param node The node object that needs to register the event. - * @param eventType The event type that needs to be registered. - * @param targetId Custom event ID, carried back in the callback parameter - * <@link ArkUI_NodeCustomEvent> when the event is triggered. - * @param userData Custom event parameters, which are carried back in the callback parameter - * <@link ArkUI_NodeCustomEvent> when the event is triggered. - * @return 0 - success. - * 401 - Function parameter exception. - * 106102 - The dynamic implementation library of the Native interface was not found in the system. - */ - int32_t (*registerNodeCustomEvent)( - ArkUI_NodeHandle node, ArkUI_NodeCustomEventType eventType, int32_t targetId, void* userData); - - /** - * @brief Unregister custom node event function. - * - * When the component has been mounted and displayed on the window, it must be called on the main thread. - * - * @param node The node object that needs to unregister the event. - * @param eventType The event type that needs to be deregistered. - */ - void (*unregisterNodeCustomEvent)(ArkUI_NodeHandle node, ArkUI_NodeCustomEventType eventType); - - /** - * @brief Register a custom node event callback unified entry function. - * - * The ArkUI framework will uniformly collect custom component events generated during the - * process and call back to the developer through the registered registerNodeCustomEventReceiver function. \n - * When called repeatedly, the previously registered function will be overwritten. - * - * @param eventReceiver Event callback unified entry function. - */ - void (*registerNodeCustomEventReceiver)(void (*eventReceiver)(ArkUI_NodeCustomEvent* event)); - - /** - * @brief Unregister custom node event callback unified entry function. - * - * When the component has been mounted and displayed on the window, it must be called on the main thread. - * - */ - void (*unregisterNodeCustomEventReceiver)(); - - /** - * @brief Set the width and height of the component after the calculation is completed in the calculation callback function. - * - * When the component has been mounted and displayed on the window, it must be called on the main thread. - * - * @param node target node object. - * @param width The width set. - * @param height The height set. - * @return 0 - success. - * 401 - Function parameter exception. - */ - int32_t (*setMeasuredSize)(ArkUI_NodeHandle node, int32_t width, int32_t height); - - /** - * @brief Set the position of the component in the layout callback function. - * - * When the component has been mounted and displayed on the window, it must be called on the main thread. - * - * @param node target node object. - * @param positionX x-axis coordinate. - * @param positionY y-axis coordinate. - * @return 0 - success. - * 401 - Function parameter exception. - */ - int32_t (*setLayoutPosition)(ArkUI_NodeHandle node, int32_t positionX, int32_t positionY); + * @brief Obtains the number of subnodes. + * + * When the component is being displayed, this API must be called in the main thread. + * + * @param node Indicates the target node. + * @return Returns 0 if success. + * Returns 401 if a parameter exception occurs. + */ + uint32_t (*getTotalChildCount)(ArkUI_NodeHandle node); + + /** + * @brief Obtains a subnode. + * + * When the component is being displayed, this API must be called in the main thread. + * + * @param node Indicates the target node. + * @param position Indicates the position of the subnode. + * @return Returns the pointer to the subnode if the subnode exists; returns NULL otherwise. + */ + ArkUI_NodeHandle (*getChildAt)(ArkUI_NodeHandle node, int32_t position); + + /** + * @brief Obtains the first subnode. + * + * When the component is being displayed, this API must be called in the main thread. + * + * @param node Indicates the target node. + * @return Returns the pointer to the subnode if the subnode exists; returns NULL otherwise. + */ + ArkUI_NodeHandle (*getFirstChild)(ArkUI_NodeHandle node); + + /** + * @brief Obtains the last subnode. + * + * When the component is being displayed, this API must be called in the main thread. + * + * @param node Indicates the target node. + * @return Returns the pointer to the subnode if the subnode exists; returns NULL otherwise. + */ + ArkUI_NodeHandle (*getLastChild)(ArkUI_NodeHandle node); + + /** + * @brief Obtains the previous sibling node. + * + * When the component is being displayed, this API must be called in the main thread. + * + * @param node Indicates the target node. + * @return Returns the pointer to the sibling node if the node exists; returns NULL otherwise. + */ + ArkUI_NodeHandle (*getPreviousSibling)(ArkUI_NodeHandle node); + + /** + * @brief Obtains the next sibling node. + * + * When the component is being displayed, this API must be called in the main thread. + * + * @param node Indicates the target node. + * @return Returns the pointer to the sibling node if the node exists; returns NULL otherwise. + */ + ArkUI_NodeHandle (*getNextSibling)(ArkUI_NodeHandle node); + + /** + * @brief Registers a custom event for a node. When the event is triggered, the value is returned through the entry + * function registered by registerNodeCustomEventReceiver. + * + * When the component is being displayed, this API must be called in the main thread. + * + * @param node Indicates the target node. + * @param eventType Indicates the type of event to register. + * @param targetId Indicates the custom event ID, which is passed in the callback of <@link ArkUI_NodeCustomEvent> + * when the event is triggered. + * @param userData Indicates the custom event parameter, which is passed in the callback of + * <@link ArkUI_NodeCustomEvent> when the event is triggered. + * @return Returns 0 if success. + * Returns 401 if a parameter exception occurs. + * Returns 106102 if the dynamic implementation library of the native API was not found. + */ + int32_t (*registerNodeCustomEvent)( + ArkUI_NodeHandle node, ArkUI_NodeCustomEventType eventType, int32_t targetId, void* userData); + + /** + * @brief Unregisters a custom event for a node. + * + * When the component is being displayed, this API must be called in the main thread. + * + * @param node Indicates the target node. + * @param eventType Indicates the type of event to unregister. + */ + void (*unregisterNodeCustomEvent)(ArkUI_NodeHandle node, ArkUI_NodeCustomEventType eventType); + + /** + * @brief Registers a unified entry function for custom node event callbacks. + * + * The ArkUI framework collects custom component events generated during the process and calls back the events + * through the registered registerNodeCustomEventReceiver. \n + * A new call to this API will overwrite the previously registered event receiver. + * + * @param eventReceiver Indicates the event receiver to register. + */ + void (*registerNodeCustomEventReceiver)(void (*eventReceiver)(ArkUI_NodeCustomEvent* event)); + + /** + * @brief Unregisters the unified entry function for custom node event callbacks. + * + * When the component is being displayed, this API must be called in the main thread. + * + */ + void (*unregisterNodeCustomEventReceiver)(); + + /** + * @brief Sets the width and height for a component after the measurement. + * + * When the component is being displayed, this API must be called in the main thread. + * + * @param node Indicates the target node. + * @param width Indicates the width. + * @param height Indicates the height. + * @return Returns 0 if success. + * Returns 401 if a parameter exception occurs. + */ + int32_t (*setMeasuredSize)(ArkUI_NodeHandle node, int32_t width, int32_t height); + + /** + * @brief Sets the position for a component.. + * + * When the component is being displayed, this API must be called in the main thread. + * + * @param node Indicates the target node. + * @param positionX Indicates the X coordinate. + * @param positionY Indicates the Y coordinate. + * @return Returns 0 if success. + * Returns 401 if a parameter exception occurs. + */ + int32_t (*setLayoutPosition)(ArkUI_NodeHandle node, int32_t positionX, int32_t positionY); - /** - * @brief Get the width and height dimensions of the component after calculation is completed. - * - * When the component has been mounted and displayed on the window, it must be called on the main thread. - * - * @param node target node object. - * @return ArkUI_IntSize The width and height of the component. - */ - ArkUI_IntSize (*getMeasuredSize)(ArkUI_NodeHandle node); - - /** - * @brief Gets the position of the component after layout is completed. - * - * When the component has been mounted and displayed on the window, it must be called on the main thread. - * - * @param node target node object. - * @return ArkUI_IntOffset The position of the component. - */ - ArkUI_IntOffset (*getLayoutPosition)(ArkUI_NodeHandle node); - - /** - * @brief To measure a specific component, you can obtain the calculated size through the getMeasuredSize interface. - * - * When the component has been mounted and displayed on the window, it must be called on the main thread. - * - * @param node target node object. - * @param Constraint constraint size. - * @return 0 - success. - * 401 - Function parameter exception. - */ - int32_t (*measureNode)(ArkUI_NodeHandle node, ArkUI_LayoutConstraint* Constraint); - - /** - * @brief Lays out a specific component and passes the component's desired position relative to its parent component. - * - * When the component has been mounted and displayed on the window, it must be called on the main thread. - * - * @param node target node object. - * @param positionX x-axis coordinate. - * @param positionY y-axis coordinate. - * @return 0 - success. - * 401 - Function parameter exception. - */ - int32_t (*layoutNode)(ArkUI_NodeHandle node, int32_t positionX, int32_t positionY); + /** + * @brief Obtains the width and height of a component after measurement. + * + * When the component is being displayed, this API must be called in the main thread. + * + * @param node Indicates the target node. + * @return Returns the width and height of the component. + */ + ArkUI_IntSize (*getMeasuredSize)(ArkUI_NodeHandle node); + + /** + * @brief Obtains the position of a component after the layout is complete. + * + * When the component is being displayed, this API must be called in the main thread. + * + * @param node Indicates the target node. + * @return Returns the position of the component. + */ + ArkUI_IntOffset (*getLayoutPosition)(ArkUI_NodeHandle node); + + /** + * @brief Measures a node. You can use the getMeasuredSize API to obtain the size after the measurement. + * + * When the component is being displayed, this API must be called in the main thread. + * + * @param node Indicates the target node. + * @param Constraint Indicates the size constraint. + * @return Returns 0 if success. + * Returns 401 if a parameter exception occurs. + */ + int32_t (*measureNode)(ArkUI_NodeHandle node, ArkUI_LayoutConstraint* Constraint); + + /** + * @brief Lays outs a component and passes the expected position of the component relative to its parent component. + * + * When the component is being displayed, this API must be called in the main thread. + * + * @param node Indicates the target node. + * @param positionX Indicates the X coordinate. + * @param positionY Indicates the Y coordinate. + * @return Returns 0 if success. + * Returns 401 if a parameter exception occurs. + */ + int32_t (*layoutNode)(ArkUI_NodeHandle node, int32_t positionX, int32_t positionY); } ArkUI_NativeNodeAPI_1; + /** -* @brief Obtain the constrained size during the measurement process through custom component events. +* @brief Obtains the size constraint for measurement through a custom component event. * -* @param event Custom component event. -* @return Constraint size pointer. +* @param event Indicates the pointer to the custom component event. +* @return Returns the pointer to the size constraint. * @since 12 */ ArkUI_LayoutConstraint* OH_ArkUI_NodeCustomEvent_GetLayoutConstraintInMeasure(ArkUI_NodeCustomEvent* event); /** -* @brief Obtains the desired position relative to the parent component during the layout phase through custom component events. +* @brief Obtains the expected position of a component relative to its parent component in the layout phase through a +* custom component event. * -* @param event Custom component event. -* @return Expected position relative to parent component. +* @param event Indicates the pointer to the custom component event. +* @return Returns the expected position relative to the parent component. * @since 12 */ ArkUI_IntOffset OH_ArkUI_NodeCustomEvent_GetPositionInLayout(ArkUI_NodeCustomEvent* event); /** -* @brief Get the drawing context through custom component events. +* @brief Obtains the drawing context through a custom component event. * -* @param event Custom component event. -* @return drawing context. +* @param event Indicates the pointer to the custom component event. +* @return Returns the drawing context. * @since 12 */ ArkUI_DrawContext* OH_ArkUI_NodeCustomEvent_GetDrawContextInDraw(ArkUI_NodeCustomEvent* event); /** -* @brief Get the custom event ID through the custom component event. +* @brief Obtains the ID of a custom component event. * -* @param event Custom component event. -* @return Custom event ID. +* @param event Indicates the pointer to the custom component event. +* @return Returns the ID of the custom component event. * @since 12 */ int32_t OH_ArkUI_NodeCustomEvent_GetEventTargetId(ArkUI_NodeCustomEvent* event); /** -* @brief Get custom event parameters through custom component events. +* @brief Obtains custom event parameters through a custom component event. * -* @param event Custom component event. -* @return Custom event parameters. +* @param event Indicates the pointer to the custom component event. +* @return Returns the custom event parameters. * @since 12 */ void* OH_ArkUI_NodeCustomEvent_GetUserData(ArkUI_NodeCustomEvent* event); /** -* @brief Get the component object through custom component events. +* @brief Obtains a component object through a custom component event. * -* @param event Custom component event. -* @return component object. +* @param event Indicates the pointer to the custom component event. +* @return Returns the component object. * @since 12 */ ArkUI_NodeHandle OH_ArkUI_NodeCustomEvent_GetNodeHandle(ArkUI_NodeCustomEvent* event); /** -* @brief Get the event type through custom component events. +* @brief Obtains the event type through a custom component event. * -* @param event Custom component event. -* @return component custom event type. +* @param event Indicates the pointer to the custom component event. +* @return Returns the type of the custom component event. * @since 12 */ ArkUI_NodeCustomEventType OH_ArkUI_NodeCustomEvent_GetEventType(ArkUI_NodeCustomEvent* event); diff --git a/arkui/ace_engine/native/native_type.h b/arkui/ace_engine/native/native_type.h index 5f590aef7..9e57f4391 100644 --- a/arkui/ace_engine/native/native_type.h +++ b/arkui/ace_engine/native/native_type.h @@ -57,18 +57,18 @@ struct ArkUI_Node; struct ArkUI_NativeDialog; /** - * @brief constrains the size and limits the size range during component layout. - * - * @since 12 - */ -struct ArkUI_LayoutConstraint; + * @brief Sets the size constraints of a component during component layout. + * + * @since 12 + */ +typedef struct ArkUI_LayoutConstraint ArkUI_LayoutConstraint; /** - * @brief defines the component drawing context type structure. - * - * @since 12 - */ -struct ArkUI_DrawContext; + * @brief Defines the structure of the component drawing context. + * + * @since 12 + */ +typedef struct ArkUI_DrawContext ArkUI_DrawContext; /** * @brief Defines the pointer to the ArkUI native component object. @@ -615,7 +615,7 @@ typedef enum { * @since 12 */ typedef enum { - /** The value can be changed to yes or no based on the component. */ + /** Whether the component can be identified by the accessibility service is dependent on the component. */ ARKUI_ACCESSIBILITY_MODE_AUTO = 0, /** The component can be identified by the accessibility service. */ ARKUI_ACCESSIBILITY_MODE_ENABLED, @@ -1245,7 +1245,7 @@ typedef enum { ARKUI_LINEAR_GRADIENT_DIRECTION_RIGHT_BOTTOM, /** No gradient. */ ARKUI_LINEAR_GRADIENT_DIRECTION_NONE, - /** Customize the gradient direction. */ + /** Custom direction. */ ARKUI_LINEAR_GRADIENT_DIRECTION_CUSTOM, } ArkUI_LinearGradientDirection; @@ -1326,176 +1326,176 @@ typedef struct { } ArkUI_Rect; /** - * @brief Dimension type, used to describe the width and height of the component. + * @brief Describes the width and height of a component. * - * @since 12。 + * @since 12 */ typedef struct { - /** Width, unit is px. */ + /** Width, in px. */ int32_t width; - /** Height, unit is px. */ + /** Height, in px. */ int32_t height; } ArkUI_IntSize; /** - * @brief location, used to describe the location of the component. - * - * @since 12. - */ + * @brief Describes the position of a component. + * + * @since 12 + */ typedef struct { - /** Horizontal abscissa, unit is px. */ - int32_t x; - /** Vertical ordinate, unit is px. */ - int32_t y; + /** Horizontal coordinate, in px. */ + int32_t x; + /** Vertical coordinate, in px. */ + int32_t y; } ArkUI_IntOffset; /** -* @brief Create constrained dimensions. +* @brief Creates a size constraint. * * @since 12 */ ArkUI_LayoutConstraint* OH_ArkUI_LayoutConstraint_Create(); /** -* @brief Constraint size deep copy. +* @brief Creates a deep copy of a size constraint. * -* @param Constraint constraint size. -* @return new constraint size pointer. +* @param Constraint Indicates the pointer to the size constraint. +* @return Returns the pointer to the new size constraint. * @since 12 */ ArkUI_LayoutConstraint* OH_ArkUI_LayoutConstraint_Copy(const ArkUI_LayoutConstraint* Constraint); /** -* @brief Destroy the constraint size pointer. +* @brief Destroys the pointer to a size constraint. * -* @param Constraint constraint size. +* @param Constraint Indicates the pointer to the size constraint. * @since 12 */ void* OH_ArkUI_LayoutConstraint_Dispose(ArkUI_LayoutConstraint* Constraint); /** -* @brief Get the maximum width through constraint size, in px. +* @brief Obtains the maximum width for a size constraint, in px. * -* @param Constraint constraint size. -* @return maximum width. +* @param Constraint Indicates the pointer to the size constraint. +* @return Returns the maximum width. * @since 12 */ int32_t OH_ArkUI_LayoutConstraint_GetMaxWidth(const ArkUI_LayoutConstraint* Constraint); /** -* @brief Get the minimum width through constraint size, in px. +* @brief Obtains the minimum width for a size constraint, in px. * -* @param Constraint constraint size. -* @return minimum width. +* @param Constraint Indicates the pointer to the size constraint. +* @return Returns the minimum width. * @since 12 */ int32_t OH_ArkUI_LayoutConstraint_GetMinWidth(const ArkUI_LayoutConstraint* Constraint); /** -* @brief Get the maximum height through constraint size, in px. +* @brief Obtains the maximum height for a size constraint, in px. * -* @param Constraint constraint size. -* @return maximum width. +* @param Constraint Indicates the pointer to the size constraint. +* @return Returns the maximum height. * @since 12 */ int32_t OH_ArkUI_LayoutConstraint_GetMaxHeight(const ArkUI_LayoutConstraint* Constraint); /** -* @brief Get the minimum height through constraint size, in px. +* @brief Obtains the minimum height for a size constraint, in px. * -* @param Constraint constraint size. -* @return maximum width. +* @param Constraint Indicates the pointer to the size constraint. +* @return Returns the minimum height. * @since 12 */ int32_t OH_ArkUI_LayoutConstraint_GetMinHeight(const ArkUI_LayoutConstraint* Constraint); /** -* @brief Get the width percentage base through the constraint size, in px. +* @brief Obtains the width percentage reference for a size constraint, in px. * -* @param Constraint constraint size. -* @return Width percentage base. +* @param Constraint Indicates the pointer to the size constraint. +* @return Returns the width percentage reference. * @since 12 */ int32_t OH_ArkUI_LayoutConstraint_GetPercentReferenceWidth(const ArkUI_LayoutConstraint* Constraint); /** -* @brief Get the height percentage base through the constraint size, in px. +* @brief Obtains the height percentage reference for a size constraint, in px. * -* @param Constraint constraint size. -* @return height percentage base. +* @param Constraint Indicates the pointer to the size constraint. +* @return Returns the height percentage reference. * @since 12 */ int32_t OH_ArkUI_LayoutConstraint_GetPercentReferenceHeight(const ArkUI_LayoutConstraint* Constraint); /** -* @brief Set the maximum width. +* @brief Sets the maximum width. * -* @param Constraint constraint size. -* @param value Maximum width, unit is px. +* @param Constraint Indicates the pointer to the size constraint. +* @param value Indicates the maximum width, in px. * @since 12 */ void OH_ArkUI_LayoutConstraint_SetMaxWidth(ArkUI_LayoutConstraint* Constraint, int32_t value); /** -* @brief Set the minimum width. +* @brief Sets the minimum width. * -* @param Constraint constraint size. -* @param value Minimum width, unit is px. +* @param Constraint Indicates the pointer to the size constraint. +* @param value Indicates the minimum width, in px. * @since 12 */ void OH_ArkUI_LayoutConstraint_SetMinWidth(ArkUI_LayoutConstraint* Constraint, int32_t value); /** -* @brief Set the maximum height. +* @brief Sets the maximum height. * -* @param Constraint constraint size. -* @param value Maximum height, unit is px. +* @param Constraint Indicates the pointer to the size constraint. +* @param value Indicates the maximum height, in px. * @since 12 */ void OH_ArkUI_LayoutConstraint_SetMaxHeight(ArkUI_LayoutConstraint* Constraint, int32_t value); /** -* @brief Set the minimum height. +* @brief Sets the minimum height. * -* @param Constraint constraint size. -* @param value Minimum height, unit is px. +* @param Constraint Indicates the pointer to the size constraint. +* @param value Indicates the minimum height, in px. * @since 12 */ void OH_ArkUI_LayoutConstraint_SetMinHeight(ArkUI_LayoutConstraint* Constraint, int32_t value); /** -* @brief Set the width percentage base. +* @brief Sets the width percentage reference. * -* @param Constraint constraint size. -* @param value Width percentage base, unit is px. +* @param Constraint Indicates the pointer to the size constraint. +* @param value Indicates the width percentage reference, in px. * @since 12 */ void OH_ArkUI_LayoutConstraint_SetPercentReferenceWidth(ArkUI_LayoutConstraint* Constraint, int32_t value); /** -* @brief Set height percentage base. +* @brief Sets the height percentage reference. * -* @param Constraint constraint size. -* @param value Height percentage reference, unit is px. +* @param Constraint Indicates the pointer to the size constraint. +* @param value Indicates the height percentage reference, in px. * @since 12 */ void OH_ArkUI_LayoutConstraint_SetPercentReferenceHeight(ArkUI_LayoutConstraint* Constraint, int32_t value); /** -* @brief Gets the drawing canvas pointer, which can be converted to the -* OH_Drawing_Canvas pointer of the graphics library for drawing. +* @brief Obtains the pointer to a canvas for drawing, which can be converted into the OH_Drawing_Canvas pointer +* in the Drawing module. * -* @param context drawing context. -* @return Canvas pointer used for drawing. +* @param context Indicates the pointer to the drawing context. +* @return Returns the pointer to the canvas for drawing. * @since 12 */ void* OH_ArkUI_DrawContext_GetCanvas(ArkUI_DrawContext* context); /** -* @brief Get the size of the drawable area. +* @brief Obtains the size of a drawing area. * -* @param context drawing context. -* @return drawable area size. +* @param context Indicates the pointer to the drawing context. +* @return Returns the size of the drawing area. * @since 12 */ ArkUI_IntSize OH_ArkUI_DrawContext_GetSize(ArkUI_DrawContext* context); -- Gitee