X-Git-Url: http://review.tizen.org/git/?p=platform%2Fcore%2Fuifw%2Fdali-toolkit.git;a=blobdiff_plain;f=capi%2Fdali-toolkit%2Fpublic-api%2Fcontrols%2Fcontrol.h;h=26baa512ad2f615abc07f6746dc65dcaeb915ff0;hp=a26cf7e066e4e742402d8c79e3d17721e29cd904;hb=86202cf2dbd203142c38e55ed38429d9aa005f75;hpb=3fbada5f2ec43d9b0ea3e63eb54223cf7b3056f4 diff --git a/capi/dali-toolkit/public-api/controls/control.h b/capi/dali-toolkit/public-api/controls/control.h index a26cf7e..26baa51 100644 --- a/capi/dali-toolkit/public-api/controls/control.h +++ b/capi/dali-toolkit/public-api/controls/control.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_CONTROLS_MODULE * @{ */ @@ -36,7 +36,8 @@ namespace Toolkit class ControlImpl; /** - * Control is the base class for all controls. + * @brief Control is the base class for all controls. + * * The implementation of the control must be supplied; see ControlImpl for more details. * @see ControlImpl */ @@ -44,14 +45,29 @@ class Control : public CustomActor, public ConnectionTrackerInterface { public: - // Action Names - static const char* const ACTION_CONTROL_ACTIVATED; - - // Signal Names - static const char* const SIGNAL_KEY_EVENT; + /// @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 + /** @} */ + + /// @name Signals + /** @{ */ + static const char* const SIGNAL_KEY_EVENT; ///< name "key-event" + /** @} */ + + /// @name Actions + /** @{ */ + static const char* const ACTION_CONTROL_ACTIVATED; ///< name "control-activated" + /** @} */ /** - * Describes how a control could be resized. + * @brief Describes how a control could be resized. */ enum SizePolicy { @@ -63,7 +79,7 @@ public: }; /** - * Describes what a control should do when a contained actor/control exceeds the boundary of the control. + * @brief Describes what a control should do when a contained actor/control exceeds the boundary of the control. */ enum ExceedPolicy { @@ -73,7 +89,7 @@ public: }; /** - * Describes the direction to move the keyboard focus towards + * @brief Describes the direction to move the keyboard focus towards. */ enum KeyboardFocusNavigationDirection { @@ -85,30 +101,37 @@ public: // Typedefs - // Key Event + /// @brief Key Event signal type; typedef SignalV2 KeyEventSignalV2; public: // Creation & Destruction /** - * Create a new instance of a Control. + * @brief Create a new instance of a Control. + * * @return A handle to a new Control. */ static Control New(); /** - * Create an uninitialized Control handle. Only derived versions can be instantiated. - * Calling member functions with an uninitialized Dali::Object is not allowed. + * @brief Create an uninitialized Control handle. + * + * Only derived versions can be instantiated. Calling member + * functions with an uninitialized Dali::Object is not allowed. */ Control(); /** - * Copy constructor. Creates another handle that points to the same real object + * @brief Copy constructor. + * + * Creates another handle that points to the same real object + * @param[in] uiControl Handle to copy */ Control(const Control& uiControl); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes do not contain member data. */ virtual ~Control(); @@ -116,34 +139,45 @@ public: // Creation & Destruction public: // operators /** - * Assignment operator. Changes this handle to point to another real object + * @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: /** - * 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. + * @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 ); /** - * Retrieve the Control implementation. + * @brief Retrieve the Control implementation. + * * @return The implementation. */ ControlImpl& GetImplementation(); /** - * Retrieve the Control implementation. + * @brief Retrieve the Control implementation. + * * @return The implementation. */ const ControlImpl& GetImplementation() const; + // Size Negotiation + /** - * Sets the size policies for the width and height dimensions. + * @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. @@ -151,7 +185,7 @@ public: void SetSizePolicy( SizePolicy widthPolicy, SizePolicy heightPolicy ); /** - * Retrieves the size policies for the width and height dimensions. + * @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. @@ -159,35 +193,35 @@ public: void GetSizePolicy( SizePolicy& widthPolicy, SizePolicy& heightPolicy ) const; /** - * Sets the minimum size for the control. + * @brief Sets the minimum size for the control. * * @param[in] size The minimum size. */ void SetMinimumSize( const Vector3& size ); /** - * Retrieves the minimum size. + * @brief Retrieves the minimum size. * * @return The minimum size. */ const Vector3& GetMinimumSize() const; /** - * Sets the maximum size + * @brief Sets the maximum size. * * @param[in] size The maximum size. */ void SetMaximumSize( const Vector3& size ); /** - * Retrieves the maximum size. + * @brief Retrieves the maximum size. * * @return The maximum size. */ const Vector3& GetMaximumSize() const; /** - * Works out the natural size. + * @brief Works out the natural size. * * Natural size is the control's size with any restriction. * @@ -196,7 +230,7 @@ public: Vector3 GetNaturalSize(); /** - * Works out the control's height for a given width. + * @brief Works out the control's height for a given width. * * @param[in] width The control's width. * @@ -205,7 +239,7 @@ public: float GetHeightForWidth( float width ); /** - * Works out the control's width for a given height. + * @brief Works out the control's width for a given height. * * @param[in] height The control's height. * @@ -213,8 +247,12 @@ public: */ float GetWidthForHeight( float height ); + // Key Input + /** - * This sets the control to receive key events. The key event can originate from a virtual or physical keyboard. + * @brief This sets the control to receive key events. + * + * The key event can originate from a virtual or physical keyboard. * @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. @@ -222,7 +260,8 @@ public: void SetKeyInputFocus(); /** - * Quries whether the control has key input focus. + * @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. * 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 @@ -230,21 +269,94 @@ public: * 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 */ bool HasKeyInputFocus(); /** - * Once an actor is Set to receive key input focus this function is called to stop it receiving key events. + * @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. * @pre The Actor has been initialized. */ void ClearKeyInputFocus(); -//signals -public: + // Gesture Detection + + /** + * @brief Retrieves the pinch gesture detector of the control. + * + * @return The pinch gesture detector. + * @pre Pinch detection should have been enabled in the control. + */ + PinchGestureDetector GetPinchGestureDetector() const; /** - * This signal is emitted when key event is received + * @brief Retrieves the pan gesture detector of the control. + * + * @return The pan gesture detector. + * @pre Pan detection should have been enabled in the control. + */ + PanGestureDetector GetPanGestureDetector() const; + + /** + * @brief Retrieves the tap gesture detector of the control. + * + * @return The tap gesture detector. + * @pre Tap detection should have been enabled in the control. + */ + TapGestureDetector GetTapGestureDetector() const; + + /** + * @brief Retrieves the long press gesture detector of the control. + * + * @return The long press gesture detector. + * @pre Long press detection should have been enabled in the control. + */ + LongPressGestureDetector GetLongPressGestureDetector() const; + + // Background + + /** + * @brief Sets the background color of the control. + * + * @param[in] color The required background color of the control + */ + void SetBackgroundColor( const Vector4& color ); + + /** + * @brief Retrieves the background color of the control. + * + * @return The background color of the control. + */ + Vector4 GetBackgroundColor() const; + + /** + * @brief Sets an image as the background of the control. + * + * The color of this image is blended with the background color @see SetBackgroundColor + * + * @param[in] image The image to set as the background. + */ + void SetBackground( 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 + + /** + * @brief This signal is emitted when key event is received. + * * A callback of the following type may be connected: * @code * bool YourCallbackName(Control control, const KeyEvent& event); @@ -276,15 +388,17 @@ protected: public: // Not intended for application developers /** - * Create an initialised Control. + * @brief Create an initialised Control. + * * @param[in] implementation The implementation for this control. * @return A handle to a newly allocated Dali resource. */ Control(ControlImpl& implementation); /** - * This constructor is used by CustomActor within Dali core to create additional Control handles + * @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 */ Control(Dali::Internal::CustomActor* internal); @@ -292,7 +406,8 @@ public: // Not intended for application developers public: // Templates for Deriving Classes /** - * Template to allow deriving controls to DownCast handles to deriving handle 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 @@ -321,8 +436,9 @@ public: // Templates for Deriving Classes } /** - * Template to allow deriving controls to verify whether the Internal::CustomActor* is actually an + * @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 */