Add SwitchParent api in actor-devel

[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
old mode 100755 (executable)
new mode 100644 (file)
index 5821af0..19b3bd3
--- 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) 2020 Samsung Electronics Co., Ltd.
+ * Copyright (c) 2021 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.
@@ -120,18 +120,37 @@ enum Type
   CAPTURE_ALL_TOUCH_AFTER_START,
 
   /**
-    * @brief If you set the TOUCH_AREA on an actor, when you touch the actor, the touch area is used rather than the size of the actor
-    * @details Name "touchArea", type Property::Vector2
-    * @note Default is Vector2::ZERO.
-    * @note for example
+    * @brief If you set the TOUCH_AREA_OFFSET on an actor, when you touch the actor, the touch area is expand from the size of actor.
+    * @details Name "touchAreaOffset", type Property::Rect<int> (left, right, bottom, top).
+    * For example
+    * @code{.cpp}
     *  Actor actor = Actor::New();
-    *  actor.SetProperty(Actor::Property::SIZE, Vector2(10.0f, 10.0f));
-    *  actor.SetProperty(DevelActor::Property::TOUCH_AREA, Vector2(200.0f, 200.0f));
+    *  actor.SetProperty(Actor::Property::SIZE, Vector2(20.0f, 20.0f));
+    *  actor.SetProperty(DevelActor::Property::TOUCH_AREA_OFFSET, Rect<int>(-10, 20, 30, -40));
     *  actor.TouchedSignal().Connect(OnTouchCallback);
     *
-    *  If you want to reset the touch area to an area different with the size of the actor, you can set this TOUCH_AREA property.
+    * +---------------------+
+    * |         ^           |
+    * |         |           |
+    * |         | -40       |
+    * |         |           |
+    * |         |           |
+    * |    +----+----+      |
+    * |    |         |      |
+    * | -10|         | 20   |
+    * |<---+         +----->|
+    * |    |         |      |
+    * |    |         |      |
+    * |    +----+----+      |
+    * |         |           |
+    * |         | 30        |
+    * |         |           |
+    * |         v           |
+    * +---------------------+
+    * @endcode
+    * The actual touched size is actor.width + touchAreaOffset.right - touchAreaOffset.left and actor.height + touchAreaOffset.bottom - touchAreaOffset.top
     */
-  TOUCH_AREA,
+  TOUCH_AREA_OFFSET,
 
   /**
    * @brief Determines which blend equation will be used to render renderers of this actor.
@@ -272,6 +291,45 @@ DALI_CORE_API ChildOrderChangedSignalType& ChildOrderChangedSignal(Actor actor);
  */
 DALI_CORE_API Actor::TouchEventSignalType& InterceptTouchedSignal(Actor actor);
 
+/**
+ * @brief This is used when the parent actor wants to listen to gesture events.
+ *
+ * @note example The child is overlapped on the parent.
+ * Currently, if you tap a child, the parent cannot listen to the tap event.
+ * Now, If set to SetNeedGesturePropagation(true), the parent can receive gesture events.
+ * Please call this setting inside a gesture callback, it will be reset after the gesture callback is called.
+ * @code
+ * {
+ *    Actor parent = Actor::New();
+ *    Actor child = Actor::New();
+ *    parent.Add(child);
+ *    parentTapDetector = TapGestureDetector::New();
+ *    childTapDetector = TapGestureDetector::New();
+ *    parentTapDetector.Attach(parent);
+ *    childTapDetector.Attach(child);
+ *    parentTapDetector.DetectedSignal().Connect(this, &OnParentTap);
+ *    childTapDetector.DetectedSignal().Connect(this, &OnChildTap);
+ * }
+ * void OnChildTap(Dali::Actor actor, const Dali::TapGesture& tap)
+ * {
+ *    // If you set SetNeedGesturePropagation to true here, the parent actor can also listen to events
+ *    Dali::DevelActor::SetNeedGesturePropagation(Self(), true);
+ * }
+ * @endcode
+ *
+ */
+DALI_CORE_API void SetNeedGesturePropagation(Actor actor, bool propagation);
+
+/**
+ * Switch parent in the same tree.
+ * This method changes the actor's parent with keeping on scene state.
+ * Both of current parent Actor and new parent Actor must already be added on Scene.
+ * This method don't emit notification about add/remove and on/off scene.
+ * @param [in] actor This actor
+ * @param [in] newParent An actor to be a new parent of this actor.
+ */
+DALI_CORE_API void SwitchParent(Actor actor, Actor newParent);
+
 } // namespace DevelActor
 
 } // namespace Dali