7 Touch events are received via signals.
9 For C++ API see Dali::Actor::TouchSignal() and Dali::Actor::HoveredSignal() for more details.
11 For JavaScript use actor.connect( "touch", myCallback ) and actor.connect("hovered", myCallback );
13 ### Hit Testing Rules Summary:
15 - An actor is only hittable if the actor's touch signal has a connection.
16 - An actor is only hittable when it is between the camera's near and far planes.
17 - If an actor is made insensitive, then the actor and its children are not hittable; see Dali::Actor::IsSensitive()
18 - If an actor's visibility flag is unset, then none of its children are hittable either; see Dali::Actor::IsVisible()
19 - To be hittable, an actor must have a non-zero size.
20 - If an actor's world color is fully transparent, then it is not hittable; see GetCurrentWorldColor()
22 ### Hit Test Algorithm:
25 - Hit testing is dependent on the camera used, which is specific to each RenderTask.
28 - For each RenderTask, hit testing starts from the top-most layer and we go through all the
29 layers until we have a hit or there are none left.
30 - Before we perform a hit test within a layer, we check if all the layer's parents are visible
32 - If they are not, we skip hit testing the actors in that layer altogether.
33 - If a layer is set to consume all touch, then we do not check any layers behind this layer.
36 - The final part of hit testing is performed by walking through the actor tree within a layer.
37 - The following pseudo-code shows the algorithm used:
41 HIT-TEST-WITHIN-LAYER( ACTOR )
43 // Only hit-test the actor and its children if it is sensitive and visible
44 IF ( ACTOR-IS-SENSITIVE &&
47 // Depth-first traversal within current layer, visiting parent first
49 // Check whether current actor should be hit-tested
50 IF ( TOUCH-SIGNAL-NOT-EMPTY &&
51 ACTOR-HAS-NON-ZERO-SIZE &&
52 ACTOR-WORLD-COLOR-IS-NOT-TRANSPARENT )
54 // Hit-test current actor
57 IF ( ACTOR-IS-OVERLAY || ( DISTANCE-TO-ACTOR < DISTANCE-TO-LAST-HIT-ACTOR ) )
59 // The current actor is the closest actor that was underneath the touch
60 LAST-HIT-ACTOR = CURRENT-ACTOR
65 // Keep checking children, in case we hit something closer
66 FOR-EACH CHILD (in order)
68 IF ( CHILD-IS-NOT-A-LAYER )
70 // Continue traversal for this child's sub-tree
71 HIT-TEST-WITHIN-LAYER ( CHILD )
73 // else we skip hit-testing the child's sub-tree altogether
78 - Overlays always take priority (i.e. they're considered closer) regardless of distance.
79 The overlay children take priority over their parents, and overlay siblings take priority
80 over their previous siblings (i.e. reverse of rendering order):
91 Hit Priority of above Actor tree (all overlays): 1 - Lowest. 6 - Highest.
94 - Stencil Actors can be used to influence the result of hits within a layer.
95 If a Stencil Actor exists on a layer and that Actor is marked visible then a successful
96 hit can only take place in the area that the stencil Actor marks as visible.
97 The hit can be in any Stencil Actor in that layer, but must be in the region of one of them.
98 Stencil Actor inheritance behaves as with rendering in that any child of a Stencil Actor will
99 also be considered a Stencil Actor.
101 <i>Touch Event Delivery:</i>
104 - The hit actor's touch signal is emitted first; if it is not consumed by any of the listeners,
105 the parent's touch signal is emitted, and so on.
106 - If there are several touch points, then the delivery is only to the first touch point's hit
107 actor (and its parents). There will be NO touch signal delivery for the hit actors of the
109 - The local coordinates are from the top-left (0.0f, 0.0f, 0.5f) of the hit actor.
110 - The following pseudo-code shows the delivery mechanism:
113 EMIT-TOUCH-SIGNAL( ACTOR )
115 IF ( TOUCH-SIGNAL-NOT-EMPTY )
117 // Only do the emission if touch signal of actor has connections.
118 CONSUMED = TOUCH-SIGNAL( TOUCH-DATA )
123 // If event is not consumed then deliver it to the parent unless we reach the root actor
126 EMIT-TOUCH-SIGNAL( ACTOR-PARENT )
132 - A "Leave" state is set when the first point exits the bounds of the previous first point's
133 hit actor (primary hit actor).
134 - When this happens, the last primary hit actor's touch signal is emitted with a "Leave" state
135 (only if it requires leave signals); see the actor property leaveRequired.
139 - If a system event occurs which interrupts the touch processing, then the last primary hit
140 actor's touch signals are emitted with an "Interrupted" state.
141 - If the last primary hit actor, or one of its parents, is no longer touchable, then its
142 touch signals are also emitted with an "Interrupted" state.
143 - If the consumed actor on touch-down is not the same as the consumed actor on touch-up, then
144 touch signals are also emitted from the touch-down actor with an "Interrupted" state.