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 21import { Callback } from './@ohos.base'; 22import { KeyEvent } from './@ohos.multimodalInput.keyEvent'; 23 24/** 25 * The event of key input management module is configured to subscribe and unsubscribe system keys. 26 * 27 * @namespace inputConsumer 28 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 29 * @since 14 30 */ 31declare namespace inputConsumer { 32 /** 33 * Defines event of key that user want to subscribe or unsubscribe. 34 * 35 * @interface KeyOptions 36 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 37 * @systemapi hide for inner use 38 * @since 8 39 */ 40 interface KeyOptions { 41 /** 42 * The pre-keys that want to subscribe or unsubscribe. 43 * 44 * @type { Array<number> } 45 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 46 * @systemapi hide for inner use 47 * @since 8 48 */ 49 preKeys: Array<number>; 50 51 /** 52 * The post position key that want to subscribe or unsubscribe. 53 * 54 * @type { number } 55 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 56 * @systemapi hide for inner use 57 * @since 8 58 */ 59 finalKey: number; 60 61 /** 62 * The final key press down or up. 63 * 64 * @type { boolean } 65 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 66 * @systemapi hide for inner use 67 * @since 8 68 */ 69 isFinalKeyDown: boolean; 70 71 /** 72 * Duration of final key press. 73 * 74 * @type { number } 75 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 76 * @systemapi hide for inner use 77 * @since 8 78 */ 79 finalKeyDownDuration: number; 80 81 /** 82 * Whether to report repeated key events. By default, the value is true if it is left unspecified. 83 * 84 * @type { ?boolean } 85 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 86 * @systemapi hide for inner use 87 * @since 18 88 */ 89 isRepeat?: boolean; 90 } 91 92 /** 93 * Defines the shortcut key structure. 94 * 95 * @typedef HotkeyOptions 96 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 97 * @since 14 98 */ 99 interface HotkeyOptions { 100 /** 101 * Defines modifier keys. One or two modifier keys are supported. 102 * 103 * @type { Array<number> } 104 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 105 * @since 14 106 */ 107 preKeys: Array<number>; 108 109 /** 110 * Defines modified keys. 111 * 112 * @type { number } 113 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 114 * @since 14 115 */ 116 finalKey: number; 117 118 /** 119 * Whether to report repeated key events. By default, the value is true if it is left unspecified. 120 * 121 * @type { ?boolean } 122 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 123 * @since 14 124 */ 125 isRepeat?: boolean; 126 } 127 128 /** 129 * Key consunption settings. 130 * 131 * @typedef KeyPressedConfig 132 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 133 * @since 16 134 */ 135 interface KeyPressedConfig { 136 /** 137 * Key value. Currently listening is supported only for KEYCODE_VOLUME_UP and KEYCODE_VOLUME_DOWN keys. 138 * 139 * @type { number } 140 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 141 * @since 16 142 */ 143 key: number; 144 145 /** 146 * Key event type. The value 1 indicates key press and the value 2 indicates key release. Currently 147 * listening is supported only for key press events. 148 * 149 * @type { number } 150 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 151 * @since 16 152 */ 153 action: number; 154 155 /** 156 * Whether to report repeated key events. 157 * 158 * @type { boolean } 159 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 160 * @since 16 161 */ 162 isRepeat: boolean; 163 } 164 165 /** 166 * Shield mode. 167 * 168 * @enum { number } 169 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 170 * @systemapi hide for inner use 171 * @since 11 172 */ 173 enum ShieldMode { 174 /** 175 * Factory mode shield all key events 176 * 177 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 178 * @systemapi hide for inner use 179 * @since 11 180 */ 181 FACTORY_MODE 182 } 183 184 /** 185 * Subscribe system keys. 186 * 187 * @param { 'key' } type - type of the inputevent about input which is to be subscribed. 188 * @param { KeyOptions } keyOptions - the key events about input which is to be subscribed. 189 * @param { Callback<KeyOptions> } callback - callback function, receive reported data. 190 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 191 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 192 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 193 * @systemapi hide for inner use 194 * @since 8 195 */ 196 /** 197 * Subscribe system keys. 198 * 199 * @param { 'key' } type - type of the inputevent about input which is to be subscribed. 200 * @param { KeyOptions } keyOptions - the key events about input which is to be subscribed. 201 * @param { Callback<KeyOptions> } callback - callback function, receive reported data. 202 * @throws { BusinessError } 202 - Permission denied, non-system app called system api. 203 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 204 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 205 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 206 * @systemapi hide for inner use 207 * @since 12 208 */ 209 function on(type: 'key', keyOptions: KeyOptions, callback: Callback<KeyOptions>): void; 210 211 /** 212 * Subscribe system keys. 213 * 214 * @param { 'key' } type - type of the inputevent about input which is to be subscribed. 215 * @param { KeyOptions } keyOptions - the key events about input which is to be subscribed. 216 * @param { Callback<KeyOptions> } callback - callback function, receive reported data. 217 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 218 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 219 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 220 * @systemapi hide for inner use 221 * @since 8 222 */ 223 /** 224 * Subscribe system keys. 225 * 226 * @param { 'key' } type - type of the inputevent about input which is to be subscribed. 227 * @param { KeyOptions } keyOptions - the key events about input which is to be subscribed. 228 * @param { Callback<KeyOptions> } callback - callback function, receive reported data. 229 * @throws { BusinessError } 202 - Permission denied, non-system app called system api. 230 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 231 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 232 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 233 * @systemapi hide for inner use 234 * @since 12 235 */ 236 function off(type: 'key', keyOptions: KeyOptions, callback?: Callback<KeyOptions>): void; 237 238 /** 239 * Sets whether shield key event interception, only support shield key event. 240 * 241 * @permission ohos.permission.INPUT_CONTROL_DISPATCHING 242 * @param { ShieldMode } shieldMode - According the shield mode select shield key event range. 243 * @param { boolean } isShield - Indicates whether control key event dispatch. The value <b>true</b> indicates 244 * all key events directly dispatch to window, if the value <b>false</b> indicates not shield shortcut key. 245 * @throws { BusinessError } 201 - Permission denied. 246 * @throws { BusinessError } 202 - SystemAPI permission error. 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 11 252 */ 253 function setShieldStatus(shieldMode: ShieldMode, isShield: boolean): void; 254 255 /** 256 * Gets shield event interception status corresponding to shield mode 257 * 258 * @permission ohos.permission.INPUT_CONTROL_DISPATCHING 259 * @param { ShieldMode } shieldMode - According the shield mode select shield key event range. 260 * @returns { boolean } Returns true if shield event interception, returns false otherwise. 261 * @throws { BusinessError } 201 - Permission denied. 262 * @throws { BusinessError } 202 - SystemAPI permission error. 263 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 264 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 265 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 266 * @systemapi hide for inner use. 267 * @since 11 268 */ 269 function getShieldStatus(shieldMode: ShieldMode): boolean; 270 271 /** 272 * Obtains all system hotkeys. This API uses a promise to return the result. 273 * 274 * @returns { Promise<Array<HotkeyOptions>> } All system hotkeys. 275 * @throws { BusinessError } 801 - Capability not supported. 276 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 277 * @since 14 278 */ 279 function getAllSystemHotkeys(): Promise<Array<HotkeyOptions>>; 280 281 /** 282 * Listening for hotkey event changes. 283 * 284 * @param { 'hotkeyChange' } type - Type of the hotkey events. 285 * @param { HotkeyOptions } hotkeyOptions - hotkey events. 286 * @param { Callback<HotkeyOptions> } callback - Callback used to return hotkey events. 287 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 288 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 289 * @throws { BusinessError } 801 - Capability not supported. 290 * @throws { BusinessError } 4200002 - The hotkey has been used by the system. 291 * @throws { BusinessError } 4200003 - The hotkey has been subscribed to by another. 292 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 293 * @since 14 294 */ 295 function on(type: 'hotkeyChange', hotkeyOptions: HotkeyOptions, callback: Callback<HotkeyOptions>): void; 296 297 /** 298 * Unsubscribe from hotkey event changes. 299 * 300 * @param { 'hotkeyChange' } type - Type of the hotkey events. 301 * @param { HotkeyOptions } hotkeyOptions - Hotkey events. 302 * @param { Callback<HotkeyOptions> } callback - Callback used to return hotkey events. 303 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 304 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 305 * @throws { BusinessError } 801 - Capability not supported. 306 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 307 * @since 14 308 */ 309 function off(type: 'hotkeyChange', hotkeyOptions: HotkeyOptions, callback?: Callback<HotkeyOptions>): void; 310 311 /** 312 * Consumed key events. Only the VolumeUp and VolumeDown keys are supported. When the current application process 313 * is the focus window's process, a callback will be triggered if the user operates the specified key. 314 * 315 * @param { 'keyPressed' } type - Type of the key events. 316 * @param { KeyPressedConfig } options - Key consumption settings. 317 * @param { Callback<KeyEvent> } callback - Callback used to return key events. 318 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 319 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 320 * @throws { BusinessError } 801 - Capability not supported. 321 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 322 * @since 16 323 */ 324 function on(type: 'keyPressed', options: KeyPressedConfig, callback: Callback<KeyEvent>): void; 325 326 /** 327 * Cancels consumption of key events. 328 * 329 * @param { 'keyPressed' } type - Type of the hotkey events. 330 * @param { Callback<KeyEvent> } callback - Callback used to return hotkey events. 331 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 332 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 333 * @throws { BusinessError } 801 - Capability not supported. 334 * @syscap SystemCapability.MultimodalInput.Input.InputConsumer 335 * @since 16 336 */ 337 function off(type: 'keyPressed', callback?: Callback<KeyEvent>): void; 338} 339 340export default inputConsumer;