• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.multimodalawareness.motion (Motion Awareness)
2
3The **motion** module provides the user motion awareness capabilities, including user gestures and actions.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 15. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8
9
10## Modules to Import
11
12```ts
13import { motion } from '@kit.MultimodalAwarenessKit';
14```
15
16## OperatingHandStatus
17
18Defines the status of the operating hand.
19
20**System capability**: SystemCapability.MultimodalAwareness.Motion
21
22| Name               | Value  | Description                  |
23| ------------------- | ---- | ---------------------- |
24| UNKNOWN_STATUS  | 0    | Unknown status.|
25| LEFT_HAND_OPERATED  | 1    | Left hand in use.|
26| RIGHT_HAND_OPERATED | 2    | Right hand in use.|
27
28
29
30
31## motion.on('operatingHandChanged')
32
33 on(type: 'operatingHandChanged', callback: Callback<OperatingHandStatus>): void;
34
35Subscribes to operating hand change events.
36
37**Required permissions**: ohos.permission.ACTIVITY_MOTION or ohos.permission.DETECT_GESTURE
38
39**System capability**: SystemCapability.MultimodalAwareness.Motion
40
41**Parameters**
42
43| Name  | Type                            | Mandatory| Description                                                        |
44| -------- | -------------------------------- | ---- | ------------------------------------------------------------ |
45| type     | string                           | Yes  | Event type. Event type. This parameter has a fixed value of **operatingHandChanged**.|
46| callback | Callback<[OperatingHandStatus](#operatinghandstatus)> | Yes  | Callback used to return the result.                                  |
47
48**Error codes**
49
50For details about the error codes, see [Motion Awareness Error Codes](errorcode-motion.md) and [Universal Error Codes](../errorcode-universal.md).
51
52| ID| Error Message                                                    |
53| -------- | ------------------------------------------------------------ |
54| 201      | Permission denied. An attempt was made to subscribe operatingHandChanged event forbidden by permission: ohos.permission.ACTIVITY_MOTION or ohos.permission.DETECT_GESTURE. |
55| 401      | Parameter error. Parameter verification failed. |
56| 801      | Capability not supported. Function can not work correctly due to limited device capabilities. |
57| 31500001 | Service exception. Possible causes: 1. A system error, such as null pointer, container-related exception; 2. N-API invocation exception, invalid N-API status. |
58| 31500002 | Subscription failed. Possible causes: 1. Callback registration failure; 2. Failed to bind native object to js wrapper; 3. N-API invocation exception, invalid N-API status; 4. IPC request exception. |
59
60**Example**
61
62```ts
63import { BusinessError } from '@kit.BasicServicesKit';
64
65callback(data:motion.OperatingHandStatus) {
66    console.info('callback success' + data);
67}
68
69try {
70    motion.on('operatingHandChanged', this.callback);
71    console.info("on succeeded");
72} catch (err) {
73    let error = err as BusinessError;
74    console.error("Failed on and err code is " + error.code);
75}
76```
77
78
79
80## motion.off('operatingHandChanged')
81
82off(type: 'operatingHandChanged', callback?: Callback<OperatingHandStatus>): void;
83
84Unsubscribes from operating hand change events.
85
86**Required permissions**: ohos.permission.ACTIVITY_MOTION or ohos.permission.DETECT_GESTURE
87
88**System capability**: SystemCapability.MultimodalAwareness.Motion
89
90**Parameters**
91
92| Name  | Type                            | Mandatory| Description                                                        |
93| -------- | -------------------------------- | ---- | ------------------------------------------------------------ |
94| type     | string                           | Yes  | Event type. Event type. This parameter has a fixed value of **operatingHandChanged**.|
95| callback | Callback<[OperatingHandStatus](#operatinghandstatus)> | No  | Callback used to return the result.                                  |
96
97**Error codes**
98
99For details about the error codes, see [Motion Awareness Error Codes](errorcode-motion.md) and [Universal Error Codes](../errorcode-universal.md).
100
101| ID| Error Message                                                    |
102| -------- | ------------------------------------------------------------ |
103| 201      | Permission denied. An attempt was made to unsubscribe operatingHandChanged event forbidden by permission: ohos.permission.ACTIVITY_MOTION or ohos.permission.DETECT_GESTURE. |
104| 401      | Parameter error. Parameter verification failed. |
105| 801      | Capability not supported. Function can not work correctly due to limited device capabilities. |
106| 31500001 | Service exception. Possible causes: 1. A system error, such as null pointer, container-related exception; 2. N-API invocation exception, invalid N-API status. |
107| 31500003 | Unsubscription failed. Possible causes: 1. Callback failure; 2. N-API invocation exception, invalid N-API status; 3. IPC request exception. |
108
109**Example**
110
111```ts
112import { BusinessError } from '@kit.BasicServicesKit';
113
114try {
115    motion.off('operatingHandChanged');
116    console.info("off succeeded");
117} catch (err) {
118    let error = err as BusinessError;
119    console.error("Failed off and err code is " + error.code);
120}
121```
122
123
124
125## motion.getRecentOperatingHandStatus()
126
127getRecentOperatingHandStatus(): OperatingHandStatus;
128
129Obtains the latest operating hand status.
130
131**Required permissions**: ohos.permission.ACTIVITY_MOTION or ohos.permission.DETECT_GESTURE
132
133**System capability**: SystemCapability.MultimodalAwareness.Motion
134
135**Return value**
136
137| Type                         | Description                                |
138| ----------------------------- | ------------------------------------ |
139| [OperatingHandStatus](#operatinghandstatus) | Status of the operating hand.|
140
141**Error codes**
142
143For details about the error codes, see [Motion Awareness Error Codes](errorcode-motion.md) and [Universal Error Codes](../errorcode-universal.md).
144
145| ID| Error Message                                                    |
146| -------- | ------------------------------------------------------------ |
147| 201      | Permission denied. An attempt was made to get the recent operating hand status forbidden by permission: ohos.permission.ACTIVITY_MOTION or ohos.permission.DETECT_GESTURE. |
148| 801      | Capability not supported. Function can not work correctly due to limited device capabilities. |
149| 31500001 | Service exception. Possible causes: 1. A system error, such as null pointer, container-related exception; 2. N-API invocation exception, invalid N-API status. |
150
151**Example**
152
153```ts
154import { BusinessError } from '@kit.BasicServicesKit';
155
156try {
157    let data:motion.OperatingHandStatus = motion.getRecentOperatingHandStatus();
158    console.info('get success' + data);
159} catch (err) {
160    let error = err as BusinessError;
161    console.error("Failed get and err code is " + error.code);
162}
163```
164