#define DALI_ACTOR_DEVEL_H
/*
- * Copyright (c) 2021 Samsung Electronics Co., Ltd.
+ * Copyright (c) 2024 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.
IS_LAYER = Dali::Actor::Property::IS_LAYER,
CONNECTED_TO_SCENE = Dali::Actor::Property::CONNECTED_TO_SCENE,
KEYBOARD_FOCUSABLE = Dali::Actor::Property::KEYBOARD_FOCUSABLE,
+ UPDATE_AREA_HINT = Dali::Actor::Property::UPDATE_AREA_HINT,
/**
* @brief Sets the sibling order of the actor so depth position can be defined within the same parent.
SIBLING_ORDER,
/**
- * @brief Sets the update size hint of the actor.
- * @details Name "updateSizeHint", type Property::VECTOR2.
- * @note Overrides the size used for the actor damaged area calculation. Affected by the actor model view matrix.
- */
- UPDATE_SIZE_HINT,
-
- /**
* @brief If this actor receives a touch-start event, then all following touch events are sent to this actor until a touch-end.
* @details Name "captureAllTouchAfterStart", type Property::BOOLEAN
* @note Default is false, i.e. actor under touch event will receive the touch even if touch started on this actor
BLEND_EQUATION,
/**
- * @brief Sets whether this view can focus by touch. If user sets this to true, the actor will be focused when user touch it.
+ * @brief Sets whether this actor can focus by touch. If user sets this to true, the actor will be focused when user touch it.
* @code
* Actor actor = Actor::New();
- * actor.SetProperty(Actor::Property::KEYBOARD_FOCUSABLE, true); // whether the view can have focus or not with keyboard navigation.
+ * actor.SetProperty(Actor::Property::KEYBOARD_FOCUSABLE, true); // whether the actor can have focus or not with keyboard navigation.
* actor.SetProperty(DevelActor::Property::TOUCH_FOCUSABLE, true); // Whether the user can focus by touch, user can set focus by touching the actor.
* @endcode
* @details Name "touchFocusable", type Property::BOOLEAN.
* @details Name "keyboardFocusableChildren", type Property::BOOLEAN.
* @note Default value is true.
*/
- KEYBOARD_FOCUSABLE_CHILDREN
+ KEYBOARD_FOCUSABLE_CHILDREN,
+
+ /**
+ * @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.
+ * @details Name "userInteractionEnabled", type Property::BOOLEAN.
+ * @note Default value is true.
+ */
+ USER_INTERACTION_ENABLED,
+
+ /**
+ * @brief It only receive for touch events that started from itself.
+ * @details Name "allowOnlyOwnTouch", type Property::BOOLEAN
+ * @note Default is false.
+ */
+ ALLOW_ONLY_OWN_TOUCH,
+
+ /**
+ * @brief Whether the actor uses the update area of the texture instead of its own.
+ * @details Name "useTextureUpdateArea", type Property::BOOLEAN
+ * @note Default is false. If this set true, the value of Actor::Property::UPDATE_AREA_HINT is ignored and we assume the sizes of the actor and the texture are same.
+ */
+ USE_TEXTURE_UPDATE_AREA,
+
+ /**
+ * @brief Whether to send touch motion events or not.
+ * @details Name "dispatchTouchMotion", type Property::BOOLEAN
+ * @note Default is true.
+ */
+ DISPATCH_TOUCH_MOTION,
+
+ /**
+ * @brief Whether to send hover motion events or not.
+ * @details Name "dispatchHoverMotion", type Property::BOOLEAN
+ * @note Default is true.
+ */
+ DISPATCH_HOVER_MOTION
};
} // namespace Property
* @code
* void YourCallbackName( Actor actor, bool visible, VisibilityChange::Type& type );
* @endcode
- * actor: The actor, or child of actor, whose visibility has changed
- * visible: Whether the actor is now visible or not
+ * actor: The actor, or child of actor, whose visibility has changed.
+ * visible: If type is SELF, then this is true if this actor's VISIBILITY property is true. If Type is PARENT, this is true if a parent's VISIBILITY property has changed to true.
* type: Whether the actor's visible property has changed or a parent's.
* @return The signal to connect to
* @pre The Actor has been initialized.
- * @note This signal is NOT emitted if the actor becomes transparent (or the reverse), it's only linked with Actor::Property::VISIBLE.
+ * @note This signal is NOT emitted if the actor becomes transparent (or the reverse), it's ONLY linked with Actor::Property::VISIBLE.
+ * @note For reference, an actor is only shown if it and it's parents (up to the root actor) are also visible, are not transparent, and this actor has a non-zero size.
*/
DALI_CORE_API VisibilityChangedSignalType& VisibilityChangedSignal(Actor actor);
/**
+ * @brief Get the actor who trigger the VisibilityChangedSignal or InheritedVisibilityChangedSignal signal.
+ * @note The return value is "INVALID" if this API called outside of the VisibilityChangedSignal or InheritedVisibilityChangedSignal signal.
+ * "INVALID" don't mean the empty handle. It might return the valid handle. But it doesn't mean the visibility changed actor.
+ * if this API called outside of VisibilityChangedSignal or InheritedVisibilityChangedSignal signal.
+ *
+ * For example, Let we assume some Actor tree looks like (root)A - B - C - D - E.
+ * If we change C's visibility as false + Change A's visibility inside of D's VisibilityChangedSignal callback,
+ * The result of this API will like this.
+ *
+ * (Some codes here) --> GetVisiblityChangedActor() is INVALID
+ * C.SetProperty(Actor::Property::VISIBLE, false)
+ * VisibilityChangedSignal(C, false, VisibilityChange::SELF) --> GetVisiblityChangedActor() is Actor C
+ * VisibilityChangedSignal(D, false, VisibilityChange::PARENT) --> GetVisiblityChangedActor() is Actor C
+ * A.SetProperty(Actor::Property::VISIBLE, false)
+ * VisibilityChangedSignal(A, false, VisibilityChange::SELF) --> GetVisiblityChangedActor() is Actor A
+ * VisibilityChangedSignal(B, false, VisibilityChange::PARENT) --> GetVisiblityChangedActor() is Actor A
+ * VisibilityChangedSignal(C, false, VisibilityChange::PARENT) --> GetVisiblityChangedActor() is Actor A
+ * VisibilityChangedSignal(D, false, VisibilityChange::PARENT) --> GetVisiblityChangedActor() is Actor A
+ * VisibilityChangedSignal(E, false, VisibilityChange::PARENT) --> GetVisiblityChangedActor() is Actor A
+ * InheritedVisibilityChangedSignal(A, false) --> GetVisiblityChangedActor() is Actor A
+ * InheritedVisibilityChangedSignal(B, false) --> GetVisiblityChangedActor() is Actor A
+ * (Some codes here) --> GetVisiblityChangedActor() is Actor C
+ * VisibilityChangedSignal(E, false, VisibilityChange::PARENT) --> GetVisiblityChangedActor() is Actor C
+ * InheritedVisibilityChangedSignal(C, false) --> GetVisiblityChangedActor() is Actor C
+ * InheritedVisibilityChangedSignal(D, false) --> GetVisiblityChangedActor() is Actor C
+ * InheritedVisibilityChangedSignal(E, false) --> GetVisiblityChangedActor() is Actor C
+ * (Some codes here) --> GetVisiblityChangedActor() is INVALID
+ *
+ * @return The actor who trigger the visibility changed signal.
+ */
+DALI_CORE_API Actor GetVisiblityChangedActor();
+
+/**
+ * Calculates screen position.
+ *
+ * @return position of anchor point from top-left corner on screen respectively.
+ */
+DALI_CORE_API Vector2 CalculateScreenPosition(Actor actor);
+
+/**
* Calculates screen position and size.
*
* @return pair of two values, position of top-left corner on screen and size respectively.
*/
DALI_CORE_API Rect<> CalculateScreenExtents(Actor actor);
+/**
+ * Calculates screen position and size from the scene-graph values.
+ *
+ * It will use already calculated informations on scene-graph so calculation will be fast.
+ * But the result doesn't applied what this event-loop updated. For example, it will return wrong value in Relayout API.
+ *
+ * @return pair of two values, position of top-left corner on screen and size respectively.
+ */
+DALI_CORE_API Rect<> CalculateCurrentScreenExtents(Actor actor);
+
using ChildChangedSignalType = Signal<void(Actor)>; ///< Called when the actor has a child added or removed
/**
DALI_CORE_API Actor::TouchEventSignalType& InterceptTouchedSignal(Actor actor);
/**
+ * @brief This signal is emitted when intercepting the actor's wheel event.
+ *
+ * A callback of the following type may be connected:
+ * @code
+ * void MyCallbackName( Actor actor );
+ * @endcode
+ * actor The actor to intercept
+ *
+ * @note WheelEvent callbacks are called from the last child in the order of the parent's actor.
+ * The InterceptWheelEvent callback is to intercept the wheel event in the parent.
+ * So, if the parent interepts the wheel event, the child cannot receive the Wheel event.
+ *
+ * @note example
+ * Actor parent = Actor::New();
+ * Actor child = Actor::New();
+ * parent.Add(child);
+ * child.WheelEventSignal().Connect(&application, childFunctor);
+ * parent.WheelEventSignal().Connect(&application, parentFunctor);
+ * The wheel event callbacks are called in the order childFunctor -> parentFunctor.
+ *
+ * If you connect InterceptWheelSignal to parentActor.
+ * Dali::DevelActor::InterceptWheelSignal(parent).Connect(&application, interceptFunctor);
+ *
+ * When interceptFunctor returns false, the wheel event callbacks are called in the same order childFunctor -> parentFunctor.
+ * If interceptFunctor returns true, it means that the WheelEvent was intercepted.
+ * So the child actor will not be able to receive wheel events.
+ * Only the parentFunctor is called.
+ *
+ * @return The signal to connect to
+ * @pre The Actor has been initialized
+ */
+DALI_CORE_API Actor::WheelEventSignalType& InterceptWheelSignal(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.
*/
DALI_CORE_API void SwitchParent(Actor actor, Actor newParent);
+/**
+ * @brief This signal is emitted when an actor is hit through hit-test.
+ *
+ * A callback of the following type may be connected:
+ * @code
+ * void MyCallbackName( Actor actor );
+ * @endcode
+ * actor The actor to intercept
+ *
+ * @note This callback is called when the actor is hit.
+ * If true is returned, TouchEvent is called from the this actor.
+ * If false is returned, the hit test starts again from the next lower actor.
+ *
+ * @note example
+ * Actor topActor = Actor::New();
+ * Actor bottomActor = Actor::New();
+ * topActor.TouchedSignal().Connect(&application, topActorFunctor);
+ * bottomActor.TouchedSignal().Connect(&application, bottomActorFunctor);
+ * The two actors have no relationship.
+ * So when the topActor is touched, the event cannot be propagated to the bottomActor.
+ *
+ * If you connect HitTestResultSignal to topActor.
+ * Dali::DevelActor::HitTestResultSignal(topActor).Connect(&application, hitTestResultFunctor);
+ *
+ * If the hitTestResult Functor returns false, it passes the hit-test and starts the hit-test again from the next lower actor.
+ * So the bottomActor can be hit and receive touch events.
+ * If hitTestResult returns true, it means that it has been hit. So it receives a TouchEvent from itself.
+ *
+ * @return The signal to connect to
+ * @pre The Actor has been initialized
+ */
+DALI_CORE_API Actor::TouchEventSignalType& HitTestResultSignal(Actor actor);
+
+/**
+ * Get the world transform of the actor.
+ *
+ * This calculates the world transform from scratch using only event
+ * side properties - it does not rely on the update thread to have
+ * already calculated the transform.
+ *
+ * @param[in] actor The actor for which to calculate the world transform
+ * @return The world transform matrix
+ */
+DALI_CORE_API Matrix GetWorldTransform(Actor actor);
+
+/**
+ * Get the world color of the actor.
+ *
+ * This calcualtes the world color of the actor from scratch using
+ * only event side properties. It does not rely on the update thread
+ * to have already calculated the color.
+ *
+ * @param[in] actor The actor to calculate the world color for
+ * @return the world color
+ */
+DALI_CORE_API Vector4 GetWorldColor(Actor actor);
+
+/**
+ * Rotate the actor look at specific position.
+ * It will change the actor's orientation property.
+ *
+ * This calculates the world transform from scratch using only event
+ * side properties - it does not rely on the update thread to have
+ * already calculated the transform.
+ *
+ * @note Target position should be setup by world coordinates.
+ * @note The result of invalid input is not determined.
+ * (ex : forward vector or actor-to-target vector has same direction with up, One of them is ZERO)
+ *
+ * @param[in] actor The actor for which to calculate the look at orientation.
+ * @param[in] target The target world position to look at.
+ * @param[in] up The up vector after target look at. Default is +Y axis.
+ * @param[in] localForward The forward vector of actor when it's orientation is not applied. Default is +Z axis.
+ * @param[in] localUp The up vector of actor when it's orientation is not applied. Default is +Y axis.
+ */
+DALI_CORE_API void LookAt(Actor actor, Vector3 target, Vector3 up = Vector3::YAXIS, Vector3 localForward = Vector3::ZAXIS, Vector3 localUp = Vector3::YAXIS);
+
+/**
+ * Query whether the actor is actually hittable. This method checks whether the actor is
+ * sensitive, has the visibility flag set to true and is not fully transparent.
+ *
+ * @param[in] actor The actor for whether is hittable or not
+ * @return true, if it can be hit, false otherwise.
+ */
+DALI_CORE_API bool IsHittable(Actor actor);
+
+/**
+ * Query whether the application or derived actor type requires touch events.
+ *
+ * @param[in] actor The actor for whether is required for touch event or not.
+ * @return True if touch events are required.
+ */
+DALI_CORE_API bool GetTouchRequired(Actor actor);
+
} // namespace DevelActor
} // namespace Dali
projects / platform / core / uifw / dali-core.git / blobdiff