1/* 2 * Copyright (C) 2021-2023 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/** 17 * @file 18 * @kit InputKit 19 */ 20 21/*** if arkts 1.1 */ 22import { Callback } from './@ohos.base'; 23import { KeyEvent } from './@ohos.multimodalInput.keyEvent'; 24/*** endif */ 25/*** if arkts 1.2 */ 26import { Callback } from './@ohos.base'; 27/*** endif */ 28 29/** 30 * The inputConsumer module provides APIs for subscribing to and unsubscribing from global shortcut keys. 31 * 32 * @namespace inputConsumer 33 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 34 * @since arkts {'1.1':'14', '1.2':'20'} 35 * @arkts 1.1&1.2 36 */ 37declare namespace inputConsumer { 38 /** 39 * Represents combination key options. 40 * 41 * @interface KeyOptions 42 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 43 * @systemapi hide for inner use 44 * @since arkts {'1.1':'8', '1.2':'20'} 45 * @arkts 1.1&1.2 46 */ 47 interface KeyOptions { 48 /** 49 * Preceding key set. The number of preceding keys ranges from 0 to 4. 50 * There is no requirement on the sequence of the keys. 51 * For example, in the combination keys Ctrl+Alt+A, Ctrl+Alt are called preceding keys. 52 * 53 * @type { Array<number> } 54 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 55 * @systemapi hide for inner use 56 * @since arkts {'1.1':'8', '1.2':'20'} 57 * @arkts 1.1&1.2 58 */ 59 preKeys: Array<number>; 60 61 /** 62 * Final key. This parameter is mandatory. A callback is triggered by the final key. 63 * For example, in the combination keys Ctrl+Alt+A, A is called the final key. 64 * 65 * @type { number } 66 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 67 * @systemapi hide for inner use 68 * @since arkts {'1.1':'8', '1.2':'20'} 69 * @arkts 1.1&1.2 70 */ 71 finalKey: number; 72 73 /** 74 * Whether the final key is pressed. 75 * The value true indicates that the key is pressed, and the value false indicates the opposite. 76 * 77 * @type { boolean } 78 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 79 * @systemapi hide for inner use 80 * @since arkts {'1.1':'8', '1.2':'20'} 81 * @arkts 1.1&1.2 82 */ 83 isFinalKeyDown: boolean; 84 85 /** 86 * Duration for holding down the key, in μs. 87 * If the value of this field is 0, a callback is triggered immediately. 88 * If the value of this field is greater than 0 and isFinalKeyDown is true, 89 * a callback is triggered when the key keeps being pressed after the specified duration expires. 90 * If isFinalKeyDown is false, a callback is triggered when the key is released before the specified duration expires. 91 * 92 * @type { number } 93 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 94 * @systemapi hide for inner use 95 * @since arkts {'1.1':'8', '1.2':'20'} 96 * @arkts 1.1&1.2 97 */ 98 finalKeyDownDuration: number; 99 100 /** 101 * Whether to report repeated key events. The value true means to report repeated key events, and the value false means the opposite. 102 * The default value is true. 103 * 104 * @type { ?boolean } 105 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 106 * @systemapi hide for inner use 107 * @since arkts {'1.1':'18', '1.2':'20'} 108 * @arkts 1.1&1.2 109 */ 110 isRepeat?: boolean; 111 } 112 113 /** 114 * Defines shortcut key options. 115 * 116 * @typedef HotkeyOptions 117 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 118 * @since 14 119 */ 120 interface HotkeyOptions { 121 /** 122 * Modifier key set (including Ctrl, Shift, and Alt). A maximum of two modifier keys are supported. 123 * There is no requirement on the sequence of modifier keys. 124 * For example, in Ctrl+Shift+Esc, Ctrl and Shift are modifier keys. 125 * 126 * @type { Array<number> } 127 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 128 * @since 14 129 */ 130 preKeys: Array<number>; 131 132 /** 133 * Modified key, which can be any key except the modifier keys and Meta key. For details about the keys, see Keycode. 134 * For example, in Ctrl+Shift+Esc, Esc is the modified key. 135 * 136 * @type { number } 137 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 138 * @since 14 139 */ 140 finalKey: number; 141 142 /** 143 * Whether to report repeated key events. The value true means to report repeated key events, and the value false means the opposite. 144 * The default value is true. 145 * 146 * @type { ?boolean } 147 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 148 * @since 14 149 */ 150 isRepeat?: boolean; 151 } 152 153 /** 154 * Sets the key event consumption configuration. 155 * 156 * @typedef KeyPressedConfig 157 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 158 * @since 16 159 */ 160 interface KeyPressedConfig { 161 /** 162 * Key value. Currently, only the KEYCODE_VOLUME_UP and KEYCODE_VOLUME_DOWN keys are supported. 163 * 164 * @type { number } 165 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 166 * @since 16 167 */ 168 key: number; 169 170 /** 171 * Key event type. Currently, this parameter can only be set to 1, indicating key press. 172 * 173 * @type { number } 174 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 175 * @since 16 176 */ 177 action: number; 178 179 /** 180 * The value true means to report repeated key events, and the value false means the opposite. The default value is true. 181 * 182 * @type { boolean } 183 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 184 * @since 16 185 */ 186 isRepeat: boolean; 187 } 188 189 /** 190 * Enumerates shortcut key shield modes. 191 * 192 * @enum { number } 193 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 194 * @systemapi hide for inner use 195 * @since 11 196 */ 197 enum ShieldMode { 198 /** 199 * Factory mode, which means to shield all shortcut keys. 200 * 201 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 202 * @systemapi hide for inner use 203 * @since 11 204 */ 205 FACTORY_MODE 206 } 207 208 /** 209 * Enables listening for combination key events. 210 * This API uses an asynchronous callback to return the combination key data when a combination key event that meets the specified condition occurs. 211 * 212 * @param { 'key' } type - Event type. Currently, only key is supported. 213 * @param { KeyOptions } keyOptions - Combination key options. 214 * @param { Callback<KeyOptions> } callback - Callback used to return the combination key data 215 * when a combination key event that meets the specified condition occurs. 216 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 217 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 218 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 219 * @systemapi hide for inner use 220 * @since 8 221 */ 222 /** 223 * Enables listening for combination key events. 224 * This API uses an asynchronous callback to return the combination key data when a combination key event that meets the specified condition occurs. 225 * 226 * @param { 'key' } type - Event type. Currently, only key is supported. 227 * @param { KeyOptions } keyOptions - Combination key options. 228 * @param { Callback<KeyOptions> } callback - Callback used to return the combination key data 229 * when a combination key event that meets the specified condition occurs. 230 * @throws { BusinessError } 202 - Permission denied, non-system app called system api. 231 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 232 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 233 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 234 * @systemapi hide for inner use 235 * @since arkts {'1.1':'12', '1.2':'20'} 236 * @arkts 1.1&1.2 237 */ 238 function on(type: 'key', keyOptions: KeyOptions, callback: Callback<KeyOptions>): void; 239 240 /** 241 * Disables listening for combination key events. 242 * 243 * @param { 'key' } type - Event type. Currently, only key is supported. 244 * @param { KeyOptions } keyOptions - Combination key options. 245 * @param { Callback<KeyOptions> } callback - Callback to unregister. 246 * If this parameter is not specified, listening will be disabled for all callbacks registered by the current application. 247 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 248 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 249 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 250 * @systemapi hide for inner use 251 * @since 8 252 */ 253 /** 254 * Disables listening for combination key events. 255 * 256 * @param { 'key' } type - Event type. Currently, only key is supported. 257 * @param { KeyOptions } keyOptions - Combination key options. 258 * @param { Callback<KeyOptions> } callback - Callback to unregister. 259 * If this parameter is not specified, listening will be disabled for all callbacks registered by the current application. 260 * @throws { BusinessError } 202 - Permission denied, non-system app called system api. 261 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 262 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 263 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 264 * @systemapi hide for inner use 265 * @since arkts {'1.1':'12', '1.2':'20'} 266 * @arkts 1.1&1.2 267 */ 268 function off(type: 'key', keyOptions: KeyOptions, callback?: Callback<KeyOptions>): void; 269 270 /** 271 * Sets the shortcut key shield status. 272 * 273 * @permission ohos.permission.INPUT_CONTROL_DISPATCHING 274 * @param { ShieldMode } shieldMode - Shortcut key shield mode. Currently, only FACTORY_MODE is supported, which means to shield all shortcut keys. 275 * @param { boolean } isShield - Whether to enable shortcut key shielding. 276 * The value true means to enable shortcut key shielding, and the value false indicates the opposite. 277 * @throws { BusinessError } 201 - Permission denied. 278 * @throws { BusinessError } 202 - SystemAPI permission error. 279 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 280 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 281 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 282 * @systemapi hide for inner use. 283 * @since 11 284 */ 285 function setShieldStatus(shieldMode: ShieldMode, isShield: boolean): void; 286 287 /** 288 * Obtains the shortcut key shield status. 289 * 290 * @permission ohos.permission.INPUT_CONTROL_DISPATCHING 291 * @param { ShieldMode } shieldMode - Shortcut key shield mode. Currently, only FACTORY_MODE is supported, which means to shield all shortcut keys. 292 * @returns { boolean } Returns true if shield event interception, returns false otherwise. 293 * @throws { BusinessError } 201 - Permission denied. 294 * @throws { BusinessError } 202 - SystemAPI permission error. 295 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 296 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 297 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 298 * @systemapi hide for inner use. 299 * @since 11 300 */ 301 function getShieldStatus(shieldMode: ShieldMode): boolean; 302 303 /** 304 * Obtains all system hotkeys. This API uses a promise to return the result. 305 * 306 * @returns { Promise<Array<HotkeyOptions>> } Promise used to return the list of all system shortcut keys. 307 * @throws { BusinessError } 801 - Capability not supported. 308 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 309 * @since 14 310 */ 311 function getAllSystemHotkeys(): Promise<Array<HotkeyOptions>>; 312 313 /** 314 * Subscribes to application shortcut key change events based on the specified options. 315 * This API uses an asynchronous callback to return the result. 316 * 317 * @param { 'hotkeyChange' } type - Event type. This parameter has a fixed value of hotkeyChange. 318 * @param { HotkeyOptions } hotkeyOptions - Shortcut key options. 319 * @param { Callback<HotkeyOptions> } callback - Callback used to return the application shortcut key change event. 320 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 321 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 322 * @throws { BusinessError } 801 - Capability not supported. 323 * @throws { BusinessError } 4200002 - The hotkey has been used by the system. 324 * @throws { BusinessError } 4200003 - The hotkey has been subscribed to by another. 325 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 326 * @since 14 327 */ 328 function on(type: 'hotkeyChange', hotkeyOptions: HotkeyOptions, callback: Callback<HotkeyOptions>): void; 329 330 /** 331 * Unsubscribes from application shortcut key change events. 332 * 333 * @param { 'hotkeyChange' } type - Event type. This parameter has a fixed value of hotkeyChange. 334 * @param { HotkeyOptions } hotkeyOptions - Shortcut key options. 335 * @param { Callback<HotkeyOptions> } callback - Callback to unregister. 336 * If this parameter is left unspecified, listening will be disabled for all callbacks registered for the specified shortcut key options. 337 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 338 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 339 * @throws { BusinessError } 801 - Capability not supported. 340 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 341 * @since 14 342 */ 343 function off(type: 'hotkeyChange', hotkeyOptions: HotkeyOptions, callback?: Callback<HotkeyOptions>): void; 344 345 /** 346 * Subscribes to key press events. This API uses an asynchronous callback to return the result. 347 * If the current application is in the foreground focus window, a callback is triggered when the specified key is pressed. 348 * 349 * @param { 'keyPressed' } type - Event type. This parameter has a fixed value of keyPressed. 350 * @param { KeyPressedConfig } options - Sets the key event consumption configuration. 351 * @param { Callback<KeyEvent> } callback - Callback used to return key press events. 352 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 353 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 354 * @throws { BusinessError } 801 - Capability not supported. 355 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 356 * @since 16 357 */ 358 function on(type: 'keyPressed', options: KeyPressedConfig, callback: Callback<KeyEvent>): void; 359 360 /** 361 * Unsubscribes from key press events. 362 * This API uses an asynchronous callback to return the result. 363 * 364 * @param { 'keyPressed' } type - Event type. This parameter has a fixed value of keyPressed. 365 * @param { Callback<KeyEvent> } callback - Callback to unregister. 366 * If this parameter is not specified, listening will be disabled for all registered callbacks. 367 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 368 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 369 * @throws { BusinessError } 801 - Capability not supported. 370 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 371 * @since 16 372 */ 373 function off(type: 'keyPressed', callback?: Callback<KeyEvent>): void; 374} 375 376export default inputConsumer;