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
44 extern "C" {
45 #endif
46 
47 /**
48 * @brief Enumerates the actions for triggering closure of the dialog box.
49 *
50 * @since 12
51 */
52 typedef 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 */
68 typedef bool (*ArkUI_OnWillDismissEvent)(int32_t reason);
69 
70 /**
71  * @brief Defines a struct for a dialog box dismiss event.
72  *
73  * @since 12
74  */
75 typedef 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  */
83 typedef 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  */
296 void 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  */
306 void* 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  */
321 int32_t OH_ArkUI_DialogDismissEvent_GetDismissReason(ArkUI_DialogDismissEvent* event);
322 
323 #ifdef __cplusplus
324 };
325 #endif
326 
327 #endif // ARKUI_NATIVE_DIALOG_H
328