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
44extern "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 */
53typedef 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 */
67typedef 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 */
79typedef 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 */
103typedef 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 */
118typedef 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 */
132typedef struct ArkUI_NodeEvent ArkUI_NodeEvent;
133
134/**
135 * @brief Defines a struct for a UI context object.
136 *
137 * @since 12
138 */
139typedef struct ArkUI_Context ArkUI_Context;
140
141/**
142 * @brief Defines a struct for a UI context object pointer.
143 *
144 * @since 12
145 */
146typedef struct ArkUI_Context* ArkUI_ContextHandle;
147
148/**
149 * @brief Defines a struct for a drag event.
150 *
151 * @since 12
152 */
153typedef struct ArkUI_DragEvent ArkUI_DragEvent;
154
155/**
156 * @brief Defines a struct for custom drag preview options.
157 *
158 * @since 12
159 */
160typedef struct ArkUI_DragPreviewOption ArkUI_DragPreviewOption;
161
162/**
163 * @brief Defines a struct for a drag action.
164 *
165 * @since 12
166 */
167typedef 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 */
174typedef struct ArkUI_DragAndDropInfo ArkUI_DragAndDropInfo;
175
176/**
177 * @brief Defines a struct for UDMF unified data.
178 *
179 * @since 12
180 */
181typedef 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 */
188typedef 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 */
198ArkUI_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 */
207ArkUI_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 */
221int32_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 */
234int32_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 */
246int32_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 */
258int32_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 */
270int32_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 */
283int32_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 */
295int32_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 */
311int32_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 */
324int32_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 */
334float 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 */
344float 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 */
354float 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 */
364float 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 */
374float 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 */
384float 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 */
394float 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 */
404float 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 */
414float 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 */
424float 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 */
434float 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 */
447int32_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 */
465int32_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 */
482int32_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 */
496int32_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 */
508int32_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 */
520int32_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 */
532int32_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 */
544int32_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 */
552ArkUI_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 */
560void 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 */
572int32_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 */
585int32_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 */
598int32_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 */
611int32_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 */
624int32_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 */
636int32_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 */
648int32_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 */
658ArkUI_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 */
667ArkUI_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 */
675void 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 */
688int32_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 */
701int32_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 */
714int32_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 */
726int32_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 */
738int32_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 */
750int32_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 */
766int32_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 */
775void 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 */
784ArkUI_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 */
795ArkUI_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 */
806int32_t OH_ArkUI_StartDrag(ArkUI_DragAction* dragAction);
807
808#ifdef __cplusplus
809};
810#endif
811
812#endif // ARKUI_NATIVE_DRAG_AND_DROP_H
813/** @} */