Dali 3D User Interface Engine
Classes | Typedefs | Enumerations | Functions
Dali::HitTestAlgorithm Namespace Reference

This namespace is provided for application developers to do hit-test for the actors. More...

Classes

struct  Results
 Results structure containing the hit actor and where it was hit. More...
 

Typedefs

typedef bool(* HitTestFunction )(Actor actor, TraverseType type)
 Definition of a hit-test function to use in HitTest() method to check if the actor is hittable (e.g. More...
 

Enumerations

enum  TraverseType { CHECK_ACTOR, DESCEND_ACTOR_TREE }
 How the actor tree should be traversed. More...
 

Functions

bool HitTest (Stage stage, const Vector2 &screenCoordinates, Results &results, HitTestFunction func)
 Given screen coordinates, this method returns the hit actor & the local coordinates relative to the top-left (0.0f, 0.0f, 0.5f) of the actor. More...
 
bool HitTest (RenderTask &renderTask, const Vector2 &screenCoordinates, Results &results, HitTestFunction func)
 Hit test specific to a given RenderTask. More...
 

Detailed Description

This namespace is provided for application developers to do hit-test for the actors.

Hit Test Algorithm:

Hit testing is dependent on the camera used, which is specific to each RenderTask. For each RenderTask, hit testing starts from the top-most layer and we go through all the layers until we have a hit or there are none left. Before we perform a hit test within a layer, we check if all the layer's parents meet the conditions defined by the function ((e.g. whether it is visible)). If they are not, we skip hit testing the actors in that layer altogether. Otherwise, we walk through the actor tree within a layer to check whether the actors within the actor tree should be hit-tested.

The following pseudocode gives an example of what the function can typically check, which should normally be provided by the application code:

HIT-TEST-FUNCTION( ACTOR, TRAVERSE-TYPE )
{
if( TRAVERSE-TYPE == CHECK_ACTOR ) // Check whether current actor should be hit-tested
{
if( ACTOR-IS-VISIBLE &&
ACTOR-WORLD-COLOR-IS-NOT-TRANSPARENT )
{
HITTABLE = TRUE
}
}
else if( TRAVERSE-TYPE == DESCEND_ACTOR_TREE )
{
if( ACTOR-IS-VISIBLE )
{
HITTABLE = TRUE
}
}
}

The following pseudocode explains how the algorithm performs the hit-test with the above functor:

HIT-TEST-WITHIN-LAYER( ACTOR )
{
// Depth-first traversal within current layer, visiting parent first
// Check whether current actor should be hit-tested
IF ( HIT-TEST-FUNCTION( ACTOR, CHECK_ACTOR ) &&
ACTOR-HAS-NON-ZERO-SIZE )
{
// Hit-test current actor
IF ( ACTOR-HIT )
{
IF ( DISTANCE-TO-ACTOR < DISTANCE-TO-LAST-HIT-ACTOR )
{
// The current actor is the closest actor that was underneath the touch
LAST-HIT-ACTOR = CURRENT-ACTOR
}
}
}
// Keep checking children, in case we hit something closer
FOR-EACH CHILD (in order)
{
IF ( HIT-TEST-FUNCTION( ACTOR, DESCEND_ACTOR_TREE ) &&
ACTOR-IS-NOT-A-LAYER )
{
// Continue traversal for this child's sub-tree
HIT-TEST-WITHIN-LAYER ( CHILD )
}
// else we skip the sub-tree with from this child
}
}

Typedef Documentation

typedef bool(* Dali::HitTestAlgorithm::HitTestFunction)(Actor actor, TraverseType type)

Definition of a hit-test function to use in HitTest() method to check if the actor is hittable (e.g.

touchable or focusable).

Returns
true, if the actor is hittable, false otherwise.

Definition at line 128 of file hit-test-algorithm.h.

Enumeration Type Documentation

How the actor tree should be traversed.

Enumerator
CHECK_ACTOR 

Hit test the given actor.

DESCEND_ACTOR_TREE 

Check whether the actor tree should be descended to hit-test its children.

Definition at line 108 of file hit-test-algorithm.h.

Function Documentation

DALI_IMPORT_API bool Dali::HitTestAlgorithm::HitTest ( Stage  stage,
const Vector2 &  screenCoordinates,
Results &  results,
HitTestFunction  func 
)

Given screen coordinates, this method returns the hit actor & the local coordinates relative to the top-left (0.0f, 0.0f, 0.5f) of the actor.

An actor is only hittable if the actor meets all the conditions defined by the given function (see HitTestAlgorithm).

Typically, if an actor has a zero size or its world color is fully transparent, it should not be hittable; and if an actor's visibility flag is unset, its children should not be hittable either.

Parameters
[in]stageThe stage.
[in]screenCoordinatesThe screen coordinates.
[out]resultsThe results of the hit-test, only modified if something is hit
[in]funcThe function to use in the hit-test algorithm.
Returns
true if something was hit

Definition at line 32 of file hit-test-algorithm.cpp.

References Dali::GetImplementation(), and Dali::Internal::HitTestAlgorithm::HitTest().

Referenced by Dali::Toolkit::Internal::AccessibilityManager::AccessibilityActionRead(), Dali::Toolkit::Internal::AccessibilityManager::HandlePanGesture(), UtcDaliHitTestAlgorithmOrtho01(), UtcDaliHitTestAlgorithmOrtho02(), UtcDaliHitTestAlgorithmOverlay(), UtcDaliHitTestAlgorithmStencil(), UtcDaliHitTestAlgorithmWithFunctor(), UtcDaliHitTestAlgorithmWithFunctorOnRenderTask(), and UtcDaliRenderTaskSetScreenToFrameBufferMappingActor().

Here is the call graph for this function:

Here is the caller graph for this function:

DALI_IMPORT_API bool Dali::HitTestAlgorithm::HitTest ( RenderTask &  renderTask,
const Vector2 &  screenCoordinates,
Results &  results,
HitTestFunction  func 
)

Hit test specific to a given RenderTask.

Parameters
[in]renderTaskThe render task for hit test
[in]screenCoordinatesThe screen coordinates.
[out]resultsThe results of the hit-test, only modified if something is hit
[in]funcThe function to use in the hit-test algorithm.
Returns
true if something was hit

Definition at line 37 of file hit-test-algorithm.cpp.

References Dali::Stage::GetCurrent(), Dali::GetImplementation(), and Dali::Internal::HitTestAlgorithm::HitTest().

Here is the call graph for this function:

Dali Docs Home
Read more about Dali