ArkUI_NativeDialogAPI_1

typedef struct {...} ArkUI_NativeDialogAPI_1

Overview

Provides a collection of native-side custom dialog box APIs provided by ArkUI.

Since: 12

Related module: ArkUI_NativeModule

Header file: native_dialog.h

Summary

Member Functions

Name	Description
ArkUI_NativeDialogHandle (*create)()	Creates a custom dialog box and returns the pointer to the created dialog box.
void (*dispose)(ArkUI_NativeDialogHandle handle)	Destroys a custom dialog box.
int32_t (*setContent)(ArkUI_NativeDialogHandle handle, ArkUI_NodeHandle content)	Sets the content for a custom dialog box.
int32_t (*removeContent)(ArkUI_NativeDialogHandle handle)	Removes the content of a custom dialog box.
int32_t (*setContentAlignment)(ArkUI_NativeDialogHandle handle, int32_t alignment, float offsetX, float offsetY)	Sets the alignment mode of a custom dialog box.
int32_t (*resetContentAlignment)(ArkUI_NativeDialogHandle handle)	Resets the alignment mode of a custom dialog box to its default settings.
int32_t (*setModalMode)(ArkUI_NativeDialogHandle handle, bool isModal)	Sets the modal mode for a custom dialog box.
int32_t (*setAutoCancel)(ArkUI_NativeDialogHandle handle, bool autoCancel)	Specifies whether to allow users to touch the mask to dismiss a custom dialog box.
int32_t (*setMask)(ArkUI_NativeDialogHandle handle, uint32_t maskColor, const ArkUI_Rect* maskRect)	Sets the mask for a custom dialog box.
int32_t (*setBackgroundColor)(ArkUI_NativeDialogHandle handle, uint32_t backgroundColor)	Sets the background color for a custom dialog box.
int32_t (*setCornerRadius)(ArkUI_NativeDialogHandle handle, float topLeft, float topRight,float bottomLeft, float bottomRight)	Sets the background corner radius for a custom dialog box.
int32_t (*setGridColumnCount)(ArkUI_NativeDialogHandle handle, int32_t gridCount)	Sets the number of grid columns occupied by a custom dialog box.
int32_t (*enableCustomStyle)(ArkUI_NativeDialogHandle handle, bool enableCustomStyle)	Specifies whether to use a custom style for the custom dialog box.
int32_t (*enableCustomAnimation)(ArkUI_NativeDialogHandle handle, bool enableCustomAnimation)	Specifies whether to use a custom animation for a custom dialog box.
int32_t (*registerOnWillDismiss)(ArkUI_NativeDialogHandle handle, ArkUI_OnWillDismissEvent eventHandler)	Registers a callback for a custom dialog box so that the user can decide whether to close the dialog box after they touch the back button or press the Esc key.
int32_t (*show)(ArkUI_NativeDialogHandle handle, bool showInSubWindow)	Shows a custom dialog box.
int32_t (*close)(ArkUI_NativeDialogHandle handle)	Closes a custom dialog box. If the dialog box has been closed, this API does not take effect. This API is executed asynchronously in the background. The dialog box node is removed from the tree only after the dismissal animation is complete. If you want to open the dialog box again after closing it, wait for 300 ms and then perform the operation again.
int32_t (*registerOnWillDismissWithUserData)(ArkUI_NativeDialogHandle handle, void* userData, void (*callback)(ArkUI_DialogDismissEvent* event))	Registers a callback for the dismissal event of a custom dialog box.

Member Function Description

create()

ArkUI_NativeDialogHandle (*create)()

Description

Creates a custom dialog box and returns the pointer to the created dialog box.

NOTE

This API must be called before the show API is invoked.

Returns

Type	Description
ArkUI_NativeDialogHandle	Pointer to the custom dialog box, or a null pointer if the creation fails.

dispose()

void (*dispose)(ArkUI_NativeDialogHandle handle)

Description

Destroys a custom dialog box.

Name	Description
ArkUI_NativeDialogHandle handle	Pointer to the custom dialog box controller.

setContent()

int32_t (*setContent)(ArkUI_NativeDialogHandle handle, ArkUI_NodeHandle content)

Description

Sets the content for a custom dialog box.

NOTE

This API must be called before the show API is invoked.

Parameters

Name	Description
ArkUI_NativeDialogHandle handle	Pointer to the custom dialog box controller.
ArkUI_NodeHandle content	Pointer to the root node of the custom dialog box content.

Returns

Type	Description
int32_t	Result code. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

removeContent()

