[3.0] Add descriptions and example codes

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

diff --git a/dali/public-api/actors/actor.h b/dali/public-api/actors/actor.h
index 24ce48f..1040218 100644 (file)
--- a/dali/public-api/actors/actor.h
+++ b/dali/public-api/actors/actor.h
@@ -46,6 +46,7 @@ struct Degree;
 class Quaternion;
 class Layer;
 struct KeyEvent;
+class TouchData;
 struct TouchEvent;
 struct HoverEvent;
 struct WheelEvent;
@@ -146,13 +147,7 @@ typedef Rect<float> Padding;      ///< Padding definition @SINCE_1_0.0
  *
  *     Hit Priority of above Actor tree (all overlays): 1 - Lowest. 6 - Highest.
  *     @endcode
- *   - Stencil Actors can be used to influence the result of hits on renderable actors within a layer.
- *     If a Stencil Actor exists on a layer and that Actor is marked visible then a successful
- *     hit on a renderable actor can only take place in the area that the stencil Actor marks as visible.
- *     The hit can be in any Stencil Actor in that layer, but must be in the region of one of them.
- *     Stencil Actor inheritance behaves as with rendering in that any child of a Stencil Actor will
- *     also be considered a Stencil Actor.
- *     Non-renderable actors can be hit regardless of whether a stencil actor is hit or not.
+ *     For more information, see SetDrawMode().
  *
  * <i>Touch or hover Event Delivery:</i>
  *
@@ -312,12 +307,13 @@ public:
 
   // Typedefs
 
-  typedef Signal< bool (Actor, const TouchEvent&)> TouchSignalType;                 ///< Touch signal type @SINCE_1_0.0
-  typedef Signal< bool (Actor, const HoverEvent&)> HoverSignalType;                 ///< Hover signal type @SINCE_1_0.0
-  typedef Signal< bool (Actor, const WheelEvent&) > WheelEventSignalType;           ///< Wheel signal type @SINCE_1_0.0
-  typedef Signal< void (Actor) > OnStageSignalType;  ///< Stage connection signal type @SINCE_1_0.0
-  typedef Signal< void (Actor) > OffStageSignalType; ///< Stage disconnection signal type @SINCE_1_0.0
-  typedef Signal< void (Actor) > OnRelayoutSignalType; ///< Called when the actor is relaid out @SINCE_1_0.0
+  typedef Signal< bool (Actor, const TouchEvent&) > TouchSignalType;        ///< @DEPRECATED_1_1.37 @brief Touch signal type @SINCE_1_0.0
+  typedef Signal< bool (Actor, const TouchData&) >  TouchDataSignalType;    ///< Touch signal type @SINCE_1_1.37
+  typedef Signal< bool (Actor, const HoverEvent&) > HoverSignalType;        ///< Hover signal type @SINCE_1_0.0
+  typedef Signal< bool (Actor, const WheelEvent&) > WheelEventSignalType;   ///< Wheel signal type @SINCE_1_0.0
+  typedef Signal< void (Actor) > OnStageSignalType;                         ///< Stage connection signal type @SINCE_1_0.0
+  typedef Signal< void (Actor) > OffStageSignalType;                        ///< Stage disconnection signal type @SINCE_1_0.0
+  typedef Signal< void (Actor) > OnRelayoutSignalType;                      ///< Called when the actor is relaid out @SINCE_1_0.0
 
   // Creation
 
@@ -1142,7 +1138,7 @@ public:
   // Input Handling
 
   /**
-   * @brief Sets whether an actor should emit touch or hover signals; see SignalTouch() and SignalHover().
+   * @brief Sets whether an actor should emit touch or hover signals.
    *
    * An actor is sensitive by default, which means that as soon as an application connects to the SignalTouch(),
    * the touch event signal will be emitted, and as soon as an application connects to the SignalHover(), the
@@ -1438,6 +1434,7 @@ public: // Renderer
 public: // Signals
 
   /**
+   * @DEPRECATED_1_1.37 Use TouchSignal() instead.
    * @brief This signal is emitted when touch input is received.
    *
    * A callback of the following type may be connected:
@@ -1453,6 +1450,21 @@ public: // Signals
   TouchSignalType& TouchedSignal();
 
   /**
+   * @brief This signal is emitted when touch input is received.
+   *
+   * A callback of the following type may be connected:
+   * @code
+   *   bool YourCallbackName( Actor actor, TouchData& touch );
+   * @endcode
+   * The return value of True, indicates that the touch event has been consumed.
+   * Otherwise the signal will be emitted on the next sensitive parent of the actor.
+   * @SINCE_1_1.37
+   * @return The signal to connect to.
+   * @pre The Actor has been initialized.
+   */
+  TouchDataSignalType& TouchSignal();
+
+  /**
    * @brief This signal is emitted when hover input is received.
    *
    * A callback of the following type may be connected:
@@ -1541,6 +1553,7 @@ public: // Signals
 public: // Not intended for application developers
 
   /**
+   * @internal
    * @brief This constructor is used by Actor::New() methods.
    *
    * @SINCE_1_0.0
@@ -1550,6 +1563,7 @@ public: // Not intended for application developers
 };
 
 /**
+ * @internal
  * @brief Helper for discarding an actor handle.
  *
  * If the handle is empty, this method does nothing.  Otherwise