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 Enumerates the level mode. 65 * 66 * @since 15 67 */ 68 typedef enum { 69 /** overlay mode. */ 70 ARKUI_LEVEL_MODE_OVERLAY = 0, 71 /** embedded mode. */ 72 ARKUI_LEVEL_MODE_EMBEDDED, 73 } ArkUI_LevelMode; 74 75 /** 76 * @brief Enumerates the immersive mode. 77 * 78 * @since 15 79 */ 80 typedef enum { 81 /** Mask covering the parent node area. */ 82 ARKUI_IMMERSIVE_MODE_DEFAULT = 0, 83 /** Mask extend safe area includes status bar and navigation bar. */ 84 ARKUI_IMMERSIVE_MODE_EXTEND, 85 } ArkUI_ImmersiveMode; 86 87 /** 88 * @brief Invoked when the dialog box is closed. 89 * 90 * @since 12 91 */ 92 typedef bool (*ArkUI_OnWillDismissEvent)(int32_t reason); 93 94 /** 95 * @brief Defines a struct for a dialog box dismiss event. 96 * 97 * @since 12 98 */ 99 typedef struct ArkUI_DialogDismissEvent ArkUI_DialogDismissEvent; 100 101 /** 102 * @brief Provides the custom dialog box APIs for the native side. 103 * 104 * @version 1 105 * @since 12 106 */ 107 typedef struct { 108 /** 109 * @brief Creates a custom dialog box and returns the pointer to the created dialog box. 110 * 111 * @note This method must be called before the <b>show</b> method. 112 * @return Returns the pointer to the created custom dialog box; returns a null pointer if the creation fails. 113 */ 114 ArkUI_NativeDialogHandle (*create)(); 115 /** 116 * @brief Destroys a custom dialog box. 117 * 118 * @param handle Indicates the pointer to the custom dialog box controller. 119 */ 120 void (*dispose)(ArkUI_NativeDialogHandle handle); 121 /** 122 * @brief Attaches the content of a custom dialog box. 123 * 124 * @note This method must be called before the <b>show</b> method. 125 * @param handle Indicates the pointer to the custom dialog box controller. 126 * @param content Indicates the pointer to the root node of the custom dialog box content. 127 * @return Returns the error code. 128 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 129 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 130 */ 131 int32_t (*setContent)(ArkUI_NativeDialogHandle handle, ArkUI_NodeHandle content); 132 /** 133 * @brief Detaches the content of a custom dialog box. 134 * 135 * @note This method must be called before the <b>show</b> method. 136 * @param handle Indicates the pointer to the custom dialog box controller. 137 * @return Returns the error code. 138 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 139 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 140 */ 141 int32_t (*removeContent)(ArkUI_NativeDialogHandle handle); 142 /** 143 * @brief Sets the alignment mode for a custom dialog box. 144 * 145 * @note This method must be called before the <b>show</b> method. 146 * @param handle Indicates the pointer to the custom dialog box controller. 147 * @param alignment Indicates the alignment mode. The parameter type is {@link ArkUI_Alignment}. 148 * @param offsetX Indicates the horizontal offset of the custom dialog box. The value is a floating point number. 149 * @param offsetY Indicates the vertical offset of the custom dialog box. The value is a floating point number. 150 * @return Returns the error code. 151 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 152 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 153 */ 154 int32_t (*setContentAlignment)(ArkUI_NativeDialogHandle handle, int32_t alignment, float offsetX, float offsetY); 155 /** 156 * @brief Resets the alignment mode of a custom dialog box to its default settings. 157 * 158 * @note This method must be called before the <b>show</b> method. 159 * @param handle Indicates the pointer to the custom dialog box controller. 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 (*resetContentAlignment)(ArkUI_NativeDialogHandle handle); 165 /** 166 * @brief Sets the modal mode 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 isModal Specifies whether the custom dialog box is a modal, which has a mask applied. The value 171 * <b>true</b> means that the custom dialog box is a modal, and <b>false</b> means the opposite. 172 * @return Returns the error code. 173 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 174 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 175 */ 176 int32_t (*setModalMode)(ArkUI_NativeDialogHandle handle, bool isModal); 177 /** 178 * @brief Specifies whether to allow users to touch the mask to dismiss the custom dialog box. 179 * 180 * @note This method must be called before the <b>show</b> method. 181 * @param handle Indicates the pointer to the custom dialog box controller. 182 * @param autoCancel Specifies whether to allow users to touch the mask to dismiss the dialog box. 183 * The value <b>true</b> means to allow users to do so, and <b>false</b> means the opposite. 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 (*setAutoCancel)(ArkUI_NativeDialogHandle handle, bool autoCancel); 189 /** 190 * @brief Sets the mask 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 maskColor Indicates the mask color, in 0xARGB format. 195 * @param maskRect Indicates the pointer to the mask area. Events outside the mask area are transparently 196 * transmitted, and events within the mask area are not. The parameter type is {@link ArkUI_Rect}. 197 * @return Returns the error code. 198 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 199 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 200 */ 201 int32_t (*setMask)(ArkUI_NativeDialogHandle handle, uint32_t maskColor, const ArkUI_Rect* maskRect); 202 /** 203 * @brief Sets the background color for a custom dialog box. 204 * 205 * @note This method must be called before the <b>show</b> method. 206 * @param handle Indicates the pointer to the custom dialog box controller. 207 * @param backgroundColor Indicates the background color of the custom dialog box, in 0xARGB format. 208 * @return Returns the error code. 209 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 210 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 211 */ 212 int32_t (*setBackgroundColor)(ArkUI_NativeDialogHandle handle, uint32_t backgroundColor); 213 /** 214 * @brief Sets the background corner radius for a custom dialog box. 215 * 216 * @note This method must be called before the <b>show</b> method. 217 * @param handle Indicates the pointer to the custom dialog box controller. 218 * @param topLeft Indicates the radius of the upper left corner of the custom dialog box background. 219 * @param topRight Indicates the radius of the upper right corner of the custom dialog box background. 220 * @param bottomLeft Indicates the radius of the lower left corner of the custom dialog box background. 221 * @param bottomRight Indicates the radius of the lower right corner of the custom dialog box background. 222 * @return Returns the error code. 223 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 224 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 225 */ 226 int32_t (*setCornerRadius)(ArkUI_NativeDialogHandle handle, float topLeft, float topRight, 227 float bottomLeft, float bottomRight); 228 /** 229 * @brief Sets the number of grid columns occupied by a custom dialog box. 230 * 231 * @note This method must be called before the <b>show</b> method. 232 * @param handle Indicates the pointer to the custom dialog box controller. 233 * @param gridCount Indicates the number of grid columns occupied by the dialog box. The default value is subject to 234 * the window size, and the maximum value is the maximum number of columns supported by the system. 235 * @return Returns the error code. 236 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 237 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 238 */ 239 int32_t (*setGridColumnCount)(ArkUI_NativeDialogHandle handle, int32_t gridCount); 240 /** 241 * @brief Specifies whether to use a custom style for the custom dialog box. 242 * 243 * @note This method must be called before the <b>show</b> method. 244 * @param handle Indicates the pointer to the custom dialog box controller. 245 * @param enableCustomStyle Specifies whether to use a custom style for the dialog box. 246 * <b>true</b>: The dialog box automatically adapts its width to the child components; the rounded corner is 0; 247 * the background color is transparent. 248 * <b>false</b>: The dialog box automatically adapts its width to the grid system and its height to the child 249 * components; the rounded corner is 24 vp. 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 (*enableCustomStyle)(ArkUI_NativeDialogHandle handle, bool enableCustomStyle); 255 /** 256 * @brief Specifies whether to use a custom animation for a custom dialog box. 257 * 258 * @note This method must be called before the <b>show</b> method. 259 * @param handle Indicates the pointer to the custom dialog box controller. 260 * @param enableCustomAnimation Specifies whether to use a custom animation. The value <b>true</b> means to use a 261 * custom animation, and <b>false</b> means to use the default animation. 262 * @return Returns the error code. 263 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 264 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 265 */ 266 int32_t (*enableCustomAnimation)(ArkUI_NativeDialogHandle handle, bool enableCustomAnimation); 267 /** 268 * @brief Registers a callback for a custom dialog box so that the user can decide whether to close the dialog box 269 * after they touch the Back button or press the Esc key. 270 * 271 * @note This method must be called before the <b>show</b> method. 272 * @param handle Indicates the pointer to the custom dialog box controller. 273 * @param eventHandler Indicates the callback to register. The parameter type is {@link ArkUI_OnWillDismissEvent}. 274 * @return Returns the error code. 275 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 276 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 277 */ 278 int32_t (*registerOnWillDismiss)(ArkUI_NativeDialogHandle handle, ArkUI_OnWillDismissEvent eventHandler); 279 /** 280 * @brief Shows a custom dialog box. 281 * 282 * @param handle Indicates the pointer to the custom dialog box controller. 283 * @param showInSubWindow Specifies whether to show the dialog box in a sub-window. 284 * @return Returns the error code. 285 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 286 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 287 */ 288 int32_t (*show)(ArkUI_NativeDialogHandle handle, bool showInSubWindow); 289 /** 290 * @brief Closes a custom dialog box. If the dialog box has been closed, this API does not take effect. 291 * 292 * @param handle Indicates the pointer to the custom dialog box controller. 293 * @return Returns the error code. 294 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 295 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 296 */ 297 int32_t (*close)(ArkUI_NativeDialogHandle handle); 298 /** 299 * @brief Registers a listener for the dismiss event of the custom dialog box. 300 * 301 * @param handle Indicates the pointer to the custom dialog box controller. 302 * @param userData Indicates the pointer to the custom data. 303 * @param callback Indicates the callback for the dismiss event of the custom dialog box. 304 * @return Returns the result code. 305 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 306 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 307 */ 308 int32_t (*registerOnWillDismissWithUserData)( 309 ArkUI_NativeDialogHandle handle, void* userData, void (*callback)(ArkUI_DialogDismissEvent* event)); 310 } ArkUI_NativeDialogAPI_1; 311 312 /** 313 * @brief Provides the custom dialog box APIs for the native side. 314 * 315 * @version 2 316 * @since 15 317 */ 318 typedef struct { 319 /** 320 * @brief Provides the custom dialog box APIs for the native side. The API scope is {@link ArkUI_NativeDialogAPI_1} 321 * 322 * @since 15 323 */ 324 ArkUI_NativeDialogAPI_1 nativeDialogAPI1; 325 /** 326 * @brief Defines the distance between the customDialog and system keyboard. 327 * 328 * @note This method must be called before the <b>show</b> method. 329 * @param handle Indicates the pointer to the custom dialog box controller. 330 * @param distance distance, in vp. 331 * @param unit Indicates the unit, which is an enumerated value of {@link ArkUI_LengthMetricUnit} 332 * @return Returns the result code. 333 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 334 * Returns {@link ARKUI_ERROR_CODE_CAPI_INIT_ERROR} if the CAPI init error. 335 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 336 * @since 15 337 */ 338 int32_t (*setKeyboardAvoidDistance)(ArkUI_NativeDialogHandle handle, float distance, ArkUI_LengthMetricUnit unit); 339 340 /** 341 * @brief Sets the level mode for a custom dialog box. 342 * 343 * @note This method must be called before the <b>show</b> method. 344 * @param handle Indicates the pointer to the custom dialog box controller. 345 * @param levelMode Indicates the level mode. The parameter type is {@link ArkUI_LevelMode}. 346 * @return Returns the error code. 347 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 348 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 349 * @since 15 350 */ 351 int32_t (*setLevelMode)(ArkUI_NativeDialogHandle handle, ArkUI_LevelMode levelMode); 352 353 /** 354 * @brief Sets the level uniqueId for a custom dialog box. 355 * 356 * @note This method must be called before the <b>setLevelMode</b> method. 357 * @param handle Indicates the pointer to the custom dialog box controller. 358 * @param uniqueId Indicates the uniquedId of any nodes in router or navigation pages. 359 * @return Returns the error code. 360 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 361 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 362 * @since 15 363 */ 364 int32_t (*setLevelUniqueId)(ArkUI_NativeDialogHandle handle, int32_t uniqueId); 365 366 /** 367 * @brief Sets the immersive mode for a custom dialog box. 368 * 369 * @note This method must be called before the <b>show</b> method. 370 * @param handle Indicates the pointer to the custom dialog box controller. 371 * @param immersiveMode Indicates the immersive mode. The parameter type is {@link ArkUI_ImmersiveMode}. 372 * @return Returns the error code. 373 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 374 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 375 * @since 15 376 */ 377 int32_t (*setImmersiveMode)(ArkUI_NativeDialogHandle handle, ArkUI_ImmersiveMode immersiveMode); 378 } ArkUI_NativeDialogAPI_2; 379 380 /** 381 * @brief Sets whether to block the system behavior of dismissing a dialog box. 382 * 383 * @param event Indicates the pointer to a dialog box dismiss event object. 384 * @param shouldBlockDismiss Indicates whether to block the system behavior of dismissing the dialog box. The value 385 * <b>true</b> means to block the system behavior, and <b>false</b> means the opposite. 386 * @since 12 387 */ 388 void OH_ArkUI_DialogDismissEvent_SetShouldBlockDismiss(ArkUI_DialogDismissEvent* event, bool shouldBlockDismiss); 389 390 /** 391 * @brief Obtains the pointer to user data in a dialog box dismiss event object. 392 * 393 * @param event Indicates the pointer to a dialog box dismiss event object. 394 * 395 * @return Returns the pointer to user data. 396 * @since 12 397 */ 398 void* OH_ArkUI_DialogDismissEvent_GetUserData(ArkUI_DialogDismissEvent* event); 399 400 /** 401 * @brief Obtains the c from a dialog box dismiss event object. 402 * 403 * @param event Indicates the pointer to a dialog box dismiss event object. 404 * 405 * @return Returns the dismissal reason. Returns <b>-1</b> if an exception occurs. 406 * {@link DIALOG_DISMISS_BACK_PRESS}: touching the Back button, swiping left or right on the screen, or 407 * pressing the Esc key. 408 * {@link DIALOG_DISMISS_TOUCH_OUTSIDE}: touching the mask. 409 * {@link DIALOG_DISMISS_CLOSE_BUTTON}: touching the Close button. 410 * {@link DIALOG_DISMISS_SLIDE_DOWN}: sliding down. 411 * @since 12 412 */ 413 int32_t OH_ArkUI_DialogDismissEvent_GetDismissReason(ArkUI_DialogDismissEvent* event); 414 415 #ifdef __cplusplus 416 }; 417 #endif 418 419 #endif // ARKUI_NATIVE_DIALOG_H 420 /** @} */ 421