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 * @kit ArkUI 32 * @syscap SystemCapability.ArkUI.ArkUI.Full 33 * @since 12 34 */ 35 36 #ifndef ARKUI_NATIVE_DRAG_AND_DROP_H 37 #define ARKUI_NATIVE_DRAG_AND_DROP_H 38 39 #include <stdint.h> 40 41 #include "native_type.h" 42 #include "database/udmf/udmf.h" 43 #include "multimedia/image_framework/image/pixelmap_native.h" 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 /** 50 * @brief Defines an enum for drag results, which are set by the data receiver and transferred by the system to the 51 * drag source so that the drag source is aware of the data processing result of the receiver. 52 * 53 * @since 12 54 */ 55 typedef enum { 56 /** The drag and drop operation succeeded. */ 57 ARKUI_DRAG_RESULT_SUCCESSFUL = 0, 58 /** The drag and drop operation failed. */ 59 ARKUI_DRAG_RESULT_FAILED, 60 /** The drag and drop operation was canceled. */ 61 ARKUI_DRAG_RESULT_CANCELED, 62 } ArkUI_DragResult; 63 64 /** 65 * @brief Defines an enum for data processing modes used when data is dropped, which affects the display of the badge. 66 * 67 * @since 12 68 */ 69 typedef enum { 70 /** Copy. */ 71 ARKUI_DROP_OPERATION_COPY = 0, 72 /** Cut. */ 73 ARKUI_DROP_OPERATION_MOVE, 74 } ArkUI_DropOperation; 75 76 /** 77 * @brief Defines an enum for interaction states prior to a drop and drop operation. 78 * 79 * @since 12 80 */ 81 typedef enum { 82 /** Unknown. */ 83 ARKUI_PRE_DRAG_STATUS_UNKNOWN = -1, 84 /** A drag gesture is being detected. */ 85 ARKUI_PRE_DRAG_STATUS_ACTION_DETECTING, 86 /** The component is ready to be dragged. */ 87 ARKUI_PRE_DRAG_STATUS_READY_TO_TRIGGER_DRAG, 88 /** A lift animation is started. */ 89 ARKUI_PRE_DRAG_STATUS_PREVIEW_LIFT_STARTED, 90 /** A lift animation is finished. */ 91 ARKUI_PRE_DRAG_STATUS_PREVIEW_LIFT_FINISHED, 92 /** A drop animation is started. */ 93 ARKUI_PRE_DRAG_STATUS_PREVIEW_LANDING_STARTED, 94 /** A drop animation is finished. */ 95 ARKUI_PRE_DRAG_STATUS_PREVIEW_LANDING_FINISHED, 96 /** A drop animation is terminated. */ 97 ARKUI_PRE_DRAG_STATUS_CANCELED_BEFORE_DRAG, 98 } ArkUI_PreDragStatus; 99 100 /** 101 * @brief Defines an enum for drag preview scale modes. 102 * 103 * @since 12 104 */ 105 typedef enum { 106 /** 107 * The system automatically changes the position of the dragged point based on the scenario and 108 * scales the drag preview based on set rules. 109 */ 110 ARKUI_DRAG_PREVIEW_SCALE_AUTO = 0, 111 /** The system does not scale the drag preview. */ 112 ARKUI_DRAG_PREVIEW_SCALE_DISABLED, 113 } ArkUI_DragPreviewScaleMode; 114 115 /** 116 * @brief Defines an enum for drag states. 117 * 118 * @since 12 119 */ 120 typedef enum { 121 /** Unknown. */ 122 ARKUI_DRAG_STATUS_UNKNOWN = -1, 123 /** Started. */ 124 ARKUI_DRAG_STATUS_STARTED, 125 /** Ended. */ 126 ARKUI_DRAG_STATUS_ENDED, 127 } ArkUI_DragStatus; 128 129 /** 130 * @brief Defines a struct for a component event. 131 * 132 * @since 12 133 */ 134 typedef struct ArkUI_NodeEvent ArkUI_NodeEvent; 135 136 /** 137 * @brief Defines a struct for a UI context object. 138 * 139 * @since 12 140 */ 141 typedef struct ArkUI_Context ArkUI_Context; 142 143 /** 144 * @brief Defines a struct for a UI context object pointer. 145 * 146 * @since 12 147 */ 148 typedef struct ArkUI_Context* ArkUI_ContextHandle; 149 150 /** 151 * @brief Defines a struct for a drag event. 152 * 153 * @since 12 154 */ 155 typedef struct ArkUI_DragEvent ArkUI_DragEvent; 156 157 /** 158 * @brief Defines a struct for custom drag preview options. 159 * 160 * @since 12 161 */ 162 typedef struct ArkUI_DragPreviewOption ArkUI_DragPreviewOption; 163 164 /** 165 * @brief Defines a struct for a drag action. 166 * 167 * @since 12 168 */ 169 typedef struct ArkUI_DragAction ArkUI_DragAction; 170 171 /** 172 * @brief Defines a struct for drag and drop information returned through a drag status listener. 173 * 174 * @since 12 175 */ 176 typedef struct ArkUI_DragAndDropInfo ArkUI_DragAndDropInfo; 177 178 /** 179 * @brief Obtains a <b>ArkUI_DragEvent</b> object from the specified <b>ArkUI_NodeEvent</b> object. 180 * 181 * @param nodeEvent Indicates the pointer to an <b>ArkUI_NodeEvent</b> object. 182 * @return Returns the pointer to an <b>ArkUI_DragEvent</b> object. 183 * Returns <b>null</b> if the parameter passed in is invalid or is not a drag-related event. 184 * @since 12 185 */ 186 ArkUI_DragEvent* OH_ArkUI_NodeEvent_GetDragEvent(ArkUI_NodeEvent* nodeEvent); 187 188 /** 189 * @brief Obtains the interaction state prior to a drop and drop operation. 190 * 191 * @param nodeEvent Indicates the pointer to an <b>ArkUI_NodeEvent</b> object. 192 * @return Returns the interaction state prior to the drop and drop operation. 193 * @since 12 194 */ 195 ArkUI_PreDragStatus OH_ArkUI_NodeEvent_GetPreDragStatus(ArkUI_NodeEvent* nodeEvent); 196 197 /** 198 * @brief Sets whether to disable the default drop animation. 199 * The default drop animation is enabled by default and can be disabled to apply a custom drop animation. 200 * 201 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 202 * @param disable Indicates whether to disable the default drop animation. 203 * The value <b>true</b> means to disable the default drop animation, and <b>false</b> means the opposite. 204 * @return Returns the result code. 205 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 206 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 207 * @since 12 208 */ 209 int32_t OH_ArkUI_DragEvent_DisableDefaultDropAnimation(ArkUI_DragEvent* event, bool disable); 210 211 /** 212 * @brief Sets the data processing mode. 213 * 214 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 215 * @param dropOperation Indicates the data processing mode. 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_SetSuggestedDropOperation(ArkUI_DragEvent* event, ArkUI_DropOperation dropOperation); 222 223 /** 224 * @brief Sets the result for a drag event. 225 * 226 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 227 * @param result Indicates the drag result. 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 * @since 12 232 */ 233 int32_t OH_ArkUI_DragEvent_SetDragResult(ArkUI_DragEvent* event, ArkUI_DragResult result); 234 235 /** 236 * @brief Set drag data for a drag event. 237 * 238 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 239 * @param data Indicates the drag data. 240 * @return Returns the result code. 241 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 242 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 243 * @since 12 244 */ 245 int32_t OH_ArkUI_DragEvent_SetData(ArkUI_DragEvent* event, OH_UdmfData* data); 246 247 /** 248 * @brief Obtains the default drag data from a drag event. 249 * 250 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 251 * @param data Indicates the pointer to an <b>OH_UdmfData</b> object. The application needs to create a pointer 252 * for receiving data by using the {@link OH_UdmfData_Create} method. 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_GetUdmfData(ArkUI_DragEvent* event, OH_UdmfData *data); 259 260 /** 261 * @brief Obtains the number of drag data types from a drag event. 262 * 263 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 264 * @param count Indicates the number of drag data types returned. 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_GetDataTypeCount(ArkUI_DragEvent* event, int32_t* count); 271 272 /** 273 * @brief Obtains the list of drag data types from a drag event. 274 * 275 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 276 * @param eventTypeArray Indicates the list of the drag data types. You need to create a string array first. 277 * @param length Indicates the total length of the list array. It must be greater than or equal to the number obtained 278 * by using {@link OH_ArkUI_DragEvent_GetDataTypeCount}. 279 * @param maxStrLen Indicates the max string length of drag data types. 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 * Returns {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} if the giving buffer is not enough for string copy. 284 * @since 12 285 */ 286 int32_t OH_ArkUI_DragEvent_GetDataTypes( 287 ArkUI_DragEvent *event, char *eventTypeArray[], int32_t length, int32_t maxStrLen); 288 289 /** 290 * @brief Obtains the drag result from a drag event. 291 * 292 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 293 * @param result Indicates the drag result returned. 294 * @return Returns the result code. 295 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 296 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 297 * @since 12 298 */ 299 int32_t OH_ArkUI_DragEvent_GetDragResult(ArkUI_DragEvent* event, ArkUI_DragResult* result); 300 301 /** 302 * @brief Obtains the drop operation from a drag event. 303 * 304 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 305 * @param operation Indicates the drop operation which the data receiver set. 306 * @return Returns the result code. 307 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 308 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 309 * Possible causes: 1. The given parameters are null or the given event is not a valid DragEvent. 310 * @since 12 311 */ 312 int32_t OH_ArkUI_DragEvent_GetDropOperation(ArkUI_DragEvent* event, ArkUI_DropOperation* operation); 313 314 /** 315 * @brief Obtains the X coordinate of the touch point for a drag preview from a drag event. 316 * 317 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 318 * @return Returns the X coordinate of the touch point, in px. 319 * Returns the default value <b>0</b> if the input parameter is invalid. 320 * @since 12 321 */ 322 float OH_ArkUI_DragEvent_GetPreviewTouchPointX(ArkUI_DragEvent* event); 323 324 /** 325 * @brief Obtains the Y coordinate of the touch point for a drag preview from a drag event. 326 * 327 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 328 * @return Returns the Y coordinate of the touch point, in px. 329 * Returns the default value <b>0</b> if the input parameter is invalid. 330 * @since 12 331 */ 332 float OH_ArkUI_DragEvent_GetPreviewTouchPointY(ArkUI_DragEvent* event); 333 334 /** 335 * @brief Obtains the width of a drag preview from a drag event. 336 * 337 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 338 * @return Returns the width of the drag preview, in px. 339 * Returns the default value <b>0</b> if the input parameter is invalid. 340 * @since 12 341 */ 342 float OH_ArkUI_DragEvent_GetPreviewRectWidth(ArkUI_DragEvent* event); 343 344 /** 345 * @brief Obtains the height of a drag preview from a drag event. 346 * 347 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 348 * @return Returns the height of the drag preview, in px. 349 * Returns the default value <b>0</b> if the input parameter is invalid. 350 * @since 12 351 */ 352 float OH_ArkUI_DragEvent_GetPreviewRectHeight(ArkUI_DragEvent* event); 353 354 /** 355 * @brief Obtains the X coordinate of the touch point relative to the window from a drag event. 356 * 357 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 358 * @return Returns the X coordinate of the touch point relative to the window, in px. 359 * Returns the default value <b>0</b> if the input parameter is invalid. 360 * @since 12 361 */ 362 float OH_ArkUI_DragEvent_GetTouchPointXToWindow(ArkUI_DragEvent* event); 363 364 /** 365 * @brief Obtains the Y coordinate of the touch point relative to the window from a drag event. 366 * 367 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 368 * @return Returns the Y coordinate of the touch point relative to the window, in px. 369 * Returns the default value <b>0</b> if the input parameter is invalid. 370 * @since 12 371 */ 372 float OH_ArkUI_DragEvent_GetTouchPointYToWindow(ArkUI_DragEvent* event); 373 374 /** 375 * @brief Obtains the X coordinate of the touch point relative to the current display from a drag event. 376 * 377 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 378 * @return Returns the X coordinate of the touch point relative to the current display, in px. 379 * Returns the default value <b>0</b> if the input parameter is invalid. 380 * @since 12 381 */ 382 float OH_ArkUI_DragEvent_GetTouchPointXToDisplay(ArkUI_DragEvent* event); 383 384 /** 385 * @brief Obtains the Y coordinate of the touch point relative to the current display from a drag event. 386 * 387 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 388 * @return Returns the Y coordinate of the touch point relative to the current display, in px. 389 * Returns the default value <b>0</b> if the input parameter is invalid. 390 * @since 12 391 */ 392 float OH_ArkUI_DragEvent_GetTouchPointYToDisplay(ArkUI_DragEvent* event); 393 394 /** 395 * @brief Obtains the dragging velocity along the x-axis. 396 * 397 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 398 * @return Returns the dragging velocity along the x-axis, in px. 399 * Returns the default value <b>0</b> if the input parameter is invalid. 400 * @since 12 401 */ 402 float OH_ArkUI_DragEvent_GetVelocityX(ArkUI_DragEvent* event); 403 404 /** 405 * @brief Obtains the dragging velocity along the y-axis. 406 * 407 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 408 * @return Returns the dragging velocity along the y-axis, in px. 409 * Returns the default value <b>0</b> if the input parameter is invalid. 410 * @since 12 411 */ 412 float OH_ArkUI_DragEvent_GetVelocityY(ArkUI_DragEvent* event); 413 414 /** 415 * @brief Obtains the dragging velocity along the main axis. 416 * 417 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 418 * @return Returns the dragging velocity along the main axis, in px. 419 * Returns the default value <b>0</b> if the input parameter is invalid. 420 * @since 12 421 */ 422 float OH_ArkUI_DragEvent_GetVelocity(ArkUI_DragEvent* event); 423 424 /** 425 * @brief Obtains the pressed status of modifier keys from a drag event. 426 * 427 * @param event Indicates the pointer to an <b>ArkUI_DragEvent</b> object. 428 * @param keys Indicates the returned combination of modifier keys that are currently pressed. 429 * The application can determine the pressed modifier keys through bitwise operations. 430 * @return Returns the result code. 431 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 432 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 433 * @since 12 434 */ 435 int32_t OH_ArkUI_DragEvent_GetModifierKeyStates(ArkUI_DragEvent* event, uint64_t* keys); 436 437 /** 438 * @brief Sets whether to enable strict reporting on drag events. 439 * This feature is disabled by default, and you are advised to enable it. 440 * If this feature is disabled, the parent component is not notified when an item in it is dragged over its child 441 * component. If this feature is enabled, the component is notified of the dragged item's leaving, and the chil 442 * component to which the dragged item is dropped is notified of the item's entering. This configuration is 443 * related to a specific UI instance. You can pass in a specific component node on the current UI instance 444 * for association. 445 * 446 * @param node Indicates the pointer to a component node. 447 * @param enabled Indicates whether to enable strict reporting on drag events. 448 * @return Returns the result code. 449 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 450 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 451 * @since 12 452 */ 453 int32_t OH_ArkUI_SetDragEventStrictReportWithNode(ArkUI_NodeHandle node, bool enabled); 454 455 /** 456 * @brief Sets whether to enable strict reporting on drag events. 457 * This feature is disabled by default, and you are advised to enable it. 458 * If this feature is disabled, the parent component is not notified when an item in it is dragged over its child 459 * component. If this feature is enabled, the component is notified of the dragged item's leaving, and the child 460 * component to which the dragged item is dropped is notified of the item's entering. This configuration is 461 * related to a specific UI instance. You can pass in a specific UI instance for association. 462 * 463 * @param uiContext Indicates the pointer to a UI instance. 464 * @param enabled Indicates whether to enable strict reporting on drag events. 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 * @since 12 469 */ 470 int32_t OH_ArkUI_SetDragEventStrictReportWithContext(ArkUI_ContextHandle uiContext, bool enabled); 471 472 /** 473 * @brief Sets the types of data that can be dropped to the specified component. This API resets the settings configured 474 * through {@link OH_ArkUI_DisallowNodeAnyDropDataTypes} and {@link OH_ArkUI_AllowNodeAllDropDataTypes}. 475 * 476 * @param node Indicates the pointer to a component node. 477 * @param typesArray Indicates the array of types of data that can be dropped. 478 * @param count Indicates length of an array. 479 * @return Returns the result code. 480 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 481 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 482 * @since 12 483 */ 484 int32_t OH_ArkUI_SetNodeAllowedDropDataTypes(ArkUI_NodeHandle node, const char* typesArray[], int32_t count); 485 486 /** 487 * @brief Configures the specified component to disallow any data types. This API resets the settings configured through 488 * {@link OH_ArkUI_SetNodeAllowedDropDataTypes}. 489 * 490 * @param node Indicates the pointer to a component node. 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_DisallowNodeAnyDropDataTypes(ArkUI_NodeHandle node); 497 498 /** 499 * @brief Configures the specified component to allow 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_AllowNodeAllDropDataTypes(ArkUI_NodeHandle node); 509 510 /** 511 * @brief Sets whether the specified component is draggable. 512 * 513 * @param node Indicates the pointer to a component node. 514 * @param bool Indicates whether the component is draggable. 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_SetNodeDraggable(ArkUI_NodeHandle node, bool enabled); 521 522 /** 523 * @brief Sets a custom drag preview for the specified component. 524 * 525 * @param node Indicates the pointer to a component node. 526 * @param preview Indicates the custom drag preview, which is a pixel map. 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_SetNodeDragPreview(ArkUI_NodeHandle node, OH_PixelmapNative* preview); 533 534 /** 535 * @brief Creates an <b>ArkUI_DragPreviewOption</b> object. 536 * 537 * @return Returns the created <b>ArkUI_DragPreviewOption</b> object. 538 * @since 12 539 */ 540 ArkUI_DragPreviewOption* OH_ArkUI_CreateDragPreviewOption(void); 541 542 /** 543 * @brief Disposes of a <b>ArkUI_DragPreviewOption</b> object. 544 * 545 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 546 * @since 12 547 */ 548 void OH_ArkUI_DragPreviewOption_Dispose(ArkUI_DragPreviewOption* option); 549 550 /** 551 * @brief Sets the scale mode for an <b>ArkUI_DragPreviewOption</b> object. 552 * 553 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 554 * @param scaleMode Indicates the scale mode. 555 * @return Returns the result code. 556 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 557 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 558 * @since 12 559 */ 560 int32_t OH_ArkUI_DragPreviewOption_SetScaleMode(ArkUI_DragPreviewOption* option, ArkUI_DragPreviewScaleMode scaleMode); 561 562 /** 563 * @brief Sets whether to enable the shadow effect for an <b>ArkUI_DragPreviewOption</b> object. 564 * The shadow effect is enabled by default. 565 * 566 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 567 * @param enabled Indicates whether to enable the shadow effect. 568 * @return Returns the result code. 569 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 570 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 571 * @since 12 572 */ 573 int32_t OH_ArkUI_DragPreviewOption_SetDefaultShadowEnabled(ArkUI_DragPreviewOption* option, bool enabled); 574 575 /** 576 * @brief Sets whether to enable the rounded corner effect for an <b>ArkUI_DragPreviewOption</b> object. 577 * The rounded corner effect is enabled by default. 578 * 579 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 580 * @param enabled Indicates whether to enable the rounded corner effect. 581 * @return Returns the result code. 582 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 583 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 584 * @since 12 585 */ 586 int32_t OH_ArkUI_DragPreviewOption_SetDefaultRadiusEnabled(ArkUI_DragPreviewOption* option, bool enabled); 587 588 /** 589 * @brief Sets whether to enable the badge for an <b>ArkUI_DragPreviewOption</b> object. 590 * If this feature is enabled, a badge that contains the number of dragged items is displayed. 591 * 592 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 593 * @param enabled Indicates whether to enable badge. 594 * @return Returns the result code. 595 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 596 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 597 * @since 12 598 */ 599 int32_t OH_ArkUI_DragPreviewOption_SetNumberBadgeEnabled(ArkUI_DragPreviewOption* option, bool enabled); 600 601 /** 602 * @brief Sets the count on the badge. 603 * The settings will overwrite the value in the <b>SetDragPreviewNumberBadgeEnabled</b> API. 604 * 605 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 606 * @param forcedNumber Indicates the count on the badge. 607 * @return Returns the result code. 608 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 609 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 610 * @since 12 611 */ 612 int32_t OH_ArkUI_DragPreviewOption_SetBadgeNumber(ArkUI_DragPreviewOption* option, uint32_t forcedNumber); 613 614 /** 615 * @brief Sets whether to enable the default animation on a click or touch, it's not used in drag action. 616 * 617 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 618 * @param enabled Indicates whether to enable the default animation on a click or touch. 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_SetDefaultAnimationBeforeLiftingEnabled( 625 ArkUI_DragPreviewOption* option, bool enabled); 626 /** 627 * @brief Sets an <b>ArkUI_DragPreviewOption</b> object for the specified component. 628 * 629 * @param node Indicates the pointer to a component node. 630 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 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_SetNodeDragPreviewOption(ArkUI_NodeHandle node, ArkUI_DragPreviewOption* option); 637 638 /** 639 * @brief Creates a drag action object for a UI instance based on the specified component node of the current 640 * UI instance. 641 * 642 * @param node Indicates the pointer to a component node. 643 * @return Returns the pointer to the created drag action object; returns null if the operation fails. 644 * @since 12 645 */ 646 ArkUI_DragAction* OH_ArkUI_CreateDragActionWithNode(ArkUI_NodeHandle node); 647 648 /** 649 * @brief Creates a drag action object for the specified UI instance. 650 * 651 * @param uiContext Indicates the pointer to a UI instance. 652 * @return Returns the pointer to the created drag action object; returns null if the operation fails. 653 * @since 12 654 */ 655 ArkUI_DragAction* OH_ArkUI_CreateDragActionWithContext(ArkUI_ContextHandle uiContext); 656 657 /** 658 * @brief Disposes of a drag action object. 659 * 660 * @param dragAction Indicates the pointer to the target drag action object. 661 * @since 12 662 */ 663 void OH_ArkUI_DragAction_Dispose(ArkUI_DragAction* dragAction); 664 665 /** 666 * @brief Sets the pointer ID. If only one finger is operating on the screen, the pointer ID is 0. 667 * In general cases, you can set the pointer ID to 0. 668 * 669 * @param dragAction Indicates the pointer to the target drag action object. 670 * @param pointer Indicates the pointer ID. The value ranges from 0 to 9. 671 * @return Returns the result code. 672 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 673 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 674 * @since 12 675 */ 676 int32_t OH_ArkUI_DragAction_SetPointerId(ArkUI_DragAction* dragAction, int32_t pointer); 677 678 /** 679 * @brief Sets the drag previews for a drag action. 680 * 681 * @param dragAction Indicates the pointer to the target drag action object. 682 * @param pixelmapArray Indicates the array of the drag previews to set, which must be pixel maps. 683 * @param size Indicates the size of the drag preview array. 684 * @return Returns the result code. 685 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 686 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 687 * @since 12 688 */ 689 int32_t OH_ArkUI_DragAction_SetPixelMaps( 690 ArkUI_DragAction* dragAction, OH_PixelmapNative* pixelmapArray[], int32_t size); 691 692 /** 693 * @brief Sets the touch point relative to the upper left corner of the first drag preview (pixel map). 694 * 695 * @param dragAction Indicates the pointer to the target drag action object. 696 * @param x Indicates the X coordinate of the touch point. 697 * @return Returns the result code. 698 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 699 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 700 * @since 12 701 */ 702 int32_t OH_ArkUI_DragAction_SetTouchPointX(ArkUI_DragAction* dragAction, float x); 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 y Indicates the Y 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_SetTouchPointY(ArkUI_DragAction* dragAction, float y); 715 716 /** 717 * @brief Sets the drag data. 718 * 719 * @param dragAction Indicates the pointer to the target drag action object. 720 * @param data Indicates the drag data. 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_SetData(ArkUI_DragAction* dragAction, OH_UdmfData* data); 727 728 /** 729 * @brief Sets an <b>ArkUI_DragPreviewOption</b> object for the specified drag action object. 730 * 731 * @param dragAction Indicates the pointer to the target drag action object. 732 * @param option Indicates the pointer to an <b>ArkUI_DragPreviewOption</b> object. 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_SetDragPreviewOption(ArkUI_DragAction* dragAction, ArkUI_DragPreviewOption* option); 739 740 /** 741 * @brief Registers a drag status listener. 742 * This listener can be used to check whether the data is successfully received and processed. 743 * 744 * @param dragAction Indicates the pointer to the target drag action object. 745 * @param userData Indicates the custom user data. 746 * @param listener 747 * Indicates the listener to register. When the callback is invoked, the system returns a pointer to the drag status 748 * object. The pointer is destroyed after the callback is complete and the application should not hold it anymore. 749 * @return Returns the result code. 750 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 751 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 752 * @since 12 753 */ 754 int32_t OH_ArkUI_DragAction_RegisterStatusListener(ArkUI_DragAction* dragAction, void* userData, 755 void(*listener)(ArkUI_DragAndDropInfo* dragAndDropInfo, void* userData)); 756 757 /** 758 * @brief Unregisters a drag status listener. 759 * 760 * @param dragAction Indicates the pointer to the target drag action object. 761 * @since 12 762 */ 763 void OH_ArkUI_DragAction_UnregisterStatusListener(ArkUI_DragAction* dragAction); 764 765 /** 766 * @brief Obtains the drag status of a drag action. 767 * 768 * @param dragAndDropInfo Indicates the drag and drop information returned by the drag status listener. 769 * @return Returns an <b>ArkUI_DragStatus</b> object; returns <b>ArkUI_DRAG_STATUS_UNKNOWN</b> if an error occurs. 770 * @since 12 771 */ 772 ArkUI_DragStatus OH_ArkUI_DragAndDropInfo_GetDragStatus(ArkUI_DragAndDropInfo* dragAndDropInfo); 773 774 /** 775 * @brief Obtains a drag event based on the specified drag and drop information. 776 * The drag event can then be used to obtain the drag result and the drag behavior, please note 777 * other info is not included in such a drag event. 778 * 779 * @param dragAndDropInfo Indicates the drag and drop information returned by the drag status listener. 780 * @return Returns an <b>ArkUI_DragEvent</b> object; returns null if an error occurs. 781 * @since 12 782 */ 783 ArkUI_DragEvent* OH_ArkUI_DragAndDropInfo_GetDragEvent(ArkUI_DragAndDropInfo* dragAndDropInfo); 784 785 /** 786 * @brief Initiates a drag action through the specified drag action object. 787 * 788 * @param dragAction Indicates a drag action object. 789 * @return Returns the result code. 790 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 791 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 792 * @since 12 793 */ 794 int32_t OH_ArkUI_StartDrag(ArkUI_DragAction* dragAction); 795 796 #ifdef __cplusplus 797 }; 798 #endif 799 800 #endif // ARKUI_NATIVE_DRAG_AND_DROP_H 801 /** @} */