1# @ohos.multimodalInput.inputConsumer-sys (Input Consumer) (System API)
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 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8>
9> - The APIs provided by this module are system APIs.
10
11## Modules to Import
12
13```js
14import { inputConsumer } from '@kit.InputKit';
15```
16
17## inputConsumer.on
18
19on(type: 'key', keyOptions: KeyOptions, callback: Callback<KeyOptions>): void
20
21Enables listening for 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.
22
23**System capability**: SystemCapability.MultimodalInput.Input.InputConsumer
24
25**Parameters**
26
27| Name        | Type                        | Mandatory  | Description                                      |
28| ---------- | -------------------------- | ---- | ---------------------------------------- |
29| type       | string                     | Yes   | Event type. Currently, only **key** is supported.                      |
30| keyOptions | [KeyOptions](#keyoptions)  | Yes   | Combination key options.                |
31| callback   | Callback<KeyOptions> | Yes   | Callback used to return the combination key data when a combination key event that meets the specified condition occurs.|
32
33**Example**
34
35```js
36let leftAltKey = 2045;
37let tabKey = 2049;
38let keyOptions: inputConsumer.KeyOptions = {
39  preKeys: [ leftAltKey ],
40  finalKey: tabKey,
41  isFinalKeyDown: true,
42  finalKeyDownDuration: 0
43};
44let callback = (keyOptions: inputConsumer.KeyOptions) => {
45  console.log(`keyOptions: ${JSON.stringify(keyOptions)}`);
46}
47try {
48  inputConsumer.on("key", keyOptions, callback);
49} catch (error) {
50  console.log(`Subscribe failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
51}
52```
53
54
55## inputConsumer.off
56
57off(type: 'key', keyOptions: KeyOptions, callback?: Callback<KeyOptions>): void
58
59Disables listening for combination key events.
60
61**System capability**: SystemCapability.MultimodalInput.Input.InputConsumer
62
63**Parameters**
64
65| Name        | Type                        | Mandatory  | Description                             |
66| ---------- | -------------------------- | ---- | ------------------------------- |
67| type       | string                     | Yes   | Event type. Currently, only **key** is supported.             |
68| keyOptions | [KeyOptions](#keyoptions)  | Yes   | Combination key options.            |
69| callback   | Callback<KeyOptions> | No   | Callback to unregister. If this parameter is not specified, listening will be disabled for all callbacks registered by the current application.|
70
71**Example**
72
73```js
74let leftAltKey = 2045;
75let tabKey = 2049;
76// Disable listening for a single callback.
77let callback = (keyOptions: inputConsumer.KeyOptions) => {
78  console.log(`keyOptions: ${JSON.stringify(keyOptions)}`);
79}
80let keyOption: inputConsumer.KeyOptions = {preKeys: [leftAltKey], finalKey: tabKey, isFinalKeyDown: true, finalKeyDownDuration: 0};
81try {
82  inputConsumer.on("key", keyOption, callback);
83  inputConsumer.off("key", keyOption, callback);
84  console.log(`Unsubscribe success`);
85} catch (error) {
86  console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
87}
88```
89```js
90let leftAltKey = 2045;
91let tabKey = 2049;
92// Disable listening for all callbacks.
93let callback = (keyOptions: inputConsumer.KeyOptions) => {
94  console.log(`keyOptions: ${JSON.stringify(keyOptions)}`);
95}
96let keyOption: inputConsumer.KeyOptions = {preKeys: [leftAltKey], finalKey: tabKey, isFinalKeyDown: true, finalKeyDownDuration: 0};
97try {
98  inputConsumer.on("key", keyOption, callback);
99  inputConsumer.off("key", keyOption);
100  console.log(`Unsubscribe success`);
101} catch (error) {
102  console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
103}
104```
105
106## inputConsumer.setShieldStatus<sup>11+</sup>
107
108setShieldStatus(shieldMode: ShieldMode, isShield: boolean): void
109
110Sets the key shielding status.
111
112**Required permissions**: ohos.permission.INPUT_CONTROL_DISPATCHING
113
114**System capability**: SystemCapability.MultimodalInput.Input.InputConsumer
115
116**Parameters**
117
118| Name        | Type                        | Mandatory  | Description                                      |
119| ---------- | -------------------------- | ---- | ---------------------------------------- |
120| shieldMode       | ShieldMode                     | Yes   | Shielding mode. Currently, only **FACTORY_MODE** is supported.                      |
121| isShield | boolean  | Yes   | Whether to enable key shielding. The value **true** means to enable key shielding, and the value **false** indicates the opposite.             |
122
123**Example**
124
125```js
126let FACTORY_MODE = 0;
127try {
128  inputConsumer.setShieldStatus(FACTORY_MODE,true);
129  console.log(`set shield status success`);
130} catch (error) {
131  console.log(`set shield status failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
132}
133
134```
135
136## inputConsumer.getShieldStatus<sup>11+</sup>
137
138getShieldStatus(shieldMode: ShieldMode): boolean
139
140Checks whether key shielding is enabled.
141
142**Required permissions**: ohos.permission.INPUT_CONTROL_DISPATCHING
143
144**System capability**: SystemCapability.MultimodalInput.Input.InputConsumer
145
146**Parameters**
147
148| Name        | Type                        | Mandatory  | Description                                      |
149| ---------- | -------------------------- | ---- | ---------------------------------------- |
150| shieldMode       | ShieldMode                    | Yes   | Shielding mode. Currently, only **FACTORY_MODE** is supported.                      |
151
152**Return value**
153
154| Parameter        |  Description                                      |
155| ---------- |  ---------------------------------------- |
156| boolean                    | Whether to enable key shielding. The value **true** means to enable key shielding, and the value **false** indicates the opposite.                      |
157
158**Example**
159
160```js
161try {
162  let FACTORY_MODE = 0;
163  let shieldstatusResult:Boolean =  inputConsumer.getShieldStatus(FACTORY_MODE);
164  console.log(` get shield status result:${JSON.stringify(shieldstatusResult)}`);
165} catch (error) {
166  console.log(`Failed to get shield status, error: ${JSON.stringify(error, [`code`, `message`])}`);
167}
168```
169
170## KeyOptions
171
172Represents combination key options.
173
174**System capability**: SystemCapability.MultimodalInput.Input.InputConsumer
175
176| Name       | Type  | Readable  | Writable  | Description     |
177| --------- | ------ | ---- | ---- | ------- |
178| preKeys    | Array\<number>   | Yes   | No| Preceding key set. The number of preceding keys ranges from 0 to 4. There is no requirement on the sequence of the keys.<br>For example, in the combination keys **Ctrl+Alt+A**, **Ctrl+Alt** are called preceding keys.|
179| finalKey             | number  | Yes   |  No| Final key. This parameter is mandatory. A callback is triggered by the final key.<br>For example, in the combination keys **Ctrl+Alt+A**, **A** is called the final key.|
180| isFinalKeyDown       | boolean | Yes   |  No| Whether the final key is pressed.<br>The value **true** indicates that the key is pressed, and the value **false** indicates the opposite.|
181| finalKeyDownDuration | number  | Yes   |  No| Duration for pressing a key, in μs.<br>If the value of this field is **0**, a callback is triggered immediately.<br>If the value of this field is greater than **0** and **isFinalKeyDown** is **true**, a callback is triggered when the key keeps being pressed after the specified duration expires. If **isFinalKeyDown** is **false**, a callback is triggered when the key is released before the specified duration expires.  |
182| isRepeat<sup>14+</sup>  | 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**.|
183
184## shieldMode<sup>11+</sup>
185
186Enumerates key shielding modes.
187
188**System capability**: SystemCapability.MultimodalInput.Input.InputConsumer
189
190| Name                       | Type | Readable| Writable| Description          |
191| ------------------------------ | ----------- | ---------------- | ---------------- | ---------------- |
192| FACTORY_MODE | number | Yes| No| Factory mode, which means to shield all shortcut keys.|
193