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 /** 321 * Joystick key A 322 * @since 15 323 */ 324 ARKUI_KEYCODE_BUTTON_A = 2301, 325 /** 326 * Joystick key B 327 * @since 15 328 */ 329 ARKUI_KEYCODE_BUTTON_B = 2302, 330 /** 331 * Joystick key X 332 * @since 15 333 */ 334 ARKUI_KEYCODE_BUTTON_X = 2304, 335 /** 336 * Joystick key Y 337 * @since 15 338 */ 339 ARKUI_KEYCODE_BUTTON_Y = 2305, 340 /** 341 * Joystick key L1 342 * @since 15 343 */ 344 ARKUI_KEYCODE_BUTTON_L1 = 2307, 345 /** 346 * Joystick key R1 347 * @since 15 348 */ 349 ARKUI_KEYCODE_BUTTON_R1 = 2308, 350 /** 351 * Joystick key L2 352 * @since 15 353 */ 354 ARKUI_KEYCODE_BUTTON_L2 = 2309, 355 /** 356 * Joystick key R2 357 * @since 15 358 */ 359 ARKUI_KEYCODE_BUTTON_R2 = 2310, 360 /** 361 * Joystick key Select 362 * @since 15 363 */ 364 ARKUI_KEYCODE_BUTTON_SELECT = 2311, 365 /** 366 * Joystick key Start 367 * @since 15 368 */ 369 ARKUI_KEYCODE_BUTTON_START = 2312, 370 /** 371 * Joystick key Mode 372 * @since 15 373 */ 374 ARKUI_KEYCODE_BUTTON_MODE = 2313, 375 /** 376 * Joystick key THUMBL 377 * @since 15 378 */ 379 ARKUI_KEYCODE_BUTTON_THUMBL = 2314, 380 /** 381 * Joystick key THUMBR 382 * @since 15 383 */ 384 ARKUI_KEYCODE_BUTTON_THUMBR = 2315, 385 } ArkUI_KeyCode; 386 387 /** 388 * @brief Defines an enum for the key event types. 389 * 390 * @since 14 391 */ 392 typedef enum { 393 /** Unknown type **/ 394 ARKUI_KEY_EVENT_UNKNOWN = -1, 395 /** Pressing of a key **/ 396 ARKUI_KEY_EVENT_DOWN = 0, 397 /** Release of a key **/ 398 ARKUI_KEY_EVENT_UP = 1, 399 /** Long press of a key **/ 400 ARKUI_KEY_EVENT_LONG_PRESS = 2, 401 /** Click of a key **/ 402 ARKUI_KEY_EVENT_CLICK = 3, 403 } ArkUI_KeyEventType; 404 405 /** 406 * @brief Defines an enum for the types of devices that trigger a key event. 407 * 408 * @since 14 409 */ 410 typedef enum { 411 /** Unknown type **/ 412 ARKUI_KEY_SOURCE_UNKNOWN = 0, 413 /** Mouse **/ 414 ARKUI_KEY_SOURCE_TYPE_MOUSE = 1, 415 /** Keyboard **/ 416 ARKUI_KEY_SOURCE_TYPE_KEYBOARD = 4, 417 /** 418 * @brief Joystick. 419 * 420 * @since 15 421 */ 422 ARKUI_KEY_SOURCE_TYPE_JOYSTICK = 5, 423 } ArkUI_KeySourceType; 424 425 /** 426 * @brief Defines an enum for key intentions. 427 * 428 * @since 14 429 */ 430 typedef enum { 431 /** Unknown intention **/ 432 ARKUI_KEY_INTENSION_UNKNOWN = -1, 433 /**Upward**/ 434 ARKUI_KEY_INTENSION_UP = 1, 435 /** Downward **/ 436 ARKUI_KEY_INTENSION_DOWN = 2, 437 /** Leftward **/ 438 ARKUI_KEY_INTENSION_LEFT = 3, 439 /** Rightward **/ 440 ARKUI_KEY_INTENSION_RIGHT = 4, 441 /** Select **/ 442 ARKUI_KEY_INTENSION_SELECT = 5, 443 /** Escape **/ 444 ARKUI_KEY_INTENSION_ESCAPE = 6, 445 /** Back**/ 446 ARKUI_KEY_INTENSION_BACK = 7, 447 /** Forward **/ 448 ARKUI_KEY_INTENSION_FORWARD = 8, 449 /** Menu **/ 450 ARKUI_KEY_INTENSION_MENU = 9, 451 /** Home **/ 452 ARKUI_KEY_INTENSION_HOME = 10, 453 /** Page up **/ 454 ARKUI_KEY_INTENSION_PAGE_UP = 11, 455 /** Page down **/ 456 ARKUI_KEY_INTENSION_PAGE_DOWN = 12, 457 /** Zoom out **/ 458 ARKUI_KEY_INTENSION_ZOOM_OUT = 13, 459 /** Zoom in **/ 460 ARKUI_KEY_INTENSION_ZOOM_IN = 14, 461 462 /** Play or pause **/ 463 ARKUI_KEY_INTENTION_MEDIA_PLAY_PAUSE = 100, 464 /** Fast-forward **/ 465 ARKUI_KEY_INTENTION_MEDIA_FAST_FORWARD = 101, 466 /** Fast playback **/ 467 ARKUI_KEY_INTENTION_MEDIA_FAST_PLAYBACK = 103, 468 /** Play next **/ 469 ARKUI_KEY_INTENTION_MEDIA_NEXT = 104, 470 /** Play previous **/ 471 ARKUI_KEY_INTENTION_MEDIA_PREVIOUS = 105, 472 /** Mute **/ 473 ARKUI_KEY_INTENTION_MEDIA_MUTE = 106, 474 /** Volume up **/ 475 ARKUI_KEY_INTENTION_VOLUME_UP = 107, 476 /** Volume down **/ 477 ARKUI_KEY_INTENTION_VOLUME_DOWN = 108, 478 479 /** Answer a call **/ 480 ARKUI_KEY_INTENTION_CALL = 200, 481 /** Camera **/ 482 ARKUI_KEY_INTENTION_CAMERA = 300, 483 } ArkUI_KeyIntension; 484 485 /** 486 * @brief Obtains the type of a key event. 487 * 488 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 489 * @return Returns the key event type. 490 * @since 14 491 */ 492 ArkUI_KeyEventType OH_ArkUI_KeyEvent_GetType(const ArkUI_UIInputEvent* event); 493 494 /** 495 * @brief Obtains the key code from a key event. 496 * 497 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 498 * @return Returns the key code. 499 * @since 14 500 */ 501 int32_t OH_ArkUI_KeyEvent_GetKeyCode(const ArkUI_UIInputEvent* event); 502 503 /** 504 * @brief Obtains the key value from a key event. 505 * 506 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 507 * @return Returns the key value. 508 * @since 14 509 */ 510 const char *OH_ArkUI_KeyEvent_GetKeyText(const ArkUI_UIInputEvent* event); 511 512 /** 513 * @brief Obtains the type of device that triggers a key event. 514 * 515 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 516 * @return Returns the device type. 517 * @since 14 518 */ 519 ArkUI_KeySourceType OH_ArkUI_KeyEvent_GetKeySource(const ArkUI_UIInputEvent* event); 520 521 /** 522 * @brief Prevents a key event from bubbling up. 523 * 524 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 525 * @param stopPropagation Whether to stop event propagation. 526 * @since 14 527 */ 528 void OH_ArkUI_KeyEvent_StopPropagation(const ArkUI_UIInputEvent* event, bool stopPropagation); 529 530 /** 531 * @brief Obtains the intention code associated with a key event. 532 * 533 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 534 * @return Returns the intention code associated with the key event. 535 * @since 14 536 */ 537 ArkUI_KeyIntension OH_ArkUI_KeyEvent_GetKeyIntensionCode(const ArkUI_UIInputEvent* event); 538 539 /** 540 * @brief Obtains the Unicode value associated with a key event. 541 * Non-space basic Latin characters in the 0x0021-0x007E range are supported. Characters with a value of 0 are not 542 * supported. In the case of key combination, this API returns the Unicode value of the key corresponding to the key 543 * event. 544 * 545 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 546 * @return Returns the Unicode value. 547 * @since 14 548 */ 549 uint32_t OH_ArkUI_KeyEvent_GetUnicode(const ArkUI_UIInputEvent* event); 550 551 /** 552 * @brief Sets whether a key event is consumed in the key event callback. 553 * 554 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 555 * @param isConsumed Whether the event is consumed. 556 * @since 14 557 */ 558 void OH_ArkUI_KeyEvent_SetConsumed(const ArkUI_UIInputEvent* event, bool isConsumed); 559 560 /** 561 * @brief Dispatch key event to a specific component node. 562 * 563 * @param node Indicates the pointer to a component node. 564 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 565 * @since 16 566 */ 567 void OH_ArkUI_KeyEvent_Dispatch(ArkUI_NodeHandle node, const ArkUI_UIInputEvent* event); 568 #ifdef __cplusplus 569 }; 570 #endif 571 572 #endif // ARKUI_NATIVE_KEY_EVENT_H 573 /** @} */