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 drag and drop APIs of ArkUI on the native side. 21 * 22 * @since 12 23 */ 24 25 /** 26 * @file drag_and_drop.h 27 * 28 * @brief Defines the native drag and drop APIs. 29 * 30 * @library libace_ndk.z.so 31 * @syscap SystemCapability.ArkUI.ArkUI.Full 32 * @since 12 33 */ 34 35 #ifndef ARKUI_NATIVE_DRAG_AND_DROP_H 36 #define ARKUI_NATIVE_DRAG_AND_DROP_H 37 38 #include <stdint.h> 39 40 #include "native_type.h" 41 #include "ui_input_event.h" 42 43 #ifdef __cplusplus 44 extern "C" { 45 #endif 46 47 /** 48 * @brief Defines an enum for drag results, which are set by the data receiver and transferred by the system to the 49 * drag source so that the drag source is aware of the data processing result of the receiver. 50 * 51 * @since 12 52 */ 53 typedef enum { 54 /** The drag and drop operation succeeded. */ 55 ARKUI_DRAG_RESULT_SUCCESSFUL = 0, 56 /** The drag and drop operation failed. */ 57 ARKUI_DRAG_RESULT_FAILED, 58 /** The drag and drop operation was canceled. */ 59 ARKUI_DRAG_RESULT_CANCELED, 60 } ArkUI_DragResult; 61 62 /** 63 * @brief Defines an enum for data processing modes used when data is dropped, which affects the display of the badge. 64 * 65 * @since 12 66 */ 67 typedef enum { 68 /** Copy. */ 69 ARKUI_DROP_OPERATION_COPY = 0, 70 /** Cut. */ 71 ARKUI_DROP_OPERATION_MOVE, 72 } ArkUI_DropOperation; 73 74 /** 75 * @brief Defines an enum for interaction states prior to a drop and drop operation. 76 * 77 * @since 12 78 */ 79 typedef enum { 80 /** Unknown. */ 81 ARKUI_PRE_DRAG_STATUS_UNKNOWN = -1, 82 /** A drag gesture is being detected. */ 83 ARKUI_PRE_DRAG_STATUS_ACTION_DETECTING, 84 /** The component is ready to be dragged. */ 85 ARKUI_PRE_DRAG_STATUS_READY_TO_TRIGGER_DRAG, 86 /** A lift animation is started. */ 87 ARKUI_PRE_DRAG_STATUS_PREVIEW_LIFT_STARTED, 88 /** A lift animation is finished. */ 89 ARKUI_PRE_DRAG_STATUS_PREVIEW_LIFT_FINISHED, 90 /** A drop animation is started. */ 91 ARKUI_PRE_DRAG_STATUS_PREVIEW_LANDING_STARTED, 92 /** A drop animation is finished. */ 93 ARKUI_PRE_DRAG_STATUS_PREVIEW_LANDING_FINISHED, 94 /** A drop animation is terminated. */ 95 ARKUI_PRE_DRAG_STATUS_CANCELED_BEFORE_DRAG, 96 } ArkUI_PreDragStatus; 97 98 /** 99 * @brief Defines an enum for drag preview scale modes. 100 * 101 * @since 12 102 */ 103 typedef enum { 104 /** 105 * The system automatically changes the position of the dragged point based on the scenario and 106 * scales the drag preview based on set rules. 107 */ 108 ARKUI_DRAG_PREVIEW_SCALE_AUTO = 0, 109 /** The system does not scale the drag preview. */ 110 ARKUI_DRAG_PREVIEW_SCALE_DISABLED, 111 } ArkUI_DragPreviewScaleMode; 112 113 /** 114 * @brief Defines an enum for drag states. 115 * 116 * @since 12 117 */ 118 typedef enum { 119 /** Unknown. */ 120 ARKUI_DRAG_STATUS_UNKNOWN = -1, 121 /** Started. */ 122 ARKUI_DRAG_STATUS_STARTED, 123 /** Ended. */ 124 ARKUI_DRAG_STATUS_ENDED, 125 } ArkUI_DragStatus; 126 127 /** 128 * @brief Defines a struct for a component event. 129 * 130 * @since 12 131 */ 132 typedef struct ArkUI_NodeEvent ArkUI_NodeEvent; 133 134 /** 135 * @brief Defines a struct for a UI context object. 136 * 137 * @since 12 138 */ 139 typedef struct ArkUI_Context ArkUI_Context; 140 141 /** 142 * @brief Defines a struct for a UI context object pointer. 143 * 144 * @since 12 145 */ 146 typedef struct ArkUI_Context* ArkUI_ContextHandle; 147 148 /** 149 * @brief Defines a struct for a drag event. 150 * 151 * @since 12 152 */ 153 typedef struct ArkUI_DragEvent ArkUI_DragEvent; 154 155 /** 156 * @brief Defines a struct for custom drag preview options. 157 * 158 * @since 12 159 */ 160 typedef struct ArkUI_DragPreviewOption ArkUI_DragPreviewOption; 161 162 /** 163 * @brief Defines a struct for a drag action. 164 * 165 * @since 12 166 */ 167 typedef struct ArkUI_DragAction ArkUI_DragAction; 168 169 /** 170 * @brief Defines a struct for drag and drop information returned through a drag status listener. 171 * 172 * @since 12 173 */ 174 typedef struct ArkUI_DragAndDropInfo ArkUI_DragAndDropInfo; 175 176 /** 177 * @brief Defines a struct for UDMF unified data. 178 * 179 * @since 12 180 */ 181 typedef struct OH_UdmfData OH_UdmfData; 182 183 /** 184 * @brief Defines a struct for UDMF to get data with progress info. 185 * 186 * @since 15 187 */ 188 typedef struct OH_UdmfGetDataParams OH_UdmfGetDataParams; 189 190 /** 191 * @brief Defines the <b>Pixelmap</b> struct, which is used to perform operations related to a pixel map. 192 * 193 * @since 12 194 */ 195 typedef struct OH_PixelmapNative OH_PixelmapNative; 196 197 /** 198 * @brief Obtains a <b>ArkUI_DragEvent</b> object from the specified <b>ArkUI_NodeEvent</b> object. 199 * 200 * @param node Indicates the pointer to an <b>ArkUI_NodeEvent</b> object. 201 * @return Returns the pointer to an <b>ArkUI_DragEvent</b> object. 202 * Returns <b>null</b> if the parameter passed in is invalid or is not a drag-related event. 203 * @since 12 204 */ 205 ArkUI_DragEvent* OH_ArkUI_NodeEvent_GetDragEvent(ArkUI_NodeEvent* nodeEvent); 206 207 /** 208 * @brief Obtains the interaction state prior to a drop and drop operation. 209 * 210 * @param node Indicates the pointer to an <b>ArkUI_NodeEvent</b> object. 211 * @return Returns the interaction state prior to the drop and drop operation. 212 * @since 12 213 */ 214 ArkUI_PreDragStatus OH_ArkUI_NodeEvent_GetPreDragStatus(ArkUI_NodeEvent* nodeEvent); 215 216 /** 217 * @brief Sets whether to disable the default drop animation. 218 * The default drop animation is enabled by default and can be disabled to apply a custom drop animation. 219 * 220 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 221 * @param disable Indicates whether to disable the default drop animation. 222 * The value <b>true</b> means to disable the default drop animation, and <b>false</b> means the opposite. 223 * @return Returns the result code. 224 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 225 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 226 * @since 12 227 */ 228 int32_t OH_ArkUI_DragEvent_DisableDefaultDropAnimation(ArkUI_DragEvent* event, bool disable); 229 230 /** 231 * @brief Obtains the drop operation from a drag event. 232 * 233 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 234 * @param operation Indicates the drop operation which the data receiver set. 235 * @return Returns the result 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 * Possible causes: 1. The given parameters are null or the given event is not a valid DragEvent. 239 * @since 12 240 */ 241 int32_t OH_ArkUI_DragEvent_SetSuggestedDropOperation(ArkUI_DragEvent* event, ArkUI_DropOperation dropOperation); 242 243 /** 244 * @brief Obtains the drop operation from a drag event. 245 * 246 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 247 * @param operation Indicates the drop operation which the data receiver set. 248 * @return Returns the result code. 249 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operations successful. 250 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 251 * @since 12 252 */ 253 int32_t OH_ArkUI_DragEvent_GetDropOperation(ArkUI_DragEvent* event, ArkUI_DropOperation* operation); 254 255 /** 256 * @brief Sets the result for a drag event. 257 * 258 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 259 * @param result Indicates the drag result. 260 * @return Returns the result 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 * @since 12 264 */ 265 int32_t OH_ArkUI_DragEvent_SetDragResult(ArkUI_DragEvent* event, ArkUI_DragResult result); 266 267 /** 268 * @brief Set drag data for a drag event. 269 * 270 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 271 * @param data Indicates the drag data. 272 * @return Returns the result code. 273 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 274 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 275 * @since 12 276 */ 277 int32_t OH_ArkUI_DragEvent_SetData(ArkUI_DragEvent* event, OH_UdmfData* data); 278 279 /** 280 * @brief Obtains the default drag data from a drag event. 281 * 282 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 283 * @param data Indicates the pointer to an <b>OH_UdmfData</b> object. The application needs to create a pointer 284 * for receiving data by using the {@link OH_UdmfData_Create} method. 285 * @return Returns the result code. 286 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 287 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 288 * @since 12 289 */ 290 int32_t OH_ArkUI_DragEvent_GetUdmfData(ArkUI_DragEvent* event, OH_UdmfData *data); 291 292 /** 293 * @brief Obtains the number of drag data types from a drag event. 294 * 295 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 296 * @param count Indicates the number of drag data types returned. 297 * @return Returns the result code. 298 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 299 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 300 * @since 12 301 */ 302 int32_t OH_ArkUI_DragEvent_GetDataTypeCount(ArkUI_DragEvent* event, int32_t* count); 303 304 /** 305 * @brief Obtains the list of drag data types from a drag event. 306 * 307 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 308 * @param eventTypeArray Indicates the list of the drag data types. You need to create a string array first. 309 * @param length Indicates the total length of the list array. It must be greater than or equal to the number obtained 310 * by using {@link OH_ArkUI_DragEvent_GetDataTypeCount}. 311 * @param maxStrLen Indicates the max string length of drag data types. 312 * @return Returns the result code. 313 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 314 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 315 * Returns {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} if the giving buffer is not enough for string copy. 316 * @since 12 317 */ 318 int32_t OH_ArkUI_DragEvent_GetDataTypes( 319 ArkUI_DragEvent *event, char *eventTypeArray[], int32_t length, int32_t maxStrLen); 320 321 /** 322 * @brief Obtains the drag result from a drag event. 323 * 324 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 325 * @param result Indicates the drag result returned. 326 * @return Returns the result code. 327 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 328 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 329 * @since 12 330 */ 331 int32_t OH_ArkUI_DragEvent_GetDragResult(ArkUI_DragEvent* event, ArkUI_DragResult* result); 332 333 /** 334 * @brief Obtains the X coordinate of the touch point for a drag preview from a drag event. 335 * 336 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 337 * @return Returns the X coordinate of the touch point, in px. 338 * Returns the default value <b>0</b> if the input parameter is invalid. 339 * @since 12 340 */ 341 float OH_ArkUI_DragEvent_GetPreviewTouchPointX(ArkUI_DragEvent* event); 342 343 /** 344 * @brief Obtains the Y coordinate of the touch point for a drag preview from a drag event. 345 * 346 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 347 * @return Returns the Y coordinate of the touch point, in px. 348 * Returns the default value <b>0</b> if the input parameter is invalid. 349 * @since 12 350 */ 351 float OH_ArkUI_DragEvent_GetPreviewTouchPointY(ArkUI_DragEvent* event); 352 353 /** 354 * @brief Obtains the width of a drag preview from a drag event. 355 * 356 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 357 * @return Returns the width of the drag preview, in px. 358 * Returns the default value <b>0</b> if the input parameter is invalid. 359 * @since 12 360 */ 361 float OH_ArkUI_DragEvent_GetPreviewRectWidth(ArkUI_DragEvent* event); 362 363 /** 364 * @brief Obtains the height of a drag preview from a drag event. 365 * 366 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 367 * @return Returns the height of the drag preview, in px. 368 * Returns the default value <b>0</b> if the input parameter is invalid. 369 * @since 12 370 */ 371 float OH_ArkUI_DragEvent_GetPreviewRectHeight(ArkUI_DragEvent* event); 372 373 /** 374 * @brief Obtains the X coordinate of the touch point relative to the window from a drag event. 375 * 376 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 377 * @return Returns the X coordinate of the touch point relative to the window, in px. 378 * Returns the default value <b>0</b> if the input parameter is invalid. 379 * @since 12 380 */ 381 float OH_ArkUI_DragEvent_GetTouchPointXToWindow(ArkUI_DragEvent* event); 382 383 /** 384 * @brief Obtains the Y coordinate of the touch point relative to the window from a drag event. 385 * 386 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 387 * @return Returns the Y coordinate of the touch point relative to the window, in px. 388 * Returns the default value <b>0</b> if the input parameter is invalid. 389 * @since 12 390 */ 391 float OH_ArkUI_DragEvent_GetTouchPointYToWindow(ArkUI_DragEvent* event); 392 393 /** 394 * @brief Obtains the X coordinate of the touch point relative to the current display from a drag event. 395 * 396 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 397 * @return Returns the X coordinate of the touch point relative to the current display, in px. 398 * Returns the default value <b>0</b> if the input parameter is invalid. 399 * @since 12 400 */ 401 float OH_ArkUI_DragEvent_GetTouchPointXToDisplay(ArkUI_DragEvent* event); 402 403 /** 404 * @brief Obtains the Y coordinate of the touch point relative to the current display from a drag event. 405 * 406 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 407 * @return Returns the Y coordinate of the touch point relative to the current display, in px. 408 * Returns the default value <b>0</b> if the input parameter is invalid. 409 * @since 12 410 */ 411 float OH_ArkUI_DragEvent_GetTouchPointYToDisplay(ArkUI_DragEvent* event); 412 413 /** 414 * @brief Obtains the dragging velocity along the x-axis. 415 * 416 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 417 * @return Returns the dragging velocity along the x-axis, in px. 418 * Returns the default value <b>0</b> if the input parameter is invalid. 419 * @since 12 420 */ 421 float OH_ArkUI_DragEvent_GetVelocityX(ArkUI_DragEvent* event); 422 423 /** 424 * @brief Obtains the dragging velocity along the y-axis. 425 * 426 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 427 * @return Returns the dragging velocity along the y-axis, in px. 428 * Returns the default value <b>0</b> if the input parameter is invalid. 429 * @since 12 430 */ 431 float OH_ArkUI_DragEvent_GetVelocityY(ArkUI_DragEvent* event); 432 433 /** 434 * @brief Obtains the dragging velocity along the main axis. 435 * 436 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 437 * @return Returns the dragging velocity along the main axis, in px. 438 * Returns the default value <b>0</b> if the input parameter is invalid. 439 * @since 12 440 */ 441 float OH_ArkUI_DragEvent_GetVelocity(ArkUI_DragEvent* event); 442 443 /** 444 * @brief Obtains the pressed status of modifier keys from a drag event. 445 * 446 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 447 * @param keys Indicates the returned combination of modifier keys that are currently pressed. 448 * The application can determine the pressed modifier keys through bitwise operations. 449 * @return Returns the result code. 450 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 451 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 452 * @since 12 453 */ 454 int32_t OH_ArkUI_DragEvent_GetModifierKeyStates(ArkUI_DragEvent* event, uint64_t* keys); 455 456 /** 457 * 458 * @brief Request to start the data sync process with the sync option. 459 * 460 * @param event Indicates the pointer to an ArkUI_DragEvent object. 461 * @param options Indicates the pointer to an OH_UdmfGetDataParams object. 462 * @param key Represents return value after set data to database successfully, it should be not 463 * less than {@link UDMF_KEY_BUFFER_LEN}. 464 * @param keyLen Represents the length of key string. 465 * @return Returns the result code. 466 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 467 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 468 * Returns {@link ARKUI_ERROR_CODE_DRAG_DATA_SYNC_FAILED } if the data sync is not allowed or failed. 469 * @since 15 470 */ 471 int32_t OH_ArkUI_DragEvent_StartDataLoading( 472 ArkUI_DragEvent* event, OH_UdmfGetDataParams* options, char* key, unsigned int keyLen); 473 474 /** 475 * 476 * @brief Cancel the data sync process. 477 * 478 * @param uiContext Indicates the pointer to a UI instance. 479 * @param key Represents the data key returned by {@link OH_ArkUI_DragEvent_StartDataLoading}. 480 * @return Returns the result code. 481 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 482 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 483 * Returns {@link ARKUI_ERROR_CODE_OPERATION_FAILED} if no any data sync is in progress. 484 * @since 15 485 */ 486 int32_t OH_ArkUI_CancelDataLoading(ArkUI_ContextHandle uiContext, const char* key); 487 488 /** 489 * @brief Sets whether to disable data prefetch process before the onDrop callback executing. 490 * The system will retry to getting data until the max time limit (2.4s for now) reaches, 491 * this's useful for the cross device draging operation, as the system helps to eliminate 492 * the communication instability, but it's redundant for {@link OH_ArkUI_DragEvent_StartDataLoading} 493 * method, as it will take care the data fetching with asynchronous mechanism, so must set this 494 * field to true if using {@link OH_ArkUI_DragEvent_StartDataLoading} in onDrop to avoid the data is 495 * fetched before onDrop executing unexpectedly. 496 * 497 * @param node Indicates the pointer to a component node. 498 * @param disabled Indicates whether to disable the data pre-fetch process, true for disable, false for not. 499 * @return Returns the result code. 500 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 501 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 502 * @since 15 503 */ 504 int32_t OH_ArkUI_DisableDropDataPrefetchOnNode(ArkUI_NodeHandle node, bool disabled); 505 506 /** 507 * @brief Sets whether to enable strict reporting on drag events. 508 * This feature is disabled by default, and you are advised to enable it. 509 * If this feature is disabled, the parent component is not notified when an item in it is dragged over its child 510 * component. If this feature is enabled, the component is notified of the dragged item's leaving, and the chil 511 * component to which the dragged item is dropped is notified of the item's entering. This configuration is 512 * related to a specific UI instance. You can pass in a specific component node on the current UI instance 513 * for association. 514 * 515 * @param node Indicates the pointer to a component node. 516 * @param enabled Indicates whether to enable strict reporting on drag events. 517 * @return Returns the result code. 518 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 519 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 520 * @since 12 521 */ 522 int32_t OH_ArkUI_SetDragEventStrictReportWithNode(ArkUI_NodeHandle node, bool enabled); 523 524 /** 525 * @brief Sets whether to enable strict reporting on drag events. 526 * This feature is disabled by default, and you are advised to enable it. 527 * If this feature is disabled, the parent component is not notified when an item in it is dragged over its child 528 * component. If this feature is enabled, the component is notified of the dragged item's leaving, and the child 529 * component to which the dragged item is dropped is notified of the item's entering. This configuration is 530 * related to a specific UI instance. You can pass in a specific UI instance for association. 531 * 532 * @param uiContext Indicates the pointer to a UI instance. 533 * @param enabled Indicates whether to enable strict reporting on drag events. 534 * @return Returns the result code. 535 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 536 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 537 * @since 12 538 */ 539 int32_t OH_ArkUI_SetDragEventStrictReportWithContext(ArkUI_ContextHandle uiContext, bool enabled); 540 541 /** 542 * @brief Sets the types of data that can be dropped to the specified component. This API resets the settings configured 543 * through {@link OH_ArkUI_DisallowNodeAnyDropDataTypes} and {@link OH_ArkUI_AllowNodeAllDropDataTypes}. 544 * 545 * @param node Indicates the pointer to a component node. 546 * @param typesArray Indicates the array of types of data that can be dropped. 547 * @param count Indicates length of an array. 548 * @return Returns the result code. 549 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 550 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 551 * @since 12 552 */ 553 int32_t OH_ArkUI_SetNodeAllowedDropDataTypes(ArkUI_NodeHandle node, const char* typesArray[], int32_t count); 554 555 /** 556 * @brief Configures the specified component to disallow any data types. This API resets the settings configured through 557 * {@link OH_ArkUI_SetNodeAllowedDropDataTypes}. 558 * 559 * @param node Indicates the pointer to a component node. 560 * @return Returns the result code. 561 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 562 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 563 * @since 12 564 */ 565 int32_t OH_ArkUI_DisallowNodeAnyDropDataTypes(ArkUI_NodeHandle node); 566 567 /** 568 * @brief Configures the specified component to allow any data types. This API resets the settings configured through 569 * {@link OH_ArkUI_SetNodeAllowedDropDataTypes}. 570 * 571 * @param node Indicates the pointer to a component node. 572 * @return Returns the result code. 573 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 574 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 575 * @since 12 576 */ 577 int32_t OH_ArkUI_AllowNodeAllDropDataTypes(ArkUI_NodeHandle node); 578 579 /** 580 * @brief Sets whether the specified component is draggable. 581 * 582 * @param node Indicates the pointer to a component node. 583 * @param bool Indicates whether the component is draggable. 584 * @return Returns the result code. 585 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 586 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 587 * @since 12 588 */ 589 int32_t OH_ArkUI_SetNodeDraggable(ArkUI_NodeHandle node, bool enabled); 590 591 /** 592 * @brief Sets a custom drag preview for the specified component. 593 * 594 * @param node Indicates the pointer to a component node. 595 * @param preview Indicates the custom drag preview, which is a pixel map. 596 * @return Returns the result code. 597 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 598 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 599 * @since 12 600 */ 601 int32_t OH_ArkUI_SetNodeDragPreview(ArkUI_NodeHandle node, OH_PixelmapNative* preview); 602 603 /** 604 * @brief Creates an <b>ArkUI_DragPreviewOption</b> object. 605 * 606 * @return Returns the created <b>ArkUI_DragPreviewOption</b> object. 607 * @since 12 608 */ 609 ArkUI_DragPreviewOption* OH_ArkUI_CreateDragPreviewOption(void); 610 611 /** 612 * @brief Disposes of a <b>ArkUI_DragPreviewOption</b> object. 613 * 614 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 615 * @since 12 616 */ 617 void OH_ArkUI_DragPreviewOption_Dispose(ArkUI_DragPreviewOption* option); 618 619 /** 620 * @brief Sets the scale mode for an <b>ArkUI_DragPreviewOption</b> object. 621 * 622 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 623 * @param scaleMode Indicates the scale mode. 624 * @return Returns the result code. 625 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 626 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 627 * @since 12 628 */ 629 int32_t OH_ArkUI_DragPreviewOption_SetScaleMode(ArkUI_DragPreviewOption* option, ArkUI_DragPreviewScaleMode scaleMode); 630 631 /** 632 * @brief Sets whether to enable the shadow effect for an <b>ArkUI_DragPreviewOption</b> object. 633 * The shadow effect is enabled by default. 634 * 635 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 636 * @param enabled Indicates whether to enable the shadow effect. 637 * @return Returns the result code. 638 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 639 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 640 * @since 12 641 */ 642 int32_t OH_ArkUI_DragPreviewOption_SetDefaultShadowEnabled(ArkUI_DragPreviewOption* option, bool enabled); 643 644 /** 645 * @brief Sets whether to enable the rounded corner effect for an <b>ArkUI_DragPreviewOption</b> object. 646 * The rounded corner effect is enabled by default. 647 * 648 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 649 * @param enabled Indicates whether to enable the rounded corner effect. 650 * @return Returns the result code. 651 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 652 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 653 * @since 12 654 */ 655 int32_t OH_ArkUI_DragPreviewOption_SetDefaultRadiusEnabled(ArkUI_DragPreviewOption* option, bool enabled); 656 657 /** 658 * @brief Sets whether to enable the badge for an <b>ArkUI_DragPreviewOption</b> object. 659 * If this feature is enabled, a badge that contains the number of dragged items is displayed. 660 * 661 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 662 * @param enabled Indicates whether to enable badge. 663 * @return Returns the result code. 664 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 665 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 666 * @since 12 667 */ 668 int32_t OH_ArkUI_DragPreviewOption_SetNumberBadgeEnabled(ArkUI_DragPreviewOption* option, bool enabled); 669 670 /** 671 * @brief Sets the count on the badge. 672 * The settings will overwrite the value in the <b>SetDragPreviewNumberBadgeEnabled</b> API. 673 * 674 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 675 * @param forcedNumber Indicates the count on the badge. 676 * @return Returns the result code. 677 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 678 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 679 * @since 12 680 */ 681 int32_t OH_ArkUI_DragPreviewOption_SetBadgeNumber(ArkUI_DragPreviewOption* option, uint32_t forcedNumber); 682 683 /** 684 * @brief Sets whether to enable the default animation on a click or touch, it's not used in drag action. 685 * 686 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 687 * @param enabled Indicates whether to enable the default animation on a click or touch. 688 * @return Returns the result code. 689 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 690 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 691 * @since 12 692 */ 693 int32_t OH_ArkUI_DragPreviewOption_SetDefaultAnimationBeforeLiftingEnabled( 694 ArkUI_DragPreviewOption* option, bool enabled); 695 /** 696 * @brief Sets an <b>ArkUI_DragPreviewOption</b> object for the specified component. 697 * 698 * @param node Indicates the pointer to a component node. 699 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 700 * @return Returns the result code. 701 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 702 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 703 * @since 12 704 */ 705 int32_t OH_ArkUI_SetNodeDragPreviewOption(ArkUI_NodeHandle node, ArkUI_DragPreviewOption* option); 706 707 /** 708 * @brief Creates a drag action object for a UI instance based on the specified component node of the current 709 * UI instance. 710 * 711 * @param node Indicates the pointer to a component node. 712 * @return Returns the pointer to the created drag action object; returns null if the operation fails. 713 * @since 12 714 */ 715 ArkUI_DragAction* OH_ArkUI_CreateDragActionWithNode(ArkUI_NodeHandle node); 716 717 /** 718 * @brief Creates a drag action object for the specified UI instance. 719 * 720 * @param uiContext Indicates the pointer to a UI instance. 721 * @return Returns the pointer to the created drag action object; returns null if the operation fails. 722 * @since 12 723 */ 724 ArkUI_DragAction* OH_ArkUI_CreateDragActionWithContext(ArkUI_ContextHandle uiContext); 725 726 /** 727 * @brief Disposes of a drag action object. 728 * 729 * @param dragAction Indicates the pointer to the target drag action object. 730 * @since 12 731 */ 732 void OH_ArkUI_DragAction_Dispose(ArkUI_DragAction* dragAction); 733 734 /** 735 * @brief Sets the pointer ID. If only one finger is operating on the screen, the pointer ID is 0. 736 * In general cases, you can set the pointer ID to 0. 737 * 738 * @param dragAction Indicates the pointer to the target drag action object. 739 * @param pointer Indicates the pointer ID. The value ranges from 0 to 9. 740 * @return Returns the result code. 741 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 742 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 743 * @since 12 744 */ 745 int32_t OH_ArkUI_DragAction_SetPointerId(ArkUI_DragAction* dragAction, int32_t pointer); 746 747 /** 748 * @brief Sets the drag previews for a drag action. 749 * 750 * @param dragAction Indicates the pointer to the target drag action object. 751 * @param pixelmapArray Indicates the array of the drag previews to set, which must be pixel maps. 752 * @param size Indicates the size of the drag preview array. 753 * @return Returns the result code. 754 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 755 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 756 * @since 12 757 */ 758 int32_t OH_ArkUI_DragAction_SetPixelMaps( 759 ArkUI_DragAction* dragAction, OH_PixelmapNative* pixelmapArray[], int32_t size); 760 761 /** 762 * @brief Sets the touch point relative to the upper left corner of the first drag preview (pixel map). 763 * 764 * @param dragAction Indicates the pointer to the target drag action object. 765 * @param x Indicates the X coordinate of the touch point. 766 * @return Returns the result code. 767 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 768 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 769 * @since 12 770 */ 771 int32_t OH_ArkUI_DragAction_SetTouchPointX(ArkUI_DragAction* dragAction, float x); 772 773 /** 774 * @brief Sets the touch point relative to the upper left corner of the first drag preview (pixel map). 775 * 776 * @param dragAction Indicates the pointer to the target drag action object. 777 * @param y Indicates the Y coordinate of the touch point. 778 * @return Returns the result code. 779 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 780 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 781 * @since 12 782 */ 783 int32_t OH_ArkUI_DragAction_SetTouchPointY(ArkUI_DragAction* dragAction, float y); 784 785 /** 786 * @brief Sets the drag data. 787 * 788 * @param dragAction Indicates the pointer to the target drag action object. 789 * @param data Indicates the drag data. 790 * @return Returns the result code. 791 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 792 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 793 * @since 12 794 */ 795 int32_t OH_ArkUI_DragAction_SetData(ArkUI_DragAction* dragAction, OH_UdmfData* data); 796 797 /** 798 * @brief Sets an <b>ArkUI_DragPreviewOption</b> object for the specified drag action object. 799 * 800 * @param dragAction Indicates the pointer to the target drag action object. 801 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 802 * @return Returns the result code. 803 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 804 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 805 * @since 12 806 */ 807 int32_t OH_ArkUI_DragAction_SetDragPreviewOption(ArkUI_DragAction* dragAction, ArkUI_DragPreviewOption* option); 808 809 /** 810 * @brief Registers a drag status listener. 811 * This listener can be used to check whether the data is successfully received and processed. 812 * 813 * @param dragAction Indicates the pointer to the target drag action object. 814 * @param userData Indicates the custom user data. 815 * @param listener 816 * Indicates the listener to register. When the callback is invoked, the system returns a pointer to the drag status 817 * object. The pointer is destroyed after the callback is complete and the application should not hold it anymore. 818 * @return Returns the result code. 819 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 820 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 821 * @since 12 822 */ 823 int32_t OH_ArkUI_DragAction_RegisterStatusListener(ArkUI_DragAction* dragAction, void* userData, 824 void(*listener)(ArkUI_DragAndDropInfo* dragAndDropInfo, void* userData)); 825 826 /** 827 * @brief Unregisters a drag status listener. 828 * 829 * @param dragAction Indicates the pointer to the target drag action object. 830 * @since 12 831 */ 832 void OH_ArkUI_DragAction_UnregisterStatusListener(ArkUI_DragAction* dragAction); 833 834 /** 835 * @brief Obtains the drag status of a drag action. 836 * 837 * @param dragAndDropInfo Indicates the drag and drop information returned by the drag status listener. 838 * @return Returns an <b>ArkUI_DragStatus</b> object; returns <b>ArkUI_DRAG_STATUS_UNKNOWN</b> if an error occurs. 839 * @since 12 840 */ 841 ArkUI_DragStatus OH_ArkUI_DragAndDropInfo_GetDragStatus(ArkUI_DragAndDropInfo* dragAndDropInfo); 842 843 /** 844 * @brief Obtains a drag event based on the specified drag and drop information. 845 * The drag event can then be used to obtain the drag result and the drag behavior, please note 846 * other info is not included in such a drag event. 847 * 848 * @param dragAndDropInfo Indicates the drag and drop information returned by the drag status listener. 849 * @return Returns an <b>ArkUI_DragEvent</b> object; returns null if an error occurs. 850 * @since 12 851 */ 852 ArkUI_DragEvent* OH_ArkUI_DragAndDropInfo_GetDragEvent(ArkUI_DragAndDropInfo* dragAndDropInfo); 853 854 /** 855 * @brief Initiates a drag action through the specified drag action object. 856 * 857 * @param dragAction Indicates a drag action object. 858 * @return Returns the result code. 859 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 860 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 861 * @since 12 862 */ 863 int32_t OH_ArkUI_StartDrag(ArkUI_DragAction* dragAction); 864 865 #ifdef __cplusplus 866 }; 867 #endif 868 869 #endif // ARKUI_NATIVE_DRAG_AND_DROP_H 870 /** @} */