docs/content/shared-javascript-and-cpp-documentation/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::TouchedSignal() and Dali::Actor::HoveredSignal() for more details.
  10
  11 For JavaScript use actor.connect( "touched", myCallback ) and actor.connect("hovered", myCallback );
  12
  13 ### Hit Testing Rules Summary:
  14
  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()
  21
  22 ### Hit Test Algorithm:
  23
  24  - RenderTasks
  25    - Hit testing is dependent on the camera used, which is specific to each RenderTask.
  26
  27  - Layers
  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
  31      and sensitive.
  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.
  34
  35  - Actors
  36    - The final part of hit testing is performed by walking through the actor tree within a layer.
  37    - The following pseudocode shows the algorithm used:
  38
  39
  40 ~~~
  41  HIT-TEST-WITHIN-LAYER( ACTOR )
  42  {
  43    // Only hit-test the actor and its children if it is sensitive and visible
  44    IF ( ACTOR-IS-SENSITIVE &&
  45            ACTOR-IS-VISIBLE )
  46       {
  47          // Depth-first traversal within current layer, visiting parent first
  48
  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 )
  53          {
  54            // Hit-test current actor
  55            IF ( ACTOR-HIT )
  56            {
  57                IF ( ACTOR-IS-OVERLAY || ( DISTANCE-TO-ACTOR < DISTANCE-TO-LAST-HIT-ACTOR ) )
  58                {
  59                  // The current actor is the closest actor that was underneath the touch
  60                  LAST-HIT-ACTOR = CURRENT-ACTOR
  61                }
  62            }
  63          }
  64
  65        // Keep checking children, in case we hit something closer
  66         FOR-EACH CHILD (in order)
  67        {
  68          IF ( CHILD-IS-NOT-A-LAYER )
  69          {
  70              // Continue traversal for this child's sub-tree
  71              HIT-TEST-WITHIN-LAYER ( CHILD )
  72          }
  73           // else we skip hit-testing the child's sub-tree altogether
  74        }
  75      }
  76    }
  77 ~~~
  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):
  81
  82 ~~~
  83       1
  84      / \
  85     /   \
  86    2     5
  87   / \     \
  88  /   \     \
  89 3     4     6
  90
  91 Hit Priority of above Actor tree (all overlays): 1 - Lowest. 6 - Highest.
  92 ~~~
  93
  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.
 100
 101  <i>Touch Event Delivery:</i>
 102
 103  - Delivery
 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
 108      other touch points.
 109    - The local coordinates are from the top-left (0.0f, 0.0f, 0.5f) of the hit actor.
 110    - The following pseudocode shows the delivery mechanism:
 111
 112 ~~~
 113   EMIT-TOUCH-SIGNAL( ACTOR )
 114   {
 115     IF ( TOUCH-SIGNAL-NOT-EMPTY )
 116     {
 117       // Only do the emission if touch signal of actor has connections.
 118         CONSUMED = TOUCHED-SIGNAL( TOUCH-EVENT )
 119     }
 120
 121     IF ( NOT-CONSUMED )
 122     {
 123         // If event is not consumed then deliver it to the parent unless we reach the root actor
 124         IF ( ACTOR-PARENT )
 125         {
 126           EMIT-TOUCH-SIGNAL( ACTOR-PARENT )
 127         }
 128     }
 129   }
 130 ~~~
 131  - Leave State
 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.
 136
 137
 138  - Interrupted State
 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.
 145
 146 @class MultiTouch
 147 *
 148 */