1/* 2 * Copyright (c) 2023 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 * @file 18 * @kit ArkUI 19 */ 20 21 22 23import type { AsyncCallback, BusinessError, Callback } from './@ohos.base'; 24import type unifiedDataChannel from './@ohos.data.unifiedDataChannel'; 25 26/** 27 * This module allows developers to trigger a drag event. 28 * @namespace dragController 29 * @syscap SystemCapability.ArkUI.ArkUI.Full 30 * @since 10 31 */ 32/** 33 * This module allows developers to trigger a drag event. 34 * @namespace dragController 35 * @syscap SystemCapability.ArkUI.ArkUI.Full 36 * @atomicservice 37 * @since 12 38 */ 39declare namespace dragController { 40 /** 41 * Defines the Drag Status. 42 * 43 * @enum { number } 44 * @syscap SystemCapability.ArkUI.ArkUI.Full 45 * @since 11 46 */ 47 /** 48 * Defines the Drag Status. 49 * 50 * @enum { number } 51 * @syscap SystemCapability.ArkUI.ArkUI.Full 52 * @atomicservice 53 * @since 12 54 */ 55 const enum DragStatus { 56 /** 57 * Drag has started. 58 * @syscap SystemCapability.ArkUI.ArkUI.Full 59 * @since 11 60 */ 61 /** 62 * Drag has started. 63 * @syscap SystemCapability.ArkUI.ArkUI.Full 64 * @atomicservice 65 * @since 12 66 */ 67 STARTED = 0, 68 /** 69 * Drag has ended. 70 * @syscap SystemCapability.ArkUI.ArkUI.Full 71 * @since 11 72 */ 73 /** 74 * Drag has ended. 75 * @syscap SystemCapability.ArkUI.ArkUI.Full 76 * @atomicservice 77 * @since 12 78 */ 79 ENDED = 1, 80 } 81 82 /** 83 * Drag and drop information 84 * 85 * @interface DragAndDropInfo 86 * @syscap SystemCapability.ArkUI.ArkUI.Full 87 * @since 11 88 */ 89 /** 90 * Drag and drop information 91 * 92 * @interface DragAndDropInfo 93 * @syscap SystemCapability.ArkUI.ArkUI.Full 94 * @atomicservice 95 * @since 12 96 */ 97 interface DragAndDropInfo { 98 /** 99 * The drag status. 100 * @type { DragStatus } 101 * @syscap SystemCapability.ArkUI.ArkUI.Full 102 * @since 11 103 */ 104 /** 105 * The drag status. 106 * @type { DragStatus } 107 * @syscap SystemCapability.ArkUI.ArkUI.Full 108 * @atomicservice 109 * @since 12 110 */ 111 status: DragStatus; 112 /** 113 * The information containing the drag event. 114 * @type { DragEvent } 115 * @syscap SystemCapability.ArkUI.ArkUI.Full 116 * @since 11 117 */ 118 /** 119 * The information containing the drag event. 120 * @type { DragEvent } 121 * @syscap SystemCapability.ArkUI.ArkUI.Full 122 * @atomicservice 123 * @since 12 124 */ 125 event: DragEvent; 126 /** 127 * Additional information about the drag info. 128 * @type { ?string } 129 * @syscap SystemCapability.ArkUI.ArkUI.Full 130 * @since 11 131 */ 132 /** 133 * Additional information about the drag info. 134 * @type { ?string } 135 * @syscap SystemCapability.ArkUI.ArkUI.Full 136 * @atomicservice 137 * @since 12 138 */ 139 extraParams?: string; 140 } 141 142 /** 143 * One drag action object for drag process 144 * 145 * @interface DragAction 146 * @syscap SystemCapability.ArkUI.ArkUI.Full 147 * @since 11 148 */ 149 /** 150 * One drag action object for drag process 151 * 152 * @interface DragAction 153 * @syscap SystemCapability.ArkUI.ArkUI.Full 154 * @atomicservice 155 * @since 12 156 */ 157 interface DragAction { 158 /** 159 * trigger drag action 160 * 161 * @returns { Promise<void> } A Promise can indicate the start result. 162 * @throws { BusinessError } 100001 - Internal handling failed. 163 * @syscap SystemCapability.ArkUI.ArkUI.Full 164 * @since 11 165 */ 166 /** 167 * trigger drag action 168 * 169 * @returns { Promise<void> } A Promise can indicate the start result. 170 * @throws { BusinessError } 100001 - Internal handling failed. 171 * @syscap SystemCapability.ArkUI.ArkUI.Full 172 * @atomicservice 173 * @since 12 174 */ 175 startDrag(): Promise<void>; 176 /** 177 * Registers a callback for listening on drag status changes. 178 * This callback is triggered when the drag status change. 179 * 180 * @param { 'statusChange' } type for status changing 181 * @param { Callback<DragAndDropInfo> } callback with drag event and status information 182 * @syscap SystemCapability.ArkUI.ArkUI.Full 183 * @since 11 184 */ 185 /** 186 * Registers a callback for listening on drag status changes. 187 * This callback is triggered when the drag status change. 188 * 189 * @param { 'statusChange' } type for status changing 190 * @param { Callback<DragAndDropInfo> } callback with drag event and status information 191 * @syscap SystemCapability.ArkUI.ArkUI.Full 192 * @atomicservice 193 * @since 12 194 */ 195 on(type: 'statusChange', callback: Callback<DragAndDropInfo>): void; 196 197 /** 198 * Deregisters a callback for listening on drag status changes. 199 * This callback is not triggered when the drag status change. 200 * 201 * @param { 'statusChange' } type for status changing 202 * @param { Callback<DragAndDropInfo> } callback with drag event and status information 203 * @syscap SystemCapability.ArkUI.ArkUI.Full 204 * @since 11 205 */ 206 /** 207 * Deregisters a callback for listening on drag status changes. 208 * This callback is not triggered when the drag status change. 209 * 210 * @param { 'statusChange' } type for status changing 211 * @param { Callback<DragAndDropInfo> } callback with drag event and status information 212 * @syscap SystemCapability.ArkUI.ArkUI.Full 213 * @atomicservice 214 * @since 12 215 */ 216 off(type: 'statusChange', callback?: Callback<DragAndDropInfo>): void; 217 } 218 219 /** 220 * DragInfo object description 221 * 222 * @interface DragInfo 223 * @syscap SystemCapability.ArkUI.ArkUI.Full 224 * @since 10 225 */ 226 /** 227 * DragInfo object description 228 * 229 * @interface DragInfo 230 * @syscap SystemCapability.ArkUI.ArkUI.Full 231 * @atomicservice 232 * @since 12 233 */ 234 interface DragInfo { 235 /** 236 * A unique identifier to identify which touch point. 237 * @type { number } 238 * @syscap SystemCapability.ArkUI.ArkUI.Full 239 * @since 10 240 */ 241 /** 242 * A unique identifier to identify which touch point. 243 * @type { number } 244 * @syscap SystemCapability.ArkUI.ArkUI.Full 245 * @atomicservice 246 * @since 12 247 */ 248 pointerId: number; 249 250 /** 251 * Drag data. 252 * @type { ?unifiedDataChannel.UnifiedData } 253 * @syscap SystemCapability.ArkUI.ArkUI.Full 254 * @since 10 255 */ 256 /** 257 * Drag data. 258 * @type { ?unifiedDataChannel.UnifiedData } 259 * @syscap SystemCapability.ArkUI.ArkUI.Full 260 * @atomicservice 261 * @since 12 262 */ 263 data?: unifiedDataChannel.UnifiedData; 264 265 /** 266 * Additional information about the drag info. 267 * @type { ?string } 268 * @syscap SystemCapability.ArkUI.ArkUI.Full 269 * @since 10 270 */ 271 /** 272 * Additional information about the drag info. 273 * @type { ?string } 274 * @syscap SystemCapability.ArkUI.ArkUI.Full 275 * @atomicservice 276 * @since 12 277 */ 278 extraParams?: string; 279 280 /** 281 * Touch point coordinates. 282 * @type { ?TouchPoint } 283 * @syscap SystemCapability.ArkUI.ArkUI.Full 284 * @since 11 285 */ 286 /** 287 * Touch point coordinates. 288 * @type { ?TouchPoint } 289 * @syscap SystemCapability.ArkUI.ArkUI.Full 290 * @atomicservice 291 * @since 12 292 */ 293 touchPoint?: TouchPoint; 294 295 /** 296 * Drag preview options. 297 * @type { ?DragPreviewOptions } 298 * @syscap SystemCapability.ArkUI.ArkUI.Full 299 * @since 11 300 */ 301 /** 302 * Drag preview options. 303 * @type { ?DragPreviewOptions } 304 * @syscap SystemCapability.ArkUI.ArkUI.Full 305 * @atomicservice 306 * @since 12 307 */ 308 previewOptions?: DragPreviewOptions; 309 } 310 311 /** 312 * Defines the animation options for drag preview. 313 * 314 * @interface AnimationOptions 315 * @syscap SystemCapability.ArkUI.ArkUI.Full 316 * @since 11 317 */ 318 /** 319 * Defines the animation options for drag preview. 320 * 321 * @interface AnimationOptions 322 * @syscap SystemCapability.ArkUI.ArkUI.Full 323 * @atomicservice 324 * @since 12 325 */ 326 interface AnimationOptions { 327 /** 328 * Animation duration, in ms. 329 * @type { ?number } 330 * @syscap SystemCapability.ArkUI.ArkUI.Full 331 * @since 11 332 */ 333 /** 334 * Animation duration, in ms. 335 * @type { ?number } 336 * @syscap SystemCapability.ArkUI.ArkUI.Full 337 * @atomicservice 338 * @since 12 339 */ 340 duration?: number; 341 /** 342 * Animation curve. 343 * @type { ?(Curve | ICurve) } 344 * @syscap SystemCapability.ArkUI.ArkUI.Full 345 * @since 11 346 */ 347 /** 348 * Animation curve. 349 * @type { ?(Curve | ICurve) } 350 * @syscap SystemCapability.ArkUI.ArkUI.Full 351 * @atomicservice 352 * @since 12 353 */ 354 curve?: Curve | ICurve; 355 } 356 357 /** 358 * Provides the functions of setting color or updating animation. 359 * @syscap SystemCapability.ArkUI.ArkUI.Full 360 * @since 11 361 */ 362 /** 363 * Provides the functions of setting color or updating animation. 364 * @syscap SystemCapability.ArkUI.ArkUI.Full 365 * @atomicservice 366 * @since 12 367 */ 368 export class DragPreview { 369 /** 370 * change foreground color of preview 371 * @param { ResourceColor } color - color value 372 * @syscap SystemCapability.ArkUI.ArkUI.Full 373 * @since 11 374 */ 375 /** 376 * change foreground color of preview 377 * @param { ResourceColor } color - color value 378 * @syscap SystemCapability.ArkUI.ArkUI.Full 379 * @atomicservice 380 * @since 12 381 */ 382 setForegroundColor(color: ResourceColor): void; 383 /** 384 * update preview style with animation 385 * @param { AnimationOptions } options - animation options 386 * @param { function } handler - change style functions 387 * @syscap SystemCapability.ArkUI.ArkUI.Full 388 * @since 11 389 */ 390 /** 391 * update preview style with animation 392 * @param { AnimationOptions } options - animation options 393 * @param { function } handler - change style functions 394 * @syscap SystemCapability.ArkUI.ArkUI.Full 395 * @atomicservice 396 * @since 12 397 */ 398 animate(options: AnimationOptions, handler: () =>void): void; 399 } 400 401 /** 402 * Define the drag event paramters 403 * 404 * @interface DragEventParam 405 * @syscap SystemCapability.ArkUI.ArkUI.Full 406 * @atomicservice 407 * @since 12 408 */ 409 interface DragEventParam { 410 411 /** 412 * The information containing the drag event. 413 * @type { DragEvent } 414 * @syscap SystemCapability.ArkUI.ArkUI.Full 415 * @since 10 416 */ 417 /** 418 * The information containing the drag event. 419 * @type { DragEvent } 420 * @syscap SystemCapability.ArkUI.ArkUI.Full 421 * @atomicservice 422 * @since 12 423 */ 424 event: DragEvent; 425 426 /** 427 * Additional information about the drag info. 428 * @type { string } 429 * @syscap SystemCapability.ArkUI.ArkUI.Full 430 * @since 10 431 */ 432 /** 433 * Additional information about the drag info. 434 * @type { string } 435 * @syscap SystemCapability.ArkUI.ArkUI.Full 436 * @atomicservice 437 * @since 12 438 */ 439 extraParams: string; 440 } 441 442 /** 443 * Execute a drag event. 444 * @param { CustomBuilder | DragItemInfo } custom - Object used for prompts displayed when the object is dragged. 445 * @param { DragInfo } dragInfo - Information about the drag event. 446 * @param { AsyncCallback<{ event: DragEvent, extraParams: string }> } callback - Callback that contains the drag event information. 447 * @throws { BusinessError } 401 - Parameter error. Possible causes: 448 * <br> 1. Mandatory parameters are left unspecified. 449 * <br> 2. Incorrect parameters types. 450 * <br> 3. Parameter verification failed. 451 * @throws { BusinessError } 100001 - Internal handling failed. 452 * @syscap SystemCapability.ArkUI.ArkUI.Full 453 * @since 10 454 */ 455 /** 456 * Execute a drag event. 457 * @param { CustomBuilder | DragItemInfo } custom - Object used for prompts displayed when the object is dragged. 458 * @param { DragInfo } dragInfo - Information about the drag event. 459 * @param { AsyncCallback<DragEventParam> } callback - Callback that contains the drag event information. 460 * @throws { BusinessError } 401 - Parameter error. Possible causes: 461 * <br> 1. Mandatory parameters are left unspecified. 462 * <br> 2. Incorrect parameters types. 463 * <br> 3. Parameter verification failed. 464 * @throws { BusinessError } 100001 - Internal handling failed. 465 * @syscap SystemCapability.ArkUI.ArkUI.Full 466 * @atomicservice 467 * @since 12 468 */ 469 function executeDrag(custom: CustomBuilder | DragItemInfo, dragInfo: DragInfo, 470 callback: AsyncCallback<DragEventParam>): void; 471 472 /** 473 * Execute a drag event. 474 * @param { CustomBuilder | DragItemInfo } custom - Object used for prompts displayed when the object is dragged. 475 * @param { DragInfo } dragInfo - Information about the drag event. 476 * @returns { Promise<{ event: DragEvent, extraParams: string }> } A Promise with the drag event information. 477 * @throws { BusinessError } 401 - Parameter error. Possible causes: 478 * <br> 1. Mandatory parameters are left unspecified. 479 * <br> 2. Incorrect parameters types. 480 * <br> 3. Parameter verification failed. 481 * @throws { BusinessError } 100001 - Internal handling failed. 482 * @syscap SystemCapability.ArkUI.ArkUI.Full 483 * @since 10 484 */ 485 /** 486 * Execute a drag event. 487 * @param { CustomBuilder | DragItemInfo } custom - Object used for prompts displayed when the object is dragged. 488 * @param { DragInfo } dragInfo - Information about the drag event. 489 * @returns { Promise<DragEventParam> } A Promise with the drag event information. 490 * @throws { BusinessError } 401 - Parameter error. Possible causes: 491 * <br> 1. Mandatory parameters are left unspecified. 492 * <br> 2. Incorrect parameters types. 493 * <br> 3. Parameter verification failed. 494 * @throws { BusinessError } 100001 - Internal handling failed. 495 * @syscap SystemCapability.ArkUI.ArkUI.Full 496 * @atomicservice 497 * @since 12 498 */ 499 function executeDrag(custom: CustomBuilder | DragItemInfo, dragInfo: DragInfo): Promise<DragEventParam>; 500 501 /** 502 * Create one drag action object, which can be used for starting drag later or monitoring 503 * the drag status after drag started. 504 * @param { Array<CustomBuilder | DragItemInfo> } customArray - Objects used for prompts 505 * displayed when the objects are dragged. 506 * @param { DragInfo } dragInfo - Information about the drag event. 507 * @returns { DragAction } one drag action object 508 * @throws { BusinessError } 401 - Parameter error. Possible causes: 509 * <br> 1. Mandatory parameters are left unspecified. 510 * <br> 2. Incorrect parameters types. 511 * <br> 3. Parameter verification failed. 512 * @throws { BusinessError } 100001 - Internal handling failed. 513 * @syscap SystemCapability.ArkUI.ArkUI.Full 514 * @since 11 515 */ 516 /** 517 * Create one drag action object, which can be used for starting drag later or monitoring 518 * the drag status after drag started. 519 * @param { Array<CustomBuilder | DragItemInfo> } customArray - Objects used for prompts 520 * displayed when the objects are dragged. 521 * @param { DragInfo } dragInfo - Information about the drag event. 522 * @returns { DragAction } one drag action object 523 * @throws { BusinessError } 401 - Parameter error. Possible causes: 524 * <br> 1. Mandatory parameters are left unspecified. 525 * <br> 2. Incorrect parameters types. 526 * <br> 3. Parameter verification failed. 527 * @throws { BusinessError } 100001 - Internal handling failed. 528 * @syscap SystemCapability.ArkUI.ArkUI.Full 529 * @atomicservice 530 * @since 12 531 */ 532 function createDragAction(customArray: Array<CustomBuilder | DragItemInfo>, dragInfo: DragInfo): DragAction; 533 534 /** 535 * Get drag preview object. 536 * @returns { DragPreview } An drag preview object. 537 * @syscap SystemCapability.ArkUI.ArkUI.Full 538 * @since 11 539 */ 540 /** 541 * Get drag preview object. 542 * @returns { DragPreview } An drag preview object. 543 * @syscap SystemCapability.ArkUI.ArkUI.Full 544 * @atomicservice 545 * @since 12 546 */ 547 function getDragPreview(): DragPreview; 548} 549 550export default dragController; 551