• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.multimodalInput.inputConsumer (Input Consumer)
2
3The **inputConsumer** module implements listening for combination key events.
4
5> **NOTE**
6>
7> - The initial APIs of this module are supported since API version 14. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8
9
10## Modules to Import
11
12
13```js
14import { inputConsumer } from '@kit.InputKit';
15```
16
17## HotkeyOptions<sup>14+</sup>
18
19Defines shortcut key options.
20
21**System capability**: SystemCapability.MultimodalInput.Input.InputConsumer
22
23| Name       | Type  | Readable  | Writable  | Description     |
24| --------- | ------ | ------- | ------- | ------- |
25| preKeys   | Array&lt;number&gt; | Yes     | No     | Modifier key set (including Ctrl, Shift, and Alt). A maximum of two modifier keys are supported. There is no requirement on the sequence of modifier keys.<br>For example, in **Ctrl+Shift+Esc**, **Ctrl** and **Shift** are modifier keys.|
26| finalKey  | number  | Yes     | No     | Modified key, which is the key other than the modifier key and meta key.<br>For example, in **Ctrl+Shift+Esc**, **Esc** is the modified key.|
27| isRepeat  | boolean  | Yes     | No     | Whether to report repeated key events. The value **true** means to report repeated key events, and the value **false** means the opposite. The default value is **true**.|
28
29## inputConsumer.getAllSystemHotkeys<sup>14+</sup>
30
31getAllSystemHotkeys(): Promise&lt;Array&lt;HotkeyOptions&gt;&gt;
32
33Obtains all system shortcut keys. This API uses a promise to return the result.
34
35**System capability**: SystemCapability.MultimodalInput.Input.InputConsumer
36
37**Return value**
38
39| Parameter        |  Description                                      |
40| ---------- |  ---------------------------------------- |
41| Promise&lt;Array&lt;HotkeyOptions&gt;&gt;                    | Promise used to return the list of all system shortcut keys.|
42
43**Error codes**:
44
45For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
46
47| Error Code| Error Message                 |
48| -------- | ------------------------- |
49| 801      | Capability not supported. |
50
51**Example**
52
53```js
54inputConsumer.getAllSystemHotkeys().then((data: Array<inputConsumer.HotkeyOptions>) => {
55  console.log(`List of system hotkeys : ${JSON.stringify(data)}`);
56});
57```
58
59## inputConsumer.on('hotkeyOptions')<sup>14+</sup>
60
61on(type: 'hotkeyChange', hotkeyOptions: HotkeyOptions, callback: Callback&lt;HotkeyOptions&gt;): void
62
63Enables listening for global combination key events. This API uses an asynchronous callback to return the combination key data when a combination key event that meets the specified condition occurs.
64
65**System capability**: SystemCapability.MultimodalInput.Input.InputConsumer
66
67**Parameters**
68
69| Name        | Type                        | Mandatory  | Description                                      |
70| ---------- | -------------------------- | ---- | ---------- |
71| type       | string                     | Yes   | Event type. This parameter has a fixed value of **hotkeyChange**.                  |
72| hotkeyOptions | [HotkeyOptions](#hotkeyoptions14) | Yes   | Shortcut key options.                |
73| callback   | Callback&lt;HotkeyOptions&gt; | Yes   | Callback used to return the combination key data when a global combination key event that meets the specified condition occurs.|
74
75**Error codes**:
76
77For details about the error codes, see [Input Consumer Error Codes](errorcode-inputconsumer.md) and [Universal Error Codes](../errorcode-universal.md).
78
79| Error Code | Error Message            |
80| ---- | --------------------- |
81| 401  | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. |
82| 801 | Capability not supported. |
83| 4200002  | The hotkey has been used by the system. |
84| 4200003  | The hotkey has been subscribed to by another. |
85
86**Example**
87
88```js
89let leftCtrlKey = 2072;
90let zKey = 2042;
91let hotkeyOptions: inputConsumer.HotkeyOptions = {
92  preKeys: [ leftCtrlKey ],
93  finalKey: zKey,
94  isRepeat: true
95};
96let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => {
97  console.log(`hotkeyOptions: ${JSON.stringify(hotkeyOptions)}`);
98}
99try {
100  inputConsumer.on("hotkeyChange", hotkeyOptions, hotkeyCallback);
101} catch (error) {
102  console.log(`Subscribe failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
103}
104```
105
106## inputConsumer.off('hotkeyOptions')<sup>14+</sup>
107
108off(type: 'hotkeyChange', hotkeyOptions: HotkeyOptions, callback?: Callback&lt;HotkeyOptions&gt;): void
109
110Disables listening for global combination key events.
111
112**System capability**: SystemCapability.MultimodalInput.Input.InputConsumer
113
114**Parameters**
115
116| Name        | Type                        | Mandatory  | Description                             |
117| ---------- | -------------------------- | ---- | ---------- |
118| type       | string                     | Yes   | Event type. This parameter has a fixed value of **hotkeyChange**.       |
119| hotkeyOptions | [HotkeyOptions](#hotkeyoptions14) | Yes   | Shortcut key options.            |
120| callback   | Callback&lt;HotkeyOptions&gt; | No   | Callback to unregister. If this parameter is not specified, listening will be disabled for all callbacks registered by the current application.|
121
122**Error codes**:
123
124For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
125
126| Error Code | Error Message            |
127| ---- | --------------------- |
128| 401  | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. |
129| 801 | Capability not supported. |
130
131**Example**
132
133```js
134let leftCtrlKey = 2072;
135let zKey = 2042;
136// Disable listening for a single callback.
137let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => {
138  console.log(`hotkeyOptions: ${JSON.stringify(hotkeyOptions)}`);
139}
140let hotkeyOption: inputConsumer.HotkeyOptions = {preKeys: [leftCtrlKey], finalKey: zKey, isRepeat: true};
141try {
142  inputConsumer.on("hotkeyChange", hotkeyOption, hotkeyCallback);
143  inputConsumer.off("hotkeyChange", hotkeyOption, hotkeyCallback);
144  console.log(`Unsubscribe success`);
145} catch (error) {
146  console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
147}
148```
149```js
150let leftCtrlKey = 2072;
151let zKey = 2042;
152// Disable listening for all callbacks.
153let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => {
154  console.log(`hotkeyOptions: ${JSON.stringify(hotkeyOptions)}`);
155}
156let hotkeyOption: inputConsumer.HotkeyOptions = {preKeys: [leftCtrlKey], finalKey: zKey, isRepeat: true};
157try {
158  inputConsumer.on("hotkeyChange", hotkeyOption, hotkeyCallback);
159  inputConsumer.off("hotkeyChange", hotkeyOption);
160  console.log(`Unsubscribe success`);
161} catch (error) {
162  console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
163}
164```
165