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 the <b>Pixelmap</b> struct, which is used to perform operations related to a pixel map. 185 * 186 * @since 12 187 */ 188 typedef struct OH_PixelmapNative OH_PixelmapNative; 189 190 /** 191 * @brief Obtains a <b>ArkUI_DragEvent</b> object from the specified <b>ArkUI_NodeEvent</b> object. 192 * 193 * @param node Indicates the pointer to an <b>ArkUI_NodeEvent</b> object. 194 * @return Returns the pointer to an <b>ArkUI_DragEvent</b> object. 195 * Returns <b>null</b> if the parameter passed in is invalid or is not a drag-related event. 196 * @since 12 197 */ 198 ArkUI_DragEvent* OH_ArkUI_NodeEvent_GetDragEvent(ArkUI_NodeEvent* nodeEvent); 199 200 /** 201 * @brief Obtains the interaction state prior to a drop and drop operation. 202 * 203 * @param node Indicates the pointer to an <b>ArkUI_NodeEvent</b> object. 204 * @return Returns the interaction state prior to the drop and drop operation. 205 * @since 12 206 */ 207 ArkUI_PreDragStatus OH_ArkUI_NodeEvent_GetPreDragStatus(ArkUI_NodeEvent* nodeEvent); 208 209 /** 210 * @brief Sets whether to disable the default drop animation. 211 * The default drop animation is enabled by default and can be disabled to apply a custom drop animation. 212 * 213 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 214 * @param disable Indicates whether to disable the default drop animation. 215 * The value <b>true</b> means to disable the default drop animation, and <b>false</b> means the opposite. 216 * @return Returns the result code. 217 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 218 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 219 * @since 12 220 */ 221 int32_t OH_ArkUI_DragEvent_DisableDefaultDropAnimation(ArkUI_DragEvent* event, bool disable); 222 223 /** 224 * @brief Obtains the drop operation from a drag event. 225 * 226 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 227 * @param operation Indicates the drop operation which the data receiver set. 228 * @return Returns the result code. 229 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 230 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 231 * Possible causes: 1. The given parameters are null or the given event is not a valid DragEvent. 232 * @since 12 233 */ 234 int32_t OH_ArkUI_DragEvent_SetSuggestedDropOperation(ArkUI_DragEvent* event, ArkUI_DropOperation dropOperation); 235 236 /** 237 * @brief Obtains the drop operation from a drag event. 238 * 239 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 240 * @param operation Indicates the drop operation which the data receiver set. 241 * @return Returns the result code. 242 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operations successful. 243 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 244 * @since 12 245 */ 246 int32_t OH_ArkUI_DragEvent_GetDropOperation(ArkUI_DragEvent* event, ArkUI_DropOperation* operation); 247 248 /** 249 * @brief Sets the result for a drag event. 250 * 251 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 252 * @param result Indicates the drag result. 253 * @return Returns the result code. 254 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 255 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 256 * @since 12 257 */ 258 int32_t OH_ArkUI_DragEvent_SetDragResult(ArkUI_DragEvent* event, ArkUI_DragResult result); 259 260 /** 261 * @brief Set drag data for a drag event. 262 * 263 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 264 * @param data Indicates the drag data. 265 * @return Returns the result code. 266 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 267 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 268 * @since 12 269 */ 270 int32_t OH_ArkUI_DragEvent_SetData(ArkUI_DragEvent* event, OH_UdmfData* data); 271 272 /** 273 * @brief Obtains the default drag data from a drag event. 274 * 275 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 276 * @param data Indicates the pointer to an <b>OH_UdmfData</b> object. The application needs to create a pointer 277 * for receiving data by using the {@link OH_UdmfData_Create} method. 278 * @return Returns the result code. 279 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 280 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 281 * @since 12 282 */ 283 int32_t OH_ArkUI_DragEvent_GetUdmfData(ArkUI_DragEvent* event, OH_UdmfData *data); 284 285 /** 286 * @brief Obtains the number of drag data types from a drag event. 287 * 288 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 289 * @param count Indicates the number of drag data types returned. 290 * @return Returns the result code. 291 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 292 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 293 * @since 12 294 */ 295 int32_t OH_ArkUI_DragEvent_GetDataTypeCount(ArkUI_DragEvent* event, int32_t* count); 296 297 /** 298 * @brief Obtains the list of drag data types from a drag event. 299 * 300 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 301 * @param eventTypeArray Indicates the list of the drag data types. You need to create a string array first. 302 * @param length Indicates the total length of the list array. It must be greater than or equal to the number obtained 303 * by using {@link OH_ArkUI_DragEvent_GetDataTypeCount}. 304 * @param maxStrLen Indicates the max string length of drag data types. 305 * @return Returns the result code. 306 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 307 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 308 * Returns {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} if the giving buffer is not enough for string copy. 309 * @since 12 310 */ 311 int32_t OH_ArkUI_DragEvent_GetDataTypes( 312 ArkUI_DragEvent *event, char *eventTypeArray[], int32_t length, int32_t maxStrLen); 313 314 /** 315 * @brief Obtains the drag result from a drag event. 316 * 317 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 318 * @param result Indicates the drag result returned. 319 * @return Returns the result code. 320 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 321 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 322 * @since 12 323 */ 324 int32_t OH_ArkUI_DragEvent_GetDragResult(ArkUI_DragEvent* event, ArkUI_DragResult* result); 325 326 /** 327 * @brief Obtains the X coordinate of the touch point for a drag preview from a drag event. 328 * 329 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 330 * @return Returns the X coordinate of the touch point, in px. 331 * Returns the default value <b>0</b> if the input parameter is invalid. 332 * @since 12 333 */ 334 float OH_ArkUI_DragEvent_GetPreviewTouchPointX(ArkUI_DragEvent* event); 335 336 /** 337 * @brief Obtains the Y coordinate of the touch point for a drag preview from a drag event. 338 * 339 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 340 * @return Returns the Y coordinate of the touch point, in px. 341 * Returns the default value <b>0</b> if the input parameter is invalid. 342 * @since 12 343 */ 344 float OH_ArkUI_DragEvent_GetPreviewTouchPointY(ArkUI_DragEvent* event); 345 346 /** 347 * @brief Obtains the width of a drag preview from a drag event. 348 * 349 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 350 * @return Returns the width of the drag preview, in px. 351 * Returns the default value <b>0</b> if the input parameter is invalid. 352 * @since 12 353 */ 354 float OH_ArkUI_DragEvent_GetPreviewRectWidth(ArkUI_DragEvent* event); 355 356 /** 357 * @brief Obtains the height of a drag preview from a drag event. 358 * 359 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 360 * @return Returns the height of the drag preview, in px. 361 * Returns the default value <b>0</b> if the input parameter is invalid. 362 * @since 12 363 */ 364 float OH_ArkUI_DragEvent_GetPreviewRectHeight(ArkUI_DragEvent* event); 365 366 /** 367 * @brief Obtains the X coordinate of the touch point relative to the window from a drag event. 368 * 369 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 370 * @return Returns the X coordinate of the touch point relative to the window, in px. 371 * Returns the default value <b>0</b> if the input parameter is invalid. 372 * @since 12 373 */ 374 float OH_ArkUI_DragEvent_GetTouchPointXToWindow(ArkUI_DragEvent* event); 375 376 /** 377 * @brief Obtains the Y coordinate of the touch point relative to the window from a drag event. 378 * 379 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 380 * @return Returns the Y coordinate of the touch point relative to the window, in px. 381 * Returns the default value <b>0</b> if the input parameter is invalid. 382 * @since 12 383 */ 384 float OH_ArkUI_DragEvent_GetTouchPointYToWindow(ArkUI_DragEvent* event); 385 386 /** 387 * @brief Obtains the X coordinate of the touch point relative to the current display from a drag event. 388 * 389 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 390 * @return Returns the X coordinate of the touch point relative to the current display, in px. 391 * Returns the default value <b>0</b> if the input parameter is invalid. 392 * @since 12 393 */ 394 float OH_ArkUI_DragEvent_GetTouchPointXToDisplay(ArkUI_DragEvent* event); 395 396 /** 397 * @brief Obtains the Y coordinate of the touch point relative to the current display from a drag event. 398 * 399 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 400 * @return Returns the Y coordinate of the touch point relative to the current display, in px. 401 * Returns the default value <b>0</b> if the input parameter is invalid. 402 * @since 12 403 */ 404 float OH_ArkUI_DragEvent_GetTouchPointYToDisplay(ArkUI_DragEvent* event); 405 406 /** 407 * @brief Obtains the dragging velocity along the x-axis. 408 * 409 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 410 * @return Returns the dragging velocity along the x-axis, in px. 411 * Returns the default value <b>0</b> if the input parameter is invalid. 412 * @since 12 413 */ 414 float OH_ArkUI_DragEvent_GetVelocityX(ArkUI_DragEvent* event); 415 416 /** 417 * @brief Obtains the dragging velocity along the y-axis. 418 * 419 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 420 * @return Returns the dragging velocity along the y-axis, in px. 421 * Returns the default value <b>0</b> if the input parameter is invalid. 422 * @since 12 423 */ 424 float OH_ArkUI_DragEvent_GetVelocityY(ArkUI_DragEvent* event); 425 426 /** 427 * @brief Obtains the dragging velocity along the main axis. 428 * 429 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 430 * @return Returns the dragging velocity along the main axis, in px. 431 * Returns the default value <b>0</b> if the input parameter is invalid. 432 * @since 12 433 */ 434 float OH_ArkUI_DragEvent_GetVelocity(ArkUI_DragEvent* event); 435 436 /** 437 * @brief Obtains the pressed status of modifier keys from a drag event. 438 * 439 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 440 * @param keys Indicates the returned combination of modifier keys that are currently pressed. 441 * The application can determine the pressed modifier keys through bitwise operations. 442 * @return Returns the result code. 443 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 444 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 445 * @since 12 446 */ 447 int32_t OH_ArkUI_DragEvent_GetModifierKeyStates(ArkUI_DragEvent* event, uint64_t* keys); 448 449 /** 450 * @brief Sets whether to enable strict reporting on drag events. 451 * This feature is disabled by default, and you are advised to enable it. 452 * If this feature is disabled, the parent component is not notified when an item in it is dragged over its child 453 * component. If this feature is enabled, the component is notified of the dragged item's leaving, and the chil 454 * component to which the dragged item is dropped is notified of the item's entering. This configuration is 455 * related to a specific UI instance. You can pass in a specific component node on the current UI instance 456 * for association. 457 * 458 * @param node Indicates the pointer to a component node. 459 * @param enabled Indicates whether to enable strict reporting on drag events. 460 * @return Returns the result code. 461 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 462 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 463 * @since 12 464 */ 465 int32_t OH_ArkUI_SetDragEventStrictReportWithNode(ArkUI_NodeHandle node, bool enabled); 466 467 /** 468 * @brief Sets whether to enable strict reporting on drag events. 469 * This feature is disabled by default, and you are advised to enable it. 470 * If this feature is disabled, the parent component is not notified when an item in it is dragged over its child 471 * component. If this feature is enabled, the component is notified of the dragged item's leaving, and the child 472 * component to which the dragged item is dropped is notified of the item's entering. This configuration is 473 * related to a specific UI instance. You can pass in a specific UI instance for association. 474 * 475 * @param uiContext Indicates the pointer to a UI instance. 476 * @param enabled Indicates whether to enable strict reporting on drag events. 477 * @return Returns the result code. 478 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 479 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 480 * @since 12 481 */ 482 int32_t OH_ArkUI_SetDragEventStrictReportWithContext(ArkUI_ContextHandle uiContext, bool enabled); 483 484 /** 485 * @brief Sets the types of data that can be dropped to the specified component. This API resets the settings configured 486 * through {@link OH_ArkUI_DisallowNodeAnyDropDataTypes} and {@link OH_ArkUI_AllowNodeAllDropDataTypes}. 487 * 488 * @param node Indicates the pointer to a component node. 489 * @param typesArray Indicates the array of types of data that can be dropped. 490 * @param count Indicates length of an array. 491 * @return Returns the result code. 492 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 493 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 494 * @since 12 495 */ 496 int32_t OH_ArkUI_SetNodeAllowedDropDataTypes(ArkUI_NodeHandle node, const char* typesArray[], int32_t count); 497 498 /** 499 * @brief Configures the specified component to disallow any data types. This API resets the settings configured through 500 * {@link OH_ArkUI_SetNodeAllowedDropDataTypes}. 501 * 502 * @param node Indicates the pointer to a component node. 503 * @return Returns the result code. 504 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 505 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 506 * @since 12 507 */ 508 int32_t OH_ArkUI_DisallowNodeAnyDropDataTypes(ArkUI_NodeHandle node); 509 510 /** 511 * @brief Configures the specified component to allow any data types. This API resets the settings configured through 512 * {@link OH_ArkUI_SetNodeAllowedDropDataTypes}. 513 * 514 * @param node Indicates the pointer to a component node. 515 * @return Returns the result code. 516 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 517 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 518 * @since 12 519 */ 520 int32_t OH_ArkUI_AllowNodeAllDropDataTypes(ArkUI_NodeHandle node); 521 522 /** 523 * @brief Sets whether the specified component is draggable. 524 * 525 * @param node Indicates the pointer to a component node. 526 * @param bool Indicates whether the component is draggable. 527 * @return Returns the result code. 528 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 529 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 530 * @since 12 531 */ 532 int32_t OH_ArkUI_SetNodeDraggable(ArkUI_NodeHandle node, bool enabled); 533 534 /** 535 * @brief Sets a custom drag preview for the specified component. 536 * 537 * @param node Indicates the pointer to a component node. 538 * @param preview Indicates the custom drag preview, which is a pixel map. 539 * @return Returns the result code. 540 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 541 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 542 * @since 12 543 */ 544 int32_t OH_ArkUI_SetNodeDragPreview(ArkUI_NodeHandle node, OH_PixelmapNative* preview); 545 546 /** 547 * @brief Creates an <b>ArkUI_DragPreviewOption</b> object. 548 * 549 * @return Returns the created <b>ArkUI_DragPreviewOption</b> object. 550 * @since 12 551 */ 552 ArkUI_DragPreviewOption* OH_ArkUI_CreateDragPreviewOption(void); 553 554 /** 555 * @brief Disposes of a <b>ArkUI_DragPreviewOption</b> object. 556 * 557 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 558 * @since 12 559 */ 560 void OH_ArkUI_DragPreviewOption_Dispose(ArkUI_DragPreviewOption* option); 561 562 /** 563 * @brief Sets the scale mode for an <b>ArkUI_DragPreviewOption</b> object. 564 * 565 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 566 * @param scaleMode Indicates the scale mode. 567 * @return Returns the result code. 568 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 569 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 570 * @since 12 571 */ 572 int32_t OH_ArkUI_DragPreviewOption_SetScaleMode(ArkUI_DragPreviewOption* option, ArkUI_DragPreviewScaleMode scaleMode); 573 574 /** 575 * @brief Sets whether to enable the shadow effect for an <b>ArkUI_DragPreviewOption</b> object. 576 * The shadow effect is enabled by default. 577 * 578 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 579 * @param enabled Indicates whether to enable the shadow effect. 580 * @return Returns the result code. 581 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 582 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 583 * @since 12 584 */ 585 int32_t OH_ArkUI_DragPreviewOption_SetDefaultShadowEnabled(ArkUI_DragPreviewOption* option, bool enabled); 586 587 /** 588 * @brief Sets whether to enable the rounded corner effect for an <b>ArkUI_DragPreviewOption</b> object. 589 * The rounded corner effect is enabled by default. 590 * 591 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 592 * @param enabled Indicates whether to enable the rounded corner effect. 593 * @return Returns the result code. 594 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 595 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 596 * @since 12 597 */ 598 int32_t OH_ArkUI_DragPreviewOption_SetDefaultRadiusEnabled(ArkUI_DragPreviewOption* option, bool enabled); 599 600 /** 601 * @brief Sets whether to enable the badge for an <b>ArkUI_DragPreviewOption</b> object. 602 * If this feature is enabled, a badge that contains the number of dragged items is displayed. 603 * 604 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 605 * @param enabled Indicates whether to enable badge. 606 * @return Returns the result code. 607 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 608 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 609 * @since 12 610 */ 611 int32_t OH_ArkUI_DragPreviewOption_SetNumberBadgeEnabled(ArkUI_DragPreviewOption* option, bool enabled); 612 613 /** 614 * @brief Sets the count on the badge. 615 * The settings will overwrite the value in the <b>SetDragPreviewNumberBadgeEnabled</b> API. 616 * 617 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 618 * @param forcedNumber Indicates the count on the badge. 619 * @return Returns the result code. 620 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 621 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 622 * @since 12 623 */ 624 int32_t OH_ArkUI_DragPreviewOption_SetBadgeNumber(ArkUI_DragPreviewOption* option, uint32_t forcedNumber); 625 626 /** 627 * @brief Sets whether to enable the default animation on a click or touch, it's not used in drag action. 628 * 629 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 630 * @param enabled Indicates whether to enable the default animation on a click or touch. 631 * @return Returns the result code. 632 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 633 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 634 * @since 12 635 */ 636 int32_t OH_ArkUI_DragPreviewOption_SetDefaultAnimationBeforeLiftingEnabled( 637 ArkUI_DragPreviewOption* option, bool enabled); 638 /** 639 * @brief Sets an <b>ArkUI_DragPreviewOption</b> object for the specified component. 640 * 641 * @param node Indicates the pointer to a component node. 642 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 643 * @return Returns the result code. 644 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 645 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 646 * @since 12 647 */ 648 int32_t OH_ArkUI_SetNodeDragPreviewOption(ArkUI_NodeHandle node, ArkUI_DragPreviewOption* option); 649 650 /** 651 * @brief Creates a drag action object for a UI instance based on the specified component node of the current 652 * UI instance. 653 * 654 * @param node Indicates the pointer to a component node. 655 * @return Returns the pointer to the created drag action object; returns null if the operation fails. 656 * @since 12 657 */ 658 ArkUI_DragAction* OH_ArkUI_CreateDragActionWithNode(ArkUI_NodeHandle node); 659 660 /** 661 * @brief Creates a drag action object for the specified UI instance. 662 * 663 * @param uiContext Indicates the pointer to a UI instance. 664 * @return Returns the pointer to the created drag action object; returns null if the operation fails. 665 * @since 12 666 */ 667 ArkUI_DragAction* OH_ArkUI_CreateDragActionWithContext(ArkUI_ContextHandle uiContext); 668 669 /** 670 * @brief Disposes of a drag action object. 671 * 672 * @param dragAction Indicates the pointer to the target drag action object. 673 * @since 12 674 */ 675 void OH_ArkUI_DragAction_Dispose(ArkUI_DragAction* dragAction); 676 677 /** 678 * @brief Sets the pointer ID. If only one finger is operating on the screen, the pointer ID is 0. 679 * In general cases, you can set the pointer ID to 0. 680 * 681 * @param dragAction Indicates the pointer to the target drag action object. 682 * @param pointer Indicates the pointer ID. The value ranges from 0 to 9. 683 * @return Returns the result code. 684 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 685 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 686 * @since 12 687 */ 688 int32_t OH_ArkUI_DragAction_SetPointerId(ArkUI_DragAction* dragAction, int32_t pointer); 689 690 /** 691 * @brief Sets the drag previews for a drag action. 692 * 693 * @param dragAction Indicates the pointer to the target drag action object. 694 * @param pixelmapArray Indicates the array of the drag previews to set, which must be pixel maps. 695 * @param size Indicates the size of the drag preview array. 696 * @return Returns the result code. 697 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 698 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 699 * @since 12 700 */ 701 int32_t OH_ArkUI_DragAction_SetPixelMaps( 702 ArkUI_DragAction* dragAction, OH_PixelmapNative* pixelmapArray[], int32_t size); 703 704 /** 705 * @brief Sets the touch point relative to the upper left corner of the first drag preview (pixel map). 706 * 707 * @param dragAction Indicates the pointer to the target drag action object. 708 * @param x Indicates the X coordinate of the touch point. 709 * @return Returns the result code. 710 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 711 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 712 * @since 12 713 */ 714 int32_t OH_ArkUI_DragAction_SetTouchPointX(ArkUI_DragAction* dragAction, float x); 715 716 /** 717 * @brief Sets the touch point relative to the upper left corner of the first drag preview (pixel map). 718 * 719 * @param dragAction Indicates the pointer to the target drag action object. 720 * @param y Indicates the Y coordinate of the touch point. 721 * @return Returns the result code. 722 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 723 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 724 * @since 12 725 */ 726 int32_t OH_ArkUI_DragAction_SetTouchPointY(ArkUI_DragAction* dragAction, float y); 727 728 /** 729 * @brief Sets the drag data. 730 * 731 * @param dragAction Indicates the pointer to the target drag action object. 732 * @param data Indicates the drag data. 733 * @return Returns the result code. 734 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 735 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 736 * @since 12 737 */ 738 int32_t OH_ArkUI_DragAction_SetData(ArkUI_DragAction* dragAction, OH_UdmfData* data); 739 740 /** 741 * @brief Sets an <b>ArkUI_DragPreviewOption</b> object for the specified drag action object. 742 * 743 * @param dragAction Indicates the pointer to the target drag action object. 744 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 745 * @return Returns the result code. 746 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 747 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 748 * @since 12 749 */ 750 int32_t OH_ArkUI_DragAction_SetDragPreviewOption(ArkUI_DragAction* dragAction, ArkUI_DragPreviewOption* option); 751 752 /** 753 * @brief Registers a drag status listener. 754 * This listener can be used to check whether the data is successfully received and processed. 755 * 756 * @param dragAction Indicates the pointer to the target drag action object. 757 * @param userData Indicates the custom user data. 758 * @param listener 759 * Indicates the listener to register. When the callback is invoked, the system returns a pointer to the drag status 760 * object. The pointer is destroyed after the callback is complete and the application should not hold it anymore. 761 * @return Returns the result code. 762 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 763 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 764 * @since 12 765 */ 766 int32_t OH_ArkUI_DragAction_RegisterStatusListener(ArkUI_DragAction* dragAction, void* userData, 767 void(*listener)(ArkUI_DragAndDropInfo* dragAndDropInfo, void* userData)); 768 769 /** 770 * @brief Unregisters a drag status listener. 771 * 772 * @param dragAction Indicates the pointer to the target drag action object. 773 * @since 12 774 */ 775 void OH_ArkUI_DragAction_UnregisterStatusListener(ArkUI_DragAction* dragAction); 776 777 /** 778 * @brief Obtains the drag status of a drag action. 779 * 780 * @param dragAndDropInfo Indicates the drag and drop information returned by the drag status listener. 781 * @return Returns an <b>ArkUI_DragStatus</b> object; returns <b>ArkUI_DRAG_STATUS_UNKNOWN</b> if an error occurs. 782 * @since 12 783 */ 784 ArkUI_DragStatus OH_ArkUI_DragAndDropInfo_GetDragStatus(ArkUI_DragAndDropInfo* dragAndDropInfo); 785 786 /** 787 * @brief Obtains a drag event based on the specified drag and drop information. 788 * The drag event can then be used to obtain the drag result and the drag behavior, please note 789 * other info is not included in such a drag event. 790 * 791 * @param dragAndDropInfo Indicates the drag and drop information returned by the drag status listener. 792 * @return Returns an <b>ArkUI_DragEvent</b> object; returns null if an error occurs. 793 * @since 12 794 */ 795 ArkUI_DragEvent* OH_ArkUI_DragAndDropInfo_GetDragEvent(ArkUI_DragAndDropInfo* dragAndDropInfo); 796 797 /** 798 * @brief Initiates a drag action through the specified drag action object. 799 * 800 * @param dragAction Indicates a drag action object. 801 * @return Returns the result code. 802 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 803 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 804 * @since 12 805 */ 806 int32_t OH_ArkUI_StartDrag(ArkUI_DragAction* dragAction); 807 808 #ifdef __cplusplus 809 }; 810 #endif 811 812 #endif // ARKUI_NATIVE_DRAG_AND_DROP_H 813 /** @} */