提交 4c82c91d 编写于 作者: S shawn_he

update docs

Signed-off-by: Nshawn_he <shawn.he@huawei.com>
上级 26f76be1
......@@ -4,17 +4,81 @@
The input device management module is used to listen for the connection, disconnection, and updates of input devices and display information about input devices. For example, it can be used to listen for mouse insertion and removal and obtain information such as the ID, name, and pointer speed of the mouse.
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
> **NOTE**<br>
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Modules to Import
```
```js
import inputDevice from '@ohos.multimodalInput.inputDevice';
```
## inputDevice.on<sup>9+</sup>
on(type: "change", listener: Callback&lt;DeviceListener&gt;): void
Enables listening for hot swap events of an input device.
**System capability**: SystemCapability.MultimodalInput.Input.InputDevice
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------- | ---- | -------------------- |
| type | string | Yes | Event type of the input device. |
| listener | Callback&lt;[DeviceListener](#devicelistener<sup>9+</sup>)&gt; | Yes | Listener for events of the input device.|
**Example**
```js
let isPhysicalKeyboardExist = true;
inputDevice.on("change", (data) => {
console.log("type: " + data.type + ", deviceId: " + data.deviceId);
inputDevice.getKeyboardType(data.deviceId, (ret) => {
console.log("The keyboard type of the device is: " + ret);
if (ret == 2 && data.type == 'add') {
// The physical keyboard is connected.
isPhysicalKeyboardExist = true;
} else if (ret == 2 && data.type == 'remove') {
// The physical keyboard is disconnected.
isPhysicalKeyboardExist = false;
}
});
});
// Check whether the soft keyboard is open based on the value of isPhysicalKeyboardExist.
```
## inputDevice.off<sup>9+</sup>
off(type: "change", listener?: Callback&lt;DeviceListener&gt;): void
Disables listening for hot swap events of an input device.
**System capability**: SystemCapability.MultimodalInput.Input.InputDevice
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------- | ---- | -------------------- |
| type | string | Yes | Event type of the input device. |
| listener | Callback&lt;[DeviceListener](#devicelistener<sup>9+</sup>)&gt; | No | Listener for events of the input device.|
**Example**
```js
listener: function(data) {
console.log("type: " + data.type + ", deviceId: " + data.deviceId);
}
// Disable this listener.
inputDevice.off("change", this.listener);
// Disable all listeners.
inputDevice.off("change");
// By default, the soft keyboard is closed when listening is disabled.
```
## inputDevice.getDeviceIds
......@@ -30,28 +94,17 @@ Obtains the IDs of all input devices. This API uses an asynchronous callback to
| -------- | ---------------------------------------- | ---- | ----- |
| callback | AsyncCallback&lt;Array&lt;number&gt;&gt; | Yes | Callback used to return the result.|
**Example**
```
export default {
data: {
deviceIds: Array,
},
callback: function(ids) {
this.deviceIds = ids;
},
testGetDeviceIds: function () {
console.info("InputDeviceJsTest---start---testGetDeviceIds");
inputDevice.getDeviceIds(this.callback);
console.info("InputDeviceJsTest---end---testGetDeviceIds");
}
}
```js
inputDevice.getDeviceIds((ids)=>{
console.log("The device ID list is: " + ids);
});
```
## inputDevice.getDeviceIds
function getDeviceIds(): Promise<Array<number>>
function getDeviceIds(): Promise&lt;&lt;Array&lt;number&gt;&gt;
Obtains the IDs of all input devices. This API uses a promise to return the result.
......@@ -59,29 +112,17 @@ Obtains the IDs of all input devices. This API uses a promise to return the resu
**Return value**
| Name | Description |
| ---------------------- | ------------------ |
| Promise<Array<number>> | Promise used to return the result.|
| Parameter | Description |
| ------------------------- | ----------------------------- |
| Promise&lt;Array&lt;number&gt;&gt; | Promise used to return the result.|
**Example**
```js
inputDevice.getDeviceIds().then((ids)=>{
console.log("The device ID list is: " + ids);
});
```
export default {
testGetDeviceIds: function () {
console.info("InputDeviceJsTest---start---testGetDeviceIds");
let promise = inputDevice.getDeviceIds();
promise.then((data)=> {
console.info('GetDeviceIds successed, Data: ' + JSON.stringify(data))
}).catch((err)=>{
console.error('Failed GetDeviceIds. Cause: ' + JSON.stringify(err));
});
}
}
```
## inputDevice.getDevice
......@@ -95,69 +136,159 @@ Obtains the information about an input device. This API uses an asynchronous cal
| Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | --------------------------- |
| deviceId | number | Yes | ID of the input device whose information is to be obtained. |
| callback | AsyncCallback&lt;[InputDeviceData](#inputdevicedata)&gt; | Yes | Callback used to return the **InputDeviceData** object.|
| deviceId | number | Yes | ID of the input device. |
| callback | AsyncCallback&lt;[InputDeviceData](#inputdevicedata)&gt; | Yes | Callback used to return the result, which is an **InputDeviceData** object.|
**Example**
```
export default {
InputDeviceData: {
deviceId : 0,
name : "NA",
sources : Array,
axisRanges : Array,
},
callback: function(deviceData) {
this.InputDeviceData = deviceData;
},
testGetDevice: function () {
// The example is used to obtain the information about the device whose ID is 1.
console.info("InputDeviceJsTest---start---testGetDevice");
inputDevice.getDevice(1, this.callback);
console.info("InputDeviceJsTest---end---testGetDevice");
}
}
```js
// Obtain the name of the device whose ID is 1.
inputDevice.getDevice(1, (inputDevice)=>{
console.log("The device name is: " + inputDevice.name);
});
```
## inputDevice.getDevice
function getDevice(deviceId: number): Promise<InputDeviceData>
function getDevice(deviceId: number): Promise&lt;InputDeviceData&gt;
Obtains the information about an input device. This API uses a promise to return the result.
Obtains information about an input device. This API uses a promise to return the result.
**System capability**: SystemCapability.MultimodalInput.Input.InputDevice
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | ---- | ---------------------- |
| deviceId | number | Yes | ID of the input device.|
**Return value**
| Name | Description |
| ------------------------ | ------------------ |
| Promise<InputDeviceData> | Promise used to return the result.|
| Parameter | Description |
| -------------------------------------------------- | ----------------------------- |
| Promise&lt;[InputDeviceData](#inputdevicedata)&gt; | Promise used to return the result.|
**Example**
```js
// Obtain the name of the device whose ID is 1.
inputDevice.getDevice(1).then((inputDevice)=>{
console.log("The device name is: " + inputDevice.name);
});
```
export default {
InputDeviceData: {
deviceId : 0,
name : "NA",
sources : Array,
axisRanges : Array,
},
testGetDevice: function () {
// The example is used to obtain the information about the device whose ID is 1.
console.info("InputDeviceJsTest---start---testGetDevice");
let promise = inputDevice.getDevice(1);
promise.then((data)=> {
console.info('GetDeviceId successed, Data: ' + JSON.stringify(data))
}).catch((err)=>{
console.error('Failed GetDeviceId. Cause: ' + JSON.stringify(err));
});
}
}
## inputDevice.supportKeys<sup>9+</sup>
supportKeys(deviceId: number, keys: Array&lt;KeyCode&gt;, callback: Callback&lt;Array&lt;boolean&gt;&gt;): void;
Obtains information about an input device. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MultimodalInput.Input.InputDevice
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------ | ---- | ------------------------------------------------------------ |
| deviceId | number | Yes | Unique ID of the input device. If the same physical device is repeatedly inserted and removed, its ID changes.|
| keys | Array&lt;KeyCode&gt; | Yes | Key code to be queried. A maximum of five key codes can be specified. |
| callback | Callback&lt;Array&lt;boolean&gt;&gt; | Yes | Callback used to return the result. |
**Example**
```js
// Check whether the input device whose ID is 1 supports key codes 17, 22, and 2055.
inputDevice.supportKeys(1, [17, 22, 2055], (ret)=>{
console.log("The query result is as follows: " + ret);
});
```
## inputDevice.supportKeys<sup>9+</sup>
supportKeys(deviceId: number, keys: Array&lt;KeyCode&gt;): Promise&lt;Array&lt;boolean&gt;&gt;;
Obtains information about an input device. This API uses a promise to return the result.
**System capability**: SystemCapability.MultimodalInput.Input.InputDevice
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------------------------------------------ |
| deviceId | number | Yes | Unique ID of the input device. If the same physical device is repeatedly inserted and removed, its ID changes.|
| keys | Array&lt;KeyCode&gt; | Yes | Key code to be queried. A maximum of five key codes can be specified. |
**Return value**
| Parameter | Description |
| ----------------------------------- | ----------------------------- |
| Promise&lt;Array&lt;boolean&gt;&gt; | Promise used to return the result.|
**Example**
```js
// Check whether the input device whose ID is 1 supports key codes 17, 22, and 2055.
inputDevice.supportKeys(1, [17, 22, 2055]).then((ret)=>{
console.log("The query result is as follows: " + ret);
})
```
## inputDevice.getKeyboardType<sup>9+</sup>
getKeyboardType(deviceId: number, callback: AsyncCallback&lt;KeyboardType&gt;): void;
Obtains the keyboard type of an input device. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MultimodalInput.Input.InputDevice
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------------------------------------- | ---- | ------------------------------------------------------------ |
| deviceId | number | Yes | Unique ID of the input device. If the same physical device is repeatedly inserted and removed, its ID changes.|
| callback | AsyncCallback&lt;[KeyboardType](#keyboardtype)&gt; | Yes | Callback used to return the result. |
**Example**
```js
// Query the keyboard type of the input device whose ID is 1.
inputDevice.getKeyboardType(1, (ret)=>{
console.log("The keyboard type of the device is: " + ret);
});
```
## inputDevice.getKeyboardType<sup>9+</sup>
getKeyboardType(deviceId: number,): Promise&lt;KeyboardType&gt;;
Query the keyboard type of an input device. This API uses a promise to return the result.
**System capability**: SystemCapability.MultimodalInput.Input.InputDevice
**Return value**
| Parameter | Description |
| -------------------------------------------- | ----------------------------- |
| Promise&lt;[KeyboardType](#keyboardtype)&gt; | Promise used to return the result.|
**Example**
```js
// Query the keyboard type of the input device whose ID is 1.
inputDevice.getKeyboardType().then((ret)=>{
console.log("The keyboard type of the device is: " + ret);
})
```
## DeviceListener<sup>9+</sup>
Defines a listener for events of an input device.
**System capability**: SystemCapability.MultimodalInput.Input.InputDevice
| Name | Type | Description |
| -------- | --------------------------- | ------------------------------------------------------------ |
| type | [ChangeType](#changetype) | Device change type, which indicates whether an input device is inserted or removed. |
| deviceId | number | Unique ID of the input device. If the same physical device is repeatedly inserted and removed, its ID changes.|
## InputDeviceData
......@@ -165,30 +296,52 @@ Defines the information about an input device.
**System capability**: SystemCapability.MultimodalInput.Input.InputDevice
| Name | Type | Description |
| ------- | -------------------------------------- | ---------------------------------------- |
| id | number | Unique identifier of an input device. If the same physical device is repeatedly inserted and removed, its ID changes. |
| name | string | Name of the input device. |
| sources | Array&lt;[SourceType](#sourcetype)&gt; | Source types of the input device. For example, if a keyboard is attached with a touchpad, the device has two input sources: keyboard and touchpad.|
| Name | Type | Description |
| -------------------- | -------------------------------------- | ------------------------------------------------------------ |
| id | number | Unique ID of the input device. If the same physical device is repeatedly inserted and removed, its ID changes.|
| name | string | Name of the input device. |
| sources | Array&lt;[SourceType](#sourcetype)&gt; | Source types of the input device. For example, if a keyboard is attached with a touchpad, the device has two input sources: keyboard and touchpad.|
| axisRanges | Array&lt;[axisRanges](#axisrange)&gt; | Axis information of the input device. |
| bus<sup>9+</sup> | number | Bus type of the input device. |
| product<sup>9+</sup> | number | Product information of the input device. |
| vendor<sup>9+</sup> | number | Vendor information of the input device. |
| version<sup>9+</sup> | number | Version information of the input device. |
| phys<sup>9+</sup> | string | Physical address of the input device. |
| uniq<sup>9+</sup> | string | Unique ID of the input device. |
## AxisType
## AxisType<sup>9+</sup>
Axis type. This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR.
Defines the axis type of an input device.
## AxisRange
**System capability**: SystemCapability.MultimodalInput.Input.InputDevice
Defines the axis information of an input device.
| Name | Type| Description |
| ----------- | -------- | ------------------- |
| touchMajor | string | touchMajor axis. |
| touchMinor | string | touchMinor axis. |
| toolMinor | string | toolMinor axis. |
| toolMajor | string | toolMajor axis. |
| orientation | string | Orientation axis.|
| pressure | string | Pressure axis. |
| x | string | X axis. |
| y | string | Y axis. |
| NULL | string | None. |
**System capability**: SystemCapability.MultimodalInput.Input.InputDevice
## AxisRange
| Name | Type | Description |
| ------ | ------------------------- | -------- |
| source | [SourceType](#sourcetype) | Input source type of the axis.|
| axis | [AxisType](axistype) | Axis type. |
| max | number | Maximum value reported by the axis. |
| min | number | Minimum value reported by the axis. |
Defines the axis range of an input device.
**System capability**: SystemCapability.MultimodalInput.Input.InputDevice
| Name | Type | Description |
| ----------------------- | ------------------------- | ---------------- |
| source | [SourceType](#sourcetype) | Input source type of the axis.|
| axis | [AxisType](axistype) | Axis type. |
| max | number | Maximum value of the axis. |
| min | number | Minimum value of the axis. |
| fuzz<sup>9+</sup> | number | Fuzzy value of the axis. |
| flat<sup>9+</sup> | number | Benchmark value of the axis. |
| resolution<sup>9+</sup> | number | Resolution of the axis. |
## SourceType
......@@ -204,3 +357,29 @@ Enumerates the input source types. For example, if a mouse reports an x-axis eve
| trackball | string | The input device is a trackball.|
| touchpad | string | The input device is a touchpad.|
| joystick | string | The input device is a joystick.|
## ChangeType
Defines the change type for the hot swap event of an input device.
**System capability**: SystemCapability.MultimodalInput.Input.InputDevice
| Name | Type| Description |
| ------ | -------- | ------------------ |
| add | string | An input device is inserted.|
| remove | string | An input device is removed.|
## KeyboardType<sup>9+</sup>
Enumerates the keyboard types.
**System capability**: SystemCapability.MultimodalInput.Input.InputDevice
| Name | Type| Value | Description |
| ------------------- | -------- | ---- | ------------------ |
| NONE | number | 0 | Keyboard without keys |
| UNKNOWN | number | 1 | Keyboard with unknown keys|
| ALPHABETIC_KEYBOARD | number | 2 | Full keyboard |
| DIGITAL_KEYBOARD | number | 3 | Keypad |
| HANDWRITING_PEN | number | 4 | Stylus |
| REMOTE_CONTROL | number | 5 | Remote control |
# Input Monitor
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
> **NOTE**<br>
> - The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
>
> - The APIs of this module are system APIs and cannot be called by third-party applications.
......@@ -10,7 +10,7 @@
## Modules to Import
```
```js
import inputMonitor from '@ohos.multimodalInput.inputMonitor';
```
......@@ -24,84 +24,97 @@ ohos.permission.INPUT_MONITORING
on(type: "touch", receiver: TouchEventReceiver): void
Starts listening for global input events.
Enables listening for global touch events.
**Required permissions**: ohos.permission.INPUT_MONITORING
**System capability**: SystemCapability.MultimodalInput.Input.InputMonitor
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | -------------------- |
| type | string | Yes | Type of the input event. Currently, only **touch** events are supported.|
| receiver | [TouchEventReceiver](#toucheventreceiver) | Yes | Callback used to return the touch event. |
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------- | ---- | ------------------------------- |
| type | string | Yes | Type of the input event to listen for. The value is **touch**.|
| receiver | [TouchEventReceiver](#toucheventreceiver) | Yes | Callback used to return the touch event. |
**Example**
```js
inputMonitor.off("touch", (event) => {
// A touch event is consumed.
return false;
});
```
export default {
callback: function (value) {
if (checkEvent(value)) {
// The event meets the service requirement and is consumed.
return true;
} else {
// The event does not meet the service requirement and is not consumed.
return false;
}
},
testOn: function () {
console.info("InputMonitorJsTest---start---testOn");
inputMonitor.on(
"touch",
this.callback
);
console.info("InputMonitorJsTest---end---testOn");
}
}
on(type: "mouse", receiver:Callback<MouseEvent>):void
Enables listening for global mouse events.
**Required permissions**: ohos.permission.INPUT_MONITORING
**System capability**: SystemCapability.MultimodalInput.Input.InputMonitor
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------------- |
| type | string | Yes | Type of the input event to listen for. The value is **mouse**.|
| receiver | Callback<MouseEvent> | Yes | Callback used to return the mouse event. |
**Example**
```js
inputMonitor.off("mouse", (event) => {
// A mouse event is consumed.
});
```
## inputMonitor.off
off(type: "touch", receiver: TouchEventReceiver): void
off(type: "touch", receiver?:TouchEventReceiver):void
Stops listening for global input events.
Enables listening for global touch events.
**Required permissions**: ohos.permission.INPUT_MONITORING
**System capability**: SystemCapability.MultimodalInput.Input.InputMonitor
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | -------------------- |
| type | string | Yes | Type of the input event. Currently, only **touch** events are supported.|
| receiver | [TouchEventReceiver](#toucheventreceiver) | No | Callback used to return the touch event. |
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------- | ---- | ------------------------------- |
| type | string | Yes | Type of the input event to listen for. The value is **touch**.|
| receiver | [TouchEventReceiver](#toucheventreceiver) | No | Callback used to return the touch event. |
**Example**
```js
inputMonitor.off("touch");
```
export default {
callback: function (value) {
if (checkEvent(value)) {
// The event meets the service requirement and is consumed.
return true;
} else {
// The event does not meet the service requirement and is not consumed.
return false;
}
},
testOff: function () {
console.info("InputMonitorJsTest---start---testOff");
inputMonitor.off(
"touch",
this.callback
);
console.info("InputMonitorJsTest---end---testOff");
}
}
off(type: "mouse", receiver?:Callback<MouseEvent>):void
Stops listening for global mouse events.
**Required permissions**: ohos.permission.INPUT_MONITORING
**System capability**: SystemCapability.MultimodalInput.Input.InputMonitor
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------------- |
| type | string | Yes | Type of the input event to listen for. The value is **mouse**.|
| receiver | Callback<MouseEvent> | No | Callback used to return the mouse event. |
**Example**
```js
inputMonitor.off("mouse");
```
## TouchEventReceiver
Represents the class of the callback used to return the touch event. The value **true** indicates that the touch event has been consumed, and the value **false** indicates the opposite.
......@@ -109,7 +122,7 @@ Represents the class of the callback used to return the touch event. The value *
### (touchEvent: TouchEvent): Boolean
Represents the callback used to return the touch event. You need to define the name of the callback function in the correct format. Ensure that the input parameter is of the TouchEvent type, and the return value is of the Boolean type.
Represents the callback used to return the touch event. You need to define the name of the callback function in the correct format. Ensure that the input parameter is of the **TouchEvent** type, and the return value is of the **Boolean** type.
**System capability**: SystemCapability.MultimodalInput.Input.InputMonitor
......@@ -125,24 +138,10 @@ Represents the callback used to return the touch event. You need to define the n
**Example**
```
export default {
callback: function (value) { // Implementation of the (touchEvent:TouchEvent): Boolean API.
if (checkEvent(value)) {
// The event meets the service requirement and is consumed.
return true;
} else {
// The event does not meet the service requirement and is not consumed.
return false;
}
},
testOff: function () {
console.info("InputMonitorJsTest---start---testOff");
inputMonitor.off(
"touch",
this.callback
);
console.info("InputMonitorJsTest---end---testOff");
}
}
```js
inputMonitor.on("touch", (event) => {
// A touch event is consumed.
return false;
});
inputMonitor.off("touch");
```
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册