diff --git a/en/application-dev/reference/apis/js-apis-inputdevice.md b/en/application-dev/reference/apis/js-apis-inputdevice.md index eca20fafe0a0510de5543a7fc777839c0c99862b..c47a977b1f2b1559488b6f6602a6ed116ad88197 100644 --- a/en/application-dev/reference/apis/js-apis-inputdevice.md +++ b/en/application-dev/reference/apis/js-apis-inputdevice.md @@ -15,6 +15,70 @@ The input device management module is used to listen for the connection, disconn import inputDevice from '@ohos.multimodalInput.inputDevice'; ``` +## inputDevice.on9+ + +on(type: "change", listener: Callback<DeviceListener>): 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<[DeviceListener](#devicelistener9+)> | 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, (err, ret) => { + console.log("The keyboard type of the device is: " + ret); + if (ret == inputDevice.KeyboardType.ALPHABETIC_KEYBOARD && data.type == 'add') { + // The physical keyboard is connected. + isPhysicalKeyboardExist = true; + } else if (ret == inputDevice.KeyboardType.ALPHABETIC_KEYBOARD && data.type == 'remove') { + // The physical keyboard is disconnected. + isPhysicalKeyboardExist = false; + } + }); +}); +// Check whether the soft keyboard is open based on the value of isPhysicalKeyboardExist. +``` + +## inputDevice.off9+ + +off(type: "change", listener?: Callback<DeviceListener>): 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<[DeviceListener](#devicelistener9+)> | No | Listener for events of the input device.| + +**Example** + +```js +function listener(data) { + console.log("type: " + data.type + ", deviceId: " + data.deviceId); +} + +// Disable this listener. +inputDevice.off("change", 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<Array<number>> | Yes | Callback used to return the result.| - **Example** ```js -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"); - } -} +inputDevice.getDeviceIds((ids)=>{ + console.log("The device ID list is: " + ids); +}); ``` ## inputDevice.getDeviceIds -function getDeviceIds(): Promise> +getDeviceIds(): Promise<Array<number>> Obtains the IDs of all input devices. This API uses a promise to return the result. @@ -59,35 +112,23 @@ Obtains the IDs of all input devices. This API uses a promise to return the resu **Return value** -| Parameter | Description | -| ---------------------- | ------------------ | -| Promise> | Promise used to return the result.| +| Parameter | Description | +| ---------------------------------- | ------------------- | +| Promise<Array<number>> | Promise used to return the result.| **Example** ```js -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.getDeviceIds().then((ids)=>{ + console.log("The device ID list is: " + ids); +}); ``` - - - - ## inputDevice.getDevice getDevice(deviceId: number, callback: AsyncCallback<InputDeviceData>): void -Obtains the information about an input device. This API uses an asynchronous callback to return the result. +Obtains information about an input device. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.MultimodalInput.Input.InputDevice @@ -95,107 +136,212 @@ 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<[InputDeviceData](#inputdevicedata)> | Yes | Callback used to return the **InputDeviceData** object.| +| deviceId | number | Yes | ID of the input device. | +| callback | AsyncCallback<[InputDeviceData](#inputdevicedata)> | Yes | Callback used to return the result, which is an **InputDeviceData** object.| **Example** ```js -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"); - } -} +// 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\ +getDevice(deviceId: number): Promise<InputDeviceData> -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** -| Parameter | Description | -| ------------------------ | ------------------ | -| Promise\ | Promise used to return the result.| +| Parameter | Description | +| ---------------------------------------- | ------------------- | +| Promise<[InputDeviceData](#inputdevicedata)> | Promise used to return the result.| **Example** ```js -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)); - }); - } -} +// Obtain the name of the device whose ID is 1. +inputDevice.getDevice(1).then((inputDevice)=>{ + console.log("The device name is: " + inputDevice.name); +}); ``` +## inputDevice.supportKeys9+ +supportKeys(deviceId: number, keys: Array<KeyCode>, callback: Callback<Array<boolean>>): void; -## InputDeviceData +Obtains the key codes supported by the 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<KeyCode> | Yes | Key codes to be queried. A maximum of five key codes can be specified. | +| callback | Callback<Array<boolean>> | 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.supportKeys9+ + +supportKeys(deviceId: number, keys: Array<KeyCode>): Promise<Array<boolean>>; + +Obtains the key codes supported by the 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<KeyCode> | Yes | Key codes to be queried. A maximum of five key codes can be specified. | + +**Return value** + +| Parameter | Description | +| ----------------------------------- | ------------------- | +| Promise<Array<boolean>> | 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.getKeyboardType9+ + +getKeyboardType(deviceId: number, callback: AsyncCallback<KeyboardType>): 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<[KeyboardType](#keyboardtype)> | 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.getKeyboardType9+ + +getKeyboardType(deviceId: number,): Promise<KeyboardType>; + +Obtains 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<[KeyboardType](#keyboardtype)> | Promise used to return the result.| + +**Example** + +```js +// Query the keyboard type of the input device whose ID is 1. +inputDevice.getKeyboardType(1).then((ret)=>{ + console.log("The keyboard type of the device is: " + ret); +}) +``` + +## DeviceListener9+ 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<[SourceType](#sourcetype)> | 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<[axisRanges](#axisrange)> | Axis information of the input device. | -| bus | number | Bus type of the input device. | -| product | number | Product information of the input device. | -| vendor | number | Vendor information of the input device. | -| version | number | Version information of the input device. | -| phys | string | Physical address of the input device. | -| uniq | string | Unique ID of the input device. | +| 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.| -## AxisType +## InputDeviceData -Defines the axis type of an input device, which is **NULL**. +Defines the information about an input device. -## AxisRange +**System capability**: SystemCapability.MultimodalInput.Input.InputDevice + +| 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<[SourceType](#sourcetype)> | Source type 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<[axisRanges](#axisrange)> | Axis information of the input device. | +| bus9+ | number | Bus type of the input device. | +| product9+ | number | Product information of the input device. | +| vendor9+ | number | Vendor information of the input device. | +| version9+ | number | Version information of the input device. | +| phys9+ | string | Physical address of the input device. | +| uniq9+ | string | Unique ID of the input device. | + +## AxisType9+ -Defines the axis information of an input device. +Defines the axis type 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 reported by the axis. | -| min | number | Minimum value reported by the axis. | +| 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. | +## AxisRange + +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. | +| fuzz9+ | number | Fuzzy value of the axis. | +| flat9+ | number | Benchmark value of the axis. | +| resolution9+ | number | Resolution of the axis. | ## SourceType @@ -211,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.| + +## KeyboardType9+ + +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. |