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**Example**
44
45```js
46inputConsumer.getAllSystemHotkeys().then((data: Array<inputConsumer.HotkeyOptions>) => {
47  console.log(`List of system hotkeys : ${JSON.stringify(data)}`);
48});
49```
50
51## inputConsumer.on('hotkeyOptions')<sup>14+</sup>
52
53on(type: 'hotkeyChange', hotkeyOptions: HotkeyOptions, callback: Callback&lt;HotkeyOptions&gt;): void
54
55Enables 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.
56
57**System capability**: SystemCapability.MultimodalInput.Input.InputConsumer
58
59**Parameters**
60
61| Name        | Type                        | Mandatory  | Description                                      |
62| ---------- | -------------------------- | ---- | ---------- |
63| type       | string                     | Yes   | Event type. This parameter has a fixed value of **hotkeyChange**.                  |
64| hotkeyOptions | [HotkeyOptions](#hotkeyoptions14) | Yes   | Shortcut key options.                |
65| 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.|
66
67**Error codes**:
68
69For details about the error codes, see [Input Consumer Error Codes](errorcode-inputconsumer.md) and [Universal Error Codes](../errorcode-universal.md).
70
71| Error Code | Error Message            |
72| ---- | --------------------- |
73| 401  | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. |
74| 4200002  | Parameter error. The hotkey has been used by the system. You can call the [inputConsumer.getAllSystemHotkeys](#inputconsumergetallsystemhotkeys14) interface to query all system hotkeys. |
75| 4200003  | Parameter error. The hotkey has been subscribed to by another. |
76
77**Example**
78
79```js
80let leftCtrlKey = 2072;
81let zKey = 2042;
82let hotkeyOptions: inputConsumer.HotkeyOptions = {
83  preKeys: [ leftCtrlKey ],
84  finalKey: zKey,
85  isRepeat: true
86};
87let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => {
88  console.log(`hotkeyOptions: ${JSON.stringify(hotkeyOptions)}`);
89}
90try {
91  inputConsumer.on("hotkeyChange", hotkeyOptions, hotkeyCallback);
92} catch (error) {
93  console.log(`Subscribe failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
94}
95```
96
97## inputConsumer.off('hotkeyOptions')<sup>14+</sup>
98
99off(type: 'hotkeyChange', hotkeyOptions: HotkeyOptions, callback?: Callback&lt;HotkeyOptions&gt;): void
100
101Disables listening for global combination key events.
102
103**System capability**: SystemCapability.MultimodalInput.Input.InputConsumer
104
105**Parameters**
106
107| Name        | Type                        | Mandatory  | Description                             |
108| ---------- | -------------------------- | ---- | ---------- |
109| type       | string                     | Yes   | Event type. This parameter has a fixed value of **hotkeyChange**.       |
110| hotkeyOptions | [HotkeyOptions](#hotkeyoptions14) | Yes   | Shortcut key options.            |
111| 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.|
112
113**Error codes**:
114
115For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
116
117| Error Code | Error Message            |
118| ---- | --------------------- |
119| 401  | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. |
120
121**Example**
122
123```js
124let leftCtrlKey = 2072;
125let zKey = 2042;
126// Disable listening for a single callback.
127let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => {
128  console.log(`hotkeyOptions: ${JSON.stringify(hotkeyOptions)}`);
129}
130let hotkeyOption: inputConsumer.HotkeyOptions = {preKeys: [leftCtrlKey], finalKey: zKey, isRepeat: true};
131try {
132  inputConsumer.on("hotkeyChange", hotkeyOption, hotkeyCallback);
133  inputConsumer.off("hotkeyChange", hotkeyOption, hotkeyCallback);
134  console.log(`Unsubscribe success`);
135} catch (error) {
136  console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
137}
138```
139```js
140let leftCtrlKey = 2072;
141let zKey = 2042;
142// Disable listening for all callbacks.
143let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => {
144  console.log(`hotkeyOptions: ${JSON.stringify(hotkeyOptions)}`);
145}
146let hotkeyOption: inputConsumer.HotkeyOptions = {preKeys: [leftCtrlKey], finalKey: zKey, isRepeat: true};
147try {
148  inputConsumer.on("hotkeyChange", hotkeyOption, hotkeyCallback);
149  inputConsumer.off("hotkeyChange", hotkeyOption);
150  console.log(`Unsubscribe success`);
151} catch (error) {
152  console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
153}
154```
155