1 #ifndef DALI_ACTOR_DEVEL_H
2 #define DALI_ACTOR_DEVEL_H
5 * Copyright (c) 2022 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 #include <dali/public-api/actors/actor.h>
23 #include <dali/public-api/math/rect.h>
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,
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.
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.
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
120 CAPTURE_ALL_TOUCH_AFTER_START,
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).
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);
132 * +---------------------+
149 * +---------------------+
151 * The actual touched size is actor.width + touchAreaOffset.right - touchAreaOffset.left and actor.height + touchAreaOffset.bottom - touchAreaOffset.top
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
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.
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.
171 * @details Name "touchFocusable", type Property::BOOLEAN.
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.
180 KEYBOARD_FOCUSABLE_CHILDREN
183 } // namespace Property
185 namespace VisibilityChange
189 SELF, ///< The visibility of the actor itself has changed.
190 PARENT ///< The visibility of a parent has changed.
193 } // namespace VisibilityChange
195 using VisibilityChangedSignalType = Signal<void(Actor, bool, VisibilityChange::Type)>; ///< Signal type of VisibilityChangedSignalType
198 * @brief This signal is emitted when the visible property of this or a parent actor is changed.
200 * A callback of the following type may be connected:
202 * void YourCallbackName( Actor actor, bool visible, VisibilityChange::Type& type );
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.
211 DALI_CORE_API VisibilityChangedSignalType& VisibilityChangedSignal(Actor actor);
214 * Calculates screen position and size.
216 * @return pair of two values, position of top-left corner on screen and size respectively.
218 DALI_CORE_API Rect<> CalculateScreenExtents(Actor actor);
220 using ChildChangedSignalType = Signal<void(Actor)>; ///< Called when the actor has a child added or removed
223 * @brief This signal is emitted when a child is added to this actor.
225 * A callback of the following type may be connected:
227 * void MyCallbackName( Actor child );
229 * child: The child that has been added.
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
235 * @return The signal to connect to
236 * @pre The Actor has been initialized
238 DALI_CORE_API ChildChangedSignalType& ChildAddedSignal(Actor actor);
241 * @brief This signal is emitted when a child is removed from this actor.
243 * A callback of the following type may be connected:
245 * void MyCallbackName( Actor child );
247 * child: The child that has been removed.
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
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.
257 * @return The signal to connect to
258 * @pre The Actor has been initialized
260 DALI_CORE_API ChildChangedSignalType& ChildRemovedSignal(Actor actor);
262 using ChildOrderChangedSignalType = Signal<void(Actor)>; ///< Used when the actor's children have changed order
265 * @brief This signal is emitted when an actor's children change their sibling order
267 * A callback of the following type may be connected:
269 * void MyCallbackName( Actor parent );
271 * parent The parent actor of the moved children
273 * @return The signal to connect to
274 * @pre The Actor has been initialized
276 DALI_CORE_API ChildOrderChangedSignalType& ChildOrderChangedSignal(Actor actor);
279 * @brief This signal is emitted when intercepting the actor's touch event.
281 * A callback of the following type may be connected:
283 * void MyCallbackName( Actor actor );
285 * actor The actor to intercept
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.
292 * Actor parent = Actor::New();
293 * Actor child = Actor::New();
295 * child.TouchedSignal().Connect(&application, childFunctor);
296 * parent.TouchedSignal().Connect(&application, parentFunctor);
297 * The touch event callbacks are called in the order childFunctor -> parentFunctor.
299 * If you connect interceptTouchSignal to parentActor.
300 * Dali::DevelActor::InterceptTouchedSignal(parent).Connect(&application, interceptFunctor);
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.
307 * @return The signal to connect to
308 * @pre The Actor has been initialized
310 DALI_CORE_API Actor::TouchEventSignalType& InterceptTouchedSignal(Actor actor);
313 * @brief This is used when the parent actor wants to listen to gesture events.
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.
321 * Actor parent = Actor::New();
322 * Actor child = Actor::New();
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);
331 * void OnChildTap(Dali::Actor actor, const Dali::TapGesture& tap)
333 * // If you set SetNeedGesturePropagation to true here, the parent actor can also listen to events
334 * Dali::DevelActor::SetNeedGesturePropagation(Self(), true);
339 DALI_CORE_API void SetNeedGesturePropagation(Actor actor, bool propagation);
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.
349 DALI_CORE_API void SwitchParent(Actor actor, Actor newParent);
352 * @brief This signal is emitted when an actor is hit through hit-test.
354 * A callback of the following type may be connected:
356 * void MyCallbackName( Actor actor );
358 * actor The actor to intercept
360 * @note This callback is called when the actor is hit.
361 * If true is returned, TouchEvent is called from the this actor.
362 * If false is returned, the hit test starts again from the next lower actor.
365 * Actor topActor = Actor::New();
366 * Actor bottomActor = Actor::New();
367 * topActor.TouchedSignal().Connect(&application, topActorFunctor);
368 * bottomActor.TouchedSignal().Connect(&application, bottomActorFunctor);
369 * The two actors have no relationship.
370 * So when the topActor is touched, the event cannot be propagated to the bottomActor.
372 * If you connect HitTestResultSignal to topActor.
373 * Dali::DevelActor::HitTestResultSignal(topActor).Connect(&application, hitTestResultFunctor);
375 * If the hitTestResult Functor returns false, it passes the hit-test and starts the hit-test again from the next lower actor.
376 * So the bottomActor can be hit and receive touch events.
377 * If hitTestResult returns true, it means that it has been hit. So it receives a TouchEvent from itself.
379 * @return The signal to connect to
380 * @pre The Actor has been initialized
382 DALI_CORE_API Actor::TouchEventSignalType& HitTestResultSignal(Actor actor);
384 } // namespace DevelActor
388 #endif // DALI_ACTOR_DEVEL_H