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=76f646ff2f950afbab031aca9448a813fdacbf23;hp=4ff673e73de08a55614e6ebc188bbe11566d9324;hb=321e8978d3d5786c2012f715106882049d8c4269;hpb=b458e407eba11c73f38da68bce8e967a30ea03e2 diff --git a/dali-toolkit/public-api/controls/control.h b/dali-toolkit/public-api/controls/control.h index 4ff673e..7720d13 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) 2014 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. @@ -19,259 +19,229 @@ */ // EXTERNAL INCLUDES +#include #include -#include #include #include #include #include -#include -#include + +// INTERNAL INCLUDES +#include namespace Dali { - namespace Toolkit { - //Forward declarations. namespace Internal { class Control; } +/** + * @addtogroup dali_toolkit_controls + * @{ + */ /** * @brief Control is the base class for all controls. * * The implementation of the control must be supplied; see Internal::Control for more details. + * @SINCE_1_0.0 * @see Internal::Control * * Signals - * | %Signal Name | Method | - * |-------------------|-----------------------------------------------------| - * | key-event | @ref KeyEventSignal() | - * | tapped | @ref GetTapGestureDetector().DetectedSignal() | - * | panned | @ref GetPanGestureDetector().DetectedSignal() | - * | pinched | @ref GetPinchGestureDetector().DetectedSignal() | - * | long-pressed | @ref GetLongPressGestureDetector().DetectedSignal() | + * | %Signal Name | Method | + * |------------------------|-----------------------------------------------------| + * | keyEvent | @ref KeyEventSignal() | + * | keyInputFocusGained | @ref KeyInputFocusGainedSignal() | + * | keyInputFocusLost | @ref KeyInputFocusLostSignal() | + * | resourceReady | @ref ResourceReadySignal() | + * | tapped | @ref GetTapGestureDetector().DetectedSignal() | + * | panned | @ref GetPanGestureDetector().DetectedSignal() | + * | pinched | @ref GetPinchGestureDetector().DetectedSignal() | + * | longPressed | @ref GetLongPressGestureDetector().DetectedSignal() | * * Actions - * | %Action Name | %Control method called | - * |-------------------|-----------------------------------------------------| - * | control-activated | %OnActivated() | + * | %Action Name | %Control method called | + * |------------------------|----------------------------------------------------| + * | 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 { - PROPERTY_START_INDEX = PROPERTY_REGISTRATION_START_INDEX, ///< Start index is used by the property registration macro. - CONTROL_PROPERTY_START_INDEX = PROPERTY_START_INDEX, ///< Start index of Control properties. - CONTROL_PROPERTY_END_INDEX = CONTROL_PROPERTY_START_INDEX + 1000 ///< Reserving 1000 property indices. + PROPERTY_START_INDEX = PROPERTY_REGISTRATION_START_INDEX, ///< Start index is used by the property registration macro. @SINCE_1_0.0 + CONTROL_PROPERTY_START_INDEX = PROPERTY_START_INDEX, ///< Start index of Control properties. @SINCE_1_0.0 + CONTROL_PROPERTY_END_INDEX = CONTROL_PROPERTY_START_INDEX + 1000 ///< Reserving 1000 property indices. @SINCE_1_0.0 }; /** - * @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 Enumeration for the instance of properties belonging to the Control class. + * @SINCE_1_0.0 + */ enum { - BACKGROUND_COLOR = PROPERTY_START_INDEX, ///< name "background-color", @see SetBackgroundColor, type VECTOR4 - BACKGROUND, ///< name "background", @see SetBackground, type MAP - WIDTH_POLICY, ///< name "width-policy", @see SetSizePolicy, type STRING - HEIGHT_POLICY, ///< name "height-policy", @see SetSizePolicy, type STRING - MINIMUM_SIZE, ///< name "minimum-size", @see SetMinimumSize, type VECTOR3 - MAXIMUM_SIZE, ///< name "maximum-size", @see SetMaximumSize, type VECTOR3 - KEY_INPUT_FOCUS, ///< name "key-input-focus", @see SetKeyInputFocus, type BOOLEAN + /** + * @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 + */ + STYLE_NAME = PROPERTY_START_INDEX, + + /** + * @brief Receives key events to the control. + * @details Name "keyInputFocus", type Property::BOOLEAN. + * @see Toolkit::Control::SetKeyInputFocus() + * @SINCE_1_0.0 + */ + KEY_INPUT_FOCUS, + + /** + * @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, + + /** + * @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. + */ + MARGIN, + + /** + * @brief The inner space of the control. + * @details Name "padding", type Property::EXTENTS. + * @SINCE_1_2.62 + */ + PADDING }; }; /** - * @brief Describes how a control could be resized. - */ - enum SizePolicy - { - Fixed, ///< Size can't grow or shrink. - Minimum, ///< Size can grow but shrink up to a minimum level. - Maximum, ///< Size can shrink but grow up to a maximum value. - Range, ///< Size can grow or shrink between a minimum and a maximum values. - Flexible, ///< Size can grow or shrink with no limits. - }; - - /** - * @brief Describes what a control should do when a contained actor/control exceeds the boundary of the control. - */ - enum ExceedPolicy - { - Crop, ///< Control's contents will be cropped. - Shrink, ///< Control's contents will be shrunk. - Scroll ///< Control's contents will be added to a scroll. - }; - - /** * @brief Describes the direction to move the keyboard focus towards. + * @SINCE_1_0.0 */ - enum KeyboardFocusNavigationDirection + struct KeyboardFocus { - Left, ///< Move keyboard focus towards the left direction - Right, ///< Move keyboard focus towards the right direction - Up, ///< Move keyboard focus towards the up direction - Down ///< Move keyboard focus towards the down direction + /** + * @brief Keyboard focus direction. + * @SINCE_1_0.0 + */ + enum Direction + { + LEFT, ///< Move keyboard focus towards the left direction @SINCE_1_0.0 + RIGHT, ///< Move keyboard focus towards the right direction @SINCE_1_0.0 + UP, ///< Move keyboard focus towards the up direction @SINCE_1_0.0 + DOWN, ///< Move keyboard focus towards the down direction @SINCE_1_0.0 + PAGE_UP, ///< Move keyboard focus towards the previous page direction @SINCE_1_2.14 + PAGE_DOWN ///< Move keyboard focus towards the next page direction @SINCE_1_2.14 + }; }; // Typedefs - /// @brief Key Event signal type; - typedef Signal KeyEventSignalType; + /// @brief Key Event signal type. @SINCE_1_0.0 + typedef Signal KeyEventSignalType; -public: // Creation & Destruction + /// @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. * - * @return A handle to a new Control. + * @SINCE_1_0.0 + * @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. + * @SINCE_1_0.0 */ Control(); /** * @brief Copy constructor. * - * Creates another handle that points to the same real object + * Creates another handle that points to the same real object. + * @SINCE_1_0.0 * @param[in] uiControl Handle to copy */ Control(const Control& uiControl); /** - * @brief Dali::Control is intended as a base class - * - * This is non-virtual since derived Handle types must not contain data or virtual methods. - */ - ~Control(); - -public: // operators - - /** - * @brief Assignment operator. - * - * Changes this handle to point to another real object - * @param[in] handle Object to assign this to - * @return reference to this - */ - Control& operator=( const Control& handle ); - -public: - - /** - * @brief Downcast an Object handle to Control. - * - * If handle points to a Control the downcast produces valid - * handle. If not the returned handle is left uninitialized. - * - * @param[in] handle Handle to an object - * @return handle to a Control or an uninitialized handle - */ - static Control DownCast( BaseHandle handle ); - - /** - * @brief Retrieve the Control implementation. - * - * @return The implementation. - */ - Internal::Control& GetImplementation(); - - /** - * @brief Retrieve the Control implementation. - * - * @return The implementation. - */ - const Internal::Control& GetImplementation() const; - - // Size Negotiation - - /** - * @brief Sets the size policies for the width and height dimensions. - * - * @param[in] widthPolicy Size policy for the width dimension. - * @param[in] heightPolicy Size policy for the height dimension. - */ - void SetSizePolicy( SizePolicy widthPolicy, SizePolicy heightPolicy ); - - /** - * @brief Retrieves the size policies for the width and height dimensions. - * - * @param[out] widthPolicy Width's size policy. - * @param[out] heightPolicy Height's size policy. - */ - void GetSizePolicy( SizePolicy& widthPolicy, SizePolicy& heightPolicy ) const; - - /** - * @brief Sets the minimum size for the control. - * - * @param[in] size The minimum size. - */ - void SetMinimumSize( const Vector3& size ); - - /** - * @brief Retrieves the minimum size. - * - * @return The minimum size. - */ - const Vector3& GetMinimumSize() const; - - /** - * @brief Sets the maximum size. + * @brief Move constructor. * - * @param[in] size The maximum size. + * @SINCE_1_9.23 + * @param[in] rhs Handle to move */ - void SetMaximumSize( const Vector3& size ); + Control(Control&& rhs); /** - * @brief Retrieves the maximum size. + * @brief Dali::Control is intended as a base class. * - * @return The maximum size. + * This is non-virtual since derived Handle types must not contain data or virtual methods. + * @SINCE_1_0.0 */ - const Vector3& GetMaximumSize() const; + ~Control(); +public: // operators /** - * @brief Works out the natural size. + * @brief Copy assignment operator. * - * Natural size is the control's size with any restriction. - * - * @return The natural size. + * 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 */ - Vector3 GetNaturalSize(); + Control& operator=(const Control& handle); /** - * @brief Works out the control's height for a given width. + * @brief Move assignment operator. * - * @param[in] width The control's width. - * - * @return The control's height for the given width. + * @SINCE_1_9.23 + * @param[in] rhs Object to assign this to + * @return Reference to this */ - float GetHeightForWidth( float width ); + Control& operator=(Control&& rhs); +public: /** - * @brief Works out the control's width for a given height. + * @brief Downcasts a handle to Control handle. * - * @param[in] height The control's height. + * If handle points to a Control, the downcast produces valid handle. + * If not, the returned handle is left uninitialized. * - * @return The control's width for the given height. + * @SINCE_1_0.0 + * @param[in] handle Handle to an object + * @return A handle to a Control or an uninitialized handle */ - float GetWidthForHeight( float height ); + static Control DownCast(BaseHandle handle); // Key Input @@ -279,23 +249,24 @@ public: * @brief This sets the control to receive key events. * * The key event can originate from a virtual or physical keyboard. + * @SINCE_1_0.0 * @pre The Control has been initialized. * @pre The Control should be on the stage before setting keyboard focus. - * @return True if the control has foucs, False otherwise. */ void SetKeyInputFocus(); /** * @brief Quries whether the control has key input focus. * - * Note: The control can be set to have the focus and still not receive all the key events if another control has over ridden it. + * @SINCE_1_0.0 + * @return true if this control has keyboard input focus + * @pre The Control has been initialized. + * @pre The Control should be on the stage before setting keyboard focus. + * @note The control can be set to have the focus and still not receive all the key events if another control has over ridden it. * 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() - * @pre The Control has been initialized. - * @pre The Control should be on the stage before setting keyboard focus. - * @return true if this control has keyboard input focus + * To query for the control which is on top of the focus stack use Dali::Toolkit::KeyInputFocusManager::GetCurrentKeyboardFocusActor(). */ bool HasKeyInputFocus(); @@ -303,6 +274,7 @@ public: * @brief Once an actor is Set to receive key input focus this function is called to stop it receiving key events. * * A check is performed to ensure it was previously set, if this check fails then nothing is done. + * @SINCE_1_0.0 * @pre The Actor has been initialized. */ void ClearKeyInputFocus(); @@ -312,7 +284,8 @@ public: /** * @brief Retrieves the pinch gesture detector of the control. * - * @return The pinch gesture detector. + * @SINCE_1_0.0 + * @return The pinch gesture detector * @note Will return an empty handle if the control does not handle the gesture itself. */ PinchGestureDetector GetPinchGestureDetector() const; @@ -320,7 +293,8 @@ public: /** * @brief Retrieves the pan gesture detector of the control. * - * @return The pan gesture detector. + * @SINCE_1_0.0 + * @return The pan gesture detector * @note Will return an empty handle if the control does not handle the gesture itself. */ PanGestureDetector GetPanGestureDetector() const; @@ -328,7 +302,8 @@ public: /** * @brief Retrieves the tap gesture detector of the control. * - * @return The tap gesture detector. + * @SINCE_1_0.0 + * @return The tap gesture detector * @note Will return an empty handle if the control does not handle the gesture itself. */ TapGestureDetector GetTapGestureDetector() const; @@ -336,49 +311,68 @@ public: /** * @brief Retrieves the long press gesture detector of the control. * - * @return The long press gesture detector. + * @SINCE_1_0.0 + * @return The long press gesture detector * @note Will return an empty handle if the control does not handle the gesture itself. */ LongPressGestureDetector GetLongPressGestureDetector() const; - // Background + // Styling /** - * @brief Sets the background color of the control. - * - * @param[in] color The required background color of the control + * @brief Sets the name of the style to be applied to the control. * - * @note The background color fully blends with the actor color. + * @SINCE_1_0.0 + * @param[in] styleName A string matching a style described in a stylesheet */ - void SetBackgroundColor( const Vector4& color ); + void SetStyleName(const std::string& styleName); /** - * @brief Retrieves the background color of the control. - * - * @return The background color of the control. + * @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 */ - Vector4 GetBackgroundColor() const; + const std::string& GetStyleName() const; + + // Background /** - * @brief Sets an image as the background of the control. + * @brief Sets the background color of the control. + * + * @SINCE_1_0.0 + * @param[in] color The required background color of the control * - * The color of this image is blended with the background color @see SetBackgroundColor + * @note If SetBackgroundImage is called later, this background color is removed. * - * @param[in] image The image to set as the background. + * @note The background color fully blends with the actor color. */ - void SetBackground( Image image ); + void SetBackgroundColor(const Vector4& color); /** * @brief Clears the background. + * @SINCE_1_0.0 */ void ClearBackground(); + // Resources + + /** + * @brief Query if all resources required by a control are loaded and ready. + * + * 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 + */ + bool IsResourceReady() const; + /** - * @brief Retrieves the actor used as the background for this control. + * @brief Get the loading state of the visual resource. * - * @return The actor that used as the background for this control. + * @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 */ - Actor GetBackgroundActor() const; + Visual::ResourceStatus GetVisualResourceStatus(const Dali::Property::Index index); // Signals @@ -389,21 +383,86 @@ public: * @code * bool YourCallbackName(Control control, const KeyEvent& event); * @endcode - * The return value of True, indicates that the touch event should be consumed. - * Otherwise the signal will be emitted on the next sensitive parent of the actor. + * 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 * @pre The Control has been initialized. - * @return The signal to connect to. */ KeyEventSignalType& KeyEventSignal(); -public: // Intended for control developers + /** + * @brief This signal is emitted when the control gets Key Input Focus. + * + * A callback of the following type may be connected: + * @code + * bool YourCallbackName( Control control ); + * @endcode + * 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 + * @pre The Control has been initialized. + */ + KeyInputFocusSignalType& KeyInputFocusGainedSignal(); /** - * @brief Create an initialised Control. + * @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: + * @code + * bool YourCallbackName( Control control ); + * @endcode + * 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 + * @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 * - * @param[in] implementation The implementation for this control. - * @return A handle to a newly allocated Dali resource. + * 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 Creates an initialized Control. + * + * @SINCE_1_0.0 + * @param[in] implementation The implementation for this control * @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); @@ -412,34 +471,35 @@ public: // Intended for control developers * @brief This constructor is used by CustomActor within Dali core to create additional Control handles * using an Internal CustomActor pointer. * - * @param [in] internal A pointer to a newly allocated Dali resource + * @SINCE_1_0.0 + * @param[in] internal A pointer to a newly allocated Dali resource */ explicit Control(Dali::Internal::CustomActor* internal); 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 - * @param[in] handle Handle to an object - * @return Handle to a class T or an uninitialized handle. + * @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 * @see DownCast(BaseHandle) */ template - DALI_INTERNAL static T DownCast( BaseHandle handle ) + DALI_INTERNAL static T DownCast(BaseHandle handle) { T result; - CustomActor custom = Dali::CustomActor::DownCast( handle ); - if ( custom ) + CustomActor custom = Dali::CustomActor::DownCast(handle); + if(custom) { CustomActorImpl& customImpl = custom.GetImplementation(); I* impl = dynamic_cast(&customImpl); - if (impl) + if(impl) { result = T(customImpl.GetOwner()); } @@ -452,24 +512,27 @@ 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 - * @param[in] internal Pointer to the Internal::CustomActor + * @tparam I The implementation class + * @SINCE_1_0.0 + * @param[in] internal Pointer to the Internal::CustomActor */ template DALI_INTERNAL void VerifyCustomActorPointer(Dali::Internal::CustomActor* internal) { // Can have a NULL pointer so we only need to check if the internal implementation is our class // when there is a value. - if (internal) + if(internal) { DALI_ASSERT_DEBUG(dynamic_cast(&CustomActor(internal).GetImplementation())); } } - }; +/** + * @} + */ } // namespace Toolkit } // namespace Dali -#endif // __DALI_TOOLKIT_CONTROL_H__ +#endif // DALI_TOOLKIT_CONTROL_H