X-Git-Url: http://review.tizen.org/git/?p=platform%2Fcore%2Fuifw%2Fdali-toolkit.git;a=blobdiff_plain;f=dali-toolkit%2Fpublic-api%2Fcontrols%2Fcontrol.h;h=6ecfd8bb19f909398601ef414dc9d2eea6629080;hp=e837858f091a08d779a099926ac2babc87345a84;hb=refs%2Fchanges%2F77%2F239777%2F2;hpb=8e781cfc4010a03a0fa065887c77c21200a8bb87 diff --git a/dali-toolkit/public-api/controls/control.h b/dali-toolkit/public-api/controls/control.h index e837858..6ecfd8b 100644 --- a/dali-toolkit/public-api/controls/control.h +++ b/dali-toolkit/public-api/controls/control.h @@ -1,8 +1,8 @@ -#ifndef __DALI_TOOLKIT_CONTROL_H__ -#define __DALI_TOOLKIT_CONTROL_H__ +#ifndef DALI_TOOLKIT_CONTROL_H +#define DALI_TOOLKIT_CONTROL_H /* - * Copyright (c) 2016 Samsung Electronics Co., Ltd. + * Copyright (c) 2020 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. @@ -20,13 +20,15 @@ // EXTERNAL INCLUDES #include -#include +#include #include #include #include #include #include -#include + +// INTERNAL INCLUDES +#include namespace Dali { @@ -58,6 +60,7 @@ class Control; * | keyEvent | @ref KeyEventSignal() | * | keyInputFocusGained | @ref KeyInputFocusGainedSignal() | * | keyInputFocusLost | @ref KeyInputFocusLostSignal() | + * | resourceReady | @ref ResourceReadySignal() | * | tapped | @ref GetTapGestureDetector().DetectedSignal() | * | panned | @ref GetPanGestureDetector().DetectedSignal() | * | pinched | @ref GetPinchGestureDetector().DetectedSignal() | @@ -68,12 +71,12 @@ class Control; * |------------------------|----------------------------------------------------| * | accessibilityActivated | %OnAccessibilityActivated() | */ -class DALI_IMPORT_API Control : public CustomActor +class DALI_TOOLKIT_API Control : public CustomActor { public: /** - * @brief The start and end property ranges for control. + * @brief Enumeration for the start and end property ranges for control. * @SINCE_1_0.0 */ enum PropertyRange @@ -84,47 +87,55 @@ public: }; /** - * @brief An enumeration of properties belonging to the Control class. + * @brief Enumeration for the instance of properties belonging to the Control class. * @SINCE_1_0.0 */ struct Property { /** - * @brief An enumeration of properties belonging to the Control class. + * @brief Enumeration for the instance of properties belonging to the Control class. * @SINCE_1_0.0 */ enum { /** - * @brief name "styleName", type std::string + * @brief The name of the style to be applied to the control. + * @details Name "styleName", type Property::STRING. + * @see Toolkit::Control::SetStyleName() * @SINCE_1_0.0 - * @see SetStyleName */ STYLE_NAME = PROPERTY_START_INDEX, + /** - * @DEPRECATED_1_1.3 - * @brief name "backgroundColor", mutually exclusive with BACKGROUND_IMAGE & BACKGROUND, type Vector4 + * @brief Receives key events to the control. + * @details Name "keyInputFocus", type Property::BOOLEAN. + * @see Toolkit::Control::SetKeyInputFocus() * @SINCE_1_0.0 - * @see SetStyleName */ - BACKGROUND_COLOR, + KEY_INPUT_FOCUS, + /** - * @DEPRECATED_1_1.3 - * @brief name "backgroundImage", mutually exclusive with BACKGROUND_COLOR & BACKGROUND, type Map - * @SINCE_1_0.0 + * @brief The background of the control. + * + * @details Name "background", type Property::MAP or std::string for URL or Property::VECTOR4 for Color. + * @SINCE_1_1.3 */ - BACKGROUND_IMAGE, + BACKGROUND, + /** - * @brief name "keyInputFocus", type bool - * @SINCE_1_0.0 - * @see SetKeyInputFocus + * @brief The outer space around the control. + * @details Name "margin", type Property::EXTENTS. + * @SINCE_1_2.62 + * @note Margin property is to be supported by Layout algorithms and containers in future. */ - KEY_INPUT_FOCUS, + MARGIN, + /** - * @brief name "background", mutually exclusive with BACKGROUND_COLOR & BACKGROUND_IMAGE, type Map or std::string for URL - * @SINCE_1_1.3 + * @brief The inner space of the control. + * @details Name "padding", type Property::EXTENTS. + * @SINCE_1_2.62 */ - BACKGROUND, + PADDING }; }; @@ -135,7 +146,7 @@ public: struct KeyboardFocus { /** - * @brief Keyboard focus direction + * @brief Keyboard focus direction. * @SINCE_1_0.0 */ enum Direction @@ -151,24 +162,27 @@ public: // Typedefs - /// @brief Key Event signal type; + /// @brief Key Event signal type. @SINCE_1_0.0 typedef Signal KeyEventSignalType; - /// @brief Key InputFocusType signal type; + /// @brief Key InputFocusType signal type. @SINCE_1_0.0 typedef Signal KeyInputFocusSignalType; + /// @brief ResourceReady signal type. @SINCE_1_2.60 + typedef Signal ResourceReadySignalType; + public: // Creation & Destruction /** - * @brief Create a new instance of a Control. + * @brief Creates a new instance of a Control. * * @SINCE_1_0.0 - * @return A handle to a new Control. + * @return A handle to a new Control */ static Control New(); /** - * @brief Create an uninitialized Control handle. + * @brief Creates an uninitialized Control handle. * * Only derived versions can be instantiated. Calling member * functions with an uninitialized Dali::Object is not allowed. @@ -186,6 +200,14 @@ public: // Creation & Destruction Control(const Control& uiControl); /** + * @brief Move constructor. + * + * @SINCE_1_9.23 + * @param[in] rhs Handle to move + */ + Control( Control&& rhs ); + + /** * @brief Dali::Control is intended as a base class. * * This is non-virtual since derived Handle types must not contain data or virtual methods. @@ -196,22 +218,31 @@ public: // Creation & Destruction public: // operators /** - * @brief Assignment operator. + * @brief Copy assignment operator. * * Changes this handle to point to another real object. * @SINCE_1_0.0 * @param[in] handle Object to assign this to - * @return reference to this + * @return Reference to this */ Control& operator=( const Control& handle ); + /** + * @brief Move assignment operator. + * + * @SINCE_1_9.23 + * @param[in] rhs Object to assign this to + * @return Reference to this + */ + Control& operator=( Control&& rhs ); + public: /** - * @brief Downcast a handle to Control handle. + * @brief Downcasts a handle to Control handle. * - * If handle points to a Control the downcast produces valid - * handle. If not the returned handle is left uninitialized. + * If handle points to a Control, the downcast produces valid handle. + * If not, the returned handle is left uninitialized. * * @SINCE_1_0.0 * @param[in] handle Handle to an object @@ -242,7 +273,7 @@ public: * As the key input focus mechanism works like a stack, the top most control receives all the key events, and passes on the * unhandled events to the controls below in the stack. A control in the stack will regain key input focus when there are no more * controls above it in the focus stack. - * To query for the conrol which is on top of the focus stack use Dali::Toolkit::KeyInputFocusManager::GetCurrentKeyboardFocusActor(). + * To query for the control which is on top of the focus stack use Dali::Toolkit::KeyInputFocusManager::GetCurrentKeyboardFocusActor(). */ bool HasKeyInputFocus(); @@ -261,7 +292,7 @@ public: * @brief Retrieves the pinch gesture detector of the control. * * @SINCE_1_0.0 - * @return The pinch gesture detector. + * @return The pinch gesture detector * @note Will return an empty handle if the control does not handle the gesture itself. */ PinchGestureDetector GetPinchGestureDetector() const; @@ -270,7 +301,7 @@ public: * @brief Retrieves the pan gesture detector of the control. * * @SINCE_1_0.0 - * @return The pan gesture detector. + * @return The pan gesture detector * @note Will return an empty handle if the control does not handle the gesture itself. */ PanGestureDetector GetPanGestureDetector() const; @@ -279,7 +310,7 @@ public: * @brief Retrieves the tap gesture detector of the control. * * @SINCE_1_0.0 - * @return The tap gesture detector. + * @return The tap gesture detector * @note Will return an empty handle if the control does not handle the gesture itself. */ TapGestureDetector GetTapGestureDetector() const; @@ -288,7 +319,7 @@ public: * @brief Retrieves the long press gesture detector of the control. * * @SINCE_1_0.0 - * @return The long press gesture detector. + * @return The long press gesture detector * @note Will return an empty handle if the control does not handle the gesture itself. */ LongPressGestureDetector GetLongPressGestureDetector() const; @@ -299,14 +330,14 @@ public: * @brief Sets the name of the style to be applied to the control. * * @SINCE_1_0.0 - * @param[in] styleName A string matching a style described in a stylesheet. + * @param[in] styleName A string matching a style described in a stylesheet */ void SetStyleName( const std::string& styleName ); /** * @brief Retrieves the name of the style to be applied to the control (if any). * @SINCE_1_0.0 - * @return A string matching a style or an empty string. + * @return A string matching a style, or an empty string */ const std::string& GetStyleName() const; @@ -318,37 +349,37 @@ public: * @SINCE_1_0.0 * @param[in] color The required background color of the control * - * @note if SetBackgroundImage is called later, this background color is removed. + * @note If SetBackgroundImage is called later, this background color is removed. * * @note The background color fully blends with the actor color. */ void SetBackgroundColor( const Vector4& color ); /** - * @DEPRECATED_1_1.3 - * - * @brief Retrieves the background color of the control. - * + * @brief Clears the background. * @SINCE_1_0.0 - * @return The background color of the control. */ - Vector4 GetBackgroundColor() const DALI_DEPRECATED_API; + void ClearBackground(); + + // Resources /** - * @DEPRECATED_1_2_8, use Property::BACKGROUND instead - * - * @brief Sets an image as the background of the control. + * @brief Query if all resources required by a control are loaded and ready. * - * @SINCE_1_0.0 - * @param[in] image The image to set as the background. + * Most resources are only loaded when the control is placed on stage. + * @SINCE_1_2.60 + * @return true if the resources are loaded and ready, false otherwise */ - void SetBackgroundImage( Image image ) DALI_DEPRECATED_API; + bool IsResourceReady() const; /** - * @brief Clears the background. - * @SINCE_1_0.0 + * @brief Get the loading state of the visual resource. + * + * @SINCE_1_3_5 + * @param[in] index The Property index of the visual + * @return Return the loading status (PREPARING, READY and FAILED) of visual resource */ - void ClearBackground(); + Visual::ResourceStatus GetVisualResourceStatus( const Dali::Property::Index index ); // Signals @@ -362,7 +393,7 @@ public: * The return value of True, indicates that the event should be consumed. * Otherwise the signal will be emitted on the next parent of the actor. * @SINCE_1_0.0 - * @return The signal to connect to. + * @return The signal to connect to * @pre The Control has been initialized. */ KeyEventSignalType& KeyEventSignal(); @@ -377,14 +408,15 @@ public: * The return value of True, indicates that the event should be consumed. * Otherwise the signal will be emitted on the next parent of the actor. * @SINCE_1_0.0 - * @return The signal to connect to. + * @return The signal to connect to * @pre The Control has been initialized. */ KeyInputFocusSignalType& KeyInputFocusGainedSignal(); /** - * @brief This signal is emitted when the control loses Key Input Focus - * which could be due to it being gained by another Control or Actor or just cleared from + * @brief This signal is emitted when the control loses Key Input Focus. + * + * This could be due to it being gained by another Control or Actor or just cleared from * this control as no longer required. * * A callback of the following type may be connected: @@ -394,20 +426,52 @@ public: * The return value of True, indicates that the event should be consumed. * Otherwise the signal will be emitted on the next parent of the actor. * @SINCE_1_0.0 - * @return The signal to connect to. + * @return The signal to connect to * @pre The Control has been initialized. */ KeyInputFocusSignalType& KeyInputFocusLostSignal(); + /** + * @brief This signal is emitted after all resources required by a control are loaded and ready. + * + * Most resources are only loaded when the control is placed on stage. + * + * If resources are shared between ImageViews, they are cached. + * In this case, the ResourceReady signal may be sent before there is an object to connect to. + * To protect against this, IsResourceReady() can be checked first. + * + * @code + * auto newControl = Control::New(); + * newControl.SetResource( resourceUrl ); + * if ( newControl.IsResourceReady() ) + * { + * // do something + * } + * else + * { + * newControl.ResourceReadySignal.Connect( .... ) + * } + * @endcode + * + * A callback of the following type may be connected: + * @code + * void YourCallbackName( Control control ); + * @endcode + * + * @SINCE_1_2.60 + * @return The signal to connect to + * @note A RelayoutRequest is queued by Control before this signal is emitted + */ + ResourceReadySignalType& ResourceReadySignal(); + public: // Intended for control developers /** - * @brief Create an initialised Control. + * @brief Creates an initialized Control. * * @SINCE_1_0.0 - * @param[in] implementation The implementation for this control. - * @return A handle to a newly allocated Dali resource. - * + * @param[in] implementation The implementation for this control + * @return A handle to a newly allocated Dali resource * @note Should NOT be called to create a handle from the implementation. As stated, this allocates a NEW Dali resource. */ explicit Control(Internal::Control& implementation); @@ -417,7 +481,7 @@ public: // Intended for control developers * using an Internal CustomActor pointer. * * @SINCE_1_0.0 - * @param [in] internal A pointer to a newly allocated Dali resource + * @param[in] internal A pointer to a newly allocated Dali resource */ explicit Control(Dali::Internal::CustomActor* internal); @@ -426,11 +490,11 @@ public: // Templates for Deriving Classes /** * @brief Template to allow deriving controls to DownCast handles to deriving handle classes. * - * @tparam T The handle class - * @tparam I The implementation class + * @tparam T The handle class + * @tparam I The implementation class * @SINCE_1_0.0 - * @param[in] handle Handle to an object - * @return Handle to a class T or an uninitialized handle. + * @param[in] handle Handle to an object + * @return Handle to a class T or an uninitialized handle * @see DownCast(BaseHandle) */ template @@ -458,9 +522,9 @@ public: // Templates for Deriving Classes * @brief Template to allow deriving controls to verify whether the Internal::CustomActor* is actually an * implementation of their class. * - * @tparam I The implementation class + * @tparam I The implementation class * @SINCE_1_0.0 - * @param[in] internal Pointer to the Internal::CustomActor + * @param[in] internal Pointer to the Internal::CustomActor */ template DALI_INTERNAL void VerifyCustomActorPointer(Dali::Internal::CustomActor* internal) @@ -482,4 +546,4 @@ public: // Templates for Deriving Classes } // namespace Dali -#endif // __DALI_TOOLKIT_CONTROL_H__ +#endif // DALI_TOOLKIT_CONTROL_H