Merge "Add UserInteractionEnabled property on actor for controlling user interaction...

[platform/core/uifw/dali-core.git] / dali / devel-api / actors / actor-devel.h

diff --git a/dali/devel-api/actors/actor-devel.h b/dali/devel-api/actors/actor-devel.h
index 19b3bd3..9d4f0ae 100644 (file)
--- a/dali/devel-api/actors/actor-devel.h
+++ b/dali/devel-api/actors/actor-devel.h
@@ -2,7 +2,7 @@
 #define DALI_ACTOR_DEVEL_H
 
 /*
- * Copyright (c) 2021 Samsung Electronics Co., Ltd.
+ * Copyright (c) 2022 Samsung Electronics Co., Ltd.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -159,7 +159,32 @@ enum Type
    * @note Color of each renderer will be blended with rendering framebuffer.
    * @note To check the blend equation is supported in the system, use Dali::Capabilities::IsBlendEquationSupported
    */
-  BLEND_EQUATION
+  BLEND_EQUATION,
+
+  /**
+   * @brief Sets whether this view can focus by touch. If user sets this to true, the actor will be focused when user touch it.
+   * @code
+   * Actor actor = Actor::New();
+   * actor.SetProperty(Actor::Property::KEYBOARD_FOCUSABLE, true); // whether the view can have focus or not with keyboard navigation.
+   * actor.SetProperty(DevelActor::Property::TOUCH_FOCUSABLE, true); // Whether the user can focus by touch, user can set focus by touching the actor.
+   * @endcode
+   * @details Name "touchFocusable", type Property::BOOLEAN.
+   */
+  TOUCH_FOCUSABLE,
+
+  /**
+   * @brief Whether the children of this actor can be focusable by keyboard navigation. If user sets this to false, the children of this actor will not be focused.
+   * @details Name "keyboardFocusableChildren", type Property::BOOLEAN.
+   * @note Default value is true.
+   */
+  KEYBOARD_FOCUSABLE_CHILDREN,
+
+  /**
+  * @brief The flag whether the actor should be enabled all user interaction including touch, focus and activation. this value have higher priority over the sensitve and focusable in negative action.
+  * @details Name "userInteractionEnabled", type Property::BOOLEAN.
+  * @note Default value is true.
+  */
+  USER_INTERACTION_ENABLED,
 };
 
 } // namespace Property
@@ -330,6 +355,39 @@ DALI_CORE_API void SetNeedGesturePropagation(Actor actor, bool propagation);
  */
 DALI_CORE_API void SwitchParent(Actor actor, Actor newParent);
 
+/**
+ * @brief This signal is emitted when an actor is hit through hit-test.
+ *
+ * A callback of the following type may be connected:
+ * @code
+ *   void MyCallbackName( Actor actor );
+ * @endcode
+ * actor The actor to intercept
+ *
+ * @note This callback is called when the actor is hit.
+ * If true is returned, TouchEvent is called from the this actor.
+ * If false is returned, the hit test starts again from the next lower actor.
+ *
+ * @note example
+ *   Actor topActor = Actor::New();
+ *   Actor bottomActor = Actor::New();
+ *   topActor.TouchedSignal().Connect(&application, topActorFunctor);
+ *   bottomActor.TouchedSignal().Connect(&application, bottomActorFunctor);
+ * The two actors have no relationship.
+ * So when the topActor is touched, the event cannot be propagated to the bottomActor.
+ *
+ * If you connect HitTestResultSignal to topActor.
+ *   Dali::DevelActor::HitTestResultSignal(topActor).Connect(&application, hitTestResultFunctor);
+ *
+ * If the hitTestResult Functor returns false, it passes the hit-test and starts the hit-test again from the next lower actor.
+ * So the bottomActor can be hit and receive touch events.
+ * If hitTestResult returns true, it means that it has been hit. So it receives a TouchEvent from itself.
+ *
+ * @return The signal to connect to
+ * @pre The Actor has been initialized
+ */
+DALI_CORE_API Actor::TouchEventSignalType& HitTestResultSignal(Actor actor);
+
 } // namespace DevelActor
 
 } // namespace Dali