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_EventModule 18 * @{ 19 * 20 * @brief Declares the UI input event capabilities provided by ArkUI on the native side. 21 * 22 * @since 12 23 */ 24 25 /** 26 * @file ui_input_event.h 27 * 28 * @brief Provides ArkUI event definitions on the native side. 29 * 30 * @library libace_ndk.z.so 31 * @syscap SystemCapability.ArkUI.ArkUI.Full 32 * @kit ArkUI 33 * @since 12 34 */ 35 36 #ifndef _ARKUI_UI_INPUT_EVENT_H_ 37 #define _ARKUI_UI_INPUT_EVENT_H_ 38 39 #include <stdint.h> 40 41 #include "native_type.h" 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 /** 47 * @brief Defines the UI input event. 48 * 49 * @since 12 50 */ 51 typedef struct ArkUI_UIInputEvent ArkUI_UIInputEvent; 52 53 /** 54 * @brief Enumerates the UI input event types. 55 * 56 * @since 12 57 */ 58 typedef enum { 59 ARKUI_UIINPUTEVENT_TYPE_UNKNOWN = 0, 60 ARKUI_UIINPUTEVENT_TYPE_TOUCH = 1, 61 ARKUI_UIINPUTEVENT_TYPE_AXIS = 2, 62 /** Mouse event. */ 63 ARKUI_UIINPUTEVENT_TYPE_MOUSE = 3, 64 } ArkUI_UIInputEvent_Type; 65 66 /** 67 * @brief Defines the action code of the input event. 68 * 69 * @since 12 70 */ 71 enum { 72 /** Cancellation of touch. */ 73 UI_TOUCH_EVENT_ACTION_CANCEL = 0, 74 /** Pressing of a touch point. */ 75 UI_TOUCH_EVENT_ACTION_DOWN = 1, 76 /** Moving of a touch point. */ 77 UI_TOUCH_EVENT_ACTION_MOVE = 2, 78 /** Lifting of a touch point. */ 79 UI_TOUCH_EVENT_ACTION_UP = 3, 80 }; 81 82 /** 83 * @brief Defines the tool type of the touch event. 84 * 85 * @since 12 86 */ 87 enum { 88 /** Unknown tool type. */ 89 UI_INPUT_EVENT_TOOL_TYPE_UNKNOWN = 0, 90 91 /** Finger. */ 92 UI_INPUT_EVENT_TOOL_TYPE_FINGER = 1, 93 94 /** Pen. */ 95 UI_INPUT_EVENT_TOOL_TYPE_PEN = 2, 96 97 /** Mouse. */ 98 UI_INPUT_EVENT_TOOL_TYPE_MOUSE = 3, 99 100 /** TouchPad. */ 101 UI_INPUT_EVENT_TOOL_TYPE_TOUCHPAD = 4, 102 103 /** JoyStick. */ 104 UI_INPUT_EVENT_TOOL_TYPE_JOYSTICK = 5, 105 }; 106 107 /** 108 * @brief Defines the source type of the touch event. 109 * 110 * @since 12 111 */ 112 enum { 113 /** Unknown source type. */ 114 UI_INPUT_EVENT_SOURCE_TYPE_UNKNOWN = 0, 115 /** Mouse. */ 116 UI_INPUT_EVENT_SOURCE_TYPE_MOUSE = 1, 117 /** Touchscreen. */ 118 UI_INPUT_EVENT_SOURCE_TYPE_TOUCH_SCREEN = 2, 119 }; 120 121 /** 122 * @brief Enumerates the hit test modes. 123 * 124 * @since 12 125 */ 126 typedef enum { 127 /** Both the node and its child node respond to the hit test of a touch event, but its sibling node is blocked from 128 * the hit test. 129 */ 130 HTM_DEFAULT = 0, 131 132 /** The node responds to the hit test of a touch event, but its child node and sibling node are blocked from the hit 133 * test. 134 */ 135 HTM_BLOCK, 136 137 /** Both the node and its child node respond to the hit test of a touch event, and its sibling node is also 138 * considered during the hit test. 139 */ 140 HTM_TRANSPARENT, 141 142 /** The node does not respond to the hit test of a touch event, but its child node and sibling node are considered 143 * during the hit test. 144 */ 145 HTM_NONE, 146 } HitTestMode; 147 148 /** 149 * @brief Define the Action Code for mouse events. 150 * 151 * @since 12 152 */ 153 enum { 154 /** Invalid. */ 155 UI_MOUSE_EVENT_ACTION_UNKNOWN = 0, 156 /** Press. */ 157 UI_MOUSE_EVENT_ACTION_PRESS = 1, 158 /** Release. */ 159 UI_MOUSE_EVENT_ACTION_RELEASE = 2, 160 /** Move. */ 161 UI_MOUSE_EVENT_ACTION_MOVE = 3, 162 }; 163 164 /** 165 * @brief Define the button type for mouse events. 166 * 167 * @since 12 168 */ 169 enum { 170 /** None. */ 171 UI_MOUSE_EVENT_BUTTON_NONE = 0, 172 /** Left. */ 173 UI_MOUSE_EVENT_BUTTON_LEFT = 1, 174 /** Right. */ 175 UI_MOUSE_EVENT_BUTTON_RIGHT = 2, 176 /** Middle. */ 177 UI_MOUSE_EVENT_BUTTON_MIDDLE = 3, 178 /** Back. */ 179 UI_MOUSE_EVENT_BUTTON_BACK = 4, 180 /** Forward. */ 181 UI_MOUSE_EVENT_BUTTON_FORWARD = 5, 182 }; 183 184 /** 185 * @brief Defines an enum for modifier keys. 186 * 187 * @since 12 188 */ 189 typedef enum { 190 /** Ctrl. */ 191 ARKUI_MODIFIER_KEY_CTRL = 1 << 0, 192 /** Shift. */ 193 ARKUI_MODIFIER_KEY_SHIFT = 1 << 1, 194 /** Alt. */ 195 ARKUI_MODIFIER_KEY_ALT = 1 << 2, 196 /** Fn. */ 197 ARKUI_MODIFIER_KEY_FN = 1 << 3, 198 } ArkUI_ModifierKeyName; 199 200 /** 201 * @brief Defines whether the touch event is from the left or right hand. 202 * 203 * @since 15 204 */ 205 typedef enum { 206 /** Unknown. */ 207 ARKUI_EVENT_HAND_NONE = 0, 208 /** Left hand. */ 209 ARKUI_EVENT_HAND_LEFT = 1, 210 /** Right hand. */ 211 ARKUI_EVENT_HAND_RIGHT = 2, 212 } ArkUI_InteractionHand; 213 214 /** 215 * @brief Defines an enum for the axis types for focus axis events. 216 * 217 * @since 15 218 */ 219 enum { 220 /** ABS_X. */ 221 UI_FOCUS_AXIS_EVENT_ABS_X = 0, 222 /** ABS_Y. */ 223 UI_FOCUS_AXIS_EVENT_ABS_Y = 1, 224 /** ABS_Z. */ 225 UI_FOCUS_AXIS_EVENT_ABS_Z = 2, 226 /** ABS_RZ. */ 227 UI_FOCUS_AXIS_EVENT_ABS_RZ = 3, 228 /** ABS_GAS. */ 229 UI_FOCUS_AXIS_EVENT_ABS_GAS = 4, 230 /** ABS_BRAKE. */ 231 UI_FOCUS_AXIS_EVENT_ABS_BRAKE = 5, 232 /** ABS_HAT0X. */ 233 UI_FOCUS_AXIS_EVENT_ABS_HAT0X = 6, 234 /** ABS_HAT0Y. */ 235 UI_FOCUS_AXIS_EVENT_ABS_HAT0Y = 7, 236 }; 237 238 /** 239 * @brief Enumerates the action types for axis events. 240 * 241 * @since 15 242 */ 243 enum { 244 /** The axis event is abnormal. */ 245 UI_AXIS_EVENT_ACTION_NONE = 0, 246 /** The axis event begins. */ 247 UI_AXIS_EVENT_ACTION_BEGIN = 1, 248 /** The axis event is updated. */ 249 UI_AXIS_EVENT_ACTION_UPDATE = 2, 250 /** The axis event ends. */ 251 UI_AXIS_EVENT_ACTION_END = 3, 252 /** The axis event is canceled. */ 253 UI_AXIS_EVENT_ACTION_CANCEL = 4, 254 }; 255 256 /** 257 * @brief Obtains the type of this UI input event. 258 * 259 * @param event Indicates the pointer to the current UI input event. 260 * @return Returns the type of the current UI input event; returns <b>0</b> if any parameter error occurs. 261 * @since 12 262 */ 263 int32_t OH_ArkUI_UIInputEvent_GetType(const ArkUI_UIInputEvent* event); 264 265 /** 266 * @brief Obtains the action type of this UI input event. 267 * 268 * @param event Indicates the pointer to the current UI input event. 269 * @return Returns the action type of the current UI input event; returns <b>0</b> if any parameter error occurs. 270 * @since 12 271 */ 272 int32_t OH_ArkUI_UIInputEvent_GetAction(const ArkUI_UIInputEvent* event); 273 274 /** 275 * @brief Obtains the source type of this UI input event. 276 * 277 * @param event Indicates the pointer to the current UI input event. 278 * @return Returns the source type of the current UI input event. 279 * @since 12 280 */ 281 int32_t OH_ArkUI_UIInputEvent_GetSourceType(const ArkUI_UIInputEvent* event); 282 283 /** 284 * @brief Obtains the tool type of this UI input event. 285 * 286 * @param event Indicates the pointer to the current UI input event. 287 * @return Returns the tool type of the current UI input event. 288 * @since 12 289 */ 290 int32_t OH_ArkUI_UIInputEvent_GetToolType(const ArkUI_UIInputEvent* event); 291 292 /** 293 * @brief Obtains the time when this UI input event occurs. 294 * 295 * @param event Indicates the pointer to the current UI input event. 296 * @return Returns the time when the UI input event occurs; returns <b>0</b> if any parameter error occurs. 297 * @since 12 298 */ 299 int64_t OH_ArkUI_UIInputEvent_GetEventTime(const ArkUI_UIInputEvent* event); 300 301 /** 302 * @brief Obtains the number of touch points from a directional input event (such as a touch event, mouse event, 303 * or axis event). 304 * 305 * @param event Indicates the pointer to the current UI input event. 306 * @return Returns the number of touch points for the directional input event. 307 * @since 12 308 */ 309 uint32_t OH_ArkUI_PointerEvent_GetPointerCount(const ArkUI_UIInputEvent* event); 310 311 /** 312 * @brief Obtains the ID of a touch point from a directional input event (such as a touch event, mouse event, 313 * or axis event). 314 * 315 * @param event Indicates the pointer to the current UI input event. 316 * @param pointerIndex Indicates the index of the target touch point in the multi-touch data list. 317 * @return Returns the ID of the corresponding touch point. 318 * @since 12 319 */ 320 int32_t OH_ArkUI_PointerEvent_GetPointerId(const ArkUI_UIInputEvent* event, uint32_t pointerIndex); 321 322 /** 323 * @brief Obtains the ID of the touch pointer that triggers the current touch event. 324 * 325 * @param event Indicates the pointer to the current UI input event. 326 * @param pointerIndex Indicates the index of the target touch point in the multi-touch data list. 327 * @return Returns the result code. 328 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 329 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 330 * @since 15 331 */ 332 int32_t OH_ArkUI_PointerEvent_GetChangedPointerId(const ArkUI_UIInputEvent* event, uint32_t* pointerIndex); 333 334 /** 335 * @brief Obtains the X coordinate relative to the upper left corner of the current component from a directional 336 * input event (such as a touch event, mouse event, or axis event). 337 * 338 * @param event Indicates the pointer to the directional input event. 339 * @return Returns the X coordinate relative to the upper left corner of the current component; 340 * returns <b>0</b> if any parameter error occurs. 341 * @since 12 342 */ 343 float OH_ArkUI_PointerEvent_GetX(const ArkUI_UIInputEvent* event); 344 345 /** 346 * @brief Obtains the X coordinate of a specific touch point relative to the upper left corner of the current component 347 * from a directional input event (such as a touch event, mouse event, or axis event). 348 * 349 * @param event Indicates the pointer to the current UI input event. 350 * @param pointerIndex Indicates the index of the target touch point in the multi-touch data list. 351 * @return Returns the X coordinate relative to the upper left corner of the current component; 352 * returns <b>0.0f</b> if any parameter error occurs. 353 * @since 12 354 */ 355 float OH_ArkUI_PointerEvent_GetXByIndex(const ArkUI_UIInputEvent* event, uint32_t pointerIndex); 356 357 /** 358 * @brief Obtains the Y coordinate relative to the upper left corner of the current component from a directional 359 * input event (such as a touch event, mouse event, or axis event). 360 * 361 * @param event Indicates the pointer to the UI input event. 362 * @return Returns the Y coordinate relative to the upper left corner of the current component; 363 * returns <b>0</b> if any parameter error occurs. 364 * @since 12 365 */ 366 float OH_ArkUI_PointerEvent_GetY(const ArkUI_UIInputEvent* event); 367 368 /** 369 * @brief Obtains the Y coordinate of a specific touch point relative to the upper left corner of the current component 370 * from a directional input event (such as a touch event, mouse event, or axis event). 371 * 372 * @param event Indicates the pointer to the current UI input event. 373 * @param pointerIndex Indicates the index of the target touch point in the multi-touch data list. 374 * @return Returns the Y coordinate relative to the upper left corner of the current component; 375 * returns <b>0.0f</b> if any parameter error occurs. 376 * @since 12 377 */ 378 float OH_ArkUI_PointerEvent_GetYByIndex(const ArkUI_UIInputEvent* event, uint32_t pointerIndex); 379 380 /** 381 * @brief Obtains the X coordinate relative to the upper left corner of the current application window from a 382 * directional input event (such as a touch event, mouse event, or axis event). 383 * 384 * @param event Indicates the pointer to the UI input event. 385 * @return Returns the X coordinate relative to the upper left corner of the current application window; 386 * returns <b>0</b> if any parameter error occurs. 387 * @since 12 388 */ 389 float OH_ArkUI_PointerEvent_GetWindowX(const ArkUI_UIInputEvent* event); 390 391 /** 392 * @brief Obtains the X coordinate of a specific touch point relative to the upper left corner of the current 393 * application window from a directional input event (such as a touch event, mouse event, or axis event). 394 * 395 * @param event Indicates the pointer to the current UI input event. 396 * @param pointerIndex Indicates the index of the target touch point in the multi-touch data list. 397 * @return Returns the X coordinate relative to the upper left corner of the current application window; 398 * returns <b>0.0f</b> if any parameter error occurs. 399 * @since 12 400 */ 401 float OH_ArkUI_PointerEvent_GetWindowXByIndex(const ArkUI_UIInputEvent* event, uint32_t pointerIndex); 402 403 /** 404 * @brief Obtains the Y coordinate relative to the upper left corner of the current application window from a 405 * directional input event (such as a touch event, mouse event, or axis event). 406 * 407 * @param event Indicates the pointer to the UI input event. 408 * @return Returns the Y coordinate relative to the upper left corner of the current application window; 409 * returns <b>0</b> if any parameter error occurs. 410 * @since 12 411 */ 412 float OH_ArkUI_PointerEvent_GetWindowY(const ArkUI_UIInputEvent* event); 413 414 /** 415 * @brief Obtains the Y coordinate of a specific touch point relative to the upper left corner of the current 416 * application window from a directional input event (such as a touch event, mouse event, or axis event). 417 * 418 * @param event Indicates the pointer to the current UI input event. 419 * @param pointerIndex Indicates the index of the target touch point in the multi-touch data list. 420 * @return Returns the Y coordinate relative to the upper left corner of the current application window; 421 * returns <b>0.0f</b> if any parameter error occurs. 422 * @since 12 423 */ 424 float OH_ArkUI_PointerEvent_GetWindowYByIndex(const ArkUI_UIInputEvent* event, uint32_t pointerIndex); 425 426 /** 427 * @brief Obtains the X coordinate relative to the upper left corner of the current screen from a directional input 428 * event (such as a touch event, mouse event, or axis event). 429 * 430 * @param event Indicates the pointer to the UI input event. 431 * @return Returns the X coordinate relative to the upper left corner of the current screen; 432 * returns <b>0</b> if any parameter error occurs. 433 * @since 12 434 */ 435 float OH_ArkUI_PointerEvent_GetDisplayX(const ArkUI_UIInputEvent* event); 436 437 /** 438 * @brief Obtains the X coordinate of a specific touch point relative to the upper left corner of the current screen 439 * from a directional input event (such as a touch event, mouse event, or axis event). 440 * 441 * @param event Indicates the pointer to the current UI input event. 442 * @param pointerIndex Indicates the index of the target touch point in the multi-touch data list. 443 * @return Returns the X coordinate relative to the upper left corner of the current screen; 444 * returns <b>0.0f</b> if any parameter error occurs. 445 * @since 12 446 */ 447 float OH_ArkUI_PointerEvent_GetDisplayXByIndex(const ArkUI_UIInputEvent* event, uint32_t pointerIndex); 448 449 /** 450 * @brief Obtains the Y coordinate relative to the upper left corner of the current screen from a directional input 451 * event (such as a touch event, mouse event, or axis event). 452 * 453 * @param event Indicates the pointer to the UI input event. 454 * @return Returns the Y coordinate relative to the upper left corner of the current screen; 455 * returns <b>0</b> if any parameter error occurs. 456 * @since 12 457 */ 458 float OH_ArkUI_PointerEvent_GetDisplayY(const ArkUI_UIInputEvent* event); 459 460 /** 461 * @brief Obtains the Y coordinate of a specific touch point relative to the upper left corner of the current screen 462 * from a directional input event (such as a touch event, mouse event, or axis event). 463 * 464 * @param event Indicates the pointer to the current UI input event. 465 * @param pointerIndex Indicates the index of the target touch point in the multi-touch data list. 466 * @return Returns the Y coordinate relative to the upper left corner of the current screen; 467 * returns <b>0.0f</b> if any parameter error occurs. 468 * @since 12 469 */ 470 float OH_ArkUI_PointerEvent_GetDisplayYByIndex(const ArkUI_UIInputEvent* event, uint32_t pointerIndex); 471 472 /** 473 * @brief Obtains the pressure applied to the touchscreen from a directional input event (for example, a touch event). 474 * 475 * @param event Indicates the pointer to the current UI input event. 476 * @param pointerIndex Indicates the index of the target touch point in the multi-touch data list. 477 * @return Returns the pressure applied to the touchscreen; returns <b>0.0f</b> if any parameter error occurs. 478 * @since 12 479 */ 480 float OH_ArkUI_PointerEvent_GetPressure(const ArkUI_UIInputEvent* event, uint32_t pointerIndex); 481 482 /** 483 * @brief Obtains the angle relative to the YZ plane from a directional input event (for example, a touch event). 484 * The value range is [-90, 90]. A positive value indicates a rightward tilt. 485 * 486 * @param event Indicates the pointer to the current UI input event. 487 * @param pointerIndex Indicates the index of the target touch point in the multi-touch data list. 488 * @return Returns the angle relative to the YZ plane. 489 * @since 12 490 */ 491 float OH_ArkUI_PointerEvent_GetTiltX(const ArkUI_UIInputEvent* event, uint32_t pointerIndex); 492 493 /** 494 * @brief Obtains the angle relative to the XZ plane from a directional input event (for example, a touch event). 495 * The value range is [-90, 90]. A positive value indicates a downward tilt. 496 * 497 * @param event Indicates the pointer to the current UI input event. 498 * @param pointerIndex Indicates the index of the target touch point in the multi-touch data list. 499 * @return Returns the angle relative to the XZ plane. 500 * @since 12 501 */ 502 float OH_ArkUI_PointerEvent_GetTiltY(const ArkUI_UIInputEvent* event, uint32_t pointerIndex); 503 504 /** 505 * @brief Obtains the width of the touch area from a directional input event (for example, a touch event). 506 * 507 * @param event Indicates the pointer to the current UI input event. 508 * @param pointerIndex Indicates the index of the target touch point in the multi-touch data list. 509 * @return Returns the width of the touch area. 510 * @since 12 511 */ 512 float OH_ArkUI_PointerEvent_GetTouchAreaWidth(const ArkUI_UIInputEvent* event, uint32_t pointerIndex); 513 514 /** 515 * @brief Obtains the height of the touch area from a directional input event (for example, a touch event). 516 * 517 * @param event Indicates the pointer to the current UI input event. 518 * @param pointerIndex Indicates the index of the target touch point in the multi-touch data list. 519 * @return Returns the height of the touch area. 520 * @since 12 521 */ 522 float OH_ArkUI_PointerEvent_GetTouchAreaHeight(const ArkUI_UIInputEvent* event, uint32_t pointerIndex); 523 524 /** 525 * @brief Obtains whether the current touch event is from the left or right hand. 526 * 527 * @param event Pointer to the current UI input event. 528 * @param hand Whether the touch point is from the left or right hand. 529 * @return Returns the result code. 530 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 531 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 532 * @since 15 533 */ 534 int32_t OH_ArkUI_PointerEvent_GetInteractionHand(const ArkUI_UIInputEvent *event, ArkUI_InteractionHand *hand); 535 536 /** 537 * @brief Obtains whether the current touch event is from the left or right hand. 538 * 539 * @param event Pointer to the current UI input event. 540 * @param pointerIndex Index of the target touch point in the multi-touch data list. 541 * @param hand Whether the touch point is from the left or right hand. 542 * @return Returns the result code. 543 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 544 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 545 * @since 15 546 */ 547 int32_t OH_ArkUI_PointerEvent_GetInteractionHandByIndex( 548 const ArkUI_UIInputEvent *event, int32_t pointerIndex, ArkUI_InteractionHand *hand); 549 550 /** 551 * @brief Obtains the number of historical events from a directional input event (such as a touch event, mouse event, 552 * or axis event). 553 * 554 * @param event Indicates the pointer to the current UI input event. 555 * @return Returns the number of historical events. 556 * @since 12 557 */ 558 uint32_t OH_ArkUI_PointerEvent_GetHistorySize(const ArkUI_UIInputEvent* event); 559 560 /** 561 * @brief Obtains the occurrence time of a historical event from a directional input event (such as a touch event, 562 * mouse event, or axis event). 563 * 564 * @param event Indicates the pointer to the current UI input event. 565 * @param historyIndex Indicates the index of the target historical event. 566 * @return Returns the time when the UI input event occurs; returns <b>0</b> if any parameter error occurs. 567 * @since 12 568 */ 569 int64_t OH_ArkUI_PointerEvent_GetHistoryEventTime(const ArkUI_UIInputEvent* event, uint32_t historyIndex); 570 571 /** 572 * @brief Obtains the number of touch points in a specific historical event from a directional input event (such as 573 * a touch event, mouse event, or axis event). 574 * 575 * @param event Indicates the pointer to the current UI input event. 576 * @param historyIndex Indicates the index of the target historical event. 577 * @return Returns the number of touch points in the specified historical event 578 * @since 12 579 */ 580 uint32_t OH_ArkUI_PointerEvent_GetHistoryPointerCount(const ArkUI_UIInputEvent* event, uint32_t historyIndex); 581 582 /** 583 * @brief Obtains the ID of a touch point in a specific historical event from a directional input event (such as 584 * a touch event, mouse event, or axis event). 585 * 586 * @param event Indicates the pointer to the current UI input event. 587 * @param pointerIndex Indicates the index of the target touch point in the multi-touch data list. 588 * @param historyIndex Indicates the index of the target historical event. 589 * @return Returns the ID of the corresponding touch point in the specified historical event. 590 * @since 12 591 */ 592 int32_t OH_ArkUI_PointerEvent_GetHistoryPointerId( 593 const ArkUI_UIInputEvent* event, uint32_t pointerIndex, uint32_t historyIndex); 594 595 /** 596 * @brief Obtains the X coordinate of a specific touch point in a historical event relative to the upper left corner 597 * of the current component from a directional input event (such as a touch event, mouse event, or axis event). 598 * 599 * @param event Indicates the pointer to the current UI input event. 600 * @param pointerIndex Indicates the index of the target touch point in the multi-touch data list. 601 * @param historyIndex Indicates the index of the target historical event. 602 * @return Returns the X coordinate relative to the upper left corner of the current component; 603 * returns <b>0.0f</b> if any parameter error occurs. 604 * @since 12 605 */ 606 float OH_ArkUI_PointerEvent_GetHistoryX(const ArkUI_UIInputEvent* event, uint32_t pointerIndex, uint32_t historyIndex); 607 608 /** 609 * @brief Obtains the Y coordinate of a specific touch point in a historical event relative to the upper left corner 610 * of the current component from a directional input event (such as a touch event, mouse event, or axis event). 611 * 612 * @param event Indicates the pointer to the current UI input event. 613 * @param pointerIndex Indicates the index of the target touch point in the multi-touch data list. 614 * @param historyIndex Indicates the index of the target historical event. 615 * @return Returns the Y coordinate relative to the upper left corner of the current component; 616 * returns <b>0.0f</b> if any parameter error occurs. 617 * @since 12 618 */ 619 float OH_ArkUI_PointerEvent_GetHistoryY(const ArkUI_UIInputEvent* event, uint32_t pointerIndex, uint32_t historyIndex); 620 621 /** 622 * @brief Obtains the X coordinate of a specific touch point in a historical event relative to the upper left corner 623 * of the current application window from a directional input event (such as a touch event, mouse event, or axis event). 624 * 625 * @param event Indicates the pointer to the current UI input event. 626 * @param pointerIndex Indicates the index of the target touch point in the multi-touch data list. 627 * @param historyIndex Indicates the index of the target historical event. 628 * @return Returns the X coordinate relative to the upper left corner of the current application window; 629 * returns <b>0.0f</b> if any parameter error occurs. 630 * @since 12 631 */ 632 float OH_ArkUI_PointerEvent_GetHistoryWindowX( 633 const ArkUI_UIInputEvent* event, uint32_t pointerIndex, uint32_t historyIndex); 634 635 /** 636 * @brief Obtains the Y coordinate of a specific touch point in a historical event relative to the upper left corner 637 * of the current application window from a directional input event (such as a touch event, mouse event, or axis event). 638 * 639 * @param event Indicates the pointer to the current UI input event. 640 * @param pointerIndex Indicates the index of the target touch point in the multi-touch data list. 641 * @param historyIndex Indicates the index of the target historical event. 642 * @return Returns the Y coordinate relative to the upper left corner of the current application window; 643 * returns <b>0.0f</b> if any parameter error occurs. 644 * @since 12 645 */ 646 float OH_ArkUI_PointerEvent_GetHistoryWindowY( 647 const ArkUI_UIInputEvent* event, uint32_t pointerIndex, uint32_t historyIndex); 648 649 /** 650 * @brief Obtains the X coordinate of a specific touch point in a historical event relative to the upper left corner 651 * of the current screen from a directional input event (such as a touch event, mouse event, or axis event). 652 * 653 * @param event Indicates the pointer to the current UI input event. 654 * @param pointerIndex Indicates the index of the target touch point in the multi-touch data list. 655 * @param historyIndex Indicates the index of the target historical event. 656 * @return Returns the X coordinate relative to the upper left corner of the current screen; 657 * returns <b>0.0f</b> if any parameter error occurs. 658 * @since 12 659 */ 660 float OH_ArkUI_PointerEvent_GetHistoryDisplayX( 661 const ArkUI_UIInputEvent* event, uint32_t pointerIndex, uint32_t historyIndex); 662 663 /** 664 * @brief Obtains the Y coordinate of a specific touch point in a historical event relative to the upper left corner 665 * of the current screen from a directional input event (such as a touch event, mouse event, or axis event). 666 * 667 * @param event Indicates the pointer to the current UI input event. 668 * @param pointerIndex Indicates the index of the target touch point in the multi-touch data list. 669 * @param historyIndex Indicates the index of the target historical event. 670 * @return Returns the Y coordinate relative to the upper left corner of the current screen; 671 * returns <b>0.0f</b> if any parameter error occurs. 672 * @since 12 673 */ 674 float OH_ArkUI_PointerEvent_GetHistoryDisplayY( 675 const ArkUI_UIInputEvent* event, uint32_t pointerIndex, uint32_t historyIndex); 676 677 /** 678 * @brief Obtains the pressure applied to the touchscreen in a specific historical event from a directional input event 679 * (for example, a touch event).. 680 * 681 * @param event Indicates the pointer to the current UI input event. 682 * @param pointerIndex Indicates the index of the target touch point in the multi-touch data list. 683 * @param historyIndex Indicates the index of the target historical event. 684 * @return Returns the pressure applied to the touchscreen; returns <b>0.0f</b> if any parameter error occurs. 685 * @since 12 686 */ 687 float OH_ArkUI_PointerEvent_GetHistoryPressure( 688 const ArkUI_UIInputEvent* event, uint32_t pointerIndex, uint32_t historyIndex); 689 690 /** 691 * @brief Obtains the angle relative to the YZ plane in a specific historical event from a directional input event 692 * (for example, a touch event). The value range is [-90, 90]. A positive value indicates a rightward tilt. 693 * 694 * @param event Indicates the pointer to the current UI input event. 695 * @param pointerIndex Indicates the index of the target touch point in the multi-touch data list. 696 * @param historyIndex Indicates the index of the target historical event. 697 * @return Returns the angle relative to the YZ plane. 698 * @since 12 699 */ 700 float OH_ArkUI_PointerEvent_GetHistoryTiltX( 701 const ArkUI_UIInputEvent* event, uint32_t pointerIndex, uint32_t historyIndex); 702 703 /** 704 * @brief Obtains the angle relative to the XZ plane in a specific historical event from a directional input event 705 * (for example, a touch event). The value range is [-90, 90]. A positive value indicates a downward tilt. 706 * 707 * @param event Indicates the pointer to the current UI input event. 708 * @param pointerIndex Indicates the index of the target touch point in the multi-touch data list. 709 * @param historyIndex Indicates the index of the target historical event. 710 * @return Returns the angle relative to the XZ plane. 711 * @since 12 712 */ 713 float OH_ArkUI_PointerEvent_GetHistoryTiltY( 714 const ArkUI_UIInputEvent* event, uint32_t pointerIndex, uint32_t historyIndex); 715 716 /** 717 * @brief Obtains the width of the touch area in a specific historical event from a directional input event 718 * (for example, a touch event). 719 * 720 * @param event Indicates the pointer to the current UI input event. 721 * @param pointerIndex Indicates the index of the target touch point in the multi-touch data list. 722 * @param historyIndex Indicates the index of the target historical event. 723 * @return Returns the width of the touch area. 724 * @since 12 725 */ 726 float OH_ArkUI_PointerEvent_GetHistoryTouchAreaWidth( 727 const ArkUI_UIInputEvent* event, uint32_t pointerIndex, uint32_t historyIndex); 728 729 /** 730 * @brief Obtains the height of the touch area in a specific historical event from a directional input event 731 * (for example, a touch event). 732 * 733 * @param event Indicates the pointer to the current UI input event. 734 * @param pointerIndex Indicates the index of the target touch point in the multi-touch data list. 735 * @param historyIndex Indicates the index of the target historical event. 736 * @return Returns the height of the touch area. 737 * @since 12 738 */ 739 float OH_ArkUI_PointerEvent_GetHistoryTouchAreaHeight( 740 const ArkUI_UIInputEvent* event, uint32_t pointerIndex, uint32_t historyIndex); 741 742 /** 743 * @brief Obtains the value of the vertical scroll axis for this axis event. 744 * 745 * @param event Indicates the pointer to the UI input event. 746 * @return Returns the value of the vertical scroll axis of the current axis event; 747 * returns <b>0</b> if any parameter error occurs. 748 * @since 12 749 */ 750 double OH_ArkUI_AxisEvent_GetVerticalAxisValue(const ArkUI_UIInputEvent* event); 751 752 /** 753 * @brief Obtains the value of the horizontal scroll axis for this axis event. 754 * 755 * @param event Indicates the pointer to the UI input event. 756 * @return Returns the value of the horizontal scroll axis of the current axis event; 757 * returns <b>0</b> if any parameter error occurs. 758 * @since 12 759 */ 760 double OH_ArkUI_AxisEvent_GetHorizontalAxisValue(const ArkUI_UIInputEvent* event); 761 762 /** 763 * @brief Obtains the scale value of the pinch axis for this axis event. 764 * 765 * @param event Indicates the pointer to the UI input event. 766 * @return Returns the scale value of the pinch axis of the current axis event; 767 * returns <b>0</b> if any parameter error occurs. 768 * @since 12 769 */ 770 double OH_ArkUI_AxisEvent_GetPinchAxisScaleValue(const ArkUI_UIInputEvent* event); 771 772 /** 773 * @brief Obtains the action type of the current axis event. 774 * 775 * @param event Indicates the pointer to the current UI input event. 776 * @return Returns the action type of the current axis event. 777 * @since 15 778 */ 779 int32_t OH_ArkUI_AxisEvent_GetAxisAction(const ArkUI_UIInputEvent* event); 780 781 /** 782 * @brief Sets how the component behaves during hit testing. 783 * 784 * @param event Indicates the pointer to the current UI input event. 785 * @param mode Indicates how the component behaves during hit testing. The parameter type is {@link HitTestMode}. 786 * @return Returns the status code of the execution. 787 * @since 12 788 */ 789 int32_t OH_ArkUI_PointerEvent_SetInterceptHitTestMode(const ArkUI_UIInputEvent* event, HitTestMode mode); 790 791 /** 792 * @brief Get the value of the button type for mouse events. 793 * 794 * @param event Represents a pointer to the current UI input event. 795 * @return Return to the mouse button type, where <b>1</b> is the left button, <b>2</b> is the right button, 796 * <b>3</b> is the middle button, <b>4</b> is the back button, and <b>5</b> is the forward button. 797 * @since 12 798 */ 799 int32_t OH_ArkUI_MouseEvent_GetMouseButton(const ArkUI_UIInputEvent* event); 800 801 /** 802 * @brief Get the value of the mouse action type for mouse events. 803 * 804 * @param event Represents a pointer to the current UI input event. 805 * @return Returns the type of mouse action, where <b>1</b> represents button pressed, 806 * <b>2</b> represents button released, and <b>3</b> represents mouse movement. 807 * @since 12 808 */ 809 int32_t OH_ArkUI_MouseEvent_GetMouseAction(const ArkUI_UIInputEvent* event); 810 811 /** 812 * @brief Sets whether to prevent event bubbling. 813 * 814 * @param event Indicates the pointer to the current UI input event. 815 * @param stopPropagation Indicates whether the event is prevented from bubbling. 816 * @return Returns the status code of the execution. If 0 is returned, the setting is successful. 817 * If 401 is returned, the execution fails. 818 * The possible cause of the failure is that the event parameter is abnormal, such as a null pointer. 819 * @since 12 820 */ 821 int32_t OH_ArkUI_PointerEvent_SetStopPropagation(const ArkUI_UIInputEvent* event, bool stopPropagation); 822 823 /** 824 * @brief Obtains the ID of device that triggers UI input event. 825 * 826 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 827 * @return Returns the device ID. 828 * @since 14 829 */ 830 int32_t OH_ArkUI_UIInputEvent_GetDeviceId(const ArkUI_UIInputEvent* event); 831 832 /** 833 * @brief Obtains the pressed status of modifier keys from UI input event. 834 * The following modifier keys are supported: Ctrl, Alt, Shift, Fn. However, the <b>Fn</b> key on external keyboards 835 * is not supported. 836 * 837 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 838 * @param pressedKeyCodes Array of all keys that are pressed. You need to allocate the memory space. 839 * @param length Length of the passed pressedKeyCodes array (when used as an input parameter); 840 * number of the keys pressed (when used as an output parameter). 841 * @return Returns the result code. 842 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 843 * Returns {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} if the giving buffer is not enough. 844 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 845 * @since 14 846 */ 847 int32_t OH_ArkUI_UIInputEvent_GetPressedKeys( 848 const ArkUI_UIInputEvent* event, int32_t* pressedKeyCodes, int32_t* length); 849 850 /** 851 * @brief Obtains the axis value of a focus axis event. 852 * 853 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 854 * @param axis Axis type of the focus axis event. 855 * @return Returns the axis value of the focus axis event; returns <b>0.0</b> if any parameter error occurs. 856 * @since 15 857 */ 858 double OH_ArkUI_FocusAxisEvent_GetAxisValue(const ArkUI_UIInputEvent* event, int32_t axis); 859 860 /** 861 * @brief Sets whether to prevent a focus axis event from bubbling up. 862 * 863 * @param event Indicates the pointer to the current UI input event. 864 * @param stopPropagation Indicates whether to stop event propagation. 865 * @return Returns the result code. 866 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 867 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 868 * @since 15 869 */ 870 int32_t OH_ArkUI_FocusAxisEvent_SetStopPropagation(const ArkUI_UIInputEvent* event, bool stopPropagation); 871 872 /** 873 * @brief Obtains the press time of a specific touch point. 874 * 875 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 876 * @param pointerIndex Index of the target touch point in the multi-touch data list. 877 * @return Returns the press time of the specific touch point; returns <b>0</b> if any parameter error occurs. 878 * @since 15 879 */ 880 int64_t OH_ArkUI_PointerEvent_GetPressedTimeByIndex(const ArkUI_UIInputEvent* event, uint32_t pointerIndex); 881 882 /** 883 * @brief Obtains the x-axis offset of the mouse pointer position relative to the position in the previously reported 884 * mouse event. This value may be less than the difference between the two reported X coordinates when the mouse pointer 885 * is near the screen edge. 886 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 887 * @return Returns the x-axis offset of the mouse pointer position relative to the position in the previously reported 888 * mouse event; returns <b>0.0f</b> if any parameter error occurs. 889 * @since 15 890 */ 891 float OH_ArkUI_MouseEvent_GetRawDeltaX(const ArkUI_UIInputEvent* event); 892 893 /** 894 * @brief Obtains the y-axis offset of the mouse pointer position relative to the position in the previously reported 895 * mouse event. This value may be less than the difference between the two reported Y coordinates when the mouse pointer 896 * is near the screen edge. 897 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 898 * @return Returns the y-axis offset of the mouse pointer position relative to the position in the previously reported 899 * mouse event; returns <b>0.0f</b> if any parameter error occurs. 900 * @since 15 901 */ 902 float OH_ArkUI_MouseEvent_GetRawDeltaY(const ArkUI_UIInputEvent* event); 903 904 /** 905 * @brief Obtains the pressed buttons from a mouse event. 906 * 907 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 908 * @param pressedButtons Array of the pressed buttons. An int array must be created beforehand to store the pressed 909 * buttons. 910 * @param length Length of the passed pressedButtons array (when used as an input parameter); 911 * number of the buttons pressed (when used as an output parameter). 912 * @return Returns the result code. 913 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 914 * Returns {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} if the given buffer size is insufficient. 915 * @since 15 916 */ 917 int32_t OH_ArkUI_MouseEvent_GetPressedButtons( 918 const ArkUI_UIInputEvent* event, int32_t* pressedButtons, int32_t* length); 919 920 /** 921 * @brief Obtains the ID of the screen where the UI input event occurs. 922 * 923 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 924 * @return Returns the screen ID; returns <b>0</b> if any parameter error occurs. 925 * @since 15 926 */ 927 int32_t OH_ArkUI_UIInputEvent_GetTargetDisplayId(const ArkUI_UIInputEvent* event); 928 929 /** 930 * @brief Creates a cloned event pointer based on an event pointer. 931 * 932 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 933 * @param clonedEvent Pointer to the cloned <b>ArkUI_UIInputEvent</b> object. 934 * @return Returns the result code. 935 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 936 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 937 * @since 15 938 */ 939 int32_t OH_ArkUI_PointerEvent_CreateClonedEvent(const ArkUI_UIInputEvent* event, ArkUI_UIInputEvent** clonedEvent); 940 941 /** 942 * @brief Destroys a cloned event pointer. 943 * 944 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 945 * @return Returns the result code. 946 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 947 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 948 * Returns {@link ARKUI_ERROR_CODE_NON_CLONED_POINTER_EVENT} if the input event pointer is not a 949 * cloned event pointer. 950 * @since 15 951 */ 952 int32_t OH_ArkUI_PointerEvent_DestroyClonedEvent(const ArkUI_UIInputEvent* event); 953 954 /** 955 * @brief Sets the X and Y coordinates of a cloned event relative to the upper left corner of the current component. 956 * 957 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 958 * @param x X coordinate of the event relative to the upper left corner of the current component. 959 * @param y Y coordinate of the event relative to the upper left corner of the current component. 960 * @return Returns the result code. 961 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 962 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 963 * Returns {@link ARKUI_ERROR_CODE_NON_CLONED_POINTER_EVENT} if the input event pointer is not a 964 * cloned event pointer. 965 * @since 15 966 */ 967 int32_t OH_ArkUI_PointerEvent_SetClonedEventLocalPosition(const ArkUI_UIInputEvent* event, float x, float y); 968 969 /** 970 * @brief Sets the X and Y coordinates of a specific contact point of a cloned event relative to the upper left corner 971 * of the current component. 972 * 973 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 974 * @param x X coordinate of the event relative to the upper left corner of the current component. 975 * @param y Y coordinate of the event relative to the upper left corner of the current component. 976 * @param pointerIndex Index of the target touch point in the multi-touch data list. 977 * @return Returns the result code. 978 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 979 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 980 * Returns {@link ARKUI_ERROR_CODE_NON_CLONED_POINTER_EVENT} if the input event pointer is not a 981 * cloned event pointer. 982 * @since 15 983 */ 984 int32_t OH_ArkUI_PointerEvent_SetClonedEventLocalPositionByIndex( 985 const ArkUI_UIInputEvent* event, float x, float y, int32_t pointerIndex); 986 987 /** 988 * @brief Sets the action type of a cloned event. 989 * 990 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 991 * @param actionType Action type of the cloned event. 992 * @return Returns the result code. 993 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 994 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 995 * Returns {@link ARKUI_ERROR_CODE_NON_CLONED_POINTER_EVENT} if the input event pointer is not a 996 * cloned event pointer. 997 * @since 15 998 */ 999 int32_t OH_ArkUI_PointerEvent_SetClonedEventActionType(const ArkUI_UIInputEvent* event, int32_t actionType); 1000 1001 /** 1002 * @brief Sets the touch point ID of a cloned pointer event. 1003 * 1004 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 1005 * @param fingerId ID of the touch point that triggers the event. 1006 * @return Returns the result code. 1007 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 1008 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 1009 * Returns {@link ARKUI_ERROR_CODE_NON_CLONED_POINTER_EVENT} if the input event pointer is not a 1010 * cloned event pointer. 1011 * @since 15 1012 */ 1013 int32_t OH_ArkUI_PointerEvent_SetClonedEventChangedFingerId(const ArkUI_UIInputEvent* event, int32_t fingerId); 1014 1015 /** 1016 * @brief Sets the touch point ID of a specific contact point of a cloned event. 1017 * 1018 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 1019 * @param fingerId Touch point ID of the specific contact point. 1020 * @param pointerIndex Index of the target touch point in the multi-touch data list. 1021 * @return Returns the result code. 1022 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 1023 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 1024 * Returns {@link ARKUI_ERROR_CODE_NON_CLONED_POINTER_EVENT} if the input event pointer is not a 1025 * cloned event pointer. 1026 * @since 15 1027 */ 1028 int32_t OH_ArkUI_PointerEvent_SetClonedEventFingerIdByIndex( 1029 const ArkUI_UIInputEvent* event, int32_t fingerId, int32_t pointerIndex); 1030 1031 /** 1032 * @brief Posts a cloned event to a specific node. 1033 * 1034 * @param node Target node. 1035 * @param event Pointer to an <b>ArkUI_UIInputEvent</b> object. 1036 * @return Returns the result code. 1037 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 1038 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 1039 * Returns {@link ARKUI_ERROR_CODE_NON_CLONED_POINTER_EVENT} if the input event pointer is not a 1040 * cloned event pointer. 1041 * Returns {@link ARKUI_ERROR_CODE_POST_CLONED_COMPONENT_STATUS_ABNORMAL} 1042 * if the component status abnormal. 1043 * Returns {@link ARKUI_ERROR_CODE_POST_CLONED_NO_COMPONENT_HIT_TO_RESPOND_TO_THE_EVENT} 1044 * if no component hit to response to the event. 1045 * @since 15 1046 */ 1047 int32_t OH_ArkUI_PointerEvent_PostClonedEvent(ArkUI_NodeHandle node, const ArkUI_UIInputEvent* event); 1048 1049 #ifdef __cplusplus 1050 }; 1051 #endif 1052 1053 #endif // _ARKUI_UI_INPUT_EVENT_H_ 1054 /** @} */ 1055