1# Interaction Mechanism Overview 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @jiangtao92--> 5<!--Designer: @piggyguy--> 6<!--Tester: @songyanhong--> 7<!--Adviser: @HelloCrease--> 8 9The interaction framework processes pointer-based inputs through coordinate-based hit testing to determine event and gesture targets. This mechanism forms a response chain where the system delivers events to corresponding UI components based on the coordinates, types, and other information of the events, combined with the UI layout. Multiple events can combine to trigger gestures or features, for example, long press, click, and drag. 10 11## Event Interaction Pipeline 12 13The event interaction pipeline describes the end-to-end process where ArkUI receives touch-type or mouse-type input events from upstream systems, collects event response chains based on developer-configured parameters, and dispatches them to components to trigger callbacks. This pipeline consists of three key phases: 14 151. Event Generation 16 17 Hardware input devices report events to target ArkUI instances through drivers and multi-mode modules. The rendering pipeline of ArkUI performs unified event processing. 18 192. Event Response Chain Formation and Event Dispatch 20 21 The event response chain forms the core of the event interaction pipeline. After receiving an event, the pipeline performs hit testing to construct an event response chain, which drives decision-making for event dispatch and gesture recognition. 22 23 (1) Hit Testing 24 25 After receiving an initial touch event, the pipeline performs spatial hit testing using event coordinates and component boundaries and constructs an event response chain. You can configure attributes to affect the formation of the event response chain. 26 27 (2) Dispatch to the Touch Event Response Chain 28 29 Through the constructed touch response chain, the system delivers the touch event to target components. 30 31 (3) Dispatch to the Gesture Response Chain and Gesture Recognition 32 33 Components with registered gestures form a gesture response chain. The system combines events to detect gestures, resolves gesture conflicts through competition logic, and triggers the callback of the winning gesture. 34 35 (4) Event Interception 36 37 You can intercept events at two levels: 38 39 - Pre-chain: Configure hit test properties to affect the formation of the event response chain. 40 41 - Post-chain: 42 43 During event dispatch to the touch event response chain, you can block touch event propagation using touch interceptors. 44 45 During dispatch to the gesture response chain, you can suppress gesture recognition using gesture interceptors. 46 473. Callback Execution 48 49 During response chain formation, registered callbacks are collected. Then, after response chain formation and event dispatch, callbacks are executed for qualifying events and gestures. 50 51## Event Response Chain Mechanism 52 53ArkUI constructs event response chains through hit testing using a reverse post-order traversal (right-subtree-first) of the component tree. 54 55Consider the following component tree, where all components have **hitTestBehavior** set to **Default**. If the user taps component 5, the final response chain collected will be [5 -> 3 -> 1]. 56 57This is because component 3 has **hitTestBehavior** set to **Default**, which blocks the collection from its sibling nodes after receiving the event, thereby excluding the left subtree of component 1 (that is, component 2) from the response chain. 58 59  60 61 62 63## Hit Testing 64 65Touch testing, also known as hit testing, is the process by which the system determines which components' events or gestures can participate in responding to a user interaction before the interaction begins. 66 67### Implementation Principles 68 69For dispatching pointer events, the system does not recursively traverse all component nodes starting from the root node. Instead, during the initial event occurrence, it identifies the range of components capable of responding to the interaction—that is, detecting which component the user has clicked. Components not clicked will not respond to this interaction. This process is called hit testing, or touch testing. The system determines whether a component is clicked by checking whether its response region contains the event coordinates. 70 71 72 73The basic process of hit testing is as follows: When the user presses down, the system traverses the component tree from top to bottom and from right to left, collects gestures and events bound to each component, and then bubbles up this information level by level to parent components for consolidation, constructing a complete event response chain. 74 75Assume that the user presses at point T (Touch Down). Components A, B, and D are identified as hit, and the chain formed by these components is called the response chain for this interaction. Base events are propagated along this chain: They are first delivered to the leaf node, and then passed to parent nodes, bubbling upward. This process is known as event bubbling. 76 77Below shows the hit testing process. 78 79 80 81As shown in the figure, when the initial event is dispatched to a component, the component collects gestures and events bound to it, and then passes the collection result to the parent component until the root node is reached. If a component is transparent, has been removed from the component tree, or the event coordinates are outside the component's response region, the collection process is not triggered, and the parent component receives an empty response. Otherwise, all components will collect gestures and events and send the collection result to the parent component. 82 83### Hit Test Intervention 84 85Applications can intervene in hit test results through the following methods to influence the final response scope, thereby controlling which components are included in the event response chain. 86 87| Intervention Mode | Description | API | Remarks | 88| -------------- | ------------------------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 89| Response region setting | Sets the region where a component can respond to user interactions.| [responseRegion](../reference/apis-arkui/arkui-ts/ts-universal-attributes-touch-target.md#responseregion) | 1. The response region is used to determine whether the user's touch falls within its range; only touches within the range will be collected.<br>2. The response region also affects gesture recognition, such as clicks, which are triggered only when the touch is released within the response region range.<br> | 90| Hit test control | Intervenes in the collection results of the component itself and other components. | [hitTestBehavior](../reference/apis-arkui/arkui-ts/ts-universal-attributes-hit-test-behavior.md#hittestbehavior) | **hitTestBehavior** works similarly to **onTouchIntercept**, but it is statically configured. | 91| Custom event interception| Intervenes in the collection results of the component itself and other components. | [onTouchIntercept](../reference/apis-arkui/arkui-ts/ts-universal-attributes-on-touch-intercept.md#ontouchintercept) | This callback is triggered when the user presses down and the system begins collecting all components that need to participate in event processing at the current position. Applications can return a **HitTestMode** value through this callback to influence the system's behavior in collecting child or sibling nodes. This enables dynamic control over interaction responses, such as allowing certain components to participate in interactions only under specific service conditions.<br>**onTouchIntercept** works similarly to **hitTestBehavior**, but it is a dynamic callback.| 92 93 941. Response Region Setting 95 96 By default, a component's response region matches its own position and size, ensuring maximum consistency between user actions and visual feedback. In rare cases, applications may need to adjust the response region size to limit or expand the component's response range. This is achieved through the **responseRegion** API. 97 98 The response region affects the dispatch of pointer events and can be specified relative to the component's own area. One or more areas can be defined to partition the component's response region into multiple sections. 99 100 >**NOTE** 101 > 102 > **x** and **y** can be set to a positive or negative percentage value. Setting **x** to **'100%'** shifts the response region rightward by the component's width, while setting **x** to **'-100%'** shifts the response region leftward by the component's width. Setting **y** to **'100%'** shifts the response region downward by the component's height, while setting **y** to **'-100%'** shifts the response region upward by the component's height. 103 > 104 > **width** and **height** can only be set to positive percentage values. When **width** is set to **'100%'**, the width of the response region is equal to that of the component. For example, if the width of a component is 100 vp, **'100%'** indicates that the width of the response region is also 100 vp. when **height** is set to **'100%'**, the height of the response region is equal to that of the component. 105 > 106 > Percentage values are calculated relative to the component's own width and height. 107 108 The following is an example of binding multiple response regions: 109 110 ```ts 111 Button("Button") 112 .responseRegion([ 113 { x: 0, y: 0, width: '30%', height: '100%' }, // First response region: left 1/3 of the button 114 { x: '70%', y: 0, width: '30%', height: '100%' }, // Second response region: right 1/3 of the button 115 ]) 116 ``` 117 118 The above code divides the button into three parts, with the middle 40% area non-responsive to clicks, while the remaining areas on both sides remain responsive. 119 120  121 1222. Hit Test Control 123 124 When [hit test control](../reference/apis-arkui/arkui-ts/ts-universal-attributes-hit-test-behavior.md) is bound to a component, it may affect the hit testing of sibling nodes and parent and child nodes. The impact of a child component on its parent component's hit testing depends on the status of the last child component that is not blocked in hit testing. 125 126 You can configure hit test control to block the hit test of the component itself or other components. 127 128 - **HitTestMode.Default**: This mode is used by default when the **hitTestBehavior** attribute is not specified. In this mode, if the component itself is hit, it will block the hit testing of sibling components, but will not block the hit testing of child components. 129 130  131 132 - **HitTestMode.None**: In this mode, the component neither receives events nor interferes with the hit testing of its sibling components or child components. 133 134  135 136 - **HitTestMode.Block**: This mode blocks the hit testing of child components. If the component itself is hit during a hit test, it will also block the hit testing of sibling and parent components. 137 138  139 140 - **HitTestMode.Transparent**: This mode allows the component to participate in hit testing itself, without blocking the hit testing of sibling or parent components. 141 142  143 1443. Custom Event Interception 145 146 When a user performs a press action, the callback for [custom event interception](../reference/apis-arkui/arkui-ts/ts-universal-attributes-on-touch-intercept.md) bound to the component is triggered. You can dynamically adjust the **hitTestBehavior** attribute of the component based on the application status to affect the hit test process. 147 148## Enable/Disable Control 149 150[Disabled](../reference/apis-arkui/arkui-ts/ts-universal-attributes-enable.md) components, including their children, do not initiate the hit test process; instead, they pass the events back to the parent to continue the hit test. 151 152## Security Components 153 154ArkUI provides security components, including [PasteButton](../security/AccessToken/pastebutton.md) and [SaveButton](../security/AccessToken/savebutton.md). 155 156If a component has a higher [z-order](../reference/apis-arkui/arkui-ts/ts-universal-attributes-z-order.md) than a security component and covers it, the security component's touch events are sent directly to the parent node for further hit testing. 157 158## Event Bubbling 159 160Basic events propagate through the response chain following a bubbling mechanism, where the innermost component processes the event first, and then the event propagates up to parent components layer by layer. Any component can terminate the further transmission of the event, that is, stop the bubbling. However, it should be noted that stopping the bubbling does not affect gesture recognition in parent components. 161 162**stopPropagation** can terminate event bubbling. As shown in the figure below, when a touch event reaches component C and **stopPropagation()** is called, components B and root will no longer receive this event. However, gesture objects attached to component B can still process the touch event. 163 164 165 166> **NOTE** 167> 168> When using **stopPropagation** to intervene in event bubbling, maintain consistent handling rules for all event types (including **Down**, **Move**, and **Up**) to avoid situations where upper-level nodes only receive partial types of events, resulting in incomplete event cycles. For example, if node B only receives the **Down** event but not the **Up** event, it will affect the integrity of events on node B. For press-type interactions, always ensure the integrity of events. 169 170## Cancel Event 171 172When processing basic events, you will find that there are various types of cancel events, such as **TouchType.Cancel** and **MouseAction.CANCEL**. These events are system generated in specific scenarios. For example, in a drag operation, when the user drags an object that supports dragging (using **onDragStart**) with a finger or mouse device, the application will normally receive touch or mouse events before **onDragStart** is triggered. Once the drag action starts, the system will send a cancel event to inform the application that the normal basic events have ended. 173 174The meaning of Cancel is the same as that of Up, both indicating the end of event processing. If you are handling scenarios involving **Up** and **Release** events, you should also handle cancel events simultaneously. 175
