1 /* 2 * Copyright (c) 2024 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 * @addtogroup ArkUI_NativeModule 18 * @{ 19 * 20 * @brief Provides the general key event APIs of ArkUI on the native side. 21 * 22 * @since 14 23 */ 24 25 /** 26 * @file native_key_event.h 27 * 28 * @brief Declares the APIs related to native key events. 29 * 30 * @library libace_ndk.z.so 31 * @syscap SystemCapability.ArkUI.ArkUI.Full 32 * @kit ArkUI 33 * @since 14 34 */ 35 36 #ifndef ARKUI_NATIVE_KEY_EVENT_H 37 #define ARKUI_NATIVE_KEY_EVENT_H 38 39 #include <stdint.h> 40 41 #include "native_type.h" 42 #include "ui_input_event.h" 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 /** 49 * @brief Defines an enum for the key codes in key events. 50 * 51 * @since 14 52 */ 53 typedef enum { 54 /** Unknown (or unrecognized) key **/ 55 ARKUI_KEYCODE_UNKNOWN = -1, 56 /** Function (Fn) key **/ 57 ARKUI_KEYCODE_FN = 0, 58 /** Volume Up key **/ 59 ARKUI_KEYCODE_VOLUME_UP = 16, 60 /** Volume Down key **/ 61 ARKUI_KEYCODE_VOLUME_DOWN = 17, 62 /** Power key **/ 63 ARKUI_KEYCODE_POWER = 18, 64 /** Shutter key **/ 65 ARKUI_KEYCODE_CAMERA = 19, 66 /** Speaker Mute key **/ 67 ARKUI_KEYCODE_VOLUME_MUTE = 22, 68 /** Mute key **/ 69 ARKUI_KEYCODE_MUTE = 23, 70 /** Brightness Up key **/ 71 ARKUI_KEYCODE_BRIGHTNESS_UP = 40, 72 /** Brightness Down key **/ 73 ARKUI_KEYCODE_BRIGHTNESS_DOWN = 41, 74 /** Key 0 **/ 75 ARKUI_KEYCODE_0 = 2000, 76 /** Key 1 **/ 77 ARKUI_KEYCODE_1 = 2001, 78 /** Key 2 **/ 79 ARKUI_KEYCODE_2 = 2002, 80 /** Key 3 **/ 81 ARKUI_KEYCODE_3 = 2003, 82 /** Key 4 **/ 83 ARKUI_KEYCODE_4 = 2004, 84 /** Key 5 **/ 85 ARKUI_KEYCODE_5 = 2005, 86 /** Key 6 **/ 87 ARKUI_KEYCODE_6 = 2006, 88 /** Key 7 **/ 89 ARKUI_KEYCODE_7 = 2007, 90 /** Key 8 **/ 91 ARKUI_KEYCODE_8 = 2008, 92 /** Key 9 **/ 93 ARKUI_KEYCODE_9 = 2009, 94 /** Key + **/ 95 ARKUI_KEYCODE_STAR = 2010, 96 /** Key # **/ 97 ARKUI_KEYCODE_POUND = 2011, 98 /** Up key on D-pad **/ 99 ARKUI_KEYCODE_DPAD_UP = 2012, 100 /** Down key on D-pad **/ 101 ARKUI_KEYCODE_DPAD_DOWN = 2013, 102 /** Left key on D-pad **/ 103 ARKUI_KEYCODE_DPAD_LEFT = 2014, 104 /** Right key on D-pad **/ 105 ARKUI_KEYCODE_DPAD_RIGHT = 2015, 106 /** OK key on D-pad **/ 107 ARKUI_KEYCODE_DPAD_CENTER = 2016, 108 /** Key A **/ 109 ARKUI_KEYCODE_A = 2017, 110 /** Key B **/ 111 ARKUI_KEYCODE_B = 2018, 112 /** Key C **/ 113 ARKUI_KEYCODE_C = 2019, 114 /** Key D **/ 115 ARKUI_KEYCODE_D = 2020, 116 /** Key E **/ 117 ARKUI_KEYCODE_E = 2021, 118 /** Key F **/ 119 ARKUI_KEYCODE_F = 2022, 120 /** Key G **/ 121 ARKUI_KEYCODE_G = 2023, 122 /** Key H **/ 123 ARKUI_KEYCODE_H = 2024, 124 /** Key I **/ 125 ARKUI_KEYCODE_I = 2025, 126 /** Key J **/ 127 ARKUI_KEYCODE_J = 2026, 128 /** Key K **/ 129 ARKUI_KEYCODE_K = 2027, 130 /** Key L **/ 131 ARKUI_KEYCODE_L = 2028, 132 /** Key M **/ 133 ARKUI_KEYCODE_M = 2029, 134 /** Key N **/ 135 ARKUI_KEYCODE_N = 2030, 136 /** Key O **/ 137 ARKUI_KEYCODE_O = 2031, 138 /** Key P **/ 139 ARKUI_KEYCODE_P = 2032, 140 /** Key R **/ 141 ARKUI_KEYCODE_Q = 2033, 142 /** Key R **/ 143 ARKUI_KEYCODE_R = 2034, 144 /** Key S **/ 145 ARKUI_KEYCODE_S = 2035, 146 /** Key T **/ 147 ARKUI_KEYCODE_T = 2036, 148 /** Key U **/ 149 ARKUI_KEYCODE_U = 2037, 150 /** Key V **/ 151 ARKUI_KEYCODE_V = 2038, 152 /** Key W **/ 153 ARKUI_KEYCODE_W = 2039, 154 /** Key X **/ 155 ARKUI_KEYCODE_X = 2040, 156 /** Key Y **/ 157 ARKUI_KEYCODE_Y = 2041, 158 /** Key Z **/ 159 ARKUI_KEYCODE_Z = 2042, 160 /** Key # **/ 161 ARKUI_KEYCODE_COMMA = 2043, 162 /** Key # **/ 163 ARKUI_KEYCODE_PERIOD = 2044, 164 /** Left Alt key **/ 165 ARKUI_KEYCODE_ALT_LEFT = 2045, 166 /** Right Alt key **/ 167 ARKUI_KEYCODE_ALT_RIGHT = 2046, 168 /** Left Shift key **/ 169 ARKUI_KEYCODE_SHIFT_LEFT = 2047, 170 /** Right Shift key **/ 171 ARKUI_KEYCODE_SHIFT_RIGHT = 2048, 172 /** Tab key **/ 173 ARKUI_KEYCODE_TAB = 2049, 174 /** Space key **/ 175 ARKUI_KEYCODE_SPACE = 2050, 176 /** Symbol key **/ 177 ARKUI_KEYCODE_SYM = 2051, 178 /** Explorer key, used to start the explorer application **/ 179 ARKUI_KEYCODE_EXPLORER = 2052, 180 /** Email key, used to start the email application **/ 181 ARKUI_KEYCODE_ENVELOPE = 2053, 182 /** Enter key **/ 183 ARKUI_KEYCODE_ENTER = 2054, 184 /** Backspace key **/ 185 ARKUI_KEYCODE_DEL = 2055, 186 /** Key ` **/ 187 ARKUI_KEYCODE_GRAVE = 2056, 188 /** Key - **/ 189 ARKUI_KEYCODE_MINUS = 2057, 190 /** Key = **/ 191 ARKUI_KEYCODE_EQUALS = 2058, 192 /** Key [ **/ 193 ARKUI_KEYCODE_LEFT_BRACKET = 2059, 194 /** Key ]**/ 195 ARKUI_KEYCODE_RIGHT_BRACKET = 2060, 196 /** Key \\ **/ 197 ARKUI_KEYCODE_BACKSLASH = 2061, 198 /** Key ; **/ 199 ARKUI_KEYCODE_SEMICOLON = 2062, 200 /** Key ' **/ 201 ARKUI_KEYCODE_APOSTROPHE = 2063, 202 /** Key / **/ 203 ARKUI_KEYCODE_SLASH = 2064, 204 /** Key @ **/ 205 ARKUI_KEYCODE_AT = 2065, 206 /** Key + **/ 207 ARKUI_KEYCODE_PLUS = 2066, 208 /** Menu key **/ 209 ARKUI_KEYCODE_MENU = 2067, 210 /** Page Up key **/ 211 ARKUI_KEYCODE_PAGE_UP = 2068, 212 /** Page Down key **/ 213 ARKUI_KEYCODE_PAGE_DOWN = 2069, 214 /** ESC key **/ 215 ARKUI_KEYCODE_ESCAPE = 2070, 216 /** Delete key **/ 217 ARKUI_KEYCODE_FORWARD_DEL = 2071, 218 /** Left Ctrl key **/ 219 ARKUI_KEYCODE_CTRL_LEFT = 2072, 220 /** Right Ctrl key **/ 221 ARKUI_KEYCODE_CTRL_RIGHT = 2073, 222 /** Caps Lock key **/ 223 ARKUI_KEYCODE_CAPS_LOCK = 2074, 224 /** Scroll Lock key **/ 225 ARKUI_KEYCODE_SCROLL_LOCK = 2075, 226 /** Left Meta key **/ 227 ARKUI_KEYCODE_META_LEFT = 2076, 228 /** Right Meta key **/ 229 ARKUI_KEYCODE_META_RIGHT = 2077, 230 /** Function key **/ 231 ARKUI_KEYCODE_FUNCTION = 2078, 232 /** System Request/Print Screen key **/ 233 ARKUI_KEYCODE_SYSRQ = 2079, 234 /** Break/Pause key **/ 235 ARKUI_KEYCODE_BREAK = 2080, 236 /** Move to Home key **/ 237 ARKUI_KEYCODE_MOVE_HOME = 2081, 238 /** Move to End key **/ 239 ARKUI_KEYCODE_MOVE_END = 2082, 240 /** Insert key **/ 241 ARKUI_KEYCODE_INSERT = 2083, 242 /** Forward key **/ 243 ARKUI_KEYCODE_FORWARD = 2084, 244 /** Play key **/ 245 ARKUI_KEYCODE_MEDIA_PLAY = 2085, 246 /** Pause key **/ 247 ARKUI_KEYCODE_MEDIA_PAUSE = 2086, 248 /** Close key **/ 249 ARKUI_KEYCODE_MEDIA_CLOSE = 2087, 250 /** Eject key **/ 251 ARKUI_KEYCODE_MEDIA_EJECT = 2088, 252 /** Record key **/ 253 ARKUI_KEYCODE_MEDIA_RECORD = 2089, 254 /** F1 key **/ 255 ARKUI_KEYCODE_F1 = 2090, 256 /** F2 key **/ 257 ARKUI_KEYCODE_F2 = 2091, 258 /** F3 key **/ 259 ARKUI_KEYCODE_F3 = 2092, 260 /** F4 key **/ 261 ARKUI_KEYCODE_F4 = 2093, 262 /** F5 key **/ 263 ARKUI_KEYCODE_F5 = 2094, 264 /** F6 key **/ 265 ARKUI_KEYCODE_F6 = 2095, 266 /** F7 key **/ 267 ARKUI_KEYCODE_F7 = 2096, 268 /** F8 key **/ 269 ARKUI_KEYCODE_F8 = 2097, 270 /** F9 key **/ 271 ARKUI_KEYCODE_F9 = 2098, 272 /** F10 key **/ 273 ARKUI_KEYCODE_F10 = 2099, 274 /** F11 key **/ 275 ARKUI_KEYCODE_F11 = 2100, 276 /** F12 key **/ 277 ARKUI_KEYCODE_F12 = 2101, 278 /** Number Lock key on numeric keypad **/ 279 ARKUI_KEYCODE_NUM_LOCK = 2102, 280 /** Key 0 on numeric keypad **/ 281 ARKUI_KEYCODE_NUMPAD_0 = 2103, 282 /** Key 1 on numeric keypad **/ 283 ARKUI_KEYCODE_NUMPAD_1 = 2104, 284 /** Key 2 on numeric keypad **/ 285 ARKUI_KEYCODE_NUMPAD_2 = 2105, 286 /** Key 3 on numeric keypad **/ 287 ARKUI_KEYCODE_NUMPAD_3 = 2106, 288 /** Key 4 on numeric keypad **/ 289 ARKUI_KEYCODE_NUMPAD_4 = 2107, 290 /** Key 5 on numeric keypad **/ 291 ARKUI_KEYCODE_NUMPAD_5 = 2108, 292 /** Key 6 on numeric keypad **/ 293 ARKUI_KEYCODE_NUMPAD_6 = 2109, 294 /** Key 7 on numeric keypad **/ 295 ARKUI_KEYCODE_NUMPAD_7 = 2110, 296 /** Key 8 on numeric keypad **/ 297 ARKUI_KEYCODE_NUMPAD_8 = 2111, 298 /** Key 9 on numeric keypad **/ 299 ARKUI_KEYCODE_NUMPAD_9 = 2112, 300 /** Key / on numeric keypad **/ 301 ARKUI_KEYCODE_NUMPAD_DIVIDE = 2113, 302 /** Key ) on numeric keypad **/ 303 ARKUI_KEYCODE_NUMPAD_MULTIPLY = 2114, 304 /** Key - on numeric keypad **/ 305 ARKUI_KEYCODE_NUMPAD_SUBTRACT = 2115, 306 /** Key + on numeric keypad **/ 307 ARKUI_KEYCODE_NUMPAD_ADD = 2116, 308 /** Key . on numeric keypad **/ 309 ARKUI_KEYCODE_NUMPAD_DOT = 2117, 310 /** Key , on numeric keypad **/ 311 ARKUI_KEYCODE_NUMPAD_COMMA = 2118, 312 /** Enter key on numeric keypad **/ 313 ARKUI_KEYCODE_NUMPAD_ENTER = 2119, 314 /** Key = on numeric keypad **/ 315 ARKUI_KEYCODE_NUMPAD_EQUALS = 2120, 316 /** Key ( on numeric keypad **/ 317 ARKUI_KEYCODE_NUMPAD_LEFT_PAREN = 2121, 318 /** Key ) on numeric keypad **/ 319 ARKUI_KEYCODE_NUMPAD_RIGHT_PAREN = 2122, 320 } ArkUI_KeyCode; 321 322 /** 323 * @brief Defines an enum for the key event types. 324 * 325 * @since 14 326 */ 327 typedef enum { 328 /** Unknown type **/ 329 ARKUI_KEY_EVENT_UNKNOWN = -1, 330 /** Pressing of a key **/ 331 ARKUI_KEY_EVENT_DOWN = 0, 332 /** Release of a key **/ 333 ARKUI_KEY_EVENT_UP = 1, 334 /** Long press of a key **/ 335 ARKUI_KEY_EVENT_LONG_PRESS = 2, 336 /** Click of a key **/ 337 ARKUI_KEY_EVENT_CLICK = 3, 338 } ArkUI_KeyEventType; 339 340 /** 341 * @brief Defines an enum for the types of devices that trigger a key event. 342 * 343 * @since 14 344 */ 345 typedef enum { 346 /** Unknown type **/ 347 ARKUI_KEY_SOURCE_UNKNOWN = 0, 348 /** Mouse **/ 349 ARKUI_KEY_SOURCE_TYPE_MOUSE = 1, 350 /** Keyboard **/ 351 ARKUI_KEY_SOURCE_TYPE_KEYBOARD = 4, 352 } ArkUI_KeySourceType; 353 354 /** 355 * @brief Defines an enum for key intentions. 356 * 357 * @since 14 358 */ 359 typedef enum { 360 /** Unknown intention **/ 361 ARKUI_KEY_INTENSION_UNKNOWN = -1, 362 /**Upward**/ 363 ARKUI_KEY_INTENSION_UP = 1, 364 /** Downward **/ 365 ARKUI_KEY_INTENSION_DOWN = 2, 366 /** Leftward **/ 367 ARKUI_KEY_INTENSION_LEFT = 3, 368 /** Rightward **/ 369 ARKUI_KEY_INTENSION_RIGHT = 4, 370 /** Select **/ 371 ARKUI_KEY_INTENSION_SELECT = 5, 372 /** Escape **/ 373 ARKUI_KEY_INTENSION_ESCAPE = 6, 374 /** Back**/ 375 ARKUI_KEY_INTENSION_BACK = 7, 376 /** Forward **/ 377 ARKUI_KEY_INTENSION_FORWARD = 8, 378 /** Menu **/ 379 ARKUI_KEY_INTENSION_MENU = 9, 380 /** Home **/ 381 ARKUI_KEY_INTENSION_HOME = 10, 382 /** Page up **/ 383 ARKUI_KEY_INTENSION_PAGE_UP = 11, 384 /** Page down **/ 385 ARKUI_KEY_INTENSION_PAGE_DOWN = 12, 386 /** Zoom out **/ 387 ARKUI_KEY_INTENSION_ZOOM_OUT = 13, 388 /** Zoom in **/ 389 ARKUI_KEY_INTENSION_ZOOM_IN = 14, 390 391 /** Play or pause **/ 392 ARKUI_KEY_INTENTION_MEDIA_PLAY_PAUSE = 100, 393 /** Fast-forward **/ 394 ARKUI_KEY_INTENTION_MEDIA_FAST_FORWARD = 101, 395 /** Fast playback **/ 396 ARKUI_KEY_INTENTION_MEDIA_FAST_PLAYBACK = 103, 397 /** Play next **/ 398 ARKUI_KEY_INTENTION_MEDIA_NEXT = 104, 399 /** Play previous **/ 400 ARKUI_KEY_INTENTION_MEDIA_PREVIOUS = 105, 401 /** Mute **/ 402 ARKUI_KEY_INTENTION_MEDIA_MUTE = 106, 403 /** Volume up **/ 404 ARKUI_KEY_INTENTION_VOLUME_UP = 107, 405 /** Volume down **/ 406 ARKUI_KEY_INTENTION_VOLUME_DOWN = 108, 407 408 /** Answer a call **/ 409 ARKUI_KEY_INTENTION_CALL = 200, 410 /** Camera **/ 411 ARKUI_KEY_INTENTION_CAMERA = 300, 412 } ArkUI_KeyIntension; 413 414 /** 415 * @brief Obtains the type of a key event. 416 * 417 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 418 * @return Returns the key event type. 419 * @since 14 420 */ 421 ArkUI_KeyEventType OH_ArkUI_KeyEvent_GetType(const ArkUI_UIInputEvent* event); 422 423 /** 424 * @brief Obtains the key code from a key event. 425 * 426 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 427 * @return Returns the key code. 428 * @since 14 429 */ 430 int32_t OH_ArkUI_KeyEvent_GetKeyCode(const ArkUI_UIInputEvent* event); 431 432 /** 433 * @brief Obtains the key value from a key event. 434 * 435 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 436 * @return Returns the key value. 437 * @since 14 438 */ 439 const char *OH_ArkUI_KeyEvent_GetKeyText(const ArkUI_UIInputEvent* event); 440 441 /** 442 * @brief Obtains the type of device that triggers a key event. 443 * 444 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 445 * @return Returns the device type. 446 * @since 14 447 */ 448 ArkUI_KeySourceType OH_ArkUI_KeyEvent_GetKeySource(const ArkUI_UIInputEvent* event); 449 450 /** 451 * @brief Prevents a key event from bubbling up. 452 * 453 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 454 * @param stopPropagation Whether to stop event propagation. 455 * @since 14 456 */ 457 void OH_ArkUI_KeyEvent_StopPropagation(const ArkUI_UIInputEvent* event, bool stopPropagation); 458 459 /** 460 * @brief Obtains the intention code associated with a key event. 461 * 462 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 463 * @return Returns the intention code associated with the key event. 464 * @since 14 465 */ 466 ArkUI_KeyIntension OH_ArkUI_KeyEvent_GetKeyIntensionCode(const ArkUI_UIInputEvent* event); 467 468 /** 469 * @brief Obtains the Unicode value associated with a key event. 470 * Non-space basic Latin characters in the 0x0021-0x007E range are supported. Characters with a value of 0 are not 471 * supported. In the case of key combination, this API returns the Unicode value of the key corresponding to the key 472 * event. 473 * 474 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 475 * @return Returns the Unicode value. 476 * @since 14 477 */ 478 uint32_t OH_ArkUI_KeyEvent_GetUnicode(const ArkUI_UIInputEvent* event); 479 480 /** 481 * @brief Sets whether a key event is consumed in the key event callback. 482 * 483 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 484 * @param isConsumed Whether the event is consumed. 485 * @since 14 486 */ 487 void OH_ArkUI_KeyEvent_SetConsumed(const ArkUI_UIInputEvent* event, bool isConsumed); 488 #ifdef __cplusplus 489 }; 490 #endif 491 492 #endif // ARKUI_NATIVE_KEY_EVENT_H 493 /** @} */