1/*
2 * Copyright (c) 2024 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16/**
17 * @addtogroup ArkUI_NativeModule
18 * @{
19 *
20 * @brief Provides UI capabilities of ArkUI on the native side, such as UI component creation and destruction,
21 * tree node operations, attribute setting, and event listening.
22 *
23 * @since 12
24 */
25
26/**
27 * @file native_dialog.h
28 *
29 * @brief Defines a set of custom dialog box APIs of ArkUI on the native side.
30 *
31 * @library libace_ndk.z.so
32 * @syscap SystemCapability.ArkUI.ArkUI.Full
33 * @kit ArkUI
34 * @since 12
35 */
36
37#ifndef ARKUI_NATIVE_DIALOG_H
38#define ARKUI_NATIVE_DIALOG_H
39
40#include <stdbool.h>
41#include "native_type.h"
42
43#ifdef __cplusplus
44extern "C" {
45#endif
46
47/**
48* @brief Enumerates the actions for triggering closure of the dialog box.
49*
50* @since 12
51*/
52typedef enum {
53    /** Touching the system-defined Back button or pressing the Esc key. */
54    DIALOG_DISMISS_BACK_PRESS = 0,
55    /** Touching the mask. */
56    DIALOG_DISMISS_TOUCH_OUTSIDE,
57    /** Touching the Close button. */
58    DIALOG_DISMISS_CLOSE_BUTTON,
59    /** Sliding down. */
60    DIALOG_DISMISS_SLIDE_DOWN,
61} ArkUI_DismissReason;
62
63/**
64* @brief Invoked when the dialog box is closed.
65*
66* @since 12
67*/
68typedef bool (*ArkUI_OnWillDismissEvent)(int32_t reason);
69
70/**
71 * @brief Defines a struct for a dialog box dismiss event.
72 *
73 * @since 12
74 */
75typedef struct ArkUI_DialogDismissEvent ArkUI_DialogDismissEvent;
76
77/**
78 * @brief Provides the custom dialog box APIs for the native side.
79 *
80 * @version 1
81 * @since 12
82 */
83typedef struct {
84    /**
85    * @brief Creates a custom dialog box and returns the pointer to the created dialog box.
86    *
87    * @note This method must be called before the <b>show</b> method.
88    * @return Returns the pointer to the created custom dialog box; returns a null pointer if the creation fails.
89    */
90    ArkUI_NativeDialogHandle (*create)();
91    /**
92    * @brief Destroys a custom dialog box.
93    *
94    * @param handle Indicates the pointer to the custom dialog box controller.
95    */
96    void (*dispose)(ArkUI_NativeDialogHandle handle);
97    /**
98    * @brief Attaches the content of a custom dialog box.
99    *
100    * @note This method must be called before the <b>show</b> method.
101    * @param handle Indicates the pointer to the custom dialog box controller.
102    * @param content Indicates the pointer to the root node of the custom dialog box content.
103    * @return Returns the error code.
104    *         Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful.
105    *         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs.
106    */
107    int32_t (*setContent)(ArkUI_NativeDialogHandle handle, ArkUI_NodeHandle content);
108    /**
109    * @brief Detaches the content of a custom dialog box.
110    *
111    * @note This method must be called before the <b>show</b> method.
112    * @param handle Indicates the pointer to the custom dialog box controller.
113    * @return Returns the error code.
114    *         Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful.
115    *         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs.
116    */
117    int32_t (*removeContent)(ArkUI_NativeDialogHandle handle);
118    /**
119    * @brief Sets the alignment mode for a custom dialog box.
120    *
121    * @note This method must be called before the <b>show</b> method.
122    * @param handle Indicates the pointer to the custom dialog box controller.
123    * @param alignment Indicates the alignment mode. The parameter type is {@link ArkUI_Alignment}.
124    * @param offsetX Indicates the horizontal offset of the custom dialog box. The value is a floating point number.
125    * @param offsetY Indicates the vertical offset of the custom dialog box. The value is a floating point number.
126    * @return Returns the error code.
127    *         Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful.
128    *         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs.
129    */
130    int32_t (*setContentAlignment)(ArkUI_NativeDialogHandle handle, int32_t alignment, float offsetX, float offsetY);
131    /**
132    * @brief Resets the alignment mode of a custom dialog box to its default settings.
133    *
134    * @note This method must be called before the <b>show</b> method.
135    * @param handle Indicates the pointer to the custom dialog box controller.
136    * @return Returns the error code.
137    *         Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful.
138    *         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs.
139    */
140    int32_t (*resetContentAlignment)(ArkUI_NativeDialogHandle handle);
141    /**
142    * @brief Sets the modal mode for a custom dialog box.
143    *
144    * @note This method must be called before the <b>show</b> method.
145    * @param handle Indicates the pointer to the custom dialog box controller.
146    * @param isModal Specifies whether the custom dialog box is a modal, which has a mask applied. The value
147    * <b>true</b> means that the custom dialog box is a modal, and <b>false</b> means the opposite.
148    * @return Returns the error code.
149    *         Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful.
150    *         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs.
151    */
152    int32_t (*setModalMode)(ArkUI_NativeDialogHandle handle, bool isModal);
153    /**
154    * @brief Specifies whether to allow users to touch the mask to dismiss the custom dialog box.
155    *
156    * @note This method must be called before the <b>show</b> method.
157    * @param handle Indicates the pointer to the custom dialog box controller.
158    * @param autoCancel Specifies whether to allow users to touch the mask to dismiss the dialog box.
159    * The value <b>true</b> means to allow users to do so, and <b>false</b> means the opposite.
160    * @return Returns the error code.
161    *         Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful.
162    *         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs.
163    */
164    int32_t (*setAutoCancel)(ArkUI_NativeDialogHandle handle, bool autoCancel);
165    /**
166    * @brief Sets the mask for a custom dialog box.
167    *
168    * @note This method must be called before the <b>show</b> method.
169    * @param handle Indicates the pointer to the custom dialog box controller.
170    * @param maskColor Indicates the mask color, in 0xARGB format.
171    * @param maskRect Indicates the pointer to the mask area. Events outside the mask area are transparently
172    * transmitted, and events within the mask area are not. The parameter type is {@link ArkUI_Rect}.
173    * @return Returns the error code.
174    *         Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful.
175    *         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs.
176    */
177    int32_t (*setMask)(ArkUI_NativeDialogHandle handle, uint32_t maskColor, const ArkUI_Rect* maskRect);
178    /**
179    * @brief Sets the background color for a custom dialog box.
180    *
181    * @note This method must be called before the <b>show</b> method.
182    * @param handle Indicates the pointer to the custom dialog box controller.
183    * @param backgroundColor Indicates the background color of the custom dialog box, in 0xARGB format.
184    * @return Returns the error code.
185    *         Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful.
186    *         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs.
187    */
188    int32_t (*setBackgroundColor)(ArkUI_NativeDialogHandle handle, uint32_t backgroundColor);
189    /**
190    * @brief Sets the background corner radius for a custom dialog box.
191    *
192    * @note This method must be called before the <b>show</b> method.
193    * @param handle Indicates the pointer to the custom dialog box controller.
194    * @param topLeft Indicates the radius of the upper left corner of the custom dialog box background.
195    * @param topRight Indicates the radius of the upper right corner of the custom dialog box background.
196    * @param bottomLeft Indicates the radius of the lower left corner of the custom dialog box background.
197    * @param bottomRight Indicates the radius of the lower right corner of the custom dialog box background.
198    * @return Returns the error code.
199    *         Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful.
200    *         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs.
201    */
202    int32_t (*setCornerRadius)(ArkUI_NativeDialogHandle handle, float topLeft, float topRight,
203        float bottomLeft, float bottomRight);
204    /**
205    * @brief Sets the number of grid columns occupied by a custom dialog box.
206    *
207    * @note This method must be called before the <b>show</b> method.
208    * @param handle Indicates the pointer to the custom dialog box controller.
209    * @param gridCount Indicates the number of grid columns occupied by the dialog box. The default value is subject to
210    * the window size, and the maximum value is the maximum number of columns supported by the system.
211    * @return Returns the error code.
212    *         Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful.
213    *         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs.
214    */
215    int32_t (*setGridColumnCount)(ArkUI_NativeDialogHandle handle, int32_t gridCount);
216    /**
217    * @brief Specifies whether to use a custom style for the custom dialog box.
218    *
219    * @note This method must be called before the <b>show</b> method.
220    * @param handle Indicates the pointer to the custom dialog box controller.
221    * @param enableCustomStyle Specifies whether to use a custom style for the dialog box.
222    * <b>true</b>: The dialog box automatically adapts its width to the child components; the rounded corner is 0;
223    * the background color is transparent.
224    * <b>false</b>: The dialog box automatically adapts its width to the grid system and its height to the child
225    * components; the rounded corner is 24 vp.
226    * @return Returns the error code.
227    *         Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful.
228    *         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs.
229    */
230    int32_t (*enableCustomStyle)(ArkUI_NativeDialogHandle handle, bool enableCustomStyle);
231    /**
232    * @brief Specifies whether to use a custom animation for a custom dialog box.
233    *
234    * @note This method must be called before the <b>show</b> method.
235    * @param handle Indicates the pointer to the custom dialog box controller.
236    * @param enableCustomAnimation Specifies whether to use a custom animation. The value <b>true</b> means to use a
237    * custom animation, and <b>false</b> means to use the default animation.
238    * @return Returns the error code.
239    *         Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful.
240    *         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs.
241    */
242    int32_t (*enableCustomAnimation)(ArkUI_NativeDialogHandle handle, bool enableCustomAnimation);
243    /**
244    * @brief Registers a callback for a custom dialog box so that the user can decide whether to close the dialog box
245    * after they touch the Back button or press the Esc key.
246    *
247    * @note This method must be called before the <b>show</b> method.
248    * @param handle Indicates the pointer to the custom dialog box controller.
249    * @param eventHandler Indicates the callback to register. The parameter type is {@link ArkUI_OnWillDismissEvent}.
250    * @return Returns the error code.
251    *         Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful.
252    *         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs.
253    */
254    int32_t (*registerOnWillDismiss)(ArkUI_NativeDialogHandle handle, ArkUI_OnWillDismissEvent eventHandler);
255    /**
256    * @brief Shows a custom dialog box.
257    *
258    * @param handle Indicates the pointer to the custom dialog box controller.
259    * @param showInSubWindow Specifies whether to show the dialog box in a sub-window.
260    * @return Returns the error code.
261    *         Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful.
262    *         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs.
263    */
264    int32_t (*show)(ArkUI_NativeDialogHandle handle, bool showInSubWindow);
265    /**
266    * @brief Closes a custom dialog box. If the dialog box has been closed, this API does not take effect.
267    *
268    * @param handle Indicates the pointer to the custom dialog box controller.
269    * @return Returns the error code.
270    *         Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful.
271    *         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs.
272    */
273    int32_t (*close)(ArkUI_NativeDialogHandle handle);
274    /**
275    * @brief Registers a listener for the dismiss event of the custom dialog box.
276    *
277    * @param handle Indicates the pointer to the custom dialog box controller.
278    * @param userData Indicates the pointer to the custom data.
279    * @param callback Indicates the callback for the dismiss event of the custom dialog box.
280    * @return Returns the result code.
281    *         Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful.
282    *         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs.
283    */
284    int32_t (*registerOnWillDismissWithUserData)(
285        ArkUI_NativeDialogHandle handle, void* userData, void (*callback)(ArkUI_DialogDismissEvent* event));
286} ArkUI_NativeDialogAPI_1;
287
288/**
289 * @brief Sets whether to block the system behavior of dismissing a dialog box.
290 *
291 * @param event Indicates the pointer to a dialog box dismiss event object.
292 * @param shouldBlockDismiss Indicates whether to block the system behavior of dismissing the dialog box. The value
293 *                           <b>true</b> means to block the system behavior, and <b>false</b> means the opposite.
294 * @since 12
295 */
296void OH_ArkUI_DialogDismissEvent_SetShouldBlockDismiss(ArkUI_DialogDismissEvent* event, bool shouldBlockDismiss);
297
298/**
299 * @brief Obtains the pointer to user data in a dialog box dismiss event object.
300 *
301 * @param event Indicates the pointer to a dialog box dismiss event object.
302 *
303 * @return Returns the pointer to user data.
304 * @since 12
305 */
306void* OH_ArkUI_DialogDismissEvent_GetUserData(ArkUI_DialogDismissEvent* event);
307
308/**
309 * @brief Obtains the c from a dialog box dismiss event object.
310 *
311 * @param event Indicates the pointer to a dialog box dismiss event object.
312 *
313 * @return Returns the dismissal reason. Returns <b>-1</b> if an exception occurs.
314 *         {@link DIALOG_DISMISS_BACK_PRESS}: touching the Back button, swiping left or right on the screen, or
315 *                                            pressing the Esc key.
316 *         {@link DIALOG_DISMISS_TOUCH_OUTSIDE}: touching the mask.
317 *         {@link DIALOG_DISMISS_CLOSE_BUTTON}: touching the Close button.
318 *         {@link DIALOG_DISMISS_SLIDE_DOWN}: sliding down.
319 * @since 12
320 */
321int32_t OH_ArkUI_DialogDismissEvent_GetDismissReason(ArkUI_DialogDismissEvent* event);
322
323#ifdef __cplusplus
324};
325#endif
326
327#endif // ARKUI_NATIVE_DIALOG_H
328