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=35587f96b64fc8f634e54af07a5343846574aa04;hp=01c1c75d75243c646deee4f4024cd4762c8f152f;hb=07bbc876b9b069903dd4ed86c9dd5f2f66fc3b86;hpb=1b1e10a3f4e486553200d8ddeb57d953c2284579 diff --git a/dali-toolkit/public-api/controls/control.h b/dali-toolkit/public-api/controls/control.h index 01c1c75..35587f9 100644 --- a/dali-toolkit/public-api/controls/control.h +++ b/dali-toolkit/public-api/controls/control.h @@ -2,7 +2,7 @@ #define __DALI_TOOLKIT_CONTROL_H__ /* - * Copyright (c) 2014 Samsung Electronics Co., Ltd. + * Copyright (c) 2015 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. @@ -40,6 +40,10 @@ namespace Internal { class Control; } +/** + * @addtogroup dali-toolkit-controls + * @{ + */ /** * @brief Control is the base class for all controls. @@ -48,65 +52,61 @@ class Control; * @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 | + * |------------------------|-----------------------------------------------------| + * | key-event | @ref KeyEventSignal() | + * | key-input-focus-gained | @ref KeyInputFocusGainedSignal() | + * | key-input-focus-lost | @ref KeyInputFocusLostSignal() | + * | tapped | @ref GetTapGestureDetector().DetectedSignal() | + * | panned | @ref GetPanGestureDetector().DetectedSignal() | + * | pinched | @ref GetPinchGestureDetector().DetectedSignal() | + * | long-pressed | @ref GetLongPressGestureDetector().DetectedSignal() | * * Actions - * | %Action Name | %Control method called | - * |-------------------|-----------------------------------------------------| - * | control-activated | %OnActivated() | + * | %Action Name | %Control method called | + * |-------------------------|----------------------------------------------------| + * | accessibility-activated | %OnAccessibilityActivated() | */ class DALI_IMPORT_API Control : public CustomActor { public: - /// @name Properties - /** @{ */ - static const Property::Index PROPERTY_BACKGROUND_COLOR; ///< name "background-color", @see SetBackgroundColor, type VECTOR4 - static const Property::Index PROPERTY_BACKGROUND; ///< name "background", @see SetBackground, type MAP - static const Property::Index PROPERTY_WIDTH_POLICY; ///< name "width-policy", @see SetSizePolicy, type STRING - static const Property::Index PROPERTY_HEIGHT_POLICY; ///< name "height-policy", @see SetSizePolicy, type STRING - static const Property::Index PROPERTY_MINIMUM_SIZE; ///< name "minimum-size", @see SetMinimumSize, type VECTOR3 - static const Property::Index PROPERTY_MAXIMUM_SIZE; ///< name "maximum-size", @see SetMaximumSize, type VECTOR3 - static const Property::Index PROPERTY_KEY_INPUT_FOCUS; ///< name "key-input-focus", @see SetKeyInputFocus, type BOOLEAN - /** @} */ - /** - * @brief Describes how a control could be resized. + * @brief The start and end property ranges for control. */ - enum SizePolicy + enum PropertyRange { - 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. + 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. }; /** - * @brief Describes what a control should do when a contained actor/control exceeds the boundary of the control. + * @brief An enumeration of properties belonging to the Control class. */ - enum ExceedPolicy + struct Property { - Crop, ///< Control's contents will be cropped. - Shrink, ///< Control's contents will be shrunk. - Scroll ///< Control's contents will be added to a scroll. + enum + { + STYLE_NAME = PROPERTY_START_INDEX, ///< name "style-name", @see SetStyleName, type std::string + BACKGROUND_COLOR, ///< name "background-color", @see SetBackgroundColor, type Vector4 + BACKGROUND_IMAGE, ///< name "background-image", @see SetBackgroundImage, type Map + KEY_INPUT_FOCUS, ///< name "key-input-focus", @see SetKeyInputFocus, type bool + }; }; /** * @brief Describes the direction to move the keyboard focus towards. */ - 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 + enum Direction + { + 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 + }; }; // Typedefs @@ -114,6 +114,9 @@ public: /// @brief Key Event signal type; typedef Signal KeyEventSignalType; + /// @brief Key InputFocusType signal type; + typedef Signal KeyInputFocusSignalType; + public: // Creation & Destruction /** @@ -170,93 +173,6 @@ public: */ 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. - * - * @param[in] size The maximum size. - */ - void SetMaximumSize( const Vector3& size ); - - /** - * @brief Retrieves the maximum size. - * - * @return The maximum size. - */ - const Vector3& GetMaximumSize() const; - - /** - * @brief Works out the natural size. - * - * Natural size is the control's size with any restriction. - * - * @return The natural size. - */ - Vector3 GetNaturalSize(); - - /** - * @brief Works out the control's height for a given width. - * - * @param[in] width The control's width. - * - * @return The control's height for the given width. - */ - float GetHeightForWidth( float width ); - - /** - * @brief Works out the control's width for a given height. - * - * @param[in] height The control's height. - * - * @return The control's width for the given height. - */ - float GetWidthForHeight( float height ); - // Key Input /** @@ -325,6 +241,22 @@ public: */ LongPressGestureDetector GetLongPressGestureDetector() const; + // Styling + + /** + * @brief Sets the name of the style to be applied to the control. + * + * @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). + * + * @return A string matching a style or an empty string. + */ + const std::string& GetStyleName() const; + // Background /** @@ -350,20 +282,13 @@ public: * * @param[in] image The image to set as the background. */ - void SetBackground( Image image ); + void SetBackgroundImage( Image image ); /** * @brief Clears the background. */ void ClearBackground(); - /** - * @brief Retrieves the actor used as the background for this control. - * - * @return The actor that used as the background for this control. - */ - Actor GetBackgroundActor() const; - // Signals /** @@ -373,13 +298,43 @@ 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. * @pre The Control has been initialized. * @return The signal to connect to. */ KeyEventSignalType& KeyEventSignal(); + /** + * @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. + * @pre The Control has been initialized. + * @return The signal to connect to. + */ + 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 + * 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. + * @pre The Control has been initialized. + * @return The signal to connect to. + */ + KeyInputFocusSignalType& KeyInputFocusLostSignal(); + public: // Intended for control developers /** @@ -452,6 +407,9 @@ public: // Templates for Deriving Classes }; +/** + * @} + */ } // namespace Toolkit } // namespace Dali