@ohos.multimodalInput.inputConsumer (Input Consumer)

The inputConsumer module implements listening for combination key events.

NOTE

• 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.

Modules to Import

import { inputConsumer } from '@kit.InputKit';

HotkeyOptions¹⁴⁺

Defines shortcut key options.

System capability: SystemCapability.MultimodalInput.Input.InputConsumer

Name	Type	Readable	Writable	Description
preKeys	Array<number>	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. For example, in Ctrl+Shift+Esc, Ctrl and Shift are modifier keys.
finalKey	number	Yes	No	Modified key, which is the key other than the modifier key and meta key. For example, in Ctrl+Shift+Esc, Esc is the modified key.
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.

inputConsumer.getAllSystemHotkeys¹⁴⁺

getAllSystemHotkeys(): Promise<Array<HotkeyOptions>>

Obtains all system shortcut keys. This API uses a promise to return the result.

System capability: SystemCapability.MultimodalInput.Input.InputConsumer

Return value

Parameter	Description
Promise<Array<HotkeyOptions>>	Promise used to return the list of all system shortcut keys.

Example

inputConsumer.getAllSystemHotkeys().then((data: Array<inputConsumer.HotkeyOptions>) => {
  console.log(`List of system hotkeys : ${JSON.stringify(data)}`);
});

inputConsumer.on('hotkeyOptions')¹⁴⁺

on(type: 'hotkeyChange', hotkeyOptions: HotkeyOptions, callback: Callback<HotkeyOptions>): void

Enables 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.

System capability: SystemCapability.MultimodalInput.Input.InputConsumer

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. This parameter has a fixed value of hotkeyChange.
hotkeyOptions	HotkeyOptions	Yes	Shortcut key options.
callback	Callback<HotkeyOptions>	Yes	Callback used to return the combination key data when a global combination key event that meets the specified condition occurs.

Error codes:

For details about the error codes, see Input Consumer Error Codes and Universal Error Codes.

Error Code	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed.
4200002	Parameter error. The hotkey has been used by the system. You can call the inputConsumer.getAllSystemHotkeys interface to query all system hotkeys.
4200003	Parameter error. The hotkey has been subscribed to by another.

Example

let leftCtrlKey = 2072;
let zKey = 2042;
let hotkeyOptions: inputConsumer.HotkeyOptions = {
  preKeys: [ leftCtrlKey ],
  finalKey: zKey,
  isRepeat: true
};
let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => {
  console.log(`hotkeyOptions: ${JSON.stringify(hotkeyOptions)}`);
}
try {
  inputConsumer.on("hotkeyChange", hotkeyOptions, hotkeyCallback);
} catch (error) {
  console.log(`Subscribe failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
}

inputConsumer.off('hotkeyOptions')¹⁴⁺

off(type: 'hotkeyChange', hotkeyOptions: HotkeyOptions, callback?: Callback<HotkeyOptions>): void

Disables listening for global combination key events.

System capability: SystemCapability.MultimodalInput.Input.InputConsumer

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. This parameter has a fixed value of hotkeyChange.
hotkeyOptions	HotkeyOptions	Yes	Shortcut key options.
callback	Callback<HotkeyOptions>	No	Callback to unregister. If this parameter is not specified, listening will be disabled for all callbacks registered by the current application.

Error codes:

For details about the error codes, see Universal Error Codes.

Error Code	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed.

Example

let leftCtrlKey = 2072;
let zKey = 2042;
// Disable listening for a single callback.
let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => {
  console.log(`hotkeyOptions: ${JSON.stringify(hotkeyOptions)}`);
}
let hotkeyOption: inputConsumer.HotkeyOptions = {preKeys: [leftCtrlKey], finalKey: zKey, isRepeat: true};
try {
  inputConsumer.on("hotkeyChange", hotkeyOption, hotkeyCallback);
  inputConsumer.off("hotkeyChange", hotkeyOption, hotkeyCallback);
  console.log(`Unsubscribe success`);
} catch (error) {
  console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
}

let leftCtrlKey = 2072;
let zKey = 2042;
// Disable listening for all callbacks.
let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => {
  console.log(`hotkeyOptions: ${JSON.stringify(hotkeyOptions)}`);
}
let hotkeyOption: inputConsumer.HotkeyOptions = {preKeys: [leftCtrlKey], finalKey: zKey, isRepeat: true};
try {
  inputConsumer.on("hotkeyChange", hotkeyOption, hotkeyCallback);
  inputConsumer.off("hotkeyChange", hotkeyOption);
  console.log(`Unsubscribe success`);
} catch (error) {
  console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
}