docs/content/programming-guide/multi-touch-guide.md

   1 <!--
   2 /**-->
   3
   4 Multi-Touch Events
   5 ==================
   6
   7 Touch events are received via signals.
   8
   9 For C++ API see Dali::Actor::TouchSignal() and Dali::Actor::HoveredSignal() for more details.
  10
  11 ### Hit Testing Rules Summary:
  12
  13  - An actor is only hittable if the actor's touch signal has a connection.
  14  - An actor is only hittable when it is between the camera's near and far planes.
  15  - If an actor is made insensitive, then the actor and its children are not hittable; see Dali::Actor:.Property::SENSITIVE
  16  - If an actor's visibility flag is unset, then none of its children are hittable either; see Dali::Actor::Property::VISIBLE
  17  - To be hittable, an actor must have a non-zero size.
  18  - If an actor's world color is fully transparent, then it is not hittable; see Dali::Actor::Property::WORLD_COLOR
  19
  20 ### Hit Test Algorithm:
  21
  22  - RenderTasks
  23    - Hit testing is dependent on the camera used, which is specific to each RenderTask.
  24
  25  - Layers
  26    - For each RenderTask, hit testing starts from the top-most layer and we go through all the
  27      layers until we have a hit or there are none left.
  28    - Before we perform a hit test within a layer, we check if all the layer's parents are visible
  29      and sensitive.
  30    - If they are not, we skip hit testing the actors in that layer altogether.
  31    - If a layer is set to consume all touch, then we do not check any layers behind this layer.
  32
  33  - Actors
  34    - The final part of hit testing is performed by walking through the actor tree within a layer.
  35    - The following pseudo-code shows the algorithm used:
  36
  37
  38 ~~~
  39  HIT-TEST-WITHIN-LAYER( ACTOR )
  40  {
  41    // Only hit-test the actor and its children if it is sensitive and visible
  42    IF ( ACTOR-IS-SENSITIVE &&
  43            ACTOR-IS-VISIBLE )
  44       {
  45          // Depth-first traversal within current layer, visiting parent first
  46
  47          // Check whether current actor should be hit-tested
  48          IF ( TOUCH-SIGNAL-NOT-EMPTY &&
  49              ACTOR-HAS-NON-ZERO-SIZE &&
  50              ACTOR-WORLD-COLOR-IS-NOT-TRANSPARENT )
  51          {
  52            // Hit-test current actor
  53            IF ( ACTOR-HIT )
  54            {
  55                IF ( ACTOR-IS-OVERLAY || ( DISTANCE-TO-ACTOR < DISTANCE-TO-LAST-HIT-ACTOR ) )
  56                {
  57                  // The current actor is the closest actor that was underneath the touch
  58                  LAST-HIT-ACTOR = CURRENT-ACTOR
  59                }
  60            }
  61          }
  62
  63        // Keep checking children, in case we hit something closer
  64         FOR-EACH CHILD (in order)
  65        {
  66          IF ( CHILD-IS-NOT-A-LAYER )
  67          {
  68              // Continue traversal for this child's sub-tree
  69              HIT-TEST-WITHIN-LAYER ( CHILD )
  70          }
  71           // else we skip hit-testing the child's sub-tree altogether
  72        }
  73      }
  74    }
  75 ~~~
  76  - Overlays always take priority (i.e. they're considered closer) regardless of distance.
  77      The overlay children take priority over their parents, and overlay siblings take priority
  78      over their previous siblings (i.e. reverse of rendering order):
  79
  80 ~~~
  81       1
  82      / \
  83     /   \
  84    2     5
  85   / \     \
  86  /   \     \
  87 3     4     6
  88
  89 Hit Priority of above Actor tree (all overlays): 1 - Lowest. 6 - Highest.
  90 ~~~
  91
  92  - Stencil Actors can be used to influence the result of hits within a layer.
  93      If a Stencil Actor exists on a layer and that Actor is marked visible then a successful
  94      hit can only take place in the area that the stencil Actor marks as visible.
  95      The hit can be in any Stencil Actor in that layer, but must be in the region of one of them.
  96      Stencil Actor inheritance behaves as with rendering in that any child of a Stencil Actor will
  97      also be considered a Stencil Actor.
  98
  99  <i>Touch Event Delivery:</i>
 100
 101  - Delivery
 102    - The hit actor's touch signal is emitted first; if it is not consumed by any of the listeners,
 103      the parent's touch signal is emitted, and so on.
 104    - If there are several touch points, then the delivery is only to the first touch point's hit
 105      actor (and its parents).  There will be NO touch signal delivery for the hit actors of the
 106      other touch points.
 107    - The local coordinates are from the top-left (0.0f, 0.0f, 0.5f) of the hit actor.
 108    - The following pseudo-code shows the delivery mechanism:
 109
 110 ~~~
 111   EMIT-TOUCH-SIGNAL( ACTOR )
 112   {
 113     IF ( TOUCH-SIGNAL-NOT-EMPTY )
 114     {
 115       // Only do the emission if touch signal of actor has connections.
 116         CONSUMED = TOUCH-SIGNAL( TOUCH-EVENT )
 117     }
 118
 119     IF ( NOT-CONSUMED )
 120     {
 121         // If event is not consumed then deliver it to the parent unless we reach the root actor
 122         IF ( ACTOR-PARENT )
 123         {
 124           EMIT-TOUCH-SIGNAL( ACTOR-PARENT )
 125         }
 126     }
 127   }
 128 ~~~
 129  - Leave State
 130    - A "Leave" state is set when the first point exits the bounds of the previous first point's
 131      hit actor (primary hit actor).
 132    - When this happens, the last primary hit actor's touch signal is emitted with a "Leave" state
 133      (only if it requires leave signals); see the actor property leaveRequired.
 134
 135
 136  - Interrupted State
 137    - If a system event occurs which interrupts the touch processing, then the last primary hit
 138      actor's touch signals are emitted with an "Interrupted" state.
 139    - If the last primary hit actor, or one of its parents, is no longer touchable, then its
 140      touch signals are also emitted with an "Interrupted" state.
 141    - If the consumed actor on touch-down is not the same as the consumed actor on touch-up, then
 142      touch signals are also emitted from the touch-down actor with an "Interrupted" state.
 143
 144
 145 */