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

   1 #ifndef DALI_ACTOR_DEVEL_H
   2 #define DALI_ACTOR_DEVEL_H
   3
   4 /*
   5  * Copyright (c) 2021 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 } // namespace Property
 184
 185 namespace VisibilityChange
 186 {
 187 enum Type
 188 {
 189   SELF,  ///< The visibility of the actor itself has changed.
 190   PARENT ///< The visibility of a parent has changed.
 191 };
 192
 193 } // namespace VisibilityChange
 194
 195 using VisibilityChangedSignalType = Signal<void(Actor, bool, VisibilityChange::Type)>; ///< Signal type of VisibilityChangedSignalType
 196
 197 /**
 198  * @brief This signal is emitted when the visible property of this or a parent actor is changed.
 199  *
 200  * A callback of the following type may be connected:
 201  * @code
 202  *   void YourCallbackName( Actor actor, bool visible, VisibilityChange::Type& type );
 203  * @endcode
 204  * actor: The actor, or child of actor, whose visibility has changed
 205  * visible: Whether the actor is now visible or not
 206  * type: Whether the actor's visible property has changed or a parent's.
 207  * @return The signal to connect to
 208  * @pre The Actor has been initialized.
 209  * @note This signal is NOT emitted if the actor becomes transparent (or the reverse), it's only linked with Actor::Property::VISIBLE.
 210  */
 211 DALI_CORE_API VisibilityChangedSignalType& VisibilityChangedSignal(Actor actor);
 212
 213 /**
 214  * Calculates screen position and size.
 215  *
 216  * @return pair of two values, position of top-left corner on screen and size respectively.
 217  */
 218 DALI_CORE_API Rect<> CalculateScreenExtents(Actor actor);
 219
 220 using ChildChangedSignalType = Signal<void(Actor)>; ///< Called when the actor has a child added or removed
 221
 222 /**
 223  * @brief This signal is emitted when a child is added to this actor.
 224  *
 225  * A callback of the following type may be connected:
 226  * @code
 227  *   void MyCallbackName( Actor child );
 228  * @endcode
 229  * child: The child that has been added.
 230  *
 231  * @note Use this signal with caution. Changing the parent of the actor
 232  * within this callback is possible, but DALi will prevent further signals
 233  * being sent.
 234  *
 235  * @return The signal to connect to
 236  * @pre The Actor has been initialized
 237  */
 238 DALI_CORE_API ChildChangedSignalType& ChildAddedSignal(Actor actor);
 239
 240 /**
 241  * @brief This signal is emitted when a child is removed from this actor.
 242  *
 243  * A callback of the following type may be connected:
 244  * @code
 245  *   void MyCallbackName( Actor child );
 246  * @endcode
 247  * child: The child that has been removed.
 248  *
 249  * @note Use this signal with caution. Changing the parent of the actor
 250  * within this callback is possible, but DALi will prevent further signals
 251  * being sent.
 252  *
 253  * @note If the child actor is moved from one actor to another, then
 254  * this signal will be emitted followed immediately by an
 255  * ChildAddedSignal() on the new parent.
 256  *
 257  * @return The signal to connect to
 258  * @pre The Actor has been initialized
 259  */
 260 DALI_CORE_API ChildChangedSignalType& ChildRemovedSignal(Actor actor);
 261
 262 using ChildOrderChangedSignalType = Signal<void(Actor)>; ///< Used when the actor's children have changed order
 263
 264 /**
 265  * @brief This signal is emitted when an actor's children change their sibling order
 266  *
 267  * A callback of the following type may be connected:
 268  * @code
 269  *   void MyCallbackName( Actor parent );
 270  * @endcode
 271  * parent The parent actor of the moved children
 272  *
 273  * @return The signal to connect to
 274  * @pre The Actor has been initialized
 275  */
 276 DALI_CORE_API ChildOrderChangedSignalType& ChildOrderChangedSignal(Actor actor);
 277
 278 /**
 279  * @brief This signal is emitted when intercepting the actor's touch event.
 280  *
 281  * A callback of the following type may be connected:
 282  * @code
 283  *   void MyCallbackName( Actor actor );
 284  * @endcode
 285  * actor The actor to intercept
 286  *
 287  * @note TouchEvent callbacks are called from the last child in the order of the parent's actor.
 288  * The InterceptTouchEvent callback is to intercept the touch event in the parent.
 289  * So, if the parent interepts the touch event, the child cannot receive the touch event.
 290  *
 291  * @note example
 292  *   Actor parent = Actor::New();
 293  *   Actor child = Actor::New();
 294  *   parent.Add(child);
 295  *   child.TouchedSignal().Connect(&application, childFunctor);
 296  *   parent.TouchedSignal().Connect(&application, parentFunctor);
 297  * The touch event callbacks are called in the order childFunctor -> parentFunctor.
 298  *
 299  * If you connect interceptTouchSignal to parentActor.
 300  *   Dali::DevelActor::InterceptTouchedSignal(parent).Connect(&application, interceptFunctor);
 301  *
 302  * When interceptFunctor returns false, the touch event callbacks are called in the same order childFunctor -> parentFunctor.
 303  * If interceptFunctor returns true, it means that the TouchEvent was intercepted.
 304  * So the child actor will not be able to receive touch events.
 305  * Only the parentFunctor is called.
 306  *
 307  * @return The signal to connect to
 308  * @pre The Actor has been initialized
 309  */
 310 DALI_CORE_API Actor::TouchEventSignalType& InterceptTouchedSignal(Actor actor);
 311
 312 /**
 313  * @brief This is used when the parent actor wants to listen to gesture events.
 314  *
 315  * @note example The child is overlapped on the parent.
 316  * Currently, if you tap a child, the parent cannot listen to the tap event.
 317  * Now, If set to SetNeedGesturePropagation(true), the parent can receive gesture events.
 318  * Please call this setting inside a gesture callback, it will be reset after the gesture callback is called.
 319  * @code
 320  * {
 321  *    Actor parent = Actor::New();
 322  *    Actor child = Actor::New();
 323  *    parent.Add(child);
 324  *    parentTapDetector = TapGestureDetector::New();
 325  *    childTapDetector = TapGestureDetector::New();
 326  *    parentTapDetector.Attach(parent);
 327  *    childTapDetector.Attach(child);
 328  *    parentTapDetector.DetectedSignal().Connect(this, &OnParentTap);
 329  *    childTapDetector.DetectedSignal().Connect(this, &OnChildTap);
 330  * }
 331  * void OnChildTap(Dali::Actor actor, const Dali::TapGesture& tap)
 332  * {
 333  *    // If you set SetNeedGesturePropagation to true here, the parent actor can also listen to events
 334  *    Dali::DevelActor::SetNeedGesturePropagation(Self(), true);
 335  * }
 336  * @endcode
 337  *
 338  */
 339 DALI_CORE_API void SetNeedGesturePropagation(Actor actor, bool propagation);
 340
 341 /**
 342  * Switch parent in the same tree.
 343  * This method changes the actor's parent with keeping on scene state.
 344  * Both of current parent Actor and new parent Actor must already be added on Scene.
 345  * This method don't emit notification about add/remove and on/off scene.
 346  * @param [in] actor This actor
 347  * @param [in] newParent An actor to be a new parent of this actor.
 348  */
 349 DALI_CORE_API void SwitchParent(Actor actor, Actor newParent);
 350
 351 } // namespace DevelActor
 352
 353 } // namespace Dali
 354
 355 #endif // DALI_ACTOR_DEVEL_H