int32_t (*removeContent)(ArkUI_NativeDialogHandle handle)

Description

Removes the content of a custom dialog box.

NOTE

This API must be called before the show API is invoked.

Parameters

Name	Description
ArkUI_NativeDialogHandle handle	Pointer to the custom dialog box controller.

Returns

Type	Description
int32_t	Result code. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

setContentAlignment()

int32_t (*setContentAlignment)(ArkUI_NativeDialogHandle handle, int32_t alignment, float offsetX, float offsetY)

Description

Sets the alignment mode of a custom dialog box.

NOTE

This API must be called before the show API is invoked.

Parameters

Name	Description
ArkUI_NativeDialogHandle handle	Pointer to the custom dialog box controller.
int32_t alignment	Alignment mode. The parameter type is ArkUI_Alignment.
float offsetX	Horizontal offset of the dialog box. The value is a floating point number, in vp.
float offsetY	Vertical offset of the dialog box. The value is a floating point number, in vp.

Returns

Type	Description
int32_t	Result code. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

resetContentAlignment()

int32_t (*resetContentAlignment)(ArkUI_NativeDialogHandle handle)

Description

Resets the alignment mode of a custom dialog box to its default settings. The default value is ARKUI_ALIGNMENT_TOP_START. For details, see ArkUI_Alignment.

NOTE

This API must be called before the show API is invoked.

Parameters

Name	Description
ArkUI_NativeDialogHandle handle	Pointer to the custom dialog box controller.

Returns

Type	Description
int32_t	Result code. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

setModalMode()

int32_t (*setModalMode)(ArkUI_NativeDialogHandle handle, bool isModal)

Description

Sets the modal mode for a custom dialog box.

NOTE

This API must be called before the show API is invoked.

Parameters

Name	Description
ArkUI_NativeDialogHandle handle	Pointer to the custom dialog box controller.
bool isModal	Whether the custom dialog box is a modal, which has a mask applied. The value true means that the custom dialog box is a modal, and false means the opposite.

Returns

Type	Description
int32_t	Result code. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

setAutoCancel()

int32_t (*setAutoCancel)(ArkUI_NativeDialogHandle handle, bool autoCancel)

Description

Specifies whether to allow users to touch the mask to dismiss a custom dialog box.

NOTE

This API must be called before the show API is invoked.

Parameters

Name	Description
ArkUI_NativeDialogHandle handle	Pointer to the custom dialog box controller.
bool autoCancel	Whether to allow users to touch the mask to dismiss the dialog box. The value true means to allow users to do so, and false means the opposite.

Returns

Type	Description
int32_t	Result code. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

setMask()

int32_t (*setMask)(ArkUI_NativeDialogHandle handle, uint32_t maskColor, const ArkUI_Rect* maskRect)

Description

Sets the mask for a custom dialog box.

NOTE

This API must be called before the show API is invoked.

Parameters

Name	Description
ArkUI_NativeDialogHandle handle	Pointer to the custom dialog box controller.
uint32_t maskColor	Mask color, in 0xARGB format.
const ArkUI_Rect* maskRect	Pointer to the mask area. Events outside the mask area are transparently transmitted, and events within the mask area are not. The parameter type is ArkUI_Rect.

Returns

Type	Description
int32_t	Result code. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

setBackgroundColor()

int32_t (*setBackgroundColor)(ArkUI_NativeDialogHandle handle, uint32_t backgroundColor)

Description

Sets the background color for a custom dialog box.

NOTE

This API must be called before the show API is invoked.

Parameters

Name	Description
ArkUI_NativeDialogHandle handle	Pointer to the custom dialog box controller.
uint32_t backgroundColor	Background color of the custom dialog box, in 0xARGB format.

Returns

Type	Description
int32_t	Result code. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

setCornerRadius()

int32_t (*setCornerRadius)(ArkUI_NativeDialogHandle handle, float topLeft, float topRight,float bottomLeft, float bottomRight)

Description

Sets the background corner radius for a custom dialog box.

NOTE

This API must be called before the show API is invoked.

Parameters

Name	Description
ArkUI_NativeDialogHandle handle	Pointer to the custom dialog box controller.
float topLeft	Radius of the upper left corner of the background for the custom dialog box, in vp. Default value: 32 vp since API version 12; 24 vp in API version 11 and earlier versions.
float topRight	Radius of the upper right corner of the background for the custom dialog box, in vp. Default value: 32 vp since API version 12; 24 vp in API version 11 and earlier versions.
float bottomLeft	Radius of the lower left corner of the background for the custom dialog box, in vp. Default value: 32 vp since API version 12; 24 vp in API version 11 and earlier versions.
float bottomRight	Radius of the lower right corner of the background for the custom dialog box, in vp. Default value: 32 vp since API version 12; 24 vp in API version 11 and earlier versions.

