@ohos.multimodalInput.inputConsumer (Global Shortcut Keys)

The inputConsumer module provides APIs for subscribing to and unsubscribing from global shortcut keys.

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.

Global shortcut keys are combination keys defined by the system or application. System shortcut keys are defined by the system, and application shortcut keys are defined by applications.

Modules to Import

import { inputConsumer, KeyEvent } 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 can be any key except the modifier keys and Meta key. For details about the keys, see Keycode. 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.

KeyPressedConfig¹⁶⁺

Sets the key event consumption configuration.

System capability: SystemCapability.MultimodalInput.Input.InputConsumer

Name	Type	Readable	Writable	Description
key	number	Yes	No	Key value. Currently, only the KEYCODE_VOLUME_UP and KEYCODE_VOLUME_DOWN keys are supported.
action	number	Yes	No	Key event type. Currently, this parameter can only be set to 1, indicating key press.
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

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

Error codes:

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

Error Code	Error Message
801	Capability not supported.

Example

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

inputConsumer.on('hotkeyChange')

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

Subscribes to application shortcut key change events based on the specified options. This API uses an asynchronous callback to return the result.

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 application shortcut key change event.

Error codes:

For details about the error codes, see Global Shortcut Key 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.
801	Capability not supported.
4200002	The hotkey has been used by the system.
4200003	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.error(`Subscribe failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
}

inputConsumer.off('hotkeyChange')

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

Unsubscribes from application shortcut key change 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 left unspecified, listening will be disabled for all callbacks registered for the specified shortcut key options.

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.
801	Capability not supported.

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.error(`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.error(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
}

inputConsumer.on('keyPressed')¹⁶⁺

on(type: 'keyPressed', options: KeyPressedConfig, callback: Callback<KeyEvent>): void

Subscribes to key press events. This API uses an asynchronous callback to return the result. If the current application is in the foreground focus window, a callback is triggered when the specified key is pressed.

System capability: SystemCapability.MultimodalInput.Input.InputConsumer

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. This parameter has a fixed value of keyPressed.
options	KeyPressedConfig	Yes	Sets the key event consumption configuration.
callback	Callback<KeyEvent>	Yes	Callback used to return key press events.

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.
801	Capability not supported.

Example

try {
  let options: inputConsumer.KeyPressedConfig = {
    key: 16,
    action: 1,
    isRepeat: false,
  }
  inputConsumer.on('keyPressed', options, (event: KeyEvent) => {
    console.log(`Subscribe success ${JSON.stringify(event)}`);
  });
} catch (error) {
  console.error(`Subscribe execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
}

inputConsumer.off('keyPressed')¹⁶⁺

off(type: 'keyPressed', callback?: Callback<KeyEvent>): void

Unsubscribes from key press events. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MultimodalInput.Input.InputConsumer

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. This parameter has a fixed value of keyPressed.
callback	Callback<KeyEvent>	No	Callback to unregister. If this parameter is not specified, listening will be disabled for all registered callbacks.

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.
801	Capability not supported.

Example

try {
  // Disable listening for a single callback.
  inputConsumer.off('keyPressed', (event: KeyEvent) => {
    console.log(`Unsubscribe success ${JSON.stringify(event)}`);
  });
  // Disable listening for all callbacks.
  inputConsumer.off("keyPressed");
} catch (error) {
  console.error(`Unsubscribe execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
}