dali/devel-api/actors/actor-devel.h

   1 #ifndef DALI_ACTOR_DEVEL_H
   2 #define DALI_ACTOR_DEVEL_H
   3
   4 /*
   5  * Copyright (c) 2022 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // INTERNAL INCLUDES
  22 #include <dali/public-api/actors/actor.h>
  23 #include <dali/public-api/math/rect.h>
  24
  25 namespace Dali
  26 {
  27 namespace DevelActor
  28 {
  29 namespace Property
  30 {
  31 enum Type
  32 {
  33   PARENT_ORIGIN              = Dali::Actor::Property::PARENT_ORIGIN,
  34   PARENT_ORIGIN_X            = Dali::Actor::Property::PARENT_ORIGIN_X,
  35   PARENT_ORIGIN_Y            = Dali::Actor::Property::PARENT_ORIGIN_Y,
  36   PARENT_ORIGIN_Z            = Dali::Actor::Property::PARENT_ORIGIN_Z,
  37   ANCHOR_POINT               = Dali::Actor::Property::ANCHOR_POINT,
  38   ANCHOR_POINT_X             = Dali::Actor::Property::ANCHOR_POINT_X,
  39   ANCHOR_POINT_Y             = Dali::Actor::Property::ANCHOR_POINT_Y,
  40   ANCHOR_POINT_Z             = Dali::Actor::Property::ANCHOR_POINT_Z,
  41   SIZE                       = Dali::Actor::Property::SIZE,
  42   SIZE_WIDTH                 = Dali::Actor::Property::SIZE_WIDTH,
  43   SIZE_HEIGHT                = Dali::Actor::Property::SIZE_HEIGHT,
  44   SIZE_DEPTH                 = Dali::Actor::Property::SIZE_DEPTH,
  45   POSITION                   = Dali::Actor::Property::POSITION,
  46   POSITION_X                 = Dali::Actor::Property::POSITION_X,
  47   POSITION_Y                 = Dali::Actor::Property::POSITION_Y,
  48   POSITION_Z                 = Dali::Actor::Property::POSITION_Z,
  49   WORLD_POSITION             = Dali::Actor::Property::WORLD_POSITION,
  50   WORLD_POSITION_X           = Dali::Actor::Property::WORLD_POSITION_X,
  51   WORLD_POSITION_Y           = Dali::Actor::Property::WORLD_POSITION_Y,
  52   WORLD_POSITION_Z           = Dali::Actor::Property::WORLD_POSITION_Z,
  53   ORIENTATION                = Dali::Actor::Property::ORIENTATION,
  54   WORLD_ORIENTATION          = Dali::Actor::Property::WORLD_ORIENTATION,
  55   SCALE                      = Dali::Actor::Property::SCALE,
  56   SCALE_X                    = Dali::Actor::Property::SCALE_X,
  57   SCALE_Y                    = Dali::Actor::Property::SCALE_Y,
  58   SCALE_Z                    = Dali::Actor::Property::SCALE_Z,
  59   WORLD_SCALE                = Dali::Actor::Property::WORLD_SCALE,
  60   VISIBLE                    = Dali::Actor::Property::VISIBLE,
  61   COLOR                      = Dali::Actor::Property::COLOR,
  62   COLOR_RED                  = Dali::Actor::Property::COLOR_RED,
  63   COLOR_GREEN                = Dali::Actor::Property::COLOR_GREEN,
  64   COLOR_BLUE                 = Dali::Actor::Property::COLOR_BLUE,
  65   COLOR_ALPHA                = Dali::Actor::Property::COLOR_ALPHA,
  66   WORLD_COLOR                = Dali::Actor::Property::WORLD_COLOR,
  67   WORLD_MATRIX               = Dali::Actor::Property::WORLD_MATRIX,
  68   NAME                       = Dali::Actor::Property::NAME,
  69   SENSITIVE                  = Dali::Actor::Property::SENSITIVE,
  70   LEAVE_REQUIRED             = Dali::Actor::Property::LEAVE_REQUIRED,
  71   INHERIT_ORIENTATION        = Dali::Actor::Property::INHERIT_ORIENTATION,
  72   INHERIT_SCALE              = Dali::Actor::Property::INHERIT_SCALE,
  73   COLOR_MODE                 = Dali::Actor::Property::COLOR_MODE,
  74   DRAW_MODE                  = Dali::Actor::Property::DRAW_MODE,
  75   SIZE_MODE_FACTOR           = Dali::Actor::Property::SIZE_MODE_FACTOR,
  76   WIDTH_RESIZE_POLICY        = Dali::Actor::Property::WIDTH_RESIZE_POLICY,
  77   HEIGHT_RESIZE_POLICY       = Dali::Actor::Property::HEIGHT_RESIZE_POLICY,
  78   SIZE_SCALE_POLICY          = Dali::Actor::Property::SIZE_SCALE_POLICY,
  79   WIDTH_FOR_HEIGHT           = Dali::Actor::Property::WIDTH_FOR_HEIGHT,
  80   HEIGHT_FOR_WIDTH           = Dali::Actor::Property::HEIGHT_FOR_WIDTH,
  81   PADDING                    = Dali::Actor::Property::PADDING,
  82   MINIMUM_SIZE               = Dali::Actor::Property::MINIMUM_SIZE,
  83   MAXIMUM_SIZE               = Dali::Actor::Property::MAXIMUM_SIZE,
  84   INHERIT_POSITION           = Dali::Actor::Property::INHERIT_POSITION,
  85   CLIPPING_MODE              = Dali::Actor::Property::CLIPPING_MODE,
  86   LAYOUT_DIRECTION           = Dali::Actor::Property::LAYOUT_DIRECTION,
  87   INHERIT_LAYOUT_DIRECTION   = Dali::Actor::Property::INHERIT_LAYOUT_DIRECTION,
  88   OPACITY                    = Dali::Actor::Property::OPACITY,
  89   SCREEN_POSITION            = Dali::Actor::Property::SCREEN_POSITION,
  90   POSITION_USES_ANCHOR_POINT = Dali::Actor::Property::POSITION_USES_ANCHOR_POINT,
  91   CULLED                     = Dali::Actor::Property::CULLED,
  92   ID                         = Dali::Actor::Property::ID,
  93   HIERARCHY_DEPTH            = Dali::Actor::Property::HIERARCHY_DEPTH,
  94   IS_ROOT                    = Dali::Actor::Property::IS_ROOT,
  95   IS_LAYER                   = Dali::Actor::Property::IS_LAYER,
  96   CONNECTED_TO_SCENE         = Dali::Actor::Property::CONNECTED_TO_SCENE,
  97   KEYBOARD_FOCUSABLE         = Dali::Actor::Property::KEYBOARD_FOCUSABLE,
  98
  99   /**
 100    * @brief Sets the sibling order of the actor so depth position can be defined within the same parent.
 101    * @details Name "siblingOrder", type Property::INTEGER.
 102    * @note The initial value is 0.
 103    * @note Raise, Lower, RaiseToTop, LowerToBottom, RaiseAbove and LowerBelow will override the
 104    * sibling order. The values set by this Property will likely change.
 105    */
 106   SIBLING_ORDER,
 107
 108   /**
 109    * @brief Sets the update size hint of the actor.
 110    * @details Name "updateSizeHint", type Property::VECTOR2.
 111    * @note Overrides the size used for the actor damaged area calculation. Affected by the actor model view matrix.
 112    */
 113   UPDATE_SIZE_HINT,
 114
 115   /**
 116     * @brief If this actor receives a touch-start event, then all following touch events are sent to this actor until a touch-end.
 117     * @details Name "captureAllTouchAfterStart", type Property::BOOLEAN
 118     * @note Default is false, i.e. actor under touch event will receive the touch even if touch started on this actor
 119     */
 120   CAPTURE_ALL_TOUCH_AFTER_START,
 121
 122   /**
 123     * @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.
 124     * @details Name "touchAreaOffset", type Property::Rect<int> (left, right, bottom, top).
 125     * For example
 126     * @code{.cpp}
 127     *  Actor actor = Actor::New();
 128     *  actor.SetProperty(Actor::Property::SIZE, Vector2(20.0f, 20.0f));
 129     *  actor.SetProperty(DevelActor::Property::TOUCH_AREA_OFFSET, Rect<int>(-10, 20, 30, -40));
 130     *  actor.TouchedSignal().Connect(OnTouchCallback);
 131     *
 132     * +---------------------+
 133     * |         ^           |
 134     * |         |           |
 135     * |         | -40       |
 136     * |         |           |
 137     * |         |           |
 138     * |    +----+----+      |
 139     * |    |         |      |
 140     * | -10|         | 20   |
 141     * |<---+         +----->|
 142     * |    |         |      |
 143     * |    |         |      |
 144     * |    +----+----+      |
 145     * |         |           |
 146     * |         | 30        |
 147     * |         |           |
 148     * |         v           |
 149     * +---------------------+
 150     * @endcode
 151     * The actual touched size is actor.width + touchAreaOffset.right - touchAreaOffset.left and actor.height + touchAreaOffset.bottom - touchAreaOffset.top
 152     */
 153   TOUCH_AREA_OFFSET,
 154
 155   /**
 156    * @brief Determines which blend equation will be used to render renderers of this actor.
 157    * @pre To use Advanced Blend Equation(DevelBlendEquation::MULTIPLY ~ DevelBlendEquation::LUMINOSITY), the color to be rendered should be pre-multipled alpha.
 158    * @details Name "blendEquation", type Property::INTEGER.
 159    * @note Color of each renderer will be blended with rendering framebuffer.
 160    * @note To check the blend equation is supported in the system, use Dali::Capabilities::IsBlendEquationSupported
 161    */
 162   BLEND_EQUATION,
 163
 164   /**
 165    * @brief Sets whether this view can focus by touch. If user sets this to true, the actor will be focused when user touch it.
 166    * @code
 167    * Actor actor = Actor::New();
 168    * actor.SetProperty(Actor::Property::KEYBOARD_FOCUSABLE, true); // whether the view can have focus or not with keyboard navigation.
 169    * actor.SetProperty(DevelActor::Property::TOUCH_FOCUSABLE, true); // Whether the user can focus by touch, user can set focus by touching the actor.
 170    * @endcode
 171    * @details Name "touchFocusable", type Property::BOOLEAN.
 172    */
 173   TOUCH_FOCUSABLE,
 174
 175   /**
 176    * @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.
 177    * @details Name "keyboardFocusableChildren", type Property::BOOLEAN.
 178    * @note Default value is true.
 179    */
 180   KEYBOARD_FOCUSABLE_CHILDREN,
 181
 182   /**
 183   * @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.
 184   * @details Name "userInteractionEnabled", type Property::BOOLEAN.
 185   * @note Default value is true.
 186   */
 187   USER_INTERACTION_ENABLED,
 188 };
 189
 190 } // namespace Property
 191
 192 namespace VisibilityChange
 193 {
 194 enum Type
 195 {
 196   SELF,  ///< The visibility of the actor itself has changed.
 197   PARENT ///< The visibility of a parent has changed.
 198 };
 199
 200 } // namespace VisibilityChange
 201
 202 using VisibilityChangedSignalType = Signal<void(Actor, bool, VisibilityChange::Type)>; ///< Signal type of VisibilityChangedSignalType
 203
 204 /**
 205  * @brief This signal is emitted when the visible property of this or a parent actor is changed.
 206  *
 207  * A callback of the following type may be connected:
 208  * @code
 209  *   void YourCallbackName( Actor actor, bool visible, VisibilityChange::Type& type );
 210  * @endcode
 211  * actor: The actor, or child of actor, whose visibility has changed
 212  * visible: Whether the actor is now visible or not
 213  * type: Whether the actor's visible property has changed or a parent's.
 214  * @return The signal to connect to
 215  * @pre The Actor has been initialized.
 216  * @note This signal is NOT emitted if the actor becomes transparent (or the reverse), it's only linked with Actor::Property::VISIBLE.
 217  */
 218 DALI_CORE_API VisibilityChangedSignalType& VisibilityChangedSignal(Actor actor);
 219
 220 /**
 221  * Calculates screen position and size.
 222  *
 223  * @return pair of two values, position of top-left corner on screen and size respectively.
 224  */
 225 DALI_CORE_API Rect<> CalculateScreenExtents(Actor actor);
 226
 227 using ChildChangedSignalType = Signal<void(Actor)>; ///< Called when the actor has a child added or removed
 228
 229 /**
 230  * @brief This signal is emitted when a child is added to this actor.
 231  *
 232  * A callback of the following type may be connected:
 233  * @code
 234  *   void MyCallbackName( Actor child );
 235  * @endcode
 236  * child: The child that has been added.
 237  *
 238  * @note Use this signal with caution. Changing the parent of the actor
 239  * within this callback is possible, but DALi will prevent further signals
 240  * being sent.
 241  *
 242  * @return The signal to connect to
 243  * @pre The Actor has been initialized
 244  */
 245 DALI_CORE_API ChildChangedSignalType& ChildAddedSignal(Actor actor);
 246
 247 /**
 248  * @brief This signal is emitted when a child is removed from this actor.
 249  *
 250  * A callback of the following type may be connected:
 251  * @code
 252  *   void MyCallbackName( Actor child );
 253  * @endcode
 254  * child: The child that has been removed.
 255  *
 256  * @note Use this signal with caution. Changing the parent of the actor
 257  * within this callback is possible, but DALi will prevent further signals
 258  * being sent.
 259  *
 260  * @note If the child actor is moved from one actor to another, then
 261  * this signal will be emitted followed immediately by an
 262  * ChildAddedSignal() on the new parent.
 263  *
 264  * @return The signal to connect to
 265  * @pre The Actor has been initialized
 266  */
 267 DALI_CORE_API ChildChangedSignalType& ChildRemovedSignal(Actor actor);
 268
 269 using ChildOrderChangedSignalType = Signal<void(Actor)>; ///< Used when the actor's children have changed order
 270
 271 /**
 272  * @brief This signal is emitted when an actor's children change their sibling order
 273  *
 274  * A callback of the following type may be connected:
 275  * @code
 276  *   void MyCallbackName( Actor parent );
 277  * @endcode
 278  * parent The parent actor of the moved children
 279  *
 280  * @return The signal to connect to
 281  * @pre The Actor has been initialized
 282  */
 283 DALI_CORE_API ChildOrderChangedSignalType& ChildOrderChangedSignal(Actor actor);
 284
 285 /**
 286  * @brief This signal is emitted when intercepting the actor's touch event.
 287  *
 288  * A callback of the following type may be connected:
 289  * @code
 290  *   void MyCallbackName( Actor actor );
 291  * @endcode
 292  * actor The actor to intercept
 293  *
 294  * @note TouchEvent callbacks are called from the last child in the order of the parent's actor.
 295  * The InterceptTouchEvent callback is to intercept the touch event in the parent.
 296  * So, if the parent interepts the touch event, the child cannot receive the touch event.
 297  *
 298  * @note example
 299  *   Actor parent = Actor::New();
 300  *   Actor child = Actor::New();
 301  *   parent.Add(child);
 302  *   child.TouchedSignal().Connect(&application, childFunctor);
 303  *   parent.TouchedSignal().Connect(&application, parentFunctor);
 304  * The touch event callbacks are called in the order childFunctor -> parentFunctor.
 305  *
 306  * If you connect interceptTouchSignal to parentActor.
 307  *   Dali::DevelActor::InterceptTouchedSignal(parent).Connect(&application, interceptFunctor);
 308  *
 309  * When interceptFunctor returns false, the touch event callbacks are called in the same order childFunctor -> parentFunctor.
 310  * If interceptFunctor returns true, it means that the TouchEvent was intercepted.
 311  * So the child actor will not be able to receive touch events.
 312  * Only the parentFunctor is called.
 313  *
 314  * @return The signal to connect to
 315  * @pre The Actor has been initialized
 316  */
 317 DALI_CORE_API Actor::TouchEventSignalType& InterceptTouchedSignal(Actor actor);
 318
 319 /**
 320  * @brief This is used when the parent actor wants to listen to gesture events.
 321  *
 322  * @note example The child is overlapped on the parent.
 323  * Currently, if you tap a child, the parent cannot listen to the tap event.
 324  * Now, If set to SetNeedGesturePropagation(true), the parent can receive gesture events.
 325  * Please call this setting inside a gesture callback, it will be reset after the gesture callback is called.
 326  * @code
 327  * {
 328  *    Actor parent = Actor::New();
 329  *    Actor child = Actor::New();
 330  *    parent.Add(child);
 331  *    parentTapDetector = TapGestureDetector::New();
 332  *    childTapDetector = TapGestureDetector::New();
 333  *    parentTapDetector.Attach(parent);
 334  *    childTapDetector.Attach(child);
 335  *    parentTapDetector.DetectedSignal().Connect(this, &OnParentTap);
 336  *    childTapDetector.DetectedSignal().Connect(this, &OnChildTap);
 337  * }
 338  * void OnChildTap(Dali::Actor actor, const Dali::TapGesture& tap)
 339  * {
 340  *    // If you set SetNeedGesturePropagation to true here, the parent actor can also listen to events
 341  *    Dali::DevelActor::SetNeedGesturePropagation(Self(), true);
 342  * }
 343  * @endcode
 344  *
 345  */
 346 DALI_CORE_API void SetNeedGesturePropagation(Actor actor, bool propagation);
 347
 348 /**
 349  * Switch parent in the same tree.
 350  * This method changes the actor's parent with keeping on scene state.
 351  * Both of current parent Actor and new parent Actor must already be added on Scene.
 352  * This method don't emit notification about add/remove and on/off scene.
 353  * @param [in] actor This actor
 354  * @param [in] newParent An actor to be a new parent of this actor.
 355  */
 356 DALI_CORE_API void SwitchParent(Actor actor, Actor newParent);
 357
 358 /**
 359  * @brief This signal is emitted when an actor is hit through hit-test.
 360  *
 361  * A callback of the following type may be connected:
 362  * @code
 363  *   void MyCallbackName( Actor actor );
 364  * @endcode
 365  * actor The actor to intercept
 366  *
 367  * @note This callback is called when the actor is hit.
 368  * If true is returned, TouchEvent is called from the this actor.
 369  * If false is returned, the hit test starts again from the next lower actor.
 370  *
 371  * @note example
 372  *   Actor topActor = Actor::New();
 373  *   Actor bottomActor = Actor::New();
 374  *   topActor.TouchedSignal().Connect(&application, topActorFunctor);
 375  *   bottomActor.TouchedSignal().Connect(&application, bottomActorFunctor);
 376  * The two actors have no relationship.
 377  * So when the topActor is touched, the event cannot be propagated to the bottomActor.
 378  *
 379  * If you connect HitTestResultSignal to topActor.
 380  *   Dali::DevelActor::HitTestResultSignal(topActor).Connect(&application, hitTestResultFunctor);
 381  *
 382  * If the hitTestResult Functor returns false, it passes the hit-test and starts the hit-test again from the next lower actor.
 383  * So the bottomActor can be hit and receive touch events.
 384  * If hitTestResult returns true, it means that it has been hit. So it receives a TouchEvent from itself.
 385  *
 386  * @return The signal to connect to
 387  * @pre The Actor has been initialized
 388  */
 389 DALI_CORE_API Actor::TouchEventSignalType& HitTestResultSignal(Actor actor);
 390
 391 } // namespace DevelActor
 392
 393 } // namespace Dali
 394
 395 #endif // DALI_ACTOR_DEVEL_H