From aa19ec23c1186efea1585ed2dc19587714063e39 Mon Sep 17 00:00:00 2001 From: David Steele Date: Fri, 14 Mar 2014 11:21:55 +0000 Subject: [PATCH] Updated CAPI documentation style Change-Id: I522f9faea68c194e8ab1ef07355e191c1c3d776b Signed-off-by: David Steele --- .../public-api/controls/alignment/alignment.h | 88 +++-- .../controls/bubble-effect/bubble-emitter.h | 59 ++- .../public-api/controls/buttons/button.h | 48 ++- .../public-api/controls/buttons/push-button.h | 97 ++--- .../public-api/controls/cluster/cluster-style.h | 53 +-- .../public-api/controls/control-impl.h | 231 ++++++++---- capi/dali-toolkit/public-api/controls/control.h | 97 +++-- .../default-controls/push-button-factory.h | 17 +- .../controls/default-controls/solid-color-actor.h | 5 +- .../controls/image-view/masked-image-view.h | 109 ++++-- .../dali-toolkit/public-api/controls/popup/popup.h | 77 ++-- .../controls/scrollable/item-view/grid-layout.h | 80 ++-- .../controls/scrollable/item-view/item-factory.h | 13 +- .../controls/scrollable/item-view/item-layout.h | 125 ++++--- .../controls/scrollable/item-view/item-view.h | 137 ++++--- .../scroll-view/scroll-view-cube-effect.h | 27 +- .../scroll-view/scroll-view-custom-effect.h | 153 +++++--- .../scrollable/scroll-view/scroll-view-effect.h | 27 +- .../scroll-view/scroll-view-page-spiral-effect.h | 21 +- .../scroll-view/scroll-view-slide-effect.h | 49 ++- .../scroll-view/scroll-view-twist-effect.h | 44 ++- .../controls/scrollable/scroll-view/scroll-view.h | 412 ++++++++++++--------- .../public-api/controls/scrollable/scrollable.h | 113 +++--- .../controls/super-blur-view/super-blur-view.h | 53 ++- .../public-api/controls/text-input/text-input.h | 205 ++++++---- .../public-api/controls/text-view/text-view.h | 181 +++++---- capi/dali-toolkit/public-api/enums.h | 16 +- .../public-api/factory/localized-control-factory.h | 26 +- .../public-api/focus-manager/focus-manager.h | 200 ++++++---- .../focus-manager/keyboard-focus-manager.h | 145 +++++--- .../public-api/markup-processor/markup-processor.h | 48 ++- .../public-api/shader-effects/dissolve-effect.h | 21 +- .../shader-effects/image-region-effect.h | 25 +- .../public-api/shader-effects/iris-effect.h | 30 +- .../public-api/shader-effects/mask-effect.h | 13 +- .../shader-effects/nine-patch-mask-effect.h | 11 +- .../shader-effects/page-turn-book-spine-effect.h | 32 +- .../public-api/shader-effects/page-turn-effect.h | 41 +- .../public-api/shader-effects/ripple-effect.h | 30 +- .../public-api/shader-effects/ripple2d-effect.h | 24 +- .../public-api/shader-effects/swirl-effect.h | 31 +- capi/dali_toolkit_doc.h | 304 +++++++++++++++ 42 files changed, 2359 insertions(+), 1159 deletions(-) create mode 100644 capi/dali_toolkit_doc.h diff --git a/capi/dali-toolkit/public-api/controls/alignment/alignment.h b/capi/dali-toolkit/public-api/controls/alignment/alignment.h index 6c1ebb8..b1ebcd3 100644 --- a/capi/dali-toolkit/public-api/controls/alignment/alignment.h +++ b/capi/dali-toolkit/public-api/controls/alignment/alignment.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_ALIGNMENT_MODULE * @{ */ @@ -37,7 +37,7 @@ class Alignment; } /** - * Alignment is a container which provides an easy way to align other actors inside its boundary. + * @brief Alignment is a container which provides an easy way to align other actors inside its boundary. * * Additionaly it provides a scaling property to resize the contained actors @see Scaling. * @note The use of scaling property will override all constraints applied to actors. @@ -49,7 +49,7 @@ class Alignment : public Control { public: /** - * Different types of alignment. + * @brief Different types of alignment. */ enum Type { @@ -62,7 +62,7 @@ public: }; /** - * Scaling determines how actors are scaled, to match the alignment's boundary. + * @brief Scaling determines how actors are scaled, to match the alignment's boundary. */ enum Scaling { @@ -74,8 +74,14 @@ public: ShrinkToFitKeepAspect, ///< If added actors are larger than the alignment's boundary it will be shrunk down to fit. Aspect ratio is maintained }; + /** + * @brief Structure describing the padding values. + */ struct Padding { + /** + * @brief Constructor + */ Padding() : left( 0.f ), right( 0.f ), @@ -84,6 +90,14 @@ public: { } + /** + * @brief Constructor + * + * @param[in] l Left padding + * @param[in] r Right padding + * @param[in] t Top padding + * @param[in] b Bottom padding + */ Padding( float l, float r, float t, float b ) : left( l ), right( r ), @@ -92,20 +106,22 @@ public: { } - float left; - float right; - float top; - float bottom; + float left; ///< The left padding + float right; ///< The right padding + float top; ///< The top padding + float bottom; ///< The bottom padding }; /** - * Create an Alignment handle; this can be initialised with Alignment::New() + * @brief Create an Alignment handle; this can be initialised with Alignment::New(). + * * Calling member functions with an uninitialised handle is not allowed. */ Alignment(); /** - * Creates an alignment control. + * @brief Creates an alignment control. + * * @param [in] horizontal Specifies how to align actors horizontally. Could be HorizontalLeft, HorizontalCenter or HorizontalRight. By default HorizontalCenter. * @param [in] vertical Specifies how to align actors vertically. Could be VerticalTop, VerticalCenter or VerticalBottom. By default VerticalCenter. * @return A handle to the Alignment control. @@ -113,79 +129,103 @@ public: static Alignment New( Type horizontal = HorizontalCenter, Type vertical = VerticalCenter ); /** - * 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] alignment Object to copy. */ Alignment(const Alignment& alignment); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~Alignment(); /** - * Downcast an Object handle to Alignment. If handle points to a Alignment the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to Alignment. + * + * If handle points to a Alignment the downcast produces valid + * handle. If not the returned handle is left uninitialized. + * * @param[in] handle Handle to an object * @return handle to a Alignment or an uninitialized handle */ static Alignment DownCast( BaseHandle handle ); /** - * Sets the new alignment. By default ( HorizontalCenter | VerticalCenter ). + * @brief Sets the new alignment. By default ( HorizontalCenter | VerticalCenter ). * @param [in] type The new alignment option. */ void SetAlignmentType( Type type ); /** - * Get the current alignment combined into a single value. - * The values can be tested by using the & operator - * and the desired flag. e.g. if (GetAlignmentType() & HorizontalCentre) ... + * @brief Get the current alignment combined into a single value. + * + * The values can be tested by using the & operator and the desired + * flag. e.g. + * @code + * if (GetAlignmentType() & HorizontalCentre) + * { + * ... + * } + * @endcode + * * @return the alignment value. */ Type GetAlignmentType() const; /** - * Sets how added actors scale to fit the alignment's boundary. + * @brief Sets how added actors scale to fit the alignment's boundary. + * * @see Scaling. * @param[in] scaling The scaling property. */ void SetScaling( Scaling scaling ); /** - * Retrieves the scaling property. + * @brief Retrieves the scaling property. + * * @see Scaling. * @return The scaling. */ Scaling GetScaling() const; /** - * Set a padding value. + * @brief Set a padding value. * * @param [in] padding The left, right, top, bottom padding values. */ void SetPadding( const Padding& padding ); /** + * @brief Get the padding values. + * * @return The left, right, top, bottom padding values. */ const Padding& GetPadding() const; /** - * 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] alignment Object to copy + * @return A reference to this */ Alignment& operator=(const Alignment& alignment); public: // Not intended for application developers /** - * Creates a handle using the Toolkit::Internal implementation. + * @brief Creates a handle using the Toolkit::Internal implementation. + * * @param[in] implementation The Control implementation. */ Alignment( Internal::Alignment& implementation ); /** - * Allows the creation of this Control from an Internal::CustomActor pointer. + * @brief Allows the creation of this Control from an Internal::CustomActor pointer. + * * @param[in] internal A pointer to the internal CustomActor. */ Alignment( Dali::Internal::CustomActor* internal ); diff --git a/capi/dali-toolkit/public-api/controls/bubble-effect/bubble-emitter.h b/capi/dali-toolkit/public-api/controls/bubble-effect/bubble-emitter.h index f292f44..81c0f8e 100644 --- a/capi/dali-toolkit/public-api/controls/bubble-effect/bubble-emitter.h +++ b/capi/dali-toolkit/public-api/controls/bubble-effect/bubble-emitter.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_BUBBLE_EFFECT_MODULE * @{ */ @@ -35,13 +35,13 @@ namespace Toolkit namespace Internal DALI_INTERNAL { /** - * BubbleEmitter implementation class + * @brief BubbleEmitter implementation class. */ class BubbleEmitter; } /** - * BubbleEmitter is used to display lots of moving bubbles on the stage. + * @brief BubbleEmitter is used to display lots of moving bubbles on the stage. * * This is done by applying BubbleEffect to multiple specifically created meshActors. */ @@ -50,17 +50,18 @@ class BubbleEmitter : public Control public: /** - * Create an empty BubbleEmitter handle + * @brief Create an empty BubbleEmitter handle. */ BubbleEmitter(); /** - * Virtual destructor. + * @brief Virtual destructor. */ ~BubbleEmitter(); /** - * Create an initialized BubbleEmitter + * @brief Create an initialized BubbleEmitter. + * * @param[in] winSize The size of the bubble moving area, usually the same size as the background image actor. * @param[in] shapeImage The alpha channnel of this texture defines the bubble shape. * @param[in] maximumNumberOfBubble The maximum number of bubble needed. @@ -74,17 +75,25 @@ public: /** - * 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] handle The handle to copy */ BubbleEmitter( const BubbleEmitter& handle ); /** - * 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] rhs The object to point at + * @return A reference to this */ BubbleEmitter& operator=( const BubbleEmitter& rhs ); /** - * Downcast an Object handle to SuperBlurView. + * @brief Downcast an Object handle to SuperBlurView. + * * If handle points to a BubbleEmitter, the downcast produces valid handle. * If not, the returned handle is left uninitialized. * @param[in] handle Handle to an object @@ -93,13 +102,15 @@ public: static BubbleEmitter DownCast( BaseHandle handle ); /** - * Return the root actor of all bubbles, should then be added to stage. + * @brief Return the root actor of all bubbles, should then be added to stage. + * * @return The bubble root actor. */ Actor GetRootActor(); /** - * Set Background image. + * @brief Set Background image. + * * The bubbles pick color from this image with HSV values adjusted. * @param[in] bgImage The background image which provide color to bubbles. * @param[in] hsvDelta The hsv channel difference used to adjust the background image color. @@ -108,20 +119,23 @@ public: void SetBackground( Image bgImage, const Vector3& hsvDelta ); /** - * Set bubble shape. + * @brief Set bubble shape. + * * The bubble mesh is a rectangular patch, but its displayed shape is decided by the alpha channel of the shape image. * @param[in] shapeImage The image whose alpha channel defines the bubble shape. */ void SetShapeImage( Image shapeImage ); /** - * Set the scale factor applied to all the bubbles. + * @brief Set the scale factor applied to all the bubbles. + * * @param [in] scale The scale factor applied on bubbles. */ void SetBubbleScale( float scale ); /** - * Set the density of the bubble. + * @brief Set the density of the bubble. + * * Ideally every bubble's moving track is controlled by different uniforms in BubbleEffect shaders. * To increase the density, 'density' number of bubbles are sharing one group of uniforms, but with random offsets between these bubbles. * The available density is one to nine. The default density is five. @@ -131,13 +145,15 @@ public: void SetBubbleDensity( unsigned int density ); /** - * Enable different blending mode for rendering + * @brief Enable different blending mode for rendering. + * * @param[in] enable If false, the default blending function for RenderableActor is used. */ void SetBlendMode( bool enable ); /** - * Add a bubble movement to the animation. + * @brief Add a bubble movement to the animation. + * * @param[in] animation The animation reference. * By passing the animation into BubbleEmitter, the animation's duration and how many bubbles contained within this animation are freely decided in App. * @param[in] emitPosition The start position of the bubble movement. @@ -147,27 +163,30 @@ public: void EmitBubble( Animation& animation, const Vector2& emitPosition, const Vector2& direction, const Vector2& displacement ); /** - * Start an animation to enlarge every activated bubble's size and moving speed. + * @brief Start an animation to enlarge every activated bubble's size and moving speed. + * * @param[in] duration The duration of the animation * @param[in] multiple The bubble size and moving speed will be increased gradually to multiple speed during the animation. */ void StartExplosion( float duration, float multiple ); /** - * Reset all the parameters controlling the bubbles after animation. + * @brief Reset all the parameters controlling the bubbles after animation. */ void Restore(); public: // Not intended for developer use /** - * Creates a handle using the Toolkit::Internal implementation. + * @brief Creates a handle using the Toolkit::Internal implementation. + * * @param[in] implementation The Control implementation. */ DALI_INTERNAL BubbleEmitter(Internal::BubbleEmitter& implementation); /** - * Allows the creation of this Control from an Internal::CustomActor pointer. + * @brief Allows the creation of this Control from an Internal::CustomActor pointer. + * * @param[in] internal A pointer to the internal CustomActor. */ DALI_INTERNAL BubbleEmitter(Dali::Internal::CustomActor* internal); diff --git a/capi/dali-toolkit/public-api/controls/buttons/button.h b/capi/dali-toolkit/public-api/controls/buttons/button.h index d414714..8e76b14 100644 --- a/capi/dali-toolkit/public-api/controls/buttons/button.h +++ b/capi/dali-toolkit/public-api/controls/buttons/button.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_BUTTONS_MODULE * @{ */ @@ -42,7 +42,8 @@ class Button; } /** - * Button is a base class for different kind of buttons. + * @brief Button is a base class for different kind of buttons. + * * This class provides the dimmed property and the clicked signal. * * A ClickedSignal() is emitted when the button is touched and the touch @@ -55,7 +56,7 @@ class Button : public Control public: // Signal Names - static const char* const SIGNAL_CLICKED; + static const char* const SIGNAL_CLICKED; ///< name "clicked" // Properties static const Property::Index PROPERTY_DIMMED; ///< name "dimmed", @see SetDimmed(), type BOOLEAN @@ -63,37 +64,43 @@ public: public: /** - * Create an uninitialized Button. Only derived versions can be instantiated. - * Calling member functions with an uninitialized Dali::Object is not allowed. + * @brief Create an uninitialized Button. + * + * Only derived versions can be instantiated. Calling member + * functions with an uninitialized Dali::Object is not allowed. */ Button(); /** - * Copy constructor. + * @brief Copy constructor. */ Button( const Button& button ); /** - * Assignment operator. + * @brief Assignment operator. */ Button& operator=( const Button& button ); /** - * Downcast an Object handle to Button. If handle points to a Button the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to Button. + * + * If handle points to a Button the downcast produces valid + * handle. If not the returned handle is left uninitialized. + * * @param[in] handle Handle to an object * @return handle to a Button or an uninitialized handle */ static Button DownCast( BaseHandle handle ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~Button(); /** - * Sets the button as \e dimmed. + * @brief Sets the button as \e dimmed. * * No signals are emitted when the \e dimmed property is set. * @@ -107,38 +114,43 @@ public: bool IsDimmed() const; /** - * Sets the animation time. + * @brief Sets the animation time. + * * @param [in] animationTime The animation time in seconds. */ void SetAnimationTime( float animationTime ); /** - * Retrieves button's animation time. + * @brief Retrieves button's animation time. + * * @return The animation time in seconds. */ float GetAnimationTime() const; public: //Signals - // Button Clicked - + /** + * @brief Button Clicked signal type + */ typedef SignalV2< bool ( Button ) > ClickedSignalV2; /** - * Signal emitted when the button is touched and the touch point doesn't leave the boundary of the button. + * @brief Signal emitted when the button is touched and the touch point doesn't leave the boundary of the button. */ ClickedSignalV2& ClickedSignal(); public: // Not intended for application developers /** - * Creates a handle using the Toolkit::Internal implementation. + * @brief Creates a handle using the Toolkit::Internal implementation. + * * @param[in] implementation The Control implementation. */ Button( Internal::Button& implementation ); /** - * Allows the creation of this Control from an Internal::CustomActor pointer. + * @brief Allows the creation of this Control from an Internal::CustomActor pointer. + * * @param[in] internal A pointer to the internal CustomActor. */ Button( Dali::Internal::CustomActor* internal ); diff --git a/capi/dali-toolkit/public-api/controls/buttons/push-button.h b/capi/dali-toolkit/public-api/controls/buttons/push-button.h index d818b07..98ae002 100644 --- a/capi/dali-toolkit/public-api/controls/buttons/push-button.h +++ b/capi/dali-toolkit/public-api/controls/buttons/push-button.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_BUTTONS_MODULE * @{ */ @@ -41,7 +41,7 @@ class PushButton; } /** - * PushButton provides a button functionality. A PushButton changes its appearance when is pressed and returns to its original when is released. + * @brief A PushButton changes its appearance when is pressed and returns to its original when is released. * * By default a PushButton emits a PushButton::PressedSignal() signal when the button is pressed, a Button::ClickedSignal() signal when it's clicked * and a PushButton::ReleasedSignal() signal when it's released or having pressed it, the touch point leaves the boundary of the button. @@ -83,13 +83,13 @@ class PushButton : public Button { public: - // Signal Names - static const char* const SIGNAL_TOGGLED; - static const char* const SIGNAL_PRESSED; - static const char* const SIGNAL_RELEASED; + //Signal Names + static const char* const SIGNAL_TOGGLED; ///< name "toggled" + static const char* const SIGNAL_PRESSED; ///< name "pressed" + static const char* const SIGNAL_RELEASED; ///< name "released" - // Action Names - static const char* const ACTION_PUSH_BUTTON_CLICK; + //Action Names + static const char* const ACTION_PUSH_BUTTON_CLICK; ///< name "push-button-click" // Properties static const Property::Index PROPERTY_AUTO_REPEATING; ///< name "auto-repeating", @see SetAutoRepeating(), type BOOLEAN @@ -105,43 +105,49 @@ public: public: /** - * Create an uninitialized PushButton; this can be initialized with PushButton::New() + * @brief Create an uninitialized PushButton; this can be initialized with PushButton::New(). + * * Calling member functions with an uninitialized Dali::Object is not allowed. */ PushButton(); /** - * Copy constructor. + * @brief Copy constructor. */ PushButton( const PushButton& pushButton ); /** - * Assignment operator. + * @brief Assignment operator. */ PushButton& operator=( const PushButton& pushButton ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~PushButton(); /** - * Create an initialized PushButton. + * @brief Create an initialized PushButton. + * * @return A handle to a newly allocated Dali resource. */ static PushButton New(); /** - * Downcast an Object handle to PushButton. If handle points to a PushButton the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to PushButton. + * + * If handle points to a PushButton the downcast produces valid + * handle. If not the returned handle is left uninitialized. + * * @param[in] handle Handle to an object * @return handle to a PushButton or an uninitialized handle */ static PushButton DownCast( BaseHandle handle ); /** - * Sets the \e autorepeating property. + * @brief Sets the \e autorepeating property. * * If the \e autorepeating property is set to \e true, then the \e toggle property is set to false * but no signal is emitted. @@ -156,7 +162,7 @@ public: bool IsAutoRepeating() const; /** - * Sets the initial autorepeating delay. + * @brief Sets the initial autorepeating delay. * * By default this value is set to 0.15 seconds. * @@ -171,7 +177,7 @@ public: float GetInitialAutoRepeatingDelay() const; /** - * Sets the next autorepeating delay. + * @brief Sets the next autorepeating delay. * * By default this value is set to 0.05 seconds. * @@ -186,7 +192,7 @@ public: float GetNextAutoRepeatingDelay() const; /** - * Sets the \e toggle property. + * @brief Sets the \e toggle property. * * If the \e toggle property is set to \e true, then the \e autorepeating property is set to false. * @@ -200,7 +206,7 @@ public: bool IsToggleButton() const; /** - * Sets the button as toggled or not toggled. + * @brief Sets the button as toggled or not toggled. * * \e toggle property must be set to \e true. * @@ -216,7 +222,7 @@ public: bool IsToggled() const; /** - * Sets the button image. + * @brief Sets the button image. * * @param[in] image The button image. */ @@ -228,13 +234,14 @@ public: void SetButtonImage( Actor image ); /** - * Gets the button image. + * @brief Gets the button image. + * * @return An actor with the button image. */ Actor GetButtonImage() const; /** - * Sets the background image. + * @brief Sets the background image. * * @param[in] image The background image. */ @@ -246,13 +253,14 @@ public: void SetBackgroundImage( Actor image ); /** - * Gets the background image. + * @brief Gets the background image. + * * @return An actor with the background image. */ Actor GetBackgroundImage() const; /** - * Sets the pressed image. + * @brief Sets the pressed image. * * @param[in] image The pressed image. */ @@ -264,13 +272,14 @@ public: void SetPressedImage( Actor image ); /** - * Gets the pressed image. + * @brief Gets the pressed image. + * * @return An actor with the pressed image. */ Actor GetPressedImage() const; /** - * Sets the dimmed background image. + * @brief Sets the dimmed background image. * * @param[in] image The dimmed background image. */ @@ -282,13 +291,14 @@ public: void SetDimmedBackgroundImage( Actor image ); /** - * Gets the dimmed background image. + * @brief Gets the dimmed background image. + * * @return An actor with the dimmed background image. */ Actor GetDimmedBackgroundImage() const; /** - * Sets the dimmed button image. + * @brief Sets the dimmed button image. * * @param[in] image The dimmed button image. */ @@ -300,13 +310,14 @@ public: void SetDimmedImage( Actor image ); /** - * Gets the dimmed image. + * @brief Gets the dimmed image. + * * @return An actor with the dimmed image. */ Actor GetDimmedImage() const; /** - * Sets the text label. + * @brief Sets the text label. * * @param[in] text Label text. */ @@ -318,50 +329,50 @@ public: void SetLabelText( Actor text ); /** - * Gets the label text. + * @brief Gets the label text. + * * @return An actor with the label text. */ Actor GetLabelText() const; public: //Signals - // PushButton Toggled - + /// @brief PushButton Toggled signal type. typedef SignalV2< bool ( Button, bool ) > ToggledSignalV2; - // PushButton Pressed - + /// @brief PushButton Pressed signal type. typedef SignalV2< bool ( Button ) > PressedSignalV2; - // PushButton Released - + /// @brief PushButton Released signal type. typedef SignalV2< bool ( Button ) > ReleasedSignalV2; /** - * Signal emitted when the \e toggle property is set and the button is touched. + * @brief Signal emitted when the \e toggle property is set and the button is touched. */ ToggledSignalV2& ToggledSignal(); /** - * Signal emitted when the button is touched. + * @brief Signal emitted when the button is touched. */ PressedSignalV2& PressedSignal(); /** - * Signal emitted when the button is touched and the touch point leaves the boundary of the button. + * @brief Signal emitted when the button is touched and the touch point leaves the boundary of the button. */ ReleasedSignalV2& ReleasedSignal(); public: // Not intended for application developers /** - * Creates a handle using the Toolkit::Internal implementation. + * @brief Creates a handle using the Toolkit::Internal implementation. + * * @param[in] implementation The Control implementation. */ PushButton( Internal::PushButton& implementation ); /** - * Allows the creation of this Control from an Internal::CustomActor pointer. + * @brief Allows the creation of this Control from an Internal::CustomActor pointer. + * * @param[in] internal A pointer to the internal CustomActor. */ PushButton( Dali::Internal::CustomActor* internal ); diff --git a/capi/dali-toolkit/public-api/controls/cluster/cluster-style.h b/capi/dali-toolkit/public-api/controls/cluster/cluster-style.h index fccedc8..7587d16 100644 --- a/capi/dali-toolkit/public-api/controls/cluster/cluster-style.h +++ b/capi/dali-toolkit/public-api/controls/cluster/cluster-style.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_CLUSTER_MODULE * @{ */ @@ -43,26 +43,27 @@ class ClusterStyleRandom; class ClusterStyle; -typedef IntrusivePtr ClusterStylePtr; +typedef IntrusivePtr ClusterStylePtr; ///< Pointer to a Dali::Toolkit::ClusterStyle object /** - * A ClusterStyle describes the constraints, which are imposed on the child actors in the cluster. + * @brief A ClusterStyle describes the constraints which are imposed on the child actors in the cluster. */ class ClusterStyle : public Dali::BaseHandle { public: - static const unsigned int UNLIMITED_CHILDREN; + static const unsigned int UNLIMITED_CHILDREN; ///< Constant that represents an unlimited number of children. public: /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~ClusterStyle(); /** - * Query the maximum number of children this Style can handle. + * @brief Query the maximum number of children this Style can handle. + * * If return value is UNLIMITED_CHILDREN, then this style has no * limit. * @return The maximum number of children. @@ -70,7 +71,7 @@ public: unsigned int GetMaximumNumberOfChildren() const; /** - * Applies style (position) to child actor over a specified time duration. + * @brief Applies style (position) to child actor over a specified time duration. * * @param[in] child The child actor to apply * @param[in] index The style position index for the actor to transform to. @@ -80,7 +81,8 @@ public: void ApplyStyle(Actor child, unsigned int index, AlphaFunction alpha, const TimePeriod& durationSeconds); /** - * Applies style to background actor over a specified time duration. + * @brief Applies style to background actor over a specified time duration. + * * @param[in] background The background actor to apply * @param[in] alpha The alpha function to use. * @param[in] durationSeconds The time period to apply this style. @@ -88,7 +90,8 @@ public: void ApplyStyleToBackground(Actor background, AlphaFunction alpha, const TimePeriod& durationSeconds); /** - * Applies style to title actor over a specified time duration. + * @brief Applies style to title actor over a specified time duration. + * * @param[in] title The title actor to apply * @param[in] alpha The alpha function to use. * @param[in] durationSeconds The time period to apply this style. @@ -98,67 +101,73 @@ public: protected: /** - * Create a new ClusterStyle; Only derived versions are instantiatable. + * @brief Create a new ClusterStyle; Only derived versions are instantiatable. */ ClusterStyle(); public: // Not intended for application developers /** - * This constructor is used by Dali New() methods + * @brief This constructor is used by Dali New() methods. + * * @param [in] internal A pointer to a newly allocated Dali resource */ ClusterStyle(Internal::ClusterStyle* internal); }; /** - * A ClusterStyle describes the constraints, which are imposed on the child actors in the cluster. + * @brief A ClusterStyle describes the constraints, which are imposed on the child actors in the cluster. */ class ClusterStyleStandard : public ClusterStyle { public: + /** + * @brief Cluster Style type. + */ enum StyleType { - ClusterStyle1, - ClusterStyle2, - ClusterStyle3, - ClusterStyle4, - TotalClusterStyles + ClusterStyle1, ///< Style number 1 + ClusterStyle2, ///< Style number 2 + ClusterStyle3, ///< Style number 3 + ClusterStyle4, ///< Style number 4 + TotalClusterStyles ///< The number of styles }; public: /** - * Create an initialized style + * @brief Create an initialized style. */ static ClusterStyleStandard New(StyleType style); public: // Not intended for application developers /** - * This constructor is used by Dali New() methods + * @brief This constructor is used by Dali New() methods. + * * @param [in] internal A pointer to a newly allocated Dali resource */ ClusterStyleStandard(Internal::ClusterStyle* internal); }; /** - * A ClusterStyle describes the constraints, which are imposed on the child actors in the cluster. + * @brief A ClusterStyle describes the constraints, which are imposed on the child actors in the cluster. */ class ClusterStyleRandom : public ClusterStyle { public: /** - * Create an initialized style + * @brief Create an initialized style. */ static ClusterStyleRandom New(); public: // Not intended for application developers /** - * This constructor is used by Dali New() methods + * @brief This constructor is used by Dali New() methods. + * * @param [in] internal A pointer to a newly allocated Dali resource */ ClusterStyleRandom(Internal::ClusterStyle* internal); diff --git a/capi/dali-toolkit/public-api/controls/control-impl.h b/capi/dali-toolkit/public-api/controls/control-impl.h index c59309a..42be06c 100644 --- a/capi/dali-toolkit/public-api/controls/control-impl.h +++ b/capi/dali-toolkit/public-api/controls/control-impl.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_CONTROLS_MODULE * @{ */ @@ -38,11 +38,12 @@ class RelayoutControllerImpl; class KeyInputFocusManager; } -typedef std::pair< Actor, Vector2 > ActorSizePair; -typedef std::vector< ActorSizePair > ActorSizeContainer; +typedef std::pair< Actor, Vector2 > ActorSizePair; ///< Pair of actor and size +typedef std::vector< ActorSizePair > ActorSizeContainer; ///< Container of actors and their sizes /** - * This is the internal base class for all controls. + * @brief This is the internal base class for all controls. + * * It will provide some common functionality required by all controls. * Implements ConnectionTrackerInterface so that signals (typically connected to member functions) will * be disconnected automatically when the control is destroyed. @@ -61,7 +62,8 @@ public: // Creation /** - * Create a new ControlImpl instance that does not require touch by default. + * @brief Create a new ControlImpl instance that does not require touch by default. + * * If touch is required then the user can connect to this class' touch signal. * @return A handle to the ConntrolImpl instance. */ @@ -70,62 +72,72 @@ public: // Destruction /** - * Virtual destructor + * @brief Virtual destructor. */ virtual ~ControlImpl(); // Actions /** - * This method should be overridden by deriving classes when they wish to be notified when they + * @brief This method should be overridden by deriving classes when they wish to be notified when they * are activated. */ virtual void OnActivated() { } /** - * This method should be overridden by deriving classes when they wish to respond the accessibility + * @brief This method should be overridden by deriving classes when they wish to respond the accessibility * pan gesture. + * * @param[in] gesture The pan gesture. * @return true if the pan gesture has been consumed by this control */ virtual bool OnAccessibilityPan(PanGesture gesture); /** - * This method should be overridden by deriving classes when they wish to respond the accessibility - * up and down action (i.e. value change of slider control) + * @brief This method should be overridden by deriving classes when they wish to respond + * the accessibility up and down action (i.e. value change of slider control). + * * @param[in] isIncrease Whether the value should be increased or decreased * @return true if the value changed action has been consumed by this control */ virtual bool OnAccessibilityValueChange(bool isIncrease); /** - * Sets whether this control supports two dimensional keyboard navigation (i.e. whether it knows how to handle the keyboard - * focus movement between its child actors). The control doesn't support it by default. + * @brief Sets whether this control supports two dimensional + * keyboard navigation (i.e. whether it knows how to handle the + * keyboardn focus movement between its child actors). + * + * The control doesn't support it by default. * @param[in] isSupported Whether this control supports two dimensional keyboard navigation. */ void SetKeyboardNavigationSupport(bool isSupported); /** - * Gets whether this control supports two dimensional keyboard navigation. + * @brief Gets whether this control supports two dimensional keyboard navigation. + * * @return true if this control supports two dimensional keyboard navigation. */ bool IsKeyboardNavigationSupported(); /** - * Sets whether this control is a focus group for keyboard navigation (i.e. the scope of keyboard focus movement + * @brief Sets whether this control is a focus group for keyboard navigation. + * + * (i.e. the scope of keyboard focus movement * can be limitied to its child actors). The control is not a focus group by default. * @param[in] isFocusGroup Whether this control is set as a focus group for keyboard navigation. */ void SetAsKeyboardFocusGroup(bool isFocusGroup); /** - * Gets whether this control is a focus group for keyboard navigation. + * @brief Gets whether this control is a focus group for keyboard navigation. + * * @return true if this control is set as a focus group for keyboard navigation. */ bool IsKeyboardFocusGroup(); /** - * Gets the next keyboard focusable actor in this control towards the given direction. + * @brief Gets the next keyboard focusable actor in this control towards the given direction. + * * A control needs to override this function in order to support two dimensional keyboard navigation. * @param[in] currentFocusedActor The current focused actor. * @param[in] direction The direction to move the focus towards. @@ -135,14 +147,18 @@ public: virtual Actor GetNextKeyboardFocusableActor(Actor currentFocusedActor, Control::KeyboardFocusNavigationDirection direction, bool loopEnabled); /** - * Informs this control that its chosen focusable actor will be focused. This allows the application to - * preform any actions if wishes before the focus is actually moved to the chosen actor. + * @brief Informs this control that its chosen focusable actor will be focused. + * + * This allows the application to preform any actions if wishes + * before the focus is actually moved to the chosen actor. + * * @param[in] commitedFocusableActor The commited focusable actor. */ virtual void OnKeyboardFocusChangeCommitted(Actor commitedFocusableActor) { } /** - * Performs actions as requested using the action name. + * @brief Performs actions as requested using the action name. + * * @param[in] object The object on which to perform the action. * @param[in] actionName The action to perform. * @param[in] attributes The attributes with which to perfrom this action. @@ -162,14 +178,15 @@ protected: // Construction /** - * Second phase initialization. + * @brief Second phase initialization. */ void Initialize(); // Gesture Detection /** - * Allows deriving classes to enable any of the gesture detectors that are available. + * @brief Allows deriving classes to enable any of the gesture detectors that are available. + * * Gesture detection can be enabled one at a time or in bitwise format as shown: * @code * EnableGestureDetection(Gesture::Type(Gesture::Pinch | Gesture::Tap | Gesture::Pan)); @@ -179,7 +196,8 @@ protected: void EnableGestureDetection(Gesture::Type type); /** - * Allows deriving classes to disable any of the gesture detectors. + * @brief Allows deriving classes to disable any of the gesture detectors. + * * Like EnableGestureDetection, this can also be called using bitwise or. * @param[in] type The gesture type(s) to disable. * @see EnableGetureDetection @@ -187,8 +205,10 @@ protected: void DisableGestureDetection(Gesture::Type type); /** - * If deriving classes wish to fine tune pinch gesture detection then they can access the gesture - * detector through this API and modify the detection. + * @brief If deriving classes wish to fine tune pinch gesture + * detection then they can access the gesture detector through this + * API and modify the detection. + * * @return The pinch gesture detector. * @pre Pinch detection should have been enabled via EnableGestureDetection(). * @see EnableGestureDetection @@ -196,8 +216,10 @@ protected: PinchGestureDetector GetPinchGestureDetector() const; /** - * If deriving classes wish to fine tune pan gesture detection then they can access the gesture - * detector through this API and modify the detection. + * @brief If deriving classes wish to fine tune pan gesture + * detection then they can access the gesture detector through this + * API and modify the detection. + * * @return The pan gesture detector. * @pre Pan detection should have been enabled via EnableGestureDetection(). * @see EnableGestureDetection @@ -205,8 +227,10 @@ protected: PanGestureDetector GetPanGestureDetector() const; /** - * If deriving classes wish to fine tune tap gesture detection then they can access the gesture - * detector through this API and modify the detection. + * @brief If deriving classes wish to fine tune tap gesture + * detection then they can access the gesture detector through this + * API and modify the detection. + * * @return The tap gesture detector. * @pre Tap detection should have been enabled via EnableGestureDetection(). * @see EnableGestureDetection @@ -214,8 +238,10 @@ protected: TapGestureDetector GetTapGestureDetector() const; /** - * If deriving classes wish to fine tune long press gesture detection then they can access the - * gesture detector through this API and modify the detection. + * @brief If deriving classes wish to fine tune long press gesture + * detection then they can access the gesture detector through this + * API and modify the detection. + * * @return The long press gesture detector. * @pre Long press detection should have been enabled via EnableGestureDetection(). * @see EnableGestureDetection @@ -225,22 +251,28 @@ protected: private: // For derived classes to override /** - * This method is called after the Control has been initialized. Derived classes should do - * any second phase initialization by overriding this method. + * @brief This method is called after the Control has been initialized. + * + * Derived classes should do any second phase initialization by + * overriding this method. */ virtual void OnInitialize() { } /** - * This method should be overridden by deriving classes when they wish to be notified when the - * style changes. + * @brief This method should be overridden by deriving classes when + * they wish to be notified when the style changes. + * * @param[in] change Information denoting what has changed. */ virtual void OnStyleChange(StyleChange change) { } /** - * Called whenever a pinch gesture is detected on this control. This can be overridden by - * deriving classes when pinch detection is enabled. The default behaviour is to scale the - * control by the pinch scale. + * @brief Called whenever a pinch gesture is detected on this control. + * + * This can be overridden by deriving classes when pinch detection + * is enabled. The default behaviour is to scale the control by the + * pinch scale. + * * @note If overridden, then the default behaviour will not occur. * @note Pinch detection should be enabled via EnableGestureDetection(). * @param[in] pinch The pinch gesture. @@ -249,8 +281,11 @@ private: // For derived classes to override virtual void OnPinch(PinchGesture pinch); /** - * Called whenever a pan gesture is detected on this control. This should be overridden by - * deriving classes when pan detection is enabled. + * @brief Called whenever a pan gesture is detected on this control. + * + * This should be overridden by deriving classes when pan detection + * is enabled. + * * @note There is no default behaviour with panning. * @note Pan detection should be enabled via EnableGestureDetection(). * @param[in] pan The pan gesture. @@ -259,8 +294,11 @@ private: // For derived classes to override virtual void OnPan(PanGesture pan) { } /** - * Called whenever a tap gesture is detected on this control. This should be overridden by - * deriving classes when tap detection is enabled. + * @brief Called whenever a tap gesture is detected on this control. + * + * This should be overridden by deriving classes when tap detection + * is enabled. + * * @note There is no default behaviour with a tap. * @note Tap detection should be enabled via EnableGestureDetection(). * @param[in] tap The tap gesture. @@ -269,8 +307,11 @@ private: // For derived classes to override virtual void OnTap(TapGesture tap) { } /** - * Called whenever a long press gesture is detected on this control. This should be overridden by - * deriving classes when long press detection is enabled. + * @brief Called whenever a long press gesture is detected on this control. + * + * This should be overridden by deriving classes when long press + * detection is enabled. + * * @note There is no default behaviour associated with a long press. * @note Long press detection should be enabled via EnableGestureDetection(). * @param[in] longPress The long press gesture. @@ -279,40 +320,53 @@ private: // For derived classes to override virtual void OnLongPress(LongPressGesture longPress) { } /** - * Called whenever the control is added to the stage. Could be overridden by derived classes. + * @brief Called whenever the control is added to the stage. + * + * Could be overridden by derived classes. */ virtual void OnControlStageConnection() { } /** - * Called whenever the control is removed from the stage. Could be overridden by derived classes. + * @brief Called whenever the control is removed from the stage. + * + * Could be overridden by derived classes. */ virtual void OnControlStageDisconnection() { } /** - * Called whenever an Actor is added to the control. Could be overridden by derived classes. + * @brief Called whenever an Actor is added to the control. + * + * Could be overridden by derived classes. * * @param[in] child The added actor. */ virtual void OnControlChildAdd( Actor& child ) { } /** - * Called whenever an Actor is removed from the control. Could be overridden by derived classes. + * @brief Called whenever an Actor is removed from the control. + * + * Could be overridden by derived classes. * * @param[in] child The removed actor. */ virtual void OnControlChildRemove( Actor& child ) { } /** - * Called whenever the Control's size is set. Could be overridden by derived classes. + * @brief Called whenever the Control's size is set. + * + * Could be overridden by derived classes. * * @param[in] size The new size. */ virtual void OnControlSizeSet( const Vector3& size ) { } /** - * Called after the Dali::Stage::SignalMessageQueueFlushed() signal is emitted if this control requested to be relaid-out. - * Should be overridden by derived classes if they need to layout actors differently after certain operations like add or - * remove actors, resize or after changing especific properties. + * @brief Called after the Dali::Stage::SignalMessageQueueFlushed() + * signal is emitted if this control requested to be relaid-out. + * + * Should be overridden by derived classes if they need to layout + * actors differently after certain operations like add or remove + * actors, resize or after changing especific properties. * * @param[in] size The allocated size. * @param[in,out] container The control should add actors to this container that it is not able @@ -323,7 +377,10 @@ private: // For derived classes to override private: // From CustomActorImpl, derived classes can override these. /** - * Sends a request to relayout this control. The control will be relaid out after the Dali::Stage::SignalMessageQueueFlushed() signal is emitted. + * @brief Sends a request to relayout this control. + * + * The control will be relaid out after the + * Dali::Stage::SignalMessageQueueFlushed() signal is emitted. * * It calls OnControlStageConnection() to notify derived classes. * @@ -332,15 +389,18 @@ private: // From CustomActorImpl, derived classes can override these. virtual void OnStageConnection(); /** - * Calls OnControlStageDisconnection() to notify derived classed. + * @brief Calls OnControlStageDisconnection() to notify derived classed. * * @see Dali::CustomActorImpl::OnStageDisconnection() */ virtual void OnStageDisconnection(); /** - * Sends a request to relayout this control. The control will be relaid out after the Dali::Stage::SignalMessageQueueFlushed() signal is emitted. - * It calls OnControlChildAdd() to notify derived classes. + * @brief Sends a request to relayout this control. + * + * The control will be relaid out after the + * Dali::Stage::SignalMessageQueueFlushed() signal is emitted. It + * calls OnControlChildAdd() to notify derived classes. * * @note This method shouldn't be overridden by derived classes. * @@ -351,8 +411,11 @@ private: // From CustomActorImpl, derived classes can override these. virtual void OnChildAdd(Actor& child); /** - * Sends a request to relayout this control. The control will be relaid out after the Dali::Stage::SignalMessageQueueFlushed() signal is emitted. - * It calls OnControlChildRemove() to notify derived classes. + * @brief Sends a request to relayout this control. + * + * The control will be relaid out after the + * Dali::Stage::SignalMessageQueueFlushed() signal is emitted. It + * calls OnControlChildRemove() to notify derived classes. * * @note This method shouldn't be overridden by derived classes. * @@ -363,7 +426,9 @@ private: // From CustomActorImpl, derived classes can override these. virtual void OnChildRemove(Actor& child); /** - * It stores the size set by size negotiation and relayout. It also keeps a backup of the size set through the Actor's API used in the size negotiation. + * @brief It stores the size set by size negotiation and relayout. + * + * It also keeps a backup of the size set through the Actor's API used in the size negotiation. * It calls the OnControlSizeSet() to notify derived classes. * * @param[in] targetSize The new size. @@ -410,7 +475,8 @@ private: // From CustomActorImpl, derived classes can override these. private: /** - * Perform the activated action. + * @brief Perform the activated action. + * * @param[in] attributes The attributes to perfrom this action. */ void DoActivatedAction(const PropertyValueContainer& attributes); @@ -418,7 +484,8 @@ private: protected: // Construction /** - * Create a ControlImpl. + * @brief Create a ControlImpl. + * * @param[in] requiresTouchEvents True if the OnTouchEvent() callback is required. */ ControlImpl(bool requiresTouchEvents); @@ -473,14 +540,15 @@ public: virtual float GetWidthForHeight( float height ); /** - * Retrieves the current Control's size. + * @brief Retrieves the current Control's size. * * @return The control's size. */ const Vector3& GetControlSize() const; /** - * Retrieves the Control's size set by the Application / Control. + * @brief Retrieves the Control's size set by the Application / Control. + * * @return The control's size. */ const Vector3& GetSizeSet() const; @@ -520,19 +588,28 @@ public: protected: /** - * Sends a request to be relaid-out. This methos is called from OnStageConnection(), OnChildAdd(), OnChildRemove(), SetSizePolicy(), SetMinimumSize() and SetMaximumSize(). + * @brief Sends a request to be relaid-out. + * + * This method is called from OnStageConnection(), OnChildAdd(), + * OnChildRemove(), SetSizePolicy(), SetMinimumSize() and + * SetMaximumSize(). * - * This method could also be called from derived classes every time a control's poperty change and it needs to be relaid-out. - * After the Dali::Stage::SignalMessageQueueFlushed() is emitted a relayout process starts and all controls which called this method will be relaid-out. + * This method could also be called from derived classes every time + * a control's poperty change and it needs to be relaid-out. After + * the Dali::Stage::SignalMessageQueueFlushed() is emitted a + * relayout process starts and all controls which called this method + * will be relaid-out. * - * @note RelayoutRequest() only sends a request per Control before the Dali::Stage::SignalMessageQueueFlushed() signal is emitted. That means a control will be relaid-out - * only once, even if more than one request is sent between two consecutive signals. + * @note RelayoutRequest() only sends a request per Control before + * the Dali::Stage::SignalMessageQueueFlushed() signal is + * emitted. That means a control will be relaid-out only once, even + * if more than one request is sent between two consecutive signals. */ void RelayoutRequest(); /** - * Helper method for controls to Relayout their children if they do not know whether that child is - * a control or not. + * @brief Helper method for controls to Relayout their children if + * they do not know whether that child is a control or not. * * @param[in] actor The actor to relayout. * @param[in] size The size to allocate to the actor. @@ -543,10 +620,12 @@ protected: private: // Used by the RelayoutController /** - * Called by the RelayoutController to negotiate the size of a control. The size allocated by the - * the algorithm is passed in which the control must adhere to. A container is passed in as well - * which the control should populate with actors it has not / or does not need to handle in its - * size negotiation. + * @brief Called by the RelayoutController to negotiate the size of a control. + * + * The size allocated by the the algorithm is passed in which the + * control must adhere to. A container is passed in as well which + * the control should populate with actors it has not / or does not + * need to handle in its size negotiation. * * @param[in] size The allocated size. * @param[in,out] container The container that holds actors that are fed back into the @@ -557,7 +636,8 @@ private: // Used by the RelayoutController private: /** - * Called by NegotiateSize when the size to allocate to the control has been calculated. + * @brief Called by NegotiateSize when the size to allocate to the control has been calculated. + * * It calls the OnRelaidOut() method which can be overridden by derived classes. * * @param[in] size The allocated size. @@ -567,7 +647,8 @@ private: void Relayout( Vector2 size, ActorSizeContainer& container ); /** - * Used by the KeyInputFocusManager to emit key event signals. + * @brief Used by the KeyInputFocusManager to emit key event signals. + * * @param[in] event The key event. * @return True if the event was consumed. */ diff --git a/capi/dali-toolkit/public-api/controls/control.h b/capi/dali-toolkit/public-api/controls/control.h index a26cf7e..f588a2c 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 */ @@ -45,13 +46,13 @@ class Control : public CustomActor, public ConnectionTrackerInterface public: // Action Names - static const char* const ACTION_CONTROL_ACTIVATED; + static const char* const ACTION_CONTROL_ACTIVATED; ///< name "control-activated" // Signal Names - static const char* const SIGNAL_KEY_EVENT; + static const char* const SIGNAL_KEY_EVENT; ///< name "key-event" /** - * Describes how a control could be resized. + * @brief Describes how a control could be resized. */ enum SizePolicy { @@ -63,7 +64,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 +74,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 +86,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 +124,43 @@ 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; /** - * 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 +168,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 +176,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 +213,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 +222,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. * @@ -214,7 +231,9 @@ public: float GetWidthForHeight( float height ); /** - * 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 +241,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,11 +250,13 @@ 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. */ @@ -244,7 +266,8 @@ public: public: /** - * This signal is emitted when key event is received + * @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 +299,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 +317,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 +347,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 */ diff --git a/capi/dali-toolkit/public-api/controls/default-controls/push-button-factory.h b/capi/dali-toolkit/public-api/controls/default-controls/push-button-factory.h index 63c8177..30c6caa 100644 --- a/capi/dali-toolkit/public-api/controls/default-controls/push-button-factory.h +++ b/capi/dali-toolkit/public-api/controls/default-controls/push-button-factory.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_DEFAULT_CONTROLS_MODULE * @{ */ @@ -33,7 +33,7 @@ namespace Toolkit { /** - * Creates a push button with the given images. + * @brief Creates a push button with the given images. * Images will be shrunk to fit the button size keeping their aspect ratio. * @note Images won't be scaled to fill the whole button size. * @note If an image path is empty, this image is not set to the button. @@ -43,12 +43,14 @@ namespace Toolkit * @param[in] backgroundImagePath Image path to be shown as button background. * @param[in] dimmedReleasedImagePath Image path to be shown when the button is released and dimmed. * @param[in] dimmedBackgroundImagePath Image path to be shown as button background when the button is dimmed. + * @return A handle to the new push button */ PushButton CreatePushButton( const std::string& releasedImagePath, const std::string& pressedImagePath, const std::string& backgroundImagePath, const std::string& dimmedReleasedImagePath, const std::string& dimmedBackgroundImagePath ); /** - * Creates a push button with the given images. + * @brief Creates a push button with the given images. + * * Images will be shrunk to fit the button size keeping their aspect ratio. * @note Images won't be scaled to fill the whole button size. * @note If an image is an empty handle, this image is not set to the button. @@ -58,25 +60,30 @@ PushButton CreatePushButton( const std::string& releasedImagePath, const std::st * @param[in] backgroundImageActor Image to be shown as button background. * @param[in] dimmedReleasedImageActor Image to be shown when the button is released and dimmed. * @param[in] dimmedBackgroundImageActor Image to be shown as button background when the button is dimmed. + * @return A handle to the new pushbutton */ PushButton CreatePushButton( Actor releasedImageActor, Actor pressedImageActor, Actor backgroundImageActor, Actor dimmedReleasedImageActor, Actor dimmedBackgroundImageActor ); /** - * Creates a push button with the given background image. + * @brief Creates a push button with the given background image. + * * Background image will be shrunk to fit the button size keeping its aspect ratio. * @note Background image won't be scaled to fill the whole button size. * * @param[in] backgroundImagePath Image path to be shown as button background. + * @return a handle to the new push button */ PushButton CreatePushButton( const std::string& backgroundImagePath ); /** - * Creates a push button with the given background image. + * @brief Creates a push button with the given background image. + * * Background image will be shrunk to fit the button size keeping its aspect ratio. * @note Background image won't be scaled to fill the whole button size. * * @param[in] backgroundImageActor Image to be shown as button background. + * @return a handle to the new push button */ PushButton CreatePushButton( Actor backgroundImageActor ); diff --git a/capi/dali-toolkit/public-api/controls/default-controls/solid-color-actor.h b/capi/dali-toolkit/public-api/controls/default-controls/solid-color-actor.h index 999692c..3d4bc16 100644 --- a/capi/dali-toolkit/public-api/controls/default-controls/solid-color-actor.h +++ b/capi/dali-toolkit/public-api/controls/default-controls/solid-color-actor.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_DEFAULT_CONTROLS_MODULE * @{ */ @@ -33,7 +33,7 @@ namespace Toolkit { /** - * Creates a Dali::ImageActor with a solid color, optionally it creates a border. + * @brief Creates a Dali::ImageActor with a solid color, optionally it creates a border. * * If the \e border parameter is set to \e true, the Dali::ImageActor's style is set to Dali::ImageActor::STYLE_NINE_PATCH. * @@ -41,6 +41,7 @@ namespace Toolkit * @param[in] border If \e true, a border is created. By default, the value is set to \e false. * @param[in] borderColor The color for the ImageActor's border. By default, the value is set to Color::WHITE. * @param[in] borderSize The size for the ImageActor's border. By default, the value is set to 1 pixel. It supports under 10 pixel for clear result of gl blend + * @return a handle to the new ImageActor */ ImageActor CreateSolidColorActor( const Vector4& color, bool border = false, const Vector4& borderColor = Color::WHITE, const unsigned int borderSize = 1 ); diff --git a/capi/dali-toolkit/public-api/controls/image-view/masked-image-view.h b/capi/dali-toolkit/public-api/controls/image-view/masked-image-view.h index d01cead..a3dbfca 100644 --- a/capi/dali-toolkit/public-api/controls/image-view/masked-image-view.h +++ b/capi/dali-toolkit/public-api/controls/image-view/masked-image-view.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_IMAGE_VIEW_MODULE * @{ */ @@ -37,8 +37,9 @@ class MaskedImageView; } /** - * MaskedImageView displays the result of an image created from a masking operation, which is described below: + * @brief MaskedImageView displays the result of an image created from a masking operation. * + * Masking operations: * - Firstly a target image size is chosen. The MaskedImageView handles the creation of this image internally. Initially the * target image will be filled according to the BACKGROUND_COLOR property. * - A source image is provided and positioned with the target image area. The position of the source image (in pixels), can @@ -58,7 +59,7 @@ class MaskedImageView : public Control public: /** - * The custom properties installed by this control + * @brief The custom properties installed by this control. */ enum CustomProperty { @@ -71,13 +72,23 @@ public: CUSTOM_PROPERTY_COUNT }; + /** + * @brief Edit mode for this control. + * + * @see SetEditMode() + */ enum EditMode { - EDIT_DISABLED, - EDIT_SOURCE, - EDIT_MASK + EDIT_DISABLED, ///< Editting is disabled + EDIT_SOURCE, ///< Editting affects the source image + EDIT_MASK ///< Editting affects the mask }; + /** + * @brief The rotation of the image. + * + * @see SetSourceRotation() + */ enum ImageRotation { ROTATE_0, ///< No rotation @@ -89,29 +100,37 @@ public: static const float DEFAULT_MAXIMUM_SOURCE_SCALE; ///< Default SetMaximumSourceScale() value /** - * Creates an empty MaskedImageView handle + * @brief Creates an empty MaskedImageView handle. */ MaskedImageView(); /** - * 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 handle to copy from */ MaskedImageView( const MaskedImageView& handle ); /** - * 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 the handle of the object to re-assign this to + * @return a reference to this */ MaskedImageView& operator=( const MaskedImageView& handle ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~MaskedImageView(); /** - * Create the MaskedImageView control + * @brief Create the MaskedImageView control. + * * @param[in] targetWidth The width of the target image * @param[in] targetHeight The height of the target image * @param[in] sourceImage The source image @@ -124,87 +143,103 @@ public: Image maskImage ); /** - * Downcast an Object handle to MaskedImageView. If handle points to an MaskedImageView the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to MaskedImageView. + * + * If handle points to an MaskedImageView the downcast produces + * valid handle. If not the returned handle is left uninitialized. + * * @param[in] handle Handle to an object * @return handle to a MaskedImageView or an uninitialized handle */ static MaskedImageView DownCast( BaseHandle handle ); /** - * Set the image used as a source in the masking operation + * @brief Set the image used as a source in the masking operation. + * * @param[in] sourceImage The source image */ void SetSourceImage( Image sourceImage ); /** - * Retrieve the image used as a source in the masking operation + * @brief Retrieve the image used as a source in the masking operation. + * * @return sourceImage The source image */ Image GetSourceImage(); /** - * Set the image used as a mask in the masking operation + * @brief Set the image used as a mask in the masking operation. + * * @param[in] maskImage The mask image */ void SetMaskImage( Image maskImage ); /** - * Retrieve the image used as a mask in the masking operation + * @brief Retrieve the image used as a mask in the masking operation. + * * @return sourceImage The mask image */ Image GetMaskImage(); /** - * Get the property index for a custom MaskedImageView property. + * @brief Get the property index for a custom MaskedImageView property. + * * @param[in] customProperty A custom property enum defined in this class. * @return The property index e.g. for use with Animation::AnimateTo() */ Property::Index GetPropertyIndex( CustomProperty customProperty ) const; /** - * Pause the masking operation to improve performance. + * @brief Pause the masking operation to improve performance. + * * Call this when the source & mask positions etc. are not being modified. */ void Pause(); /** - * Resume the masking operation. + * @brief Resume the masking operation. + * */ void Resume(); /** - * Query whether the masking operation has been paused. + * @brief Query whether the masking operation has been paused. + * * @return True if the masking operation has been paused. */ bool IsPaused() const; /** - * Enable or disable an edit mode. The default is EDIT_DISABLED. + * @brief Enable or disable an edit mode. + * + * The default is EDIT_DISABLED. * @param[in] editMode The edit mode required. */ void SetEditMode( EditMode editMode ); /** - * Query which edit mode is enabled. + * @brief Query which edit mode is enabled. */ EditMode GetEditMode() const; /** - * Set the aspect ratio to be preserved when editing the source image. + * @brief Set the aspect ratio to be preserved when editing the source image. + * * @param[in] widthOverHeight The aspect ratio i.e. width divided by height. If a value * of zero or less is set, then the aspect ratio of the source image will be ignored. */ void SetSourceAspectRatio( float widthOverHeight ); /** - * Query the aspect ratio preserved when editing the source image. + * @brief Query the aspect ratio preserved when editing the source image. + * * @return The aspect ratio (width divided by height) or zero if no aspect ratio is set. */ float GetSourceAspectRatio() const; /** - * Set the maximum scale applied when editing the source image. + * @brief Set the maximum scale applied when editing the source image. + * * The minimum scale is implied by the target width/height i.e. the source image will * always fill that area when edit mode is enabled. * @param[in] scale The maximum scale. @@ -212,49 +247,59 @@ public: void SetMaximumSourceScale( float scale ); /** - * Query the maximum scale applied when editing the source image. + * @brief Query the maximum scale applied when editing the source image. + * * @return The maximum scale. */ float GetMaximumSourceScale() const; /** - * Set the rotation applied to the source image. + * @brief Set the rotation applied to the source image. + * * @param[in] rotation The new rotation; by default the source image is not rotated (ROTATE_0). */ void SetSourceRotation( ImageRotation rotation ); /** - * Query the rotation applied to the source image. + * @brief Query the rotation applied to the source image. + * * @return The current rotation. */ ImageRotation GetSourceRotation() const; public: /* Signals */ + /// @brief Finished signal type. typedef SignalV2< void (MaskedImageView& source) > MaskedImageViewSignal; /** - * Signal emitted when the render task which targets the frame buffer of the masked image has finished. + * @brief Signal emitted when the render task which targets the + * frame buffer of the masked image has finished. + * * This signal carries information of the control handle to the callback function. + * @return the signal */ MaskedImageViewSignal& MaskFinishedSignal(); /** * @deprecated Use MaskFinishedSignal() instead. * Signal emitted when the render task which targets the frame buffer of the masked image has finished. + * @return the signal. */ Dali::RenderTask::RenderTaskSignalV2& RenderFinishedSignal(); public: // Not intended for application developers /** - * Creates a handle using the Toolkit::Internal implementation. + * @brief Creates a handle using the Toolkit::Internal implementation. + * * @param[in] implementation The Control implementation. */ MaskedImageView(Internal::MaskedImageView& implementation); /** - * Allows the creation of this Control from an Internal::CustomActor pointer. + * @brief Allows the creation of this Control from an Internal::CustomActor pointer. + * * @param[in] internal A pointer to the internal CustomActor. */ MaskedImageView(Dali::Internal::CustomActor* internal); diff --git a/capi/dali-toolkit/public-api/controls/popup/popup.h b/capi/dali-toolkit/public-api/controls/popup/popup.h index 3b847c3..145cda6 100644 --- a/capi/dali-toolkit/public-api/controls/popup/popup.h +++ b/capi/dali-toolkit/public-api/controls/popup/popup.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_POPUP_MODULE * @{ */ @@ -40,8 +40,7 @@ class Popup; class Button; /** - * Popup contains content that can come into focus when - * activated, and out of focus when deactivated. + * @brief Popup contains content that can come into focus when activated, and out of focus when deactivated. * * Content: * @@ -65,10 +64,8 @@ class Button; * * Transition Effects: * - * A popup can use various custom transition effects e.g. - * + * A popup can use various custom transition effects, e.g. * Alpha fade, Scaling transition, position/rotation, shader effects. - * */ class Popup : public Control { @@ -76,11 +73,11 @@ class Popup : public Control public: //Signal Names - static const char* const SIGNAL_TOUCHED_OUTSIDE; - static const char* const SIGNAL_HIDDEN; + static const char* const SIGNAL_TOUCHED_OUTSIDE; ///< name "touched-outside" + static const char* const SIGNAL_HIDDEN; ///< name "hidden" /** - * Current popup state + * @brief Current popup state. */ enum PopupState { @@ -89,50 +86,61 @@ public: POPUP_SHOW, ///< Shown (visible in default size) }; - typedef SignalV2< void () > TouchedOutsideSignalV2; - typedef SignalV2< void () > HiddenSignalV2; + typedef SignalV2< void () > TouchedOutsideSignalV2; ///< Touched outside signal type. + typedef SignalV2< void () > HiddenSignalV2; ///< Hidden signal type. /** - * Signal emitted when user has touched outside of the Dialog. + * @brief Signal emitted when user has touched outside of the Dialog. */ TouchedOutsideSignalV2& OutsideTouchedSignal(); /** - * Signal emitted when popup has been hidden. + * @brief Signal emitted when popup has been hidden. */ HiddenSignalV2& HiddenSignal(); public: /** - * Creates an empty Popup handle + * @brief Creates an empty Popup handle. */ Popup(); /** - * 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] handle Handle to the copied object */ Popup( const Popup& handle ); /** - * 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 Handle to the object + * @return A reference to this */ Popup& operator=( const Popup& handle ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~Popup(); /** - * Create the Poup control + * @brief Create the Poup control. + * * @return A handle to the Popup control. */ static Popup New(); /** - * Downcast an Object handle to Popup. If handle points to a Popup the + * @brief Downcast an Object handle to Popup. + * + * If handle points to a Popup the * downcast produces valid handle. If not the returned handle is left uninitialized. * @param[in] handle Handle to an object * @return handle to a Popup or an uninitialized handle @@ -142,7 +150,7 @@ public: public: /** - * Sets the background image for this Popup. + * @brief Sets the background image for this Popup. * * The background is resized (stretched according to scale settings), * to the size of the Popup. @@ -152,7 +160,7 @@ public: void SetBackgroundImage( Actor image ); /** - * Sets a title for this Popup. + * @brief Sets a title for this Popup. * * By default a TextView is created with following settings: black color, split-by-word multi-line policy and split exceed policy. * @@ -161,21 +169,21 @@ public: void SetTitle( const std::string& text ); /** - * Sets a title for this Popup. + * @brief Sets a title for this Popup. * * @param[in] titleActor The TextView to appear as the heading for this Popup */ void SetTitle( TextView titleActor ); /** - * Gets the text (TextView) for this Popup. + * @brief Gets the text (TextView) for this Popup. * * @return The TextView representing this popup is returned. */ TextView GetTitle() const; /** - * Adds a button to this Popup. + * @brief Adds a button to this Popup. * * Buttons are added to the bottom of the Popup and Centered. * @@ -187,7 +195,7 @@ public: void AddButton( Button button ); /** - * Sets state of Popup, such as HIDE, and SHOW. + * @brief Sets state of Popup, such as HIDE, and SHOW. * * The Popup will instantaneously jump to this state. * @@ -196,7 +204,7 @@ public: void SetState( PopupState state ); /** - * Sets state of Popup, such as HIDE, and SHOW. + * @brief Sets state of Popup, such as HIDE, and SHOW. * * The Popup will smoothly animate to this state. * @@ -206,27 +214,28 @@ public: void SetState( PopupState state, float duration ); /** - * Gets the state of the popup. + * @brief Gets the state of the popup. + * * @return The state of the popup. */ PopupState GetState() const; /** - * Shows the popup. + * @brief Shows the popup. * * The Popup will animate to the SHOW state */ void Show(); /** - * Hides the popup. + * @brief Hides the popup. * * The Popup will animate to the HIDE state */ void Hide(); /** - * Shows the tail. + * @brief Shows the tail. * * The tail position is specified relative to it's Parent. * To display at top center for instace, pass: @@ -241,20 +250,22 @@ public: void ShowTail(const Vector3& position); /** - * Hides the tail. + * @brief Hides the tail. */ void HideTail(); public: // Not intended for application developers /** - * Creates a handle using the Toolkit::Internal implementation. + * @brief Creates a handle using the Toolkit::Internal implementation. + * * @param[in] implementation The Control implementation. */ Popup(Internal::Popup& implementation); /** - * Allows the creation of this Control from an Internal::CustomActor pointer. + * @brief Allows the creation of this Control from an Internal::CustomActor pointer. + * * @param[in] internal A pointer to the internal CustomActor. */ Popup( Dali::Internal::CustomActor* internal ); diff --git a/capi/dali-toolkit/public-api/controls/scrollable/item-view/grid-layout.h b/capi/dali-toolkit/public-api/controls/scrollable/item-view/grid-layout.h index b6b4d1b..82be3ca 100644 --- a/capi/dali-toolkit/public-api/controls/scrollable/item-view/grid-layout.h +++ b/capi/dali-toolkit/public-api/controls/scrollable/item-view/grid-layout.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_ITEM_VIEW_MODULE * @{ */ @@ -35,139 +35,165 @@ namespace Toolkit class GridLayout; -typedef IntrusivePtr GridLayoutPtr; +typedef IntrusivePtr GridLayoutPtr; ///< Pointer to a Dali::Toolkit::GridLayout object /** - * An ItemView layout which arranges items in a grid. + * @brief An ItemView layout which arranges items in a grid. */ class GridLayout : public ItemLayout { public: + /** + * @brief Function signature for a method to calculate the item size. + * + * @see SetItemSizeFunction() + */ typedef boost::function ItemSizeFunction; /** - * Create a new grid layout + * @brief Create a new grid layout. */ static GridLayoutPtr New(); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~GridLayout(); /** - * Set the number of columns in the layout. + * @brief Set the number of columns in the layout. + * * @param[in] columns The number of columns. */ void SetNumberOfColumns(unsigned int columns); /** - * Get the number of columns in the layout. + * @brief Get the number of columns in the layout. + * * @return The number of columns. */ unsigned int GetNumberOfColumns() const; /** - * Set the spacing between rows. + * @brief Set the spacing between rows. + * * @param[in] spacing The row spacing. */ void SetRowSpacing(float spacing); /** - * Get the spacing between rows. + * @brief Get the spacing between rows. + * * @return The row spacing. */ float GetRowSpacing() const; /** - * Set the spacing between columns. + * @brief Set the spacing between columns. + * * @param[in] spacing The row spacing. */ void SetColumnSpacing(float spacing); /** - * Get the spacing between columns. + * @brief Get the spacing between columns. + * * @return The row spacing. */ float GetColumnSpacing() const; /** - * Set the margin in the top of the layout + * @brief Set the margin in the top of the layout. + * * @param[in] margin The layout top margin. */ void SetTopMargin(float margin); /** - * Get the margin in the top of the layout + * @brief Get the margin in the top of the layout. + * * @return The layout top margin. */ float GetTopMargin() const; /** - * Set the margin in the bottom of the layout + * @brief Set the margin in the bottom of the layout. + * * @param[in] margin The layout bottom margin. */ void SetBottomMargin(float margin); /** - * Get the margin in the bottom of the layout + * @brief Get the margin in the bottom of the layout. + * * @return The layout bottom margin. */ float GetBottomMargin() const; /** - * Set the margin in the left and right of the layout + * @brief Set the margin in the left and right of the layout. + * * @param[in] margin The layout side margin. */ void SetSideMargin(float margin); /** - * Get the margin in the left and right of the layout + * @brief Get the margin in the left and right of the layout. + * * @return The layout side margin. */ float GetSideMargin() const; /** - * Set the gap of items in the Z axis in different columns. + * @brief Set the gap of items in the Z axis in different columns. + * * @param[in] gap The gap of items. */ void SetZGap(float gap); /** - * Get the gap of items in the Z axis in different columns. + * @brief Get the gap of items in the Z axis in different columns. + * * @return The gap of items. */ float GetZGap() const; /** - * Set the function used to calculate the item-size, for a given layout-size. + * @brief Set the function used to calculate the item-size, for a given layout-size. + * * @param[in] function The item-size function. */ void SetItemSizeFunction(ItemSizeFunction function); /** - * Get the function used to calculate the item-size. + * @brief Get the function used to calculate the item-size. + * * @return The item-size function. */ ItemSizeFunction GetItemSizeFunction() const; /** - * Set the factor used to customise the scroll speed while dragging and swiping the layout. + * @brief Set the factor used to customise the scroll speed while dragging and swiping the layout. + * * @param[in] scrollSpeed The scroll speed factor. */ void SetScrollSpeedFactor(float scrollSpeed); /** - * Set the maximum swipe speed in pixels per second. + * @brief Set the maximum swipe speed in pixels per second. + * * @param[in] speed The maximum swipe speed. */ void SetMaximumSwipeSpeed(float speed); /** - * Set the duration of the flick animation in second. This is the time taken to animate each - * item to its next layout position (e.g. from 1.0 to 2.0) when a flick animation is triggered - * by a swipe gesture. + * @brief Set the duration of the flick animation in seconds. + * + * This is the time taken to animate each item to its next layout + * position (e.g. from 1.0 to 2.0) when a flick animation is + * triggered by a swipe gesture. + * * @pre durationSeconds must be greater than zero. * @param[in] durationSeconds The duration of flick animation in seconds. */ @@ -268,7 +294,7 @@ private: protected: /** - * Protected constructor; see also GridLayout::New() + * @brief Protected constructor; see also GridLayout::New(). */ GridLayout(); diff --git a/capi/dali-toolkit/public-api/controls/scrollable/item-view/item-factory.h b/capi/dali-toolkit/public-api/controls/scrollable/item-view/item-factory.h index def729d..9f34da1 100644 --- a/capi/dali-toolkit/public-api/controls/scrollable/item-view/item-factory.h +++ b/capi/dali-toolkit/public-api/controls/scrollable/item-view/item-factory.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_ITEM_VIEW_MODULE * @{ */ @@ -32,7 +32,7 @@ namespace Toolkit { /** - * ItemFactory is an abstract interface for providing actors to ItemView. + * @brief ItemFactory is an abstract interface for providing actors to ItemView. * Each actor is identified by a unique ID, and has a linear order from 0 to GetNumberOfItems()-1. */ class ItemFactory @@ -40,18 +40,21 @@ class ItemFactory public: /** - * Virtual destructor + * @brief Virtual destructor. */ virtual ~ItemFactory() = 0; /** - * Query the number of items available from the factory. + * @brief Query the number of items available from the factory. + * * The maximum available item has an ID of GetNumberOfItems() - 1. + * @return the number of items */ virtual unsigned int GetNumberOfItems() = 0; /** - * Create an Actor to represent a visible item. + * @brief Create an Actor to represent a visible item. + * * @param[in] itemId The ID of the newly visible item. * @return An actor, or an uninitialized pointer if the ID is out of range. */ diff --git a/capi/dali-toolkit/public-api/controls/scrollable/item-view/item-layout.h b/capi/dali-toolkit/public-api/controls/scrollable/item-view/item-layout.h index 760de32..c04a58e 100644 --- a/capi/dali-toolkit/public-api/controls/scrollable/item-view/item-layout.h +++ b/capi/dali-toolkit/public-api/controls/scrollable/item-view/item-layout.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_ITEM_VIEW_MODULE * @{ */ @@ -35,16 +35,21 @@ namespace Toolkit class ItemLayout; -typedef IntrusivePtr ItemLayoutPtr; +typedef IntrusivePtr ItemLayoutPtr; ///< Pointer to a Dali::Toolkit::ItemLayout object -typedef std::vector ItemLayoutContainer; -typedef ItemLayoutContainer::iterator ItemLayoutIter; -typedef ItemLayoutContainer::const_iterator ItemLayoutConstIter; +typedef std::vector ItemLayoutContainer; ///< Container of Dali::Toolkit::ItemLayout objects +typedef ItemLayoutContainer::iterator ItemLayoutIter; ///< Iterator for Dali::Toolkit::ItemLayoutContainer +typedef ItemLayoutContainer::const_iterator ItemLayoutConstIter; ///< Const Iterator for Dali::Toolkit::ItemLayoutContainer + +/** + * @brief A support class for managing ranges of items. + */ struct ItemRange { /** - * Create a range of item identifiers. + * @brief Create a range of item identifiers. + * * @param[in] beginItem The first item within the range. * @param[in] endItem The past-the-end item. */ @@ -55,7 +60,8 @@ struct ItemRange } /** - * Copy Constructor. + * @brief Copy Constructor. + * * @param[in] copy ItemRange we should copy from. */ ItemRange(const ItemRange& copy) @@ -65,7 +71,8 @@ struct ItemRange } /** - * Assignment operator. + * @brief Assignment operator. + * * @param[in] range The Range to assign from. * @return The updated range. */ @@ -77,7 +84,8 @@ struct ItemRange } /** - * Test whether an item is within the range. + * @brief Test whether an item is within the range. + * * @param[in] itemId The item identifier. * @return True if the item is within the range. */ @@ -88,7 +96,8 @@ struct ItemRange } /** - * Create the intersection of two ranges. + * @brief Create the intersection of two ranges. + * * @param[in] second The second range. * @return The intersection. */ @@ -107,12 +116,13 @@ struct ItemRange return intersection; } - unsigned int begin; - unsigned int end; + unsigned int begin; ///< The start of the range + unsigned int end; ///< The end of the range }; /** - * An ItemLayout describes the constraints, which are imposed on items in the layout. + * @brief An ItemLayout describes the constraints which are imposed on items in the layout. + * * - Potentially visible items are represented by Actors, created for ItemView by the ItemFactory. * - Constraints are applied after ItemView activates a layout. * @@ -123,30 +133,40 @@ class ItemLayout : public RefObject { public: + /// @brief Function signature of a boolean constraint typedef boost::function BoolFunction; + + /// @brief Function signature of a Vector3 constraint typedef boost::function Vector3Function; + + /// @brief Function signature of a Vector4 constraint typedef boost::function Vector4Function; + + /// @brief Function signature of a Quaternion constraint typedef boost::function QuaternionFunction; /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~ItemLayout(); /** - * Set the orientation of the layout. + * @brief Set the orientation of the layout. + * * @param[in] orientation The orientation of the layout. */ void SetOrientation(ControlOrientation::Type orientation); /** - * Query the orientation of the layout. + * @brief Query the orientation of the layout. + * * @return the orientation of the layout. */ ControlOrientation::Type GetOrientation() const; /** - * Query the minimum valid layout position; this is a negative value. + * @brief Query the minimum valid layout position; this is a negative value. + * * When scrolling, the first item will move within the range 0 to GetMinimumLayoutPosition(). * @param[in] numberOfItems The current number of items in the layout. * @param[in] layoutSize The size of the layout area. @@ -155,7 +175,8 @@ public: virtual float GetMinimumLayoutPosition(unsigned int numberOfItems, Vector3 layoutSize) const = 0; /** - * Query the closest anchor position for the given layout position. + * @brief Query the closest anchor position for the given layout position. + * * This anchor position is the position where all the items in the layout are aligned to * their rounded layout positions in integer. * @param[in] layoutPosition The layout position. @@ -164,15 +185,17 @@ public: virtual float GetClosestAnchorPosition(float layoutPosition) const = 0; /** - * Query the layout position for the first item in the layout to move to when the layout + * @brief Query the layout position for the first item in the layout to move to when the layout * needs to scroll to a particular item. + * * @param[in] itemId The ID of an item in the layout. * @return The layout position for the first item in the layout to move to. */ virtual float GetItemScrollToPosition(unsigned int itemId) const = 0; /** - * Query the items within a given layout-area. + * @brief Query the items within a given layout-area. + * * @param[in] firstItemPosition The layout-position of the first item in the layout. * @param[in] layoutSize The size of the layout area. * @return The ID of the first & last visible item. @@ -180,21 +203,26 @@ public: virtual ItemRange GetItemsWithinArea(float firstItemPosition, Vector3 layoutSize) const = 0; /** - * Get the closest layout position to bring an item onto the screen. If the item is already fully on the screen - * this function will return the current layout position. + * @brief Get the closest layout position to bring an item onto the screen. * - * This function is used by systems such as KeyboardFocusManager to bring the next focusable item into view and all - * layout implementations should provide their own version of this function to ensure proper functionality of - * internal toolkit systems. + * If the item is already fully on the screen this function will + * return the current layout position. + * + * This function is used by systems such as KeyboardFocusManager to + * bring the next focusable item into view and all layout + * implementations should provide their own version of this function + * to ensure proper functionality of internal toolkit systems. * * @param[in] itemID id of the item to bring within the viewable screen area * @param[in] currentLayoutPosition the current layout position of the item view instance * @param[in] layoutSize the current size of the item view instance + * @return The layout position */ virtual float GetClosestOnScreenLayoutPosition(int itemID, float currentLayoutPosition, const Vector3& layoutSize); /** - * Query the number of items that should be reserved, for scrolling purposes. + * @brief Query the number of items that should be reserved, for scrolling purposes. + * * @param[in] layoutSize The size of the layout area. * @return The number of extra items. ItemView will populate itself with actors within the layout-area * (see GetItemsWithinArea), plus this number of additional items on either-side. @@ -202,7 +230,8 @@ public: virtual unsigned int GetReserveItemCount(Vector3 layoutSize) const = 0; /** - * Retrieve the target size of an item in the layout. + * @brief Retrieve the target size of an item in the layout. + * * @note layout-position is not provided as a parameter, since applying size constraints is not recommended. * Animating to target-sizes is preferable, since this allows controls to perform layouting without constraints. * @param[in] itemId The ID of an item in the layout. @@ -213,7 +242,8 @@ public: virtual bool GetItemSize(unsigned int itemId, Vector3 layoutSize, Vector3& itemSize) const = 0; /** - * Retrieve the resize animation in the layout. + * @brief Retrieve the resize animation in the layout. + * * @note This allows the layout to provide its own resize animation. * @param[in] animation The resize animation, not owned by the layout * @param[in] actor The actor to animate @@ -223,7 +253,8 @@ public: virtual void GetResizeAnimation(Animation& animation, Actor actor, Vector3 size, float durationSeconds) const = 0; /** - * Retrieve the position constraint function of an item in the layout. + * @brief Retrieve the position constraint function of an item in the layout. + * * The constraint will be applied when the item is created or the layout is activated. * @param[in] itemId The ID of an item in the layout. * @param[out] constraint The position constraint function of an item, or an uninitialized function pointer. @@ -232,7 +263,8 @@ public: virtual bool GetPositionConstraint(unsigned int itemId, Vector3Function& constraint) const = 0; /** - * Retrieve the rotation constraint function of an item in the layout. + * @brief Retrieve the rotation constraint function of an item in the layout. + * * The constraint will be applied when the item is created or the layout is activated. * @param[in] itemId The ID of an item in the layout. * @param[out] constraint The rotation constraint function of an item, or an uninitialized function pointer. @@ -241,7 +273,8 @@ public: virtual bool GetRotationConstraint(unsigned int itemId, QuaternionFunction& constraint) const = 0; /** - * Retrieve the scale constraint function of an item in the layout. + * @brief Retrieve the scale constraint function of an item in the layout. + * * The constraint will be applied when the item is created or the layout is activated. * @param[in] itemId The ID of an item in the layout. * @param[out] constraint The scale constraint function of an item, or an uninitialized function pointer. @@ -250,7 +283,8 @@ public: virtual bool GetScaleConstraint(unsigned int itemId, Vector3Function& constraint) const = 0; /** - * Retrieve the color constraint function of an item in the layout. + * @brief Retrieve the color constraint function of an item in the layout. + * * The constraint will be applied when the item is created or the layout is activated. * @param[in] itemId The ID of an item in the layout. * @param[out] constraint The color constraint function of an item, or an uninitialized function pointer. @@ -259,7 +293,8 @@ public: virtual bool GetColorConstraint(unsigned int itemId, Vector4Function& constraint) const = 0; /** - * Retrieve the visibility constraint function of an item in the layout. + * @brief Retrieve the visibility constraint function of an item in the layout. + * * The constraint will be applied when the item is created or the layout is activated. * @param[in] itemId The ID of an item in the layout. * @param[out] constraint The visibility constraint function of an item, or an uninitialized function pointer. @@ -268,7 +303,8 @@ public: virtual bool GetVisibilityConstraint(unsigned int itemId, BoolFunction& constraint) const = 0; /** - * Query the scroll direction of the layout. + * @brief Query the scroll direction of the layout. + * * When an input gesture follows this direction, the layout-position of items will be increased. * If the input gesture points in the opposite direction, then the layout-positions will decrease. * @return The scroll direction in degrees. @@ -276,7 +312,7 @@ public: virtual Degree GetScrollDirection() const = 0; /** - * Tells scroll components how to interpolate our logical scroll position as a screen x/y direction + * @brief Tells scroll components how to interpolate our logical scroll position as a screen x/y direction. * * Application developer wants to use -ve y, +ve x as up direction and +ve y, -ve x as down direction scroll values in a * vertical scroll type effect (SpiralLayout). This means that scroll bar/overshoot indicator should be affected by y-axis. @@ -292,7 +328,7 @@ public: virtual void GetXAxisScrollHint(Vector2& scrollHint) const; /** - * Tells scroll components how to interpolate our logical scroll position as a screen x/y direction + * @brief Tells scroll components how to interpolate our logical scroll position as a screen x/y direction. * * Application developer wants to use -ve y, +ve x as up direction and +ve y, -ve x as down direction scroll values in a * vertical scroll type effect (SpiralLayout). This means that scroll bar/overshoot indicator should be affected by y-axis. @@ -308,7 +344,8 @@ public: virtual void GetYAxisScrollHint(Vector2& scrollHint) const; /** - * Query the scroll speed factor of the layout. + * @brief Query the scroll speed factor of the layout. + * * This factor is used by the layout to customise its scroll speed while dragging and swiping. * The factor will be multiplied with the scroll distance of how many pixels in actor coordinate, * and the layout position of the actors in ItemView will be moved by this result. @@ -321,14 +358,17 @@ public: virtual float GetScrollSpeedFactor() const = 0; /** - * Query the maximum swipe speed in pixels per second. + * @brief Query the maximum swipe speed in pixels per second. + * * Swipe gestures will be clamped when exceeding this speed limit. * @return speed The maximum swipe speed. */ virtual float GetMaximumSwipeSpeed() const = 0; /** - * Get the duration of the flick animation in second. This is the time taken to animate each + * @brief Get the duration of the flick animation in second. + * + * This is the time taken to animate each * item to its next layout position (e.g. from 1.0 to 2.0) when a flick animation is triggered * by a swipe gesture. * @return The duration of the flick animation. @@ -336,25 +376,26 @@ public: virtual float GetItemFlickAnimationDuration() const = 0; /** - * Gets the id of the next item for KeyboardFocusManager to focus on depending on the inputted item ID + * @brief Gets the id of the next item for KeyboardFocusManager to focus on depending on the inputted item ID. * * @param[in] itemID The current focused item * @param[in] maxItems The maximum number of items in the list * @param[in] direction The directional key pressed on the keyboard * @param[in] loopEnabled Whether the KeyboardFocusManager is set to wrap around between first and last item + * @return The next item ID. */ virtual int GetNextFocusItemID(int itemID, int maxItems, Dali::Toolkit::Control::KeyboardFocusNavigationDirection direction, bool loopEnabled); protected: /** - * Create a new ItemLayout; Only derived versions are instantiatable. + * @brief Create a new ItemLayout; Only derived versions are instantiatable. */ ItemLayout(); protected: - ControlOrientation::Type mOrientation; + ControlOrientation::Type mOrientation; ///< the orientation of the layout. }; } // namespace Toolkit diff --git a/capi/dali-toolkit/public-api/controls/scrollable/item-view/item-view.h b/capi/dali-toolkit/public-api/controls/scrollable/item-view/item-view.h index cb5ed06..d7b04c6 100644 --- a/capi/dali-toolkit/public-api/controls/scrollable/item-view/item-view.h +++ b/capi/dali-toolkit/public-api/controls/scrollable/item-view/item-view.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_ITEM_VIEW_MODULE * @{ */ @@ -47,7 +47,8 @@ class ItemLayout; typedef IntrusivePtr ItemLayoutPtr; /** - * ItemView is a scrollable layout container. + * @brief ItemView is a scrollable layout container. + * * Multiple ItemLayouts may be provided, to determine the logical position of each item a layout. * Actors are provided from an external ItemFactory, to display the currently visible items. */ @@ -56,90 +57,108 @@ class ItemView : public Scrollable public: /** - * Create an uninitialized ItemView; this can be initialized with ItemView::New() + * @brief Create an uninitialized ItemView; this can be initialized with ItemView::New(). + * * Calling member functions with an uninitialized Dali::Object is not allowed. */ ItemView(); /** - * Copy constructor. + * @brief Copy constructor. */ ItemView( const ItemView& itemView ); /** - * Assignment operator. + * @brief Assignment operator. */ ItemView& operator=( const ItemView& itemView ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~ItemView(); /** - * Create an initialized ItemView. + * @brief Create an initialized ItemView. + * * @param[in] factory The factory which provides ItemView with items. * @return A handle to a newly allocated Dali resource. */ static ItemView New(ItemFactory& factory); /** - * Downcast an Object handle to ItemView. If handle points to a ItemView the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to ItemView. + * + * If handle points to a ItemView the downcast produces valid + * handle. If not the returned handle is left uninitialized. + * * @param[in] handle Handle to an object * @return handle to a ItemView or an uninitialized handle */ static ItemView DownCast( BaseHandle handle ); /** - * Retrieve a scroll-connector; this can be used to connect scroll components e.g. scroll bars. + * @brief Retrieve a scroll-connector; this can be used to connect scroll components e.g. scroll bars. + * * @return The connector. */ ScrollConnector GetScrollConnector() const; /** - * Query the number of layouts. + * @brief Query the number of layouts. + * * @return The number of layouts. */ unsigned int GetLayoutCount() const; /** - * Add a layout. + * @brief Add a layout. + * * @param[in] layout The layout. */ void AddLayout(ItemLayout& layout); /** - * Remove a layout. + * @brief Remove a layout. + * * @pre layoutIndex is less than GetLayoutCount(). * @param[in] layoutIndex The index of one of the ItemView layouts. */ void RemoveLayout(unsigned int layoutIndex); /** - * Retrieve a layout. + * @brief Retrieve a layout. + * * @pre layoutIndex is less than GetLayoutCount(). + * @param[in] layoutIndex The index of the layout to retrieve. * @return The layout */ ItemLayoutPtr GetLayout(unsigned int layoutIndex) const; /** - * Retrieve the currently active layout, if any. + * @brief Retrieve the currently active layout, if any. + * * @return The layout, or an uninitialized pointer if no layout is active. */ ItemLayoutPtr GetActiveLayout() const; /** - * Retrieve the current layout-position of an item in the ItemView. + * @brief Retrieve the current layout-position of an item in the ItemView. + * * @param[in] itemId The item identifier. * @return The current layout-position. */ float GetCurrentLayoutPosition(ItemId itemId) const; /** - * Activate one of the layouts; this will resize the ItemView & relayout actors within the ItemView. - * This is done by applying constraints from the new layout, and removing constraints from the previous layout. + * @brief Activate one of the layouts; this will resize the ItemView + * & relayout actors within the ItemView. + * + * This is done by applying constraints from the new layout, and + * removing constraints from the previous layout. + * * @pre layoutIndex is less than GetLayoutCount(). * @pre durationSeconds is greater or equal to zero. * @param[in] layoutIndex The index of one of the ItemView layouts. @@ -149,77 +168,95 @@ public: void ActivateLayout(unsigned int layoutIndex, Vector3 targetSize, float durationSeconds); /** - * Deactivate the current layout, if any. + * @brief Deactivate the current layout, if any. + * * The constraints applied by the layout will be removed. */ void DeactivateCurrentLayout(); /** - * Set the minimum swipe speed in pixels per second; A pan gesture must exceed this to trigger a swipe. + * @brief Set the minimum swipe speed in pixels per second; A pan + * gesture must exceed this to trigger a swipe. + * * @param[in] speed The minimum swipe speed */ void SetMinimumSwipeSpeed(float speed); /** - * Get the minimum swipe speed in pixels per second. + * @brief Get the minimum swipe speed in pixels per second. + * * @return The minimum swipe speed */ float GetMinimumSwipeSpeed() const; /** - * Set the minimum swipe distance in actor coordinates; A pan gesture must exceed this to trigger a swipe. + * @brief Set the minimum swipe distance in actor coordinates; A pan + * gesture must exceed this to trigger a swipe. + * * @param[in] distance The minimum swipe distance. */ void SetMinimumSwipeDistance(float distance); /** - * Get the minimum swipe distance in actor coordinates. + * @brief Get the minimum swipe distance in actor coordinates. + * * @return The minimum swipe distance */ float GetMinimumSwipeDistance() const; /** - * Set the step of scroll distance in actor coordinates for each mouse wheel event received. + * @brief Set the step of scroll distance in actor coordinates for each mouse wheel event received. + * * @param[in] step The step of scroll distance(pixel). */ void SetMouseWheelScrollDistanceStep(float step); /** - * Get the step of scroll distance in actor coordinates for each mouse wheel event received. + * @brief Get the step of scroll distance in actor coordinates for each mouse wheel event received. + * * @return The step of scroll distance(pixel) */ float GetMouseWheelScrollDistanceStep() const; /** - * Set whether to enable the animation for the layout to scroll to its anchor position after - * dragging or swiping. The anchor position is the position where all the items in the layout + * @brief Set whether to enable the animation for the layout to + * scroll to its anchor position after dragging or swiping. + * + * The anchor position is the position where all the items in the layout * are aligned to their closest rounded layout positions in integer. + * * @param[in] enabled Whether the anchor animation is enabled or not. */ void SetAnchoring(bool enabled); /** - * Get whether the anchor animation is enabled or not + * @brief Get whether the anchor animation is enabled or not. + * * @return Whether the anchor animation is enabled or not. */ bool GetAnchoring() const; /** - * Set the duration of the anchor animation in seconds. This is the time taken to reach the nearest - * anchor position after a drag or swipe gesture ends. + * @brief Set the duration of the anchor animation in seconds. + * + * This is the time taken to reach the nearest anchor position after + * a drag or swipe gesture ends. + * * @pre durationSeconds must be greater than zero. * @param[in] durationSeconds The duration of the anchor animation in seconds. */ void SetAnchoringDuration(float durationSeconds); /** - * Get the duration of the anchor animation in seconds + * @brief Get the duration of the anchor animation in seconds. + * * @return The duration of the anchor animation */ float GetAnchoringDuration() const; /** - * Scroll the current layout to a particular item. + * @brief Scroll the current layout to a particular item. + * * @pre durationSeconds must be zero or greater; zero means the layout should scroll to the particular item instantly. * If calling this with zero second of duration immediately after calling ActivateLayout, it might not work unless * the duration of relayout animation for ActivateLayout is also set to be zero. @@ -229,26 +266,30 @@ public: void ScrollToItem(ItemId itemId, float durationSeconds); /** - * Set the interval between refreshes, during which new items are requested from ItemFactory. + * @brief Set the interval between refreshes, during which new items are requested from ItemFactory. + * * @param[in] intervalMilliseconds The refresh interval in milliseconds. */ void SetRefreshInterval(unsigned int intervalMilliseconds); /** - * Get the interval between refreshes in milliseconds. + * @brief Get the interval between refreshes in milliseconds. + * * @return The refresh interval */ unsigned int GetRefreshInterval() const; /** - * Given the Item ID, this returns the accompanying actor. + * @brief Given the Item ID, this returns the accompanying actor. + * * @param[in] itemId The Item ID of the actor required. * @return The Actor corresponding to the Item ID. */ Actor GetItem(ItemId itemId) const; /** - * Returns the Item ID of the specified actor. + * @brief Returns the Item ID of the specified actor. + * * @param[in] actor The actor whose Item ID is required. * @return The Item ID of the item. * @pre The actor should be an item of ItemView. @@ -256,7 +297,8 @@ public: ItemId GetItemId(Actor actor) const; /** - * Insert an item. + * @brief Insert an item. + * * A relayout will occur for the existing actors; for example if InsertItem(Item(2, ActorZ), 0) is called, * the items with ID 2 or greater will be moved: * Initial actors: After insert: @@ -271,7 +313,8 @@ public: void InsertItem(Item newItem, float durationSeconds); /** - * Insert a set of items; this is more efficient than calling InsertItem() repeatedly. + * @brief Insert a set of items; this is more efficient than calling InsertItem() repeatedly. + * * @pre durationSeconds must be zero or greater; zero means the relayout occurs instantly. * @param[in] newItems The items to insert. * @param[in] durationSeconds How long the relayout takes in seconds. @@ -279,7 +322,8 @@ public: void InsertItems(const ItemContainer& newItems, float durationSeconds); /** - * Removes an item with the given ID. + * @brief Removes an item with the given ID. + * * A relayout will occur for the remaining actors; for example if RemoveItem(Item(2, ActorZ), 0) is called, * the items with ID 3 or greater will be moved: * Initial actors: After remove: @@ -294,7 +338,8 @@ public: void RemoveItem(ItemId itemId, float durationSeconds); /** - * Remove a set of items; this is more efficient than calling RemoveItem() repeatedly. + * @brief Remove a set of items; this is more efficient than calling RemoveItem() repeatedly. + * * @pre durationSeconds must be zero or greater; zero means the relayout occurs instantly. * @param[in] itemIds The IDs of the items to remove. * @param[in] durationSeconds How long the relayout takes in seconds. @@ -302,7 +347,8 @@ public: void RemoveItems(const ItemIdContainer& itemIds, float durationSeconds); /** - * Replace an item. + * @brief Replace an item. + * * A relayout will occur for the replacement item only. * @pre durationSeconds must be zero or greater; zero means the relayout occurs instantly. * @param[in] replacementItem The replacement for an existing item. @@ -311,7 +357,8 @@ public: void ReplaceItem(Item replacementItem, float durationSeconds); /** - * Replace a set of items. + * @brief Replace a set of items. + * * A relayout will occur for the replacement items only. * @pre durationSeconds must be zero or greater; zero means the relayout occurs instantly. * @param[in] replacementItems The replacements for a set of existing items. @@ -322,13 +369,15 @@ public: public: // Not intended for application developers /** - * Creates a handle using the Toolkit::Internal implementation. + * @brief Creates a handle using the Toolkit::Internal implementation. + * * @param[in] implementation The Control implementation. */ ItemView(Internal::ItemView& implementation); /** - * Allows the creation of this Control from an Internal::CustomActor pointer. + * @brief Allows the creation of this Control from an Internal::CustomActor pointer. + * * @param[in] internal A pointer to the internal CustomActor. */ ItemView( Dali::Internal::CustomActor* internal ); diff --git a/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view-cube-effect.h b/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view-cube-effect.h index dc3bbaf..26c6ef3 100644 --- a/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view-cube-effect.h +++ b/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view-cube-effect.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_SCROLL_VIEW_MODULE * @{ */ @@ -41,9 +41,8 @@ class ScrollViewCubeEffect; } /** - * ScrollView Cube-Effect. + * @brief This effect causes Actors to appear to rotate around a 3D cube. * - * This effect causes Actors to appear to rotate around a 3D cube. * It should be used on the following Actor hierarchy: * * ScrollView @@ -68,27 +67,33 @@ class ScrollViewCubeEffect : public ScrollViewEffect public: /** - * Create an initialized ScrollViewCubeEffect. + * @brief Create an initialized ScrollViewCubeEffect. + * * @return A handle to a newly allocated Dali resource. */ static ScrollViewCubeEffect New(); /** - * Create an uninitialized ScrollViewCubeEffect; this can be initialized with ScrollViewCubeEffect::New() + * @brief Create an uninitialized ScrollViewCubeEffect; this can be initialized with ScrollViewCubeEffect::New(). + * * Calling member functions with an uninitialized Toolkit::ScrollViewCubeEffect is not allowed. */ ScrollViewCubeEffect(); /** - * Downcast an Object handle to ScrollViewCubeEffect. If handle points to a ScrollViewCubeEffect the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to ScrollViewCubeEffect. + * + * If handle points to a ScrollViewCubeEffect the downcast produces + * valid handle. If not the returned handle is left uninitialized. + * * @param[in] handle Handle to an object * @return handle to a ScrollViewCubeEffect or an uninitialized handle */ static ScrollViewCubeEffect DownCast( BaseHandle handle ); /** - * Manually apply effect to an Actor. + * @brief Manually apply effect to an Actor. + * * @param[in] child The child Actor to be affected by this effect. * @param[in] anchor The anchor point that the child actor should * rotate around when scrolling @@ -103,7 +108,8 @@ public: const Vector2& positionSwing); /** - * Manually apply effect to an Actor. + * @brief Manually apply effect to an Actor. + * * @param[in] child The child Actor to be affected by this effect. * @param[in] parentPage The parent page Actor to be used by this effect. * @param[in] anchor The anchor point that the child actor should @@ -122,7 +128,8 @@ public: protected: /** - * This constructor is used by Dali New() methods. + * @brief This constructor is used by Dali New() methods. + * * @param [in] impl A pointer to a newly allocated Dali resource */ ScrollViewCubeEffect(Internal::ScrollViewCubeEffect *impl); diff --git a/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view-custom-effect.h b/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view-custom-effect.h index 8c4be1b..a5dafe6 100644 --- a/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view-custom-effect.h +++ b/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view-custom-effect.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_SCROLL_VIEW_MODULE * @{ */ @@ -39,9 +39,8 @@ class ScrollViewCustomEffect; } /** - * ScrollView Inner Cube-Effect. + * @brief This class has many transition effects for use when scrolling pages, e.g opacity, rotation, swing, translation. * - * This effect cause each page in a scroll-view to rotate round an inner 3D cube. * It should be used on the following Actor hierarchy: * * ScrollView @@ -61,6 +60,9 @@ class ScrollViewCustomEffect; class ScrollViewCustomEffect : public ScrollViewEffect { public: + /** + * @brief Bitflags for effect types. + */ enum EFlag { FlagTranslate = 0x0001, ///< indicates that translation is wanted @@ -109,96 +111,112 @@ public: }; /** - * Create an initialized ScrollViewPageCubeEffect. + * @brief Create an initialized ScrollViewCustomEffect. + * * @return A handle to a newly allocated Dali resource. */ static ScrollViewCustomEffect New(); /** - * Create an uninitialized ScrollViewPageCubeEffect; this can be initialized with ScrollViewPageCubeEffect::New() - * Calling member functions with an uninitialized Toolkit::ScrollViewPageCubeEffect is not allowed. + * @brief Create an uninitialized ScrollViewCustomEffect; this can be initialized with ScrollViewCustomEffect::New(). + * + * Calling member functions with an uninitialized Toolkit::ScrollViewCustomEffect is not allowed. */ ScrollViewCustomEffect(); /** - * Downcast an Object handle to ScrollViewCustomEffect. If handle points to a ScrollViewCustomEffect the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to ScrollViewCustomEffect. + * + * If handle points to a ScrollViewCustomEffect the downcast + * produces valid handle. If not the returned handle is left + * uninitialized. + * * @param[in] handle Handle to an object * @return handle to a ScrollViewCustomEffect or an uninitialized handle */ static ScrollViewCustomEffect DownCast( BaseHandle handle ); /** - * @brief SetPageSpacing + * @brief SetPageSpacing. + * * @param spacing */ void SetPageSpacing(const Vector2& spacing); /** - * @brief SetPageTranslation sets a simple translate on/off value + * @brief SetPageTranslation sets a simple translate on/off value. + * * @param translation */ void SetPageTranslation(const Vector3& translation); /** - * @brief SetPageTranslation + * @brief SetPageTranslation. + * * @param translationIn * @param translationOut */ void SetPageTranslation(const Vector3& translationIn, const Vector3& translationOut); /** - * @brief SetPageTranslationIn + * @brief SetPageTranslationIn. * @param translation */ void SetPageTranslationIn(const Vector3& translation); /** - * @brief SetPageTranslationOut + * @brief SetPageTranslationOut. + * * @param translation */ void SetPageTranslationOut(const Vector3& translation); /** - * @brief SetPageTranslateAlphaFunction + * @brief SetPageTranslateAlphaFunction. + * * @param func */ void SetPageTranslateAlphaFunction(AlphaFunction func); /** - * @brief SetPageTranslateAlphaFunction + * @brief SetPageTranslateAlphaFunction. + * * @param funcIn * @param funcOut */ void SetPageTranslateAlphaFunction(AlphaFunction funcIn, AlphaFunction funcOut); /** - * @brief SetPageTranslateAlphaFunctionIn + * @brief SetPageTranslateAlphaFunctionIn. + * * @param func */ void SetPageTranslateAlphaFunctionIn(AlphaFunction func); /** - * @brief SetPageTranslateAlphaFunctionOut + * @brief SetPageTranslateAlphaFunctionOut. * @param func */ void SetPageTranslateAlphaFunctionOut(AlphaFunction func); /** - * @brief SetGlobalPageRotation + * @brief SetGlobalPageRotation. + * * @param angle * @param axis */ void SetGlobalPageRotation(float angle, const Vector3& axis); /** - * @brief SetAnglePageRotation uses the angle and page size passed in on creation to create a faked origin (inner cube needs this method) + * @brief SetAnglePageRotation uses the angle and page size passed in on creation to create a faked origin (inner cube needs this method). + * * @param angle */ void SetAngledOriginPageRotation(const Vector3& angle); /** - * @brief SetGlobalPageRotation + * @brief SetGlobalPageRotation. + * * @param angleIn * @param axisIn * @param angleOut @@ -207,54 +225,62 @@ public: void SetGlobalPageRotation(float angleIn, const Vector3& axisIn, float angleOut, const Vector3& axisOut); /** - * @brief SetGlobalPageRotationIn + * @brief SetGlobalPageRotationIn. + * * @param angle * @param axis */ void SetGlobalPageRotationIn(float angle, const Vector3& axis); /** - * @brief SetGlobalPageRotationOut + * @brief SetGlobalPageRotationOut. + * * @param angle * @param axis */ void SetGlobalPageRotationOut(float angle, const Vector3& axis); /** - * @brief SetPageRotationOrigin Set the origin to rotate all the pages around + * @brief SetPageRotationOrigin Set the origin to rotate all the pages around. + * * - The default value is (0,0,0) * @param origin */ void SetGlobalPageRotationOrigin(const Vector3& origin); /** - * @brief SetGlobalPageRotationOrigin + * @brief SetGlobalPageRotationOrigin. + * * @param originIn * @param originOut */ void SetGlobalPageRotationOrigin(const Vector3& originIn, const Vector3& originOut); /** - * @brief SetGlobalPageRotationOriginIn + * @brief SetGlobalPageRotationOriginIn. + * * @param origin */ void SetGlobalPageRotationOriginIn(const Vector3& origin); /** - * @brief SetGlobalPageRotationOriginOut + * @brief SetGlobalPageRotationOriginOut. + * * @param origin */ void SetGlobalPageRotationOriginOut(const Vector3& origin); /** - * @brief SetSwingAngle + * @brief SetSwingAngle. + * * @param angle * @param axis */ void SetSwingAngle(float angle, const Vector3& axis); /** - * @brief SetSwingAngle + * @brief SetSwingAngle. + * * @param angleIn * @param axisIn * @param angleOut @@ -263,147 +289,169 @@ public: void SetSwingAngle(float angleIn, const Vector3& axisIn, float angleOut, const Vector3& axisOut); /** - * @brief SetSwingAngleIn + * @brief SetSwingAngleIn. + * * @param angle * @param axis */ void SetSwingAngleIn(float angle, const Vector3& axis); /** - * @brief SetSwingAngleOut + * @brief SetSwingAngleOut. + * * @param angle * @param axis */ void SetSwingAngleOut(float angle, const Vector3& axis); /** - * @brief SetSwingAngleAlphaFunction + * @brief SetSwingAngleAlphaFunction. + * * @param func */ void SetSwingAngleAlphaFunction(AlphaFunction func); /** - * @brief SetSwingAngleAlphaFunction + * @brief SetSwingAngleAlphaFunction. + * * @param funcIn * @param funcOut */ void SetSwingAngleAlphaFunction(AlphaFunction funcIn, AlphaFunction funcOut); /** - * @brief SetSwingAngleAlphaFunctionIn + * @brief SetSwingAngleAlphaFunctionIn. + * * @param func */ void SetSwingAngleAlphaFunctionIn(AlphaFunction func); /** - * @brief SetSwingAngleAlphaFunctionOut + * @brief SetSwingAngleAlphaFunctionOut. + * * @param func */ void SetSwingAngleAlphaFunctionOut(AlphaFunction func); /** - * @brief SetPageRotationOrigin Set the origin to rotate all the pages around + * @brief SetPageRotationOrigin Set the origin to rotate all the pages around. + * * - The default value is (0,0,0) * @param anchor */ void SetSwingAnchor(const Vector3& anchor); /** - * @brief SetSwingAnchor + * @brief SetSwingAnchor. + * * @param anchorIn * @param anchorOut */ void SetSwingAnchor(const Vector3& anchorIn, const Vector3& anchorOut); /** - * @brief SetSwingAnchorIn + * @brief SetSwingAnchorIn. + * * @param anchor */ void SetSwingAnchorIn(const Vector3& anchor); /** - * @brief SetSwingAnchorOut + * @brief SetSwingAnchorOut. + * * @param anchor */ void SetSwingAnchorOut(const Vector3& anchor); /** - * @brief SetSwingAnchorAlphaFunction + * @brief SetSwingAnchorAlphaFunction. + * * @param func */ void SetSwingAnchorAlphaFunction(AlphaFunction func); /** - * @brief SetSwingAnchorAlphaFunction + * @brief SetSwingAnchorAlphaFunction. + * * @param funcIn * @param funcOut */ void SetSwingAnchorAlphaFunction(AlphaFunction funcIn, AlphaFunction funcOut); /** - * @brief SetSwingAnchorAlphaFunctionIn + * @brief SetSwingAnchorAlphaFunctionIn. + * * @param func */ void SetSwingAnchorAlphaFunctionIn(AlphaFunction func); /** - * @brief SetSwingAnchorAlphaFunctionOut + * @brief SetSwingAnchorAlphaFunctionOut. * @param func */ void SetSwingAnchorAlphaFunctionOut(AlphaFunction func); /** - * @brief SetOpacityThreshold + * @brief SetOpacityThreshold. + * * @param thresh */ void SetOpacityThreshold(float thresh); /** - * @brief SetOpacityThreshold + * @brief SetOpacityThreshold. + * * @param threshIn * @param threshOut */ void SetOpacityThreshold(float threshIn, float threshOut); /** - * @brief SetOpacityThresholdIn + * @brief SetOpacityThresholdIn. + * * @param thresh */ void SetOpacityThresholdIn(float thresh); /** - * @brief SetOpacityThresholdOut + * @brief SetOpacityThresholdOut. + * * @param thresh */ void SetOpacityThresholdOut(float thresh); /** - * @brief SetOpacityAlphaFunction + * @brief SetOpacityAlphaFunction. + * * @param func */ void SetOpacityAlphaFunction(AlphaFunction func); /** - * @brief SetOpacityAlphaFunction + * @brief SetOpacityAlphaFunction. + * * @param funcIn * @param funcOut */ void SetOpacityAlphaFunction(AlphaFunction funcIn, AlphaFunction funcOut); /** - * @brief SetOpacityAlphaFunctionIn + * @brief SetOpacityAlphaFunctionIn. + * * @param func */ void SetOpacityAlphaFunctionIn(AlphaFunction func); /** - * @brief SetOpacityAlphaFunctionOut + * @brief SetOpacityAlphaFunctionOut. + * * @param func */ void SetOpacityAlphaFunctionOut(AlphaFunction func); /** - * Applies the effect to a page + * @brief Applies the effect to a page. + * * @param page the page to apply this effect to * @param pageSize not needed, page size is determined by scroll view @@ -413,7 +461,8 @@ public: protected: /** - * This constructor is used by Dali New() methods. + * @brief This constructor is used by Dali New() methods. + * * @param [in] impl A pointer to a newly allocated Dali resource */ ScrollViewCustomEffect( Internal::ScrollViewCustomEffect *impl ); diff --git a/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view-effect.h b/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view-effect.h index 7c862c9..07a0607 100644 --- a/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view-effect.h +++ b/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view-effect.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_SCROLL_VIEW_MODULE * @{ */ @@ -45,17 +45,18 @@ class ScrollViewWobbleEffect; class ScrollView; class ScrollViewEffect; -typedef std::vector ScrollViewEffectContainer; -typedef ScrollViewEffectContainer::iterator ScrollViewEffectIter; -typedef ScrollViewEffectContainer::const_iterator ScrollViewEffectConstIter; +typedef std::vector ScrollViewEffectContainer; ///< Container of Dali::Toolkit::ScrollViewEffect%s +typedef ScrollViewEffectContainer::iterator ScrollViewEffectIter; ///< Iterator for Dali::Toolkit::ScrollViewEffectContainer +typedef ScrollViewEffectContainer::const_iterator ScrollViewEffectConstIter; ///< Const Iterator for Dali::Toolkit::ScrollViewEffectContainer /** - * ScrollView Effect base class, used to apply custom - * effects to a ScrollView instance. Such effects are - * purely logical (i.e. physics), and may produce - * properties that can be used with visual effects. - * Such as creating constraints that are applied to ShaderEffects - * or Actors using these properties as inputs. + * @brief ScrollView Effect base class, used to apply custom effects to a + * ScrollView instance. + * + * Such effects are purely logical (i.e. physics), and may produce + * properties that can be used with visual effects. Such as creating + * constraints that are applied to ShaderEffects or Actors using these + * properties as inputs. */ class ScrollViewEffect : public Dali::BaseHandle { @@ -63,7 +64,8 @@ class ScrollViewEffect : public Dali::BaseHandle public: /** - * Create an uninitialized ScrollViewEffect; this can only be initialized with derived classes + * @brief Create an uninitialized ScrollViewEffect; this can only be initialized with derived classes. + * * Calling member functions with an uninitialized Toolkit::BaseObject is not allowed. */ ScrollViewEffect(); @@ -71,7 +73,8 @@ public: public: // Not intended for application developers /** - * This constructor is used by Dali New() methods. + * @brief This constructor is used by Dali New() methods. + * * @param [in] impl A pointer to a newly allocated Dali resource */ ScrollViewEffect(Internal::ScrollViewEffect *impl); diff --git a/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view-page-spiral-effect.h b/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view-page-spiral-effect.h index 9de2d54..0455a99 100644 --- a/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view-page-spiral-effect.h +++ b/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view-page-spiral-effect.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_SCROLL_VIEW_MODULE * @{ */ @@ -39,9 +39,8 @@ class ScrollViewPageSpiralEffect; } /** - * ScrollView Page Spiral Effect. + * @brief This effect cause each page in a scroll-view to move along a spiral. * - * This effect cause each page in a scroll-view to move along a spiral. * It should be used on the following Actor hierarchy: * * ScrollView @@ -64,19 +63,23 @@ class ScrollViewPageSpiralEffect : public ScrollViewEffect public: /** - * Create an initialized ScrollViewPageSpiralEffect. + * @brief Create an initialized ScrollViewPageSpiralEffect. + * * @return A handle to a newly allocated Dali resource. */ static ScrollViewPageSpiralEffect New(); /** - * Create an uninitialized ScrollViewPageSpiralEffect; this can be initialized with ScrollViewPageSpiralEffect::New() + * @brief Create an uninitialized ScrollViewPageSpiralEffect; this can be initialized with ScrollViewPageSpiralEffect::New(). + * * Calling member functions with an uninitialized Toolkit::ScrollViewPageSpiralEffect is not allowed. */ ScrollViewPageSpiralEffect(); /** - * Downcast an Object handle to ScrollViewPageSpiralEffect. If handle points to a ScrollViewPageSpiralEffect the + * @brief Downcast an Object handle to ScrollViewPageSpiralEffect. + * + * If handle points to a ScrollViewPageSpiralEffect the * downcast produces valid handle. If not the returned handle is left uninitialized. * @param[in] handle Handle to an object * @return handle to a ScrollViewPageSpiralEffect or an uninitialized handle @@ -84,7 +87,8 @@ public: static ScrollViewPageSpiralEffect DownCast( BaseHandle handle ); /** - * Manually apply effect to a page in the scroll-view. + * @brief Manually apply effect to a page in the scroll-view. + * * @param[in] page The page to be affected by this effect. * @param[in] spiralAngle The spirald angle (in radians). * @@ -96,7 +100,8 @@ public: protected: /** - * This constructor is used by Dali New() methods. + * @brief This constructor is used by Dali New() methods. + * * @param [in] impl A pointer to a newly allocated Dali resource */ ScrollViewPageSpiralEffect( Internal::ScrollViewPageSpiralEffect *impl ); diff --git a/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view-slide-effect.h b/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view-slide-effect.h index 08a240e..a64aa46 100644 --- a/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view-slide-effect.h +++ b/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view-slide-effect.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_SCROLL_VIEW_MODULE * @{ */ @@ -43,47 +43,52 @@ class ScrollViewSlideEffect; } /** - * ScrollView Twist-Effect. + * @brief ScrollView effect that uses slides for transitioning pages. */ class ScrollViewSlideEffect : public ScrollViewEffect { - public: - - static const std::string EFFECT_TIME; - static const std::string EFFECT_REFERENCE; - static const std::string EFFECT_ACTIVE; + static const std::string EFFECT_TIME; ///< Effect time property name + static const std::string EFFECT_REFERENCE; ///< Effect reference property name + static const std::string EFFECT_ACTIVE; ///< Effect active property name public: /** - * Create an initialized ScrollViewSlideEffect. + * @brief Create an initialized ScrollViewSlideEffect. + * * @return A handle to a newly allocated Dali resource. */ static ScrollViewSlideEffect New(); /** - * Create an uninitialized ScrollViewSlideEffect; this can be initialized with ScrollViewSlideEffect::New() + * @brief Create an uninitialized ScrollViewSlideEffect; this can be initialized with ScrollViewSlideEffect::New(). + * * Calling member functions with an uninitialized Toolkit::ScrollViewSlideEffect is not allowed. */ ScrollViewSlideEffect(); /** - * Downcast an Object handle to ScrollViewSlideEffect. If handle points to a ScrollViewSlideEffect the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to ScrollViewSlideEffect. + * + * If handle points to a ScrollViewSlideEffect the downcast produces + * valid handle. If not the returned handle is left uninitialized. + * * @param[in] handle Handle to an object * @return handle to a ScrollViewSlideEffect or an uninitialized handle */ static ScrollViewSlideEffect DownCast( BaseHandle handle ); /** - * Gets the slide direction for this effect. + * @brief Gets the slide direction for this effect. + * * @return The slide direction (true = vertical, false = horizontal) */ bool GetSlideDirection() const; /** - * Sets the slide direction for this effect. + * @brief Sets the slide direction for this effect. + * * If the direction has been set to horizontal (false), then * the user will see the Actors have a delay in horizontal movement * based on the vertical distance the actor is away from the initial drag point. @@ -95,14 +100,16 @@ public: void SetSlideDirection(bool vertical); /** - * Gets the delay reference offset for this effect. + * @brief Gets the delay reference offset for this effect. + * * @return The delay reference offset (Vector3::ZERO - indicates no offset) */ Vector3 GetDelayReferenceOffset() const; /** - * Sets an offset for where the central delay point on the scroll-view should be + * @brief Sets an offset for where the central delay point on the scroll-view should be * when dragging. + * * By default the offset is 0. Which means that the point where the user drags * the scroll-view content should have no delay, and the further away from this * point, the delay should increase. Adjusting this offset to for example @@ -114,19 +121,22 @@ public: void SetDelayReferenceOffset(const Vector3& offset); /** - * Gets the maximum duration of the effect after scrolling completes + * @brief Gets the maximum duration of the effect after scrolling completes. + * * @return The duration in seconds */ float GetMaxDelayDuration() const; /** - * Sets the maximum duration of the effect after scrolling completes + * @brief Sets the maximum duration of the effect after scrolling completes. + * * @param[in] duration The duration in seconds (>= 0.0f, default is 0.25 seconds) */ void SetMaxDelayDuration(float duration); /** - * Manually apply effect to an Actor. + * @brief Manually apply effect to an Actor. + * * @param[in] child The child Actor to be affected by this effect. * @param[in] delayMin The minimum delay coefficient for Actors at the * scroll-view touch point. Set to 0 for instantaneous, and 1 for infinite delay. @@ -142,7 +152,8 @@ public: protected: /** - * This constructor is used by Dali New() methods. + * @brief This constructor is used by Dali New() methods. + * * @param [in] impl A pointer to a newly allocated Dali resource */ ScrollViewSlideEffect(Internal::ScrollViewSlideEffect *impl); diff --git a/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view-twist-effect.h b/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view-twist-effect.h index 26f7070..14991cf 100644 --- a/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view-twist-effect.h +++ b/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view-twist-effect.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_SCROLL_VIEW_MODULE * @{ */ @@ -41,31 +41,35 @@ class ScrollViewTwistEffect; } /** - * ScrollView Twist-Effect. + * @brief ScrollView effect that twists pages onto screen when transitioning. */ class ScrollViewTwistEffect : public ScrollViewEffect { public: - static const float DEFAULT_MINIMUM_DISTANCE_FOR_SHRINK; + static const float DEFAULT_MINIMUM_DISTANCE_FOR_SHRINK; ///< The min distance for shrink public: /** - * Create an initialized ScrollViewTwistEffect. + * @brief Create an initialized ScrollViewTwistEffect. + * * @return A handle to a newly allocated Dali resource. */ static ScrollViewTwistEffect New(); /** - * Create an uninitialized ScrollViewTwistEffect; this can be initialized with ScrollViewTwistEffect::New() + * @brief Create an uninitialized ScrollViewTwistEffect; this can be initialized with ScrollViewTwistEffect::New(). + * * Calling member functions with an uninitialized Toolkit::ScrollViewTwistEffect is not allowed. */ ScrollViewTwistEffect(); /** - * Downcast an Object handle to ScrollViewTwistEffect. If handle points to a ScrollViewTwistEffect the + * @brief Downcast an Object handle to ScrollViewTwistEffect. + * + * If handle points to a ScrollViewTwistEffect the * downcast produces valid handle. If not the returned handle is left uninitialized. * @param[in] handle Handle to an object * @return handle to a ScrollViewTwistEffect or an uninitialized handle @@ -73,28 +77,32 @@ public: static ScrollViewTwistEffect DownCast( BaseHandle handle ); /** - * Gets the minimum animation distance for the shrink effect to - * occur + * @brief Gets the minimum animation distance for the shrink effect to + * occur. + * * @return The minimum distance in seconds is returned. */ float GetMinimumDistanceForShrink() const; /** - * Sets the minimum animation distance for the shrink effect + * @brief Sets the minimum animation distance for the shrink effect * to occur. + * * @param[in] distance The minimum distance in pixels (default = 0.0) * i.e. any flick will result in shrinking. */ void SetMinimumDistanceForShrink(float distance); /** - * Enable or disable this effect. + * @brief Enable or disable this effect. + * * @param[in] enableFlag Set to true if the effect should be enabled. */ void EnableEffect(bool enableFlag); /** - * Manually apply effect to an Actor. + * @brief Manually apply effect to an Actor. + * * @param[in] child The child Actor to be affected by this effect. * @param[in] additionalEffects Whether just the basic effect (delay) * should be applied. Or all effects (delay, rotation, scaling). @@ -119,16 +127,19 @@ public: float delayMax = 0.9f ); /** - * Set the maximum swing angle when at zero drop off + * @brief Set the maximum swing angle when at zero drop off. * * @param[in] maxSwingAngle maximum swing angle for x and y axes */ void SetMaxSwingAngle(const Vector2& maxSwingAngle); /** - * Set the drop off values to affect the amount of swing angle applied to an actor the further it is from - * the scroll position. A drop off of 0.0f means no angle drop off while 1.0f will reduce the angle to zero - * over the distance supplied for that axis. + * @brief Set the drop off values to affect the amount of swing + * angle applied to an actor the further it is from the scroll + * position. + * + * A drop off of 0.0f means no angle drop off while 1.0f will reduce + * the angle to zero over the distance supplied for that axis. * * Example maxSwingAngle.x is Pi, dropOff.x is 0.5f and distance.x is 100.0f: * The angle on the x axis will reduce to (0.5f * Pi) over 100 pixels @@ -142,7 +153,8 @@ public: protected: /** - * This constructor is used by Dali New() methods. + * @brief This constructor is used by Dali New() methods. + * * @param [in] impl A pointer to a newly allocated Dali resource */ ScrollViewTwistEffect(Internal::ScrollViewTwistEffect *impl); diff --git a/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view.h b/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view.h index cf614e3..79a42f3 100644 --- a/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view.h +++ b/capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_SCROLL_VIEW_MODULE * @{ */ @@ -36,33 +36,35 @@ namespace Internal DALI_INTERNAL class ScrollView; } +/** + * @brief The snap type + */ enum SnapType { - Snap, - Flick + Snap, ///< Snap + Flick ///< Flick }; /** - * DirectionBias types + * @brief DirectionBias types. */ enum DirectionBias { - DirectionBiasLeft = -1, ///< Bias scroll snap to Left - DirectionBiasNone = 0, ///< Don't bias scroll snap - DirectionBiasRight = 1 ///< Bias scroll snap to Right + DirectionBiasLeft = -1, ///< Bias scroll snap to Left + DirectionBiasNone = 0, ///< Don't bias scroll snap + DirectionBiasRight = 1 ///< Bias scroll snap to Right }; /** - * RulerDomain class - * - * Used for specifying minimum/maximum extents of a ruler. + * @brief Used for specifying minimum/maximum extents of a ruler. */ class RulerDomain { public: /** - * Creates Ruler domain allowing a point to traverse between min and max extents + * @brief Creates Ruler domain allowing a point to traverse between min and max extents. + * * @param[in] min Minimum extent (point cannot traverse less than this) * @param[in] max Maximum extent (point cannot traverse greater than this) * @param[in] enabled Whether domain has been enabled or not. @@ -71,35 +73,39 @@ public: public: - float min; - float max; - bool enabled; + float min; ///< Minimum extent (point cannot traverse less than this) + float max; ///< Maximum extent (point cannot traverse greater than this) + bool enabled; ///< Whether domain has been enabled or not. /** - * Clamps value (x) from (min) to (max), an optional length parameter can be - * specifies to suggest that the subject is not a point but a line to that - * should be clamped. + * @brief Clamps value (x) from (min) to (max). + * + * An optional length parameter can be specified to suggest that the + * subject is not a point but a line to that should be clamped. * * @param[in] x X point to be clamped between (min) and (max) extents. * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped. * @param[in] scale Scaling parameter which treats domain as scaled in calculations. + * @return The clamped value. */ float Clamp(float x, float length = 0.0f, float scale = 1.0f) const; /** - * Clamps value (x) from (min) to (max), an optional length parameter can be - * specifies to suggest that the subject is not a point but a line to that - * should be clamped. + * @brief Clamps value (x) from (min) to (max). + * + * An optional length parameter can be specified to suggest that the + * subject is not a point but a line to that should be clamped. * * @param[in] x X point to be clamped between (min) and (max) extents. * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped. * @param[in] scale Scaling parameter which treats domain as scaled in calculations. * @param[out] clamped Whether clamping occured and which size (None, Min or Max) + * @return The clamped value. */ float Clamp(float x, float length, float scale, ClampState &clamped) const; /** - * Returns (max-min) size of ruler. + * @brief Returns (max-min) size of ruler. * * @return The size of the ruler from min to max. */ @@ -108,34 +114,34 @@ public: }; /** - * Ruler abstract class. + * @brief Abstract class to define scroll axes. * - * Rulers are used to define axes, specifying whether they are traversable, - * where their snap points are, and their domain. + * It can specify whether they are traversable, where their snap + * points are and their domain. */ class Ruler : public RefObject { public: - + /// @brief The type of the ruler enum RulerType { - Fixed, - Free + Fixed, ///< A fixed ruler + Free ///< A free ruler }; public: /** - * Constructs ruler, defaulty enabled, with limitless domain. + * @brief Constructs ruler, default enabled, with limitless domain. */ Ruler(); /** - * Destructor - A reference counted object may only be deleted by calling Unreference() + * @brief Destructor - A reference counted object may only be deleted by calling Unreference(). */ virtual ~Ruler(); /** - * Snaps (x) in accordance to the ruler settings. + * @brief Snaps (x) in accordance to the ruler settings. * * @param[in] x The input value on the ruler to be snapped. * @param[in] bias (optional) The biasing employed for snapping @@ -147,7 +153,7 @@ public: virtual float Snap(float x, float bias = 0.5f) const = 0; /** - * Returns position from page, based on whatever the ruler + * @brief Returns position from page, based on whatever the ruler * defines as a page. * * If (wrap) is true, then will set volume to the number of @@ -163,7 +169,7 @@ public: virtual float GetPositionFromPage(unsigned int page, unsigned int &volume, bool wrap) const = 0; /** - * Returns page from position, based on whatever the ruler + * @brief Returns page from position, based on whatever the ruler * defines as a page. * * If (wrap) is true, then will return a page wrapped within the domain. @@ -175,7 +181,7 @@ public: virtual unsigned int GetPageFromPosition(float position, bool wrap) const = 0; /** - * Returns the total number of pages within this Ruler + * @brief Returns the total number of pages within this Ruler. * * @return The number of pages in the Ruler. */ @@ -183,84 +189,98 @@ public: public: + /** + * @brief Gets the ruler type. + * + * @return The ruler type. + */ Ruler::RulerType GetType() const; + /** - * Returns whether this axis has been enabled or not. + * @brief Returns whether this axis has been enabled or not. + * * @return true if axis is enabled */ bool IsEnabled() const; /** - * Enables ruler (ruler must be enabled in order to traverse along it) + * @brief Enables ruler (ruler must be enabled in order to traverse along it). */ void Enable(); /** - * Disables ruler + * @brief Disables ruler. */ void Disable(); /** - * Sets Domain + * @brief Sets Domain. + * * @param[in] domain Ruler domain object. */ void SetDomain(RulerDomain domain); /** - * Gets Domain + * @brief Gets Domain. + * * @return The domain */ const RulerDomain &GetDomain() const; /** - * Disables Domain (minimum/maximum extents for this axis) + * @brief Disables Domain (minimum/maximum extents for this axis). */ void DisableDomain(); /** - * Clamps value (x) from (min) to (max), an optional length parameter can be - * specifies to suggest that the subject is not a point but a line to that - * should be clamped. + * @brief Clamps value (x) from (min) to (max). + * + * An optional length parameter can be specified to suggest that the + * subject is not a point but a line that should be clamped. * * @param[in] x X point to be clamped between (min) and (max) extents. * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped. * @param[in] scale Scaling parameter which treats domain as scaled in calculations. + * @return The clamped value. */ float Clamp(float x, float length = 0.0f, float scale = 1.0f) const; /** - * Clamps value (x) from (min) to (max), an optional length parameter can be - * specifies to suggest that the subject is not a point but a line to that - * should be clamped. + * @brief Clamps value (x) from (min) to (max). + * + * An optional length parameter can be specified to suggest that the + * subject is not a point but a line to that should be clamped. * * @param[in] x X point to be clamped between (min) and (max) extents. * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped. * @param[in] scale Scaling parameter which treats domain as scaled in calculations. * @param[out] clamped Whether clamping occured and which size (None, Min or Max) + * @return The clamped value. */ float Clamp(float x, float length, float scale, ClampState &clamped) const; /** - * Snaps and Clamps (x) in accordance to ruler settings. + * @brief Snaps and Clamps (x) in accordance to ruler settings. * * @param[in] x value to be snapped in accordance to ruler snap value, - * and clamped in accordance to the ruler's domain (if set). + * and clamped in accordance to the ruler's domain (if set). * @param[in] bias (optional) The biasing employed for snapping - * 0 floor input (floor x) "Used for Flick Left" - * 0.5 round input (floor x + 0.5) "Used for Release" - * 1 ceil input (floor x + 1.0) "Used for Flick Right" + * 0 floor input (floor x) "Used for Flick Left" + * 0.5 round input (floor x + 0.5) "Used for Release" + * 1 ceil input (floor x + 1.0) "Used for Flick Right" * @param[in] length (optional) The Length of the line from (x) to (x + length) - * to be clamped. + * to be clamped. * @param[in] scale Scaling parameter which treats domain as scaled in calculations. + * @return the clamped value after snapping */ float SnapAndClamp(float x, float bias = 0.5f, float length = 0.0f, float scale = 1.0f) const; /** - * Snaps and Clamps (x) in accordance to ruler settings. + * @brief Snaps and Clamps (x) in accordance to ruler settings. * * @param[in] x value to be snapped in accordance to ruler snap value, - * and clamped in accordance to the ruler's domain (if set). + * and clamped in accordance to the ruler's domain (if set). * @param[in] bias (optional) The biasing employed for snapping * 0 floor input (floor x) "Used for Flick Left" * 0.5 round input (floor x + 0.5) "Used for Release" @@ -269,27 +289,28 @@ public: * to be clamped. * @param[in] scale Scaling parameter which treats domain as scaled in calculations. * @param[out] clamped Whether clamping occured and which size (None, Min or Max) + * @return The clamped value after snapping */ float SnapAndClamp(float x, float bias, float length, float scale, ClampState &clamped) const; protected: - RulerType mType; ///< Type of Ruler (Fixed or Free) - bool mEnabled; - RulerDomain mDomain; + RulerType mType; ///< Type of Ruler (Fixed or Free). + bool mEnabled; ///< If the ruler is enabled. + RulerDomain mDomain; ///< The domain of the ruler. }; -typedef IntrusivePtr RulerPtr; +typedef IntrusivePtr RulerPtr; ///< Pointer to Dali::Toolkit::Ruler object /** - * DefaultRuler has no snapping, and has one single page. + * @brief Concrete implementation of Ruler that has no snapping and has one single page. */ class DefaultRuler : public Ruler { public: /** - * DefaultRuler constructor + * @brief DefaultRuler constructor. */ DefaultRuler(); @@ -315,13 +336,15 @@ public: }; /** - * FixedRuler has fixed snapping, and contains + * @brief Concrete implementation of Ruler that has fixed snapping. */ class FixedRuler : public Ruler { public: /** - *@param[in] spacing The spacing between each interval on this ruler + * @brief Constructor + * + * @param[in] spacing The spacing between each interval on this ruler. */ FixedRuler(float spacing = 1.0f); @@ -346,29 +369,30 @@ public: virtual unsigned int GetTotalPages() const; private: - float mSpacing; + float mSpacing; ///< The spacing between each interval }; class ScrollViewEffect; class ScrollView; /** - * ScrollView contains actors that can be scrolled manually (via touch) + * @brief ScrollView contains actors that can be scrolled manually (via touch) * or automatically. */ class ScrollView : public Scrollable { public: + /// Page effect types enum PageEffect { - PageEffectNone, ///< No Effect (Standard ScrollView) - PageEffectOuterCube, ///< 3D Rotating Cube Effect - PageEffectDepth, ///< Depth Effect - PageEffectInnerCube, ///< Page Cube Effect - PageEffectCarousel, ///< Page Carousel Effect - PageEffectSpiral, ///< Page Spiral Effect - - Total + PageEffectNone, ///< No Effect (Standard ScrollView) + PageEffectOuterCube, ///< 3D Rotating Cube Effect + PageEffectDepth, ///< Depth Effect + PageEffectInnerCube, ///< Page Cube Effect + PageEffectCarousel, ///< Page Carousel Effect + PageEffectSpiral, ///< Page Spiral Effect + + Total ///< The total number of effect types }; // Custom properties @@ -402,8 +426,9 @@ public: static const float DEFAULT_MAX_FLICK_SPEED; ///< Default Maximum flick speed. (in stage diagonals per second) //Signal Names - static const char* const SIGNAL_SNAP_STARTED; + static const char* const SIGNAL_SNAP_STARTED; ///< Name "snap-started" + /// Direction of transitions enum EDirectionFlag { DirectionFlagLeft = 0x01, @@ -419,21 +444,21 @@ public: public: /** - * Snap signal event's data. + * @brief Snap signal event's data. */ struct SnapEvent { - SnapType type; ///< Current snap commencing - Vector3 position; ///< Target snap position - Vector3 scale; ///< Target snap scale - float rotation; ///< Target snap rotation - float duration; ///< Duration of snap animation. + SnapType type; ///< Current snap commencing + Vector3 position; ///< Target snap position + Vector3 scale; ///< Target snap scale + float rotation; ///< Target snap rotation + float duration; ///< Duration of snap animation. }; - typedef SignalV2< void ( const SnapEvent& ) > SnapStartedSignalV2; + typedef SignalV2< void ( const SnapEvent& ) > SnapStartedSignalV2; ///< SnapStarted signal type /** - * Signal emitted when the ScrollView has started to snap or flick (it tells the target + * @brief Signal emitted when the ScrollView has started to snap or flick (it tells the target * position, scale, rotation for the snap or flick) */ SnapStartedSignalV2& SnapStartedSignal(); @@ -441,36 +466,48 @@ public: public: /** - * Creates an empty ScrollView handle + * @brief Creates an empty ScrollView handle. */ ScrollView(); /** - * Copy constructor. Creates another handle that points to the same real object - * @param handle to copy from + * @brief Copy constructor. + * + * Creates another handle that points to the same real object + * + * @param[in] handle to copy from */ ScrollView( const ScrollView& handle ); /** - * 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 The handle to copy from + * @return A reference to this */ ScrollView& operator=( const ScrollView& handle ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~ScrollView(); /** - * Create an initialized ScrollView. + * @brief Create an initialized ScrollView. + * * @return A handle to a newly allocated Dali resource. */ static ScrollView New(); /** - * Downcast an Object handle to ScrollView. If handle points to a ScrollView the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to ScrollView. + * + * If handle points to a ScrollView the downcast produces valid + * handle. If not the returned handle is left uninitialized. + * * @param[in] handle Handle to an object * @return handle to a ScrollView or an uninitialized handle */ @@ -479,35 +516,36 @@ public: public: /** - * Get snap-animation's AlphaFunction + * @brief Get snap-animation's AlphaFunction. * * @return Current easing alpha function of the snap animation. */ AlphaFunction GetScrollSnapAlphaFunction() const; /** - * Set snap-animation's AlphaFunction + * @brief Set snap-animation's AlphaFunction. * * @param[in] alpha Easing alpha function of the snap animation. */ void SetScrollSnapAlphaFunction(AlphaFunction alpha); /** - * Get flick-animation's AlphaFunction + * @brief Get flick-animation's AlphaFunction. * * @return Current easing alpha function of the flick animation. */ AlphaFunction GetScrollFlickAlphaFunction() const; /** - * Set flick-animation's AlphaFunction + * @brief Set flick-animation's AlphaFunction. * * @param[in] alpha Easing alpha function of the flick animation. */ void SetScrollFlickAlphaFunction(AlphaFunction alpha); /** - * Gets the time for the scroll snap-animation + * @brief Gets the time for the scroll snap-animation. + * * This animation occurs when the user drags, and releases. * * @return The time in seconds for the animation to take. @@ -515,7 +553,8 @@ public: float GetScrollSnapDuration() const; /** - * Sets the time for the scroll snap-animation + * @brief Sets the time for the scroll snap-animation. + * * This animation occurs when the user drags, and releases. * * @param[in] time The time in seconds for the animation to take. @@ -523,7 +562,8 @@ public: void SetScrollSnapDuration(float time); /** - * Gets the time for the scroll flick-animation + * @brief Gets the time for the scroll flick-animation. + * * This animation occurs when the user flicks scroll view. * * @return The time in seconds for the animation to take. @@ -531,7 +571,8 @@ public: float GetScrollFlickDuration() const; /** - * Sets the time for the scroll flick-animation + * @brief Sets the time for the scroll flick-animation. + * * This animation occurs when the user flicks scroll view. * * @param[in] time The time in seconds for the animation to take. @@ -539,7 +580,9 @@ public: void SetScrollFlickDuration(float time); /** - * Set X axis ruler. Defines how scrolling horizontally is snapped, and + * @brief Set X axis ruler. + * + * Defines how scrolling horizontally is snapped, and * the boundary (domain) in which the ScrollView can pan. * * @param[in] ruler The ruler to be used for the X axis @@ -547,31 +590,37 @@ public: void SetRulerX(RulerPtr ruler); /** - * Set Y axis ruler. Defines how scrolling vertically is snapped, and - * the boundary (domain) in which the ScrollView can pan. + * @brief Set Y axis ruler. + * + * Defines how scrolling vertically is snapped, and the boundary + * (domain) in which the ScrollView can pan. * * @param[in] ruler The ruler to be used for the Y axis */ void SetRulerY(RulerPtr ruler); /** - * Set Scale-X axis ruler. Defines how scaling horizontally is snapped, and - * the extent (domain) to which scaling can be performed e.g. 10% to 200% + * @brief Set Scale-X axis ruler. + * + * Defines how scaling horizontally is snapped, and the extent + * (domain) to which scaling can be performed e.g. 10% to 200% * * @param[in] ruler The ruler to be used for the Scale-X axis */ void SetRulerScaleX(RulerPtr ruler); /** - * Set Scale-Y axis ruler. Defines how scaling vertically is snapped, and - * the extent (domain) to which scaling can be performed e.g. 10% to 200% + * @brief Set Scale-Y axis ruler. + * + * Defines how scaling vertically is snapped, and the extent + * (domain) to which scaling can be performed e.g. 10% to 200% * * @param[in] ruler The ruler to be used for the Scale-Y axis */ void SetRulerScaleY(RulerPtr ruler); /** - * Set Scroll's touch sensitivity. + * @brief Set Scroll's touch sensitivity. * * @note Unlike SetSensitive(), this determines whether this ScrollView * should react (e.g. pan), without disrupting the sensitivity of it's children. @@ -581,9 +630,12 @@ public: void SetScrollSensitive(bool sensitive); /** - * Set maximum overshoot amount. The final overshoot value is within 0.0f to 1.0f, - * but the maximum overshoot is in pixels (e.g. if you scroll 75 pixels beyond the edge of a scrollable - * area and the maximum overshoot is 100 then the final overshoot value will be 0.75f) + * @brief Set maximum overshoot amount. + * + * The final overshoot value is within 0.0f to 1.0f, but the maximum + * overshoot is in pixels (e.g. if you scroll 75 pixels beyond the + * edge of a scrollable area and the maximum overshoot is 100 then + * the final overshoot value will be 0.75f) * * @param[in] overshootX the maximum number of horizontally scrolled pixels before overshoot X reaches 1.0f * @param[in] overshootY the maximum number of vertically scrolled pixels before overshoot Y reaches 1.0f @@ -591,14 +643,14 @@ public: void SetMaxOvershoot(float overshootX, float overshootY); /** - * Set Snap Overshoot animation's AlphaFunction + * @brief Set Snap Overshoot animation's AlphaFunction. * * @param[in] alpha Easing alpha function of the overshoot snap animation. */ void SetSnapOvershootAlphaFunction(AlphaFunction alpha); /** - * Set Snap Overshoot animation's Duration + * @brief Set Snap Overshoot animation's Duration. * * @note Set duration to 0 seconds, to disable Animation. * @@ -607,7 +659,7 @@ public: void SetSnapOvershootDuration(float duration); /** - * Sets Touches required for pan gestures. + * @brief Sets Touches required for pan gestures. * * Panning requires number of touches to be within (minTouches) and * (maxTouches). @@ -625,7 +677,7 @@ public: void SetTouchesRequiredForPanning(unsigned int minTouches = 1, unsigned int maxTouches = 1, bool endOutside = true); /** - * Enables or Disables Actor Auto-Snap mode. + * @brief Enables or Disables Actor Auto-Snap mode. * * When Actor Auto-Snap mode has been enabled, ScrollView will automatically * snap to the closest actor (The closest actor will appear in the center of @@ -636,7 +688,7 @@ public: void SetActorAutoSnap(bool enable); /** - * Enables or Disables Wrap mode for ScrollView contents. + * @brief Enables or Disables Wrap mode for ScrollView contents. * * When enabled, the ScrollView contents are wrapped over the X/Y Domain. * @@ -648,18 +700,18 @@ public: void SetWrapMode(bool enable); /** - * Gets the current refresh interval in milliseconds. + * @brief Gets the current refresh interval in milliseconds. * * @return Current refresh interval in milliseconds */ int GetRefreshInterval() const; /** - * Sets the refresh interval in milliseconds. + * @brief Sets the refresh interval in milliseconds. * * The refresh interval is a notification signal - * (SignalScrollUpdate), that is periodically fired - * when scrolling animation is occuring. + * (SignalScrollUpdate), that is periodically fired when scrolling + * animation is occuring. * * When set to 0. No update signals are sent. * @@ -668,14 +720,14 @@ public: void SetRefreshInterval(int milliseconds); /** - * Returns state of Axis Auto Lock mode. + * @brief Returns state of Axis Auto Lock mode. * * @return Whether Axis Auto Lock mode has been enabled or not. */ bool GetAxisAutoLock() const; /** - * Enables or Disables Axis Auto Lock mode for panning within the ScrollView + * @brief Enables or Disables Axis Auto Lock mode for panning within the ScrollView. * * When enabled, any pan gesture that appears mostly horizontal or mostly * vertical, will be automatically restricted to horizontal only or vertical @@ -686,16 +738,19 @@ public: void SetAxisAutoLock(bool enable); /** - * Gets the gradient threshold at which a panning gesture should be locked to the - * Horizontal or Vertical axis. + * @brief Gets the gradient threshold at which a panning gesture + * should be locked to the Horizontal or Vertical axis. + * * @return The gradient, a value between 0.0 and 1.0f. */ float GetAxisAutoLockGradient() const; /** - * Sets the gradient threshold at which a panning gesture should be locked to the - * Horizontal or Vertical axis. by default this is 0.36 (0.36:1) which means angles - * less than 20 degrees to an axis will lock to that axis. + * @brief Sets the gradient threshold at which a panning gesture should be locked to the + * Horizontal or Vertical axis. + * + * By default this is 0.36 (0.36:1) which means angles less than 20 + * degrees to an axis will lock to that axis. * * @note: Specifying a value of 1.0 (the maximum value accepted) indicates that * all panning gestures will auto-lock. Either to the horizontal or vertical axis. @@ -705,8 +760,9 @@ public: void SetAxisAutoLockGradient(float gradient); /** - * Gets the friction coefficient setting for ScrollView when + * @brief Gets the friction coefficient setting for ScrollView when * flicking in free panning mode. + * * This is a value in stage-diagonals per second^2. * stage-diagonal = Length( stage.width, stage.height ) * @return Friction coefficient is returned. @@ -714,8 +770,9 @@ public: float GetFrictionCoefficient() const; /** - * Sets the friction coefficient for ScrollView when - * flicking in free panning mode. + * @brief Sets the friction coefficient for ScrollView when flicking + * in free panning mode. + * * This is a value in stage-diagonals per second^2. * stage-diagonal = Length( stage.width, stage.height ). * example: @@ -727,8 +784,9 @@ public: void SetFrictionCoefficient(float friction); /** - * Gets the flick speed coefficient for ScrollView when + * @brief Gets the flick speed coefficient for ScrollView when * flicking in free panning mode. + * * This is a constant which multiplies the input touch * flick velocity to determine the actual velocity at * which to move the scrolling area. @@ -737,8 +795,9 @@ public: float GetFlickSpeedCoefficient() const; /** - * Sets the flick speed coefficient for ScrollView when + * @brief Sets the flick speed coefficient for ScrollView when * flicking in free panning mode. + * * This is a constant which multiplies the input touch * flick velocity to determine the actual velocity at * which to move the scrolling area. @@ -747,8 +806,9 @@ public: void SetFlickSpeedCoefficient(float speed); /** - * Gets the maximum flick speed setting for ScrollView when + * @brief Gets the maximum flick speed setting for ScrollView when * flicking in free panning mode. + * * This is a value in stage-diagonals per second. * stage-diagonal = Length( stage.width, stage.height ) * @return Maximum flick speed is returned @@ -756,8 +816,9 @@ public: float GetMaxFlickSpeed() const; /** - * Sets the maximum flick speed for the ScrollView when + * @brief Sets the maximum flick speed for the ScrollView when * flicking in free panning mode. + * * This is a value in stage-diagonals per second. * stage-diagonal = Length( stage.width, stage.height ) * example: @@ -769,15 +830,17 @@ public: void SetMaxFlickSpeed(float speed); /** - * Gets the step of scroll distance in actor coordinates for + * @brief Gets the step of scroll distance in actor coordinates for * each mouse wheel event received in free panning mode. + * * @return The step of scroll distance(pixel) in X and Y axes. */ Vector2 GetMouseWheelScrollDistanceStep() const; /** - * Sets the step of scroll distance in actor coordinates for + * @brief Sets the step of scroll distance in actor coordinates for * each mouse wheel event received in free panning mode. + * * @param[in] step The step of scroll distance(pixel) in X and Y axes. * * @note: If snap points are defined in the rulers, it will always @@ -788,23 +851,24 @@ public: void SetMouseWheelScrollDistanceStep(Vector2 step); /** - * Retrieves current scroll position. + * @brief Retrieves current scroll position. * * @returns The current scroll position. */ Vector3 GetCurrentScrollPosition() const; /** - * Retrieves current scroll scale. + * @brief Retrieves current scroll scale. * * @returns The current scroll scale. */ Vector3 GetCurrentScrollScale() const; /** - * Retrieves current scroll page based on ScrollView dimensions being - * the size of one page, and all pages laid out in a grid fashion, - * increasing from left to right until the end of the X-domain. + * @brief Retrieves current scroll page based on ScrollView + * dimensions being the size of one page, and all pages laid out in + * a grid fashion, increasing from left to right until the end of + * the X-domain. * * @note: Pages start from 0 as the first page, not 1. * @@ -813,7 +877,7 @@ public: unsigned int GetCurrentPage() const; /** - * Transforms View to position, scale and rotation specified + * @brief Transforms View to position, scale and rotation specified. * * @param[in] position The position to transform to. * @param[in] scale The scale to transform to. @@ -822,7 +886,7 @@ public: void TransformTo(const Vector3& position, const Vector3& scale, float rotation); /** - * Transforms View to position, scale and rotation specified + * @brief Transforms View to position, scale and rotation specified. * * @param[in] position The position to transform to. * @param[in] scale The scale to transform to. @@ -832,7 +896,8 @@ public: void TransformTo(const Vector3& position, const Vector3& scale, float rotation, float duration); /** - * Scrolls View to position specified (contents will scroll to this position) + * @brief Scrolls View to position specified (contents will scroll to this position). + * * Position 0,0 is the origin. Increasing X scrolls contents left, while * increasing Y scrolls contents up. * - If Rulers have been applied to the axes, then the contents will scroll until @@ -844,7 +909,8 @@ public: void ScrollTo(const Vector3 &position); /** - * Scrolls View to position specified (contents will scroll to this position) + * @brief Scrolls View to position specified (contents will scroll to this position). + * * Position 0,0 is the origin. Increasing X scrolls contents left, while * increasing Y scrolls contents up. * - If Rulers have been applied to the axes, then the contents will scroll until @@ -857,7 +923,8 @@ public: void ScrollTo(const Vector3 &position, float duration); /** - * Scrolls View to position specified (contents will scroll to this position) + * @brief Scrolls View to position specified (contents will scroll to this position). + * * Position 0,0 is the origin. Increasing X scrolls contents left, while * increasing Y scrolls contents up. * - If Rulers have been applied to the axes, then the contents will scroll until @@ -876,8 +943,9 @@ public: DirectionBias horizontalBias, DirectionBias verticalBias); /** - * Scrolls View to page currently based on assumption that each page is + * @brief Scrolls View to page currently based on assumption that each page is * "(page) * ScrollViewSize.width, 0". + * * @note Should probably be upgraded so that page is an abstract class, that can be * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be * orchestrated in a 2D grid fashion, or variable width. @@ -887,8 +955,9 @@ public: void ScrollTo(unsigned int page); /** - * Scrolls View to page currently based on assumption that each page is + * @brief Scrolls View to page currently based on assumption that each page is * "(page) * ScrollViewSize.width, 0". + * * @note Should probably be upgraded so that page is an abstract class, that can be * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be * orchestrated in a 2D grid fashion, or variable width. @@ -899,8 +968,9 @@ public: void ScrollTo(unsigned int page, float duration); /** - * Scrolls View to page currently based on assumption that each page is + * @brief Scrolls View to page currently based on assumption that each page is * "(page) * ScrollViewSize.width, 0". + * * @note Should probably be upgraded so that page is an abstract class, that can be * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be * orchestrated in a 2D grid fashion, or variable width. @@ -915,7 +985,7 @@ public: void ScrollTo(unsigned int page, float duration, DirectionBias bias); /** - * Scrolls View such that actor appears in the center of the ScrollView. + * @brief Scrolls View such that actor appears in the center of the ScrollView. * * @note Actor must be a direct child of ScrollView, otherwise will * cause an assertion failure. @@ -924,7 +994,7 @@ public: void ScrollTo(Actor& actor); /** - * Scrolls View such that actor appears in the center of the ScrollView. + * @brief Scrolls View such that actor appears in the center of the ScrollView. * * @note Actor must be a direct child of ScrollView, otherwise will * cause an assertion failure. @@ -934,7 +1004,7 @@ public: void ScrollTo(Actor& actor, float duration); /** - * Scrolls View to the nearest snap points as specified by the Rulers. + * @brief Scrolls View to the nearest snap points as specified by the Rulers. * * If already at snap points, then will return false, and not scroll. * @@ -943,14 +1013,14 @@ public: bool ScrollToSnapPoint(); /** - * Scales View to (scale) + * @brief Scales View to (scale). * * @param[in] scale The scale factor the animate to. */ void ScaleTo(const Vector3& scale); /** - * Scales View to (scale) + * @brief Scales View to (scale). * * @param[in] scale The scale factor the animate to. * @param[in] duration The duration of the animation in seconds. @@ -958,15 +1028,15 @@ public: void ScaleTo(const Vector3& scale, float duration); /** - * Applies a constraint that will affect the children of ScrollView + * @brief Applies a constraint that will affect the children of ScrollView. * - * @note this affects all existing, and future Actors that are added to - * scrollview. + * @note this affects all existing and future Actors that are added to scrollview. + * @param[in] constraint The constraint to apply */ void ApplyConstraintToChildren(Constraint constraint); /** - * Removes all constraints that will affect the children of ScrollView + * @brief Removes all constraints that will affect the children of ScrollView. * * @note this removes all constraints from actors that have been added * to scrollview. @@ -974,40 +1044,46 @@ public: void RemoveConstraintsFromChildren(); /** - * Apply Effect to ScrollView + * @brief Apply Effect to ScrollView. + * * @param[in] effect The effect to apply to scroll view */ void ApplyEffect(ScrollViewEffect effect); /** - * ApplyEffect Applies a predefined effect + * @brief ApplyEffect Applies a predefined effect. + * * @param[in] effect enum for the predefined effect + * @return The scrollview effect that was applied */ ScrollViewEffect ApplyEffect(ScrollView::PageEffect effect); /** - * Remove Effect from ScrollView + * @brief Remove Effect from ScrollView. + * * @param[in] effect The effect to remove. */ void RemoveEffect(ScrollViewEffect effect); /** - * Remove All Effects from ScrollView + * @brief Remove All Effects from ScrollView. */ void RemoveAllEffects(); /** - * Binds actor to this ScrollView, once an actor is bound to a ScrollView, - * it'll be subject to that ScrollView's properties. + * @brief Binds actor to this ScrollView. + * + * Once an actor is bound to a ScrollView, it will be subject to + * that ScrollView's properties. * * @param[in] child The actor to add to this ScrollView. */ void BindActor(Actor child); /** - * Unbind Actor from this ScrollView - * Once Unbound, this ScrollView will not affect the actor. + * @brief Unbind Actor from this ScrollView. * + * Once Unbound, this ScrollView will not affect the actor. * @note this does not remove the child from the ScrollView container * * @param[in] child The actor to be unbound. @@ -1015,7 +1091,8 @@ public: void UnbindActor(Actor child); /** - * Allows the user to constrain the scroll view in a particular direction. + * @brief Allows the user to constrain the scroll view in a particular direction. + * * @param[in] direction The axis to constrain the scroll-view to. * Usually set to PanGestureDetector::DIRECTION_VERTICAL or PanGestureDetector::DIRECTION_HORIZONTAL (but can be any other angle if desired). * @param[in] threshold The threshold to apply around the axis. @@ -1024,7 +1101,8 @@ public: void SetScrollingDirection( Radian direction, Radian threshold = PanGestureDetector::DEFAULT_THRESHOLD ); /** - * Remove a direction constraint from the scroll view. + * @brief Remove a direction constraint from the scroll view. + * * @param[in] direction The axis to stop constraining to. * Usually will be PanGestureDetector::DIRECTION_VERTICAL or PanGestureDetector::DIRECTION_HORIZONTAL (but can be any other angle if desired). */ @@ -1033,13 +1111,15 @@ public: public: // Not intended for application developers /** - * Creates a handle using the Toolkit::Internal implementation. + * @brief Creates a handle using the Toolkit::Internal implementation. + * * @param[in] implementation The Control implementation. */ ScrollView(Internal::ScrollView& implementation); /** - * Allows the creation of this Control from an Internal::CustomActor pointer. + * @brief Allows the creation of this Control from an Internal::CustomActor pointer. + * * @param[in] internal A pointer to the internal CustomActor. */ ScrollView( Dali::Internal::CustomActor* internal ); diff --git a/capi/dali-toolkit/public-api/controls/scrollable/scrollable.h b/capi/dali-toolkit/public-api/controls/scrollable/scrollable.h index bdc9e29..5abd3ac 100644 --- a/capi/dali-toolkit/public-api/controls/scrollable/scrollable.h +++ b/capi/dali-toolkit/public-api/controls/scrollable/scrollable.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_SCROLLABLE_MODULE * @{ */ @@ -36,47 +36,57 @@ namespace Internal DALI_INTERNAL class Scrollable; } +/** + * @brief How axes/rotation or scale are clamped + */ enum ClampState { - NotClamped, - ClampedToMin, - ClampedToMax + NotClamped, ///< The quantity isn't clamped + ClampedToMin, ///< The quantity is clamped to the min value + ClampedToMax ///< The quantity is clamped to the max value }; +/** + * @brief A 2 dimensional clamp + */ struct ClampState2 { - ClampState x; - ClampState y; + ClampState x; ///< The clamp state of the x axis + ClampState y; ///< The clamp state of the y axis }; +/** + * @brief A 3 dimensional clamp + */ struct ClampState3 { - ClampState x; - ClampState y; - ClampState z; + ClampState x; ///< The clamp state of the x axis + ClampState y; ///< The clamp state of the y axis + ClampState z; ///< The clamp state of the z axis }; /** - * Base class for derived Scrollables that contains actors that can be scrolled manually - * (via touch) or automatically. Scrollables such as ScrollView and ItemView can be derived - * from this class. + * @brief Base class for derived Scrollables that contains actors that can be scrolled manually + * (via touch) or automatically. + * + * Scrollables such as ScrollView and ItemView can be derived from this class. */ class Scrollable : public Control { public: /** - * Clamp signal event's data + * @brief Clamp signal event's data */ struct ClampEvent { - ClampState3 scale; ///< Clamp information for scale axes - ClampState3 position; ///< Clamp information for position axes - ClampState rotation; ///< Clamp information for rotation + ClampState3 scale; ///< Clamp information for scale axes + ClampState3 position; ///< Clamp information for position axes + ClampState rotation; ///< Clamp information for rotation }; /** - * Scroll component types + * @brief Scroll component types */ enum ScrollComponentType { @@ -93,89 +103,102 @@ public: static const std::string SCROLL_DIRECTION_PROPERTY_NAME; ///< Property, name "scroll-direction", type VECTOR2 //Signal Names - static const char* const SIGNAL_SCROLL_STARTED; - static const char* const SIGNAL_SCROLL_COMPLETED; - static const char* const SIGNAL_SCROLL_UPDATED; - static const char* const SIGNAL_SCROLL_CLAMPED; + static const char* const SIGNAL_SCROLL_STARTED; ///< "scroll-started"; + static const char* const SIGNAL_SCROLL_COMPLETED; ///< "scroll-completed"; + static const char* const SIGNAL_SCROLL_UPDATED; ///< "scroll-updated"; + static const char* const SIGNAL_SCROLL_CLAMPED; ///< "scroll-clamped"; public: - typedef SignalV2< void ( const Vector3& ) > ScrollStartedSignalV2; - - typedef SignalV2< void ( const Vector3& ) > ScrollUpdatedSignalV2; - - typedef SignalV2< void ( const Vector3& ) > ScrollCompletedSignalV2; - - typedef SignalV2< void ( const ClampEvent& ) > ScrollClampedSignalV2; + typedef SignalV2< void ( const Vector3& ) > ScrollStartedSignalV2; ///< ScrollStarted signal type + typedef SignalV2< void ( const Vector3& ) > ScrollCompletedSignalV2; ///< ScrollCompleted signal type + typedef SignalV2< void ( const Vector3& ) > ScrollUpdatedSignalV2; ///< Scroll updated signal type + typedef SignalV2< void ( const ClampEvent& ) > ScrollClampedSignalV2; ///< Scroll clamped signal type /** - * Signal emitted when the Scrollable has moved (whether by touch or animation) + * @brief Signal emitted when the Scrollable has moved (whether by touch or animation). */ ScrollStartedSignalV2& ScrollStartedSignal(); /** - * Signal emitted when the Scrollable has moved (whether by touch or animation) + * @brief Signal emitted when the Scrollable has moved (whether by touch or animation). */ ScrollUpdatedSignalV2& ScrollUpdatedSignal(); /** - * Signal emitted when the Scrollable has completed movement (whether by touch or animation) + * @brief Signal emitted when the Scrollable has completed movement (whether by touch or animation). */ ScrollCompletedSignalV2& ScrollCompletedSignal(); /** - * Signal emitted when the Scrollable is pushing against a domain boundary - * (in either position, scale, or rotation) + * @brief Signal emitted when the Scrollable is pushing against a domain boundary + * (in either position, scale, or rotation). + * + * @return The signal to connect to */ ScrollClampedSignalV2& ScrollClampedSignal(); public: /** - * Creates an uninitialized Scrollable handle + * @brief Creates an uninitialized Scrollable handle. */ Scrollable(); /** - * 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 handle to copy from */ Scrollable( const Scrollable& handle ); /** - * 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 to copy from + * @return A reference to this */ Scrollable& operator=( const Scrollable& handle ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~Scrollable(); /** - * Downcast an Object handle to Scrollable. If handle points to a Scrollable the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to Scrollable. + * + * If handle points to a Scrollable the downcast produces valid + * handle. If not the returned handle is left uninitialized. + * * @param[in] handle Handle to an object * @return handle to a Scrollable or an uninitialized handle */ static Scrollable DownCast( BaseHandle handle ); /** - * Checks if a ScrollComponent has been enabled or not. + * @brief Checks if a ScrollComponent has been enabled or not. + * * @param[in] type The Scroll Component Type to check * @return True (if Enabled) */ bool IsScrollComponentEnabled(Scrollable::ScrollComponentType type) const; /** - * Enables a ScrollComponent + * @brief Enables a ScrollComponent. + * * @param[in] type The Scroll Component Type to enable */ void EnableScrollComponent(Scrollable::ScrollComponentType type); /** - * Disables a ScrollComponent + * @brief Disables a ScrollComponent. + * * @param[in] type The Scroll Component Type to disable */ void DisableScrollComponent(Scrollable::ScrollComponentType type); @@ -183,13 +206,15 @@ public: public: // Not intended for application developers /** - * Creates a handle using the Toolkit::Internal implementation. + * @brief Creates a handle using the Toolkit::Internal implementation. + * * @param[in] implementation The Control implementation. */ Scrollable(Internal::Scrollable& implementation); /** - * Allows the creation of this Control from an Internal::CustomActor pointer. + * @brief Allows the creation of this Control from an Internal::CustomActor pointer. + * * @param[in] internal A pointer to the internal CustomActor. */ Scrollable( Dali::Internal::CustomActor* internal ); diff --git a/capi/dali-toolkit/public-api/controls/super-blur-view/super-blur-view.h b/capi/dali-toolkit/public-api/controls/super-blur-view/super-blur-view.h index c9be8f6..2a6b748 100644 --- a/capi/dali-toolkit/public-api/controls/super-blur-view/super-blur-view.h +++ b/capi/dali-toolkit/public-api/controls/super-blur-view/super-blur-view.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_SUPER_BLUR_VIEW_MODULE * @{ */ @@ -39,7 +39,7 @@ class SuperBlurView; } /** - * SuperBlurView accepts an image as input, and displays/animates it with various blur strength. + * @brief SuperBlurView accepts an image as input, and displays/animates it with various blur strength. * Usage example:- * * // initialise\n @@ -60,39 +60,48 @@ class SuperBlurView : public Control { public: /** - * Signal type for notifications + * @brief Signal type for notifications. */ typedef SignalV2< void (SuperBlurView source) > SuperBlurViewSignal; /** - * Creates an empty SuperBlurView handle + * @brief Creates an empty SuperBlurView handle. */ SuperBlurView(); /** - * Create an initialized SuperBlurView + * @brief Create an initialized SuperBlurView. + * * @param[in] blurLevels The final blur strength level. It decides how many filtering passes are used to create the group of blurred images. * @return A handle to a newly allocated Dali resource */ static SuperBlurView New( unsigned int blurLevels ); /** - * 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] handle the handle to copy from */ SuperBlurView( const SuperBlurView& handle ); /** - * 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] rhs the handle to copy from + * @return a reference to this */ SuperBlurView& operator=( const SuperBlurView& rhs ); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~SuperBlurView(); /** - * Downcast an Object handle to SuperBlurView. + * @brief Downcast an Object handle to SuperBlurView. + * * If handle points to a SuperBlurView, the downcast produces valid handle. * If not, the returned handle is left uninitialized. * @param[in] handle Handle to an object @@ -101,38 +110,46 @@ public: static SuperBlurView DownCast( BaseHandle handle ); /** - * Sets a custom image to be blurred + * @brief Sets a custom image to be blurred. + * * @param[in] inputImage The image that the user wishes to blur */ void SetImage(Image inputImage); /** - * Get the index of the property that can be used to fade the blur in / out. This is the overall strength of the blur. + * @brief Get the index of the property that can be used to fade the blur in / out. + * + * This is the overall strength of the blur. * User can use this to animate the blur. A value of 0.0 is zero blur and 1.0 is full blur. Default is 0.0. * @return Index of the property that can be used to fade the blur in / out */ Property::Index GetBlurStrengthPropertyIndex() const; /** - * Set the blur strength to display the image + * @brief Set the blur strength to display the image. + * * @param[in] blurStrength The blur strength used to display the image. */ void SetBlurStrength( float blurStrength ); /** - * Get the current blur strength + * @brief Get the current blur strength. + * * @return The current blur strength */ float GetCurrentBlurStrength() const; /** - * Connect to this signal to be notified when the all the blurs have completed. + * @brief Connect to this signal to be notified when the all the blurs have completed. + * * @return The BlurFinished signal */ SuperBlurViewSignal& BlurFinishedSignal(); /** - * Get the blurred image. Should wait for the BlurFinishedSignal before calling this method + * @brief Get the blurred image. + * + * Should wait for the BlurFinishedSignal before calling this method. * @param[in] level Indicate which blurred image to get, must be a value between 1 and blurLevels * @return The level-th blurred image */ @@ -141,13 +158,15 @@ public: public: // Not intended for application developers /** - * Creates a handle using the Toolkit::Internal implementation. + * @brief Creates a handle using the Toolkit::Internal implementation. + * * @param[in] implementation The Control implementation. */ DALI_INTERNAL SuperBlurView(Internal::SuperBlurView& implementation); /** - * Allows the creation of this Control from an Internal::CustomActor pointer. + * @brief Allows the creation of this Control from an Internal::CustomActor pointer. + * * @param[in] internal A pointer to the internal CustomActor. */ DALI_INTERNAL SuperBlurView(Dali::Internal::CustomActor* internal); diff --git a/capi/dali-toolkit/public-api/controls/text-input/text-input.h b/capi/dali-toolkit/public-api/controls/text-input/text-input.h index d52b041..6905ecd 100644 --- a/capi/dali-toolkit/public-api/controls/text-input/text-input.h +++ b/capi/dali-toolkit/public-api/controls/text-input/text-input.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_TEXT_INPUT_MODULE * @{ */ @@ -37,7 +37,7 @@ class TextInput; } /** - * TextInput Actor takes input one character at a time and displays it as a string within an input box. + * @brief TextInput Actor takes input one character at a time and displays it as a string within an input box. * Characters can be removed from the end of the string until it is empty. A maximum length of displayed string * can be set. */ @@ -47,93 +47,108 @@ class TextInput : public Control public: //Signal Names - static const char* const SIGNAL_START_INPUT; - static const char* const SIGNAL_END_INPUT; - static const char* const SIGNAL_STYLE_CHANGED; - static const char* const SIGNAL_MAX_INPUT_CHARACTERS_REACHED; - static const char* const SIGNAL_TOOLBAR_DISPLAYED; - static const char* const SIGNAL_TEXT_EXCEED_BOUNDARIES; + static const char* const SIGNAL_START_INPUT; ///< name "start-input" + static const char* const SIGNAL_END_INPUT; ///< name "end-input" + static const char* const SIGNAL_STYLE_CHANGED; ///< name "style-changed" + static const char* const SIGNAL_MAX_INPUT_CHARACTERS_REACHED; ///< name "max-input-characters-reached" + static const char* const SIGNAL_TOOLBAR_DISPLAYED; ///< name "toolbar-displayed" + static const char* const SIGNAL_TEXT_EXCEED_BOUNDARIES; ///< name "text-exceed-boundaries" public: /** - * Create an uninitialized TextInput; this can be initialized with TextView::New() + * @brief Create an uninitialized TextInput; this can be initialized with TextView::New(). + * * Calling member functions with an uninitialized Dali::Object is not allowed. */ TextInput(); /** - * Copy constructor. + * @brief Copy constructor. + * * @param handle to be copied */ TextInput( const TextInput& handle ); /** - * Assignment operator. + * @brief Assignment operator. + * * @param handle to object we want to point to * @return handle to the TextInput */ TextInput& operator=( const TextInput& handle ); /** - * Create an initialised TextInput. + * @brief Create an initialised TextInput. + * * @return A handle to a newly allocated Dali resource. */ static TextInput New(); /** - * Downcast an Object handle to TextInput. If handle points to a TextInput the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to TextInput. + * + * If handle points to a TextInput the downcast produces valid + * handle. If not the returned handle is left uninitialized. + * * @param[in] handle Handle to an object * @return handle to a TextInput or an uninitialized handle */ static TextInput DownCast( BaseHandle handle ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~TextInput(); /** - * Get the inputed text currently being displayed. + * @brief Get the inputed text currently being displayed. + * * @return string, the currently displayed string. */ std::string GetText() const; /** - * Get the inputed text currently being displayed together with mark-up tags. + * @brief Get the inputed text currently being displayed together with mark-up tags. + * * @return string, the currently displayed string with mark-up. */ std::string GetMarkupText() const; /** - * Set the maximum number of characters for the Text Input + * @brief Set the maximum number of characters for the Text Input. + * * @param [in] maxChars the max number of characters */ void SetMaxCharacterLength(std::size_t maxChars); /** - * Limits the number of lines of text Text Input will display + * @brief Limits the number of lines of text Text Input will display. + * * @param [in] maxLines the max number of lines to display, must be greater than 0. * Currently the only valid limit is 1. Which turns TextInput into Single line mode. Any number higher than 1 results in no limit. */ void SetNumberOfLinesLimit(std::size_t maxLines); /** - * Returns the limit of lines Text Input is allowed to display. + * @brief Returns the limit of lines Text Input is allowed to display. + * * @return max line number limit */ std::size_t GetNumberOfLinesLimit() const; /** - * Returns the number of characters TextInput is displaying. + * @brief Returns the number of characters TextInput is displaying. + * * @return number of characters */ std::size_t GetNumberOfCharacters() const; /** - * Sets a place holder text to be displayed when the text-input is empty. + * @brief Sets a place holder text to be displayed when the text-input is empty. + * * If not set or set to an empty string then no place holder will be shown. * @param [in] placeHolderText text to be used as place holder. */ @@ -145,14 +160,16 @@ public: std::string GetPlaceholderText(); /** - * set initial text to be displayed in text-input - * can be used to edit a pre-existing string + * @brief set initial text to be displayed in text-input. + * + * Can be used to edit a pre-existing string. * @param [in] initialText text to be initially displayed */ void SetInitialText(const std::string& initialText); /** - * Manual method to set the focus on the TextInput so it starts or stops edit state + * @brief Manual method to set the focus on the TextInput so it starts or stops edit state. + * * @pre The text input actor has been initialised. * @param[in] editMode true or false to indicate editMode on or off */ @@ -169,14 +186,16 @@ public: void SetEditable(bool editMode, const Vector2& touchPoint); /** - * Check if TextInput is in edit state + * @brief Check if TextInput is in edit state. + * * @pre The text input actor has been initialised. * @return True or False to indicate editMode on or off */ bool IsEditable() const; /** - * Method to enable or disable edit on touch/tap. + * @brief Method to enable or disable edit on touch/tap. + * * If not enabled (set to false) then SetEditable(true) will be used to start edit mode. * @pre The text input actor has been initialised. * @param[in] editOnTouch true or false to indicate if editing should start on touch @@ -185,14 +204,16 @@ public: void SetEditOnTouch(bool editOnTouch = true); /** - * Check if TextInput starts edit mode on touch + * @brief Check if TextInput starts edit mode on touch. + * * @pre The text input actor has been initialised. * @return True or False to indicate editOnTouch on or off */ bool IsEditOnTouch() const; /** - * Check if Text Selection is enabled so required text can be highlighted + * @brief Check if Text Selection is enabled so required text can be highlighted. + * * @pre The text input actor has been initialised. * @param[in] textSelectable true or false to indicate if text can be selected or not * default is for text to be select-able when in edit mode @@ -200,21 +221,24 @@ public: void SetTextSelectable(bool textSelectable = true); /** - * Check if Text can be selected + * @brief Check if Text can be selected. + * * @pre The text input actor has been initialised. * @return True or False to indicate if text can be selected or not */ bool IsTextSelectable() const; /** - * Check if any text is currently selected, can be used to determine if ApplyStyle or SetActiveStyle should be used. + * @brief Check if any text is currently selected, can be used to determine if ApplyStyle or SetActiveStyle should be used. + * * @pre The text input actor has been initialised. * @return True if text selected else False */ bool IsTextSelected() const; /** - * Selects text between the given positions + * @brief Selects text between the given positions. + * * @pre TextInput should be in edit mode. * @param start position to start selection * @param end position to end selection, inclusive of this character. @@ -223,20 +247,23 @@ public: void SelectText(std::size_t start, std::size_t end); /** - * If any text is selected then de-select it and hide highlight. + * @brief If any text is selected then de-select it and hide highlight. + * * @pre The text input actor has been initialised. */ void DeSelectText(); /** - * Set the image to be used as the cursor grab hander + * @brief Set the image to be used as the cursor grab hander. + * * @pre The text input actor has been initialised. * @param[in] image The image to be used. */ void SetGrabHandleImage( Image image ); /** - * Set the image to be used for the regular left to right cursor + * @brief Set the image to be used for the regular left to right cursor. + * * @pre The text input actor has been initialised. * @param[in] image The image to be used. * @param[in] border The nine patch border for the image. @@ -244,13 +271,16 @@ public: void SetCursorImage(Dali::Image image, const Vector4& border ); /** - * Retrieve the selection handle size. Both handles have same size. + * @brief Retrieve the selection handle size. + * + * Both handles have same size. * @return Vector3 the selection handle size. */ Vector3 GetSelectionHandleSize(); /** - * Set the image to be used for the Right to Left cursor + * @brief Set the image to be used for the Right to Left cursor. + * * @pre The text input actor has been initialised. * @param[in] image The image to be used. * @param[in] border The nine patch border for the image. @@ -258,20 +288,23 @@ public: void SetRTLCursorImage(Dali::Image image, const Vector4& border ); /** - * Toggle to enable the grab handle, used to position cursor when magnifier not being used. + * @brief Toggle to enable the grab handle, used to position cursor when magnifier not being used. + * * Default behaviour is to use the magnifier to position the cursor, enabling this prevents the magnifier from being shown. * @param[in] toggle true to enable, false to disable grab handle */ void EnableGrabHandle(bool toggle); /** - * Method to check if grab handle is enabled, if false then the magnifier will be used to position cursor. + * @brief Method to check if grab handle is enabled, if false then the magnifier will be used to position cursor. + * * @return bool returns true is grab handle enabled. */ bool IsGrabHandleEnabled(); /** - * Set the bounding rectangle which handles, popup and similar decorations will not exceed + * @brief Set the bounding rectangle which handles, popup and similar decorations will not exceed. + * * The default value is the width and height of the stage from the top left origin. * If a title bar for example is on the top of the screen then the y should be the title's height and * the boundary height the stage height minus the title's height. @@ -290,14 +323,16 @@ public: void SetBoundingRectangle( const Rect& boundingOriginAndSize ); /** - * Retrieve the bounding box origin and dimensions + * @brief Retrieve the bounding box origin and dimensions. + * * default is set once control is added to stage, before this the return vector will be Vector4:ZERO * @return Rect the bounding rectangle */ const Rect GetBoundingRectangle() const; /** - * Sets the style for new text being typed. + * @brief Sets the style for new text being typed. + * * By default all style settings are applied but a bit mask could be used to modify only certain style settings. * @pre The text input actor has been initialised. * @param[in] style The style for the new text. @@ -306,7 +341,8 @@ public: void SetActiveStyle( const TextStyle& style, const TextStyle::Mask mask = TextStyle::ALL ); /** - * Applies the given style to the selected text. + * @brief Applies the given style to the selected text. + * * By default all style settings are applied but a bit mask could be used to modify only certain style settings. * Introduced text after this call uses the new style. * @param[in] style The given style. @@ -315,7 +351,8 @@ public: void ApplyStyle( const TextStyle& style, const TextStyle::Mask mask = TextStyle::ALL ); /** - * Applies the given style to all text, selected or not selected. + * @brief Applies the given style to all text, selected or not selected. + * * By default all style settings are applied but a bit mask could be used to modify only certain style settings. * @param[in] style The given style. * @param[in] mask The bit mask. @@ -323,14 +360,15 @@ public: void ApplyStyleToAll( const TextStyle& style, const TextStyle::Mask mask = TextStyle::ALL ); /** - * Get the style of the Text character before the cursor + * @brief Get the style of the Text character before the cursor. + * * If no character before then return the InputStyle. * @return TextStyle, the style of the character before the cursor */ TextStyle GetStyleAtCursor() const; /** - * Set the current text alignment (overrides default setting) + * @brief Set the current text alignment (overrides default setting). * * The default alignment is dependent on the current text in the text field. * If the text begins using LTR characters (e.g. European text) then the @@ -343,7 +381,8 @@ public: void SetTextAlignment( Toolkit::Alignment::Type align ); /** - * Set the current line justification. (overrides default setting) + * @brief Set the current line justification. (overrides default setting). + * * The default justification is dependent on the current text in the text field. * If the text begins using LTR characters (e.g. European text) then the * justification is HorizontalLeft. If the text begins using RTL characters @@ -355,7 +394,7 @@ public: void SetTextLineJustification( Toolkit::TextView::LineJustification justification ); /** - * Sets a fade boundary. + * @brief Sets a fade boundary. * * @see TextView::FadeBoundary. * @@ -364,7 +403,7 @@ public: void SetFadeBoundary( const Toolkit::TextView::FadeBoundary& fadeBoundary ); /** - * Retrieves the fade boundary. + * @brief Retrieves the fade boundary. * * @see TextView::FadeBoundary. * @@ -373,50 +412,58 @@ public: const Toolkit::TextView::FadeBoundary& GetFadeBoundary() const; /** - * Get the current text alignment combined into a single value. + * @brief Get the current text alignment combined into a single value. + * * The values can be tested by using the & operator * and the desired flag. e.g. if (GetTextAlignment() & HorizontalCentre) ... + * @return The combined text alignment */ Toolkit::Alignment::Type GetTextAlignment() const; /** - * Sets how to split the text in lines policy. + * @brief Sets how to split the text in lines policy. + * * @param policy The multi-line policy. */ void SetMultilinePolicy( Toolkit::TextView::MultilinePolicy policy ); /** - * Gets the split in lines policy. + * @brief Gets the split in lines policy. + * * @return The multi-line policy. */ Toolkit::TextView::MultilinePolicy GetMultilinePolicy() const; /** - * Sets how to display the text inside the TextView when it exceeds the text-view's width. + * @brief Sets how to display the text inside the TextView when it exceeds the text-view's width. + * * @param policy The exceed policy. */ void SetWidthExceedPolicy( Toolkit::TextView::ExceedPolicy policy ); /** - * Gets the width exceed policy. + * @brief Gets the width exceed policy. + * * @return The exceed policy. */ TextView::ExceedPolicy GetWidthExceedPolicy() const; /** - * Sets how to display the text inside the TextView when it exceeds the text-view's height. + * @brief Sets how to display the text inside the TextView when it exceeds the text-view's height. + * * @param policy The exceed policy. */ void SetHeightExceedPolicy( Toolkit::TextView::ExceedPolicy policy ); /** - * Gets the height exceed policy. + * @brief Gets the height exceed policy. + * * @return The exceed policy. */ TextView::ExceedPolicy GetHeightExceedPolicy() const; /** - * Sets if the inputed text can exceed the text-input boundary. + * @brief Sets if the inputed text can exceed the text-input boundary. * * By default is enabled. * @@ -425,14 +472,14 @@ public: void SetExceedEnabled( bool enable ); /** - * Retrieves whether inputed text can exceed the text-input boundary. + * @brief Retrieves whether inputed text can exceed the text-input boundary. * * @return \e true if text inputed can exceed the boundary, otherwise \e false. */ bool GetExceedEnabled() const; /** - * Allows modification of text-actor's position in the depth sort algorithm. + * @brief Allows modification of text-actor's position in the depth sort algorithm. * * @see Dali::RenderableActor::SetSortModifier() * @param [in] depthOffset the offset to be given to the internal text-actors. Positive values pushing it further back. @@ -440,7 +487,7 @@ public: void SetSortModifier( float depthOffset ); /** - * Sets whether text-view renders text using a previously generated snapshot. + * @brief Sets whether text-view renders text using a previously generated snapshot. * * @see TextView::SetSnapshotModeEnabled() * @@ -449,7 +496,7 @@ public: void SetSnapshotModeEnabled( bool enable ); /** - * Retrieves whether text-view is using a snapshot to render text + * @brief Retrieves whether text-view is using a snapshot to render text. * * @see TextView::IsSnapshotModeEnabled() * @@ -479,59 +526,71 @@ public: public: /* Signals */ - // Input Signal + /// @brief Input Signal. typedef SignalV2< void ( TextInput textInput ) > InputSignalV2; - // Input style changed signal + /// @brief Input style changed signal. typedef SignalV2< void ( TextInput textInput, const TextStyle& style ) > StyleChangedSignalV2; - // Max input characters reached signal + /// @brief Max input characters reached signal. typedef SignalV2< void ( TextInput textInput ) > MaxInputCharactersReachedSignalV2; - // Input text exceeds boundaries signal + /// @brief Input text exceeds boundaries signal. typedef SignalV2< void ( TextInput textInput ) > InputTextExceedBoundariesSignalV2; /** - * Signal emitted when the Text-Input starts receiving input. + * @brief Signal emitted when the Text-Input starts receiving input. */ InputSignalV2& InputStartedSignal(); /** - * Signal emitted when the Text-Input is finished receiving input. + * @brief Signal emitted when the Text-Input is finished receiving input. + * * TextInput::GetText() can be called to get current text string. + * @return The signal to connect to */ InputSignalV2& InputFinishedSignal(); /** - * Signal emitted when the cut and paste toolbar is displayed. + * @brief Signal emitted when the cut and paste toolbar is displayed. + * + * @return The signal to connect to */ InputSignalV2& CutAndPasteToolBarDisplayedSignal(); /** - * Signal emitted when style changes. + * @brief Signal emitted when style changes. + * + * @return The signal to connect to */ StyleChangedSignalV2& StyleChangedSignal(); /** - * Signal emitted when max input characters are reached during text input. + * @brief Signal emitted when max input characters are reached during text input. + * + * @return The signal to connect to */ MaxInputCharactersReachedSignalV2& MaxInputCharactersReachedSignal(); /** - * Signal emitted when input text exceeds the boundaries of the text-input. + * @brief Signal emitted when input text exceeds the boundaries of the text-input. + * + * @return The signal to connect to */ InputTextExceedBoundariesSignalV2& InputTextExceedBoundariesSignal(); public: // Not intended for application developers /** - * Creates a handle using the Toolkit::Internal implementation. + * @brief Creates a handle using the Toolkit::Internal implementation. + * * @param[in] implementation The Control implementation. */ TextInput(Internal::TextInput& implementation); /** - * Allows the creation of this Control from an Internal::CustomActor pointer. + * @brief Allows the creation of this Control from an Internal::CustomActor pointer. + * * @param[in] internal A pointer to the internal CustomActor. */ TextInput(Dali::Internal::CustomActor* internal ); diff --git a/capi/dali-toolkit/public-api/controls/text-view/text-view.h b/capi/dali-toolkit/public-api/controls/text-view/text-view.h index 1e866dd..30ae3bc 100644 --- a/capi/dali-toolkit/public-api/controls/text-view/text-view.h +++ b/capi/dali-toolkit/public-api/controls/text-view/text-view.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_TEXT_VIEW_MODULE * @{ */ @@ -41,7 +41,7 @@ class TextView; } /** - * TextView is a layout container with alignment, multi-line wrapping and formatting support. + * @brief TextView is a layout container for text with alignment, multi-line wrapping and formatting support. * * Different multi-line and exceed policies could be chosen to represent the given text. * \see Toolkit::TextView::SetMultilinePolicy \see Toolkit::TextView::SetExceedPolicy @@ -104,36 +104,36 @@ public: static const char* const SIGNAL_TEXT_SCROLLED; ///< Signal emitted when the scroll position changes. @see SignalScrolled() /** - * Structure used to retrieve Layout info per character. + * @brief Structure used to retrieve Layout info per character. */ struct CharacterLayoutInfo { /** - * Default constructor. + * @brief Default constructor. * * Initializes all members to their default values. */ CharacterLayoutInfo(); /** - * Empty destructor. + * @brief Empty destructor. * * @note Added to increase coverage. */ ~CharacterLayoutInfo(); /** - * Copy constructor. + * @brief Copy constructor. */ CharacterLayoutInfo( const CharacterLayoutInfo& characterLayoutInfo ); /** - * Assignment operator. + * @brief Assignment operator. */ CharacterLayoutInfo& operator=( const CharacterLayoutInfo& character ); /** - * Constructor. + * @brief Constructor. * * @param[in] size of the character. * @param[in] position of the character. @@ -157,10 +157,10 @@ public: float mDescender; ///< The character's descender which is the distance from the baseline to the bottom of the character }; - typedef std::vector CharacterLayoutInfoContainer; + typedef std::vector CharacterLayoutInfoContainer; ///< Container of Character layouts /** - * Stores some info about a laid-out line. + * @brief Stores some info about a laid-out line. */ struct LineLayoutInfo { @@ -168,29 +168,33 @@ public: Size mSize; ///< Size of the current laid-out line. float mAscender; ///< The max ascender of the current laid-out line. }; - typedef std::vector LineLayoutInfoContainer; + typedef std::vector LineLayoutInfoContainer; ///< Container of line layouts + + /** + * @brief How text is laid out. + */ struct TextLayoutInfo { /** - * Default constructor. + * @brief Default constructor. */ TextLayoutInfo(); /** - * Empty destructor + * @brief Empty destructor. * * @note Added to increase coverage. */ ~TextLayoutInfo(); /** - * Copy constructor. + * @brief Copy constructor. */ TextLayoutInfo( const TextLayoutInfo& textLayoutInfo ); /** - * Assignment operator. + * @brief Assignment operator. */ TextLayoutInfo& operator=( const TextLayoutInfo& textLayoutInfo ); @@ -203,20 +207,23 @@ public: }; /** - * It represents a fade boundary. + * @brief This structure represents a fade boundary. + * * If Exceed policy is set to Fade all text which does not fit within the text-view fade boundary is faded out. Text which exceeds the text-view boundary becomes invisible. * The \e left, \e right, \e top and \e bottom values are positive, in pixels and set the distances between the text-view and fade boundaries. */ struct FadeBoundary { /** - * Default constructor. + * @brief Default constructor. + * * Initializes all values to 0. It means no fade boundary. */ FadeBoundary(); /** - * Constructor. + * @brief Constructor. + * * Initializes the fade boundary with the given values. * * @param[in] left value in pixels. @@ -226,14 +233,15 @@ public: */ FadeBoundary( PixelSize left, PixelSize right, PixelSize top, PixelSize bottom ); - PixelSize mLeft; - PixelSize mRight; - PixelSize mTop; - PixelSize mBottom; + PixelSize mLeft; ///< The left fade boundary + PixelSize mRight; ///< The right fade boundary + PixelSize mTop; ///< The top fade boundary + PixelSize mBottom; ///< The bottom fade bounday }; /** - * Define how to split the text in lines. + * @brief Define how to split the text in lines. + * * SplitByNewLineChar will split the text in lines when a '\\n' character is found. * SplitByWord has effect only when TextView size is assigned. * It will split the text in lines when a '\\n' character is found or if a line exceeds the TextView's boundary. This option won't split a word in two. @@ -249,7 +257,8 @@ public: }; /** - * Define how to display the text when it doesn't fit inside the TextView. + * @brief Define how to display the text when it doesn't fit inside the TextView. + * * The default value is ShrinkToFit. */ enum ExceedPolicy @@ -263,7 +272,8 @@ public: }; /** - * Define how to justify lines inside the text area. + * @brief Define how to justify lines inside the text area. + * * The default value is Left. */ enum LineJustification @@ -276,29 +286,39 @@ public: public: /** - * Create an TextView handle; this can be initialised with TextView::New() + * @brief Create an TextView handle; this can be initialised with TextView::New(). + * * Calling member functions with an uninitialised Dali::Object handle is not allowed. */ TextView(); /** - * 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] handle The handle to copy from */ TextView( const TextView& handle ); /** - * 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 The handle to copy from + * @return a reference to this */ TextView& operator=( const TextView& handle ); /** - * Create a TextView control with no text + * @brief Create a TextView control with no text. + * * @return A handle the TextView control. */ static TextView New(); /** - * Create a TextView control. + * @brief Create a TextView control. + * * @param[in] text to display. * @return A handle the TextView control. */ @@ -310,7 +330,9 @@ public: static TextView New( const MarkupProcessor::StyledTextArray& text ); /** - * Downcast an Object handle to TextView. If handle points to a TextView the + * @brief Downcast an Object handle to TextView. + * + * If handle points to a TextView the * downcast produces valid handle. If not the returned handle is left uninitialized. * @param[in] handle Handle to an object * @return handle to a TextView or an uninitialized handle @@ -318,25 +340,28 @@ public: static TextView DownCast( BaseHandle handle ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~TextView(); /** - * Replace the current text with a new text string. + * @brief Replace the current text with a new text string. + * * @param[in] text to display. The string may contain style tags. */ void SetText( const std::string& text ); /** - * Replace the current text with a new text string with style. + * @brief Replace the current text with a new text string with style. + * * @param[in] text with style to display. */ void SetText( const MarkupProcessor::StyledTextArray& text ); /** - * Inserts the given text in the specified position + * @brief Inserts the given text in the specified position. * * @param[in] position Where the given text is going to be added. * @param[in] text The text to be added. @@ -349,7 +374,7 @@ public: void InsertTextAt( std::size_t position, const MarkupProcessor::StyledTextArray& text ); /** - * Replaces part of the text. + * @brief Replaces part of the text. * * It removes the specified number of characters from the given position and inserts the given text in the same specified position. * @@ -365,7 +390,7 @@ public: void ReplaceTextFromTo( std::size_t position, std::size_t numberOfCharacters, const MarkupProcessor::StyledTextArray& text ); /** - * Removes the specified number of characters from the given position. + * @brief Removes the specified number of characters from the given position. * * @param[in] position of the first character to be removed. * @param[in] numberOfCharacters number of characters to be removed. @@ -373,26 +398,30 @@ public: void RemoveTextFrom( std::size_t position, std::size_t numberOfCharacters ); /** - * Get the currently displayed text. + * @brief Get the currently displayed text. + * * @return The currently displayed text. */ std::string GetText() const; /** - * Sets a line height offset. + * @brief Sets a line height offset. + * * The line height offset will be added to the font line height. * @param [in] offset The height offset in PointSize units. */ void SetLineHeightOffset( PointSize offset ); /** - * Retrieves the line height offset. + * @brief Retrieves the line height offset. + * * @return The line height offset in PointSize units. */ PointSize GetLineHeightOffset() const; /** - * Sets the given style to the current text. + * @brief Sets the given style to the current text. + * * By default all style settings are applied but a bit mask could be used to modify only certain style settings. * @note TextView doesn't store a copy of the given style, it applies the given style to the current text only. * Subsequent calls to SetText() will override any style set by this method. @@ -402,69 +431,80 @@ public: void SetStyleToCurrentText( const TextStyle& style, TextStyle::Mask mask = TextStyle::ALL ); /** - * Set the current text alignment. + * @brief Set the current text alignment. + * * Default alignment is (HorizontalCenter | VerticalCenter) * @param[in] align The new alignment option. */ void SetTextAlignment( Alignment::Type align ); /** - * Get the current text alignment combined into a single value. + * @brief Get the current text alignment combined into a single value. + * * The values can be tested by using the & operator * and the desired flag. e.g. if (GetTextAlignment() & HorizontalCentre) ... + * @return the combined alignment */ Alignment::Type GetTextAlignment() const; /** - * Sets how to split the text in lines policy. + * @brief Sets how to split the text in lines policy. + * * @param policy The multi-line policy. SplitByNewLineChar is set by default. */ void SetMultilinePolicy( MultilinePolicy policy ); /** - * Gets the split in lines policy. + * @brief Gets the split in lines policy. + * * @return The multi-line policy. */ MultilinePolicy GetMultilinePolicy() const; /** - * Sets how to display the text inside the TextView when it exceeds the text-view's width. + * @brief Sets how to display the text inside the TextView when it exceeds the text-view's width. + * * @param policy The exceed policy. Original is set by default. */ void SetWidthExceedPolicy( ExceedPolicy policy ); /** - * Gets the width exceed policy. + * @brief Gets the width exceed policy. + * * @return The exceed policy. */ ExceedPolicy GetWidthExceedPolicy() const; /** - * Sets how to display the text inside the TextView when it exceeds the text-view's height. + * @brief Sets how to display the text inside the TextView when it exceeds the text-view's height. + * * @param policy The exceed policy. Original is set by default. */ void SetHeightExceedPolicy( ExceedPolicy policy ); /** - * Gets the height exceed policy. + * @brief Gets the height exceed policy. + * * @return The exceed policy. */ ExceedPolicy GetHeightExceedPolicy() const; /** - * Sets how to justify lines inside the text area. + * @brief Sets how to justify lines inside the text area. + * * @param justification The line justification. Left is set by default. */ void SetLineJustification( LineJustification justification ); /** - * Gets the line justification. + * @brief Gets the line justification. + * * @return The line justification. */ LineJustification GetLineJustification() const; /** - * Sets a fade boundary. + * @brief Sets a fade boundary. * * @see FadeBoundary. * @@ -473,7 +513,7 @@ public: void SetFadeBoundary( const FadeBoundary& fadeBoundary ); /** - * Retrieves the fade boundary. + * @brief Retrieves the fade boundary. * * @see FadeBoundary. * @@ -482,28 +522,28 @@ public: const FadeBoundary& GetFadeBoundary() const; /** - * Sets the ellipsize text. + * @brief Sets the ellipsize text. * * @param[in] ellipsizeText The new text. The string may contain style tags. By default the ellipsize text is '...' */ void SetEllipsizeText( const std::string& ellipsizeText ); /** - * Sets the ellipsize text. + * @brief Sets the ellipsize text. * * @param[in] ellipsizeText The new text with its style. */ void SetEllipsizeText( const MarkupProcessor::StyledTextArray& ellipsizeText ); /** - * Retrieves the ellipsize text. + * @brief Retrieves the ellipsize text. * * @return The ellipsize text. */ std::string GetEllipsizeText() const; /** - * A mechanism to retrieve layout information from the TextView. + * @brief A mechanism to retrieve layout information from the TextView. * * It produces a vector of CharcterLayoutInfo structures which describe the size and position of each character, * two vectors which maps the logical and visual positions of the characters in a bidirectional text, the size @@ -516,7 +556,7 @@ public: void GetTextLayoutInfo( TextLayoutInfo& textLayoutInfo ); /** - * Allows modification of text-actor's position in the depth sort algorithm. + * @brief Allows modification of text-actor's position in the depth sort algorithm. * * @see Dali::RenderableActor::SetSortModifier() * @param [in] depthOffset the offset to be given to the internal text-actors. Positive values pushing it further back. @@ -524,7 +564,7 @@ public: void SetSortModifier( float depthOffset ); /** - * Sets whether text-view renders text using a previously generated snapshot. + * @brief Sets whether text-view renders text using a previously generated snapshot. * * Rendering long text using a snapshot may increase performance. The default value is \e true (render using a snapshot). * @@ -533,14 +573,14 @@ public: void SetSnapshotModeEnabled( bool enable ); /** - * Retrieves whether text-view is using a snapshot to render text + * @brief Retrieves whether text-view is using a snapshot to render text. * * @return \e true if text-view is using a snapshot to render text, otherwhise it returns \e false. */ bool IsSnapshotModeEnabled() const; /** - * Enables or disables the text scroll. + * @brief Enables or disables the text scroll. * * When scroll is enabled, snapshot mode will be enabled automatically. Equally, if scroll is disabled * the snapshot mode is restored to the previous value. @@ -550,14 +590,14 @@ public: void SetScrollEnabled( bool enable ); /** - * Retrieves whether the text scroll is enabled. + * @brief Retrieves whether the text scroll is enabled. * * @return \e true if the scroll is enabled. */ bool IsScrollEnabled() const; /** - * Sets a new scroll position. + * @brief Sets a new scroll position. * * The new scroll position set could be trimmed if the text doesn't cover the whole text-view. * i.e. If a text-view is 100x100 and a text is 200x100 a scroll position beyond 50x0 will be trimmed to 50x0. @@ -571,25 +611,25 @@ public: void SetScrollPosition( const Vector2& position ); /** - * Recrieves current scroll position. + * @brief Recrieves current scroll position. * * @return The scroll position. */ const Vector2& GetScrollPosition() const; /** - * Whether the last scroll position set was trimmed. + * @brief Whether the last scroll position set was trimmed. * * @return \e true if the last scroll position set was trimmed, otherwise \e false. */ bool IsScrollPositionTrimmed() const; public: - // Signals + /// @brief Signal types typedef SignalV2< void ( TextView textView, Vector2 scrollDelta ) > ScrolledSignalV2; /** - * Signal emitted when the scroll position changes. + * @brief Signal emitted when the scroll position changes. * * A callback with the following prototype can be connected to this signal. * @@ -597,19 +637,22 @@ public: * * \e textView is the handle of the text-view emitting the signal. * \e scrollDelta is the differente of the current scroll position with the previous one. + * @return The signal to connect to */ ScrolledSignalV2& ScrolledSignal(); public: // Not intended for application developers /** - * Creates a handle using the Toolkit::Internal implementation. + * @brief Creates a handle using the Toolkit::Internal implementation. + * * @param[in] implementation The Control implementation. */ TextView( Internal::TextView& implementation ); /** - * Allows the creation of this Control from an Internal::CustomActor pointer. + * @brief Allows the creation of this Control from an Internal::CustomActor pointer. + * * @param[in] internal A pointer to the internal CustomActor. */ TextView( Dali::Internal::CustomActor* internal ); diff --git a/capi/dali-toolkit/public-api/enums.h b/capi/dali-toolkit/public-api/enums.h index 436751e..6b221de 100644 --- a/capi/dali-toolkit/public-api/enums.h +++ b/capi/dali-toolkit/public-api/enums.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_MODULE * @{ */ @@ -28,14 +28,20 @@ namespace Dali DALI_IMPORT_API { +/** + * @brief DALi Toolkit namespace. + */ namespace Toolkit { +/** + * @brief Control Orientation namespace. + */ namespace ControlOrientation { /** - * The internal orientation a control. + * @brief The internal orientation of a control. */ enum Type { @@ -48,14 +54,16 @@ enum Type } // namespace ControlOrientation /** - * Query whether an orientation is vertical. + * @brief Query whether an orientation is vertical. + * * @param[in] orientation The orientation. * @return True if the orientation is vertical. */ bool IsVertical(ControlOrientation::Type orientation); /** - * Query whether an orientation is horizontal. + * @brief Query whether an orientation is horizontal. + * * @param[in] orientation The orientation. * @return True if the orientation is horizontal. */ diff --git a/capi/dali-toolkit/public-api/factory/localized-control-factory.h b/capi/dali-toolkit/public-api/factory/localized-control-factory.h index fcb42c3..d899c6d 100644 --- a/capi/dali-toolkit/public-api/factory/localized-control-factory.h +++ b/capi/dali-toolkit/public-api/factory/localized-control-factory.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_FACTORY_MODULE * @{ */ @@ -37,8 +37,8 @@ class LocalizedControlFactory; } /** - * LocalizedControlFactory - * This class provides functionality for creating controls which have localized text. + * @brief This class provides functionality for creating controls which have localized text. + * * This class keeps track of objects created using its factory methods, and updates them * when the system language changes. * @@ -47,12 +47,12 @@ class LocalizedControlFactory; * localized text when language/locale changes. */ - class LocalizedControlFactory : public BaseHandle - { - public: +class LocalizedControlFactory : public BaseHandle +{ +public: /** - * Creates a localized TextView, which is automatically updated when the locale or language changes. + * @brief Creates a localized TextView, which is automatically updated when the locale or language changes. * * @pre The LocalizedControlFactory has been initialized. * @@ -60,6 +60,7 @@ class LocalizedControlFactory; * @param textDomain The text domain for the localized text. Eg "sys_string" * @param textViewTheme A string containing style info about various properties of TextView for different * locale/language. + * @return handle to a new localized TextView */ static Dali::Toolkit::TextView CreateLocalizedTextView( const std::string& textID, const std::string& textDomain = "sys_string", const std::string& textViewTheme = "{}" ); @@ -67,24 +68,27 @@ class LocalizedControlFactory; private: /** - * Create a LocalizedControlFactory handle; this can be initialised with LocalizedControlFactory::New() + * @brief Create a LocalizedControlFactory handle; this can be initialised with LocalizedControlFactory::New(). + * * Calling member functions with an uninitialised handle is not allowed. */ LocalizedControlFactory(); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~LocalizedControlFactory(); /** - * Get the singleton of LocalizedControlFactory object. + * @brief Get the singleton of LocalizedControlFactory object. + * * @return A handle to the LocalizedControlFactory control. */ static LocalizedControlFactory Get(); /** - * Allows the creation of this Control from an Internal::LocalizedControlFactory pointer. + * @brief Allows the creation of this Control from an Internal::LocalizedControlFactory pointer. + * * @param[in] impl A pointer to the internal LocalizedControlFactory. */ LocalizedControlFactory(Internal::LocalizedControlFactory *impl); diff --git a/capi/dali-toolkit/public-api/focus-manager/focus-manager.h b/capi/dali-toolkit/public-api/focus-manager/focus-manager.h index 970eb9a..7f3b31e 100644 --- a/capi/dali-toolkit/public-api/focus-manager/focus-manager.h +++ b/capi/dali-toolkit/public-api/focus-manager/focus-manager.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_FOCUS_MANAGER_MODULE * @{ */ @@ -37,23 +37,28 @@ class FocusManager; } /** - * FocusManager + * @brief Manages registration of actors in a focus chain and changing the focused + * actor within that chain. + * * This class provides the functionality of registering the focus order and description - * of actors and maintaining the focus chain. It provides functionality of setting the + * of actors and maintaining the focus chain. + * + * It provides functionality of setting the * focus and moving the focus forward and backward. It also draws a highlight for the * focused actor and emits a signal when the focus is changed. */ - class FocusManager : public BaseHandle - { - public: +class FocusManager : public BaseHandle +{ +public: // Signal Names - static const char* const SIGNAL_FOCUS_CHANGED; - static const char* const SIGNAL_FOCUS_OVERSHOT; - static const char* const SIGNAL_FOCUSED_ACTOR_ACTIVATED; + static const char* const SIGNAL_FOCUS_CHANGED; ///< name "focus-changed" + static const char* const SIGNAL_FOCUS_OVERSHOT; ///< name "focus-overshot" + static const char* const SIGNAL_FOCUSED_ACTOR_ACTIVATED; ///< name "focused-actor-activated" /** - * Accessibility needs four information which will be read by screen-reader. + * @brief Accessibility needs four information which will be read by screen-reader. + * * Reading order : Label -> Trait -> Optional (Value and Hint) */ enum AccessibilityAttribute @@ -62,45 +67,51 @@ class FocusManager; ACCESSIBILITY_TRAIT, ///< Description of ui-control trait ACCESSIBILITY_VALUE, ///< Current value of ui-control (Optional) ACCESSIBILITY_HINT, ///< Hint for action (Optional) - ACCESSIBILITY_ATTRIBUTE_NUM + ACCESSIBILITY_ATTRIBUTE_NUM ///< Number of attributes }; + /** + * @brief Overshoot direction. + */ enum FocusOvershotDirection { OVERSHOT_PREVIOUS = -1, ///< Try to move previous of the first actor - OVERSHOT_NEXT = 1, ///< Try to move next of the last actor + OVERSHOT_NEXT = 1, ///< Try to move next of the last actor }; public: - //Focus changed signal + /// @brief Focus changed signal typedef SignalV2< void ( Actor, Actor ) > FocusChangedSignalV2; - //Focus overshooted signal + /// @brief Focus overshooted signal typedef SignalV2< void ( Actor, FocusOvershotDirection ) > FocusOvershotSignalV2; - //Focused actor activated signal + /// @brief Focused actor activated signal typedef SignalV2< void ( Actor ) > FocusedActorActivatedSignalV2; /** - * Create a FocusManager handle; this can be initialised with FocusManager::New() + * @brief Create a FocusManager handle; this can be initialised with FocusManager::New(). + * * Calling member functions with an uninitialised handle is not allowed. */ FocusManager(); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~FocusManager(); /** - * Get the singleton of FocusManager object. + * @brief Get the singleton of FocusManager object. + * * @return A handle to the FocusManager control. */ static FocusManager Get(); /** - * Set the information of the specified actor's accessibility attribute. + * @brief Set the information of the specified actor's accessibility attribute. + * * @pre The FocusManager has been initialized. * @pre The Actor has been initialized. * @param actor The actor the text to be set with @@ -110,7 +121,8 @@ class FocusManager; void SetAccessibilityAttribute(Actor actor, AccessibilityAttribute type, const std::string& text); /** - * Get the text of the specified actor's accessibility attribute. + * @brief Get the text of the specified actor's accessibility attribute. + * * @pre The FocusManager has been initialized. * @pre The Actor has been initialized. * @param actor The actor to be queried @@ -120,13 +132,18 @@ class FocusManager; std::string GetAccessibilityAttribute(Actor actor, AccessibilityAttribute type) const; /** - * Set the focus order of the actor. The focus order of each actor in the focus chain - * is unique. If there is another actor assigned with the same focus order already, - * the new actor will be inserted to the focus chain with that focus order, and the - * focus order of the original actor and all the actors followed in the focus chain - * will be increased accordingly. If the focus order assigned to the actor is 0, it - * means that actor's focus order is undefined (e.g. the actor has a description but - * with no focus order being set yet) and therefore that actor is not focusable. + * @brief Set the focus order of the actor. + * + * The focus order of each actor in the focus chain is unique. If + * there is another actor assigned with the same focus order + * already, the new actor will be inserted to the focus chain with + * that focus order, and the focus order of the original actor and + * all the actors followed in the focus chain will be increased + * accordingly. If the focus order assigned to the actor is 0, it + * means that actor's focus order is undefined (e.g. the actor has a + * description but with no focus order being set yet) and therefore + * that actor is not focusable. + * * @pre The FocusManager has been initialized. * @pre The Actor has been initialized. * @param actor The actor the focus order to be set with @@ -135,8 +152,11 @@ class FocusManager; void SetFocusOrder(Actor actor, const unsigned int order); /** - * Get the focus order of the actor. When the focus order is 0, it means the focus order - * of the actor is undefined. + * @brief Get the focus order of the actor. + * + * When the focus order is 0, it means the focus order of the actor + * is undefined. + * * @pre The FocusManager has been initialized. * @pre The Actor has been initialized. * @param actor The actor to be queried @@ -145,28 +165,42 @@ class FocusManager; unsigned int GetFocusOrder(Actor actor) const; /** - * Generates a new focus order number which can be used to assign to actors which need to be - * appended to the end of the current focus order chain. The new number will be an increment - * over the very last focus order number in the focus chain. If the focus chain is empty then - * the function returns 1, else the number returned will be FOLast + 1 where FOLast is the focus - * order of the very last control in the focus chain. + * @brief Generates a new focus order number which can be used to + * assign to actors which need to be appended to the end of the + * current focus order chain. + * + * The new number will be an increment over the very last focus + * order number in the focus chain. If the focus chain is empty then + * the function returns 1, else the number returned will be FOLast + + * 1 where FOLast is the focus order of the very last control in the + * focus chain. + * * @pre The FocusManager has been initialized. * @return The focus order of the actor */ unsigned int GenerateNewFocusOrder() const; /** - * Get the actor that has the specified focus order. It will return an empty handle if the - * actor is not in the stage or has a focus order of 0. + * @brief Get the actor that has the specified focus order. + * + * It will return an empty handle if the actor is not in the stage + * or has a focus order of 0. + * * @pre The FocusManager has been initialized. * @param order The focus order of the actor - * @return The actor that has the specified focus order or an empty handle if no actor in the stage has the specified focus order. + * + * @return The actor that has the specified focus order or an empty + * handle if no actor in the stage has the specified focus order. */ Actor GetActorByFocusOrder(const unsigned int order); /** - * Move the focus to the specified actor. Only one actor can be focused at the same time. - * The actor must have a defined focus order and must be focusable, visible and in the stage. + * @brief Move the focus to the specified actor. + * + * Only one actor can be focused at the same time. The actor must + * have a defined focus order and must be focusable, visible and in + * the stage. + * * @pre The FocusManager has been initialized. * @pre The Actor has been initialized. * @param actor The actor to be focused @@ -175,62 +209,77 @@ class FocusManager; bool SetCurrentFocusActor(Actor actor); /** - * Get the current focused actor. + * @brief Get the current focused actor. + * * @pre The FocusManager has been initialized. * @return A handle to the current focused actor or an empty handle if no actor is focused. */ Actor GetCurrentFocusActor(); /** - * Get the focus group of current focused actor. + * @brief Get the focus group of current focused actor. + * * @pre The FocusManager has been initialized. - * @return A handle to the immediate parent of the current focused actor which is also a focus group, - * or an empty handle if no actor is focused. + * + * @return A handle to the immediate parent of the current focused + * actor which is also a focus group, or an empty handle if no actor + * is focused. */ Actor GetCurrentFocusGroup(); /** - * Get the focus order of currently focused actor. + * @brief Get the focus order of currently focused actor. * @pre The FocusManager has been initialized. - * @return The focus order of the currently focused actor or 0 if no actor is in focus. + * + * @return The focus order of the currently focused actor or 0 if no + * actor is in focus. */ unsigned int GetCurrentFocusOrder(); /** - * Move the focus to the next focusable actor in the focus chain (according to the focus - * traversal order). When the focus movement is wrapped around, the focus will be moved + * @brief Move the focus to the next focusable actor in the focus + * chain (according to the focus traversal order). + * + * When the focus movement is wrapped around, the focus will be moved * to the first focusable actor when it reaches the end of the focus chain. + * * @pre The FocusManager has been initialized. * @return true if the moving was successful */ bool MoveFocusForward(); /** - * Move the focus to the previous focusable actor in the focus chain (according to the - * focus traversal order). When the focus movement is wrapped around, the focus will be - * moved to the last focusable actor when it reaches the beginning of the focus chain. + * @brief Move the focus to the previous focusable actor in the + * focus chain (according to the focus traversal order). + * + * When the focus movement is wrapped around, the focus will be + * moved to the last focusable actor when it reaches the beginning + * of the focus chain. + * * @pre The FocusManager has been initialized. * @return true if the moving was successful */ bool MoveFocusBackward(); /** - * Clear the focus from the current focused actor if any, so that no actor is focused - * in the focus chain. + * @brief Clear the focus from the current focused actor if any, so + * that no actor is focused in the focus chain. + * * It will emit focus changed signal without current focused actor * @pre The FocusManager has been initialized. */ void ClearFocus(); /** - * Clear the every registered focusable actor from focus-manager. + * @brief Clear the every registered focusable actor from focus-manager. * @pre The FocusManager has been initialized. */ void Reset(); /** - * Set whether an actor is a focus group that can limit the scope of focus movement to - * its child actors in the focus chain. + * @brief Set whether an actor is a focus group that can limit the + * scope of focus movement to its child actors in the focus chain. + * * @pre The FocusManager has been initialized. * @pre The Actor has been initialized. * @param actor The actor to be set as a focus group. @@ -239,7 +288,8 @@ class FocusManager; void SetFocusGroup(Actor actor, bool isFocusGroup); /** - * Check whether the actor is set as a focus group or not. + * @brief Check whether the actor is set as a focus group or not. + * * @pre The FocusManager has been initialized. * @pre The Actor has been initialized. * @param actor The actor to be checked. @@ -248,7 +298,8 @@ class FocusManager; bool IsFocusGroup(Actor actor) const; /** - * Set whether the group mode is enabled or not. + * @brief Set whether the group mode is enabled or not. + * * When the group mode is enabled, the focus movement will be limited to the child actors * of the current focus group including the current focus group itself. The current focus * group is the closest ancestor of the current focused actor that set as a focus group. @@ -258,15 +309,18 @@ class FocusManager; void SetGroupMode(bool enabled); /** - * Get whether the group mode is enabled or not. + * @brief Get whether the group mode is enabled or not. + * * @pre The FocusManager has been initialized. * @return Whether the group mode is enabled or not. */ bool GetGroupMode() const; /** - * Set whether focus will be moved to the beginning of the focus chain when it reaches the - * end or vice versa. When both the wrap mode and the group mode are enabled, focus will be + * @brief Set whether focus will be moved to the beginning of the + * focus chain when it reaches the end or vice versa. + * + * When both the wrap mode and the group mode are enabled, focus will be * wrapped within the current focus group. Focus will not be wrapped in default. * @pre The FocusManager has been initialized. * @param wrapped Whether the focus movement is wrapped around or not @@ -274,15 +328,20 @@ class FocusManager; void SetWrapMode(bool wrapped); /** - * Get whether the wrap mode is enabled or not. + * @brief Get whether the wrap mode is enabled or not. + * * @pre The FocusManager has been initialized. * @return Whether the wrap mode is enabled or not. */ bool GetWrapMode() const; /** - * Set the focus indicator actor. This will replace the default focus indicator actor - * in FocusManager and will be added to the focused actor as a highlight. + * @brief Set the focus indicator actor. + * + * This will replace the default focus indicator actor in + * FocusManager and will be added to the focused actor as a + * highlight. + * * @pre The FocusManager has been initialized. * @pre The indicator actor has been initialized. * @param indicator The indicator actor to be added @@ -290,14 +349,16 @@ class FocusManager; void SetFocusIndicatorActor(Actor indicator); /** - * Get the focus indicator actor. + * @brief Get the focus indicator actor. + * * @pre The FocusManager has been initialized. * @return A handle to the focus indicator actor */ Actor GetFocusIndicatorActor(); /** - * Returns the closest ancestor of the given actor that is a focus group. + * @brief Returns the closest ancestor of the given actor that is a focus group. + * * @param actor The actor to be checked for its focus group * @return The focus group the given actor belongs to or an empty handle if the given actor doesn't belong to any focus group */ @@ -306,7 +367,8 @@ class FocusManager; public: // Signals /** - * This signal is emitted when the current focused actor is changed. + * @brief This signal is emitted when the current focused actor is changed. + * * A callback of the following type may be connected: * @code * void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor); @@ -317,7 +379,8 @@ class FocusManager; FocusChangedSignalV2& FocusChangedSignal(); /** - * This signal is emitted when there is no way to move focus further. + * @brief This signal is emitted when there is no way to move focus further. + * * A callback of the following type may be connected: * @code * void YourCallbackName(Actor currentFocusedActor, FocusOvershotDirection direction); @@ -328,7 +391,8 @@ class FocusManager; FocusOvershotSignalV2& FocusOvershotSignal(); /** - * This signal is emitted when the current focused actor is activated. + * @brief This signal is emitted when the current focused actor is activated. + * * A callback of the following type may be connected: * @code * void YourCallbackName(Actor activatedActor); diff --git a/capi/dali-toolkit/public-api/focus-manager/keyboard-focus-manager.h b/capi/dali-toolkit/public-api/focus-manager/keyboard-focus-manager.h index f86d78b..13e3b34 100644 --- a/capi/dali-toolkit/public-api/focus-manager/keyboard-focus-manager.h +++ b/capi/dali-toolkit/public-api/focus-manager/keyboard-focus-manager.h @@ -17,6 +17,11 @@ // limitations under the License. // +/** + * @addtogroup CAPI_DALI_TOOLKIT_FOCUS_MANAGER_MODULE + * @{ + */ + // INTERNAL INCLUDES #include #include @@ -33,56 +38,62 @@ class KeyboardFocusManager; } /** - * KeyboardFocusManager - * This class provides the functionality of handling keyboard navigation and maintaining - * the two dimensional keyboard focus chain. It provides functionality of setting the - * focus and moving the focus in four directions (i.e. Left, Right, Up and Down). It also - * draws a highlight for the focused actor and emits a signal when the focus is changed. + * @brief Provides the functionality of handling keyboard navigation + * and maintaining the two dimensional keyboard focus chain. + * + * It provides functionality of setting the focus and moving the focus + * in four directions (i.e. Left, Right, Up and Down). It also draws a + * highlight for the focused actor and emits a signal when the focus + * is changed. */ - - class KeyboardFocusManager : public BaseHandle - { - public: +class KeyboardFocusManager : public BaseHandle +{ +public: //Signal Names - static const char* const SIGNAL_PRE_FOCUS_CHANGE; - static const char* const SIGNAL_FOCUS_CHANGED; - static const char* const SIGNAL_FOCUS_GROUP_CHANGED; - static const char* const SIGNAL_FOCUSED_ACTOR_ACTIVATED; + static const char* const SIGNAL_PRE_FOCUS_CHANGE; ///< name "keyboard-pre-focus-change" + static const char* const SIGNAL_FOCUS_CHANGED; ///< name "keyboard-focus-changed" + static const char* const SIGNAL_FOCUS_GROUP_CHANGED; ///< name "keyboard-focus-group-changed" + static const char* const SIGNAL_FOCUSED_ACTOR_ACTIVATED; ///< name "keyboard-focused-actor-activated" - public: +public: - //Pre focus change signal + /// @brief Pre focus change signal typedef SignalV2< Actor ( Actor, Actor, Control::KeyboardFocusNavigationDirection ) > PreFocusChangeSignalV2; - //Focus changed signal + /// @brief Focus changed signal typedef SignalV2< void ( Actor, Actor ) > FocusChangedSignalV2; - //Focus group changed signal + /// @brief Focus group changed signal typedef SignalV2< void ( Actor, bool ) > FocusGroupChangedSignalV2; - //Focused actor activated signal + /// @brief Focused actor activated signal typedef SignalV2< void ( Actor ) > FocusedActorActivatedSignalV2; /** - * Create a KeyboardFocusManager handle; this can be initialised with KeyboardFocusManager::New() + * @brief Create a KeyboardFocusManager handle; this can be initialised with KeyboardFocusManager::New(). + * * Calling member functions with an uninitialised handle is not allowed. */ KeyboardFocusManager(); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~KeyboardFocusManager(); /** - * Get the singleton of KeyboardFocusManager object. + * @brief Get the singleton of KeyboardFocusManager object. + * * @return A handle to the KeyboardFocusManager control. */ static KeyboardFocusManager Get(); /** - * Move the keyboard focus to the given actor. Only one actor can be focused at the same time. - * The actor must be in the stage already and keyboard focusable. + * @brief Move the keyboard focus to the given actor. + * + * Only one actor can be focused at the same time. The actor must + * be in the stage already and keyboard focusable. + * * @pre The KeyboardFocusManager has been initialized. * @pre The Actor has been initialized. * @param actor The actor to be focused @@ -91,15 +102,18 @@ class KeyboardFocusManager; bool SetCurrentFocusActor(Actor actor); /** - * Get the current focused actor. + * @brief Get the current focused actor. + * * @pre The KeyboardFocusManager has been initialized. * @return A handle to the current focused actor or an empty handle if no actor is focused. */ Actor GetCurrentFocusActor(); /** - * Move the focus to the next focusable actor in the focus chain in the given direction - * (according to the focus traversal order). + * @brief Move the focus to the next focusable actor in the focus + * chain in the given direction (according to the focus traversal + * order). + * * @pre The KeyboardFocusManager has been initialized. * @param direction The direction of focus movement * @return true if the movement was successful @@ -107,15 +121,17 @@ class KeyboardFocusManager; bool MoveFocus(Control::KeyboardFocusNavigationDirection direction); /** - * Clear the focus from the current focused actor if any, so that no actor is focused - * in the focus chain. + * @brief Clear the focus from the current focused actor if any, so + * that no actor is focused in the focus chain. + * * It will emit focus changed signal without current focused actor * @pre The KeyboardFocusManager has been initialized. */ void ClearFocus(); /** - * Set whether the focus movement should be looped within the same focus group. + * @brief Set whether the focus movement should be looped within the same focus group. + * * The focus movement is not looped by default. * @pre The KeyboardFocusManager has been initialized. * @param enabled Whether the focus movement should be looped @@ -123,16 +139,19 @@ class KeyboardFocusManager; void SetFocusGroupLoop(bool enabled); /** - * Get whether the focus movement should be looped within the same focus group. + * @brief Get whether the focus movement should be looped within the same focus group. + * * @pre The KeyboardFocusManager has been initialized. * @return Whether the focus movement should be looped */ bool GetFocusGroupLoop() const; /** - * Set whether an actor is a focus group that can limit the scope of focus movement to - * its child actors in the focus chain. Layout controls set themselves as focus groups - * by default. + * @brief Set whether an actor is a focus group that can limit the + * scope of focus movement to its child actors in the focus chain. + * + * Layout controls set themselves as focus groups by default. + * * @pre The KeyboardFocusManager has been initialized. * @pre The Actor has been initialized. * @param actor The actor to be set as a focus group. @@ -141,7 +160,8 @@ class KeyboardFocusManager; void SetAsFocusGroup(Actor actor, bool isFocusGroup); /** - * Check whether the actor is set as a focus group or not. + * @brief Check whether the actor is set as a focus group or not. + * * @pre The KeyboardFocusManager has been initialized. * @pre The Actor has been initialized. * @param actor The actor to be checked. @@ -150,7 +170,8 @@ class KeyboardFocusManager; bool IsFocusGroup(Actor actor) const; /** - * Returns the closest ancestor of the given actor that is a focus group. + * @brief Returns the closest ancestor of the given actor that is a focus group. + * * @param actor The actor to be checked for its focus group * @return The focus group the given actor belongs to or an empty handle if the given actor * doesn't belong to any focus group @@ -158,8 +179,12 @@ class KeyboardFocusManager; Actor GetFocusGroup(Actor actor); /** - * Set the focus indicator actor. This will replace the default focus indicator actor - * in KeyboardFocusManager and will be added to the focused actor as a highlight. + * @brief Set the focus indicator actor. + * + * This will replace the default focus indicator actor in + * KeyboardFocusManager and will be added to the focused actor as a + * highlight. + * * @pre The KeyboardFocusManager has been initialized. * @pre The indicator actor has been initialized. * @param indicator The indicator actor to be added @@ -167,22 +192,27 @@ class KeyboardFocusManager; void SetFocusIndicatorActor(Actor indicator); /** - * Get the focus indicator actor. + * @brief Get the focus indicator actor. + * * @pre The KeyboardFocusManager has been initialized. * @return A handle to the focus indicator actor */ Actor GetFocusIndicatorActor(); - public: // Signals +public: // Signals /** - * This signal is emitted before the focus is going to be changed. - * KeyboardFocusManager makes the best guess for which actor to focus towards the given direction, - * but applications might want to change that. By connecting with this signal, they can check the - * proposed actor to focus and return a different actor if they wish. - * This signal is only emitted when the navigation key is pressed and KeyboardFocusManager tries to - * move the focus automatically. It won't be emitted for focus movement by calling SetCurrentFocusActor - * directly. + * @brief This signal is emitted before the focus is going to be changed. + * + * KeyboardFocusManager makes the best guess for which actor to + * focus towards the given direction, but applications might want to + * change that. By connecting with this signal, they can check the + * proposed actor to focus and return a different actor if they + * wish. This signal is only emitted when the navigation key is + * pressed and KeyboardFocusManager tries to move the focus + * automatically. It won't be emitted for focus movement by calling + * SetCurrentFocusActor directly. + * * A callback of the following type may be connected: * @code * Actor YourCallbackName(Actor currentFocusedActor, Actor proposedActorToFocus, Control::KeyboardFocusNavigationDirection direction); @@ -193,7 +223,8 @@ class KeyboardFocusManager; PreFocusChangeSignalV2& PreFocusChangeSignal(); /** - * This signal is emitted after the current focused actor has been changed. + * @brief This signal is emitted after the current focused actor has been changed. + * * A callback of the following type may be connected: * @code * void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor); @@ -204,10 +235,13 @@ class KeyboardFocusManager; FocusChangedSignalV2& FocusChangedSignal(); /** - * This signal is emitted when the focus group has been changed. - * If the current focus group has a parent layout control, KeyboardFocusManager will make the best guess - * for the next focus group to move the focus to in the given direction (forward or backward). If not, - * the application has to set the new focus. + * @brief This signal is emitted when the focus group has been changed. + * + * If the current focus group has a parent layout control, + * KeyboardFocusManager will make the best guess for the next focus + * group to move the focus to in the given direction (forward or + * backward). If not, the application has to set the new focus. + * * A callback of the following type may be connected: * @code * void YourCallbackName(Actor currentFocusedActor, bool forward); @@ -218,7 +252,8 @@ class KeyboardFocusManager; FocusGroupChangedSignalV2& FocusGroupChangedSignal(); /** - * This signal is emitted when the current focused actor is activated. + * @brief This signal is emitted when the current focused actor is activated. + * * A callback of the following type may be connected: * @code * void YourCallbackName(Actor activatedActor); @@ -231,7 +266,8 @@ class KeyboardFocusManager; // Not intended for application developers /** - * Creates a new handle from the implementation. + * @brief Creates a new handle from the implementation. + * * @param[in] impl A pointer to the object. */ explicit DALI_INTERNAL KeyboardFocusManager(Internal::KeyboardFocusManager *impl); @@ -242,4 +278,7 @@ class KeyboardFocusManager; } // namespace Dali +/** + * @} + */ #endif // __DALI_TOOLKIT_KEYBOARD_FOCUS_MANAGER_H__ diff --git a/capi/dali-toolkit/public-api/markup-processor/markup-processor.h b/capi/dali-toolkit/public-api/markup-processor/markup-processor.h index ecb76e1..705a79e 100644 --- a/capi/dali-toolkit/public-api/markup-processor/markup-processor.h +++ b/capi/dali-toolkit/public-api/markup-processor/markup-processor.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_MARKUP_PROCESSOR_MODULE * @{ */ @@ -34,23 +34,36 @@ namespace Dali DALI_IMPORT_API namespace Toolkit { +/** + * @brief Markup Processor enumerations, structures and functions. + */ namespace MarkupProcessor { /** - * Holds text and its style. + * @brief A pair of Dali::Text and Dali::TextStyle. * - * mText is a Dali::Text object which can store text in different languages. mStyle is a Dali::TextStyle object which can - * store all text styling features provided by Dali::TextActor. + * mText is a Dali::Text object which can store text in different + * languages. mStyle is a Dali::TextStyle object which can store all + * text styling features provided by Dali::TextActor. */ struct StyledText { + /** + * @brief Constructor + */ StyledText() : mText(), mStyle() { } + /** + * @brief Constructor + * + * @param[in] text A Text object + * @param[in] style A Style object + */ StyledText( const Text& text, const TextStyle& style ) : mText( text ), mStyle( style ) @@ -62,15 +75,20 @@ struct StyledText }; /** - * This type defines a vector of StyledText. It's used to store a whole text with its style - * and set it to a Dali::Toolkit::TextView. It could be used in other UI Dali::Toolkit::Control classes - * which need text with style. + * @brief This type defines a vector of StyledText. + * + * It's used to store a whole text with its style and set it to a + * Dali::Toolkit::TextView. It could be used in other UI + * Dali::Toolkit::Control classes which need text with style. */ typedef std::vector StyledTextArray; /** - * Creates a text array with its style from a markup string. - * The syntax of a markup string is html-ish. It contains open, close and empty tags and some of them can contain parameters. + * @brief Creates a text array with its style from a markup string. + * + * The syntax of a markup string is html-ish. It contains open, close + * and empty tags and some of them can contain parameters. + * *
    *
  • \e \\ Bold text. *
  • \e \\ Italic text. @@ -112,21 +130,24 @@ typedef std::vector StyledTextArray; void GetStyledTextArray( const std::string& markupString, StyledTextArray& styledTextArray ); /** - * Creates a plain string from a text array (thus stripping the style meta) + * @brief Creates a plain string from a text array (thus stripping the style meta). + * * @param [in] styledTextArray A text array split in characters, each one with its style. * @param [out] plainString A string without style. */ void GetPlainString( const StyledTextArray& styledTextArray, std::string& plainString ); /** - * Creates a markup string from a text array with its style. + * @brief Creates a markup string from a text array with its style. + * * @param [in] styledTextArray A text array split in characters, each one with its style. * @param [out] markupString A string with style. */ void GetMarkupString( const StyledTextArray& styledTextArray, std::string& markupString ); /** - * Sets a text style to the given text. + * @brief Sets a text style to the given text. + * * By default all style settings are applied but a bit mask could be used to modify only certain style settings. * @param[in,out] styledTextArray The given text * @param[in] style The given style @@ -144,7 +165,8 @@ void SetTextStyle( StyledTextArray& styledTextArray, const TextStyle& style, con void SetTextStyle( const Text& text, StyledTextArray& styledTextArray, const TextStyle& style, const TextStyle::Mask mask = TextStyle::ALL ); /** - * Sets a text style to a range of characters of the given text. + * @brief Sets a text style to a range of characters of the given text. + * * By default all style settings are applied but a bit mask could be used to modify only certain style settings. * @param[in,out] styledTextArray The given text * @param[in] style The given style diff --git a/capi/dali-toolkit/public-api/shader-effects/dissolve-effect.h b/capi/dali-toolkit/public-api/shader-effects/dissolve-effect.h index 634e4ab..f687e88 100644 --- a/capi/dali-toolkit/public-api/shader-effects/dissolve-effect.h +++ b/capi/dali-toolkit/public-api/shader-effects/dissolve-effect.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_SHADER_EFFECTS_MODULE * @{ */ @@ -32,32 +32,35 @@ namespace Toolkit { /** - * DissolveEffect is a custom shader effect to achieve Dissolve effects in Image actors + * @brief DissolveEffect is a custom shader effect to achieve Dissolve effects in Image actors. */ class DissolveEffect : public ShaderEffect { public: /** - * Create an uninitialized DissolveEffect; this can be initialized with DissolveEffect::New() + * @brief Create an uninitialized DissolveEffect; this can be initialized with DissolveEffect::New(). + * * Calling member functions with an uninitialized Dali::Object is not allowed. */ DissolveEffect(); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~DissolveEffect(); /** - * Create an initialized DissolveEffect. + * @brief Create an initialized DissolveEffect. + * * @param[in] useHighPrecision True if using high precision in fragment shader for fully random noise, false otherwise * @return A handle to a newly allocated Dali resource. */ static DissolveEffect New( bool useHighPrecision = true); /** - * Set the dissolve central line + * @brief Set the dissolve central line. + * * Use one point (position) and one direction ( displacement ) vector to define this line * As we use the texture coordinate as pixel position to calculate random offset, * the line should passing through rectangle {(0,0),(0,1),(1,0),(1,1)}, @@ -68,14 +71,16 @@ public: void SetCentralLine( const Vector2& position, const Vector2& displacement ); /** - * Sets the distortion applied to the effect texture. + * @brief Sets the distortion applied to the effect texture. + * * This value is proportional to the distortion applied; a value of zero means no distortion. * @param [in] distortion The distortion value. */ void SetDistortion( float distortion ); /** - * Get the name for the distortion property + * @brief Get the name for the distortion property. + * * @return A std::string containing the property name */ const std::string& GetDistortionPropertyName() const; diff --git a/capi/dali-toolkit/public-api/shader-effects/image-region-effect.h b/capi/dali-toolkit/public-api/shader-effects/image-region-effect.h index 6c16097..6dbdf9b 100644 --- a/capi/dali-toolkit/public-api/shader-effects/image-region-effect.h +++ b/capi/dali-toolkit/public-api/shader-effects/image-region-effect.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_SHADER_EFFECTS_MODULE * @{ */ @@ -32,53 +32,58 @@ namespace Toolkit { /** - * ImageRegionEffect is a custom shader effect to show only a region of an Image actor + * @brief ImageRegionEffect is a custom shader effect to show only a region of an Image actor. */ class ImageRegionEffect : public ShaderEffect { public: /** - * Create an uninitialized ImageRegionEffect; this can be initialized with ImageRegionEffect::New() + * @brief Create an uninitialized ImageRegionEffect; this can be initialized with ImageRegionEffect::New(). + * * Calling member functions with an uninitialized Dali::Object is not allowed. */ ImageRegionEffect(); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~ImageRegionEffect(); /** - * Create an initialized ~ImageRegionEffect. + * @brief Create an initialized ImageRegionEffect. + * * @return A handle to a newly allocated Dali resource. */ static ImageRegionEffect New(); /** - * Set the top-left corner of the image region. + * @brief Set the top-left corner of the image region. + * * The coordinates are in percentage, (0,0) being the top-left and (1,1) the bottom right of the original image. * @param [in] point The top-left corner of the region. */ void SetTopLeft(const Vector2& point); /** - * Set the bottom-right corner of the image region. + * @brief Set the bottom-right corner of the image region. + * * The coordinates are in percentage, (0,0) being the top-left and (1,1) the bottom right of the original image. * @param [in] point The bottom-right corner of the region. */ void SetBottomRight(const Vector2& point); /** - * Get the name for the top-left point property + * @brief Get the name for the top-left point property. + * * which can be used in Animation API's * @return A std::string containing the property name */ const std::string& GetTopLeftPropertyName() const; /** - * Get the name for the bottom-right point property - * which can be used in Animation API's + * @brief Get the name for the bottom-right point property which can be used in Animation APIs. + * * @return A std::string containing the property name */ const std::string& GetBottomRightPropertyName() const; diff --git a/capi/dali-toolkit/public-api/shader-effects/iris-effect.h b/capi/dali-toolkit/public-api/shader-effects/iris-effect.h index 9f8b33a..b9b3653 100644 --- a/capi/dali-toolkit/public-api/shader-effects/iris-effect.h +++ b/capi/dali-toolkit/public-api/shader-effects/iris-effect.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_SHADER_EFFECTS_MODULE * @{ */ @@ -32,7 +32,7 @@ namespace Toolkit { /** - * IrisEffect is a custom shader effect to achieve iris effects in Image actors + * @brief IrisEffect is a custom shader effect to achieve iris effects in Image actors */ class IrisEffect : public ShaderEffect { @@ -40,26 +40,28 @@ class IrisEffect : public ShaderEffect public: /** - * Create an uninitialized IrisEffect; this can be initialized with IrisEffect::New() + * @brief Create an uninitialized IrisEffect; this can be initialized with IrisEffect::New(). + * * Calling member functions with an uninitialized Dali::Object is not allowed. */ IrisEffect(); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~IrisEffect(); /** - * Create an initialized IrisEffect + * @brief Create an initialized IrisEffect. + * * @return A handle to a newly allocated Dali resource. */ static IrisEffect New(); /** - * Set the radius of the iris effect (in texture coordinate distance, + * @brief Set the radius of the iris effect in texture coordinate distance, * i.e. 0.0 (no circle) to 1.0 (complete circle), to > 1.0 (extending - * outside of texture) + * outside of texture). * * @note For Atlas Textures results may be unpredictable. * @@ -68,7 +70,7 @@ public: void SetRadius(float radius); /** - * Set the blend factor of the iris effect. + * @brief Set the blend factor of the iris effect. * * The lower the value, the larger the blending portion * (between Opaque & Transparent) @@ -81,27 +83,29 @@ public: void SetBlendFactor(float value); /** - * Sets the center point of the iris (in texture coordinates) + * @brief Sets the center point of the iris (in texture coordinates). * * @param[in] center The center point. */ void SetCenter( const Vector2& center ); /** - * Get the name for the radius property - * which can be used in Animation API's + * @brief Get the name for the radius property which can be used in Animation APIs. + * * @return A std::string containing the property name */ const std::string& GetRadiusPropertyName() const; /** - * Get the name for the blend factor property + * @brief Get the name for the blend factor property. + * * @return A std::string containing the property name */ const std::string& GetBlendFactorPropertyName() const; /** - * Get the name for the center property + * @brief Get the name for the center property. + * * @return A std::string containing the property name */ const std::string& GetCenterPropertyName() const; diff --git a/capi/dali-toolkit/public-api/shader-effects/mask-effect.h b/capi/dali-toolkit/public-api/shader-effects/mask-effect.h index de6c223..aefa9e7 100644 --- a/capi/dali-toolkit/public-api/shader-effects/mask-effect.h +++ b/capi/dali-toolkit/public-api/shader-effects/mask-effect.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_SHADER_EFFECTS_MODULE * @{ */ @@ -32,7 +32,8 @@ namespace Toolkit { /** - * MaskEffect is used to control which parts of an image are visible, using the alpha channel of a separate mask image. + * @brief MaskEffect is used to control which parts of an image are visible, using the alpha channel of a separate mask image. + * * Typically mask images should be the same size as the main image being viewed, but this isn't essential. * * Usage example: @@ -46,17 +47,19 @@ class DALI_IMPORT_API MaskEffect : public ShaderEffect public: /** - * Create an empty MaskEffect handle. + * @brief Create an empty MaskEffect handle. */ MaskEffect(); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~MaskEffect(); /** - * Create a MaskEffect. + * @brief Create a MaskEffect. + * + * @param[in] maskImage The image to use as a mask * @return A handle to a newly allocated MaskEffect. */ static MaskEffect New( Image maskImage ); diff --git a/capi/dali-toolkit/public-api/shader-effects/nine-patch-mask-effect.h b/capi/dali-toolkit/public-api/shader-effects/nine-patch-mask-effect.h index 43de3b2..b203eb6 100644 --- a/capi/dali-toolkit/public-api/shader-effects/nine-patch-mask-effect.h +++ b/capi/dali-toolkit/public-api/shader-effects/nine-patch-mask-effect.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_SHADER_EFFECTS_MODULE * @{ */ @@ -32,7 +32,8 @@ namespace Toolkit { /** - * NinePatchMaskEffect is used to control which parts of an image are visible, using the alpha channel of a separate mask image. + * @brief NinePatchMaskEffect is used to control which parts of an image are visible, using the alpha channel of a separate mask image. + * * The mask image is expected to be smaller than the main image being viewed. * Conceptually the mask image is divided into a 3x3 grid (9 patches). The middle patch is stretched whilst the outer border is not. * @@ -49,7 +50,8 @@ namespace NinePatchMaskEffect { /** - * Apply the mask effect to an ImageActor. + * @brief Apply the mask effect to an ImageActor. + * * NinePatchMaskEffect is mutually exclusive with ImageActor::STYLE_NINE_PATCH i.e. the actor's main image should not be a nine-patch. * @param [in] actor The actor which needs the effect. To remove the effect call actor.RemoveShaderEffect(). * @param [in] maskImage The path to a file containing the mask. The center pixels of the mask will be stretched. @@ -57,7 +59,8 @@ namespace NinePatchMaskEffect void Apply( ImageActor actor, const std::string& maskImage ); /** - * Apply the mask effect to an ImageActor. + * @brief Apply the mask effect to an ImageActor. + * * NinePatchMaskEffect is mutually exclusive with ImageActor::STYLE_NINE_PATCH i.e. the actor's main image should not be a nine-patch. * @param [in] actor The actor which needs the effect. To remove the effect call actor.RemoveShaderEffect(). * @param [in] maskImage The path to a file containing the mask. diff --git a/capi/dali-toolkit/public-api/shader-effects/page-turn-book-spine-effect.h b/capi/dali-toolkit/public-api/shader-effects/page-turn-book-spine-effect.h index 72330bf..0fcece0 100644 --- a/capi/dali-toolkit/public-api/shader-effects/page-turn-book-spine-effect.h +++ b/capi/dali-toolkit/public-api/shader-effects/page-turn-book-spine-effect.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_SHADER_EFFECTS_MODULE * @{ */ @@ -31,52 +31,62 @@ namespace Dali DALI_IMPORT_API namespace Toolkit { /** - * It is an assisting effect of PageTurnEffect to display book spine on STATIC pages, and also flip the image horizontally when needed. - * When the page is turned over in landscape, call SetIsBackImageVisible(true), this effect can display the back image correctly after the imageActor been rotated 180 degrees. - * To display the pages visually consistent with its turning state, please set the uniforms with the same values as the PageTurnEffect + * @brief This is an assisting effect of PageTurnEffect to display a book spine on _static_ pages, and also to flip the image horizontally when needed. + * + * When the page is turned over in landscape, call + * SetIsBackImageVisible(true), this effect can display the back image + * correctly after the imageActor been rotated 180 degrees. To + * display the pages visually consistent with its turning state, + * please set the uniforms with the same values as the PageTurnEffect. **/ class PageTurnBookSpineEffect : public ShaderEffect { public: /** - * Create an uninitialized PageTurnBookSpineEffect; this can be initialized with PageTurnBookSpineEffect::New() + * @brief Create an uninitialized PageTurnBookSpineEffect; this can be initialized with PageTurnBookSpineEffect::New(). + * * Calling member functions with an uninitialized Dali::Object is not allowed. */ PageTurnBookSpineEffect(); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~PageTurnBookSpineEffect(); /** - * Create an initialized PageTurnBookSpineEffect. + * @brief Create an initialized PageTurnBookSpineEffect. + * * @return A handle to a newly allocated Dali resource. */ static PageTurnBookSpineEffect New(); /** - * Set whether the current page is with its backside visible + * @brief Set whether the current page is with its backside visible. + * * Need to pass the parameter as true for the page which is turned over but still visible in Landscape * @param [in] isBackVisible True for page with its backside upwards */ void SetIsBackImageVisible( bool isBackVisible ); /** - * Set the page width of the PageTurnBookSpineEffect. + * @brief Set the page width of the PageTurnBookSpineEffect. + * * @param [in] pageWidth The width of the page size. */ void SetPageWidth( float pageWidth ); /** - * Set the width of shadow to be pageSize * shadowWidth + * @brief Set the width of shadow to be pageSize * shadowWidth. + * * this shadow appears at the edges of the actor which is not visible on static pages * @param [in] shadowWidth The width for the simulated shadow */ void SetShadowWidth( float shadowWidth ); /** - * Set the spine shadow parameter + * @brief Set the spine shadow parameter. + * * The two parameters are the major&minor radius (in pixels) to form an ellipse shape * The top-left quarter of this ellipse is used to calculate spine normal for simulating shadow * @param [in] spineShadowParameter The major&minor ellipse radius for the simulated spine shadow diff --git a/capi/dali-toolkit/public-api/shader-effects/page-turn-effect.h b/capi/dali-toolkit/public-api/shader-effects/page-turn-effect.h index 97f5c38..124777c 100644 --- a/capi/dali-toolkit/public-api/shader-effects/page-turn-effect.h +++ b/capi/dali-toolkit/public-api/shader-effects/page-turn-effect.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_SHADER_EFFECTS_MODULE * @{ */ @@ -35,14 +35,14 @@ namespace Internal DALI_INTERNAL { /** - * PageTurnEffect implementation class + * @brief PageTurnEffect implementation class. */ class PageTurnEffect; } // namespace Internal /** - * PageTurnEffect is a custom shader effect to achieve page turn effect for Image actors + * @brief PageTurnEffect is a custom shader effect to achieve page turn effect for Image actors. * * Usage example:- * @@ -76,18 +76,20 @@ class PageTurnEffect : public ShaderEffect { public: /** - * Create an uninitialized PageTurnEffect; this can be initialized with PageTurnEffect::New() + * @brief Create an uninitialized PageTurnEffect; this can be initialized with PageTurnEffect::New(). + * * Calling member functions with an uninitialized Dali::Object is not allowed. */ PageTurnEffect(); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~PageTurnEffect(); /** - * Create an initialized PageTurnEffect. + * @brief Create an initialized PageTurnEffect. + * * If fake shadow is used, need to apply the ShaderEffect::HINT_BLENDING * @param[in] enableBlending If true, apply HINT_BLENDING when creating the shader object; If false, disable the HINT_BLENDING * @return A handle to a newly allocated Dali resource. @@ -95,37 +97,43 @@ public: static PageTurnEffect New( bool enableBlending = true ); /** - * Set the page size of the PageTurnEffect. + * @brief Set the page size of the PageTurnEffect. + * * @param [in] pageSize The page size. */ void SetPageSize(const Vector2& pageSize); /** - * Set the origin point of the PageTurnEffect, the position where the mouse/finger is pushed from. + * @brief Set the origin point of the PageTurnEffect, the position where the mouse/finger is pushed from. + * * @param [in] originalCenter The new origin point. */ void SetOriginalCenter(const Vector2& originalCenter); /** - * Set the center point of the PageTurnEffect, the current position of touch motion. + * @brief Set the center point of the PageTurnEffect, the current position of touch motion. + * * @param [in] currentCenter The new center point. */ void SetCurrentCenter(const Vector2& currentCenter); /** - * Set whether the current page is turning forward or backward + * @brief Set whether the current page is turning forward or backward. + * * @param [in] isTurningBack True for turning backward or False for turning forward */ void SetIsTurningBack(bool isTurningBack); /** - * Set the width of shadow to be pageSize * shadowWidth + * @brief Set the width of shadow to be pageSize * shadowWidth. + * * @param [in] shadowWidth The width for the simulated shadow */ void SetShadowWidth(float shadowWidth); /** - * Set the spine shadow parameter + * @brief Set the spine shadow parameter. + * * The two parameters are the major&minor radius (in pixels) to form an ellipse shape * The top-left quarter of this ellipse is used to calculate spine normal for simulating shadow * @param [in] spineShadowParameter The major&minor ellipse radius for the simulated spine shadow @@ -133,19 +141,22 @@ public: void SetSpineShadowParameter(const Vector2& spineShadowParameter); /** - * Get the name for the page size property + * @brief Get the name for the page size property. + * * @return A std::string containing the property name */ const std::string& GetPageSizePropertyName() const; /** - * Get the name for the origin center property + * @brief Get the name for the origin center property. + * * @return A std::string containing the property name */ const std::string& GetOriginalCenterPropertyName() const; /** - * Get the name for the current center property + * @brief Get the name for the current center property. + * * which can be used in Animation API's * @return A std::string containing the property name */ diff --git a/capi/dali-toolkit/public-api/shader-effects/ripple-effect.h b/capi/dali-toolkit/public-api/shader-effects/ripple-effect.h index 5e8cc42..9245ca9 100644 --- a/capi/dali-toolkit/public-api/shader-effects/ripple-effect.h +++ b/capi/dali-toolkit/public-api/shader-effects/ripple-effect.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_SHADER_EFFECTS_MODULE * @{ */ @@ -32,62 +32,70 @@ namespace Toolkit { /** - * RippleEffect is a custom shader effect to achieve ripple effects on Image actors + * @brief RippleEffect is a custom shader effect to achieve ripple effects on Image actors. */ class RippleEffect : public ShaderEffect { public: /** - * Create an uninitialized RippleEffect; this can be initialized with RippleEffect::New() + * @brief Create an uninitialized RippleEffect; this can be initialized with RippleEffect::New(). + * * Calling member functions with an uninitialized Dali::Object is not allowed. */ RippleEffect(); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~RippleEffect(); /** - * Create an initialized RippleEffect. + * @brief Create an initialized RippleEffect. + * * @return A handle to a newly allocated Dali resource. */ static RippleEffect New(); /** - * Set the amplitude of the effect. + * @brief Set the amplitude of the effect. + * * @param [in] amplitude The new amplitude. */ void SetAmplitude(float amplitude); /** - * Set the center point of the effect as screen coordinates. + * @brief Set the center point of the effect as screen coordinates. + * * @param [in] center The new center point. */ void SetCenter(const Vector2& center); /** - * Set the time duration for the ripple. + * @brief Set the time duration for the ripple. + * * @param[in] time The time duration in float. */ void SetTime(float time); /** - * Get the name for the amplitude property + * @brief Get the name for the amplitude property. + * * @return A std::string containing the property name */ const std::string& GetAmplitudePropertyName() const; /** - * Get the name for the center property + * @brief Get the name for the center property. + * * which can be used in Animation API's * @return A std::string containing the property name */ const std::string& GetCenterPropertyName() const; /** - * Get the name for the time property + * @brief Get the name for the time property. + * * which can be used in Animation API's * @return A std::string containing the property name */ diff --git a/capi/dali-toolkit/public-api/shader-effects/ripple2d-effect.h b/capi/dali-toolkit/public-api/shader-effects/ripple2d-effect.h index 45b9efb..a49c4e5 100644 --- a/capi/dali-toolkit/public-api/shader-effects/ripple2d-effect.h +++ b/capi/dali-toolkit/public-api/shader-effects/ripple2d-effect.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_SHADER_EFFECTS_MODULE * @{ */ @@ -32,49 +32,55 @@ namespace Toolkit { /** - * Ripple2DEffect is a custom shader effect to achieve 2d ripple effects on Image actors + * @brief Ripple2DEffect is a custom shader effect to achieve 2d ripple effects on Image actors. */ class Ripple2DEffect : public ShaderEffect { public: /** - * Create an uninitialized Ripple2DEffect; this can be initialized with Ripple2DEffect::New() + * @brief Create an uninitialized Ripple2DEffect; this can be initialized with Ripple2DEffect::New(). + * * Calling member functions with an uninitialized Dali::Object is not allowed. */ Ripple2DEffect(); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~Ripple2DEffect(); /** - * Create an initialized Ripple2DEffect. + * @brief Create an initialized Ripple2DEffect. + * * @return A handle to a newly allocated Dali resource. */ static Ripple2DEffect New(); /** - * Set the amplitude of the 2d ripple. + * @brief Set the amplitude of the 2d ripple. + * * @param[in] amplitude The amplitude in float. */ void SetAmplitude(float amplitude); /** - * Set the time duration for the 2d ripple. + * @brief Set the time duration for the 2d ripple. + * * @param[in] time The time duration in float. */ void SetTime(float time); /** - * Get the name for the amplitude property + * @brief Get the name for the amplitude property. + * * @return A std::string containing the property name */ const std::string& GetAmplitudePropertyName() const; /** - * Get the name for the time property + * @brief Get the name for the time property. + * * which can be used in Animation API's * @return A std::string containing the property name */ diff --git a/capi/dali-toolkit/public-api/shader-effects/swirl-effect.h b/capi/dali-toolkit/public-api/shader-effects/swirl-effect.h index 62c1538..6a0e676 100644 --- a/capi/dali-toolkit/public-api/shader-effects/swirl-effect.h +++ b/capi/dali-toolkit/public-api/shader-effects/swirl-effect.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_SHADER_EFFECTS_MODULE * @{ */ @@ -32,61 +32,70 @@ namespace Toolkit { /** - * SwirlEffect is a custom shader effect to achieve swirl effects in Image actors + * @brief SwirlEffect is a custom shader effect to achieve swirl effects in Image actors. */ class SwirlEffect : public ShaderEffect { public: /** - * Create an uninitialized SwirlEffect; this can be initialized with SwirlEffect::New() + * @brief Create an uninitialized SwirlEffect; this can be initialized with SwirlEffect::New(). + * * Calling member functions with an uninitialized Dali::Object is not allowed. */ SwirlEffect(); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~SwirlEffect(); /** - * Create an initialized SwirlEffect. + * @brief Create an initialized SwirlEffect. + * + * @param[in] warp True if the effect should warp. * @return A handle to a newly allocated Dali resource. */ static SwirlEffect New(bool warp); /** - * Set the angle of the swirl. + * @brief Set the angle of the swirl. + * * @param[in] angle The angle in float. */ void SetAngle(float angle); /** - * Set the center of the swirl. + * @brief Set the center of the swirl. + * * @param[in] center The center in Vector2. */ void SetCenter(const Vector2& center); /** - * Set the radius of the swirl. + * @brief Set the radius of the swirl. + * * @param[in] radius The radius in float. */ void SetRadius(float radius); /** - * Get the name for the angle property + * @brief Get the name for the angle property. + * * @return A std::string containing the property name */ const std::string& GetAnglePropertyName() const; /** - * Get the name for the center property + * @brief Get the name for the center property. + * * @return A std::string containing the property name */ const std::string& GetCenterPropertyName() const; /** - * Get the name for the radius property + * @brief Get the name for the radius property. + * * @return A std::string containing the property name */ const std::string& GetRadiusPropertyName() const; diff --git a/capi/dali_toolkit_doc.h b/capi/dali_toolkit_doc.h new file mode 100644 index 0000000..a53b6d6 --- /dev/null +++ b/capi/dali_toolkit_doc.h @@ -0,0 +1,304 @@ +#ifndef __DALI_TOOLKIT_DOC_H__ +#define __DALI_TOOLKIT_DOC_H__ + +// +// Copyright (c) 2014 Samsung Electronics Co., Ltd. +// +// Licensed under the Flora License, Version 1.0 (the License); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://floralicense.org/license/ +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an AS IS BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +/** + * @ingroup CAPI_DALI_FRAMEWORK + * @defgroup CAPI_DALI_TOOLKIT_MODULE Dali Toolkit + * @brief A library to provide a user interface toolkit on top of Dali. + * @section CAPI_DALI_TOOLKIT_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_TOOLKIT_MODULE_OVERVIEW Overview + * A library to provide a user interface toolkit running on top of Dali. + * + * + * + * + * + * + *
    APIDescription
    @ref CAPI_DALI_TOOLKIT_CONTROLS_MODULEUser interface controls
    @ref CAPI_DALI_TOOLKIT_FACTORY_MODULEFactory methods for creating controls
    @ref CAPI_DALI_TOOLKIT_FOCUS_MANAGER_MODULEClasses for managing focus between controls and actors
    @ref CAPI_DALI_TOOLKIT_MARKUP_PROCESSOR_MODULEText markup classes
    @ref CAPI_DALI_TOOLKIT_SHADER_EFFECTS_MODULEShader effects classes
    + */ + +/** + * @ingroup CAPI_DALI_TOOLKIT_MODULE + * @defgroup CAPI_DALI_TOOLKIT_CONTROLS_MODULE Controls + * @brief + * @section CAPI_DALI_TOOLKIT_CONTROLS_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_TOOLKIT_CONTROLS_MODULE_OVERVIEW Overview + * + * + * + * + * + * + * + * Popup control + * + * + * + * + * + * + *
    APIDescription
    @ref CAPI_DALI_TOOLKIT_ALIGNMENT_MODULE Layout class
    @ref CAPI_DALI_TOOLKIT_BUBBLE_EFFECT_MODULE Particle emitter
    @ref CAPI_DALI_TOOLKIT_BUTTONS_MODULE Button
    @ref CAPI_DALI_TOOLKIT_CLUSTER_MODULE Styles for clusters of actors
    @ref CAPI_DALI_TOOLKIT_DEFAULT_CONTROLS_MODULE Factory methods for generating controls
    @ref CAPI_DALI_TOOLKIT_IMAGE_VIEW_MODULE Classes for displaying images
    @ref CAPI_DALI_TOOLKIT_POPUP_MODULE
    @ref CAPI_DALI_TOOLKIT_SCROLLABLE_MODULE Scrollable containers
    @ref CAPI_DALI_TOOLKIT_SUPER_BLUR_VIEW_MODULE Control to perform blurring on an image
    @ref CAPI_DALI_TOOLKIT_TEXT_INPUT_MODULE Input control using the virtual keyboard
    @ref CAPI_DALI_TOOLKIT_TEXT_VIEW_MODULE Control to display text in different styles
    @ref Dali::Toolkit::Control Control is the base class for all controls.
    @ref Dali::Toolkit::ControlImpl This is the internal base class for all controls.
    + */ + +/** + * @ingroup CAPI_DALI_TOOLKIT_CONTROLS_MODULE + * @defgroup CAPI_DALI_TOOLKIT_ALIGNMENT_MODULE Alignment + * @brief + * @section CAPI_DALI_TOOLKIT_ALIGNMENT_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_TOOLKIT_ALIGNMENT_MODULE_OVERVIEW Overview + * + * + *
    APIDescription
    @ref Dali::Toolkit::Alignment Alignment is a container which provides an easy way to align other actors inside its boundary.
    + */ + +/** + * @ingroup CAPI_DALI_TOOLKIT_CONTROLS_MODULE + * @defgroup CAPI_DALI_TOOLKIT_BUBBLE_EFFECT_MODULE Bubble Effect + * @brief + * @section CAPI_DALI_TOOLKIT_BUBBLE_EFFECT_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_TOOLKIT_BUBBLE_EFFECT_MODULE_OVERVIEW Overview + * + * + *
    APIDescription
    @ref Dali::Toolkit::BubbleEmitter BubbleEmitter is used to display lots of moving bubbles on the stage.
    + */ + +/** + * @ingroup CAPI_DALI_TOOLKIT_CONTROLS_MODULE + * @defgroup CAPI_DALI_TOOLKIT_BUTTONS_MODULE Buttons + * @brief + * @section CAPI_DALI_TOOLKIT_BUTTONS_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_TOOLKIT_BUTTONS_MODULE_OVERVIEW Overview + * + * + * + *
    APIDescription
    @ref Dali::Toolkit::Button Button is a base class for different kind of buttons.
    @ref Dali::Toolkit::PushButton A PushButton changes its appearance when is pressed and returns to its original when is released.
    + */ + +/** + * @ingroup CAPI_DALI_TOOLKIT_CONTROLS_MODULE + * @defgroup CAPI_DALI_TOOLKIT_CLUSTER_MODULE Cluster + * @brief + * @section CAPI_DALI_TOOLKIT_CLUSTER_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_TOOLKIT_CLUSTER_MODULE_OVERVIEW Overview + * + * + *
    APIDescription
    @ref Dali::Toolkit::ClusterStyle A ClusterStyle describes the constraints, which are imposed on the child actors in the cluster.
    + */ + +/** + * @ingroup CAPI_DALI_TOOLKIT_CONTROLS_MODULE + * @defgroup CAPI_DALI_TOOLKIT_DEFAULT_CONTROLS_MODULE Default Controls + * @brief + * @section CAPI_DALI_TOOLKIT_DEFAULT_CONTROLS_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_TOOLKIT_DEFAULT_CONTROLS_MODULE_OVERVIEW Overview + * + * + *
    APIDescription
    Factory methods Dali::Toolkit::CreateSolidColorActor(), Dali::Toolkit::CreatePushButton()
    + */ + +/** + * @ingroup CAPI_DALI_TOOLKIT_CONTROLS_MODULE + * @defgroup CAPI_DALI_TOOLKIT_IMAGE_VIEW_MODULE Image View + * @brief + * @section CAPI_DALI_TOOLKIT_IMAGE_VIEW_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_TOOLKIT_IMAGE_VIEW_MODULE_OVERVIEW Overview + * + * + *
    APIDescription
    @ref Dali::Toolkit::MaskedImageView MaskedImageView displays the result of an image created from a masking operation.
    + */ + +/** + * @ingroup CAPI_DALI_TOOLKIT_CONTROLS_MODULE + * @defgroup CAPI_DALI_TOOLKIT_POPUP_MODULE Popup + * @brief + * @section CAPI_DALI_TOOLKIT_POPUP_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_TOOLKIT_POPUP_MODULE_OVERVIEW Overview + * + * + *
    APIDescription
    @ref Dali::Toolkit::Popup Popup contains content that can come into focus when activated, and out of focus when deactivated.
    + */ + +/** + * @ingroup CAPI_DALI_TOOLKIT_CONTROLS_MODULE + * @defgroup CAPI_DALI_TOOLKIT_SCROLLABLE_MODULE Scrollable + * @brief + * @section CAPI_DALI_TOOLKIT_SCROLLABLE_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_TOOLKIT_SCROLLABLE_MODULE_OVERVIEW Overview + * + * (via touch) or automatically. + * + * + *
    APIDescription
    @ref CAPI_DALI_TOOLKIT_ITEM_VIEW_MODULE Item view
    @ref CAPI_DALI_TOOLKIT_SCROLL_VIEW_MODULE Scroll view
    @ref Dali::Toolkit::Scrollable Base class for derived Scrollables that contains actors that can be scrolled manually + *
    + */ + +/** + * @ingroup CAPI_DALI_TOOLKIT_SCROLLABLE_MODULE + * @defgroup CAPI_DALI_TOOLKIT_ITEM_VIEW_MODULE Item view + * @brief + * @section CAPI_DALI_TOOLKIT_ITEM_VIEW_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_TOOLKIT_ITEM_VIEW_MODULE_OVERVIEW Overview + * + * + * + * + * + * + *
    APIDescription
    @ref Dali::Toolkit::GridLayout An ItemView layout which arranges items in a grid.
    @ref Dali::Toolkit::ItemFactory ItemFactory is an abstract interface for providing actors to ItemView.
    @ref Dali::Toolkit::ItemRange A support class for managing ranges of items.
    @ref Dali::Toolkit::ItemLayout An ItemLayout describes the constraints which are imposed on items in the layout.
    @ref Dali::Toolkit::ItemView ItemView is a scrollable layout container.
    + */ + +/** + * @ingroup CAPI_DALI_TOOLKIT_SCROLLABLE_MODULE + * @defgroup CAPI_DALI_TOOLKIT_SCROLL_VIEW_MODULE Scroll view + * @brief + * @section CAPI_DALI_TOOLKIT_SCROLL_VIEW_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_TOOLKIT_SCROLL_VIEW_MODULE_OVERVIEW Overview + * + * + * + * + * + * + * + * + * + * + * + * + *
    APIDescription
    @ref Dali::Toolkit::ScrollViewCubeEffect This effect causes Actors to appear to rotate around a 3D cube.
    @ref Dali::Toolkit::ScrollViewCustomEffect This class has many transition effects for use when scrolling pages, e.g opacity, rotation, swing, translation.
    @ref Dali::Toolkit::ScrollViewEffect ScrollView Effect base class, used to apply custom effects to a ScrollView instance.
    @ref Dali::Toolkit::ScrollViewPageSpiralEffect This effect cause each page in a scroll-view to move along a spiral.
    @ref Dali::Toolkit::ScrollViewSlideEffect ScrollView effect that uses slides for transitioning pages.
    @ref Dali::Toolkit::ScrollViewTwistEffect ScrollView effect that twists pages onto screen when transitioning.
    @ref Dali::Toolkit::RulerDomain Used for specifying minimum/maximum extents of a ruler.
    @ref Dali::Toolkit::Ruler Abstract class to define scroll axes.
    @ref Dali::Toolkit::DefaultRuler Concrete implementation of Dali::Toolkit::Ruler that has no snapping and has one single page.
    @ref Dali::Toolkit::FixedRuler Concrete implementation of Ruler that has fixed snapping.
    @ref Dali::Toolkit::ScrollView ScrollView contains actors that can be scrolled manually (via touch) or automatically.
    + */ + +/** + * @ingroup CAPI_DALI_TOOLKIT_CONTROLS_MODULE + * @defgroup CAPI_DALI_TOOLKIT_SUPER_BLUR_VIEW_MODULE Super Blur View + * @brief + * @section CAPI_DALI_TOOLKIT_SUPER_BLUR_VIEW_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_TOOLKIT_SUPER_BLUR_VIEW_MODULE_OVERVIEW Overview + * + * + *
    APIDescription
    @ref Dali::Toolkit::SuperBlurView SuperBlurView accepts an image as input, and displays/animates it with various blur strengths.
    + */ + +/** + * @ingroup CAPI_DALI_TOOLKIT_CONTROLS_MODULE + * @defgroup CAPI_DALI_TOOLKIT_TEXT_INPUT_MODULE Text Input + * @brief + * @section CAPI_DALI_TOOLKIT_TEXT_INPUT_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_TOOLKIT_TEXT_INPUT_MODULE_OVERVIEW Overview + * + * + *
    APIDescription
    @ref Dali::Toolkit::TextInput TextInput Actor takes input one character at a time and displays it as a string within an input box.
    + */ + +/** + * @ingroup CAPI_DALI_TOOLKIT_CONTROLS_MODULE + * @defgroup CAPI_DALI_TOOLKIT_TEXT_VIEW_MODULE Text view + * @brief + * @section CAPI_DALI_TOOLKIT_TEXT_VIEW_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_TOOLKIT_TEXT_VIEW_MODULE_OVERVIEW Overview + * + * + *
    APIDescription
    @ref Dali::Toolkit::TextView TextView is a layout container for text with alignment, multi-line wrapping and formatting support.
    + */ + +/** + * @ingroup CAPI_DALI_TOOLKIT_MODULE + * @defgroup CAPI_DALI_TOOLKIT_FACTORY_MODULE Factory + * @brief + * @section CAPI_DALI_TOOLKIT_FACTORY_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_TOOLKIT_FACTORY_MODULE_OVERVIEW Overview + * + * + *
    APIDescription
    @ref Dali::Toolkit::LocalizedControlFactory This class provides functionality for creating controls which have localized text.
    + */ + +/** + * @ingroup CAPI_DALI_TOOLKIT_MODULE + * @defgroup CAPI_DALI_TOOLKIT_FOCUS_MANAGER_MODULE Focus Manager + * @brief + * @section CAPI_DALI_TOOLKIT_FOCUS_MANAGER_HEADER Required Header + * \#include + * @section CAPI_DALI_TOOLKIT_FOCUS_MANAGER_MODULE_OVERVIEW Overview + * + * + * + *
    APIDescription
    @ref Dali::Toolkit::FocusManager Manages registration of actors in a focus chain and changing the focused + * actor within that chain.
    @ref Dali::Toolkit::KeyboardFocusManager Provides the functionality of handling keyboard navigation and maintaining the two dimensional keyboard focus chain.
    + */ + +/** + * @ingroup CAPI_DALI_TOOLKIT_MODULE + * @defgroup CAPI_DALI_TOOLKIT_MARKUP_PROCESSOR_MODULE Markup Processor + * @brief + * @section CAPI_DALI_TOOLKIT_MARKUP_PROCESSOR_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_TOOLKIT_MARKUP_PROCESSOR_MODULE_OVERVIEW Overview + * + * + * + * + *
    APIDescription
    @ref Dali::Toolkit::MarkupProcessor::StyledText A pair of Dali::Text and Dali::TextStyle.
    @ref Dali::Toolkit::MarkupProcessor::StyledTextArray Vector of StyledText
    @ref Dali::Toolkit::MarkupProcessor +Dali::Toolkit::MarkupProcessor::GetStyledTextArray() +Dali::Toolkit::MarkupProcessor::GetPlainString() +Dali::Toolkit::MarkupProcessor::GetMarkupString() +Dali::Toolkit::MarkupProcessor::SetTextStyle() +Dali::Toolkit::MarkupProcessor::SetTextStyle() +Dali::Toolkit::MarkupProcessor::SetTextStyleToRange() +
    + */ + +/** + * @ingroup CAPI_DALI_TOOLKIT_MODULE + * @defgroup CAPI_DALI_TOOLKIT_SHADER_EFFECTS_MODULE Shader Effects + * @brief + * @section CAPI_DALI_TOOLKIT_SHADER_EFFECTS_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_TOOLKIT_SHADER_EFFECTS_MODULE_OVERVIEW Overview + * + * + * + * + * + * + * + * + * + * + * + *
    APIDescription
    @ref Dali::Toolkit::DissolveEffect DissolveEffect is a custom shader effect to achieve Dissolve effects in Image actors.
    @ref Dali::Toolkit::ImageRegionEffect ImageRegionEffect is a custom shader effect to show only a region of an Image actor.
    @ref Dali::Toolkit::IrisEffect IrisEffect is a custom shader effect to achieve iris effects in Image actors.
    @ref Dali::Toolkit::MaskEffect MaskEffect is used to control which parts of an image are visible, using the alpha channel of a separate mask image.
    @ref Dali::Toolkit::NinePatchMaskEffect NinePatchMaskEffect is used to control which parts of an image are visible, using the alpha channel of a separate mask image.
    @ref Dali::Toolkit::PageTurnBookSpineEffect This is an assisting effect of PageTurnEffect to display a book spine on _static_ pages, and also to flip the image horizontally when needed.
    @ref Dali::Toolkit::PageTurnEffect PageTurnEffect is a custom shader effect to achieve a page turn effect for Image actors.
    @ref Dali::Toolkit::RippleEffect RippleEffect is a custom shader effect to achieve ripple effects on Image actors
    @ref Dali::Toolkit::Ripple2DEffect Ripple2DEffect is a custom shader effect to achieve 2d ripple effects on Image actors
    @ref Dali::Toolkit::SwirlEffect SwirlEffect is a custom shader effect to achieve swirl effects in Image actors.
    + */ + + +#endif //__DALI_TOOLKIT_DOC_H__ -- 2.7.4