Returns

Type	Description
int32_t	Result code. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

setGridColumnCount()

int32_t (*setGridColumnCount)(ArkUI_NativeDialogHandle handle, int32_t gridCount)

Description

Sets the number of grid columns occupied by a custom dialog box.

NOTE

This API must be called before the show API is invoked.

Parameters

Name	Description
ArkUI_NativeDialogHandle handle	Pointer to the custom dialog box controller.
int32_t gridCount	Number of grids. The default value is subject to the window size, and the maximum value is the maximum number of columns supported by the system. The value is an integer greater than or equal to 0.

Returns

Type	Description
int32_t	Result code. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

enableCustomStyle()

int32_t (*enableCustomStyle)(ArkUI_NativeDialogHandle handle, bool enableCustomStyle)

Description

Specifies whether to use a custom style for the custom dialog box.

NOTE

This API must be called before the show API is invoked.

Parameters

Name	Description
ArkUI_NativeDialogHandle handle	Pointer to the custom dialog box controller.
bool enableCustomStyle	Whether to use a custom style for the dialog box. Default value: false. true: The dialog box cannot use a custom style. Its width adapts to its child components, with zero corner radius and a transparent background. false: The dialog box can use a custom style. Its height adapts to its child components and its width is defined by the grid system. The rounded corner radius is 24 vp. On PC and 2-in-1 devices, it automatically avoids screen edges and window title bars.

Returns

Type	Description
int32_t	Result code. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

enableCustomAnimation()

int32_t (*enableCustomAnimation)(ArkUI_NativeDialogHandle handle, bool enableCustomAnimation)

Description

Specifies whether to use a custom animation for a custom dialog box.

NOTE

This API must be called before the show API is invoked.

Parameters

Name	Description
ArkUI_NativeDialogHandle handle	Pointer to the custom dialog box controller.
bool enableCustomAnimation	Whether to use a custom animation. The value true means to use a custom animation, and false means to use the default animation.

Returns

Type	Description
int32_t	Result code. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

registerOnWillDismiss()

int32_t (*registerOnWillDismiss)(ArkUI_NativeDialogHandle handle, ArkUI_OnWillDismissEvent eventHandler)

Description

Registers a callback for a custom dialog box so that the user can decide whether to close the dialog box after they touch the back button or press the Esc key.

NOTE

This API must be called before the show API is invoked.

Parameters

Name	Description
ArkUI_NativeDialogHandle handle	Pointer to the custom dialog box controller.
ArkUI_OnWillDismissEvent eventHandler	Callback for dialog box dismissal.

Returns

Type	Description
int32_t	Result code. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

show()

int32_t (*show)(ArkUI_NativeDialogHandle handle, bool showInSubWindow)

Description

Shows a custom dialog box.

Parameters

Name	Description
ArkUI_NativeDialogHandle handle	Pointer to the custom dialog box controller.
bool showInSubWindow	Whether to show the dialog box in a subwindow. true: The dialog box is shown in a subwindow. false: The dialog box is not shown in a subwindow.

Returns

Type	Description
int32_t	Result code. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

close()

int32_t (*close)(ArkUI_NativeDialogHandle handle)

Description

Closes a custom dialog box. If the dialog box has been closed, this API does not take effect. This API is executed asynchronously in the background. The dialog box node is removed from the tree only after the dismissal animation is complete. If you want to open the dialog box again after closing it, wait for 300 ms and then perform the operation again.

Parameters

Name	Description
ArkUI_NativeDialogHandle handle	Pointer to the custom dialog box controller.

Returns

Type	Description
int32_t	Result code. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. This only indicates that the close command is successfully delivered, but does not indicate that the dialog box is completely closed. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

registerOnWillDismissWithUserData()

int32_t (*registerOnWillDismissWithUserData)(ArkUI_NativeDialogHandle handle, void* userData, void (*callback)(ArkUI_DialogDismissEvent* event))

Description

Registers a callback for the dismissal event of a custom dialog box.

Parameters

Name	Description
ArkUI_NativeDialogHandle handle	Pointer to the custom dialog box controller.
void* userData	Pointer to user data.
callback	Callback for the dismissal event of the custom dialog box. - event: input parameter of the callback, which captures the reason for dismissal.

Returns

Type	Description
int32_t	Result code. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.