diff --git a/en/application-dev/reference/apis/js-apis-arkui-dragController.md b/en/application-dev/reference/apis/js-apis-arkui-dragController.md new file mode 100644 index 0000000000000000000000000000000000000000..02d5d474c46a9d1e660bcb26efdd5de677123956 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-arkui-dragController.md @@ -0,0 +1,180 @@ +# @ohos.arkui.dragController (DragController) + +The **dragController** module provides APIs for initiating drag actions. When receiving a gesture event, such as a click or long-press event, an application can initiate a drag action and carry drag information therein. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> +> You can preview how this component looks on a real device. The preview is not yet available in the DevEco Studio Previewer. + + +## Modules to Import + +```js +import dragController from "@ohos.arkui.dragController"; +``` + +## dragController.executeDrag + +executeDrag(custom: CustomBuilder | DragItemInfo, dragInfo: DragInfo, callback: AsyncCallback<{event: DragEvent, extraParams: string}>): void + +Initiates a drag action, with the object to be dragged and the drag information passed in. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | -------------------------------- | +| custom | [CustomBuilder](../arkui-ts/ts-types.md#custombuilder8) \| [DragItemInfo](../arkui-ts/ts-universal-events-drag-drop.md#dragiteminfo) | Yes | Object to be dragged.| +| dragInfo | [DragInfo](#draginfo) | Yes | Drag information. | +| callback | AsyncCallback<{event: [DragEvent](../arkui-ts/ts-universal-events-drag-drop.md#dragevent), extraParams: string}> | Yes | Callback used to return the result. | + +**Example** + +```ts +import dragController from "@ohos.arkui.dragController" +import UDMF from '@ohos.data.UDMF' + +@Entry +@Component +struct DragControllerPage { + @Builder DraggingBuilder() { + Column() { + Text("DraggingBuilder") + } + .width(100) + .height(100) + .backgroundColor(Color.Blue) + } + + build() { + Column() { + Button('touch to execute drag') + .onTouch((event) => { + if (event.type == TouchType.Down) { + let text = new UDMF.Text() + let unifiedData = new UDMF.UnifiedData(text) + + let dragInfo: dragController.DragInfo = { + pointerId: 0, + data: unifiedData, + extraParams: '' + } + dragController.executeDrag(this.DraggingBuilder.bind(this), dragInfo, (err, {event, extraParams}) => { + if (event.getResult() == DragRet.DRAG_SUCCESS) { + // ... + } else if (event.getResult() == DragRet.DRAG_FAILED) { + // ... + } + }) + } + }) + } + } +} +``` + +## dragController.executeDrag + +executeDrag(custom: CustomBuilder | DragItemInfo, dragInfo: DragInfo): Promise<{event: DragEvent, extraParams: string}> + +Initiates a drag action, with the object to be dragged and the drag information passed in. This API uses a promise to return the result. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | -------------------------------- | +| custom | [CustomBuilder](../arkui-ts/ts-types.md#custombuilder8) \| [DragItemInfo](../arkui-ts/ts-universal-events-drag-drop.md#dragiteminfo) | Yes | Object to be dragged.| +| dragInfo | [DragInfo](#draginfo) | Yes | Drag information. | + +**Return value** + +| Type | Description | +| ------------------------------------------------------ | ------------------ | +| Promise<{event: [DragEvent](../arkui-ts/ts-universal-events-drag-drop.md#dragevent), extraParams: string}> | Promise used to return the result.| + +**Example** + +```ts +import dragController from "@ohos.arkui.dragController" +import UDMF from '@ohos.data.UDMF'; +import componentSnapshot from '@ohos.arkui.componentSnapshot'; +import image from '@ohos.multimedia.image'; + +@Entry +@Component +struct DragControllerPage { + @State pixmap: image.PixelMap = null + + @Builder DraggingBuilder() { + Column() { + Text("DraggingBuilder") + } + .width(100) + .height(100) + .backgroundColor(Color.Blue) + } + + @Builder PixmapBuilder() { + Column() { + Text("PixmapBuilder") + } + .width(100) + .height(100) + .backgroundColor(Color.Blue) + } + + build() { + Column() { + Button('touch to execute drag') + .onTouch((event) => { + if (event.type == TouchType.Down) { + let text = new UDMF.Text() + let unifiedData = new UDMF.UnifiedData(text) + + let dragInfo: dragController.DragInfo = { + pointerId: 0, + data: unifiedData, + extraParams: '' + } + componentSnapshot.createFromBuilder(this.PixmapBuilder.bind(this)).then((pix: image.PixelMap) => { + this.pixmap = pix; + let dragItemInfo: DragItemInfo = { + pixelMap: this.pixmap, + builder: this.DraggingBuilder.bind(this), + extraInfo: "DragItemInfoTest" + } + + dragController.executeDrag(dragItemInfo, dragInfo) + .then(({event, extraParams}) => { + if (event.getResult() == DragRet.DRAG_SUCCESS) { + // ... + } else if (event.getResult() == DragRet.DRAG_FAILED) { + // ... + } + }) + .catch((err) => { + }) + }) + } + }) + } + .width('100%') + .height('100%') + } +} +``` + +## DragInfo + +Defines the attributes required for initiating a drag action and information carried in the dragging process. + +| Name | Type | Mandatory| Description | +| ----------- | ------------------------------------------------------ | ---- | ---------------------------------------- | +| pointerId | number | Yes | ID of the touch point on the screen when dragging is started. | +| data | [UDMF.UnifiedData](./js-apis-data-udmf.md#unifieddata) | No | Data carried in the dragging process. | +| extraParams | string | No | Additional information about the drag action. Not supported currently.| diff --git a/en/application-dev/reference/apis/js-apis-base.md b/en/application-dev/reference/apis/js-apis-base.md new file mode 100644 index 0000000000000000000000000000000000000000..8435c5b922204a5e94a437219564ca3f52520b39 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-base.md @@ -0,0 +1,90 @@ +# @ohos.base (Public Callback Information) + +The **Base** module defines the public callback types of ArkTS APIs, including the common and error callbacks. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## Modules to Import + +``` +import base from '@ohos.base'; +``` + +## Callback + +Callback\ { + +(data: T): void; + +} + +Defines a common callback. + +You can set **data** to customize the data type of the information returned by the callback. + +**System capability**: SystemCapability.Base + +| Name| Type| Mandatory| Description | +| ---- | ---- | ---- | -------------------------- | +| data | T | Yes | Common callback information.| + +## ErrorCallback + +ErrorCallback\ { + +(err: T): void; + +} + +Defines a common callback that carries an error parameter. + +The error parameter is of the [BusinessError](#businesserror) type. + +**System capability**: SystemCapability.Base + +**Parameters** + +| Name| Type| Mandatory| Description | +| ---- | ---- | ---- | ---------------------------- | +| err | T | Yes | Common error information about the API invoking failure.| + +## AsyncCallback + +AsyncCallback\ { + +(err: BusinessError, data: T): void; + +} + +Defines a common callback that carries an error parameter and asynchronous return value. + +The error parameter is of the [BusinessError](#businesserror) type. + +The type of the asynchronous return value is defined by the developer. + +**System capability**: SystemCapability.Base + +| Name| Type | Mandatory| Description | +| ---- | ------------------------------------------------------------ | ---- | ---------------------------- | +| err | [BusinessError](https://gitee.com/openharmony/docs/pulls/20172/files#businesserror) | Yes | Common error information about the API invoking failure.| +| data | T | Yes | Common callback information. | + +## BusinessError + +BusinessError\ extends Error { + +code: number; + +data?: T; +} + +Defines the error parameter. + +**System capability**: SystemCapability.Base + +| Name| Type | Mandatory| Description | +| ---- | ------ | ---- | ---------------------------------------------------------- | +| code | number | Yes | Common error information about the API invoking failure. | +| data | T | No | Common callback information. If this parameter is left empty, no related information is returned.| diff --git a/en/application-dev/reference/apis/js-apis-multimodalinput-gestureevent.md b/en/application-dev/reference/apis/js-apis-multimodalinput-gestureevent.md new file mode 100644 index 0000000000000000000000000000000000000000..ba63aa3d0cf5b941fadd01cbaf40804337e2c2aa --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-multimodalinput-gestureevent.md @@ -0,0 +1,62 @@ +# @ohos.multimodalInput.gestureEvent (Gesture Input Event) + +The **gestureEvent** module provides APIs for gesture events reported by devices. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## Modules to Import + +```js +import { Pinch, ThreeFingersSwipe, FourFingersSwipe, ActionType } from '@ohos.multimodalInput.gestureEvent'; +``` + +## Pinch + +Defines a pinch event. + +**System capability**: SystemCapability.MultimodalInput.Input.Core + +| Name | Type | Readable | Writable | Description | +| -------------- | ----------- | ---- | ---- | ---------------------------------------- | +| type | [ActionType](#actiontype) | Yes | No | Pinch event type. | +| scale | number | Yes | No | Pinch scale factor. The value is greater than or equal to 0. | + +## ThreeFingersSwipe + +Defines a three-finger swipe event. + +**System capability**: SystemCapability.MultimodalInput.Input.Core + +| Name | Type | Readable | Writable | Description | +| -------------- | ----------- | ---- | ---- | ---------------------------------------- | +| type | [ActionType](#actiontype) | Yes | No | Three-finger swipe event type. | +| x | number | Yes | No | X coordinate. | +| y | number | Yes | No | Y coordinate. | + +## FourFingersSwipe + +Defines a four-finger swipe event. + +**System capability**: SystemCapability.MultimodalInput.Input.Core + +| Name | Type | Readable | Writable | Description | +| -------------- | ----------- | ---- | ---- | ---------------------------------------- | +| type | [ActionType](#actiontype) | Yes | No | Four-finger swipe event type. | +| x | number | Yes | No | X coordinate. | +| y | number | Yes | No | Y coordinate. | + + +## ActionType + +Enumerates gesture event types. + +**System capability**: SystemCapability.MultimodalInput.Input.Core + +| Name | Value | Description | +| ----------- | --- | --------------- | +| CANCEL | 0 | Canceled. | +| BEGIN | 1 | Started. | +| UPDATE | 2 | Updated. | +| END | 3 | Ended. |