From 0012340dc1864ff170aceceeb81db2ab3f341840 Mon Sep 17 00:00:00 2001 From: zcdqs Date: Mon, 18 Aug 2025 10:06:46 +0800 Subject: [PATCH] add grid capi Signed-off-by: zcdqs --- arkui/ace_engine/native/native_node.h | 123 +++++++++++++++++++++++ arkui/ace_engine/native/native_type.h | 139 ++++++++++++++++++++++++++ 2 files changed, 262 insertions(+) diff --git a/arkui/ace_engine/native/native_node.h b/arkui/ace_engine/native/native_node.h index ce5b57eb466..ecf1f86d2b7 100644 --- a/arkui/ace_engine/native/native_node.h +++ b/arkui/ace_engine/native/native_node.h @@ -6853,6 +6853,52 @@ typedef enum { */ NODE_GRID_SYNC_LOAD = 1013007, + /** + * @brief Specifies the alignment of GridItem components in the parent Grid container. + * 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: alignment of GridItem components in the parent Grid container, \n + * specified using the {@link ArkUI_GridItemAlignment} enum. \n + * The default value is GRID_ITEM_ALIGNMENT_DEFAULT. \n + * \n + * Format of the return value {@link ArkUI_AttributeItem}:\n + * .value[0].i32: alignment of GridItem components in the parent Grid container, \n + * specified using the {@link ArkUI_GridItemAlignment} enum. \n + * + * @since 21 + */ + NODE_GRID_ALIGN_ITEMS = 1013008, + + /** + * @brief Specifies the layout options of the Grid component. + * This attribute can be set, reset, and obtained as required through APIs. + * + * Format of the {@link ArkUI_AttributeItem} parameter for setting the attribute: \n + * .object: layout options, with the parameter format of {@link ArkUI_GridLayoutOptions}. \n + * \n + * Format of the return value {@link ArkUI_AttributeItem}:\n + * .object: current {@link ArkUI_GridLayoutOptions} object. \n + * + * @since 21 + */ + NODE_GRID_LAYOUT_OPTIONS = 1013009, + + /** + * @brief Sets the style of the GridItem component. + * 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: style of the GridItem component, specified using {@link ArkUI_SliderStyle}. \n + * The default value is GRID_ITEM_STYLE_NONE. \n + * \n + * Format of the return value {@link ArkUI_AttributeItem}:\n + * .value[0].i32: style of the GridItem component, specified using {@link ArkUI_SliderStyle}. \n + * + * @since 21 + */ + NODE_GRID_ITEM_STYLE = MAX_NODE_SCOPE_NUM * ARKUI_NODE_GRID_ITEM, + /** * @brief Defines the column width of the text picker. * This attribute can be set, reset, and obtained as required through APIs. @@ -8410,6 +8456,83 @@ typedef enum { * the end position of the currently displayed waterfall. \n */ NODE_WATER_FLOW_ON_SCROLL_INDEX, + + /** + * @brief Defines the event triggered when a child component enters or leaves the grid display area. + * + * Notes for triggering the event:\n + * This event is triggered once when the grid is initialized and when the index of the first or \n + * last child component in the grid display area changes. \n + * When the event callback occurs, the union type in the {@link ArkUI_NodeEvent} object is \n + * {@link ArkUI_NodeComponentEvent}. \n + * {@link ArkUI_NodeComponentEvent} contains two parameters:\n + * ArkUI_NodeComponentEvent.data[0].i32: index of the first child component in the grid display area. \n + * ArkUI_NodeComponentEvent.data[1].i32: index of the last child component in the grid display area. \n + * + * @since 21 + */ + NODE_GRID_ON_SCROLL_INDEX = MAX_NODE_SCOPE_NUM * ARKUI_NODE_GRID, + + /** + * @brief Defines the event triggered when the grid is about to scroll. + * + * Notes for triggering the event:\n + * 1. This event is triggered when scrolling is started by the scrollable component or other input settings, + * such as keyboard and mouse operations. \n + * 2. Scrolling can be initiated by calling the controller API. \n + * 3. The out-of-bounds bounce effect is supported. \n + * When the event callback occurs, the union type in the {@link ArkUI_NodeEvent} object is + * {@link ArkUI_NodeComponentEvent}. \n + * {@link ArkUI_NodeComponentEvent} contains three parameters:\n + * ArkUI_NodeComponentEvent.data[0].f32: + * Scroll offset of each frame. A positive offset indicates content scrolling upward, \n + * and a negative offset indicates content scrolling downward. \n + * ArkUI_NodeComponentEvent.data[1].i32: current scroll state. The parameter type is + * {@link ArkUI_ScrollState}. \n + * ArkUI_NodeComponentEvent.data[2].i32: scroll source. The parameter type is {@link ArkUI_ScrollSource}. \n + * @return Returns one or no number to indicate the actual amount by which the scroll component scrolls. + * + * @since 21 + */ + NODE_GRID_ON_WILL_SCROLL = 1013001, + + /** + * @brief Defines the event triggered when the grid scrolls. + * + * Notes for triggering the event:\n + * 1. This event is triggered when scrolling is started by the scrollable component or other input settings, + * such as keyboard and mouse operations. \n + * 2. Scrolling can be initiated by calling the controller API. \n + * 3. The out-of-bounds bounce effect is supported. \n + * When the event callback occurs, the union type in the {@link ArkUI_NodeEvent} object is + * {@link ArkUI_NodeComponentEvent}. \n + * {@link ArkUI_NodeComponentEvent} contains two parameters:\n + * ArkUI_NodeComponentEvent.data[0].f32: + * Scroll offset of each frame. A positive offset indicates content scrolling upward, \n + * and a negative offset indicates content scrolling downward. \n + * ArkUI_NodeComponentEvent.data[1].i32: current scroll state. \n + * + * @since 21 + */ + NODE_GRID_ON_DID_SCROLL = 1013002, + + /** + * @brief Defines the event triggered at the end of each frame layout of the ARKUI_NODE_GRID component, + * which is used to set the position and length of the scrollbar. + * + * The event parameter is {@link ArkUI_NodeEvent}. \n + * value.i32 at index 0:offset of the first visible grid item, + * obtained using OH_ArkUI_NodeEvent_GetNumberValue. \n + * value.f32 at index 1: offset of the first visible item relative to the grid's display starting position, in vp, + * obtained using OH_ArkUI_NodeEvent_GetNumberValue. \n + * @return Information about the scrollbar position and length. \n + * You can set the return value using OH_ArkUI_NodeEvent_SetReturnNumberValue. \n + * value.f32 at index 0: total offset of the grid content relative to the display area, in px. \n + * value.f32 at index 1: total length of the grid content, in px. \n + * + * @since 21 + */ + NODE_GRID_ON_SCROLL_BAR_UPDATE = 1013003, } ArkUI_NodeEventType; /** diff --git a/arkui/ace_engine/native/native_type.h b/arkui/ace_engine/native/native_type.h index 7cef398b2d6..79a79257f3e 100644 --- a/arkui/ace_engine/native/native_type.h +++ b/arkui/ace_engine/native/native_type.h @@ -94,6 +94,42 @@ typedef struct ArkUI_Node* ArkUI_NodeHandle; */ typedef struct ArkUI_NativeDialog* ArkUI_NativeDialogHandle; +/** + * @brief Defines the return value structure for the onGetIrregularSizeByIndex callback + * in Grid layout options. + * + * @since 21 + */ +typedef struct { + /** Number of rows occupied by the GridItem component. */ + uint32_t rowSpan; + /** Number of columns occupied by the GridItem component. */ + uint32_t columnSpan; +} ArkUI_GridItemSize; + +/** + * @brief Defines the return value structure for the onGetRectByIndex callback in Grid layout options. + * + * @since 21 + */ +typedef struct { + /** Starting row position of the GridItem component. */ + uint32_t rowStart; + /** Starting column position of the GridItem component. */ + uint32_t columnStart; + /** Number of rows occupied by the GridItem component. */ + uint32_t rowSpan; + /** Number of columns occupied by the GridItem component. */ + uint32_t columnSpan; +} ArkUI_GridItemRect; + +/** + * @brief Defines the Grid layout options. + * + * @since 21 + */ +typedef struct ArkUI_GridLayoutOptions ArkUI_GridLayoutOptions; + /** * @brief Defines the water flow section configuration. * @@ -699,6 +735,30 @@ typedef enum { ARKUI_FOCUS_WRAP_WITH_ARROW = 1, } ArkUI_FocusWrapMode; +/** + * @brief Enumerates the grid item alignment modes. + * + * @since 21 + */ +typedef enum { + /** Use the default alignment mode of the grid. */ + GRID_ITEM_ALIGNMENT_DEFAULT = 0, + /** Set the height of all grid items in a row to match the height of the tallest item in that row. */ + GRID_ITEM_ALIGNMENT_STRETCH = 1, +} ArkUI_GridItemAlignment; + +/** + * @brief Enumerates styles of grid items. + * + * @since 21 + */ +typedef enum { + /** No style. */ + GRID_ITEM_STYLE_NONE = 0, + /** Hover or press style. */ + GRID_ITEM_STYLE_PLAIN = 1, +} ArkUI_GridItemStyle; + /** * @brief Enumerates the scroll directions for the component. * @@ -2986,6 +3046,85 @@ void* OH_ArkUI_DrawContext_GetCanvas(ArkUI_DrawContext* context); */ ArkUI_IntSize OH_ArkUI_DrawContext_GetSize(ArkUI_DrawContext* context); +/** + * @brief Creates Grid layout options. + * + * @return Grid layout options created. + * @since 21 + */ +ArkUI_GridLayoutOptions* OH_ArkUI_GridLayoutOptions_Create(); + +/** + * @brief Disposes of Grid layout options. + * + * @param option Grid layout options. + * @since 21 + */ +void OH_ArkUI_GridLayoutOptions_Dispose(ArkUI_GridLayoutOptions* option); + +/** + * @brief Sets the irregular grid item index array for the grid layout. + * + * @param option Grid layout options. + * @param irregularIndexes Array of irregular grid item indexes. + * @param size Size of the index array. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * If an error code is returned, it may be due to a failure in parameter validation; + * the parameter must not be null. + * @since 21 + */ +int32_t OH_ArkUI_GridLayoutOptions_SetIrregularIndexes( + ArkUI_GridLayoutOptions* option, uint32_t* irregularIndexes, int32_t size); + +/** + * @brief Obtains the irregular grid item index array for the grid layout. + * When OH_ArkUI_GridLayoutOptions_RegisterGetIrregularSizeByIndexCallback is not set, + * the grid item specified in irregularIndexes occupies an entire row of the grid that scrolls vertically or + * an entire column of the grid that scrolls horizontally. + * + * @param option Grid layout options. + * @param irregularIndexes Array of irregular grid item indexes. + * @param size Size of the index array. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * Returns {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} if the provided buffer size is insufficient. + * If an error code is returned, it may be due to a failure in parameter validation; + * the parameter must not be null. + * @since 21 + */ +int32_t OH_ArkUI_GridLayoutOptions_GetIrregularIndexes( + ArkUI_GridLayoutOptions* option, uint32_t* irregularIndexes, int32_t* size); + +/** + * @brief Registers a callback to obtain the row and column span for the grid item at the specified index. + * + * @param option Grid layout options. + * @param userData Indicates the custom data. + * @param callback Callback that returns the row and column span for the grid item at the specified index. + * itemIndex: grid item index, which must be within the range set by + * {@link OH_ArkUI_GridLayoutOptions_SetIrregularIndexes}. + * @since 21 + */ +void OH_ArkUI_GridLayoutOptions_RegisterGetIrregularSizeByIndexCallback( + ArkUI_GridLayoutOptions* option, void* userData, ArkUI_GridItemSize (*callback)(int32_t itemIndex, void* userData)); + +/** + * @brief Registers a callback to obtain the starting row, starting column, row span, + * and column span for the grid item at the specified index. + * + * @param option Grid layout options. + * @param userData Indicates the custom data. + * @param callback Callback that returns the starting row, starting column, row span, + * and column span for the grid item at the specified index. + * itemIndex: grid item index. + * @since 21 + */ +void OH_ArkUI_GridLayoutOptions_RegisterGetRectByIndexCallback( + ArkUI_GridLayoutOptions* option, void* userData, ArkUI_GridItemRect (*callback)(int32_t itemIndex, void* userData)); + /** * @brief Creates water flow section configuration. * -- Gitee