From 58c8ebd3e35f8c5e74204f3602107781758b7fac Mon Sep 17 00:00:00 2001 From: David Steele Date: Fri, 14 Mar 2014 11:18:53 +0000 Subject: [PATCH] Updated CAPI documentation style. Change-Id: Idbf19cf1fc92558e10b2c77cd03fef395225041c Signed-off-by: David Steele --- capi/dali/public-api/actors/actor-enumerations.h | 7 +- capi/dali/public-api/actors/actor.h | 362 ++++++++++------ capi/dali/public-api/actors/blending.h | 43 +- capi/dali/public-api/actors/camera-actor.h | 117 +++-- capi/dali/public-api/actors/custom-actor-impl.h | 69 +-- capi/dali/public-api/actors/custom-actor.h | 31 +- capi/dali/public-api/actors/draw-mode.h | 8 +- capi/dali/public-api/actors/image-actor.h | 204 +++++---- capi/dali/public-api/actors/layer.h | 91 ++-- capi/dali/public-api/actors/mesh-actor.h | 50 ++- capi/dali/public-api/actors/renderable-actor.h | 59 ++- capi/dali/public-api/actors/text-actor.h | 145 ++++--- .../animation/active-constraint-declarations.h | 2 +- capi/dali/public-api/animation/active-constraint.h | 34 +- capi/dali/public-api/animation/alpha-functions.h | 5 +- capi/dali/public-api/animation/animation.h | 330 ++++++++++----- .../public-api/animation/constraint-functions.h | 31 +- capi/dali/public-api/animation/constraint-source.h | 31 +- capi/dali/public-api/animation/constraint.h | 118 ++++-- capi/dali/public-api/animation/constraints.h | 170 +++++++- .../public-api/animation/interpolator-functions.h | 49 ++- capi/dali/public-api/animation/key-frames.h | 46 +- capi/dali/public-api/animation/time-period.h | 12 +- capi/dali/public-api/common/constants.h | 83 ++-- capi/dali/public-api/common/dali-common.h | 29 +- capi/dali/public-api/common/intrusive-ptr.h | 120 ++++-- capi/dali/public-api/common/loading-state.h | 4 +- capi/dali/public-api/common/stage.h | 90 ++-- capi/dali/public-api/common/vector-wrapper.h | 2 +- capi/dali/public-api/events/gesture-detector.h | 33 +- capi/dali/public-api/events/gesture.h | 37 +- capi/dali/public-api/events/key-event.h | 56 ++- .../events/long-press-gesture-detector.h | 59 ++- capi/dali/public-api/events/long-press-gesture.h | 23 +- capi/dali/public-api/events/pan-gesture-detector.h | 84 ++-- capi/dali/public-api/events/pan-gesture.h | 44 +- .../public-api/events/pinch-gesture-detector.h | 35 +- capi/dali/public-api/events/pinch-gesture.h | 30 +- capi/dali/public-api/events/tap-gesture-detector.h | 51 ++- capi/dali/public-api/events/tap-gesture.h | 25 +- capi/dali/public-api/events/touch-event.h | 30 +- capi/dali/public-api/events/touch-point.h | 31 +- capi/dali/public-api/geometry/animatable-mesh.h | 48 ++- capi/dali/public-api/geometry/animatable-vertex.h | 34 +- capi/dali/public-api/images/bitmap-image.h | 55 ++- capi/dali/public-api/images/encoded-buffer-image.h | 19 +- capi/dali/public-api/images/frame-buffer-image.h | 32 +- capi/dali/public-api/images/image-attributes.h | 95 +++-- capi/dali/public-api/images/image.h | 100 +++-- capi/dali/public-api/images/native-image.h | 33 +- capi/dali/public-api/images/pixel.h | 34 +- capi/dali/public-api/math/angle-axis.h | 20 +- capi/dali/public-api/math/compile-time-assert.h | 11 +- capi/dali/public-api/math/compile-time-math.h | 29 +- capi/dali/public-api/math/degree.h | 39 +- capi/dali/public-api/math/math-utils.h | 39 +- capi/dali/public-api/math/matrix.h | 117 +++-- capi/dali/public-api/math/matrix3.h | 81 +++- capi/dali/public-api/math/quaternion.h | 152 ++++--- capi/dali/public-api/math/radian.h | 35 +- capi/dali/public-api/math/random.h | 15 +- capi/dali/public-api/math/rect.h | 282 +++++++------ capi/dali/public-api/math/vector2.h | 131 ++++-- capi/dali/public-api/math/vector3.h | 146 ++++--- capi/dali/public-api/math/vector4.h | 140 +++--- capi/dali/public-api/math/viewport.h | 5 +- capi/dali/public-api/modeling/material.h | 170 +++++--- capi/dali/public-api/object/base-handle.h | 79 ++-- capi/dali/public-api/object/base-object.h | 41 +- capi/dali/public-api/object/constrainable.h | 35 +- capi/dali/public-api/object/handle.h | 82 ++-- capi/dali/public-api/object/object-registry.h | 32 +- capi/dali/public-api/object/property-conditions.h | 44 +- capi/dali/public-api/object/property-index.h | 7 +- capi/dali/public-api/object/property-input.h | 33 +- .../object/property-notification-declarations.h | 8 +- .../dali/public-api/object/property-notification.h | 48 ++- capi/dali/public-api/object/property-types.h | 11 +- capi/dali/public-api/object/property-value.h | 152 ++++--- capi/dali/public-api/object/property.h | 78 ++-- capi/dali/public-api/object/ref-object.h | 29 +- .../public-api/render-tasks/render-task-list.h | 33 +- capi/dali/public-api/render-tasks/render-task.h | 111 +++-- .../dali/public-api/shader-effects/shader-effect.h | 87 ++-- capi/dali/public-api/signals/base-signal.h | 99 +++-- capi/dali/public-api/signals/callback.h | 470 ++++++++++++++++----- .../signals/connection-tracker-interface.h | 15 +- capi/dali/public-api/signals/connection-tracker.h | 10 +- capi/dali/public-api/signals/dali-signal-v2.h | 366 ++++++++++------ capi/dali/public-api/signals/functor-delegate.h | 40 +- .../public-api/signals/signal-slot-connections.h | 31 +- .../public-api/signals/signal-slot-observers.h | 22 +- capi/dali/public-api/signals/slot-delegate.h | 28 +- capi/dali/public-api/text/character.h | 41 +- capi/dali/public-api/text/font-parameters.h | 76 +++- capi/dali/public-api/text/font.h | 144 ++++--- capi/dali/public-api/text/text-style.h | 137 ++++-- capi/dali/public-api/text/text.h | 56 ++- capi/dali_doc.h | 323 ++++++++++++++ 99 files changed, 5051 insertions(+), 2459 deletions(-) create mode 100644 capi/dali_doc.h diff --git a/capi/dali/public-api/actors/actor-enumerations.h b/capi/dali/public-api/actors/actor-enumerations.h index b266e5c..976acec 100644 --- a/capi/dali/public-api/actors/actor-enumerations.h +++ b/capi/dali/public-api/actors/actor-enumerations.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_ACTORS_MODULE * @{ */ @@ -28,7 +28,8 @@ namespace Dali DALI_IMPORT_API { /** - * Actor color mode + * @brief Actor color mode. + * */ enum ColorMode { @@ -39,7 +40,7 @@ enum ColorMode }; /** - * Actor position inheritance mode + * @brief Actor position inheritance mode. */ enum PositionInheritanceMode { diff --git a/capi/dali/public-api/actors/actor.h b/capi/dali/public-api/actors/actor.h index aa0ddbc..9a6c781 100644 --- a/capi/dali/public-api/actors/actor.h +++ b/capi/dali/public-api/actors/actor.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_ACTORS_MODULE * @{ */ @@ -60,14 +60,18 @@ struct Vector2; struct Vector3; struct Vector4; +/** + * @brief Actor container. + */ typedef std::vector ActorContainer; -typedef ActorContainer::iterator ActorIter; -typedef ActorContainer::const_iterator ActorConstIter; +typedef ActorContainer::iterator ActorIter; ///< Iterator for Dali::ActorContainer +typedef ActorContainer::const_iterator ActorConstIter; ///< Const iterator for Dali::ActorContainer /** - * Actor is the primary object which Dali applications interact with. + * @brief Actor is the primary object with which Dali applications interact. + * * UI controls can be built by combining multiple actors. * *

Multi-Touch Events:

@@ -207,11 +211,11 @@ public: // Typedefs - typedef SignalV2< bool (Actor, const TouchEvent&)> TouchSignalV2; - typedef SignalV2< bool (Actor, const MouseWheelEvent&) > MouseWheelEventSignalV2; - typedef SignalV2< void (Actor, const Vector3&) > SetSizeSignalV2; - typedef SignalV2< void (Actor) > OnStageSignalV2; - typedef SignalV2< void (Actor) > OffStageSignalV2; + typedef SignalV2< bool (Actor, const TouchEvent&)> TouchSignalV2; ///< Touch signal type + typedef SignalV2< bool (Actor, const MouseWheelEvent&) > MouseWheelEventSignalV2;///< Mousewheel signal type + typedef SignalV2< void (Actor, const Vector3&) > SetSizeSignalV2; ///< SetSize signal type + typedef SignalV2< void (Actor) > OnStageSignalV2; ///< Stage connection signal type + typedef SignalV2< void (Actor) > OffStageSignalV2; ///< Stage disconnection signal type // Default Properties static const Property::Index PARENT_ORIGIN; ///< name "parent-origin", type VECTOR3 @@ -252,42 +256,48 @@ public: static const Property::Index NAME; ///< name "name", type STRING // Signal Names - static const char* const SIGNAL_TOUCHED; - static const char* const SIGNAL_MOUSE_WHEEL_EVENT; - static const char* const SIGNAL_SET_SIZE; - static const char* const SIGNAL_ON_STAGE; - static const char* const SIGNAL_OFF_STAGE; + static const char* const SIGNAL_TOUCHED; ///< Touched signal name + static const char* const SIGNAL_MOUSE_WHEEL_EVENT;///< Mouse wheel signal name + static const char* const SIGNAL_SET_SIZE; ///< SetSize signal name + static const char* const SIGNAL_ON_STAGE; ///< Stage connection signal name + static const char* const SIGNAL_OFF_STAGE; ///< Stage disconnection signal name //Action Names - static const char* const ACTION_SHOW; - static const char* const ACTION_HIDE; + static const char* const ACTION_SHOW; ///< Show action name + static const char* const ACTION_HIDE; ///< Hide action name // Creation /** - * Create an uninitialized Actor; this can be initialized with Actor::New() + * @brief Create an uninitialized Actor; this can be initialized with Actor::New(). + * * Calling member functions with an uninitialized Dali::Object is not allowed. */ Actor(); /** - * Create an initialized Actor. + * @brief Create an initialized Actor. + * * @return A handle to a newly allocated Dali resource. */ static Actor New(); /** - * Downcast an Object handle to Actor handle. If handle points to a Actor object the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to Actor handle. + * + * If handle points to a Actor object the downcast produces valid + * handle. If not the returned handle is left uninitialized. + * * @param[in] handle to An object * @return handle to a Actor object or an uninitialized handle */ static Actor DownCast( BaseHandle handle ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~Actor(); @@ -298,21 +308,24 @@ public: using BaseHandle::operator=; /** - * Retrieve the Actor's name. + * @brief Retrieve the Actor's name. + * * @pre The Actor has been initialized. * @return The Actor's name. */ const std::string& GetName() const; /** - * Sets the Actor's name. + * @brief Sets the Actor's name. + * * @pre The Actor has been initialized. * @param [in] name The new name. */ void SetName(const std::string& name); /** - * Retrieve the unique ID of the actor. + * @brief Retrieve the unique ID of the actor. + * * @pre The Actor has been initialized. * @return The ID. */ @@ -321,14 +334,16 @@ public: // Containment /** - * Query whether an actor is the root actor, which is owned by the Stage. + * @brief Query whether an actor is the root actor, which is owned by the Stage. + * * @pre The Actor has been initialized. * @return True if the actor is the root actor. */ bool IsRoot() const; /** - * Query whether the actor is connected to the Stage. + * @brief Query whether the actor is connected to the Stage. + * * When an actor is connected, it will be directly or indirectly parented to the root Actor. * @note The root Actor is provided automatically by Dali::Stage, and is always considered to be connected. * @pre The Actor has been initialized. @@ -337,21 +352,24 @@ public: bool OnStage() const; /** - * Query whether the actor is of class Dali::Layer + * @brief Query whether the actor is of class Dali::Layer. + * * @pre The Actor has been initialized. * @return True if the actor is a layer. */ bool IsLayer() const; /** - * Gets the layer in which the actor is present. + * @brief Gets the layer in which the actor is present. + * * @pre The Actor has been initialized. * @return The layer, which will be uninitialized if the actor is off-stage. */ Layer GetLayer(); /** - * Adds a child Actor to this Actor. + * @brief Adds a child Actor to this Actor. + * * NOTE! if the child already has a parent, it will be removed from old parent * and reparented to this actor. This may change childs position, color, shader effect, * scale etc as it now inherits them from this actor @@ -367,7 +385,8 @@ public: void Add(Actor child); /** - * Removes a child Actor from this Actor. + * @brief Removes a child Actor from this Actor. + * * If the actor was not a child of this actor, this is a no-op. * @pre This Actor (the parent) has been initialized. * @pre The child actor is not the same as the parent actor. @@ -377,21 +396,25 @@ public: void Remove(Actor child); /** - * Removes an actor from its parent. If the actor has no parent, this method does nothing. + * @brief Removes an actor from its parent. + * + * If the actor has no parent, this method does nothing. * @pre The (child) actor has been initialized. * @post This may invalidate ActorContainer iterators. */ void Unparent(); /** - * Retrieve the number of children held by the actor. + * @brief Retrieve the number of children held by the actor. + * * @pre The Actor has been initialized. * @return The number of children */ unsigned int GetChildCount() const; /** - * Retrieve and child actor by index + * @brief Retrieve and child actor by index. + * * @pre The Actor has been initialized. * @param[in] index The index of the child to retrieve * @return The actor for the given index or empty handle if children not initialised @@ -399,7 +422,8 @@ public: Actor GetChildAt(unsigned int index) const; /** - * Search through this actor's hierarchy for an actor with the given name. + * @brief Search through this actor's hierarchy for an actor with the given name. + * * The actor itself is also considered in the search * @pre The Actor has been initialized. * @param[in] actorName the name of the actor to find @@ -408,7 +432,8 @@ public: Actor FindChildByName(const std::string& actorName); /** - * Search through this actor's hierarchy for an actor with the given name or alias. + * @brief Search through this actor's hierarchy for an actor with the given name or alias. + * * Actors can customize this function to provide actors with preferred alias' * For example 'previous' could return the last selected child. * If no aliased actor is found then FindChildByName() is called. @@ -419,7 +444,8 @@ public: Actor FindChildByAlias(const std::string& actorAlias); /** - * Search through this actor's hierarchy for an actor with the given unique ID. + * @brief Search through this actor's hierarchy for an actor with the given unique ID. + * * The actor itself is also considered in the search * @pre The Actor has been initialized. * @param[in] id the ID of the actor to find @@ -428,7 +454,8 @@ public: Actor FindChildById(const unsigned int id); /** - * Retrieve the actor's parent. + * @brief Retrieve the actor's parent. + * * @pre The actor has been initialized. * @return A handle to the actor's parent. If the actor has no parent, this handle will be invalid. */ @@ -437,7 +464,8 @@ public: // Positioning /** - * Set the origin of an actor, within its parent's area. + * @brief Set the origin of an actor, within its parent's area. + * * This is expressed in unit coordinates, such that (0.0, 0.0, 0.5) is the top-left corner of the parent, * and (1.0, 1.0, 0.5) is the bottom-right corner. * The default parent-origin is Dali::ParentOrigin::TOP_LEFT (0.0, 0.0, 0.5). @@ -450,7 +478,8 @@ public: void SetParentOrigin(const Vector3& origin); /** - * Retrieve the parent-origin of an actor. + * @brief Retrieve the parent-origin of an actor. + * * @pre The Actor has been initialized. * @note This property can be animated; the return value may not match the value written with SetParentOrigin(). * @return The current parent-origin. @@ -458,9 +487,12 @@ public: Vector3 GetCurrentParentOrigin() const; /** - * Set the anchor-point of an actor. This is expressed in unit coordinates, such that - * (0.0, 0.0, 0.5) is the top-left corner of the actor, and (1.0, 1.0, 0.5) is the bottom-right corner. - * The default anchor point is Dali::AnchorPoint::CENTER (0.5, 0.5, 0.5). + * @brief Set the anchor-point of an actor. + * + * This is expressed in unit coordinates, such that (0.0, 0.0, 0.5) + * is the top-left corner of the actor, and (1.0, 1.0, 0.5) is the + * bottom-right corner. The default anchor point is + * Dali::AnchorPoint::CENTER (0.5, 0.5, 0.5). * An actor position is the distance between its parent-origin, and this anchor-point. * An actor's rotation is centered around its anchor-point. * @see Dali::AnchorPoint for predefined anchor point values @@ -471,7 +503,8 @@ public: void SetAnchorPoint(const Vector3& anchorPoint); /** - * Retrieve the anchor-point of an actor. + * @brief Retrieve the anchor-point of an actor. + * * @pre The Actor has been initialized. * @note This property can be animated; the return value may not match the value written with SetAnchorPoint(). * @return The current anchor-point. @@ -479,7 +512,8 @@ public: Vector3 GetCurrentAnchorPoint() const; /** - * Sets the size of an actor. + * @brief Sets the size of an actor. + * * Geometry can be scaled to fit within this area. * This does not interfere with the actors scale factor. * The actors default depth is the minimum of width & height. @@ -491,7 +525,8 @@ public: void SetSize(float width, float height); /** - * Sets the size of an actor. + * @brief Sets the size of an actor. + * * Geometry can be scaled to fit within this area. * This does not interfere with the actors scale factor. * @pre The actor has been initialized. @@ -503,7 +538,8 @@ public: void SetSize(float width, float height, float depth); /** - * Sets the size of an actor. + * @brief Sets the size of an actor. + * * Geometry can be scaled to fit within this area. * This does not interfere with the actors scale factor. * The actors default depth is the minimum of width & height. @@ -514,7 +550,8 @@ public: void SetSize(const Vector2& size); /** - * Sets the size of an actor. + * @brief Sets the size of an actor. + * * Geometry can be scaled to fit within this area. * This does not interfere with the actors scale factor. * @pre The actor has been initialized. @@ -524,7 +561,8 @@ public: void SetSize(const Vector3& size); /** - * Retrieve the actor's size. + * @brief Retrieve the actor's size. + * * @pre The actor has been initialized. * @note This property can be animated; the return value may not match the value written with SetSize(). * @return The actor's current size. @@ -532,7 +570,8 @@ public: Vector3 GetCurrentSize() const; /** - * Sets the position of the actor. + * @brief Sets the position of the actor. + * * The Actor's z position will be set to 0.0f. * @pre The Actor has been initialized. * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentPosition(). @@ -542,7 +581,8 @@ public: void SetPosition(float x, float y); /** - * Sets the position of the Actor. + * @brief Sets the position of the Actor. + * * @pre The Actor has been initialized. * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentPosition(). * @param [in] x The new x position @@ -552,7 +592,8 @@ public: void SetPosition(float x, float y, float z); /** - * Sets the position of the Actor. + * @brief Sets the position of the Actor. + * * @pre The Actor has been initialized. * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentPosition(). * @param [in] position The new position @@ -560,7 +601,8 @@ public: void SetPosition(const Vector3& position); /** - * Set the position of an actor along the X-axis. + * @brief Set the position of an actor along the X-axis. + * * @pre The Actor has been initialized. * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentPosition(). * @param [in] x The new x position @@ -568,7 +610,8 @@ public: void SetX(float x); /** - * Set the position of an actor along the Y-axis. + * @brief Set the position of an actor along the Y-axis. + * * @pre The Actor has been initialized. * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentPosition(). * @param [in] y The new y position. @@ -576,7 +619,8 @@ public: void SetY(float y); /** - * Set the position of an actor along the Z-axis. + * @brief Set the position of an actor along the Z-axis. + * * @pre The Actor has been initialized. * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentPosition(). * @param [in] z The new z position @@ -584,14 +628,16 @@ public: void SetZ(float z); /** - * Move an actor relative to its existing position. + * @brief Move an actor relative to its existing position. + * * @pre The actor has been initialized. * @param[in] distance The actor will move by this distance. */ void MoveBy(const Vector3& distance); /** - * Retrieve the position of the Actor. + * @brief Retrieve the position of the Actor. + * * @pre The Actor has been initialized. * @note This property can be animated; the return value may not match the value written with SetPosition(). * @return the Actor's current position. @@ -599,7 +645,8 @@ public: Vector3 GetCurrentPosition() const; /** - * Retrieve the world-position of the Actor. + * @brief Retrieve the world-position of the Actor. + * * @note The actor will not have a world-position, unless it has previously been added to the stage. * @pre The Actor has been initialized. * @return The Actor's current position in world coordinates. @@ -607,7 +654,9 @@ public: Vector3 GetCurrentWorldPosition() const; /** - * Set the actors position inheritance mode. Default is to inherit. + * @brief Set the actors position inheritance mode. + * + * The default is to inherit. * Switching this off means that using SetPosition() sets the actor's world position. * @see PositionInheritanceMode * @pre The Actor has been initialized. @@ -616,14 +665,16 @@ public: void SetPositionInheritanceMode( PositionInheritanceMode mode ); /** - * Returns the actors position inheritance mode + * @brief Returns the actors position inheritance mode. + * * @pre The Actor has been initialized. * @return true if the actor inherit's it's parent orientation, false if it uses world orientation. */ PositionInheritanceMode GetPositionInheritanceMode() const; /** - * Sets the rotation of the Actor. + * @brief Sets the rotation of the Actor. + * * An actor's rotation is centered around its anchor point. * @pre The Actor has been initialized. * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentRotation(). @@ -633,7 +684,8 @@ public: void SetRotation(const Degree& angle, const Vector3& axis); /** - * Sets the rotation of the Actor. + * @brief Sets the rotation of the Actor. + * * An actor's rotation is centered around its anchor point. * @pre The Actor has been initialized. * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentRotation(). @@ -643,7 +695,8 @@ public: void SetRotation(const Radian& angle, const Vector3& axis); /** - * Sets the rotation of the Actor. + * @brief Sets the rotation of the Actor. + * * @pre The Actor has been initialized. * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentRotation(). * @param [in] rotation The new rotation. @@ -651,7 +704,8 @@ public: void SetRotation(const Quaternion& rotation); /** - * Apply a relative rotation to an actor. + * @brief Apply a relative rotation to an actor. + * * @pre The actor has been initialized. * @param[in] angle The angle to the rotation to combine with the existing rotation. * @param[in] axis The axis of the rotation to combine with the existing rotation. @@ -659,7 +713,8 @@ public: void RotateBy(const Degree& angle, const Vector3& axis); /** - * Apply a relative rotation to an actor. + * @brief Apply a relative rotation to an actor. + * * @pre The actor has been initialized. * @param[in] angle The angle to the rotation to combine with the existing rotation. * @param[in] axis The axis of the rotation to combine with the existing rotation. @@ -667,14 +722,16 @@ public: void RotateBy(const Radian& angle, const Vector3& axis); /** - * Apply a relative rotation to an actor. + * @brief Apply a relative rotation to an actor. + * * @pre The actor has been initialized. * @param[in] relativeRotation The rotation to combine with the existing rotation. */ void RotateBy(const Quaternion& relativeRotation); /** - * Retreive the Actor's rotation. + * @brief Retreive the Actor's rotation. + * * @pre The Actor has been initialized. * @note This property can be animated; the return value may not match the value written with SetRotation(). * @return The current rotation. @@ -682,7 +739,9 @@ public: Quaternion GetCurrentRotation() const; /** - * Set whether a child actor inherits it's parent's orientation. Default is to inherit. + * @brief Set whether a child actor inherits it's parent's orientation. + * + * Default is to inherit. * Switching this off means that using SetRotation() sets the actor's world orientation. * @pre The Actor has been initialized. * @param[in] inherit - true if the actor should inherit orientation, false otherwise. @@ -690,14 +749,16 @@ public: void SetInheritRotation(bool inherit); /** - * Returns whether the actor inherit's it's parent's orientation. + * @brief Returns whether the actor inherit's it's parent's orientation. + * * @pre The Actor has been initialized. * @return true if the actor inherit's it's parent orientation, false if it uses world orientation. */ bool IsRotationInherited() const; /** - * Retrieve the world-rotation of the Actor. + * @brief Retrieve the world-rotation of the Actor. + * * @note The actor will not have a world-rotation, unless it has previously been added to the stage. * @pre The Actor has been initialized. * @return The Actor's current rotation in the world. @@ -705,7 +766,8 @@ public: Quaternion GetCurrentWorldRotation() const; /** - * Set the scale factor applied to an actor. + * @brief Set the scale factor applied to an actor. + * * @pre The Actor has been initialized. * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentScale(). * @param [in] scale The scale factor applied on all axes. @@ -713,7 +775,8 @@ public: void SetScale(float scale); /** - * Set the scale factor applied to an actor. + * @brief Set the scale factor applied to an actor. + * * @pre The Actor has been initialized. * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentScale(). * @param [in] scaleX The scale factor applied along the x-axis. @@ -723,7 +786,8 @@ public: void SetScale(float scaleX, float scaleY, float scaleZ); /** - * Set the scale factor applied to an actor. + * @brief Set the scale factor applied to an actor. + * * @pre The Actor has been initialized. * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentScale(). * @param [in] scale A vector representing the scale factor for each axis. @@ -731,14 +795,16 @@ public: void SetScale(const Vector3& scale); /** - * Apply a relative scale to an actor. + * @brief Apply a relative scale to an actor. + * * @pre The actor has been initialized. * @param[in] relativeScale The scale to combine with the actors existing scale. */ void ScaleBy(const Vector3& relativeScale); /** - * Retrieve the scale factor applied to an actor. + * @brief Retrieve the scale factor applied to an actor. + * * @pre The Actor has been initialized. * @note This property can be animated; the return value may not match the value written with SetScale(). * @return A vector representing the scale factor for each axis. @@ -746,7 +812,8 @@ public: Vector3 GetCurrentScale() const; /** - * Retrieve the world-scale of the Actor. + * @brief Retrieve the world-scale of the Actor. + * * @note The actor will not have a world-scale, unless it has previously been added to the stage. * @pre The Actor has been initialized. * @return The Actor's current scale in the world. @@ -754,7 +821,9 @@ public: Vector3 GetCurrentWorldScale() const; /** - * Set whether a child actor inherits it's parent's scale. Default is to inherit. + * @brief Set whether a child actor inherits it's parent's scale. + * + * Default is to inherit. * Switching this off means that using SetScale() sets the actor's world scale. * @pre The Actor has been initialized. * @param[in] inherit - true if the actor should inherit scale, false otherwise. @@ -762,14 +831,16 @@ public: void SetInheritScale( bool inherit ); /** - * Returns whether the actor inherit's it's parent's scale. + * @brief Returns whether the actor inherit's it's parent's scale. + * * @pre The Actor has been initialized. * @return true if the actor inherit's it's parent scale, false if it uses world scale. */ bool IsScaleInherited() const; /** - * Retrieves the world-matrix of the actor + * @brief Retrieves the world-matrix of the actor. + * * @note The actor will not have a world-matrix, unless it has previously been added to the stage. * @pre The Actor has been initialized. * @return The Actor's current world matrix @@ -779,7 +850,8 @@ public: // Visibility & Color /** - * Sets the visibility flag of an actor. + * @brief Sets the visibility flag of an actor. + * * @pre The actor has been initialized. * @note This is an asynchronous method; the value written may not match a value subsequently read with IsVisible(). * @note If an actor's visibility flag is set to false, then the actor and its children will not be rendered. @@ -790,7 +862,8 @@ public: void SetVisible(bool visible); /** - * Retrieve the visibility flag of an actor. + * @brief Retrieve the visibility flag of an actor. + * * @pre The actor has been initialized. * @note This property can be animated; the return value may not match the value written with SetVisible(). * @note If an actor is not visible, then the actor and its children will not be rendered. @@ -801,7 +874,8 @@ public: bool IsVisible() const; /** - * Sets the opacity of an actor. + * @brief Sets the opacity of an actor. + * * @pre The actor has been initialized. * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentOpacity(). * @param [in] opacity The new opacity. @@ -809,14 +883,16 @@ public: void SetOpacity(float opacity); /** - * Apply a relative opacity change to an actor. + * @brief Apply a relative opacity change to an actor. + * * @pre The actor has been initialized. * @param[in] relativeOpacity The opacity to combine with the actors existing opacity. */ void OpacityBy(float relativeOpacity); /** - * Retrieve the actor's opacity. + * @brief Retrieve the actor's opacity. + * * @pre The actor has been initialized. * @note This property can be animated; the return value may not match the value written with SetOpacity(). * @return The actor's opacity. @@ -824,7 +900,8 @@ public: float GetCurrentOpacity() const; /** - * Sets the actor's color; this is an RGBA value + * @brief Sets the actor's color; this is an RGBA value. + * * The final color of the actor depends on its color mode. * @pre The Actor has been initialized. * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentColor(). @@ -833,14 +910,17 @@ public: void SetColor(const Vector4& color); /** - * Apply a relative color change to an actor. + * @brief Apply a relative color change to an actor. + * * @pre The actor has been initialized. * @param[in] relativeColor The color to combine with the actors existing color. */ void ColorBy(const Vector4& relativeColor); /** - * Retrieve the actor's color. Actors own color is not clamped. + * @brief Retrieve the actor's color. + * + * Actor's own color is not clamped. * @pre The Actor has been initialized. * @note This property can be animated; the return value may not match the value written with SetColor(). * @return The color. @@ -848,22 +928,26 @@ public: Vector4 GetCurrentColor() const; /** - * Sets the actor's color mode. This specifies whether the Actor uses its own color, - * or inherits its parent color. The default is USE_OWN_MULTIPLY_PARENT_ALPHA. + * @brief Sets the actor's color mode. + * + * This specifies whether the Actor uses its own color, or inherits + * its parent color. The default is USE_OWN_MULTIPLY_PARENT_ALPHA. * @pre The Actor has been initialized. * @param [in] colorMode to use. */ void SetColorMode( ColorMode colorMode ); /** - * Returns the actor's color mode. + * @brief Returns the actor's color mode. + * * @pre The Actor has been initialized. * @return currently used colorMode. */ ColorMode GetColorMode() const; /** - * Retrieve the world-color of the Actor, where each component is clamped within the 0->1 range. + * @brief Retrieve the world-color of the Actor, where each component is clamped within the 0->1 range. + * * @note The actor will not have a world-color, unless it has previously been added to the stage. * @pre The Actor has been initialized. * @return The Actor's current color in the world. @@ -873,7 +957,8 @@ public: // Shader Effects /** - * Set whether the actor inherits a shader effect from its parent; it does inherit by default. + * @brief Set whether the actor inherits a shader effect from its parent; it does inherit by default. + * * The inherited effect can still be overriden using SetShaderEffect(). * @pre The Actor has been initialized. * @param [in] inherit True if the parent effect is inherited. @@ -881,14 +966,16 @@ public: void SetInheritShaderEffect(bool inherit); /** - * Query whether the actor inherits a shader effect from its parent. + * @brief Query whether the actor inherits a shader effect from its parent. + * * @pre The Actor has been initialized. * @return True if the parent effect is inherited. */ bool GetInheritShaderEffect() const; /** - * Sets the shader effect for the Actor. + * @brief Sets the shader effect for the Actor. + * * Shader effects provide special effects like rippling and bending. * Setting a shader effect removes any shader effect previously set by SetShaderEffect. * @pre The actor has been initialized. @@ -898,20 +985,23 @@ public: void SetShaderEffect(ShaderEffect effect); /** - * Retrieve the shader effect for the Actor. + * @brief Retrieve the shader effect for the Actor. + * * @pre The Actor has been initialized. * @return The shader effect */ ShaderEffect GetShaderEffect() const; /** - * Removes the current shader effect. + * @brief Removes the current shader effect. + * * @pre The Actor has been initialized. */ void RemoveShaderEffect(); /** - * Set how the actor and its children should be drawn. + * @brief Set how the actor and its children should be drawn. + * * Not all actors are renderable, but DrawMode can be inherited from any actor. * By default a renderable actor will be drawn as a 3D object. It will be depth-tested against * other objects in the world i.e. it may be obscured if other objects are in front. @@ -932,7 +1022,8 @@ public: void SetDrawMode( DrawMode::Type drawMode ); /** - * Query how the actor and its children will be drawn. + * @brief Query how the actor and its children will be drawn. + * * @return True if the Actor is an overlay. */ DrawMode::Type GetDrawMode() const; @@ -940,7 +1031,8 @@ public: // Input Handling /** - * Sets whether an actor should emit touch event signals; see SignalTouched(). + * @brief Sets whether an actor should emit touch event signals; @see SignalTouched(). + * * An actor is sensitive by default, which means that as soon as an application connects to the SignalTouched(), * the touch event signal will be emitted. * @@ -964,7 +1056,8 @@ public: void SetSensitive(bool sensitive); /** - * Query whether an actor emits touch event signals. + * @brief Query whether an actor emits touch event signals. + * * @note If an actor is not sensitive, then it's children will not be hittable either. * This is regardless of the individual sensitivity values of the children i.e. an actor will only be * hittable if all of its parents have sensitivity set to true. @@ -974,7 +1067,8 @@ public: bool IsSensitive() const; /** - * Converts screen coordinates into the actor's coordinate system using the default camera. + * @brief Converts screen coordinates into the actor's coordinate system using the default camera. + * * @note The actor coordinates are relative to the top-left (0.0, 0.0, 0.5) * @pre The Actor has been initialized. * @param[out] localX On return, the X-coordinate relative to the actor. @@ -986,7 +1080,7 @@ public: bool ScreenToLocal(float& localX, float& localY, float screenX, float screenY) const; /** - * Sets whether the actor should receive a notification when touch motion events leave + * @brief Sets whether the actor should receive a notification when touch motion events leave * the boundary of the actor. * * @note By default, this is set to false as most actors do not require this. @@ -998,15 +1092,18 @@ public: void SetLeaveRequired(bool required); /** - * This returns whether the actor requires touch events whenever touch motion events leave + * @brief This returns whether the actor requires touch events whenever touch motion events leave * the boundary of the actor. + * * @pre The Actor has been initialized. * @return true if a Leave event is required, false otherwise. */ bool GetLeaveRequired() const; /** - * Sets whether the actor should be focusable by keyboard navigation. Default is true. + * @brief Sets whether the actor should be focusable by keyboard navigation. + * + * The default is true. * @pre The Actor has been initialized. * @param[in] focusable - true if the actor should be focusable by keyboard navigation, * false otherwise. @@ -1014,7 +1111,8 @@ public: void SetKeyboardFocusable( bool focusable ); /** - * Returns whether the actor is focusable by keyboard navigation. + * @brief Returns whether the actor is focusable by keyboard navigation. + * * @pre The Actor has been initialized. * @return true if the actor is focusable by keyboard navigation, false if not. */ @@ -1023,7 +1121,8 @@ public: public: // Signals /** - * This signal is emitted when touch input is received. + * @brief This signal is emitted when touch input is received. + * * A callback of the following type may be connected: * @code * bool YourCallbackName(Actor actor, const TouchEvent& event); @@ -1036,7 +1135,8 @@ public: // Signals TouchSignalV2& TouchedSignal(); /** - * This signal is emitted when mouse wheel event is received + * @brief This signal is emitted when mouse wheel event is received. + * * A callback of the following type may be connected: * @code * bool YourCallbackName(Actor actor, const MouseWheelEvent& event); @@ -1049,7 +1149,9 @@ public: // Signals MouseWheelEventSignalV2& MouseWheelEventSignal(); /** - * This signal is emitted when actors size is being set by application code + * @brief Signal to indicate when the actor's size is set by application code. + * + * This signal is emitted when actors size is being set by application code. * This signal is not emitted when size is animated * Note! GetCurrentSize might not return this same size as the set size message may still be queued * A callback of the following type may be connected: @@ -1062,7 +1164,8 @@ public: // Signals SetSizeSignalV2& SetSizeSignal(); /** - * This signal is emitted after the actor has been connected to the stage. + * @brief This signal is emitted after the actor has been connected to the stage. + * * When an actor is connected, it will be directly or indirectly parented to the root Actor. * @note The root Actor is provided automatically by Dali::Stage, and is always considered to be connected. * @@ -1076,11 +1179,14 @@ public: // Signals * B C * / \ \ * D E F + * + * @return The signal */ OnStageSignalV2& OnStageSignal(); /** - * This signal is emitted after the actor has been disconnected from the stage. + * @brief This signal is emitted after the actor has been disconnected from the stage. + * * If an actor is disconnected it either has no parent, or is parented to a disconnected actor. * * @note When the parent of a set of actors is disconnected to the stage, then all of the children @@ -1093,13 +1199,16 @@ public: // Signals * B C * / \ \ * D E F + * + * @return The signal */ OffStageSignalV2& OffStageSignal(); public: // Dynamics /** - * Enable dynamics for this actor. + * @brief Enable dynamics for this actor. + * * The actor will behave as a rigid/soft body in the simulation * @pre The actor is not already acting as a DynamicsBody and IsDynamicsRoot() returns false * @@ -1109,7 +1218,8 @@ public: // Dynamics DynamicsBody EnableDynamics(DynamicsBodyConfig bodyConfig); /** - * Add a joint constraint to this actor + * @brief Add a joint constraint to this actor. + * * @param[in] attachedActor The other actor in the joint * @param[in] offset The offset (relative to this actor) of the origin of the joint * @return The new joint @@ -1120,7 +1230,8 @@ public: // Dynamics DynamicsJoint AddDynamicsJoint( Actor attachedActor, const Vector3& offset ); /** - * Add a joint constraint to this actor + * @brief Add a joint constraint to this actor. + * * @param[in] attachedActor The other actor in the joint * @param[in] offsetA The offset (relative to this actor) of the origin of the joint * @param[in] offsetB The offset (relative to attachedActor) of the origin of the joint @@ -1132,13 +1243,15 @@ public: // Dynamics DynamicsJoint AddDynamicsJoint( Actor attachedActor, const Vector3& offsetA, const Vector3& offsetB ); /** - * Get the number of DynamicsJoint objects added to this actor + * @brief Get the number of DynamicsJoint objects added to this actor. + * * @return The number of DynamicsJoint objects added to this actor */ const int GetNumberOfJoints() const; /** - * Get a joint by index. + * @brief Get a joint by index. + * * @param[in] index The index of the joint. * Use GetNumberOfJoints to get the valid range of indices. * @return The joint. @@ -1146,26 +1259,30 @@ public: // Dynamics DynamicsJoint GetDynamicsJointByIndex( const int index ); /** - * Get the joint between this actor and attachedActor + * @brief Get the joint between this actor and attachedActor. + * * @param[in] attachedActor The other actor in the joint * @return The joint. */ DynamicsJoint GetDynamicsJoint( Actor attachedActor ); /** - * Remove a joint from this actor + * @brief Remove a joint from this actor + * * @param[in] joint The joint to be removed */ void RemoveDynamicsJoint( DynamicsJoint joint ); /** - * Disable dynamics for this actor. + * @brief Disable dynamics for this actor. + * * The actor will be detached from the DynamicsBody/DynamicsJoint associated with it through EnableDynamics */ void DisableDynamics(); /** - * Get the associated DynamicsBody + * @brief Get the associated DynamicsBody. + * * @return A DynamicsBody */ DynamicsBody GetDynamicsBody(); @@ -1173,15 +1290,18 @@ public: // Dynamics 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] actor A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL Actor(Internal::Actor* actor); }; /** - * Helper for discarding an actor handle. If the handle is empty, this method does nothing. - * Otherwise actor.Unparent() will be called, followed by actor.Reset(). + * @brief Helper for discarding an actor handle. + * + * If the handle is empty, this method does nothing. Otherwise + * actor.Unparent() will be called, followed by actor.Reset(). * @param[in,out] actor A handle to an actor, or an empty handle. */ void UnparentAndReset( Actor& actor ); diff --git a/capi/dali/public-api/actors/blending.h b/capi/dali/public-api/actors/blending.h index 0933bac..fbf440d 100644 --- a/capi/dali/public-api/actors/blending.h +++ b/capi/dali/public-api/actors/blending.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_ACTORS_MODULE * @{ */ @@ -30,19 +30,26 @@ namespace Dali DALI_IMPORT_API namespace BlendingMode { - - enum Type - { - OFF, ///< Blending is disabled. - AUTO, ///< Blending is enabled if there is alpha channel. - ON ///< Blending is enabled. - }; +/** + * @brief Blending mode. + * @see Dali::RenderableActor::SetBlendMode() and Dali::RenderableActor::GetBlendMode() + */ +enum Type +{ + OFF, ///< Blending is disabled. + AUTO, ///< Blending is enabled if there is alpha channel. + ON ///< Blending is enabled. +}; } //namespace BlendingMode namespace BlendingFactor { - +/** + * @brief Blending Factor. + * + * @see Dali::RenderableActor::SetBlendFunc() and Dali::RenderableActor::GetBlendFunc() + */ enum Type { ZERO = 0, @@ -66,7 +73,11 @@ enum Type namespace BlendingEquation { - +/** + * @brief Blending Equation. + * + * @see Dali::RenderableActor::SetBlendEquation() and Dali::RenderableActor::GetBlendEquation() + */ enum Type { ADD = 0x8006, @@ -76,13 +87,13 @@ enum Type } // namespace BlendingEquation -extern const BlendingFactor::Type DEFAULT_BLENDING_SRC_FACTOR_RGB; // BlendingFactor::SRC_ALPHA -extern const BlendingFactor::Type DEFAULT_BLENDING_DEST_FACTOR_RGB; // BlendingFactor::ONE_MINUS_SRC_ALPHA -extern const BlendingFactor::Type DEFAULT_BLENDING_SRC_FACTOR_ALPHA; // BlendingFactor::ONE -extern const BlendingFactor::Type DEFAULT_BLENDING_DEST_FACTOR_ALPHA; // BlendingFactor::ONE_MINUS_SRC_ALPHA +extern const BlendingFactor::Type DEFAULT_BLENDING_SRC_FACTOR_RGB; ///< BlendingFactor::SRC_ALPHA +extern const BlendingFactor::Type DEFAULT_BLENDING_DEST_FACTOR_RGB; ///< BlendingFactor::ONE_MINUS_SRC_ALPHA +extern const BlendingFactor::Type DEFAULT_BLENDING_SRC_FACTOR_ALPHA; ///< BlendingFactor::ONE +extern const BlendingFactor::Type DEFAULT_BLENDING_DEST_FACTOR_ALPHA; ///< BlendingFactor::ONE_MINUS_SRC_ALPHA -extern const BlendingEquation::Type DEFAULT_BLENDING_EQUATION_RGB; // BlendingEquation::ADD -extern const BlendingEquation::Type DEFAULT_BLENDING_EQUATION_ALPHA; // BlendingEquation::ADD +extern const BlendingEquation::Type DEFAULT_BLENDING_EQUATION_RGB; ///< BlendingEquation::ADD +extern const BlendingEquation::Type DEFAULT_BLENDING_EQUATION_ALPHA; ///< BlendingEquation::ADD } // namespace Dali diff --git a/capi/dali/public-api/actors/camera-actor.h b/capi/dali/public-api/actors/camera-actor.h index 51eaf13..1bd40a0 100644 --- a/capi/dali/public-api/actors/camera-actor.h +++ b/capi/dali/public-api/actors/camera-actor.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_ACTORS_MODULE * @{ */ @@ -36,7 +36,7 @@ class CameraActor; namespace Camera { /** - * Type determines how camera operates + * @brief Type determines how camera operates. */ enum Type { @@ -45,7 +45,7 @@ enum Type }; /** - * Projection modes + * @brief Projection modes. */ enum ProjectionMode { @@ -56,7 +56,7 @@ enum ProjectionMode } // namespace Camera /** - * Controls a camera. + * @brief Controls a camera. * * Allows the developer to use actor semantics to control a camera. * @@ -74,53 +74,60 @@ class CameraActor : public Actor public: // Default Properties; additional to Actor properties - static const Property::Index TYPE; // Property::STRING, // "type" // Not animatable - static const Property::Index PROJECTION_MODE; // Property::STRING, // "projection-mode" // Not animatable - static const Property::Index FIELD_OF_VIEW; // Property::FLOAT, // "field-of-view" // Not animatable - static const Property::Index ASPECT_RATIO; // Property::FLOAT, // "aspect-ratio" // Not animatable - static const Property::Index NEAR_PLANE_DISTANCE; // Property::FLOAT, // "near-plane-distance" // Not animatable - static const Property::Index FAR_PLANE_DISTANCE; // Property::FLOAT, // "far-plane-distance" // Not animatable - static const Property::Index LEFT_PLANE_DISTANCE; // Property::FLOAT, // "left-plane-distance" // Not animatable - static const Property::Index RIGHT_PLANE_DISTANCE; // Property::FLOAT, // "right-plane-distance" // Not animatable - static const Property::Index TOP_PLANE_DISTANCE; // Property::FLOAT, // "top-plane-distance" // Not animatable - static const Property::Index BOTTOM_PLANE_DISTANCE; // Property::FLOAT, // "bottom-plane-distance"// Not animatable - static const Property::Index TARGET_POSITION; // Property::VECTOR3, // "target" // Not animatable - static const Property::Index PROJECTION_MATRIX; // Property::MATRIX, // "projection-matrix" // Constraint input, not animatable - static const Property::Index VIEW_MATRIX; // Property::MATRIX, // "view-matrix" // constraint input, not abimatable - static const Property::Index INVERT_Y_AXIS; // Property::BOOLEAN, // "invert-y-axis" // Not animatable + static const Property::Index TYPE; ///< Property::STRING, // "type" // Not animatable + static const Property::Index PROJECTION_MODE; ///< Property::STRING, // "projection-mode" // Not animatable + static const Property::Index FIELD_OF_VIEW; ///< Property::FLOAT, // "field-of-view" // Not animatable + static const Property::Index ASPECT_RATIO; ///< Property::FLOAT, // "aspect-ratio" // Not animatable + static const Property::Index NEAR_PLANE_DISTANCE; ///< Property::FLOAT, // "near-plane-distance" // Not animatable + static const Property::Index FAR_PLANE_DISTANCE; ///< Property::FLOAT, // "far-plane-distance" // Not animatable + static const Property::Index LEFT_PLANE_DISTANCE; ///< Property::FLOAT, // "left-plane-distance" // Not animatable + static const Property::Index RIGHT_PLANE_DISTANCE; ///< Property::FLOAT, // "right-plane-distance" // Not animatable + static const Property::Index TOP_PLANE_DISTANCE; ///< Property::FLOAT, // "top-plane-distance" // Not animatable + static const Property::Index BOTTOM_PLANE_DISTANCE; ///< Property::FLOAT, // "bottom-plane-distance"// Not animatable + static const Property::Index TARGET_POSITION; ///< Property::VECTOR3, // "target" // Not animatable + static const Property::Index PROJECTION_MATRIX; ///< Property::MATRIX, // "projection-matrix" // Constraint input, not animatable + static const Property::Index VIEW_MATRIX; ///< Property::MATRIX, // "view-matrix" // constraint input, not abimatable + static const Property::Index INVERT_Y_AXIS; ///< Property::BOOLEAN, // "invert-y-axis" // Not animatable /** - * Create an uninitialized CameraActor handle; Initialise it using CameraActor::New(). - * Calling member functions with an uninitialized Dali::Object is not allowed. + * @brief Create an uninitialized CameraActor handle. + * + * Initialise it using CameraActor::New(). Calling member functions + * with an uninitialized Dali::Object is not allowed. */ CameraActor(); /** - * Create a CameraActor object. + * @brief Create a CameraActor object. * * Sets the default camera perspective projection for the stage's size. @see SetPerspectiveProjection(). + * @return the newly created camera actor. */ static CameraActor New(); /** - * Create a CameraActor object. + * @brief Create a CameraActor object. * * Sets the default camera perspective projection for the given canvas size. @see SetPerspectiveProjection(). * * @param[in] size The canvas size. + * @return the newly created camera actor. */ static CameraActor New( const Size& size ); /** - * Downcast an Object handle to CameraActor. If handle points to a CameraActor the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to CameraActor. + * + * If handle points to a CameraActor the downcast produces valid + * handle. If not the returned handle is left uninitialized. * @param[in] handle to An object * @return handle to a CameraActor or an uninitialized handle */ static CameraActor DownCast( BaseHandle handle ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~CameraActor(); @@ -131,60 +138,73 @@ public: using BaseHandle::operator=; /** - * Set the camera type + * @brief Set the camera type. * The default type is Dali::Camera::LookAtTarget * @param[in] type The camera type */ void SetType( Dali::Camera::Type type ); /** + * @brief Get the type of the camera. + * * @return the type of camera */ Dali::Camera::Type GetType() const; /** - * Set the projection mode + * @brief Set the projection mode. + * * @param[in] mode One of PerspectiveProjection or OrthographicProjection */ void SetProjectionMode( Dali::Camera::ProjectionMode mode ); /** - * Get the projection mode + * @brief Get the projection mode. + * * @return One of PerspectiveProjection or OrthographicProjection */ Dali::Camera::ProjectionMode GetProjectionMode() const; /** - * Set the field of view + * @brief Set the field of view. + * * @param[in] fieldOfView The field of view in radians */ void SetFieldOfView( float fieldOfView ); /** + * @brief Get the field of view in Radians. + * * The default field of view is 45 degrees * @return The field of view in radians */ float GetFieldOfView( ); /** - * Set the aspect ratio + * @brief Set the aspect ratio. + * * @param[in] aspectRatio The aspect ratio */ void SetAspectRatio( float aspectRatio ); /** + * @brief Get the aspect ratio of the camera. + * * The default aspect ratio is 4.0f/3.0f * @return the aspect ratio */ float GetAspectRatio( ); /** - * Sets the near clipping plane + * @brief Sets the near clipping plane distance. + * * @param[in] nearClippingPlane distance of the near clipping plane */ void SetNearClippingPlane( float nearClippingPlane ); /** + * @brief Get the near clipping plane distance. + * * The default near clipping plane is 800.0f, to match the default screen height * Reduce this value to see objects closer to the camera * @return the near clipping plane value @@ -192,26 +212,31 @@ public: float GetNearClippingPlane( ); /** - * Sets the far clipping plane + * @brief Sets the far clipping plane distance. + * * @param[in] farClippingPlane distance of the far clipping plane */ void SetFarClippingPlane( float farClippingPlane ); /** + * @brief Get the far clipping plane distance. + * * The default value is the default near clipping plane + (0xFFFF>>4) * @return the far clipping plane value */ float GetFarClippingPlane( ); /** - * Set the target of the camera + * @brief Set the target position of the camera. + * * @pre Camera type is LookAtTarget * @param[in] targetPosition The position of the target to look at */ void SetTargetPosition( const Vector3& targetPosition ); /** - * Get Camera Target position + * @brief Get Camera Target position. + * * The target position is Vector3::ZERO * @pre Camera type is LookAtTarget * @return The target position of the camera @@ -219,7 +244,8 @@ public: Vector3 GetTargetPosition() const; /** - * Set whether the Y axis is inverted in the update calculation + * @brief Set whether the Y axis is inverted in the update calculation. + * * Inverting the Y axis allows +ve Y down in main coordinate system * The default value is inverted. * @param[in] invertYAxis True if the Y axis should be inverted @@ -227,13 +253,14 @@ public: void SetInvertYAxis(bool invertYAxis); /** - * Get whether the Y axis is inverted. + * @brief Get whether the Y axis is inverted. + * * @return True if the Y axis is inverted, false otherwise */ bool GetInvertYAxis(); /** - * Sets the default camera perspective projection for the given canvas size. + * @brief Sets the default camera perspective projection for the given canvas size. * * Sets the near and far clipping planes, the field of view, the aspect ratio * and the Z position of the actor based on the canvas size so that 1 unit in @@ -249,9 +276,11 @@ public: void SetPerspectiveProjection( const Size& size ); /** - * Sets the camera projection to use orthographic projection. The XY plane is - * centered on the camera axis. The units in the X/Y plane directly equate to - * pixels on an equivalently sized framebuffer. + * @brief Sets the camera projection to use orthographic projection. + * + * The XY plane is centered on the camera axis. The units in the X/Y + * plane directly equate to pixels on an equivalently sized + * framebuffer. * * The Z position of the actor, and the near and far clip planes of the * bounding box match those that would be created by using @@ -262,7 +291,8 @@ public: void SetOrthographicProjection( const Size& size ); /** - * Sets the camera projection to use orthographic projection with the given clip planes. + * @brief Sets the camera projection to use orthographic projection with the given clip planes. + * * This does not change the Z value of the camera actor. * * @param[in] left Distance to left clip plane (normal to camera axis) @@ -274,11 +304,10 @@ public: */ void SetOrthographicProjection( float left, float right, float top, float bottom, float near, float far ); - - public: // Not intended for use by Application developers /** - * This constructor is used by Dali New() methods + * @brief This constructor is used by Dali New() methods. + * * @param [in] actor A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL CameraActor(Internal::CameraActor* actor); diff --git a/capi/dali/public-api/actors/custom-actor-impl.h b/capi/dali/public-api/actors/custom-actor-impl.h index 48ff326..2c7c730 100644 --- a/capi/dali/public-api/actors/custom-actor-impl.h +++ b/capi/dali/public-api/actors/custom-actor-impl.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_ACTORS_MODULE * @{ */ @@ -44,10 +44,14 @@ struct TouchEvent; struct MouseWheelEvent; struct Vector3; +/** + * @brief Pointer to Dali::CustomActorImpl object. + */ typedef IntrusivePtr CustomActorImplPtr; /** - * CustomActorImpl is an abstract base class for custom control implementations. + * @brief CustomActorImpl is an abstract base class for custom control implementations. + * * This provides a series of pure virtual methods, which are called when actor-specific events occur. * An CustomActorImpl is typically owned by a single CustomActor instance; see also CustomActor::New(CustomActorImplPtr). */ @@ -56,18 +60,20 @@ class DALI_IMPORT_API CustomActorImpl : public Dali::RefObject public: /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~CustomActorImpl(); /** - * Used by derived CustomActorImpl instances, to access the public Actor interface. + * @brief Used by derived CustomActorImpl instances, to access the public Actor interface. + * * @return A pointer to self, or an uninitialized pointer if the CustomActorImpl is not owned. */ CustomActor Self() const; /** - * Called after the actor has been connected to the stage. + * @brief Called after the actor has been connected to the stage. + * * When an actor is connected, it will be directly or indirectly parented to the root Actor. * @note The root Actor is provided automatically by Dali::Stage, and is always considered to be connected. * @@ -85,7 +91,8 @@ public: virtual void OnStageConnection() = 0; /** - * Called after the actor has been disconnected from the stage. + * @brief Called after the actor has been disconnected from the stage. + * * If an actor is disconnected it either has no parent, or is parented to a disconnected actor. * * @note When the parent of a set of actors is disconnected to the stage, then all of the children @@ -102,39 +109,45 @@ public: virtual void OnStageDisconnection() = 0; /** - * Called after a child has been added to the owning actor. + * @brief Called after a child has been added to the owning actor. + * * @param[in] child The child which has been added. */ virtual void OnChildAdd(Actor& child) = 0; /** - * Called after a child has been removed from the owning actor. + * @brief Called after a child has been removed from the owning actor. + * * @param[in] child The child being removed. */ virtual void OnChildRemove(Actor& child) = 0; /** - * Called when the owning actor property is set. + * @brief Called when the owning actor property is set. + * * @param[in] index The Property index that was set. * @param[in] propertyValue The value to set. */ virtual void OnPropertySet( Property::Index index, Property::Value propertyValue ) ; /** - * Called when the owning actor's size is set e.g. using Actor::SetSize(). + * @brief Called when the owning actor's size is set e.g. using Actor::SetSize(). + * * @param[in] targetSize The target size. Note that this target size may not match the size returned via Actor::GetSize(). */ virtual void OnSizeSet(const Vector3& targetSize) = 0; /** - * Called when the owning actor's size is animated e.g. using Animation::Resize(). + * @brief Called when the owning actor's size is animated e.g. using Animation::Resize(). + * * @param[in] animation The object which is animating the owning actor. * @param[in] targetSize The target size. Note that this target size may not match the size returned via Actor::GetSize(). */ virtual void OnSizeAnimation(Animation& animation, const Vector3& targetSize) = 0; /** - * Called after a touch-event is received by the owning actor. + * @brief Called after a touch-event is received by the owning actor. + * * @note This must be enabled during construction; see CustomActorImpl::CustomActorImpl(bool) * @param[in] event The touch event. * @return True if the event should be consumed. @@ -142,14 +155,16 @@ public: virtual bool OnTouchEvent(const TouchEvent& event) = 0; /** - * Called after a key-event is received by the actor that has had its focus set. + * @brief Called after a key-event is received by the actor that has had its focus set. + * * @param[in] event the Key Event * @return True if the event should be consumed. */ virtual bool OnKeyEvent(const KeyEvent& event) = 0; /** - * Called after a mouse-wheel-event is received by the owning actor. + * @brief Called after a mouse-wheel-event is received by the owning actor. + * * @note This must be enabled during construction; see CustomActorImpl::SetRequiresMouseWheelEvents(bool) * @param[in] event The mouse wheel event. * @return True if the event should be consumed. @@ -157,17 +172,19 @@ public: virtual bool OnMouseWheelEvent(const MouseWheelEvent& event) = 0; /** - * Called when this actor gains keyboard focus. + * @brief Called when this actor gains keyboard focus. + * */ virtual void OnKeyInputFocusGained() = 0; /** - * Called when this actor loses keyboard focus. + * @brief Called when this actor loses keyboard focus. */ virtual void OnKeyInputFocusLost() = 0; /** - * Called to find a child by an alias. + * @brief Called to find a child by an alias. + * * If an alias for a child exists, return the child otherwise return an empty handle. * For example 'previous' could return the last selected child. * @pre The Actor has been initialized. @@ -179,13 +196,13 @@ public: protected: // For derived classes /** - * Create a CustomActorImpl. + * @brief Create a CustomActorImpl. * @param[in] requiresTouchEvents True if the OnTouchEvent() callback is required. */ CustomActorImpl(bool requiresTouchEvents); /** - * Set whether the custom actor requires mouse wheel events. + * @brief Set whether the custom actor requires mouse wheel events. * @param[in] requiresMouseWheelEvents True if the OnMouseWheelEvent() callback is required. */ void SetRequiresMouseWheelEvents(bool requiresMouseWheelEvents); @@ -193,13 +210,15 @@ protected: // For derived classes public: // Not intended for application developers /** - * Called when ownership of the CustomActorImpl passed to a CustomActor. + * @brief Called when ownership of the CustomActorImpl is passed to a CustomActor. * @pre The CustomActorImpl is not already owned. * @param[in] owner The owning object. */ void Initialize(Internal::CustomActor& owner); /** + * @brief Get the owner. + * * This method is needed when creating additional handle objects to existing objects. * Owner is the Dali::Internal::CustomActor that owns the implementation of the custom actor * inside core. Creation of a handle to Dali public API Actor requires this pointer. @@ -208,22 +227,22 @@ public: // Not intended for application developers Internal::CustomActor* GetOwner() const; /** - * Called when ownership of the CustomActorImpl passed to a CustomActor. + * @brief Called when ownership of the CustomActorImpl is passed to a CustomActor. * @return True if the OnTouchEvent() callback is required. */ bool RequiresTouchEvents() const; /** - * Called when ownership of the CustomActorImpl passed to a CustomActor. + * @brief Called when ownership of the CustomActorImpl is passed to a CustomActor. * @return True if the OnMouseWheelEvent() callback is required. */ bool RequiresMouseWheelEvents() const; private: - Internal::CustomActor* mOwner; - bool mRequiresTouchEvents; - bool mRequiresMouseWheelEvents; + Internal::CustomActor* mOwner; ///< Internal owner of this custom actor implementation + bool mRequiresTouchEvents; ///< Whether the OnTouchEvent() callback is required + bool mRequiresMouseWheelEvents; ///< Whether the OnMouseWheelEvent() callback is required }; } // namespace Dali diff --git a/capi/dali/public-api/actors/custom-actor.h b/capi/dali/public-api/actors/custom-actor.h index 04639fa..c01a766 100644 --- a/capi/dali/public-api/actors/custom-actor.h +++ b/capi/dali/public-api/actors/custom-actor.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_ACTORS_MODULE * @{ */ @@ -35,7 +35,8 @@ class CustomActor; } /** - * CustomActor is a base class for custom UI controls. + * @brief CustomActor is a base class for custom UI controls. + * * The implementation of the control must be supplied; see CustomActorImpl for more details. */ class DALI_IMPORT_API CustomActor : public Actor @@ -43,39 +44,48 @@ class DALI_IMPORT_API CustomActor : public Actor public: /** - * Create an uninitialized CustomActor handle. Only derived versions can be instantiated. + * @brief Create an uninitialized CustomActor handle. + * + * Only derived versions can be instantiated. * Calling member functions with an uninitialized Dali::Object is not allowed. */ CustomActor(); /** - * Downcast an Object handle to CustomActor. If handle points to a CustomActor the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to CustomActor. + * + * If handle points to a CustomActor the downcast produces valid + * handle. If not the returned handle is left uninitialized. + * * @param[in] handle to An object * @return handle to a CustomActor or an uninitialized handle */ static CustomActor DownCast( BaseHandle handle ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes do not contain member data. */ virtual ~CustomActor(); /** - * Retrieve the custom actor implementation. + * @brief Retrieve the custom actor implementation. + * * @return The implementation. */ CustomActorImpl& GetImplementation(); /** - * Retrieve the custom actor implementation. + * @brief Retrieve the custom actor implementation. + * * @return The implementation. */ const CustomActorImpl& GetImplementation() const; /** - * Create an initialised CustomActor. + * @brief Create an initialised CustomActor. + * * @param[in] implementation The implementation for this custom actor. * @return A handle to a newly allocated Dali resource. */ @@ -89,7 +99,8 @@ public: public: // Not intended for application developers /** - * This constructor is used internally to create additional CustomActor handles. + * @brief This constructor is used internally to create additional CustomActor handles. + * * @param [in] actor A pointer to a newly allocated Dali resource */ CustomActor(Internal::CustomActor* actor); diff --git a/capi/dali/public-api/actors/draw-mode.h b/capi/dali/public-api/actors/draw-mode.h index acc82d1..b7e796d 100644 --- a/capi/dali/public-api/actors/draw-mode.h +++ b/capi/dali/public-api/actors/draw-mode.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_ACTORS_MODULE * @{ */ @@ -30,7 +30,11 @@ namespace Dali DALI_IMPORT_API namespace DrawMode { -// Used with Actor::SetDrawMode() +/** + * @brief How the actor and it's children will be drawn. + * + * @see Dali::Actor::SetDrawMode() + */ enum Type { NORMAL = 0, ///< binary 00. The default draw-mode diff --git a/capi/dali/public-api/actors/image-actor.h b/capi/dali/public-api/actors/image-actor.h index af0c67e..bdbf93a 100644 --- a/capi/dali/public-api/actors/image-actor.h +++ b/capi/dali/public-api/actors/image-actor.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_ACTORS_MODULE * @{ */ @@ -39,7 +39,7 @@ class ImageActor; } /** - * An actor for displaying images. + * @brief An actor for displaying images. * * Allows the developer to add an actor to stage which displays the content of an Image object. * @@ -75,63 +75,63 @@ public: static const Property::Index IMAGE; ///< name "image", type MAP {"filename":"", "load-policy":...} /** - * Style determines how the Image is rendered. - * - * @code - * STYLE_QUAD: - * - * 0---------2 0-----------------2 - * | /| | /| - * | A / | | A / | - * | / | | / | - * | / | SCALE (X) | / | - * | / | --------> | / | - * | / | | / | - * | / | | / | - * | / B | | / B | - * |/ | |/ | - * 1---------3 1-----------------3 - * - * Image is rendered as a textured rectangle. The texture - * is scaled uniformly as the quad is resized. - * - * STYLE_NINE_PATCH: - * - * |---|---------------|---| |---|-----------------------------|---| - * | 1 | 2 | 3 | | 1 | 2 | 3 | - * |---|---------------|---| |---|-----------------------------|---| - * | | | | | | | | - * | | | | | | | | - * | 4 | 5 | 6 | SCALE | | | | - * | | | | ----> | | | | - * | | | | | 4 | 5 | 6 | - * |-------------------|---| | | | | - * | 7 | 8 | 9 | | | | | - * |---|---------------|---| | | | | - * |---------------------------------|---| - * | 7 | 8 | 9 | - * |---|-----------------------------|---| - * - * @endcode - * Image is rendered as a textured rectangle. The texture - * is scaled differently over each of the 9 sections. - * - * Visualise a Picture Frame: - * - * - Corner sections (1,3,7,9) are not scaled, regardless - * of how big the Image is. - * - Horizontal edge sections (2,8) are scaled only in the - * X axis as the image increases in width. - * - Vertical edge sections (4,6) are scaled only in the - * Y axis as the image increases in height. - * - Center section (5) is scaled in both X and Y axes as - * the image increases in width and/or height. - * - * Note: If GRID hints are enabled (via a Shader that requires it), - * the above geometry will be further subdivided into rectangles of - * approx. 40x40 in size. - * - */ + * @brief Style determines how the Image is rendered. + * + * @code + * STYLE_QUAD: + * + * 0---------2 0-----------------2 + * | /| | /| + * | A / | | A / | + * | / | | / | + * | / | SCALE (X) | / | + * | / | --------> | / | + * | / | | / | + * | / | | / | + * | / B | | / B | + * |/ | |/ | + * 1---------3 1-----------------3 + * + * Image is rendered as a textured rectangle. The texture + * is scaled uniformly as the quad is resized. + * + * STYLE_NINE_PATCH: + * + * |---|---------------|---| |---|-----------------------------|---| + * | 1 | 2 | 3 | | 1 | 2 | 3 | + * |---|---------------|---| |---|-----------------------------|---| + * | | | | | | | | + * | | | | | | | | + * | 4 | 5 | 6 | SCALE | | | | + * | | | | ----> | | | | + * | | | | | 4 | 5 | 6 | + * |-------------------|---| | | | | + * | 7 | 8 | 9 | | | | | + * |---|---------------|---| | | | | + * |---------------------------------|---| + * | 7 | 8 | 9 | + * |---|-----------------------------|---| + * + * @endcode + * Image is rendered as a textured rectangle. The texture + * is scaled differently over each of the 9 sections. + * + * Visualise a Picture Frame: + * + * - Corner sections (1,3,7,9) are not scaled, regardless + * of how big the Image is. + * - Horizontal edge sections (2,8) are scaled only in the + * X axis as the image increases in width. + * - Vertical edge sections (4,6) are scaled only in the + * Y axis as the image increases in height. + * - Center section (5) is scaled in both X and Y axes as + * the image increases in width and/or height. + * + * Note: If GRID hints are enabled (via a Shader that requires it), + * the above geometry will be further subdivided into rectangles of + * approx. 40x40 in size. + * + */ enum Style { STYLE_QUAD, ///< As a simple quad. @@ -139,25 +139,30 @@ public: }; /** - * Pixel area is relative to the top-left (0,0) of the image. + * @brief Pixel area is relative to the top-left (0,0) of the image. */ typedef Rect PixelArea; /** - * Create an uninitialized ImageActor handle; this can be initialized with ImageActor::New(...) + * @brief Create an uninitialized ImageActor handle. + * + * This can be initialized with ImageActor::New(...) * Calling member functions with an uninitialized Dali::Object is not allowed. */ ImageActor(); /** - * Create an empty image actor object. + * @brief Create an empty image actor object. + * * @return A handle to a newly allocated actor. */ static ImageActor New(); /** - * Create a image actor object. The actor will take the image's - * natural size unless a custom size is chosen, e.g. via Actor:SetSize() + * @brief Create a image actor object. + * + * The actor will take the image's natural size unless a custom size + * is chosen, e.g. via Actor:SetSize() * @pre image must be initialized. * @param[in] image The image to display. * @return A handle to a newly allocated actor. @@ -165,7 +170,8 @@ public: static ImageActor New(Image image); /** - * Create a image actor object. + * @brief Create a image actor object. + * * When the image is loaded the actor's size will reset to the pixelArea, * unless a custom size was chosen, e.g. via Actor:SetSize(). * @pre image must be initialized. @@ -177,15 +183,20 @@ public: static ImageActor New(Image image, PixelArea pixelArea); /** - * Downcast an Object handle to ImageActor. If handle points to a ImageActor the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to ImageActor. + * + * + * If handle points to a ImageActor the downcast produces valid + * handle. If not the returned handle is left uninitialized. + * * @param[in] handle to An object * @return handle to a ImageActor or an uninitialized handle */ static ImageActor DownCast( BaseHandle handle ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~ImageActor(); @@ -196,7 +207,8 @@ public: using BaseHandle::operator=; /** - * Set the image rendered by the actor. + * @brief Set the image rendered by the actor. + * * When the image is loaded the actor's size will be reset to the image size, * unless a custom size was chosen, e.g. via Actor:SetSize() or a pixel area * was set. @@ -207,15 +219,19 @@ public: void SetImage(Image image); /** - * Retrieve the image rendered by the actor's attachment. + * @brief Retrieve the image rendered by the actor's attachment. + * * @return The image. */ Image GetImage(); /** - * Tell the image actor to use the natural size of the current image - * or future images. Calling SetSize on this actor or animating the size - * of the actor overrides this behaviour. + * @brief Tell the image actor to use the natural size of the current image + * or future images. + * + * Calling SetSize on this actor or animating the size of the actor + * overrides this behaviour. + * * @post The image actor uses the natural image size after an image * has been loaded. * @note Actor::SetSizeSignal() will be triggered if there is a current image. @@ -223,7 +239,8 @@ public: void SetToNaturalSize(); /** - * Set a region of the image to display, in pixels. + * @brief Set a region of the image to display, in pixels. + * * When the image is loaded the actor's size will be reset to the pixelArea, * unless a custom size was chosen, e.g. via Actor:SetSize(). * Note! PixelArea should be inside the image data size. It gets clamped by GL @@ -234,21 +251,24 @@ public: void SetPixelArea(const PixelArea& pixelArea); /** - * Retrieve the region of the image to display, in pixels. + * @brief Retrieve the region of the image to display, in pixels. + * * @pre image must be initialized. * @return The pixel area, or a default-constructed area if none was set. */ PixelArea GetPixelArea() const; /** - * Query whether a pixel area has been set. + * @brief Query whether a pixel area has been set. + * * @pre image must be initialized. * @return True if a pixel area has been set. */ bool IsPixelAreaSet() const; /** - * Remove any pixel areas specified with SetPixelArea; the entire image will be displayed. + * @brief Remove any pixel areas specified with SetPixelArea; the entire image will be displayed. + * * The actor size will change to that of the Image unless a custom size was set, e.g. via * Actor::SetSize(). * @pre image must be initialized. @@ -256,21 +276,24 @@ public: void ClearPixelArea(); /** - * Set how the image is rendered; the default is STYLE_QUAD. + * @brief Set how the image is rendered; the default is STYLE_QUAD. + * * @pre image must be initialized. * @param [in] style The new style. */ void SetStyle(Style style); /** - * Query how the image is rendered. + * @brief Query how the image is rendered. + * * @pre image must be initialized. * @return The rendering style. */ Style GetStyle() const; /** - * Set the border used with STYLE_NINE_PATCH. + * @brief Set the border used with STYLE_NINE_PATCH. + * * The values are in pixels from the left, top, right, and bottom of the image respectively. * i.e. SetNinePatchBorder( Vector4(1,2,3,4) ) sets the left-border to 1, top-border to 2, right-border to 3, and bottom-border to 4 pixels. * @param [in] border The new nine-patch border. @@ -278,42 +301,49 @@ public: void SetNinePatchBorder(const Vector4& border); /** - * Retrieve the border used with STYLE_NINE_PATCH. + * @brief Retrieve the border used with STYLE_NINE_PATCH. + * * @return The nine-patch border. */ Vector4 GetNinePatchBorder() const; /** - * Set whether the image should gradually fade in when first rendered. + * @brief Set whether the image should gradually fade in when first rendered. + * * @pre image must be initialized. * @param [in] enableFade True if the image should fade in. */ void SetFadeIn(bool enableFade); /** - * Query whether the image will gradually fade in when first rendered. + * @brief Query whether the image will gradually fade in when first rendered. + * * @pre image must be initialized. * @return True if the image will fade in. */ bool GetFadeIn() const; /** - * Set the duration of the fade-in effect; the default is 1 second. + * @brief Set the duration of the fade-in effect; the default is 1 second. + * * @pre image must be initialized. * @param [in] durationSeconds The duration in seconds. */ void SetFadeInDuration(float durationSeconds); /** - * Retrieve the duration of the fade-in effect. + * @brief Retrieve the duration of the fade-in effect. + * * @pre image must be initialized. * @return The duration in seconds. */ float GetFadeInDuration() const; /** - * Retrieve the size of the displayed image within the image actor. The size of the image may be - * different to that of the image actor size depending on the geometry scaling used. + * @brief Retrieve the size of the displayed image within the image actor. + * + * The size of the image may be different to that of the image actor + * size depending on the geometry scaling used. * @pre image must be initialized. * @return The actual size of the image shown. * @note If a pixel area is set then this returns the size of the pixel area shown. diff --git a/capi/dali/public-api/actors/layer.h b/capi/dali/public-api/actors/layer.h index f6a3054..fc00fde 100644 --- a/capi/dali/public-api/actors/layer.h +++ b/capi/dali/public-api/actors/layer.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_ACTORS_MODULE * @{ */ @@ -37,10 +37,15 @@ namespace Internal DALI_INTERNAL class Layer; } +/** + * @brief Rectangle describing area on screen that a layer can draw to. + * + * @see Dali::Layer::SetClippingBox() + */ typedef Rect ClippingBox; /** - * Layers provide a mechanism for overlaying groups of actors on-top of each other. + * @brief Layers provide a mechanism for overlaying groups of actors on top of each other. * * When added to the stage, a layer can be ordered relative to other layers. The bottom * layer is at depth zero. The stage provides a default layer for it's children. @@ -61,13 +66,13 @@ public: static const Property::Index CLIPPING_BOX; ///< name "clipping-box", type RECTANGLE // Action Names - static const char* const ACTION_RAISE; - static const char* const ACTION_LOWER; - static const char* const ACTION_RAISE_TO_TOP; - static const char* const ACTION_LOWER_TO_BOTTOM; + static const char* const ACTION_RAISE; ///< name "raise" + static const char* const ACTION_LOWER; ///< name "lower" + static const char* const ACTION_RAISE_TO_TOP; ///< name "raise-to-top" + static const char* const ACTION_LOWER_TO_BOTTOM; ///< name "lower-to-bottom" /** - * The sort function type + * @brief The sort function type. * * The position value is the actor translation from camera. * The sortModifier is the user value that can be used to sort coplanar actors/nodes. This value is @@ -79,26 +84,32 @@ public: typedef float (*SortFunctionType)(const Vector3& position, float sortModifier); /** - * Create an empty Layer handle. This can be initialised with Layer::New(...) + * @brief Create an empty Layer handle. + * + * This can be initialised with Layer::New(...) */ Layer(); /** - * Create a Layer object + * @brief Create a Layer object. + * * @return A handle to a newly allocated Layer */ static Layer New(); /** - * Downcast an Object handle to Layer. If handle points to a Layer the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to Layer. + * + * If handle points to a Layer the downcast produces valid + * handle. If not the returned handle is left uninitialized. * @param[in] handle to An object * @return handle to a Layer or an uninitialized handle */ static Layer DownCast( BaseHandle handle ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~Layer(); @@ -109,7 +120,8 @@ public: using BaseHandle::operator=; /** - * Query the depth of the layer + * @brief Query the depth of the layer + * * 0 is bottom most layer, higher number is on top * @pre layer is on the stage * If layer is not added to the stage, returns 0. @@ -118,19 +130,22 @@ public: unsigned int GetDepth() const; /** - * Increment the depth of the layer. + * @brief Increment the depth of the layer. + * * @pre layer is on the stage */ void Raise(); /** - * Decrement the depth of the layer. + * @brief Decrement the depth of the layer. + * * @pre layer is on the stage */ void Lower(); /** - * Ensures the layers depth is greater than the target layer + * @brief Ensures the layers depth is greater than the target layer. + * * If the layer already is above target layer its depth is not changed * If the layer was below target, its new depth will be immediately above target * Note! All layers between this layer and target get new depth values @@ -141,7 +156,8 @@ public: void RaiseAbove( Layer target ); /** - * Ensures the layers depth is less than the target layer + * @brief Ensures the layers depth is less than the target layer. + * * If the layer already is below the layer its depth is not changed * If the layer was above target, its new depth will be immediately below target * Note! All layers between this layer and target get new depth values @@ -152,19 +168,20 @@ public: void LowerBelow( Layer target ); /** - * Raises the layer to the top. + * @brief Raises the layer to the top. * @pre layer is on the stage */ void RaiseToTop(); /** - * Lowers the layer to the bottom. + * @brief Lowers the layer to the bottom. * @pre layer is on the stage */ void LowerToBottom(); /** - * Moves the layer directly above the given layer + * @brief Moves the layer directly above the given layer. + * * After the call this layers depth will be immediately above target * Note! All layers between this layer and target get new depth values * @pre layer is on the stage @@ -174,7 +191,8 @@ public: void MoveAbove( Layer target ); /** - * Moves the layer directly below the given layer + * @brief Moves the layer directly below the given layer. + * * After the call this layers depth will be immediately below target * Note! All layers between this layer and target get new depth values * @pre layer is on the stage @@ -184,22 +202,26 @@ public: void MoveBelow( Layer target ); /** - * Sets whether clipping is enabled for a layer. + * @brief Sets whether clipping is enabled for a layer. + * * Clipping is initially disabled; see also SetClippingBox(). * @param [in] enabled True if clipping is enabled. */ void SetClipping(bool enabled); /** - * Query whether clipping is enabled for a layer. + * @brief Query whether clipping is enabled for a layer. * @return True if clipping is enabled. */ bool IsClipping() const; /** - * Sets the clipping box of a layer, in window coordinates. + * @brief Sets the clipping box of a layer, in window coordinates. + * * The contents of the layer will not be visible outside this box, when clipping is * enabled. The default clipping box is empty (0,0,0,0). + * This has the limitation that it only applies to rectangles on a window. + * For other kinds of clipping, @see Dali::Actor::SetDrawMode(). * @param [in] x The X-coordinate of the lower-left corner. * @param [in] y The Y-coordinate of the lower-left corner. * @param [in] width The width of the box. @@ -208,7 +230,8 @@ public: void SetClippingBox(int x, int y, int width, int height); /** - * Sets the clipping box of a layer, in window coordinates. + * @brief Sets the clipping box of a layer, in window coordinates. + * * The contents of the layer will not be visible outside this box, when clipping is * enabled. The default clipping box is empty (0,0,0,0). * @param [in] box The clipping box @@ -216,7 +239,8 @@ public: void SetClippingBox(ClippingBox box); /** - * Retrieves the clipping box of a layer, in window coordinates. + * @brief Retrieves the clipping box of a layer, in window coordinates. + * * @return The clipping box */ ClippingBox GetClippingBox() const; @@ -224,7 +248,7 @@ public: // Depth test /** - * Whether to disable the depth test. + * @brief Whether to disable the depth test. * * By default a layer enables depth test if there is more than one opaque actor or if there is one opaque actor and one, or more, transparent actors. * However, it's possible to disable the depth test by calling this method. @@ -234,7 +258,7 @@ public: void SetDepthTestDisabled( bool disable ); /** - * Retrieves whether depth test is disabled. + * @brief Retrieves whether depth test is disabled. * * @return \e true if depth test is disabled. */ @@ -243,7 +267,7 @@ public: // Sorting /** - * This sort function sorts actors according to the Z-value in the camera coordinate system. + * @brief This sort function sorts translucent actors according to the Z-value in view space. * * This is useful for 2D user interfaces. * @@ -251,11 +275,15 @@ public: * * We return a negative z value as in our translation, a low z means that it should * be sorted further away and a high z means that it should be closer. + * @param[in] position position of actor in view space + * @param[in] sortModifier additional sort modifer + * @return depth */ static float ZValue(const Vector3& position, float sortModifier); /** - * This allows the user to specify the sort function that the layer should use. + * @brief This allows the user to specify the sort function that the layer should use. + * * The sort function is used to determine the order in which the actors are drawn * and input is processed on the actors in the layer. * @@ -277,7 +305,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] Layer A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL Layer(Internal::Layer* Layer); diff --git a/capi/dali/public-api/actors/mesh-actor.h b/capi/dali/public-api/actors/mesh-actor.h index e3bf32d..9059603 100644 --- a/capi/dali/public-api/actors/mesh-actor.h +++ b/capi/dali/public-api/actors/mesh-actor.h @@ -19,7 +19,7 @@ /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_ACTORS_MODULE * @{ */ @@ -39,9 +39,9 @@ class MeshActor; } /** - * This actor is used to draw one or more mesh geometries, passed in on creation. It allows - * for a custom material to be drawn on the mesh. + * @brief This actor is used to draw a mesh geometry with a material. * + * It allows for a custom material to be drawn on the mesh. * By default CullFaceMode is set to CullBack to enable back face culling. */ class DALI_IMPORT_API MeshActor : public RenderableActor @@ -49,41 +49,48 @@ class DALI_IMPORT_API MeshActor : public RenderableActor public: /** - * Create an uninitialized MeshActor handle. This can be initialised with MeshActor::New(). + * @brief Create an uninitialized MeshActor handle. + * + * This can be initialised with MeshActor::New(). * Calling member functions with an uninitialized Dali::Object is not allowed. */ MeshActor(); /** - * Create a MeshActor object. + * @brief Create a MeshActor object. * @return the newly allocated MeshActor object */ static MeshActor New(); /** - * Create a MeshActor object. + * @brief Create a MeshActor object. + * * @param[in] mesh the Mesh the actor will use. * @return the newly allocated MeshActor object */ static MeshActor New( Mesh mesh ); /** - * Create a MeshActor object + * @brief Create a MeshActor object + * * @param[in] mesh the Animated Mesh the actor will use. * @return the newly allocated MeshActor object */ static MeshActor New( AnimatableMesh mesh ); /** - * Downcast an Object handle to MeshActor. If handle points to a MeshActor the - * downcast produces a valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to MeshActor. + * + * If handle points to a MeshActor the downcast produces a valid + * handle. If not the returned handle is left uninitialized. * @param[in] handle to an object * @return handle to a MeshActor or an uninitialized handle */ static MeshActor DownCast( BaseHandle handle ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~MeshActor(); @@ -94,7 +101,8 @@ public: using BaseHandle::operator=; /** - * Set a custom material on the given actor or one of it's children. + * @brief Set a custom material on the given actor or one of it's children. + * * @pre the mesh is loaded * @param[in] actor The first actor in the tree of model actors * @param[in] actorName The name of the actor to search for. @@ -104,7 +112,8 @@ public: static void SetMaterial(Actor actor, const std::string& actorName, Material material); /** - * Set a custom material on this actor + * @brief Set a custom material on this actor. + * * @pre the mesh is loaded * @param[in] material The custom material.@n * Pass an uninitialised Material to revert to the original material. @@ -112,15 +121,17 @@ public: void SetMaterial(Material material); /** - * Get the material for this mesh actor + * @brief Get the material for this mesh actor. + * * @pre the mesh is loaded * @return The material */ Material GetMaterial() const; /** - * Set whether this mesh actor should be affected by lights in the - * scene. If it set to false, then the mesh will be unaffected by + * @brief Set whether this mesh actor should be affected by lights in the scene. + * + * If it is set to false, then the mesh will be unaffected by * lighting, and will be drawn with flat lighting, applying * the material's diffuse & ambient colors and the actor's color to the * material texture. If it is set to true, and there are no lights in the @@ -133,13 +144,15 @@ public: void SetAffectedByLighting(bool affectedByLighting); /** - * Get the lighting status + * @brief Get the lighting status. + * * @return true if the actor is affected by the scene lighting, or false if its evenly lit. */ bool IsAffectedByLighting(); /** - * Search the actor tree for all named bones in the mesh and connect them. + * @brief Search the actor tree for all named bones in the mesh and connect them. + * * @param[in] rootActor The root actor of the actor tree. */ void BindBonesToMesh(Actor rootActor); @@ -147,7 +160,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] actor A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL MeshActor(Internal::MeshActor* actor); diff --git a/capi/dali/public-api/actors/renderable-actor.h b/capi/dali/public-api/actors/renderable-actor.h index 25a5d8e..b20192a 100644 --- a/capi/dali/public-api/actors/renderable-actor.h +++ b/capi/dali/public-api/actors/renderable-actor.h @@ -19,7 +19,7 @@ /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_ACTORS_MODULE * @{ */ @@ -35,7 +35,7 @@ class RenderableActor; } /** - * Face culling modes + * @brief Face culling modes. */ enum CullFaceMode { @@ -47,7 +47,7 @@ enum CullFaceMode /** - * An base class for renderable actors + * @brief A base class for renderable actors. */ class DALI_IMPORT_API RenderableActor : public Actor { @@ -56,13 +56,16 @@ public: static const BlendingMode::Type DEFAULT_BLENDING_MODE; ///< default value is BlendingMode::AUTO /** - * Create an uninitialized actor. + * @brief Create an uninitialized actor. + * * Calling member functions with an uninitialized Dali::Object is not allowed. */ RenderableActor(); /** - * Downcast an Object handle to RenderableActor. If handle points to a RenderableActor the + * @brief Downcast an Object handle to RenderableActor. + * + * If handle points to a RenderableActor the * downcast produces valid handle. If not the returned handle is left uninitialized. * @param[in] handle to An object * @return handle to a RenderableActor or an uninitialized handle @@ -70,7 +73,8 @@ public: static RenderableActor DownCast( BaseHandle handle ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~RenderableActor(); @@ -81,7 +85,8 @@ public: using BaseHandle::operator=; /** - * Allows modification of an actors position in the depth sort algorithm. + * @brief Allows modification of an actors position in the depth sort algorithm. + * * The offset can be altered for each coplanar actor hence allowing an order of painting. * @pre The Actor has been initialized. * @param [in] depthOffset the offset to be given to the actor. Positive values pushing it further back. @@ -89,7 +94,8 @@ public: void SetSortModifier(float depthOffset); /** - * Retrieves the offset used to modify an actors position in the depth sort algorithm. + * @brief Retrieves the offset used to modify an actors position in the depth sort algorithm. + * * The offset can be altered for each coplanar actor hence allowing an order of painting. * @pre The Actor has been initialized. * @return the offset that has been given to the actor. Positive values pushing it further back. @@ -97,19 +103,21 @@ public: float GetSortModifier() const; /** - * Set the face-culling mode for this actor. + * @brief Set the face-culling mode for this actor. + * * @param[in] mode The culling mode. */ void SetCullFace(CullFaceMode mode); /** - * Retrieve the face-culling mode for this actor. + * @brief Retrieve the face-culling mode for this actor. + * * @return mode The culling mode. */ CullFaceMode GetCullFace() const; /** - * Sets the blending mode. + * @brief Sets the blending mode. * * Possible values are: BlendingMode::OFF, BlendingMode::AUTO and BlendingMode::ON. Default is BlendingMode::AUTO. * @@ -126,14 +134,14 @@ public: void SetBlendMode( BlendingMode::Type mode ); /** - * Retrieves the blending mode. + * @brief Retrieves the blending mode. * * @return The blending mode, one of BlendingMode::OFF, BlendingMode::AUTO or BlendingMode::ON. */ BlendingMode::Type GetBlendMode() const; /** - * Specify the pixel arithmetic used when the actor is blended. + * @brief Specify the pixel arithmetic used when the actor is blended. * * @param[in] srcFactorRgba Specifies how the red, green, blue, and alpha source blending factors are computed. * The options are BlendingFactor::ZERO, ONE, SRC_COLOR, ONE_MINUS_SRC_COLOR, DST_COLOR, ONE_MINUS_DST_COLOR, @@ -148,7 +156,7 @@ public: void SetBlendFunc( BlendingFactor::Type srcFactorRgba, BlendingFactor::Type destFactorRgba ); /** - * Specify the pixel arithmetic used when the actor is blended. + * @brief Specify the pixel arithmetic used when the actor is blended. * * @param[in] srcFactorRgb Specifies how the red, green, and blue source blending factors are computed. * The options are BlendingFactor::ZERO, ONE, SRC_COLOR, ONE_MINUS_SRC_COLOR, DST_COLOR, ONE_MINUS_DST_COLOR, @@ -170,7 +178,8 @@ public: BlendingFactor::Type srcFactorAlpha, BlendingFactor::Type destFactorAlpha ); /** - * Query the pixel arithmetic used when the actor is blended. + * @brief Query the pixel arithmetic used when the actor is blended. + * * @param[out] srcFactorRgb Specifies how the red, green, blue, and alpha source blending factors are computed. * @param[out] destFactorRgb Specifies how the red, green, blue, and alpha destination blending factors are computed. * @param[out] srcFactorAlpha Specifies how the red, green, blue, and alpha source blending factors are computed. @@ -180,14 +189,16 @@ public: BlendingFactor::Type& srcFactorAlpha, BlendingFactor::Type& destFactorAlpha ) const; /** - * Specify the equation used when the actor is blended. - * @param[in] equationRgba The equation used for combining red, green, blue, and alpha components. + * @brief Specify the equation used when the actor is blended. + * * The options are BlendingEquation::ADD, SUBTRACT, or REVERSE_SUBTRACT. + * @param[in] equationRgba The equation used for combining red, green, blue, and alpha components. */ void SetBlendEquation( BlendingEquation::Type equationRgba ); /** - * Specify the equation used when the actor is blended. + * @brief Specify the equation used when the actor is blended. + * * @param[in] equationRgb The equation used for combining red, green, and blue components. * @param[in] equationAlpha The equation used for combining the alpha component. * The options are BlendingEquation::ADD, SUBTRACT, or REVERSE_SUBTRACT. @@ -195,20 +206,23 @@ public: void SetBlendEquation( BlendingEquation::Type equationRgb, BlendingEquation::Type equationAlpha ); /** - * Query the equation used when the actor is blended. + * @brief Query the equation used when the actor is blended. + * * @param[out] equationRgb The equation used for combining red, green, and blue components. * @param[out] equationAlpha The equation used for combining the alpha component. */ void GetBlendEquation( BlendingEquation::Type& equationRgb, BlendingEquation::Type& equationAlpha ) const; /** - * Specify the color used when the actor is blended; the default is Vector4::ZERO. + * @brief Specify the color used when the actor is blended; the default is Vector4::ZERO. + * * @param[in] color The blend color. */ void SetBlendColor( const Vector4& color ); /** - * Query the color used when the actor is blended. + * @brief Query the color used when the actor is blended. + * * @return The blend color. */ const Vector4& GetBlendColor() const; @@ -216,7 +230,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] actor A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL RenderableActor(Internal::RenderableActor* actor); diff --git a/capi/dali/public-api/actors/text-actor.h b/capi/dali/public-api/actors/text-actor.h index 8f8b9b7..ee1da20 100644 --- a/capi/dali/public-api/actors/text-actor.h +++ b/capi/dali/public-api/actors/text-actor.h @@ -19,7 +19,7 @@ /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_ACTORS_MODULE * @{ */ @@ -45,7 +45,7 @@ class TextActor; } /** - * TextActor is a basic actor for displaying a text label + * @brief TextActor is a basic actor for displaying a text label * * By default the text actor always uses the natural size of the text when SetText is called, * unless SetSize is called to override the size or size is animated to some other size. @@ -58,10 +58,10 @@ class DALI_IMPORT_API TextActor : public RenderableActor { public: - typedef SignalV2< void (TextActor) > TextSignalV2; + typedef SignalV2< void (TextActor) > TextSignalV2; ///< Text available signal type //Signal Names - static const char* const SIGNAL_TEXT_LOADING_FINISHED; + static const char* const SIGNAL_TEXT_LOADING_FINISHED; ///< name "text-loading-finished" // Default Properties; additional to RenderableActor properties static const Property::Index TEXT; ///< name "text" type STRING @@ -88,19 +88,23 @@ public: static const Property::Index TEXT_COLOR; ///< name "text-color" type VECTOR4 /** - * Create an uninitialized TextActor handle. This can be initialised with TextActor::New(). + * @brief Create an uninitialized TextActor handle. + * + * This can be initialised with TextActor::New(). * Calling member functions with an uninitialized handle is not allowed. */ TextActor(); /** - * Create a TextActor object with no text + * @brief Create a TextActor object with no text. + * * @return A handle to a newly allocated Dali resource. */ static TextActor New(); /** - * Create a TextActor object with LeftToRight text and font detection + * @brief Create a TextActor object with LeftToRight text and font detection + * * @param [in] text The text which will be displayed * @return A handle to a newly allocated Dali resource. */ @@ -112,7 +116,8 @@ public: static TextActor New(const Text& text); /** - * Create a TextActor object with LeftToRight text + * @brief Create a TextActor object with LeftToRight text. + * * @param [in] text The text which will be displayed * @param [in] fontDetection Try to detect font in case text is not supported with current one. * @return A handle to a newly allocated Dali resource. @@ -125,7 +130,8 @@ public: static TextActor New(const Text& text, bool fontDetection); /** - * Create a TextActor object + * @brief Create a TextActor object. + * * @param [in] text The text which will be displayed * @param [in] fontDetection Try to detect font in case text is not supported with current one. * @param [in] isLeftToRight Text is displayed from left to right if true, otherwise from right to left. @@ -139,7 +145,8 @@ public: static TextActor New(const Text& text, bool fontDetection, bool isLeftToRight); /** - * Create a TextActor object with LeftToRight text and font detection + * @brief Create a TextActor object with LeftToRight text and font detection. + * * @param [in] text The text which will be displayed * @param [in] font The font which will be used for the text * @return A handle to a newly allocated Dali resource. @@ -152,7 +159,8 @@ public: static TextActor New(const Text& text, Font font); /** - * Create a TextActor object with LeftToRight text + * @brief Create a TextActor object with LeftToRight text. + * * @param [in] text The text which will be displayed * @param [in] font The font which will be used for the text * @param [in] fontDetection Try to detect font in case text is not supported with current one. @@ -166,7 +174,8 @@ public: static TextActor New(const Text& text, Font font, bool fontDetection); /** - * Create a TextActor object + * @brief Create a TextActor object. + * * @param [in] text The text which will be displayed * @param [in] font The font which will be used for the text * @param [in] fontDetection Try to detect font in case text is not supported with current one. @@ -181,7 +190,8 @@ public: static TextActor New(const Text& text, Font font, bool fontDetection, bool isLeftToRight); /** - * Create a TextActor object + * @brief Create a TextActor object. + * * @param [in] text The text which will be displayed * @param [in] style The style which will be used for the text * @param [in] fontDetection Try to detect font in case text is not supported with current one. @@ -191,15 +201,18 @@ public: static TextActor New(const Text& text, const TextStyle& style, bool fontDetection, bool isLeftToRight); /** - * Downcast an Object handle to TextActor. If handle points to a TextActor the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to TextActor. + * + * If handle points to a TextActor the downcast produces valid + * handle. If not the returned handle is left uninitialized. * @param[in] handle to An object * @return handle to a TextActor or an uninitialized handle */ static TextActor DownCast( BaseHandle handle ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~TextActor(); @@ -210,14 +223,16 @@ public: using BaseHandle::operator=; /** - * Get the text label displayed by the actor + * @brief Get the text label displayed by the actor. + * * @pre The text actor has been initialized. * @return The text label */ std::string GetText() const; /** - * Set the text label displayed by the actor + * @brief Set the text label displayed by the actor. + * * @pre The text actor has been initialized. * @param [in] text The new text label */ @@ -229,21 +244,24 @@ public: void SetText(const Text& text); /** - * Set text to the natural size of the text string + * @brief Set text to the natural size of the text string. + * * After this method the text actor always uses the natural size of the text * when SetText is called unless SetSize is called to override the size. */ void SetToNaturalSize(); /** - * Get the font used to display the text label displayed by the actor + * @brief Get the font used to display the text label displayed by the actor. + * * @pre The text actor has been initialized. * @return The font currently in use */ Font GetFont() const; /** - * Set the font used to display the text label displayed by the actor + * @brief Set the font used to display the text label displayed by the actor. + * * @pre The text actor has been initialized. * @param [in] font The new font */ @@ -252,21 +270,24 @@ public: // styling and effects /** - * Set the gradient color + * @brief Set the gradient color. + * * This is the color associated with the gradient end point. * @param[in] color The gradient color (end-point color) */ void SetGradientColor( const Vector4& color ); /** - * Get the gradient color + * @brief Get the gradient color. + * * This is the color associated with the gradient end point. * @return The gradient color (end-point color) */ Vector4 GetGradientColor() const; /** - * Set the gradient start point. + * @brief Set the gradient start point. + * * This is a 2D position between the coordinate range: * 0.0,0.0 (Left,Top) to 1.0,1.0 (Right,Bottom) within * the outputted Text. Actor::COLOR will represent this point @@ -276,13 +297,15 @@ public: void SetGradientStartPoint( const Vector2& position ); /** - * Get the gradient start point. + * @brief Get the gradient start point. + * * @return The relative position of the gradient start point. */ Vector2 GetGradientStartPoint() const; /** - * Set the gradient end point. + * @brief Set the gradient end point. + * * This is a 2D position between the coordinate range: * 0.0,0.0 (Left,Top) to 1.0,1.0 (Right,Bottom) within * the outputted Text. TextActor::GRADIENT_COLOR will represent @@ -292,44 +315,52 @@ public: void SetGradientEndPoint( const Vector2& position ); /** - * Get the gradient end point. + * @brief Get the gradient end point. + * * @return The relative position of the gradient end point. */ Vector2 GetGradientEndPoint() const; /** - * Sets text style. + * @brief Sets text style. + * * @param[in] style The text style. */ void SetTextStyle( const TextStyle& style ); /** - * Retrieves a copy of the text style. + * @brief Retrieves a copy of the text style. + * * @return The text style. */ TextStyle GetTextStyle() const; /** - * Set the text color. This is blended with the Actor color + * @brief Set the text color. + * + * This is blended with the Actor color * @param[in] color The text color (Default: WHITE) */ void SetTextColor( const Vector4& color ); /** - * Get the text color. + * @brief Get the text color. + * * @return The text color. */ Vector4 GetTextColor() const; /** - * Set soft edge smoothing + * @brief Set soft edge smoothing. + * * @param[in] smoothEdge Specify the distance field value for the center of the text edge. * 0 <= smoothEdge <= 1 */ void SetSmoothEdge(const float smoothEdge = TextStyle::DEFAULT_SMOOTH_EDGE_DISTANCE_FIELD); /** - * Set text outlining + * @brief Set text outlining. + * * @param[in] enable Set to true to enable text outlining. * @param[in] color Outline color. * @param[in] thickness Thickness of outline. The outline thickness is determined by two parameters. @@ -342,7 +373,8 @@ public: void SetOutline(const bool enable, const Vector4& color, const Vector2& thickness = TextStyle::DEFAULT_OUTLINE_THICKNESS); /** - * Set text glow + * @brief Set text glow. + * * @param[in] enable Set to true to enable text outer glow. * @param[in] color Glow color. * @param[in] intensity Determines the amount of glow around text. @@ -352,7 +384,8 @@ public: void SetGlow(const bool enable, const Vector4& color, const float intensity = TextStyle::DEFAULT_GLOW_INTENSITY); /** - * Set text shadow + * @brief Set text shadow. + * * @param[in] enable Set to true to enable text drop shadow. * @param[in] color Shadow color * @param[in] offset Offset in pixels. To avoid cropping of the drop shadow limit the offset to PointSize / 3.5 @@ -362,76 +395,89 @@ public: const float size = TextStyle::DEFAULT_SHADOW_SIZE ); /** - * Enable italics on the text actor, the text will be sheared by the given angle. + * @brief Enable italics on the text actor, the text will be sheared by the given angle. + * * @param[in] enabled True will enable italics, false disable it. * @param[in] angle Italics angle in degrees. */ void SetItalics( const bool enabled, const Degree& angle = TextStyle::DEFAULT_ITALICS_ANGLE ); /** - * Enable italics on the text actor, the text will be sheared by the given angle. + * @brief Enable italics on the text actor, the text will be sheared by the given angle. + * * @param[in] enabled True will enable italics, false disable it. * @param[in] angle Italics angle in radians. */ void SetItalics( const bool enabled, const Radian& angle ); /** - * Get text italics for the actor. + * @brief Get text italics for the actor. + * * @returns True if italics is enabled. */ bool GetItalics() const; /** - * Get text italics angle. + * @brief Get text italics angle. + * * @returns Angle as a Radian. */ const Radian& GetItalicsAngle() const; /** - * Set text underline. + * @brief Set text underline. + * * @param[in] enable Boolean indicating if the text should be underlined or not. */ void SetUnderline( bool enable ); /** - * Get text underline. + * @brief Get text underline. + * * @return Boolean indicating if the text should be underlined or not. */ bool GetUnderline() const; /** - * Set text weight. + * @brief Set text weight. + * * @param weight Text weight. */ void SetWeight( TextStyle::Weight weight ); /** - * Get text weight. + * @brief Get text weight. + * * @return Text weight. */ TextStyle::Weight GetWeight() const; /** - * Try to detect font in case text is not supported with current one. + * @brief Try to detect font in case text is not supported with current one. + * * @param [in] value true or false */ void SetFontDetectionAutomatic(bool value); /** - * Query whether TextActor is using automatic font detection. + * @brief Query whether TextActor is using automatic font detection. + * * @return true or false */ bool IsFontDetectionAutomatic() const; /** - * Query whether the font has been loaded and built. Should be used by the application to determine whether the - * font is ready to be queried for metrics + * @brief Query whether the font has been loaded and built. + * + * Should be used by the application to determine whether the font + * is ready to be queried for metrics * @return The loading state, either Loading, Success or Failed. */ LoadingState GetLoadingState() const; /** - * Emitted when text loads successfully and is available for displaying, or when the loading fails. + * @brief Emitted when text loads successfully and is available for displaying, or when the loading fails. + * * @return A signal object to Connect() with. */ TextSignalV2& TextAvailableSignal(); @@ -439,7 +485,8 @@ public: public: // Not intended for use by Application developers /** - * This constructor is used by Dali New() methods + * @brief This constructor is used by Dali New() methods + * e * @param [in] actor A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL TextActor(Internal::TextActor* actor); diff --git a/capi/dali/public-api/animation/active-constraint-declarations.h b/capi/dali/public-api/animation/active-constraint-declarations.h index 35ce0eb..96c47ae 100644 --- a/capi/dali/public-api/animation/active-constraint-declarations.h +++ b/capi/dali/public-api/animation/active-constraint-declarations.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_ANIMATION_MODULE * @{ */ diff --git a/capi/dali/public-api/animation/active-constraint.h b/capi/dali/public-api/animation/active-constraint.h index 7a25f82..84f3902 100644 --- a/capi/dali/public-api/animation/active-constraint.h +++ b/capi/dali/public-api/animation/active-constraint.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_ANIMATION_MODULE * @{ */ @@ -36,7 +36,7 @@ class ActiveConstraintBase; } /** - * A constraint which is being applied to an object. + * @brief A constraint which is being applied to an object. */ class DALI_IMPORT_API ActiveConstraint : public Handle { @@ -45,20 +45,21 @@ public: // Default Properties static const Property::Index WEIGHT; ///< Property 0, name "weight", type FLOAT - static const float FINAL_WEIGHT; // 1.0f means the constraint is fully-applied, unless weight is still being animated - static const float DEFAULT_WEIGHT; // 1.0f + static const float FINAL_WEIGHT; ///< 1.0f means the constraint is fully-applied, unless weight is still being animated + static const float DEFAULT_WEIGHT; ///< 1.0f //Signal Names - static const char* const SIGNAL_APPLIED; + static const char* const SIGNAL_APPLIED; ///< name "applied" /** - * Create an uninitialized Constraint; this can be initialized with Constraint::New() + * @brief Create an uninitialized Constraint; this can be initialized with Constraint::New(). + * * Calling member functions with an uninitialized Dali::Object is not allowed. */ ActiveConstraint(); /** - * Destructor + * @brief Destructor. */ virtual ~ActiveConstraint(); @@ -68,19 +69,23 @@ public: using BaseHandle::operator=; /** - * Retrieve the object which this constraint is targeting. + * @brief Retrieve the object which this constraint is targeting. + * * @return The target object. */ Handle GetTargetObject(); /** - * Retrieve the property which this constraint is targeting. + * @brief Retrieve the property which this constraint is targeting. + * * @return The target property. */ Property::Index GetTargetProperty(); /** - * Set the weight of the constraint; this is a value clamped between 0.0f and 1.0f. The default is 1.0f. + * @brief Set the weight of the constraint; this is a value clamped between 0. + * 0f and 1.0f. + * The default is 1.0f. * 0.0f means the constraint has no effect, and 1.0f means the constraint is fully-applied. * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentWeight(). * @param [in] weight The weight. @@ -88,13 +93,15 @@ public: void SetWeight( float weight ); /** - * Retrieve the current weight of the constraint. + * @brief Retrieve the current weight of the constraint. + * * @return The current weight. */ float GetCurrentWeight() const; /** - * This signal is emitted after the apply-time of the constraint has expired. + * @brief This signal is emitted after the apply-time of the constraint has expired. + * * @note A non-zero apply-time must have been set using Constraint::SetApplyTime(). * @return A signal object to Connect() with. */ @@ -103,7 +110,8 @@ public: public: // Not intended for use by Application developers /** - * This constructor is used by Dali New() methods + * @brief This constructor is used by Dali New() methods. + * * @param [in] constraint A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL ActiveConstraint( Internal::ActiveConstraintBase* constraint ); diff --git a/capi/dali/public-api/animation/alpha-functions.h b/capi/dali/public-api/animation/alpha-functions.h index 236a97a..18489ee 100644 --- a/capi/dali/public-api/animation/alpha-functions.h +++ b/capi/dali/public-api/animation/alpha-functions.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_ANIMATION_MODULE * @{ */ @@ -30,6 +30,9 @@ namespace Dali DALI_IMPORT_API typedef float (*AlphaFunction)(float progress); ///< Definition of an alpha function +/** + * @brief Namespace containing a set of alpha functions. + */ namespace AlphaFunctions { diff --git a/capi/dali/public-api/animation/animation.h b/capi/dali/public-api/animation/animation.h index 8d8fb84..622b737 100644 --- a/capi/dali/public-api/animation/animation.h +++ b/capi/dali/public-api/animation/animation.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_ANIMATION_MODULE * @{ */ @@ -47,12 +47,12 @@ struct Vector2; struct Vector3; struct Vector4; -typedef boost::function AnimatorFunctionBool; -typedef boost::function AnimatorFunctionFloat; -typedef boost::function AnimatorFunctionVector2; -typedef boost::function AnimatorFunctionVector3; -typedef boost::function AnimatorFunctionVector4; -typedef boost::function AnimatorFunctionQuaternion; +typedef boost::function AnimatorFunctionBool; ///< Animator function signature for boolean properties. +typedef boost::function AnimatorFunctionFloat; ///< Animator function signature for float properties. +typedef boost::function AnimatorFunctionVector2; ///< Animator function signature for Vector2 properties. +typedef boost::function AnimatorFunctionVector3; ///< Animator function signature for Vector3 properties. +typedef boost::function AnimatorFunctionVector4; ///< Animator function signature for Vector4 properties. +typedef boost::function AnimatorFunctionQuaternion;///< Animator function signature for Quaternion properties. namespace Internal DALI_INTERNAL { @@ -60,7 +60,8 @@ class Animation; } /** - * Dali::Animation can be used to animate the properties of any number of objects, typically Actors. + * @brief Dali::Animation can be used to animate the properties of any number of objects, typically Actors. + * * An example animation setup is shown below: * * @code @@ -114,12 +115,15 @@ class DALI_IMPORT_API Animation : public BaseHandle { public: - typedef SignalV2< void (Animation&) > AnimationSignalV2; + typedef SignalV2< void (Animation&) > AnimationSignalV2; ///< Animation finished signal type - typedef boost::any AnyFunction; - typedef boost::function Vector3AnimatorFunc; - typedef boost::function QuaternionAnimatorFunc; + typedef boost::any AnyFunction; ///< Interpolation function + typedef boost::function Vector3AnimatorFunc; ///< Interpolation function + typedef boost::function QuaternionAnimatorFunc; ///< Interpolation function + /** + * @brief What to do when the animation ends. + */ enum EndAction { Bake, ///< When the animation ends, the animated property values are saved. @@ -127,21 +131,23 @@ public: }; //Signal Names - static const char* const SIGNAL_FINISHED; + static const char* const SIGNAL_FINISHED; ///< name "finished" //Action Names - static const char* const ACTION_PLAY; - static const char* const ACTION_STOP; - static const char* const ACTION_PAUSE; + static const char* const ACTION_PLAY; ///< name "play" + static const char* const ACTION_STOP; ///< name "stop" + static const char* const ACTION_PAUSE; ///< name "pause" /** - * Create an uninitialized Animation; this can be initialized with Animation::New() + * @brief Create an uninitialized Animation; this can be initialized with Animation::New(). + * * Calling member functions with an uninitialized Dali::Object is not allowed. */ Animation(); /** - * Create an initialized Animation. + * @brief Create an initialized Animation. + * * The animation will not loop. * The default end action is "Bake". * The default alpha function is linear. @@ -152,15 +158,18 @@ public: static Animation New(float durationSeconds); /** - * Downcast an Object handle to Animation. If handle points to an Animation object the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to Animation. + * + * If handle points to an Animation object the downcast produces + * valid handle. If not the returned handle is left uninitialized. + * * @param[in] handle to An object * @return handle to a Animation object or an uninitialized handle */ static Animation DownCast( BaseHandle handle ); /** - * Destructor + * @brief Destructor. */ virtual ~Animation(); @@ -170,32 +179,37 @@ public: using BaseHandle::operator=; /** - * Set the duration of an animation. + * @brief Set the duration of an animation. + * * @pre durationSeconds must be greater than zero. * @param[in] seconds The duration in seconds. */ void SetDuration(float seconds); /** - * Retrieve the duration of an animation. + * @brief Retrieve the duration of an animation. + * * @return The duration in seconds. */ float GetDuration() const; /** - * Set whether the animation will loop. + * @brief Set whether the animation will loop. + * * @param[in] looping True if the animation will loop. */ void SetLooping(bool looping); /** - * Query whether the animation will loop. + * @brief Query whether the animation will loop. + * * @return True if the animation will loop. */ bool IsLooping() const; /** - * Set the end action of the animation. + * @brief Set the end action of the animation. + * * This action is performed when the animation ends. * Default end action is bake * @param[in] action The end action. @@ -203,13 +217,15 @@ public: void SetEndAction(EndAction action); /** - * Returns the end action of the animation. + * @brief Returns the end action of the animation. + * * @return The end action. */ EndAction GetEndAction() const; /** - * Set the destroy action of the animation. + * @brief Set the destroy action of the animation. + * * If the animation is destroyed this action is performed on the following update. * Default destroy action is bake * @param[in] action The destroy action. @@ -217,53 +233,59 @@ public: void SetDestroyAction(EndAction action); /** - * Returns the destroy action of the animation. + * @brief Returns the destroy action of the animation. + * * @return The destroy action. */ EndAction GetDestroyAction() const; /** - * Set the default alpha function for an animation. + * @brief Set the default alpha function for an animation. + * * This is applied to individual property animations, if no further alpha functions are supplied. * @param[in] alpha The default alpha function. */ void SetDefaultAlphaFunction(AlphaFunction alpha); /** - * Retrieve the default alpha function for an animation. + * @brief Retrieve the default alpha function for an animation. + * * @return The default alpha function. */ AlphaFunction GetDefaultAlphaFunction() const; /** - * Play the animation. + * @brief Play the animation. */ void Play(); /** - * Pause the animation. + * @brief Pause the animation. */ void Pause(); /** - * Stop the animation. + * @brief Stop the animation. */ void Stop(); /** - * Clear the animation. + * @brief Clear the animation. + * * This disconnects any objects that were being animated, effectively stopping the animation. */ void Clear(); /** - * Connect to this signal to be notified when an Animation's animations have finished. + * @brief Connect to this signal to be notified when an Animation's animations have finished. + * * @return A signal object to Connect() with. */ AnimationSignalV2& FinishedSignal(); /** - * Animate a property value by a relative amount. + * @brief Animate a property value by a relative amount. + * * The default alpha function will be used. * The effect will start & end when the animation begins & ends. * @param [in] target The target object/property to animate. @@ -272,7 +294,8 @@ public: void AnimateBy(Property target, Property::Value relativeValue); /** - * Animate a property value by a relative amount. + * @brief Animate a property value by a relative amount. + * * The effect will start & end when the animation begins & ends. * @param [in] target The target object/property to animate. * @param [in] relativeValue The property value will change by this amount. @@ -281,7 +304,8 @@ public: void AnimateBy(Property target, Property::Value relativeValue, AlphaFunction alpha); /** - * Animate a property value by a relative amount. + * @brief Animate a property value by a relative amount. + * * The default alpha function will be used. * @param [in] target The target object/property to animate. * @param [in] relativeValue The property value will increase/decrease by this amount. @@ -290,7 +314,8 @@ public: void AnimateBy(Property target, Property::Value relativeValue, TimePeriod period); /** - * Animate a property value by a relative amount. + * @brief Animate a property value by a relative amount. + * * @param [in] target The target object/property to animate. * @param [in] relativeValue The property value will increase/decrease by this amount. * @param [in] alpha The alpha function to apply. @@ -299,7 +324,8 @@ public: void AnimateBy(Property target, Property::Value relativeValue, AlphaFunction alpha, TimePeriod period); /** - * Animate a property to a destination value. + * @brief Animate a property to a destination value. + * * The default alpha function will be used. * The effect will start & end when the animation begins & ends. * @param [in] target The target object/property to animate. @@ -308,7 +334,8 @@ public: void AnimateTo(Property target, Property::Value destinationValue); /** - * Animate a property to a destination value. + * @brief Animate a property to a destination value. + * * The effect will start & end when the animation begins & ends. * @param [in] target The target object/property to animate. * @param [in] destinationValue The destination value. @@ -317,7 +344,8 @@ public: void AnimateTo(Property target, Property::Value destinationValue, AlphaFunction alpha); /** - * Animate a property to a destination value. + * @brief Animate a property to a destination value. + * * The default alpha function will be used. * @param [in] target The target object/property to animate. * @param [in] destinationValue The destination value. @@ -326,7 +354,8 @@ public: void AnimateTo(Property target, Property::Value destinationValue, TimePeriod period); /** - * Animate a property to a destination value. + * @brief Animate a property to a destination value. + * * @param [in] target The target object/property to animate. * @param [in] destinationValue The destination value. * @param [in] alpha The alpha function to apply. @@ -335,14 +364,16 @@ public: void AnimateTo(Property target, Property::Value destinationValue, AlphaFunction alpha, TimePeriod period); /** - * Animate a property between keyframes + * @brief Animate a property between keyframes. + * * @param [in] target The target object/property to animate. * @param [in] keyFrames The key frames */ void AnimateBetween(Property target, KeyFrames& keyFrames); /** - * Animate a property between keyframes + * @brief Animate a property between keyframes. + * * @param [in] target The target object/property to animate. * @param [in] keyFrames The key frames * @param [in] alpha The alpha function to apply. @@ -350,7 +381,8 @@ public: void AnimateBetween(Property target, KeyFrames& keyFrames, AlphaFunction alpha); /** - * Animate a property between keyframes + * @brief Animate a property between keyframes. + * * @param [in] target The target object/property to animate. * @param [in] keyFrames The key frames * @param [in] period The effect will occur during this time period. @@ -358,7 +390,8 @@ public: void AnimateBetween(Property target, KeyFrames& keyFrames, TimePeriod period); /** - * Animate a property between keyframes + * @brief Animate a property between keyframes. + * * @param [in] target The target object/property to animate. * @param [in] keyFrames The key frames * @param [in] alpha The alpha function to apply. @@ -367,7 +400,8 @@ public: void AnimateBetween(Property target, KeyFrames& keyFrames, AlphaFunction alpha, TimePeriod period); /** - * Animate a property using a custom function. + * @brief Animate a property using a custom function. + * * The function will be called from a separate animation-thread; it should return quickly, to avoid performance degredation. * @pre The property type is equal PropertyTypes::Get

(). * @param [in] target The target object/property to animate. @@ -380,7 +414,8 @@ public: } /** - * Animate a property using a custom function. + * @brief Animate a property using a custom function. + * * The function will be called from a separate animation-thread; it should return quickly, to avoid performance degredation. * @pre The property type is equal PropertyTypes::Get

(). * @param [in] target The target object/property to animate. @@ -394,7 +429,8 @@ public: } /** - * Animate a property using a custom function. + * @brief Animate a property using a custom function. + * * The function will be called from a separate animation-thread; it should return quickly, to avoid performance degredation. * @pre The property type is equal PropertyTypes::Get

(). * @param [in] target The target object/property to animate. @@ -408,7 +444,8 @@ public: } /** - * Animate a property using a custom function. + * @brief Animate a property using a custom function. + * * The function will be called from a separate animation-thread; it should return quickly, to avoid performance degredation. * @pre The property type is equal PropertyTypes::Get

(). * @param [in] target The target object/property to animate. @@ -425,7 +462,8 @@ public: // Actor-specific convenience methods /** - * Move an actor relative to its position + * @brief Move an actor relative to its position. + * * The default alpha function will be used. * The move will start & end when the animation begins & ends. * @param [in] actor The actor to animate. @@ -436,7 +474,8 @@ public: void MoveBy(Actor actor, float x, float y, float z); /** - * Move an actor relative to its position. + * @brief Move an actor relative to its position. + * * This overload allows the alpha function to be customized. * The move will start & end when the animation begins & ends. * @param [in] actor The actor to animate. @@ -446,7 +485,8 @@ public: void MoveBy(Actor actor, Vector3 displacement, AlphaFunction alpha); /** - * Move an actor relative to its position. + * @brief Move an actor relative to its position. + * * This overload allows the translation start & end time to be customized. * @pre delaySeconds must be zero or greater. * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. @@ -459,7 +499,8 @@ public: void MoveBy(Actor actor, Vector3 displacement, AlphaFunction alpha, float delaySeconds, float durationSeconds); /** - * Move an actor to a target position. + * @brief Move an actor to a target position. + * * The default alpha function will be used. * The move will start & end when the animation begins & ends. * @param [in] actor The actor to animate. @@ -470,7 +511,9 @@ public: void MoveTo(Actor actor, float x, float y, float z); /** - * Move an actor to a target position. This overload allows the alpha function to be customized. + * @brief Move an actor to a target position. + * + * This overload allows the alpha function to be customized. * The move will start & end when the animation begins & ends. * @param [in] actor The actor to animate. * @param [in] position to move to @@ -479,7 +522,9 @@ public: void MoveTo(Actor actor, Vector3 position, AlphaFunction alpha); /** - * Move an actor to a target position. This overload allows the translation start & end time to be customized. + * @brief Move an actor to a target position. + * + * This overload allows the translation start & end time to be customized. * @pre delaySeconds must be zero or greater. * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. * @param [in] actor The actor to animate. @@ -491,7 +536,8 @@ public: void MoveTo(Actor actor, Vector3 position, AlphaFunction alpha, float delaySeconds, float durationSeconds); /** - * Move an actor using a custom function. + * @brief Move an actor using a custom function. + * * The animatorFunc will be called from a separate animation-thread; it should return quickly, to avoid performance degredation. * @pre delaySeconds must be zero or greater. * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. @@ -504,7 +550,8 @@ public: void Move(Actor actor, AnimatorFunctionVector3 animatorFunc, AlphaFunction alpha, float delaySeconds, float durationSeconds); /** - * Rotate an actor around an arbitrary axis. + * @brief Rotate an actor around an arbitrary axis. + * * The default alpha function will be used. * The rotation will start & end when the animation begins & ends. * @param [in] actor The actor to animate. @@ -514,7 +561,8 @@ public: void RotateBy(Actor actor, Degree angle, Vector3 axis); /** - * Rotate an actor around an arbitrary axis. + * @brief Rotate an actor around an arbitrary axis. + * * The default alpha function will be used. * The rotation will start & end when the animation begins & ends. * @param [in] actor The actor to animate. @@ -524,7 +572,9 @@ public: void RotateBy(Actor actor, Radian angle, Vector3 axis); /** - * Rotate an actor around an arbitrary axis. This overload allows the alpha function to be customized. + * @brief Rotate an actor around an arbitrary axis. + * + * This overload allows the alpha function to be customized. * The rotation will start & end when the animation begins & ends. * @param [in] actor The actor to animate. * @param [in] angle The angle in radians. @@ -534,7 +584,9 @@ public: void RotateBy(Actor actor, Degree angle, Vector3 axis, AlphaFunction alpha); /** - * Rotate an actor around an arbitrary axis. This overload allows the alpha function to be customized. + * @brief Rotate an actor around an arbitrary axis. + * + * This overload allows the alpha function to be customized. * The rotation will start & end when the animation begins & ends. * @param [in] actor The actor to animate. * @param [in] angle The angle in radians. @@ -544,7 +596,9 @@ public: void RotateBy(Actor actor, Radian angle, Vector3 axis, AlphaFunction alpha); /** - * Rotate an actor around an arbitrary axis. This overload allows the rotation start & end time to be customized. + * @brief Rotate an actor around an arbitrary axis. + * + * This overload allows the rotation start & end time to be customized. * @pre delaySeconds must be zero or greater. * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. * @param [in] actor The actor to animate. @@ -557,7 +611,9 @@ public: void RotateBy(Actor actor, Degree angle, Vector3 axis, AlphaFunction alpha, float delaySeconds, float durationSeconds); /** - * Rotate an actor around an arbitrary axis. This overload allows the rotation start & end time to be customized. + * @brief Rotate an actor around an arbitrary axis. + * + * This overload allows the rotation start & end time to be customized. * @pre delaySeconds must be zero or greater. * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. * @param [in] actor The actor to animate. @@ -570,7 +626,8 @@ public: void RotateBy(Actor actor, Radian angle, Vector3 axis, AlphaFunction alpha, float delaySeconds, float durationSeconds); /** - * Rotate an actor to a target orientation. + * @brief Rotate an actor to a target orientation. + * * The default alpha function will be used. * The rotation will start & end when the animation begins & ends. * @param [in] actor The actor to animate. @@ -580,7 +637,8 @@ public: void RotateTo(Actor actor, Degree angle, Vector3 axis); /** - * Rotate an actor to a target orientation. + * @brief Rotate an actor to a target orientation. + * * The default alpha function will be used. * The rotation will start & end when the animation begins & ends. * @param [in] actor The actor to animate. @@ -590,7 +648,8 @@ public: void RotateTo(Actor actor, Radian angle, Vector3 axis); /** - * Rotate an actor to a target orientation. + * @brief Rotate an actor to a target orientation. + * * The default alpha function will be used. * The rotation will start & end when the animation begins & ends. * @param [in] actor The actor to animate. @@ -599,7 +658,9 @@ public: void RotateTo(Actor actor, Quaternion orientation); /** - * Rotate an actor to a target orientation. This overload allows the alpha function to be customized. + * @brief Rotate an actor to a target orientation. + * + * This overload allows the alpha function to be customized. * The rotation will start & end when the animation begins & ends. * @param [in] actor The actor to animate. * @param [in] angle The target rotation angle in degrees. @@ -609,7 +670,9 @@ public: void RotateTo(Actor actor, Degree angle, Vector3 axis, AlphaFunction alpha); /** - * Rotate an actor to a target orientation. This overload allows the alpha function to be customized. + * @brief Rotate an actor to a target orientation. + * + * This overload allows the alpha function to be customized. * The rotation will start & end when the animation begins & ends. * @param [in] actor The actor to animate. * @param [in] angle The target rotation angle in radians. @@ -619,7 +682,9 @@ public: void RotateTo(Actor actor, Radian angle, Vector3 axis, AlphaFunction alpha); /** - * Rotate an actor to a target orientation. This overload allows the alpha function to be customized. + * @brief Rotate an actor to a target orientation. + * + * This overload allows the alpha function to be customized. * The rotation will start & end when the animation begins & ends. * @param [in] actor The actor to animate. * @param [in] orientation The target orientation. @@ -628,7 +693,9 @@ public: void RotateTo(Actor actor, Quaternion orientation, AlphaFunction alpha); /** - * Rotate an actor to a target orientation. This overload allows the rotation start & end time to be customized. + * @brief Rotate an actor to a target orientation. + * + * This overload allows the rotation start & end time to be customized. * @pre delaySeconds must be zero or greater. * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. * @param [in] actor The actor to animate. @@ -641,7 +708,9 @@ public: void RotateTo(Actor actor, Degree angle, Vector3 axis, AlphaFunction alpha, float delaySeconds, float durationSeconds); /** - * Rotate an actor to a target orientation. This overload allows the rotation start & end time to be customized. + * @brief Rotate an actor to a target orientation. + * + * This overload allows the rotation start & end time to be customized. * @pre delaySeconds must be zero or greater. * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. * @param [in] actor The actor to animate. @@ -654,7 +723,9 @@ public: void RotateTo(Actor actor, Radian angle, Vector3 axis, AlphaFunction alpha, float delaySeconds, float durationSeconds); /** - * Rotate an actor to a target orientation. This overload allows the rotation start & end time to be customized. + * @brief Rotate an actor to a target orientation. + * + * This overload allows the rotation start & end time to be customized. * @pre delaySeconds must be zero or greater. * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. * @param [in] actor The actor to animate. @@ -666,7 +737,8 @@ public: void RotateTo(Actor actor, Quaternion orientation, AlphaFunction alpha, float delaySeconds, float durationSeconds); /** - * Rotate an actor using a custom function. + * @brief Rotate an actor using a custom function. + * * The animatorFunc will be called from a separate animation-thread; it should return quickly, to avoid performance degredation. * @pre delaySeconds must be zero or greater. * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. @@ -679,7 +751,8 @@ public: void Rotate(Actor actor, AnimatorFunctionQuaternion animatorFunc, AlphaFunction alpha, float delaySeconds, float durationSeconds); /** - * Scale an actor. + * @brief Scale an actor. + * * The default alpha function will be used. * The scaling will start & end when the animation begins & ends. * @param [in] actor The actor to animate. @@ -690,7 +763,9 @@ public: void ScaleBy(Actor actor, float x, float y, float z); /** - * Scale an actor. This overload allows the alpha function to be customized. + * @brief Scale an actor. + * + * This overload allows the alpha function to be customized. * The scaling will start & end when the animation begins & ends. * @param [in] actor The actor to animate. * @param [in] scale The scale factor. @@ -699,7 +774,9 @@ public: void ScaleBy(Actor actor, Vector3 scale, AlphaFunction alpha); /** - * Scale an actor. This overload allows the scaling start & end time to be customized. + * @brief Scale an actor. + * + * This overload allows the scaling start & end time to be customized. * @pre delaySeconds must be zero or greater. * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. * @param [in] actor The actor to animate. @@ -711,7 +788,8 @@ public: void ScaleBy(Actor actor, Vector3 scale, AlphaFunction alpha, float delaySeconds, float durationSeconds); /** - * Scale an actor to a target scale factor. + * @brief Scale an actor to a target scale factor. + * * The default alpha function will be used. * The scaling will start & end when the animation begins & ends. * @param [in] actor The actor to animate. @@ -722,7 +800,9 @@ public: void ScaleTo(Actor actor, float x, float y, float z); /** - * Scale an actor to a target scale factor. This overload allows the alpha function to be customized. + * @brief Scale an actor to a target scale factor. + * + * This overload allows the alpha function to be customized. * The scaling will start & end when the animation begins & ends. * @param [in] actor The actor to animate. * @param [in] scale The target scale factor. @@ -731,7 +811,9 @@ public: void ScaleTo(Actor actor, Vector3 scale, AlphaFunction alpha); /** - * Scale an actor to a target scale factor. This overload allows the scaling start & end time to be customized. + * @brief Scale an actor to a target scale factor. + * + * This overload allows the scaling start & end time to be customized. * @pre delaySeconds must be zero or greater. * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. * @param [in] actor The actor to animate. @@ -743,21 +825,24 @@ public: void ScaleTo(Actor actor, Vector3 scale, AlphaFunction alpha, float delaySeconds, float durationSeconds); /** - * Show an actor during the animation. + * @brief Show an actor during the animation. + * * @param [in] actor The actor to animate. * @param [in] delaySeconds The initial delay from the start of the animation. */ void Show(Actor actor, float delaySeconds); /** - * Hide an actor during the animation. + * @brief Hide an actor during the animation. + * * @param [in] actor The actor to animate. * @param [in] delaySeconds The initial delay from the start of the animation. */ void Hide(Actor actor, float delaySeconds); /** - * Animate the opacity of an actor. + * @brief Animate the opacity of an actor. + * * The default alpha function will be used. * The effect will start & end when the animation begins & ends. * @param [in] actor The actor to animate. @@ -766,7 +851,9 @@ public: void OpacityBy(Actor actor, float opacity); /** - * Animate the opacity of an actor. This overload allows the alpha function to be customized. + * @brief Animate the opacity of an actor. + * + * This overload allows the alpha function to be customized. * The effect will start & end when the animation begins & ends. * @param [in] actor The actor to animate. * @param [in] opacity The relative change in opacity. @@ -775,7 +862,9 @@ public: void OpacityBy(Actor actor, float opacity, AlphaFunction alpha); /** - * Animate the opacity of an actor. This overload allows the animation start & end time to be customized. + * @brief Animate the opacity of an actor. + * + * This overload allows the animation start & end time to be customized. * @pre delaySeconds must be zero or greater. * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. * @param [in] actor The actor to animate. @@ -787,7 +876,8 @@ public: void OpacityBy(Actor actor, float opacity, AlphaFunction alpha, float delaySeconds, float durationSeconds); /** - * Animate an actor to a target opacity. + * @brief Animate an actor to a target opacity. + * * The default alpha function will be used. * The effect will start & end when the animation begins & ends. * @param [in] actor The actor to animate. @@ -796,7 +886,9 @@ public: void OpacityTo(Actor actor, float opacity); /** - * Animate an actor to a target opacity. This overload allows the alpha function to be customized. + * @brief Animate an actor to a target opacity. + * + * This overload allows the alpha function to be customized. * The effect will start & end when the animation begins & ends. * @param [in] actor The actor to animate. * @param [in] opacity The target opacity. @@ -805,7 +897,9 @@ public: void OpacityTo(Actor actor, float opacity, AlphaFunction alpha); /** - * Animate an actor to a target opacity. This overload allows the animation start & end time to be customized. + * @brief Animate an actor to a target opacity. + * + * This overload allows the animation start & end time to be customized. * @pre delaySeconds must be zero or greater. * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. * @param [in] actor The actor to animate. @@ -817,7 +911,8 @@ public: void OpacityTo(Actor actor, float opacity, AlphaFunction alpha, float delaySeconds, float durationSeconds); /** - * Animate the color of an actor. + * @brief Animate the color of an actor. + * * The default alpha function will be used. * The effect will start & end when the animation begins & ends. * @param [in] actor The actor to animate. @@ -826,7 +921,9 @@ public: void ColorBy(Actor actor, Vector4 color); /** - * Animate the color of an actor. This overload allows the alpha function to be customized. + * @brief Animate the color of an actor. + * + * This overload allows the alpha function to be customized. * The effect will start & end when the animation begins & ends. * @param [in] actor The actor to animate. * @param [in] color The relative change in color. @@ -835,7 +932,9 @@ public: void ColorBy(Actor actor, Vector4 color, AlphaFunction alpha); /** - * Animate the color of an actor. This overload allows the animation start & end time to be customized. + * @brief Animate the color of an actor. + * + * This overload allows the animation start & end time to be customized. * @pre delaySeconds must be zero or greater. * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. * @param [in] actor The actor to animate. @@ -847,7 +946,8 @@ public: void ColorBy(Actor actor, Vector4 color, AlphaFunction alpha, float delaySeconds, float durationSeconds); /** - * Animate an actor to a target color. + * @brief Animate an actor to a target color. + * * The default alpha function will be used. * The effect will start & end when the animation begins & ends. * @param [in] actor The actor to animate. @@ -856,7 +956,9 @@ public: void ColorTo(Actor actor, Vector4 color); /** - * Animate an actor to a target color. This overload allows the alpha function to be customized. + * @brief Animate an actor to a target color. + * + * This overload allows the alpha function to be customized. * The effect will start & end when the animation begins & ends. * @param [in] actor The actor to animate. * @param [in] color The target color. @@ -865,7 +967,9 @@ public: void ColorTo(Actor actor, Vector4 color, AlphaFunction alpha); /** - * Animate an actor to a target color. This overload allows the animation start & end time to be customized. + * @brief Animate an actor to a target color. + * + * This overload allows the animation start & end time to be customized. * @pre delaySeconds must be zero or greater. * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. * @param [in] actor The actor to animate. @@ -877,7 +981,8 @@ public: void ColorTo(Actor actor, Vector4 color, AlphaFunction alpha, float delaySeconds, float durationSeconds); /** - * Resize an actor. + * @brief Resize an actor. + * * The default alpha function will be used. * The resizing will start & end when the animation begins & ends. * The depth defaults to the minimum of width & height. @@ -888,7 +993,9 @@ public: void Resize(Actor actor, float width, float height); /** - * Resize an actor. This overload allows the alpha function to be customized. + * @brief Resize an actor. + * + * This overload allows the alpha function to be customized. * The resizing will start & end when the animation begins & ends. * The depth defaults to the minimum of width & height. * @param [in] actor The actor to animate. @@ -899,7 +1006,9 @@ public: void Resize(Actor actor, float width, float height, AlphaFunction alpha); /** - * Resize an actor. This overload allows the resizing start & end time to be customized. + * @brief Resize an actor. + * + * This overload allows the resizing start & end time to be customized. * The depth defaults to the minimum of width & height. * @pre delaySeconds must be zero or greater. * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. @@ -913,7 +1022,8 @@ public: void Resize(Actor actor, float width, float height, AlphaFunction alpha, float delaySeconds, float durationSeconds); /** - * Resize an actor. + * @brief Resize an actor. + * * The default alpha function will be used. * The resizing will start & end when the animation begins & ends. * @param [in] actor The actor to animate. @@ -922,7 +1032,9 @@ public: void Resize(Actor actor, Vector3 size); /** - * Resize an actor. This overload allows the alpha function to be customized. + * @brief Resize an actor. + * + * This overload allows the alpha function to be customized. * The resizing will start & end when the animation begins & ends. * @param [in] actor The actor to animate. * @param [in] size The target size. @@ -931,7 +1043,9 @@ public: void Resize(Actor actor, Vector3 size, AlphaFunction alpha); /** - * Resize an actor. This overload allows the resizing start & end time to be customized. + * @brief Resize an actor. + * + * This overload allows the resizing start & end time to be customized. * @pre delaySeconds must be zero or greater. * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. * @param [in] actor The actor to animate. @@ -945,7 +1059,7 @@ public: public: // Not intended for use by Application developers /** - * This constructor is used by Dali New() methods + * @brief This constructor is used by Dali New() methods * @param [in] animation A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL Animation(Internal::Animation* animation); @@ -953,7 +1067,8 @@ public: // Not intended for use by Application developers private: /** - * Animate a property using a custom function. + * @brief Animate a property using a custom function. + * * @pre The property type is equal expectedType. * @param [in] target The target object/property to animate. * @param [in] targetType The expected type of the property. @@ -964,7 +1079,8 @@ private: AnyFunction func ); /** - * Animate a property using a custom function. + * @brief Animate a property using a custom function. + * * @pre The property type is equal expectedType. * @param [in] target The target object/property to animate. * @param [in] targetType The expected type of the property. @@ -977,7 +1093,8 @@ private: AlphaFunction alpha ); /** - * Animate a property using a custom function. + * @brief Animate a property using a custom function. + * * @pre The property type is equal expectedType. * @param [in] target The target object/property to animate. * @param [in] targetType The expected type of the property. @@ -990,7 +1107,8 @@ private: TimePeriod period ); /** - * Animate a property using a custom function. + * @brief Animate a property using a custom function. + * * @pre The property type is equal expectedType. * @param [in] target The target object/property to animate. * @param [in] targetType The expected type of the property. diff --git a/capi/dali/public-api/animation/constraint-functions.h b/capi/dali/public-api/animation/constraint-functions.h index d59cc54..d878e4e 100644 --- a/capi/dali/public-api/animation/constraint-functions.h +++ b/capi/dali/public-api/animation/constraint-functions.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_ANIMATION_MODULE * @{ */ @@ -33,14 +33,16 @@ struct Vector4; class Quaternion; /** - * Constraints can be used to adjust an Actor property, after animations have been applied. + * @brief Constraints can be used to adjust an Actor property, after animations have been applied. + * * A local-constraint function is based on local properties of the Actor. */ namespace LocalConstraint DALI_IMPORT_API { /** - * A function which constrains a Vector3 property, based on the local properties of an Actor. + * @brief A function which constrains a Vector3 property, based on the local properties of an Actor. + * * @param[in] size The actor's current size. * @param[in] position The actor's current position. * @param[in] scale The actor's current rotation. @@ -55,7 +57,8 @@ typedef boost::function Vector3Function; /** - * A function which constrains a Vector4 property, based on the local properties of an Actor. + * @brief A function which constrains a Vector4 property, based on the local properties of an Actor. + * * @param[in] size The actor's current size. * @param[in] position The actor's current position. * @param[in] scale The actor's current rotation. @@ -70,7 +73,8 @@ typedef boost::function Vector4Function; /** - * A function which constrains a Quaternion property, based on the local properties of an Actor. + * @brief A function which constrains a Quaternion property, based on the local properties of an Actor. + * * @param[in] size The actor's current size. * @param[in] position The actor's current position. * @param[in] scale The actor's current rotation. @@ -85,7 +89,8 @@ typedef boost::function QuaternionFunction; /** - * A function which constrains a boolean property, based on the local properties of an Actor. + * @brief A function which constrains a boolean property, based on the local properties of an Actor. + * * @param[in] size The actor's current size. * @param[in] position The actor's current position. * @param[in] scale The actor's current rotation. @@ -102,13 +107,14 @@ typedef boost::function Vector3Function; /** - * A function which constrains a Vector4 property, based on properties related to the Actor's parent. + * @brief A function which constrains a Vector4 property, based on properties related to the Actor's parent. + * * @param[in] current The current value of the property to be constrained. * @param[in] parentOrigin The actor's current parent-origin. * @param[in] anchorPoint The actor's current anchor-point. @@ -146,7 +153,8 @@ typedef boost::function Vector4Function; /** - * A function which constrains a Quaternion property, based on properties related to the Actor's parent. + * @brief A function which constrains a Quaternion property, based on properties related to the Actor's parent. + * * @param[in] parentOrigin The actor's current parent-origin. * @param[in] anchorPoint The actor's current anchor-point. * @param[in] parentSize The parent's current size. @@ -164,7 +172,8 @@ typedef boost::function QuaternionFunction; /** - * A function which constrains a boolean property, based on properties related to the Actor's parent. + * @brief A function which constrains a boolean property, based on properties related to the Actor's parent. + * * @param[in] progress A progress value in the range 0->1, where 1 means that the constraint is fully applied. * @param[in] parentOrigin The actor's current parent-origin. * @param[in] anchorPoint The actor's current anchor-point. diff --git a/capi/dali/public-api/animation/constraint-source.h b/capi/dali/public-api/animation/constraint-source.h index b0a2d8b..8e4f717 100644 --- a/capi/dali/public-api/animation/constraint-source.h +++ b/capi/dali/public-api/animation/constraint-source.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_ANIMATION_MODULE * @{ */ @@ -30,7 +30,8 @@ namespace Dali DALI_IMPORT_API { /** - * Constraint source types. + * @brief Constraint source types. + * * This specifies the location of a property, which is used as an input for a constraint function. */ enum SourceType @@ -42,12 +43,13 @@ enum SourceType /** - * Identifies a property from an object. + * @brief Identifies a property from an object. */ struct DALI_IMPORT_API LocalSource { /** - * Create a local constraint source. + * @brief Create a local constraint source. + * * @param [in] index The index of a property provided by the constrained object. */ LocalSource( Property::Index index ); @@ -56,12 +58,13 @@ struct DALI_IMPORT_API LocalSource }; /** - * Identifies a property from the parent of an object. + * @brief Identifies a property from the parent of an object. */ struct DALI_IMPORT_API ParentSource { /** - * Create a local constraint source. + * @brief Create a local constraint source. + * * @param [in] index The index of a property, provided by the parent of the constrained object. */ ParentSource( Property::Index index ); @@ -70,12 +73,13 @@ struct DALI_IMPORT_API ParentSource }; /** - * Identifies a property from any object. + * @brief Identifies a property from any object. */ struct DALI_IMPORT_API Source { /** - * Create a constraint source. + * @brief Create a constraint source. + * * @param [in] object The object providing the property. * @param [in] index The index of a property provided by object. */ @@ -87,24 +91,27 @@ struct DALI_IMPORT_API Source }; /** - * The source of an input property for a constraint. + * @brief The source of an input property for a constraint. */ struct DALI_IMPORT_API ConstraintSource { /** - * Create a constraint source. + * @brief Create a constraint source. + * * @param [in] source A constraint source from an arbitrary object. */ ConstraintSource( Source source ); /** - * Create a constraint source. + * @brief Create a constraint source. + * * @param [in] local A local constraint source. */ ConstraintSource( LocalSource local ); /** - * Create a constraint source. + * @brief Create a constraint source. + * * @param [in] parent A parent constraint source. */ ConstraintSource( ParentSource parent ); diff --git a/capi/dali/public-api/animation/constraint.h b/capi/dali/public-api/animation/constraint.h index 9d2db39..5d12aed 100644 --- a/capi/dali/public-api/animation/constraint.h +++ b/capi/dali/public-api/animation/constraint.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_ANIMATION_MODULE * @{ */ @@ -44,7 +44,7 @@ class Constraint; } /** - * An abstract base class for Constraints. + * @brief An abstract base class for Constraints. * This can be used to constrain a property of an actor, after animations have been applied. * Constraints are applied in the following order: * - Constraints are applied to on-stage actors in a depth-first traversal. @@ -55,9 +55,11 @@ class DALI_IMPORT_API Constraint : public BaseHandle { public: - typedef boost::any AnyFunction; + typedef boost::any AnyFunction; ///< Generic function pointer for constraint and interpolator functions /** + * @brief The action that will happen when the constraint is removed. + * * Constraints can be applied gradually; see SetApplyTime() for more details. * When a constraint is fully-applied the final value may be "baked" i.e. saved permanently. * Alternatively the constrained value may be discarded when the constraint is removed. @@ -68,17 +70,19 @@ public: Discard ///< When the constraint is removed, the constrained value is discarded. }; - static const AlphaFunction DEFAULT_ALPHA_FUNCTION; // AlphaFunctions::Linear - static const RemoveAction DEFAULT_REMOVE_ACTION; // Bake + static const AlphaFunction DEFAULT_ALPHA_FUNCTION; ///< AlphaFunctions::Linear + static const RemoveAction DEFAULT_REMOVE_ACTION; ///< Bake /** - * Create an uninitialized Constraint; this can be initialized with Constraint::New() + * @brief Create an uninitialized Constraint; this can be initialized with Constraint::New(). + * * Calling member functions with an uninitialized Dali::Object is not allowed. */ Constraint(); /** - * Create a constraint which targets a property. + * @brief Create a constraint which targets a property. + * * The templated parameter P, is the type of the property to constrain. * Animation will be performed using the default interpolator. * @param [in] target The index of the property to constrain. @@ -96,7 +100,8 @@ public: } /** - * Create a constraint which targets a property. + * @brief Create a constraint which targets a property. + * * The templated parameter P, is the type of the property to constrain. * @param [in] target The index of the property to constrain. * @param [in] func A function which returns the constrained property value. @@ -115,7 +120,8 @@ public: } /** - * Create a constraint which targets a property. + * @brief Create a constraint which targets a property. + * * The templated parameter P, is the type of the property to constrain. * Animation will be performed using the default interpolator. * @param [in] target The index of the property to constrain. @@ -136,7 +142,8 @@ public: } /** - * Create a constraint which targets a property. + * @brief Create a constraint which targets a property. + * * The templated parameter P, is the type of the property to constrain. * @param [in] target The index of the property to constrain. * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func. @@ -158,7 +165,8 @@ public: } /** - * Create a constraint which targets a property. + * @brief Create a constraint which targets a property. + * * The templated parameter P, is the type of the property to constrain. * Animation will be performed using the default interpolator. * @param [in] target The index of the property to constrain. @@ -182,7 +190,8 @@ public: } /** - * Create a constraint which targets a property. + * @brief Create a constraint which targets a property. + * * The templated parameter P, is the type of the property to constrain. * @param [in] target The index of the property to constrain. * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func. @@ -207,7 +216,8 @@ public: } /** - * Create a constraint which targets a property. + * @brief Create a constraint which targets a property. + * * The templated parameter P, is the type of the property to constrain. * Animation will be performed using the default interpolator. * @param [in] target The index of the property to constrain. @@ -234,7 +244,8 @@ public: } /** - * Create a constraint which targets a property. + * @brief Create a constraint which targets a property. + * * The templated parameter P, is the type of the property to constrain. * @param [in] target The index of the property to constrain. * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func. @@ -262,7 +273,8 @@ public: } /** - * Create a constraint which targets a property. + * @brief Create a constraint which targets a property. + * * The templated parameter P, is the type of the property to constrain. * Animation will be performed using the default interpolator. * @param [in] target The index of the property to constrain. @@ -296,7 +308,8 @@ public: } /** - * Create a constraint which targets a property. + * @brief Create a constraint which targets a property. + * * The templated parameter P, is the type of the property to constrain. * @param [in] target The index of the property to constrain. * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func. @@ -331,7 +344,8 @@ public: } /** - * Create a constraint which targets a property. + * @brief Create a constraint which targets a property. + * * The templated parameter P, is the type of the property to constrain. * Animation will be performed using the default interpolator. * @param [in] target The index of the property to constrain. @@ -369,7 +383,8 @@ public: } /** - * Create a constraint which targets a property. + * @brief Create a constraint which targets a property. + * * The templated parameter P, is the type of the property to constrain. * @param [in] target The index of the property to constrain. * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func. @@ -408,7 +423,8 @@ public: } /** - * Create a constraint which targets a property. + * @brief Create a constraint which targets a property. + * * The templated parameter P, is the type of the property to constrain. * Animation will be performed using the default interpolator. * @param [in] target The index of the property to constrain. @@ -450,7 +466,8 @@ public: } /** - * Create a constraint which targets a property. + * @brief Create a constraint which targets a property. + * * The templated parameter P, is the type of the property to constrain. * @param [in] target The index of the property to constrain. * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func. @@ -493,7 +510,9 @@ public: } /** - * Downcast an Object handle to Constraint handle. If handle points to a Constraint object the + * @brief Downcast an Object handle to Constraint handle. + * + * If handle points to a Constraint object the * downcast produces valid handle. If not the returned handle is left uninitialized. * @param[in] handle to An object * @return handle to a Constraint object or an uninitialized handle @@ -501,7 +520,8 @@ public: static Constraint DownCast( BaseHandle handle ); /** - * Destructor + * @brief Destructor. + * */ virtual ~Constraint(); @@ -511,45 +531,52 @@ public: using BaseHandle::operator=; /** - * Set the time taken for the constraint to be fully applied. + * @brief Set the time taken for the constraint to be fully applied. + * * The default is zero, meaning that the constraint is applied immediately. * @param [in] timePeriod The constraint will be applied during this time period. */ void SetApplyTime( TimePeriod timePeriod ); /** - * Retrieve the time taken for the constraint to be fully applied. + * @brief Retrieve the time taken for the constraint to be fully applied. + * * @return The apply time. */ TimePeriod GetApplyTime() const; /** - * Set the time taken for the constraint to be fully removed. + * @brief Set the time taken for the constraint to be fully removed. + * * The default is zero, meaning that the constraint is removed immediately. * @param [in] timePeriod The constraint will be removed during this time period. */ void SetRemoveTime( TimePeriod timePeriod ); /** - * Retrieve the time taken for the constraint to be fully removed. + * @brief Retrieve the time taken for the constraint to be fully removed. + * * @return The remove time. */ TimePeriod GetRemoveTime() const; /** - * Set the alpha function for a constraint; the default is AlphaFunctions::Linear. + * @brief Set the alpha function for a constraint; the default is AlphaFunctions::Linear. + * * @param [in] func The alpha function to use when applying/removing the constraint. */ void SetAlphaFunction( AlphaFunction func ); /** - * Retrieve the alpha function of a constraint. + * @brief Retrieve the alpha function of a constraint. + * * @return The function. */ AlphaFunction GetAlphaFunction(); /** - * Set whether the constraint will "bake" a value when fully-applied. + * @brief Set whether the constraint will "bake" a value when fully-applied. + * * Otherwise the constrained value will be discarded, when the constraint is removed. * The default value is Constraint::Bake. * @param[in] action The remove-action. @@ -557,7 +584,8 @@ public: void SetRemoveAction( RemoveAction action ); /** - * Query whether the constraint will "bake" a value when fully-applied. + * @brief Query whether the constraint will "bake" a value when fully-applied. + * * Otherwise the constrained value will be discarded, when the constraint is removed. * @return The apply-action. */ @@ -566,7 +594,7 @@ public: public: // Not intended for use by Application developers /** - * This constructor is used by Dali New() methods + * @brief This constructor is used by Dali New() methods * @param [in] constraint A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL Constraint( Internal::Constraint* constraint ); @@ -574,11 +602,13 @@ public: // Not intended for use by Application developers private: // Not intended for use by Application developers /** - * Construct a new constraint which targets a property. + * @brief Construct a new constraint which targets a property. + * * @param [in] target The index of the property to constrain. * @param [in] targetType The type of the constrained property. * @param [in] func The constraint function. * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func. + * @return The new constraint. */ static Constraint New( Property::Index target, Property::Type targetType, @@ -586,12 +616,14 @@ private: // Not intended for use by Application developers AnyFunction interpolator ); /** - * Construct a new constraint which targets a property. + * @brief Construct a new constraint which targets a property. + * * @param [in] target The index of the property to constrain. * @param [in] targetType The type of the constrained property. * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func. * @param [in] func The constraint function. * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func. + * @return The new constraint. */ static Constraint New( Property::Index target, Property::Type targetType, @@ -600,13 +632,15 @@ private: // Not intended for use by Application developers AnyFunction interpolator ); /** - * Construct a new constraint which targets a property. + * @brief Construct a new constraint which targets a property. + * * @param [in] target The index of the property to constrain. * @param [in] targetType The type of the constrained property. * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func. * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func. * @param [in] func The constraint function. * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func. + * @return The new constraint. */ static Constraint New( Property::Index target, Property::Type targetType, @@ -616,7 +650,8 @@ private: // Not intended for use by Application developers AnyFunction interpolator ); /** - * Construct a new constraint which targets a property. + * @brief Construct a new constraint which targets a property. + * * @param [in] target The index of the property to constrain. * @param [in] targetType The type of the constrained property. * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func. @@ -624,6 +659,7 @@ private: // Not intended for use by Application developers * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func. * @param [in] func The constraint function. * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func. + * @return The new constraint. */ static Constraint New( Property::Index target, Property::Type targetType, @@ -634,7 +670,8 @@ private: // Not intended for use by Application developers AnyFunction interpolator ); /** - * Construct a new constraint which targets a property. + * @brief Construct a new constraint which targets a property. + * * @param [in] target The index of the property to constrain. * @param [in] targetType The type of the constrained property. * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func. @@ -643,6 +680,7 @@ private: // Not intended for use by Application developers * @param [in] source4 The source of a property; the current value will be passed as the 5th parameter of func. * @param [in] func The constraint function. * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func. + * @return The new constraint. */ static Constraint New( Property::Index target, Property::Type targetType, @@ -654,7 +692,8 @@ private: // Not intended for use by Application developers AnyFunction interpolator ); /** - * Construct a new constraint which targets a property. + * @brief Construct a new constraint which targets a property. + * * @param [in] target The index of the property to constrain. * @param [in] targetType The type of the constrained property. * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func. @@ -664,6 +703,7 @@ private: // Not intended for use by Application developers * @param [in] source5 The source of a property; the current value will be passed as the 6th parameter of func. * @param [in] func The constraint function. * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func. + * @return The new constraint. */ static Constraint New( Property::Index target, Property::Type targetType, @@ -676,7 +716,8 @@ private: // Not intended for use by Application developers AnyFunction interpolator ); /** - * Construct a new constraint which targets a property. + * @brief Construct a new constraint which targets a property. + * * @param [in] target The index of the property to constrain. * @param [in] targetType The type of the constrained property. * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func. @@ -687,6 +728,7 @@ private: // Not intended for use by Application developers * @param [in] source6 The source of a property; the current value will be passed as the 7th parameter of func. * @param [in] func The constraint function. * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func. + * @return The new constraint. */ static Constraint New( Property::Index target, Property::Type targetType, diff --git a/capi/dali/public-api/animation/constraints.h b/capi/dali/public-api/animation/constraints.h index e96743f..4407f48 100644 --- a/capi/dali/public-api/animation/constraints.h +++ b/capi/dali/public-api/animation/constraints.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_ANIMATION_MODULE * @{ */ @@ -35,16 +35,21 @@ class Matrix; class Matrix3; /** - * Scale To Fit constraint. + * @brief Scale To Fit constraint. * * Scales an Actor, such that it fits within it's Parent's Size. * f(current, size, parentSize) = parentSize / size */ struct DALI_IMPORT_API ScaleToFitConstraint { + /** + * @brief Constructor. + */ ScaleToFitConstraint(); /** + * @brief Functor operator + * * @param[in] current The actor's current scale * @param[in] sizeProperty The actor's current size * @param[in] parentSizeProperty The parent's current size. @@ -57,16 +62,21 @@ struct DALI_IMPORT_API ScaleToFitConstraint }; /** - * Scale To Fit Keep Aspect Ratio constraint. + * @brief Scale To Fit Keep Aspect Ratio constraint. * * Scales an Actor, such that it fits within its Parent's Size Keeping the aspect ratio. * f(current, size, parentSize) = Vector3( min( parentSizeX / sizeX, min( parentSizeY / sizeY, parentSizeZ / sizeZ ) ) */ struct DALI_IMPORT_API ScaleToFitKeepAspectRatioConstraint { + /** + * @brief Constructor. + */ ScaleToFitKeepAspectRatioConstraint(); /** + * @brief Functor operator + * * @param[in] current The actor's current scale * @param[in] sizeProperty The actor's current size * @param[in] parentSizeProperty The parent's current size. @@ -78,13 +88,16 @@ struct DALI_IMPORT_API ScaleToFitKeepAspectRatioConstraint }; /** - * Scale To Fill Keep Aspect Ratio constraint. + * @brief Scale To Fill Keep Aspect Ratio constraint. * * Scales an Actor, such that it fill its Parent's Size Keeping the aspect ratio. * f(current, size, parentSize) = Vector3( max( parentSizeX / sizeX, max( parentSizeY / sizeY, parentSizeZ / sizeZ ) ) */ struct DALI_IMPORT_API ScaleToFillKeepAspectRatioConstraint { + /** + * @brief Constructor. + */ ScaleToFillKeepAspectRatioConstraint(); /** @@ -99,13 +112,16 @@ struct DALI_IMPORT_API ScaleToFillKeepAspectRatioConstraint }; /** - * Scale To Fill XY Keep Aspect Ratio constraint. + * @brief Scale To Fill XY Keep Aspect Ratio constraint. * * Scales an Actor, such that it fill its Parent's Size in the X and Y coordinates Keeping the aspect ratio. * f(current, size, parentSize) = Vector3( max( parentSizeX / sizeX, max( parentSizeY / sizeY, parentSizeZ / sizeZ ) ) */ struct DALI_IMPORT_API ScaleToFillXYKeepAspectRatioConstraint { + /** + * @brief Constructor. + */ ScaleToFillXYKeepAspectRatioConstraint(); /** @@ -120,11 +136,14 @@ struct DALI_IMPORT_API ScaleToFillXYKeepAspectRatioConstraint }; /** - * Shrinks source size inside the target size maintaining aspect ratio of source. + * @brief Shrinks source size inside the target size maintaining aspect ratio of source. * If source is smaller than target it returns source */ struct ShrinkInsideKeepAspectRatioConstraint { + /** + * @brief Constructor. + */ ShrinkInsideKeepAspectRatioConstraint(); /** @@ -139,12 +158,15 @@ struct ShrinkInsideKeepAspectRatioConstraint }; /** - * MultiplyConstraint + * @brief MultiplyConstraint * * f(current, property) = current * property */ struct DALI_IMPORT_API MultiplyConstraint { + /** + * @brief Constructor. + */ MultiplyConstraint(); /** @@ -157,12 +179,15 @@ struct DALI_IMPORT_API MultiplyConstraint }; /** - * DivideConstraint + * @brief DivideConstraint * * f(current, property) = current / property */ struct DALI_IMPORT_API DivideConstraint { + /** + * @brief Constructor. + */ DivideConstraint(); /** @@ -175,93 +200,187 @@ struct DALI_IMPORT_API DivideConstraint }; /** - * EqualToConstraint + * @brief EqualToConstraint * * f(current, property) = property */ struct DALI_IMPORT_API EqualToConstraint { + /** + * @brief Constructor. + */ EqualToConstraint(); + /** + * @brief override functor for float properties + * + * @param[in] current The current property value + * @param[in] property The property to copy + * @return The copy of the input property + */ float operator()(const float current, const PropertyInput& property); + + /** + * @brief override functor for float properties + * + * @param[in] current The current property value + * @param[in] property The property to copy + * @return The copy of the input property + */ Vector3 operator()(const Vector3& current, const PropertyInput& property); + + /** + * @brief override functor for float properties + * + * @param[in] current The current property value + * @param[in] property The property to copy + * @return The copy of the input property + */ Vector4 operator()(const Vector4& current, const PropertyInput& property); + + /** + * @brief override functor for float properties + * + * @param[in] current The current property value + * @param[in] property The property to copy + * @return The copy of the input property + */ Quaternion operator()(const Quaternion& current, const PropertyInput& property); + + /** + * @brief override functor for float properties + * + * @param[in] current The current property value + * @param[in] property The property to copy + * @return The copy of the input property + */ Matrix3 operator()(const Matrix3& current, const PropertyInput& property); + + /** + * @brief override functor for float properties + * + * @param[in] current The current property value + * @param[in] property The property to copy + * @return The copy of the input property + */ Matrix operator()(const Matrix& current, const PropertyInput& property); }; /** - * RelativeToConstraint + * @brief RelativeToConstraint for Vector3 properties * * f(current, property, scale) = property * scale */ struct DALI_IMPORT_API RelativeToConstraint { + /** + * @brief Constructor. + */ RelativeToConstraint( float scale ); + + /** + * @brief Constructor. + */ RelativeToConstraint( const Vector3& scale ); + /** + * @brief Functor. + */ Vector3 operator()(const Vector3& current, const PropertyInput& property); - Vector3 mScale; + Vector3 mScale; ///< Component-wise scale factor }; +/** + * @brief RelativeToConstraint for float properties + */ struct DALI_IMPORT_API RelativeToConstraintFloat { + /** + * @brief Constructor. + */ RelativeToConstraintFloat( float scale ); + /** + * @brief Functor. + */ float operator()(const float current, const PropertyInput& property); - float mScale; + float mScale; ///< Scale factor }; /** - * InverseOfConstraint + * @brief InverseOfConstraint * * f(current, property) = 1 / property */ struct DALI_IMPORT_API InverseOfConstraint { + /** + * @brief Constructor. + */ InverseOfConstraint(); + /** + * @brief Functor. + */ Vector3 operator()(const Vector3& current, const PropertyInput& property); }; /** - * Constraint which sets width to be another actor's width, + * @brief Constraint which sets width to be another actor's width, * and the height to a fixed height. */ struct DALI_IMPORT_API SourceWidthFixedHeight { + /** + * @brief Constructor. + */ SourceWidthFixedHeight( float height ); + /** + * @brief Functor. + */ Vector3 operator()(const Vector3& current, const PropertyInput& sourceSize); - float mFixedHeight; + float mFixedHeight; ///< the fixed height }; /** - * Constraint which sets height to be another actor's height, + * @brief Constraint which sets height to be another actor's height, * and the width to a fixed width. */ struct DALI_IMPORT_API SourceHeightFixedWidth { + /** + * @brief Constructor + */ SourceHeightFixedWidth( float width ); + /** + * @brief Functor + */ Vector3 operator()(const Vector3& current, const PropertyInput& sourceSize); - float mFixedWidth; + float mFixedWidth; ///< the fixed width }; /** + * @brief Constraint function to aim a camera at a target. + * * Constraint which sets camera's rotation given camera world position - * and a target world position Uses target's up vector to orient the + * and a target world position. Uses target's up vector to orient the * constrained actor along the vector between camera position and * target position. * + * @param[in] current The current rotation property value + * @param[in] targetPosition World position of target + * @param[in] cameraPosition World position of camera + * @param[in] targetRotation World rotation of the target + * @return The orientation of the camera */ DALI_IMPORT_API Dali::Quaternion LookAt( const Dali::Quaternion& current, const PropertyInput& targetPosition, @@ -270,6 +389,8 @@ DALI_IMPORT_API Dali::Quaternion LookAt( const Dali::Quaternion& current, /** + * @brief Constraint functor to aim a camera at a target. + * * Constraint which sets rotation given camera world position, * target world position (usually the looked at actor's world position) * and the angle parameter (how much the camera is offset with respect @@ -278,7 +399,7 @@ DALI_IMPORT_API Dali::Quaternion LookAt( const Dali::Quaternion& current, struct DALI_IMPORT_API OrientedLookAt { /** - * Functor constructor + * @brief Functor constructor. * * @param[in] angle The angle of the camera's up vector with regards * to the target's up vector in radians. Positive angles rotate the @@ -286,12 +407,21 @@ struct DALI_IMPORT_API OrientedLookAt */ OrientedLookAt( float angle ); + /** + * @brief Functor. + * + * @param[in] current The current rotation property value + * @param[in] targetPosition World position of target + * @param[in] cameraPosition World position of camera + * @param[in] targetRotation World rotation of the target + * @return The orientation of the camera + */ Dali::Quaternion operator()(const Dali::Quaternion& current, const PropertyInput& targetPosition, const PropertyInput& cameraPosition, const PropertyInput& targetRotation ); - float mAngle; + float mAngle; ///< camera angle offset }; diff --git a/capi/dali/public-api/animation/interpolator-functions.h b/capi/dali/public-api/animation/interpolator-functions.h index baf4deb..2b2ca05 100644 --- a/capi/dali/public-api/animation/interpolator-functions.h +++ b/capi/dali/public-api/animation/interpolator-functions.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_ANIMATION_MODULE * @{ */ @@ -40,7 +40,7 @@ namespace Dali DALI_IMPORT_API // Interpolation functions used by Constraints /** - * Interpolate linearly between two boolean values. + * @brief Interpolate linearly between two boolean values. * @param [in] current The current value. * @param [in] target The target value. * @param [in] progress The current progress (between 0 & 1). @@ -49,7 +49,8 @@ namespace Dali DALI_IMPORT_API bool LerpBoolean( const bool& current, const bool& target, float progress ); /** - * Interpolate linearly between two float values. + * @brief Interpolate linearly between two float values. + * * @param [in] current The current value. * @param [in] target The target value. * @param [in] progress The current progress (between 0 & 1). @@ -58,7 +59,8 @@ bool LerpBoolean( const bool& current, const bool& target, float progress ); float LerpFloat( const float& current, const float& target, float progress ); /** - * Interpolate linearly between two Vector2 values. + * @brief Interpolate linearly between two Vector2 values. + * * @param [in] current The current value. * @param [in] target The target value. * @param [in] progress The current progress (between 0 & 1). @@ -67,7 +69,8 @@ float LerpFloat( const float& current, const float& target, float progress ); Vector2 LerpVector2( const Vector2& current, const Vector2& target, float progress ); /** - * Interpolate linearly between two Vector3 values. + * @brief Interpolate linearly between two Vector3 values. + * * @param [in] current The current value. * @param [in] target The target value. * @param [in] progress The current progress (between 0 & 1). @@ -76,7 +79,8 @@ Vector2 LerpVector2( const Vector2& current, const Vector2& target, float progre Vector3 LerpVector3( const Vector3& current, const Vector3& target, float progress ); /** - * Interpolate linearly between two Vector4 values. + * @brief Interpolate linearly between two Vector4 values. + * * @param [in] current The current value. * @param [in] target The target value. * @param [in] progress The current progress (between 0 & 1). @@ -85,7 +89,8 @@ Vector3 LerpVector3( const Vector3& current, const Vector3& target, float progre Vector4 LerpVector4( const Vector4& current, const Vector4& target, float progress ); /** - * Spherical linear interpolation between two Quaternion values. + * @brief Spherical linear interpolation between two Quaternion values. + * * @param [in] current The current value. * @param [in] target The target value. * @param [in] progress The current progress (between 0 & 1). @@ -94,7 +99,8 @@ Vector4 LerpVector4( const Vector4& current, const Vector4& target, float progre Quaternion SlerpQuaternion( const Quaternion& current, const Quaternion& target, float progress ); /** - * A function which interpolates between a start and target value. + * @brief A function which interpolates between a start and target value. + * * @param[in] start The start value. * @param[in] target The target value. * @param[in] progress The current progress (between 0 and 1). @@ -103,7 +109,8 @@ Quaternion SlerpQuaternion( const Quaternion& current, const Quaternion& target, typedef boost::function BoolInterpolator; /** - * A function which interpolates between a start and target value. + * @brief A function which interpolates between a start and target value. + * * @param[in] start The start value. * @param[in] target The target value. * @param[in] progress The current progress (between 0 and 1). @@ -112,7 +119,8 @@ typedef boost::function FloatInterpolator; /** - * A function which interpolates between a start and target value. + * @brief A function which interpolates between a start and target value. + * * @param[in] start The start value. * @param[in] target The target value. * @param[in] progress The current progress (between 0 and 1). @@ -121,7 +129,8 @@ typedef boost::function Vector2Interpolator; /** - * A function which interpolates between a start and target value. + * @brief A function which interpolates between a start and target value. + * * @param[in] start The start value. * @param[in] target The target value. * @param[in] progress The current progress (between 0 and 1). @@ -130,7 +139,8 @@ typedef boost::function Vector3Interpolator; /** - * A function which interpolates between a start and target value. + * @brief A function which interpolates between a start and target value. + * * @param[in] start The start value. * @param[in] target The target value. * @param[in] progress The current progress (between 0 and 1). @@ -139,7 +149,8 @@ typedef boost::function Vector4Interpolator; /** - * A function which interpolates between a start and target value. + * @brief A function which interpolates between a start and target value. + * * @param[in] start The start value. * @param[in] target The target value. * @param[in] progress The current progress (between 0 and 1). @@ -148,7 +159,8 @@ typedef boost::function QuaternionInterpolator; /** - * A function which interpolates between a start and target value. + * @brief A function which interpolates between a start and target value. + * * @param[in] start The start value. * @param[in] target The target value. * @param[in] progress The current progress (between 0 and 1). @@ -157,7 +169,8 @@ typedef boost::function Matrix3Interpolator; /** - * A function which interpolates between a start and target value. + * @brief A function which interpolates between a start and target value. + * * @param[in] start The start value. * @param[in] target The target value. * @param[in] progress The current progress (between 0 and 1). @@ -166,13 +179,15 @@ typedef boost::function MatrixInterpolator; /** - * Any interpolator function. + * @brief Any interpolator function. */ typedef boost::any AnyInterpolator; /** - * Retrieve an interpolator function for a property. + * @brief Retrieve an interpolator function for a property. + * * This can be cast to boost::function

where P corresponds to the property type. + * @param[in] type The property type for which to get an interpolator * @return The interpolator function. */ AnyInterpolator GetDefaultInterpolator(Property::Type type); diff --git a/capi/dali/public-api/animation/key-frames.h b/capi/dali/public-api/animation/key-frames.h index ddb2619..00fa23f 100644 --- a/capi/dali/public-api/animation/key-frames.h +++ b/capi/dali/public-api/animation/key-frames.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_ANIMATION_MODULE * @{ */ @@ -37,37 +37,43 @@ class KeyFrames; } /** - * Handle to a KeyFrames object. This allows the generation of key frame objects from - * individual Property::Values. The type of the key frame is specified by the type of - * the first value to be added. Adding key frames with a different Property::Value type - * will result in a run time assert. + * @brief A set of key frames for a property that can be animated using Dali::Animation::AnimateBetween(). + * + * This allows the generation of key frame objects from individual + * Property::Values. The type of the key frame is specified by the + * type of the first value to be added. Adding key frames with a + * different Property::Value type will result in a run time assert. */ class KeyFrames : public BaseHandle { public: /** - * Create an initialized KeyFrame handle. + * @brief Create an initialized KeyFrame handle. + * * @return a handle to a newly allocated Dali resource. */ static KeyFrames New(); /** - * Downcast an Object handle to KeyFrames handle. If handle points to a KeyFrames object the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to KeyFrames handle. + * + * If handle points to a KeyFrames object the downcast produces + * valid handle. If not the returned handle is left uninitialized. * @param[in] handle to An object * @return handle to a KeyFrames object or an uninitialized handle */ static KeyFrames DownCast( BaseHandle handle ); /** - * Create an uninitialized KeyFrame handle. This can be initialized with - * KeyFrame::New(). Calling member functions with an uninitialized Dali::Object - * is not allowed. + * @brief Create an uninitialized KeyFrame handle. + * + * This can be initialized with KeyFrame::New(). Calling member + * functions with an uninitialized Dali::Object is not allowed. */ KeyFrames(); /** - * Virtual destructor + * @brief Virtual destructor. */ virtual ~KeyFrames(); @@ -77,21 +83,26 @@ public: using BaseHandle::operator=; /** - * Gets the type of the key frame. If no key frames have been added, this returns - * Property::NONE. + * @brief Gets the type of the key frame. + * + * If no key frames have been added, this returns Property::NONE. * @return The key frame property type. */ Property::Type GetType() const; /** - * Add a key frame. The key frames should be added in time order. + * @brief Add a key frame. + * + * The key frames should be added in time order. * @param[in] progress A value between 0.0 and 1.0. * @param[in] value A value. */ void Add(float progress, Property::Value value); /** - * Add a key frame. The key frames should be added in time order. + * @brief Add a key frame. + * + * The key frames should be added in time order. * @param[in] progress A value between 0.0 and 1.0. * @param[in] value A value. * @param[in] alpha The alpha function used to blend to the next keyframe @@ -101,7 +112,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] keyFrames A pointer to an internal KeyFrame resource */ explicit DALI_INTERNAL KeyFrames(Internal::KeyFrames* keyFrames); diff --git a/capi/dali/public-api/animation/time-period.h b/capi/dali/public-api/animation/time-period.h index f81c1ce..5a9474f 100644 --- a/capi/dali/public-api/animation/time-period.h +++ b/capi/dali/public-api/animation/time-period.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_ANIMATION_MODULE * @{ */ @@ -29,25 +29,27 @@ namespace Dali DALI_IMPORT_API { /** - * A value-type representing a period of time within an animation. + * @brief A value-type representing a period of time within an animation. */ struct DALI_IMPORT_API TimePeriod { /** - * Create a time period. + * @brief Create a time period. + * * @param [in] durationSeconds The duration of the time period in seconds. */ TimePeriod(float durationSeconds); /** - * Create a time period. + * @brief Create a time period. + * * @param [in] delaySeconds A delay before the time period in seconds. * @param [in] durationSeconds The duration of the time period in seconds. */ TimePeriod(float delaySeconds, float durationSeconds); /** - * Non-virtual destructor; TimePeriod is not intended as a base class. + * @brief Non-virtual destructor; TimePeriod is not intended as a base class. */ ~TimePeriod(); diff --git a/capi/dali/public-api/common/constants.h b/capi/dali/public-api/common/constants.h index 1bf33dd..7673f20 100644 --- a/capi/dali/public-api/common/constants.h +++ b/capi/dali/public-api/common/constants.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_COMMON_MODULE * @{ */ @@ -34,21 +34,20 @@ namespace Dali DALI_IMPORT_API { -namespace ParentOrigin -{ - /** - * ParentOrigin constants + * @brief ParentOrigin constants + * * Note that for 2D layouting, the typical Z position is 0.5f (not 0.0f) */ +namespace ParentOrigin +{ +extern const Vector3 DEFAULT; ///< TOP_LEFT -extern const Vector3 DEFAULT; // TOP_LEFT - -extern const float TOP; // 0.0f -extern const float BOTTOM; // 1.0f -extern const float LEFT; // 0.0f -extern const float RIGHT; // 1.0f -extern const float MIDDLE; // 0.5f +extern const float TOP; ///< 0.0f +extern const float BOTTOM; ///< 1.0f +extern const float LEFT; ///< 0.0f +extern const float RIGHT; ///< 1.0f +extern const float MIDDLE; ///< 0.5f extern const Vector3 BACK_TOP_LEFT; ///< 0.0f, 0.0f, 0.0f extern const Vector3 BACK_TOP_CENTER; ///< 0.5f, 0.0f, 0.0f @@ -82,21 +81,20 @@ extern const Vector3 FRONT_BOTTOM_RIGHT; ///< 1.0f, 1.0f, 1.0f } -namespace AnchorPoint -{ - /** - * AnchorPoint constants + * @brief AnchorPoint constants + * * Note that for 2D layouting, the typical Z position is 0.5f (not 0.0f) */ +namespace AnchorPoint +{ +extern const float TOP; ///< 0.0f +extern const float BOTTOM; ///< 1.0f +extern const float LEFT; ///< 0.0f +extern const float RIGHT; ///< 1.0f +extern const float MIDDLE; ///< 0.5f -extern const float TOP; // 0.0f -extern const float BOTTOM; // 1.0f -extern const float LEFT; // 0.0f -extern const float RIGHT; // 1.0f -extern const float MIDDLE; // 0.5f - -extern const Vector3 DEFAULT; // CENTER +extern const Vector3 DEFAULT; ///< CENTER extern const Vector3 BACK_TOP_LEFT; ///< 0.0f, 0.0f, 0.0f extern const Vector3 BACK_TOP_CENTER; ///< 0.5f, 0.0f, 0.0f @@ -127,17 +125,16 @@ extern const Vector3 FRONT_CENTER_RIGHT; ///< 1.0f, 0.5f, 1.0f extern const Vector3 FRONT_BOTTOM_LEFT; ///< 0.0f, 1.0f, 1.0f extern const Vector3 FRONT_BOTTOM_CENTER;///< 0.5f, 1.0f, 1.0f extern const Vector3 FRONT_BOTTOM_RIGHT; ///< 1.0f, 1.0f, 1.0f - } -namespace Color -{ /** - * Color Constants. + * @brief Color Constants. + * * Color is represented by the Vector4 class (see vector4.h). */ - +namespace Color +{ extern const Vector4 BLACK; ///< Pure black (0.0f, 0.0f, 0.0f, 1.0f); extern const Vector4 WHITE; ///< Pure white (1.0f, 1.0f, 1.0f, 1.0f); @@ -153,31 +150,33 @@ extern const Vector4 TRANSPARENT; ///< Black transparent (0.0f, 0.0f, 0.0f, 0.0f } // namespace Color +/** + * @brief Math constants + */ namespace Math { - -extern const float MACHINE_EPSILON_0; -extern const float MACHINE_EPSILON_1; -extern const float MACHINE_EPSILON_10; -extern const float MACHINE_EPSILON_100; -extern const float MACHINE_EPSILON_1000; -extern const float MACHINE_EPSILON_10000; +extern const float MACHINE_EPSILON_0; ///< Epsilon for values near zero +extern const float MACHINE_EPSILON_1; ///< Epsilon for values near 1 +extern const float MACHINE_EPSILON_10; ///< Epsilon for values near 10 +extern const float MACHINE_EPSILON_100; ///< Epsilon for values near 100 +extern const float MACHINE_EPSILON_1000; ///< Epsilon for values near 1000 +extern const float MACHINE_EPSILON_10000; ///< Epsilon for values near 10000 // float is preferred to double for performance on ARM targets -const float PI = static_cast(M_PI); -const float PI_2 = static_cast(M_PI_2); -const float PI_4 = static_cast(M_PI_4); +const float PI = static_cast(M_PI); ///< Constant representing PI +const float PI_2 = static_cast(M_PI_2); ///< Constant representing PI/2 +const float PI_4 = static_cast(M_PI_4); ///< Constant representing PI/4 } // namespace Math +/** + * @brief String Constants + */ namespace String { - -extern const std::string EMPTY; - +extern const std::string EMPTY; ///< The empty string } - } // namespace Dali /** diff --git a/capi/dali/public-api/common/dali-common.h b/capi/dali/public-api/common/dali-common.h index a3eaf75..d31cf13 100644 --- a/capi/dali/public-api/common/dali-common.h +++ b/capi/dali/public-api/common/dali-common.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_COMMON_MODULE * @{ */ @@ -27,7 +27,7 @@ #include -/** +/* * Definitions for shared library support * * If a library is configured with --enable-exportall or --enable-debug @@ -48,8 +48,11 @@ # define DALI_INTERNAL __attribute__ ((visibility ("hidden"))) # endif #else +/** Visibility attribute to show method definitions */ # define DALI_EXPORT_API +/** Visibility attribute to show declarations */ # define DALI_IMPORT_API +/** Visibility attribute to hide declarations */ # define DALI_INTERNAL #endif @@ -75,11 +78,15 @@ #endif +/** + * @brief The DALi namespace + */ namespace Dali { /** - * Method to log assertion message in DALI_ASSERT_ALWAYS macro below + * @brief Method to log assertion message in DALI_ASSERT_ALWAYS macro below. + * * @param[in] condition The assertion condition * @param[in] file The file in which the assertion occurred * @param[in] line The line number at which the assertion occured @@ -87,27 +94,30 @@ namespace Dali DALI_IMPORT_API void DaliAssertMessage(const char* condition, const char* file, int line); /** - * Exception class for Dali Core library - Raised by assertions in codebase. + * @brief Exception class for Dali Core library - Raised by assertions in codebase. */ class DALI_IMPORT_API DaliException { public: /** - * Constructor. Will always display a backtrace when raised in a debug build. + * @brief Constructor. + * + * Will always display a backtrace when raised in a debug build. * * @param[in] location - the location of the assertion * @param[in] condition - The assertion condition */ DALI_IMPORT_API DaliException(const char *location, const char* condition); - std::string mLocation; - std::string mCondition; + std::string mLocation; ///< Location in code of the assertion + std::string mCondition; ///< The assertion string }; }// Dali /** - * An invariant concurrent assertion to ensure its argument always evaluates TRUE + * @brief An invariant concurrent assertion to ensure its argument always evaluates TRUE. + * * Use this for rules that must always be true regardless of build options. * For example, Actor must only ever have one parent. * To be clear, this test remains compiled into release builds that are deployed @@ -133,7 +143,8 @@ public: }\ /** - * An invariant concurrent assertion to ensure its argument evaluates TRUE in debug builds + * @brief An invariant concurrent assertion to ensure its argument evaluates TRUE in debug builds. + * * Use this to sanity check algorithms and prevent internal programming errors */ #if defined(DEBUG_ENABLED) diff --git a/capi/dali/public-api/common/intrusive-ptr.h b/capi/dali/public-api/common/intrusive-ptr.h index 6ee813d..4554c02 100644 --- a/capi/dali/public-api/common/intrusive-ptr.h +++ b/capi/dali/public-api/common/intrusive-ptr.h @@ -17,6 +17,11 @@ // limitations under the License. // +/** + * @addtogroup CAPI_DALI_OBJECT_MODULE + * @{ + */ + // INTERNAL INCLUDES #include @@ -24,7 +29,8 @@ namespace Dali { /** - * Templated class to emulate a sub-set of functions served by deprecating boost::intrusive_ptr + * @brief Templated class to emulate a sub-set of functions served by deprecating boost::intrusive_ptr. + * * Uses the Dali:Refobject type supply actual reference counting * The object is responsible for destroying itself */ @@ -35,12 +41,13 @@ class IntrusivePtr public: /** - * Standard constructor to unassigned object - */ + * @brief Standard constructor to unassigned object. + */ IntrusivePtr() : mPtr( 0 ) {} /** - * Constructor to attach existing object + * @brief Constructor to attach existing object. + * * @param p pointer to object, */ IntrusivePtr( T* p ) : mPtr( p ) @@ -52,7 +59,8 @@ public: } /** - * Copy constructor + * @brief Copy constructor. + * * @param rhs const reference to an IntrusivePtr * @tparam U reference counter object type */ @@ -66,7 +74,7 @@ public: } /** - * Copy constructor + * @brief Copy constructor. */ IntrusivePtr( IntrusivePtr const& rhs ) : mPtr( rhs.mPtr ) { @@ -77,7 +85,8 @@ public: } /** - * Destructor + * @brief Destructor. + * * Object will self-destruct if reference count is zero */ ~IntrusivePtr() @@ -89,37 +98,41 @@ public: } /** - * Get pointer to reference counted object - * @return pointer to reference counted object - */ + * @brief Get pointer to reference counted object. + * + * @return pointer to reference counted object + */ T* Get() const { return mPtr; } /** - * Pointer operator ovveride - * @return pointer to reference counted object - */ + * @brief Pointer operator ovveride. + * + * @return pointer to reference counted object + */ T* operator->() const { return mPtr; } /** - * Dereference operator override - * @return reference to reference counted object - */ + * @brief Dereference operator override. + * + * @return reference to reference counted object + */ T& operator*() const { return *mPtr; } /** - * Assignment operator - * @param rhs const reference to intrusive pointer - * @return reference to reference counted object - */ + * @brief Assignment operator. + * + * @param rhs const reference to intrusive pointer + * @return reference to reference counted object + */ IntrusivePtr& operator=( IntrusivePtr const& rhs ) { IntrusivePtr( rhs ).Swap( *this ); @@ -127,9 +140,11 @@ public: } /** - * Assignment operator - * @param rhs pointer to object to wrap - */ + * @brief Assignment operator. + * + * @param rhs pointer to object to wrap + * @return A reference to this object + */ IntrusivePtr& operator=( T* rhs ) { IntrusivePtr( rhs ).Swap( *this ); @@ -137,7 +152,7 @@ public: } /** - * Reset intrusive pointer + * @brief Reset intrusive pointer. */ void Reset() { @@ -145,7 +160,8 @@ public: } /** - * Reset intrusive pointer with reference counted object + * @brief Reset intrusive pointer with reference counted object. + * * @param rhs pointer to object */ void Reset( T* rhs ) @@ -156,12 +172,15 @@ public: // IntrusivePtr comparisons - This is a variation of the safe bool idiom /** - * Pointer-to-member type. Objects can be implicitly converted to this for validity checks. + * @brief Pointer-to-member type. + * + * Objects can be implicitly converted to this for validity checks. */ typedef void (IntrusivePtr::*BooleanType)() const; /** - * Converts an object handle to a BooleanType. + * @brief Converts an object handle to a BooleanType. + * * This is useful for checking whether the handle is NULL. */ operator BooleanType() const @@ -172,12 +191,12 @@ public: private: /** - * Used by the safe bool idiom. + * @brief Used by the safe bool idiom. */ void ThisIsSaferThanReturningVoidStar() const {} /** - * Internal swap function + * @brief Internal swap function */ void Swap( IntrusivePtr& rhs ) { @@ -186,59 +205,83 @@ private: rhs.mPtr = tmp; } - T* mPtr; // pointer to RefObject + T* mPtr; ///< pointer to RefObject }; /** - * Comparison overrides of objects wrapped by intrusive pointers + * @brief Comparison overrides of objects wrapped by intrusive pointers. * * @param lhs intrusive pointer to compare with * @param rhs intrusive pointer to compare against + * @return true if the pointers point at the same object */ template inline bool operator==( IntrusivePtrconst& lhs, IntrusivePtrconst& rhs ) { return lhs.Get() == rhs.Get(); } +/** + * @brief Comparison overrides of objects wrapped by intrusive pointers. + * + * @param lhs intrusive pointer to compare with + * @param rhs intrusive pointer to compare against + * @return true if the pointers point at different objects + */ template inline bool operator!=( IntrusivePtrconst& lhs, IntrusivePtrconst &rhs) { return lhs.Get() != rhs.Get(); } /** - * Comparison overrides of objects wrapped by intrusive pointers + * @brief Comparison overrides of objects wrapped by intrusive pointers * * @param lhs intrusive pointer to compare with - * @param rhs object compare against + * @param rhs object to compare against + * @return true if the intrusive pointer points at the specified object */ template inline bool operator==( IntrusivePtrconst& lhs, U* rhs ) { return lhs.Get() == rhs; } +/** + * @brief Comparison overrides of objects wrapped by intrusive pointers. + * + * @param lhs intrusive pointer to compare with + * @param rhs intrusive pointer to compare against + * @return true if the intrusive pointer doesn't point at the specified object + */ template inline bool operator!=( IntrusivePtrconst& lhs, U* rhs ) { return lhs.Get() != rhs; } /** - * Comparison overrides of objects wrapped by intrusive pointers + * @brief Comparison overrides of objects wrapped by intrusive pointers * * @param lhs object to compare with * @param rhs intrusive pointer to compare against + * @return true if the intrusive pointer points at the specified object */ template inline bool operator==( T* lhs, IntrusivePtrconst& rhs ) { return lhs == rhs.Get(); } +/** + * @brief Comparison overrides of objects wrapped by intrusive pointers + * + * @param lhs object to compare with + * @param rhs intrusive pointer to compare against + * @return true if the intrusive pointer doesn't point at the specified object + */ template inline bool operator!=( T* lhs, IntrusivePtrconst& rhs ) { return lhs != rhs.Get(); } /** - * Get pointer to reference counted object (Dali camel case variant) + * @brief Get pointer to reference counted object (Dali camel case variant) * * @param rhs intrusive pointer wrapping object * @return pointer to object @@ -249,7 +292,7 @@ templateinline T* GetPointer(IntrusivePtr const& rhs) } /** - * Get pointer to reference counted object (boost:: naming convention) + * @brief Get pointer to reference counted object (boost:: naming convention) * * @param rhs intrusive pointer wrapping object * @return pointer to object @@ -259,6 +302,9 @@ templateinline T* get_pointer(IntrusivePtr const& rhs) return rhs.Get(); } -} +} // namespace Dali +/** + * @} + */ #endif /* __DALI_INTRUSIVE_PTR_H__ */ diff --git a/capi/dali/public-api/common/loading-state.h b/capi/dali/public-api/common/loading-state.h index f9269cd..53d5b65 100644 --- a/capi/dali/public-api/common/loading-state.h +++ b/capi/dali/public-api/common/loading-state.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_COMMON_MODULE * @{ */ @@ -29,7 +29,7 @@ namespace Dali DALI_IMPORT_API { /** - * The status during resource loading operations. + * @brief The status during resource loading operations. */ enum LoadingState { diff --git a/capi/dali/public-api/common/stage.h b/capi/dali/public-api/common/stage.h index 9224325..9a28314 100644 --- a/capi/dali/public-api/common/stage.h +++ b/capi/dali/public-api/common/stage.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_COMMON_MODULE * @{ */ @@ -47,45 +47,50 @@ struct KeyEvent; struct TouchEvent; /** - * The Stage is a top-level object used for displaying a tree of Actors. + * @brief The Stage is a top-level object used for displaying a tree of Actors. + * * Multiple stage/window support is not currently provided. */ class Stage : public BaseHandle { public: - typedef SignalV2< void (const KeyEvent&)> KeyEventSignalV2; - typedef SignalV2< void () > EventProcessingFinishedSignalV2; - typedef SignalV2< void (const TouchEvent&)> TouchedSignalV2; + typedef SignalV2< void (const KeyEvent&)> KeyEventSignalV2; ///< Key event signal type + typedef SignalV2< void () > EventProcessingFinishedSignalV2; ///< Event Processing finished signal type + typedef SignalV2< void (const TouchEvent&)> TouchedSignalV2; ///< Touched signal type static const Vector4 DEFAULT_BACKGROUND_COLOR; ///< Default black background. static const Vector4 DEBUG_BACKGROUND_COLOR; ///< Green background, useful when debugging. // Signal Names - static const char* const SIGNAL_KEY_EVENT; - static const char* const SIGNAL_EVENT_PROCESSING_FINISHED; - static const char* const SIGNAL_TOUCHED; + static const char* const SIGNAL_KEY_EVENT; ///< name "key-event" + static const char* const SIGNAL_EVENT_PROCESSING_FINISHED; ///< name "event-processing-finished" + static const char* const SIGNAL_TOUCHED; ///< name "touched" /** - * Allows the creation of an empty stage handle. To retrieve the current stage, - * this handle can be set using Stage::GetCurrent(). + * @brief Allows the creation of an empty stage handle. + * + * To retrieve the current stage, this handle can be set using Stage::GetCurrent(). */ Stage(); /** - * Get the current Stage. + * @brief Get the current Stage. + * * @return The current stage or an empty handle if Core has not been created or has been already destroyed. */ static Stage GetCurrent(); /** - * Query whether the Stage exists; this should only return false during or after destruction of Dali core. + * @brief Query whether the Stage exists; this should only return false during or after destruction of Dali core. + * * @return True when it's safe to call Stage::GetCurrent(). */ static bool IsInstalled(); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~Stage(); @@ -98,7 +103,9 @@ public: // Containment /** - * Adds a child Actor to the Stage. The child will be referenced. + * @brief Adds a child Actor to the Stage. + * + * The child will be referenced. * @pre The actor has been initialized. * @pre The actor does not have a parent. * @param [in] actor The child. @@ -106,14 +113,17 @@ public: void Add(Actor& actor); /** - * Removes a child Actor from the Stage. The child will be unreferenced. + * @brief Removes a child Actor from the Stage. + * + * The child will be unreferenced. * @pre The actor has been added to the stage. * @param [in] actor The child. */ void Remove(Actor& actor); /** - * Returns the size of the Stage in pixels as a Vector. + * @brief Returns the size of the Stage in pixels as a Vector. + * * The x component will be the width of the Stage in pixels * The y component will be the height of the Stage in pixels * The z component will be the distance between far and near planes @@ -124,7 +134,8 @@ public: // Render Tasks /** - * Retrieve the list of render-tasks. + * @brief Retrieve the list of render-tasks. + * * @return A valid handle to a RenderTaskList. */ RenderTaskList GetRenderTaskList() const; @@ -132,14 +143,16 @@ public: // Layers /** - * Query the number of on-stage layers. + * @brief Query the number of on-stage layers. + * * Note that a default layer is always provided (count >= 1). * @return The number of layers. */ unsigned int GetLayerCount() const; /** - * Retrieve the layer at a specified depth. + * @brief Retrieve the layer at a specified depth. + * * @pre depth is less than layer count; see GetLayerCount(). * @param[in] depth The depth. * @return The layer found at the given depth. @@ -147,7 +160,8 @@ public: Layer GetLayer(unsigned int depth) const; /** - * Returns the Stage's Root Layer. + * @brief Returns the Stage's Root Layer. + * * @return The root layer. */ Layer GetRootLayer() const; @@ -155,25 +169,29 @@ public: // Background color /** - * Set the background color of the stage. + * @brief Set the background color of the stage. + * * @param[in] color The new background color. */ void SetBackgroundColor(Vector4 color); /** - * Retrieve the background color of the stage. + * @brief Retrieve the background color of the stage. + * * @return The background color. */ Vector4 GetBackgroundColor() const; /** - * Retrieve the DPI of the display device to which the stage is connected. + * @brief Retrieve the DPI of the display device to which the stage is connected. + * * @return the horizontal and vertical DPI */ Vector2 GetDpi() const; /** - * Get the Object registry. + * @brief Get the Object registry. + * * @return The object registry. */ ObjectRegistry GetObjectRegistry() const; @@ -181,7 +199,8 @@ public: // Dynamics /** - * Initialise the dynamics simulation and create a DynamicsWorld object. + * @brief Initialise the dynamics simulation and create a DynamicsWorld object. + * * Only one instance of DynamicsWorld will be created, so calling this method multiple times * will return the same DynamicsWorld object. * @param[in] config A DynamicsWorldConfig object describing the required capabilities of the dynamics world. @@ -191,13 +210,15 @@ public: DynamicsWorld InitializeDynamics(DynamicsWorldConfig config); /** - * Get a handle to the world object of the dynamics simulation. + * @brief Get a handle to the world object of the dynamics simulation. + * * @return A handle to the world object of the dynamics simulation */ DynamicsWorld GetDynamicsWorld(); /** - * Terminate the dynamics simulation. + * @brief Terminate the dynamics simulation. + * * Calls Actor::DisableDynamics on all dynamics enabled actors, * all handles to any DynamicsBody or DynamicsJoint objects held by applications * will become detached from their actors and the simulation therefore should be discarded. @@ -207,7 +228,8 @@ public: // Rendering /** - * Keep rendering for at least the given amount of time. + * @brief Keep rendering for at least the given amount of time. + * * By default Dali will stop rendering when no Actor positions are being set, and when no animations are running etc. * This method is useful to force screen refreshes e.g. when updating a NativeImage. * @param durationSeconds to keep rendering, 0 means render at least one more frame @@ -217,7 +239,8 @@ public: // Signals /** - * 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 * void YourCallbackName(const KeyEvent& event); @@ -227,14 +250,16 @@ public: KeyEventSignalV2& KeyEventSignal(); /** - * This signal is emitted just after the event processing is finished. + * @brief This signal is emitted just after the event processing is finished. + * * @return The signal to connect to. */ EventProcessingFinishedSignalV2& EventProcessingFinishedSignal(); /** - * This signal is emitted when the screen is touched and when the touch ends + * @brief This signal is emitted when the screen is touched and when the touch ends * (i.e. the down & up touch events only). + * * If there are multiple touch points, then this will be emitted when the first touch occurs and * then when the last finger is lifted. * An interrupted event will also be emitted. @@ -251,7 +276,8 @@ public: public: // Not intended for application developers /** - * This constructor is used by Dali GetCurrent() methods + * @brief This constructor is used by Dali GetCurrent() methods. + * * @param [in] stage A pointer to a Dali resource */ explicit DALI_INTERNAL Stage(Internal::Stage* stage); diff --git a/capi/dali/public-api/common/vector-wrapper.h b/capi/dali/public-api/common/vector-wrapper.h index 0fae668..7ef45ad 100644 --- a/capi/dali/public-api/common/vector-wrapper.h +++ b/capi/dali/public-api/common/vector-wrapper.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_COMMON_MODULE * @{ */ diff --git a/capi/dali/public-api/events/gesture-detector.h b/capi/dali/public-api/events/gesture-detector.h index e5e7f44..d9f8f0f 100644 --- a/capi/dali/public-api/events/gesture-detector.h +++ b/capi/dali/public-api/events/gesture-detector.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_EVENTS_MODULE * @{ */ @@ -37,7 +37,8 @@ class GestureDetector; class Actor; /** - * GestureDetectors analyse a stream of touch events and attempt to determine the intention of the user. + * @brief GestureDetectors analyse a stream of touch events and attempt to determine the intention of the user. + * * An actor is attached to a gesture detector and if the detector recognises a pattern in its analysis, it will * emit a detected signal to the application. * @@ -51,13 +52,16 @@ class GestureDetector : public Handle public: // Creation & Destruction /** - * Create an uninitialized GestureDetector; this can be initialized with one of the derived gestures' New() methods + * @brief Create an uninitialized GestureDetector; this can be initialized with one of the derived gestures' New() methods. + * * Calling member functions with an uninitialized Dali::Object is not allowed. */ GestureDetector(); /** - * Downcast an Object handle to GestureDetector handle. If handle points to a GestureDetector object the + * @brief Downcast an Object handle to GestureDetector handle. + * + * If handle points to a GestureDetector object the * downcast produces valid handle. If not the returned handle is left uninitialized. * @param[in] handle to An object * @return handle to a GestureDetector object or an uninitialized handle @@ -65,7 +69,8 @@ public: // Creation & Destruction static GestureDetector DownCast( BaseHandle handle ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~GestureDetector(); @@ -78,8 +83,10 @@ public: // Creation & Destruction public: // Actor related /** - * Attaches an actor to the gesture. The detected signal will be dispatched when the - * gesture occurs on the attached actor. + * @brief Attaches an actor to the gesture. + * + * The detected signal will be dispatched when the gesture occurs on + * the attached actor. * @note You can attach several actors to a gesture detector. * @param[in] actor The actor to attach to the gesture detector * @pre The gesture detector has been initialized. @@ -87,7 +94,8 @@ public: // Actor related void Attach(Actor actor); /** - * Detaches the attached actor from the gesture detector. + * @brief Detaches the attached actor from the gesture detector. + * * @param[in] actor The actor to detach from the gesture detector. * @pre The gesture detector has been initialized. * @pre The specified actor has been attached to the gesture detector. @@ -95,14 +103,16 @@ public: // Actor related void Detach(Actor actor); /** - * Detaches all the actors that have been attached to the gesture detector. + * @brief Detaches all the actors that have been attached to the gesture detector. + * * @pre The gesture detector has been initialized. * @pre At least one actor has been attached to the gesture detector. */ void DetachAll(); /** - * Returns a vector of actors attached to the gesture detector. + * @brief Returns a vector of actors attached to the gesture detector. + * * @return The attached actor vector. * @pre The gesture detector has been initialized. */ @@ -111,7 +121,8 @@ public: // Actor related protected: /** - * This constructor is used by Dali New() methods of derived classes. + * @brief This constructor is used by Dali New() methods of derived classes. + * * @param [in] internal A pointer to a newly allocated Dali resource. */ explicit DALI_INTERNAL GestureDetector(Internal::GestureDetector* internal); diff --git a/capi/dali/public-api/events/gesture.h b/capi/dali/public-api/events/gesture.h index aa0db31..09c8c70 100644 --- a/capi/dali/public-api/events/gesture.h +++ b/capi/dali/public-api/events/gesture.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_EVENTS_MODULE * @{ */ @@ -29,9 +29,11 @@ namespace Dali DALI_IMPORT_API { /** - * Base structure for different gestures that an application can receive. A gesture is an event - * that is produced from a combination of several touch events in a particular order or within a - * certain time frame (e.g pinch). + * @brief Base structure for different gestures that an application can receive. + * + * A gesture is an event that is produced from a combination of + * several touch events in a particular order or within a certain time + * frame (e.g pinch). * * To receive a particular gesture, the application has to create and connect to the appropriate * GestureDetector. @@ -43,24 +45,25 @@ namespace Dali DALI_IMPORT_API struct Gesture { /** - * Copy constructor + * @brief Copy constructor. */ Gesture( const Gesture& rhs ); /** - * Assignment operator + * @brief Assignment operator. */ Gesture& operator=( const Gesture& rhs ); // Destruction /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~Gesture(); - // Types - + /** + * @brief Type of gesture. + */ enum Type { Pinch = 1 << 0, ///< When two touch points move away or towards each other. @@ -69,6 +72,9 @@ struct Gesture LongPress = 1 << 3 ///< When the user continues to touch the same area on the screen for the device configured time. }; + /** + * @brief State of the gesture. + */ enum State { Clear, ///< There is no state associated with this gesture. @@ -82,25 +88,28 @@ struct Gesture // Data /** - * The gesture type. + * @brief The gesture type. */ Type type; /** - * The gesture state. Please see the description in the sub-classes to see the states used by the - * actual gesture. + * @brief The gesture state. + * + * Please see the description in the sub-classes to see the states + * used by the actual gesture. */ State state; /** - * The time the gesture took place. + * @brief The time the gesture took place. */ unsigned int time; protected: // Creation /** - * This constructor is only used by derived classes. + * @brief This constructor is only used by derived classes. + * * @param[in] gestureType The type of gesture event. * @param[in] gestureState The state of the gesture event. */ diff --git a/capi/dali/public-api/events/key-event.h b/capi/dali/public-api/events/key-event.h index 70dccc6..7d0eeec 100644 --- a/capi/dali/public-api/events/key-event.h +++ b/capi/dali/public-api/events/key-event.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_EVENTS_MODULE * @{ */ @@ -32,33 +32,41 @@ namespace Dali DALI_IMPORT_API { /** - * The key event structure is used to store a key press, it facilitates processing of these key presses - * and passing to other libraries like Toolkit. The keyString is the actual character you might want to display - * while the key name is just a descriptive name. There is a key modifier which relates to keys like alt, shift and control - * functions are supplied to check if they have been pressed. + * @brief The key event structure is used to store a key press. * - * Currently KeyEvent is also being used to relay messages from the IMF keyboard to Core. In future IMF may communicate via its own module. + * It facilitates processing of these key presses and passing to other + * libraries like Toolkit. The keyString is the actual character you + * might want to display while the key name is just a descriptive + * name. There is a key modifier which relates to keys like alt, + * shift and control functions are supplied to check if they have been + * pressed. * + * Currently KeyEvent is also being used to relay messages from the + * IMF keyboard to Core. In future IMF may communicate via its own + * module. */ struct KeyEvent { // Enumerations - // Specifies the state of the key event. + + /** + * @brief Specifies the state of the key event. + */ enum State { - Down, /**< Key down */ - Up, /**< Key up */ - + Down, ///< Key down + Up, ///< Key up Last }; /** - * Default constructor + * @brief Default constructor */ KeyEvent(); /** - * Constructor + * @brief Constructor. + * * @param[in] keyName The name of the key pressed or command from the IMF, if later then the some following parameters will be needed. * @param[in] keyString A string of input characters or key pressed * @param[in] keyCode The unique key code for the key pressed. @@ -69,24 +77,27 @@ struct KeyEvent KeyEvent(const std::string& keyName, const std::string& keyString, int keyCode, int keyModifier, unsigned long timeStamp, const State& keyState); /** - * Destructor + * @brief Destructor. */ ~KeyEvent(); /** - * Check to see if Shift key modifier has been supplied + * @brief Check to see if Shift key modifier has been supplied. + * * @return bool true if shift modifier */ bool IsShiftModifier() const; /** - * Check to see if Ctrl (control) key modifier has been supplied + * @brief Check to see if Ctrl (control) key modifier has been supplied. + * * @return bool true if ctrl modifier */ bool IsCtrlModifier() const; /** - * Check to see if Alt key modifier has been supplied + * @brief Check to see if Alt key modifier has been supplied. + * * @return bool true if alt modifier */ bool IsAltModifier() const; @@ -94,32 +105,33 @@ struct KeyEvent // Data /** - * name given to the key pressed + * @brief name given to the key pressed. */ std::string keyPressedName; /** - * the actual string returned that should be used for input editors. + * @brief The actual string returned that should be used for input editors. */ std::string keyPressed; /** - * keycode for the key pressed. + * @brief Keycode for the key pressed. */ int keyCode; /** - * special keys like shift, alt and control which modify the next key pressed. + * @brief special keys like shift, alt and control which modify the next key pressed. */ int keyModifier; /** - * The time (in ms) that the key event occurred. + * @brief The time (in ms) that the key event occurred. */ unsigned long time; /** - * State of the key event. + * @brief State of the key event. + * * @see State */ State state; diff --git a/capi/dali/public-api/events/long-press-gesture-detector.h b/capi/dali/public-api/events/long-press-gesture-detector.h index d43b833..58c730f 100644 --- a/capi/dali/public-api/events/long-press-gesture-detector.h +++ b/capi/dali/public-api/events/long-press-gesture-detector.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_EVENTS_MODULE * @{ */ @@ -37,10 +37,10 @@ class LongPressGestureDetector; struct LongPressGesture; /** - * This class emits a signals when a long press gesture occurs that meets the requirements set by the - * application. See LongPressGestureDetector::SetTouchesRequired. + * @brief This class emits a signals when a long press gesture occurs that meets the requirements set by the application. + * @see LongPressGestureDetector::SetTouchesRequired. * - * For any valid long press. Two signals will be emitted: + * For any valid long press, two signals will be emitted: * - First identifying the beginning (state = Started) i.e. when fingers held down for the required time. * - Second identifying the ending (state = Finished) i.e. when fingers are released. * @@ -57,28 +57,31 @@ class LongPressGestureDetector : public GestureDetector { public: // Typedefs - typedef SignalV2< void (Actor, LongPressGesture) > DetectedSignalV2; + typedef SignalV2< void (Actor, LongPressGesture) > DetectedSignalV2; ///< Gesture detected signal type //Signal Names - static const char* const SIGNAL_LONG_PRESS_DETECTED; + static const char* const SIGNAL_LONG_PRESS_DETECTED; ///< name "long-press-detected" public: // Creation & Destruction /** - * Create an uninitialized LongPressGestureDetector; this can be initialized with LongPressGestureDetector::New() + * @brief Create an uninitialized LongPressGestureDetector; this can be initialized with LongPressGestureDetector::New(). + * * Calling member functions with an uninitialized Dali::Object is not allowed. */ LongPressGestureDetector(); /** - * Create an initialized LongPressGestureDetector. + * @brief Create an initialized LongPressGestureDetector. + * * By default, this would create a gesture detector that requires only one touch. * @return A handle to a newly allocated Dali resource. */ static LongPressGestureDetector New(); /** - * Create an initialized LongPressGestureDetector with the number of touches required. + * @brief Create an initialized LongPressGestureDetector with the number of touches required. + * * A long press gesture will be emitted from this detector if the number of fingers touching the * screen is equal to the touches required. * @param[in] touchesRequired The number of touches required. @@ -87,7 +90,8 @@ public: // Creation & Destruction static LongPressGestureDetector New(unsigned int touchesRequired); /** - * Create an initialized LongPressGestureDetector with the minimum and maximum number of touches required. + * @brief Create an initialized LongPressGestureDetector with the minimum and maximum number of touches required. + * * A long press gesture will be emitted from this detector if the number of fingers touching the screen * falls between the minimum and maximum touches set. * @param[in] minTouches The minimum number of touches required. @@ -97,7 +101,9 @@ public: // Creation & Destruction static LongPressGestureDetector New(unsigned int minTouches, unsigned int maxTouches); /** - * Downcast an Object handle to LongPressGestureDetector handle. If handle points to a LongPressGestureDetector object the + * @brief Downcast an Object handle to LongPressGestureDetector handle. + * + * If handle points to a LongPressGestureDetector object the * downcast produces valid handle. If not the returned handle is left uninitialized. * @param[in] handle to An object * @return handle to a LongPressGestureDetector object or an uninitialized handle @@ -105,7 +111,8 @@ public: // Creation & Destruction static LongPressGestureDetector DownCast( BaseHandle handle ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~LongPressGestureDetector(); @@ -118,9 +125,12 @@ public: // Creation & Destruction public: // Setters /** - * Set the number of touches required. The number of touches corresponds to the number of fingers - * a user has on the screen. - * This sets the minimum and maximum touches to the input parameter. + * @brief Set the number of touches required. + * + * The number of touches corresponds to the number of fingers a user + * has on the screen. This sets the minimum and maximum touches to + * the input parameter. + * * @param[in] touches Touches required. * @pre The gesture detector has been initialized. * @note The default is '1'. @@ -128,8 +138,11 @@ public: // Setters void SetTouchesRequired(unsigned int touches); /** - * Sets the minimum and maximum touches required. The number of touches corresponds to the number - * of fingers a user has on the screen. + * @brief Sets the minimum and maximum touches required. + * + * The number of touches corresponds to the number of fingers a user + * has on the screen. + * * @param[in] minTouches Minimum Touches required. * @param[in] maxTouches Maximum Touches required. * @pre The gesture detector has been initialized. @@ -140,14 +153,16 @@ public: // Setters public: // Getters /** - * Retrieves the minimum number of touches required. + * @brief Retrieves the minimum number of touches required. + * * @return The minimum number of touches required. * @pre The gesture detector has been initialized. */ unsigned int GetMinimumTouchesRequired() const; /** - * Retrieves the maximum number of touches required. + * @brief Retrieves the maximum number of touches required. + * * @return The maximum number of touches required. * @pre The gesture detector has been initialized. */ @@ -156,7 +171,8 @@ public: // Getters public: // Signals /** - * This signal is emitted when the specified long press is detected on the attached actor. + * @brief This signal is emitted when the specified long press is detected on the attached actor. + * * A callback of the following type may be connected: * @code * void YourCallbackName(Actor actor, LongPressGesture gesture); @@ -169,7 +185,8 @@ public: // Signals 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. */ explicit DALI_INTERNAL LongPressGestureDetector(Internal::LongPressGestureDetector* internal); diff --git a/capi/dali/public-api/events/long-press-gesture.h b/capi/dali/public-api/events/long-press-gesture.h index 5402b25..4ec07e5 100644 --- a/capi/dali/public-api/events/long-press-gesture.h +++ b/capi/dali/public-api/events/long-press-gesture.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_EVENTS_MODULE * @{ */ @@ -30,8 +30,8 @@ namespace Dali DALI_IMPORT_API { /** - * A LongPressGesture is emitted when the user touches and holds the screen with the stated number of - * fingers. + * @brief A LongPressGesture is emitted when the user touches and holds the screen with the stated number of fingers. + * * This gesture can be in one of two states, when the long-press gesture is first detected: "Started"; * and when the long-press gesture ends: "Finished". * @@ -44,42 +44,45 @@ struct LongPressGesture : public Gesture // Construction & Destruction /** - * Constructor + * @brief Constructor + * * @param[in] state The state of the gesture */ LongPressGesture(Gesture::State state); /** - * Copy constructor + * @brief Copy constructor */ LongPressGesture( const LongPressGesture& rhs ); /** - * Assignment operator + * @brief Assignment operator */ LongPressGesture& operator=( const LongPressGesture& rhs ); /** - * Virtual destructor + * @brief Virtual destructor */ virtual ~LongPressGesture(); // Data /** - * The number of touch points in this long press gesture, i.e. the number of fingers the user had + * @brief The number of touch points in this long press gesture, i.e. the number of fingers the user had * on the screen to generate the long press gesture. */ unsigned int numberOfTouches; /** - * This is the point, in screen coordinates, where the long press occurred. + * @brief This is the point, in screen coordinates, where the long press occurred. + * * If a multi-touch long press, then this is the centroid of all the touch points. */ Vector2 screenPoint; /** - * This is the point, in local actor coordinates, where the long press occurred. + * @brief This is the point, in local actor coordinates, where the long press occurred. + * * If a multi-touch long press, then this is the centroid of all the touch points. * @return The point where tap has occurred (in local actor coordinates). */ diff --git a/capi/dali/public-api/events/pan-gesture-detector.h b/capi/dali/public-api/events/pan-gesture-detector.h index a8369e2..a1e7166 100644 --- a/capi/dali/public-api/events/pan-gesture-detector.h +++ b/capi/dali/public-api/events/pan-gesture-detector.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_EVENTS_MODULE * @{ */ @@ -39,8 +39,9 @@ class PanGestureDetector; struct PanGesture; /** - * This class looks for panning (or dragging) gestures. The user will be pressing one or more fingers on - * an actor while they pan it. + * @brief This class looks for panning (or dragging) gestures. + * + * The user will be pressing one or more fingers on an actor while they pan it. * * The application programmer can use this gesture detector as follows: * @code @@ -59,23 +60,23 @@ class PanGestureDetector : public GestureDetector public: // Typedefs // Signals - typedef SignalV2< void (Actor, PanGesture) > DetectedSignalV2; + typedef SignalV2< void (Actor, PanGesture) > DetectedSignalV2; ///< Pan gesture detected signal type // Signal Names - static const char* const SIGNAL_PAN_DETECTED; + static const char* const SIGNAL_PAN_DETECTED; ///< name "pan-detected" // Directional Pan - typedef std::pair< Radian, Radian > AngleThresholdPair; - typedef std::vector< AngleThresholdPair > AngleContainer; + typedef std::pair< Radian, Radian > AngleThresholdPair; ///< Range of angles for a direction + typedef std::vector< AngleThresholdPair > AngleContainer; ///< Group of angular thresholds for all directions - static const Radian DIRECTION_LEFT; // For a left pan (-PI Radians). - static const Radian DIRECTION_RIGHT; // For a right pan (0 Radians). - static const Radian DIRECTION_UP; // For an up pan (-0.5 * PI Radians). - static const Radian DIRECTION_DOWN; // For a down pan (0.5 * PI Radians). - static const Radian DIRECTION_HORIZONTAL; // For a left and right pan (PI Radians). Useful for AddDirection(). - static const Radian DIRECTION_VERTICAL; // For an up and down pan (-0.5 * PI Radians). Useful for AddDirection(). + static const Radian DIRECTION_LEFT; ///< For a left pan (-PI Radians). + static const Radian DIRECTION_RIGHT; ///< For a right pan (0 Radians). + static const Radian DIRECTION_UP; ///< For an up pan (-0.5 * PI Radians). + static const Radian DIRECTION_DOWN; ///< For a down pan (0.5 * PI Radians). + static const Radian DIRECTION_HORIZONTAL; ///< For a left and right pan (PI Radians). Useful for AddDirection(). + static const Radian DIRECTION_VERTICAL; ///< For an up and down pan (-0.5 * PI Radians). Useful for AddDirection(). - static const Radian DEFAULT_THRESHOLD; // The default threshold is PI * 0.25 radians (or 45 degrees). + static const Radian DEFAULT_THRESHOLD; ///< The default threshold is PI * 0.25 radians (or 45 degrees). // Default Properties static const Property::Index SCREEN_POSITION; ///< name "screen-position", type VECTOR2 @@ -86,19 +87,23 @@ public: // Typedefs public: // Creation & Destruction /** - * Create an uninitialized PanGestureDetector; this can be initialized with PanGestureDetector::New() + * @brief Create an uninitialized PanGestureDetector; this can be initialized with PanGestureDetector::New(). + * * Calling member functions with an uninitialized Dali::Object is not allowed. */ PanGestureDetector(); - /* - * Create an initialized PanGestureDetector. + /** + * @brief Create an initialized PanGestureDetector. + * * @return A handle to a newly allocated Dali resource. */ static PanGestureDetector New(); /** - * Downcast an Object handle to PanGestureDetector handle. If handle points to a PanGestureDetector object the + * @brief Downcast an Object handle to PanGestureDetector handle. + * + * If handle points to a PanGestureDetector object the * downcast produces valid handle. If not the returned handle is left uninitialized. * @param[in] handle to An object * @return handle to a PanGestureDetector object or an uninitialized handle @@ -106,7 +111,8 @@ public: // Creation & Destruction static PanGestureDetector DownCast( BaseHandle handle ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~PanGestureDetector(); @@ -119,7 +125,8 @@ public: // Creation & Destruction public: // Setters /** - * This is the minimum number of touches required for the pan gesture to be detected. + * @brief This is the minimum number of touches required for the pan gesture to be detected. + * * @param[in] minimum Minimum touches required. * @pre The gesture detector has been initialized. * @note The default minimum is '1'. @@ -127,7 +134,8 @@ public: // Setters void SetMinimumTouchesRequired(unsigned int minimum); /** - * This is the maximum number of touches required for the pan gesture to be detected. + * @brief This is the maximum number of touches required for the pan gesture to be detected. + * * @param[in] maximum Maximum touches required. * @pre The gesture detector has been initialized. * @note The default maximum is '1'. @@ -137,14 +145,16 @@ public: // Setters public: // Getters /** - * Retrieves the minimum number of touches required for the pan gesture to be detected. + * @brief Retrieves the minimum number of touches required for the pan gesture to be detected. + * * @return The minimum touches required. * @pre The gesture detector has been initialized. */ unsigned int GetMinimumTouchesRequired() const; /** - * Retrieves the maximum number of touches required for the pan gesture to be detected. + * @brief Retrieves the maximum number of touches required for the pan gesture to be detected. + * * @return The maximum touches required. * @pre The gesture detector has been initialized. */ @@ -153,8 +163,7 @@ public: // Getters public: // Directional Panning /** - * The pan gesture is only emitted if the pan occurs in the direction specified by this method - * with a +/- threshold allowance. + * @brief The pan gesture is only emitted if the pan occurs in the direction specified by this method with a +/- threshold allowance. * * The angle is from -180 -> 0 -> 180 degrees (or -M_PI -> 0 -> M_PI in radians) i.e: * @@ -188,7 +197,8 @@ public: // Directional Panning void AddAngle( Radian angle, Radian threshold = DEFAULT_THRESHOLD ); /** - * A helper method for adding bi-directional angles where the pan should take place. + * @brief A helper method for adding bi-directional angles where the pan should take place. + * * In other words, if 0 is requested, then PI will also be added so that we have both left and * right scrolling. * @@ -208,21 +218,25 @@ public: // Directional Panning void AddDirection( Radian direction, Radian threshold = DEFAULT_THRESHOLD ); /** - * Returns the container of all the angles this pan gesture detector emits a signal. + * @brief Returns the container of all the angles this pan gesture detector emits a signal. + * * @return a const reference to the container of all the angles. * @pre The gesture detector has been initialized. */ const AngleContainer& GetAngles() const; /** - * Clears any directional angles that are used by the gesture detector. After this, the pan gesture + * @brief Clears any directional angles that are used by the gesture detector. + * + * After this, the pan gesture * will be emitted for a pan in ANY direction. * @pre The gesture detector has been initialized. */ void ClearAngles(); /** - * Removes the angle specified from the container. + * @brief Removes the angle specified from the container. + * * @param[in] angle The angle to remove. * @pre The gesture detector has been initialized. * @note This will only remove the first instance of the angle found from the container. @@ -232,7 +246,8 @@ public: // Directional Panning void RemoveAngle( Radian angle ); /** - * Removes the two angles that make up the direction from the container. + * @brief Removes the two angles that make up the direction from the container. + * * @param[in] direction The direction to remove. * @pre The gesture detector has been initialized. * @note If a direction outside the range in AddAngle() is given, then the value is wrapped within @@ -243,7 +258,8 @@ public: // Directional Panning public: // Signals /** - * This signal is emitted when the pan gesture is detected on the attached actor. + * @brief This signal is emitted when the pan gesture is detected on the attached actor. + * * A callback of the following type may be connected: * @code * void YourCallbackName(Actor actor, PanGesture gesture); @@ -256,7 +272,8 @@ public: // Signals public: // Pan Properties Setters /** - * Allows setting of the pan properties that are returned in constraints. + * @brief Allows setting of the pan properties that are returned in constraints. + * * @param[in] pan The pan gesture to set. *@note If a normal pan is taking place, then any value set is ignored. */ @@ -265,7 +282,8 @@ public: // Pan Properties Setters 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. */ explicit DALI_INTERNAL PanGestureDetector(Internal::PanGestureDetector* internal); diff --git a/capi/dali/public-api/events/pan-gesture.h b/capi/dali/public-api/events/pan-gesture.h index 6206d2f..ab65f03 100644 --- a/capi/dali/public-api/events/pan-gesture.h +++ b/capi/dali/public-api/events/pan-gesture.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_EVENTS_MODULE * @{ */ @@ -30,7 +30,8 @@ namespace Dali DALI_IMPORT_API { /** - * A PanGesture is emitted when the user moves one or more fingers in a particular direction. + * @brief A PanGesture is emitted when the user moves one or more fingers in a particular direction. + * * This gesture can be in one of three states, when the pan gesture is first detected: "Started"; * when the pan gesture is continuing: "Continuing"; and finally, when the pan gesture ends: * "Finished". @@ -48,30 +49,32 @@ struct PanGesture: public Gesture // Construction & Destruction /** - * Default Constructor + * @brief Default Constructor. + * * @param[in] state The state of the gesture */ PanGesture(Gesture::State state); /** - * Copy constructor + * @brief Copy constructor. */ PanGesture( const PanGesture& rhs ); /** - * Assignment operator + * @brief Assignment operator. */ PanGesture& operator=( const PanGesture& rhs ); /** - * Virtual destructor + * @brief Virtual destructor. */ virtual ~PanGesture(); // Data /** - * The velocity at which the user is moving their fingers. + * @brief The velocity at which the user is moving their fingers. + * * This is represented as a Vector2 and is the pixel movement per millisecond. * A positive x value shows that the user is panning to the right, a negative x value means the opposite. * A positive y value shows that the user is panning downwards, a negative y values means upwards. @@ -80,8 +83,9 @@ struct PanGesture: public Gesture Vector2 velocity; /** - * This is a Vector2 showing how much the user has panned (dragged) since the last pan gesture or, + * @brief This is a Vector2 showing how much the user has panned (dragged) since the last pan gesture or, * if the gesture has just started, then the amount panned since the user touched the screen. + * * A positive x value shows that the user is panning to the right, a negative x value means the opposite. * A positive y value shows that the user is panning downwards, a negative y value means upwards. * This value is in local actor coordinates, the actor being the one attached to the @@ -90,12 +94,13 @@ struct PanGesture: public Gesture Vector2 displacement; /** - * This current touch position of the primary touch point in local actor coordinates. + * @brief This current touch position of the primary touch point in local actor coordinates. */ Vector2 position; /** - * The velocity at which the user is moving their fingers. + * @brief The velocity at which the user is moving their fingers. + * * This is represented as a Vector2 and is the pixel movement per millisecond. * A positive x value shows that the user is panning to the right, a negative x value means the opposite. * A positive y value shows that the user is panning downwards, a negative y values means upwards. @@ -104,8 +109,9 @@ struct PanGesture: public Gesture Vector2 screenVelocity; /** - * This is a Vector2 showing how much the user has panned (dragged) since the last pan gesture or, + * @brief This is a Vector2 showing how much the user has panned (dragged) since the last pan gesture or, * if the gesture has just started, then the amount panned since the user touched the screen. + * * A positive x value shows that the user is panning to the right, a negative x value means the opposite. * A positive y value shows that the user is panning downwards, a negative y value means upwards. * This value is in screen coordinates. @@ -113,43 +119,47 @@ struct PanGesture: public Gesture Vector2 screenDisplacement; /** - * This current touch position of the primary touch point in screen coordinates. + * @brief This current touch position of the primary touch point in screen coordinates. */ Vector2 screenPosition; /** - * The total number of fingers touching the screen in a pan gesture. + * @brief The total number of fingers touching the screen in a pan gesture. */ unsigned int numberOfTouches; // Convenience Methods /** - * Returns the speed at which the user is moving their fingers. + * @brief Returns the speed at which the user is moving their fingers. + * * This is the pixel movement per millisecond. * @return The speed of the pan (in pixels per millisecond). */ float GetSpeed() const; /** - * This returns the distance the user has panned (dragged) since the last pan gesture or, + * @brief This returns the distance the user has panned (dragged) since the last pan gesture or, * if the gesture has just started, then the distance moved since the user touched the screen. + * * This is always a positive value. * @return The distance, as a float, a user's finger has panned. */ float GetDistance() const; /** - * Returns the speed at which the user is moving their fingers relative to screen coordinates. + * @brief Returns the speed at which the user is moving their fingers relative to screen coordinates. + * * This is the pixel movement per millisecond. * @return The speed of the pan (in pixels per millisecond). */ float GetScreenSpeed() const; /** - * This returns the distance the user has panned (dragged) since the last pan gesture in screen + * @brief This returns the distance the user has panned (dragged) since the last pan gesture in screen * coordinates or, if the gesture has just started, then the distance in screen coordinates moved * since the user touched the screen. + * * This is always a positive value. * @return The distance, as a float, a user's finger has panned. */ diff --git a/capi/dali/public-api/events/pinch-gesture-detector.h b/capi/dali/public-api/events/pinch-gesture-detector.h index 3d1fc5f..a0df0fe 100644 --- a/capi/dali/public-api/events/pinch-gesture-detector.h +++ b/capi/dali/public-api/events/pinch-gesture-detector.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_EVENTS_MODULE * @{ */ @@ -37,8 +37,11 @@ class PinchGestureDetector; struct PinchGesture; /** - * This class looks for pinching gestures involving two touches. It tries to detect when the user moves two - * touch points towards or away from each other. Please see PinchGesture for more information. + * @brief This class looks for pinching gestures involving two touches. + * + * It tries to detect when the user moves two touch points towards or + * away from each other. Please see PinchGesture for more + * information. * * The application programmer can use this gesture detector as follows: * @code @@ -53,27 +56,34 @@ class PinchGestureDetector : public GestureDetector { public: // Typedefs + /** + * @brief Signal type. + */ typedef SignalV2< void (Actor, PinchGesture) > DetectedSignalV2; //Signal Names - static const char* const SIGNAL_PINCH_DETECTED; + static const char* const SIGNAL_PINCH_DETECTED; ///< name "pinch-detected" public: // Creation & Destruction /** - * Create an uninitialized PinchGestureDetector; this can be initialized with PinchGestureDetector::New() + * @brief Create an uninitialized PinchGestureDetector; this can be initialized with PinchGestureDetector::New(). + * * Calling member functions with an uninitialized Dali::Object is not allowed. */ PinchGestureDetector(); - /* - * Create an initialized PinchGestureDetector. + /** + * @brief Create an initialized PinchGestureDetector. + * * @return A handle to a newly allocated Dali resource. */ static PinchGestureDetector New(); /** - * Downcast an Object handle to PinchGestureDetector handle. If handle points to a PinchGestureDetector object the + * @brief Downcast an Object handle to PinchGestureDetector handle. + * + * If handle points to a PinchGestureDetector object the * downcast produces valid handle. If not the returned handle is left uninitialized. * @param[in] handle to An object * @return handle to a PinchGestureDetector object or an uninitialized handle @@ -81,7 +91,8 @@ public: // Creation & Destruction static PinchGestureDetector DownCast( BaseHandle handle ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~PinchGestureDetector(); @@ -94,7 +105,8 @@ public: // Creation & Destruction public: // Signals /** - * This signal is emitted when the pinch gesture is detected on the attached actor. + * @brief This signal is emitted when the pinch gesture is detected on the attached actor. + * * A callback of the following type may be connected: * @code * void YourCallbackName(Actor actor, PinchGesture gesture); @@ -107,7 +119,8 @@ public: // Signals 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. */ explicit DALI_INTERNAL PinchGestureDetector(Internal::PinchGestureDetector* internal); diff --git a/capi/dali/public-api/events/pinch-gesture.h b/capi/dali/public-api/events/pinch-gesture.h index 48131bc..483e1b9 100644 --- a/capi/dali/public-api/events/pinch-gesture.h +++ b/capi/dali/public-api/events/pinch-gesture.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_EVENTS_MODULE * @{ */ @@ -30,7 +30,8 @@ namespace Dali DALI_IMPORT_API { /** - * A PinchGesture is emitted when the user moves two fingers towards or away from each other. + * @brief A PinchGesture is emitted when the user moves two fingers towards or away from each other. + * * This gesture can be in one of three states; when the pinch gesture is first detected, its * state is set to "Started". After this, if there is change in the gesture, the state will * be "Continuing". Finally, when the gesture ends, the state of the gesture changes to @@ -44,47 +45,52 @@ struct PinchGesture: public Gesture // Construction & Destruction /** - * Default Constructor + * @brief Default Constructor. + * * @param[in] state The state of the gesture */ PinchGesture(Gesture::State state); /** - * Copy constructor + * @brief Copy constructor. */ PinchGesture( const PinchGesture& rhs ); /** - * Assignment operator + * @brief Assignment operator. */ PinchGesture& operator=( const PinchGesture& rhs ); /** - * Virtual destructor + * @brief Virtual destructor. */ virtual ~PinchGesture(); // Data /** - * The scale factor from the start of the pinch gesture till the latest pinch gesture. If the user - * is moving their fingers away from each other, then this value increases. Conversely, if the - * user is moving their fingers towards each other, this value will decrease. + * @brief The scale factor from the start of the pinch gesture till the latest pinch gesture. + * + * If the user is moving their fingers away from each other, then + * this value increases. Conversely, if the user is moving their + * fingers towards each other, this value will decrease. */ float scale; /** - * The speed at which the user is moving their fingers. This is the pixel movement per second. + * @brief The speed at which the user is moving their fingers. + * + * This is the pixel movement per second. */ float speed; /** - * The center point of the two points that caused the pinch gesture in screen coordinates. + * @brief The center point of the two points that caused the pinch gesture in screen coordinates. */ Vector2 screenCenterPoint; /** - * The center point of the two points that caused the pinch gesture in local actor coordinates. + * @brief The center point of the two points that caused the pinch gesture in local actor coordinates. */ Vector2 localCenterPoint; }; diff --git a/capi/dali/public-api/events/tap-gesture-detector.h b/capi/dali/public-api/events/tap-gesture-detector.h index ec42325..925e161 100644 --- a/capi/dali/public-api/events/tap-gesture-detector.h +++ b/capi/dali/public-api/events/tap-gesture-detector.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_EVENTS_MODULE * @{ */ @@ -37,8 +37,10 @@ class TapGestureDetector; struct TapGesture; /** - * This class emits a signal when a tap gesture occurs that meets the requirements set by the - * application. See TapGestureDetector::SetTapsRequired and TapGestureDetector::SetTouchesRequired. + * @brief This class emits a signal when a tap gesture occurs that meets the requirements set by the + * application. + * + * See TapGestureDetector::SetTapsRequired and TapGestureDetector::SetTouchesRequired. * * A Tap Gesture is a discrete gesture, which means it does not have any state information attached * to it. Please see TapGesture for more information. @@ -56,28 +58,34 @@ class TapGestureDetector : public GestureDetector { public: // Typedefs + /** + * @brief Signal type for detected signal. + */ typedef SignalV2< void (Actor, TapGesture) > DetectedSignalV2; //Signal Names - static const char* const SIGNAL_TAP_DETECTED; + static const char* const SIGNAL_TAP_DETECTED; ///< name "tap-detected" public: // Creation & Destruction /** - * Create an uninitialized TapGestureDetector; this can be initialized with TapGestureDetector::New() + * @brief Create an uninitialized TapGestureDetector; this can be initialized with TapGestureDetector::New(). + * * Calling member functions with an uninitialized Dali::Object is not allowed. */ TapGestureDetector(); /** - * Create an initialized TapGestureDetector. + * @brief Create an initialized TapGestureDetector. + * * By default, this would create a gesture detector which requires one tap with one touch. * @return A handle to a newly allocated Dali resource. */ static TapGestureDetector New(); /** - * Create an initialized TapGestureDetector with the specified parameters. + * @brief Create an initialized TapGestureDetector with the specified parameters. + * * @param[in] tapsRequired The number of taps required. * @param[in] touchesRequired The number of touches required. * @return A handle to a newly allocated Dali resource. @@ -85,7 +93,9 @@ public: // Creation & Destruction static TapGestureDetector New(unsigned int tapsRequired, unsigned int touchesRequired); /** - * Downcast an Object handle to TapGestureDetector handle. If handle points to a TapGestureDetector object the + * @brief Downcast an Object handle to TapGestureDetector handle. + * + * If handle points to a TapGestureDetector object the * downcast produces valid handle. If not the returned handle is left uninitialized. * @param[in] handle to An object * @return handle to a TapGestureDetector object or an uninitialized handle @@ -93,7 +103,8 @@ public: // Creation & Destruction static TapGestureDetector DownCast( BaseHandle handle ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~TapGestureDetector(); @@ -106,8 +117,9 @@ public: // Creation & Destruction public: // Setters /** - * Set the number of taps required. The tap count is the number of times a user should "tap" the - * screen. + * @brief Set the number of taps required. + * + * The tap count is the number of times a user should "tap" the screen. * @param[in] taps Taps required. * @pre The gesture detector has been initialized. * @note The default is '1'. @@ -115,8 +127,9 @@ public: // Setters void SetTapsRequired(unsigned int taps); /** - * Set the number of touches required. The number of touches corresponds to the number of fingers - * a user has on the screen. + * @brief Set the number of touches required. + * + * The number of touches corresponds to the number of fingers a user has on the screen. * @param[in] touches Touches required. * @pre The gesture detector has been initialized. * @note The default is '1'. @@ -126,14 +139,16 @@ public: // Setters public: // Getters /** - * Retrieves the number of taps required. + * @brief Retrieves the number of taps required. + * * @return The taps required. * @pre The gesture detector has been initialized. */ unsigned int GetTapsRequired() const; /** - * Retrieves the number of touches required. + * @brief Retrieves the number of touches required. + * * @return The number of touches required. * @pre The gesture detector has been initialized. */ @@ -142,7 +157,8 @@ public: // Getters public: // Signals /** - * This signal is emitted when the specified tap is detected on the attached actor. + * @brief This signal is emitted when the specified tap is detected on the attached actor. + * * A callback of the following type may be connected: * @code * void YourCallbackName(Actor actor, TapGesture gesture); @@ -155,7 +171,8 @@ public: // Signals 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. */ explicit DALI_INTERNAL TapGestureDetector(Internal::TapGestureDetector* internal); diff --git a/capi/dali/public-api/events/tap-gesture.h b/capi/dali/public-api/events/tap-gesture.h index 4d65457..27a7ef5 100644 --- a/capi/dali/public-api/events/tap-gesture.h +++ b/capi/dali/public-api/events/tap-gesture.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_EVENTS_MODULE * @{ */ @@ -30,8 +30,9 @@ namespace Dali DALI_IMPORT_API { /** - * A TapGesture is emitted when the user taps the screen with the stated number of fingers a stated - * number of times. This is a discrete gesture so does not have any state information. + * @brief A TapGesture is emitted when the user taps the screen with the stated number of fingers a stated number of times. + * + * This is a discrete gesture so does not have any state information. * @see TapGestureDetector */ struct TapGesture : public Gesture @@ -39,46 +40,48 @@ struct TapGesture : public Gesture // Construction & Destruction /** - * Default Constructor + * @brief Default Constructor */ TapGesture(); /** - * Copy constructor + * @brief Copy constructor */ TapGesture( const TapGesture& rhs ); /** - * Assignment operator + * @brief Assignment operator */ TapGesture& operator=( const TapGesture& rhs ); /** - * Virtual destructor + * @brief Virtual destructor */ virtual ~TapGesture(); // Data /** - * The number of taps in this tap gesture. + * @brief The number of taps in this tap gesture. */ unsigned int numberOfTaps; /** - * The number of touch points in this tap gesture, i.e. the number of fingers the user had on the + * @brief The number of touch points in this tap gesture, i.e. the number of fingers the user had on the * screen to generate the tap gesture. */ unsigned int numberOfTouches; /** - * This is the point, in screen coordinates, where the tap occurred. + * @brief This is the point, in screen coordinates, where the tap occurred. + * * If a multi-touch tap, then this is the centroid of all the touch points. */ Vector2 screenPoint; /** - * This is the point, in local actor coordinates, where the tap occurred. + * @brief This is the point, in local actor coordinates, where the tap occurred. + * * If a multi-touch tap, then this is the centroid of all the touch points. * @return The point where tap has occurred (in local actor coordinates). */ diff --git a/capi/dali/public-api/events/touch-event.h b/capi/dali/public-api/events/touch-event.h index 1b7abf5..a55055e 100644 --- a/capi/dali/public-api/events/touch-event.h +++ b/capi/dali/public-api/events/touch-event.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_EVENTS_MODULE * @{ */ @@ -29,12 +29,13 @@ namespace Dali DALI_IMPORT_API { -typedef std::vector TouchPointContainer; -typedef TouchPointContainer::iterator TouchPointContainerIterator; -typedef TouchPointContainer::const_iterator TouchPointContainerConstIterator; +typedef std::vector TouchPointContainer; ///< Container of touch points. +typedef TouchPointContainer::iterator TouchPointContainerIterator; ///< Iterator for Dali::TouchPointContainer +typedef TouchPointContainer::const_iterator TouchPointContainerConstIterator; ///< Const iterator for Dali::TouchPointContainer /** - * Touch events are a collection of touch points at a specific moment in time. + * @brief Touch events are a collection of touch points at a specific moment in time. + * * When a multi-touch event occurs, each touch point represents the points that are currently being * touched or the points where a touch has stopped. */ @@ -43,44 +44,49 @@ struct DALI_IMPORT_API TouchEvent // Construction & Destruction /** - * Default constructor + * @brief Default constructor */ TouchEvent(); /** - * Constructor + * @brief Constructor * @param[in] time The time the event occurred */ TouchEvent(unsigned long time); /** - * Destructor + * @brief Destructor */ ~TouchEvent(); // Data /** - * This is a container of points for this touch event. The first point in the set is always the + * @brief This is a container of points for this touch event. + * + * The first point in the set is always the * primary touch point (i.e. the first point touched in a multi-touch event). */ TouchPointContainer points; /** - * The time (in ms) that the touch event occurred. + * @brief The time (in ms) that the touch event occurred. */ unsigned long time; // Convenience Methods /** - * Returns the total number of points in this TouchEvent. + * @brief Returns the total number of points in this TouchEvent. + * * @return Total number of Points. */ unsigned int GetPointCount() const; /** - * Returns a touch point at the index requested. The first point in the set is always the primary + * @brief Returns a touch point at the index requested. + * + * The first point in the set is always the primary * touch point (i.e. the first point touched in a multi-touch event). * @note "point" should be less than the value returned by GetPointCount(). * If out of range, then program asserts. diff --git a/capi/dali/public-api/events/touch-point.h b/capi/dali/public-api/events/touch-point.h index 052d610..a66b28b 100644 --- a/capi/dali/public-api/events/touch-point.h +++ b/capi/dali/public-api/events/touch-point.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_EVENTS_MODULE * @{ */ @@ -30,13 +30,16 @@ namespace Dali DALI_IMPORT_API { /** - * A TouchPoint represents a point on the screen that is currently being touched or where touch - * has stopped. + * @brief A TouchPoint represents a point on the screen that is currently being touched + * or where touch has stopped. */ struct TouchPoint { // Enumerations + /** + * @brief Touch state + */ enum State { Down, /**< Screen touched */ @@ -47,13 +50,14 @@ struct TouchPoint all points are sent but indicates that this particular point has not changed since the last time */ Interrupted, /**< A system event has occurred which has interrupted the touch event sequence. */ - Last + Last /**< Number of states. */ }; // Construction & Destruction /** - * Constructor + * @brief Constructor + * * @param[in] id The touch device ID. * @param[in] state The state. * @param[in] screenX The X co-ordinate relative to the screen's origin. @@ -62,7 +66,8 @@ struct TouchPoint TouchPoint(int id, State state, float screenX, float screenY); /** - * Constructor + * @brief Constructor + * * @param[in] id The touch device ID. * @param[in] state The state. * @param[in] screenX The X co-ordinate relative to the screen's origin. @@ -73,30 +78,32 @@ struct TouchPoint TouchPoint(int id, State state, float screenX, float screenY, float localX, float localY); /** - * Destructor + * @brief Destructor */ ~TouchPoint(); // Data /** - * Each touch point has a unique device ID which specifies the touch device for that point. + * @brief Each touch point has a unique device ID which specifies the touch device for that point. */ int deviceId; /** - * State of the point. + * @brief State of the point. + * * @see State */ State state; /** - * The actor that was underneath the touch point. + * @brief The actor that was underneath the touch point. */ Actor hitActor; /** - * The co-ordinates relative to the top-left of the hit-actor + * @brief The co-ordinates relative to the top-left of the hit-actor. + * * @note The top-left of an actor is (0.0, 0.0, 0.5). * @note If you require the local coordinates of another actor (e.g the parent of the hit actor), * then you should use Actor::ScreenToLocal(). @@ -104,7 +111,7 @@ struct TouchPoint Vector2 local; /** - * The co-ordinates relative to the top-left of the screen. + * @brief The co-ordinates relative to the top-left of the screen. */ Vector2 screen; }; diff --git a/capi/dali/public-api/geometry/animatable-mesh.h b/capi/dali/public-api/geometry/animatable-mesh.h index 4d000cc..0b8eaf7 100644 --- a/capi/dali/public-api/geometry/animatable-mesh.h +++ b/capi/dali/public-api/geometry/animatable-mesh.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_GEOMETRY_MODULE * @{ */ @@ -38,28 +38,34 @@ class AnimatableMesh; } /** - * An animatable mesh can have any of its vertices animated using Dali's animation and + * @brief An animatable mesh can have any of its vertices animated using Dali's animation and * constraint systems. + * * It is recommended that the vertices of the mesh remain in the bounds -0.5 - 0.5, which * will match the actor size boundaries. The origin of the mesh matches the actor's position. */ class AnimatableMesh : public Constrainable { public: + /** + * @brief Vector of face indices. + */ typedef std::vector Faces; - typedef Faces::iterator FacesIter; - typedef Faces::const_iterator FacesConstIter; + typedef Faces::iterator FacesIter; ///< Iterator for Dali::AnimatableMesh::Faces + typedef Faces::const_iterator FacesConstIter; ///< Const Iterator for Dali::AnimatableMesh::Faces /** - * Create an uninitialized handle, this can be initialized with New(). + * @brief Create an uninitialized handle, this can be initialized with New(). + * * Calling member functions on an uninitialized handle will result * in an assertion */ AnimatableMesh(); /** - * Create a new animatable mesh with a given number of vertices - * and triangles. This will assert if any index is out of range. + * @brief Create a new animatable mesh with a given number of vertices and triangles. + * + * This will assert if any index is out of range. * Using this constructor enables the vertex color property. * AnimatableMesh does not take ownership of the faceIndices. * @param[in] numVertices The number of vertices in the mesh @@ -71,8 +77,9 @@ public: const Faces& faceIndices ); /** - * Create a new animatable mesh with a given number of vertices - * and triangles. This will assert if any index is out of range. + * @brief Create a new animatable mesh with a given number of vertices and triangles. + * + * This will assert if any index is out of range. * Using this constructor disables the vertex color property. * AnimatableMesh does not take ownership of the faceIndices. * @param[in] numVertices The number of vertices in the mesh @@ -86,9 +93,11 @@ public: Dali::Material material ); /** - * Downcast an Object handle to AnimatableMesh. If the handle points - * to an AnimatableMesh objec, the downcast produces a valid - * handle. If not, the handle is left uninitialized. + * @brief Downcast an Object handle to AnimatableMesh. + * + * If the handle points to an AnimatableMesh objec, the downcast + * produces a valid handle. If not, the handle is left + * uninitialized. * * @param[in] handle to an Object * @return handle to an AnimatableMesh or an uninitialized handle @@ -96,12 +105,13 @@ public: static AnimatableMesh DownCast( BaseHandle handle ); /** - * Destructor + * @brief Destructor */ virtual ~AnimatableMesh(); /** - * Get the number of vertices with which this mesh was created. + * @brief Get the number of vertices with which this mesh was created. + * * @return number of vertices in this mesh */ unsigned int GetNumberOfVertices() const; @@ -112,7 +122,7 @@ public: using BaseHandle::operator=; /** - * Array subscript operator overload. + * @brief Array subscript operator overload. * * @pre The vertex index is in range * @param[in] index subscript @@ -121,7 +131,8 @@ public: AnimatableVertex operator[]( unsigned int index ) const; /** - * Get a property index for a given vertex + * @brief Get a property index for a given vertex. + * * @pre The vertex index and property is in range * @param[in] vertex The vertex * @param[in] property The vertex attribute @@ -130,7 +141,7 @@ public: Property::Index GetPropertyIndex( unsigned int vertex, Property::Index property) const; /** - * Get the property for a given vertex. + * @brief Get the property for a given vertex. * * @pre The vertex index and property is in range * @param[in] vertex The vertex @@ -142,7 +153,8 @@ public: public: // Not for use by application developer /** - * This constructor is used by Dali New() methods + * @brief This constructor is used by Dali New() methods + * * @param [in] mesh A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL AnimatableMesh(Internal::AnimatableMesh* mesh); diff --git a/capi/dali/public-api/geometry/animatable-vertex.h b/capi/dali/public-api/geometry/animatable-vertex.h index f75a848..f339a43 100644 --- a/capi/dali/public-api/geometry/animatable-vertex.h +++ b/capi/dali/public-api/geometry/animatable-vertex.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_GEOMETRY_MODULE * @{ */ @@ -39,8 +39,10 @@ class AnimatableMesh; } /** - * Represents a vertex in an AnimatableMesh. It is used by AnimatableMesh - * to offer an array interface for setting properties: + * @brief Represents a vertex in an AnimatableMesh. + * + * It is used by AnimatableMesh to offer an array interface for + * setting properties: * * @code * AnimatableMesh mesh = AnimatableMesh(numVerts, faces); @@ -57,42 +59,47 @@ public: static const Property::Index TEXTURE_COORDS; ///< Property 2, name prefix "texture-coords-", type VECTOR2 /** - * Destructor + * @brief Destructor */ ~AnimatableVertex(); /** - * Set the position of the vertex. + * @brief Set the position of the vertex. + * * @param[in] position (note, -0.5 - +0.5 are inside the actor's boundaries) */ void SetPosition(const Vector3& position); /** - * Set the vertex color + * @brief Set the vertex color. * @param[in] color The vertex color */ void SetColor(const Vector4& color); /** - * Set the texture coordinates + * @brief Set the texture coordinates. + * * @param[in] textureCoords The texture coordinates */ void SetTextureCoords(const Vector2& textureCoords); /** - * Get the current position of the vertex. + * @brief Get the current position of the vertex. + * * @return position */ Vector3 GetCurrentPosition(); /** - * Get the current vertex color + * @brief Get the current vertex color. + * * @return The vertex color */ Vector4 GetCurrentColor(); /** - * Get the current texture coordinates + * @brief Get the current texture coordinates. + * * @return textureCoords The texture coordinates */ Vector2 GetCurrentTextureCoords(); @@ -102,18 +109,19 @@ private: friend class Dali::AnimatableMesh; /** - * Constructor + * @brief Constructor. + * * @param[in] vertex The index of the vertex in the parent mesh * @param[in] mesh The parent mesh */ AnimatableVertex( unsigned int vertex, AnimatableMesh mesh ); /** - * Undefined Copy Constructor + * @brief Undefined Copy Constructor */ AnimatableVertex(const AnimatableVertex& vertex); - int mVertex; //< The index of this vertex in the parent mesh + int mVertex; ///< The index of this vertex in the parent mesh Internal::AnimatableMesh& mMesh; ///< The parent mesh }; diff --git a/capi/dali/public-api/images/bitmap-image.h b/capi/dali/public-api/images/bitmap-image.h index 5813dc8..810a3e9 100644 --- a/capi/dali/public-api/images/bitmap-image.h +++ b/capi/dali/public-api/images/bitmap-image.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_IMAGES_MODULE * @{ */ @@ -40,7 +40,7 @@ typedef Rect RectArea; ///< rectangular area (x,y,w,h) /** - * BitmapImage represents an image resource that can be added to ImageActors. + * @brief BitmapImage represents an image resource that can be added to ImageActors. * Its pixel buffer data is provided by the application developer. * * Care should be taken with pixel data allocated by the application, @@ -70,13 +70,15 @@ class BitmapImage : public Image { public: /** - * Constructor which creates an uninitialized BitmapImage object. + * @brief Constructor which creates an uninitialized BitmapImage object. + * * Use Image::New(...) to create an initialised object. */ BitmapImage(); /** - * Create a new BitmapImage. + * @brief Create a new BitmapImage. + * * Also a pixel buffer for image data is allocated. * Dali has ownership of the buffer. * For better performance and portability use power of two dimensions. @@ -87,13 +89,15 @@ public: * @param [in] width image width in pixels * @param [in] height image height in pixels * @param [in] pixelformat the pixel format (rgba 32 bit by default) + * @return a handle to a new instance of BitmapImage */ static BitmapImage New(unsigned int width, unsigned int height, Pixel::Format pixelformat=Pixel::RGBA8888); /** - * Create a new BitmapImage. + * @brief Create a new BitmapImage. + * * Also a pixel buffer for image data is allocated. * Dali has ownership of the buffer. * For better performance and portability use power of two dimensions. @@ -105,6 +109,7 @@ public: * @param [in] pixelFormat The pixel format * @param [in] loadPolicy Controls time of loading a resource from the filesystem. * @param [in] releasePolicy Optionally release memory when image is not visible on screen. + * @return a handle to a new instance of BitmapImage */ static BitmapImage New(unsigned int width, unsigned int height, @@ -113,7 +118,8 @@ public: ReleasePolicy releasePolicy); /** - * Create a new BitmapImage, which uses an external data source. + * @brief Create a new BitmapImage, which uses an external data source. + * * The PixelBuffer has to be allocated by application. * * The application holds ownership of the buffer. It must not @@ -130,6 +136,7 @@ public: * @param [in] height image height in pixels * @param [in] pixelFormat the pixel format (rgba 32 bit by default) * @param [in] stride the internal stride of the pixelbuffer in pixels + * @return a handle to a new instance of BitmapImage */ static BitmapImage New(PixelBuffer* pixelBuffer, unsigned int width, @@ -138,7 +145,8 @@ public: unsigned int stride=0); /** - * Create a new BitmapImage, which uses an external data source. + * @brief Create a new BitmapImage, which uses an external data source. + * * The PixelBuffer has to be allocated by application. * * The application holds ownership of the buffer. It must not @@ -159,6 +167,7 @@ public: * @param [in] pixelFormat the pixel format * @param [in] stride the internal stride of the pixelbuffer in pixels * @param [in] releasePolicy optionally relase memory when image is not visible on screen. + * @return a handle to a new instance of BitmapImage */ static BitmapImage New(PixelBuffer* pixelBuffer, unsigned int width, @@ -168,15 +177,18 @@ public: ReleasePolicy releasePolicy); /** - * Downcast an Object handle to BitmapImage. If handle points to a BitmapImage the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to BitmapImage. + * + * If handle points to a BitmapImage the downcast produces valid + * handle. If not the returned handle is left uninitialized. + * * @param[in] handle to An object * @return handle to a BitmapImage or an uninitialized handle */ static BitmapImage DownCast( BaseHandle handle ); /** - * Destructor. + * @brief Destructor. */ virtual ~BitmapImage(); @@ -186,15 +198,18 @@ public: using BaseHandle::operator=; /** - * White pixel as image data. Can be used to create solid color actors. + * @brief White pixel as image data. + * + * Can be used to create solid color actors. * @return 1 white pixel with 32 bit colordepth */ static const BitmapImage WHITE(); public: /** - * Returns the pixel buffer of the Image. The application can write - * to the buffer to modify its contents. + * @brief Returns the pixel buffer of the Image. + * + * The application can write to the buffer to modify its contents. * * Whilst the image is on stage, after writing to the buffer the * application should call Update() and wait for the @@ -205,19 +220,22 @@ public: PixelBuffer* GetBuffer(); /** - * Returns buffer size in bytes. + * @brief Returns buffer size in bytes. + * * @return the buffer size in bytes */ unsigned int GetBufferSize() const; /** - * Returns buffer stride (in bytes). + * @brief Returns buffer stride (in bytes). + * * @return the buffer stride */ unsigned int GetBufferStride() const; /** - * Inform Dali that the contents of the buffer have changed. + * @brief Inform Dali that the contents of the buffer have changed. + * * SignalUploaded will be sent in response if the image is on stage * and the image data has been successfully copied to graphics * memory. To avoid visual tearing, the application should wait for @@ -227,7 +245,7 @@ public: * image after calling this method until the SignalUploaded has been * successfully received. * - * @note: BitmapImage::BufferUpdated might not work with BGR/BGRA formats! + * @note: BitmapImage::Update might not work with BGR/BGRA formats! * @note: Some GPUs may not support Non power of two buffer updates (for * example C110/SGX540) */ @@ -240,7 +258,8 @@ public: void Update( RectArea updateArea ); /** - * Returns whether BitmapImage uses external data source or not. + * @brief Returns whether BitmapImage uses external data source or not. + * * If not, dali holds ownership of the PixelBuffer, otherwise the application * is responsible for freeing it. * diff --git a/capi/dali/public-api/images/encoded-buffer-image.h b/capi/dali/public-api/images/encoded-buffer-image.h index afe774f..3d995d2 100644 --- a/capi/dali/public-api/images/encoded-buffer-image.h +++ b/capi/dali/public-api/images/encoded-buffer-image.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_IMAGES_MODULE * @{ */ @@ -38,7 +38,7 @@ class EncodedBufferImage; /** - * EncodedBufferImage represents an image resource that can be added to + * @brief EncodedBufferImage represents an image resource that can be added to * ImageActors. * * A memory buffer of encoded image data is provided by the application and @@ -66,13 +66,15 @@ class EncodedBufferImage : public Image { public: /** - * Constructor which creates an uninitialized EncodedBufferImage object. + * @brief Constructor which creates an uninitialized EncodedBufferImage object. + * * Use Image::New(...) to create an initialised object. */ EncodedBufferImage(); /** - * Create an initialised image object from an encoded image buffer in memory. + * @brief Create an initialised image object from an encoded image buffer in memory. + * * The image will be created eagerly using LoadPolicy::Immediate. * The function is non-blocking and returns immediately while the image * decoding happens on a background thread. @@ -92,7 +94,8 @@ public: static EncodedBufferImage New(const uint8_t * const encodedImage, std::size_t encodedImageByteCount, const ImageAttributes& attributes, ReleasePolicy releasePol = Image::Never); /** - * Create an initialised image object from an encoded image buffer in memory. + * @brief Create an initialised image object from an encoded image buffer in memory. + * * The image will be created eagerly using LoadPolicy::Immediate. * The function is non-blocking and returns immediately while the image * decoding happens on a background thread. @@ -108,7 +111,9 @@ public: static EncodedBufferImage New(const uint8_t * const encodedImage, std::size_t encodedImageByteCount); /** - * Downcast an Object handle to EncodedBufferImage. If handle points to a EncodedBufferImage the + * @brief Downcast an Object handle to EncodedBufferImage. + * + * If handle points to a EncodedBufferImage the * downcast produces valid handle. If not the returned handle is left uninitialized. * @param[in] handle to An object * @return handle to a EncodedBufferImage or an uninitialized handle @@ -116,7 +121,7 @@ public: static EncodedBufferImage DownCast( BaseHandle handle ); /** - * Destructor. + * @brief Destructor. */ ~EncodedBufferImage(); diff --git a/capi/dali/public-api/images/frame-buffer-image.h b/capi/dali/public-api/images/frame-buffer-image.h index edc5530..57dad07 100644 --- a/capi/dali/public-api/images/frame-buffer-image.h +++ b/capi/dali/public-api/images/frame-buffer-image.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_IMAGES_MODULE * @{ */ @@ -35,9 +35,8 @@ class FrameBufferImage; } /** - * FrameBufferImage represents a GLES Frame Buffer Object and contains the result - * of an 'off screen' render pass of a Layer. Call Layer::SetOffscreenImage to enable - * offscreen rendering for that layer. + * @brief FrameBufferImage represents a GLES Frame Buffer Object and contains the result + * of an 'off screen' render pass of a RenderTask. * The FrameBufferImage can then be used with an ImageActor (with optional shader * effects) and rendered to the screen. */ @@ -45,24 +44,28 @@ class FrameBufferImage : public Image { public: /** - * Constructor which creates an uninitialized FrameBufferImage object. + * @brief Constructor which creates an uninitialized FrameBufferImage object. + * * Use Image::New(...) to create an initialised object. */ FrameBufferImage(); /** - * Create a new FrameBufferImage. + * @brief Create a new FrameBufferImage. + * * The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE. * The ReleasePolicy defaults to Dali::Image::Never. * @param [in] width The width in pixels. Setting to zero will use the width of the stage. * @param [in] height The height in pixels. Setting to zero will use the height of the stage. * @param [in] pixelformat The pixel format (rgba 32 bit by default) * @post When the FrameBufferImage is first used as a render target, an exception may be thrown if pixelFormat is not supported on the hardware platform. + * @return A handle to a new instance of a FrameBufferImage. */ static FrameBufferImage New(unsigned int width = 0, unsigned int height = 0, Pixel::Format pixelformat = Pixel::RGBA8888); /** - * Create a new FrameBufferImage. + * @brief Create a new FrameBufferImage. + * * The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE. * @param [in] width The width in pixels. Setting to zero will use the width of the stage. * @param [in] height The height in pixels. Setting to zero will use the height of the stage. @@ -73,11 +76,13 @@ public: * it, or it is being used as an input (e.g. ShaderEffect / ImageActor). * * @post When the FrameBufferImage is first used as a render target, an exception may be thrown if pixelFormat is not supported on the hardware platform. + * @return A handle to a new instance of a FrameBufferImage. */ static FrameBufferImage New(unsigned int width, unsigned int height, Pixel::Format pixelformat, ReleasePolicy releasePolicy ); /** - * Create a new FrameBufferImage. + * @brief Create a new FrameBufferImage. + * * The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE. * @param [in] image The native image. * @@ -85,11 +90,13 @@ public: * it, or it is being used as an input (e.g. ShaderEffect / ImageActor). * * @post When the FrameBufferImage is first used as a render target, an exception may be thrown if the NativeImage cannot be mapped to a texture. + * @return A handle to a new instance of a FrameBufferImage. */ static FrameBufferImage New(NativeImage& image); /** - * Create a new FrameBufferImage. + * @brief Create a new FrameBufferImage. + * * The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE. * @param [in] image The native image. * @param [in] releasePolicy The ReleasePolicy to apply to the FrameBufferImage. @@ -98,11 +105,14 @@ public: * it, or it is being used as an input (e.g. ShaderEffect / ImageActor). * * @post When the FrameBufferImage is first used as a render target, an exception may be thrown if the NativeImage cannot be mapped to a texture. + * @return A handle to a new instance of a FrameBufferImage. */ static FrameBufferImage New(NativeImage& image, ReleasePolicy releasePolicy); /** - * Downcast an Object handle to FrameBufferImage handle. If handle points to a FrameBufferImage object the + * @brief Downcast an Object handle to FrameBufferImage handle. + * + * If handle points to a FrameBufferImage object the * downcast produces valid handle. If not the returned handle is left uninitialized. * @param[in] handle to An object * @return handle to a FrameBufferImage object or an uninitialized handle @@ -110,7 +120,7 @@ public: static FrameBufferImage DownCast( BaseHandle handle ); /** - * Destructor. + * @brief Destructor. */ virtual ~FrameBufferImage(); diff --git a/capi/dali/public-api/images/image-attributes.h b/capi/dali/public-api/images/image-attributes.h index b695772..011b3e7 100644 --- a/capi/dali/public-api/images/image-attributes.h +++ b/capi/dali/public-api/images/image-attributes.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_IMAGES_MODULE * @{ */ @@ -33,7 +33,7 @@ namespace Dali DALI_IMPORT_API class ImageAttributes; /** - * Describes Image properties like width or pixel format. + * @brief Describes Image properties like width or pixel format. * ImageAttributes are used to request specific details when loading an image. * Loading a scaled-down version of a JPEG image can be done by requesting width and height values that are * smaller than the image's natural size. The requested values are taken into consideration but @@ -45,7 +45,7 @@ class ImageAttributes public: /** - * Scaling options, meant for thumbnail loading. + * @brief Scaling options, meant for thumbnail loading. */ enum ScalingMode { @@ -55,39 +55,43 @@ public: FitHeight ///< thumbnail fills whole height, width is scaled to maintain aspect ratio }; - static const ImageAttributes DEFAULT_ATTRIBUTES; + static const ImageAttributes DEFAULT_ATTRIBUTES; ///< Default attributes have no size /** - * Default constructor, initializes to default values. + * @brief Default constructor, initializes to default values. */ ImageAttributes(); /** - * This copy constructor is required for correctly copying internal implementation + * @brief This copy constructor is required for correctly copying internal implementation. + * * @param [in] rhs A reference to the copied handle */ ImageAttributes(const ImageAttributes& rhs); /** - * This assignment operator is required for correctly handling the internal implementation + * @brief This assignment operator is required for correctly handling the internal implementation. + * * @param [in] rhs A reference to the copied handle + * @return a reference to this object */ ImageAttributes& operator=(const ImageAttributes& rhs); /** - * Default destructor, + * @brief Default destructor. */ ~ImageAttributes(); /** - * Create an initialised image attributes object + * @brief Create an initialised image attributes object. * * @return A handle to a newly allocated object */ static ImageAttributes New(); /** - * Create an initialised image attributes object + * @brief Create an initialised image attributes object. + * * @param [in] width desired width. * @param [in] height desired height * @param [in] format desired pixelformat @@ -96,15 +100,15 @@ public: static ImageAttributes New(unsigned int width, unsigned int height, Pixel::Format format); /** - * Create an initialised image attributes object for distance field generation - * Using default parameters. + * @brief Create an initialised image attributes object for distance field generation + * using default parameters. * * @return A handle to a newly allocated object */ static ImageAttributes NewDistanceField(); /** - * Create an initialised image attributes object for distance field generation + * @brief Create an initialised image attributes object for distance field generation. * * @param [in] fieldRadius The minimum search radius to check for differing pixels * @param [in] fieldBorder The amount of distancefield cells to add around the data (for glow/shadow effects) @@ -113,7 +117,8 @@ public: static ImageAttributes NewDistanceField(float fieldRadius, int fieldBorder); /** - * Set the size properties + * @brief Set the size properties. + * * By default width and height are set to zero which means the image loaded has the original size. * @param [in] width desired width. * @param [in] height desired height @@ -121,28 +126,31 @@ public: void SetSize(unsigned int width, unsigned int height); /** - * Set the size properties + * @brief Set the size properties. + * * By default width and height are set to zero which means the image loaded has the original size. * @param [in] size desired size. */ void SetSize( const Size& size ); /** - * Set the pixelformat field of the image attributes + * @brief Set the pixelformat field of the image attributes. + * * By default is set to Pixel::RGBA8888. * @param [in] format desired pixelformat */ void SetPixelFormat(Pixel::Format format); /** - * Set the scale field of the image attributes. + * @brief Set the scale field of the image attributes. + * * By default, ShrinkToFit is set. * @param [in] scalingMode The desired scaling mode */ void SetScalingMode(ScalingMode scalingMode); /** - * Set the desired cropping for the attribute + * @brief Set the desired cropping for the attribute. * * Cropping options, relative to image actual size. * (0.0, 0.0) is top left corner, (1.0, 1.0) is the full width and height @@ -154,8 +162,9 @@ public: void SetCrop(const Rect& cropRect); /** - * Set whether the image will be rotated/flipped back into portrait - * orientation. This will only be necessary if metadata indicates that the + * @brief Set whether the image will be rotated/flipped back into portrait orientation. + * + * This will only be necessary if metadata indicates that the * image has a different viewing orientation. * * This metadata, optionally present in formats that use exif for example, @@ -173,118 +182,132 @@ public: /** - * Return the width currently represented by the attribute + * @brief Return the width currently represented by the attribute. * * @return width */ unsigned int GetWidth() const; /** - * Return the height currently represented by the attribute + * @brief Return the height currently represented by the attribute. * * @return height */ unsigned int GetHeight() const; /** - * Return the size currently represented by the attribute + * @brief Return the size currently represented by the attribute. * * @return size */ Size GetSize() const; /** - * Return the pixel format currently represented by the attribute + * @brief Return the pixel format currently represented by the attribute. * * @return pixel format */ Pixel::Format GetPixelFormat() const; /** - * Return the scale currently represented by the attribute + * @brief Return the scale currently represented by the attribute. * * @return scale */ ScalingMode GetScalingMode() const; /** - * Return if the attribute set up as a distance field + * @brief Return if the attribute set up as a distance field. * * @return true, if the attribute is a distance field. */ bool IsDistanceField() const; /** - * Return the field border currently represented by the attribute + * @brief Return the field border currently represented by the attribute. * * @return field border */ int GetFieldBorder() const; /** - * Return the field search radius currently represented by the attribute + * @brief Return the field search radius currently represented by the attribute. * * @return field radius */ float GetFieldRadius() const; /** - * Return the crop currently represented by the attribute + * @brief Return the crop currently represented by the attribute. * * @return crop */ const Rect& GetCrop() const; /** + * @brief Whether to correct for physical orientation of an image. + * * @return Whether image pixels should be transformed according to the * orientation metadata, if any. */ bool GetOrientationCorrection() const; /** - * Less then comparison operator. + * @brief Less then comparison operator. + * * @param [in] a parameter tested * @param [in] b parameter tested + * @return true if a is less than b */ friend bool operator<(const ImageAttributes& a, const ImageAttributes& b); /** - * Equal to comparison operator. + * @brief Equal to comparison operator. + * * @param [in] a parameter tested for equality * @param [in] b parameter tested for equality + * @return true if a is equal to b */ friend bool operator==(const ImageAttributes& a, const ImageAttributes& b); /** - * Not equal to comparison operator. + * @brief Not equal to comparison operator. + * * @param [in] a parameter tested for equality * @param [in] b parameter tested for equality + * @return true if a is not equal to b */ friend bool operator!=(const ImageAttributes& a, const ImageAttributes& b); private: struct ImageAttributesImpl; - ImageAttributesImpl* impl; + ImageAttributesImpl* impl; ///< Implementation pointer }; /** - * Less then comparison operator. + * @brief Less then comparison operator. + * * @param [in] a parameter tested * @param [in] b parameter tested + * @return true if a is less than b */ bool operator<(const ImageAttributes& a, const ImageAttributes& b); /** - * Equal to comparison operator. + * @brief Equal to comparison operator. + * * @param [in] a parameter tested for equality * @param [in] b parameter tested for equality + * @return true if a is equal to b */ bool operator==(const ImageAttributes& a, const ImageAttributes& b); /** - * Not equal to comparison operator. + * @brief Not equal to comparison operator. + * * @param [in] a parameter tested for equality * @param [in] b parameter tested for equality + * @return true if a is not equal to b */ bool operator!=(const ImageAttributes& a, const ImageAttributes& b); diff --git a/capi/dali/public-api/images/image.h b/capi/dali/public-api/images/image.h index 9d8ea1a..8fef159 100644 --- a/capi/dali/public-api/images/image.h +++ b/capi/dali/public-api/images/image.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_IMAGES_MODULE * @{ */ @@ -45,7 +45,8 @@ class ImageAttributes; /** - * Image object represents an image resource that can be added to ImageActors. + * @brief An Image object represents an image resource that can be added to ImageActors. + * * Image objects can also handle custom requests for image loading and are responsible for * the underlying resource's lifetime. * @@ -102,11 +103,11 @@ class Image : public BaseHandle { public: /** - * Resource management options. + * @brief Resource management options. */ /** - * LoadPolicy controls the way images are loaded into memory. + * @brief LoadPolicy controls the way images are loaded into memory. */ enum LoadPolicy { @@ -115,7 +116,7 @@ public: }; /** - * ReleasePolicy controls the way images are deleted from memory. + * @brief ReleasePolicy controls the way images are deleted from memory. */ enum ReleasePolicy { @@ -123,30 +124,39 @@ public: Never ///< keep image data for the lifetime of the object. (default) }; + /** + * @brief Type of signal for LoadingFinished and Uploaded. + */ typedef SignalV2< void (Image) > ImageSignalV2; // Signal Names - static const char* const SIGNAL_IMAGE_LOADING_FINISHED; - static const char* const SIGNAL_IMAGE_UPLOADED; + static const char* const SIGNAL_IMAGE_LOADING_FINISHED; ///< Name of LoadingFinished signal + static const char* const SIGNAL_IMAGE_UPLOADED; ///< Name of Uploaded signal public: /** - * Get the size of an image from disc. This function will read the header info from - * file on disc and is synchronous, so it should not be used repeatedly or in tight loops. + * @brief Get the size of an image from disk. + * + * This function will read the header info from file on disk and is + * synchronous, so it should not be used repeatedly or in tight + * loops. + * * @param [in] filename of the image file to use. * @return The width and height in pixels of the image. */ static Vector2 GetImageSize(const std::string filename); /** - * Constructor which creates an empty Image object. + * @brief Constructor which creates an empty Image object. + * * Use Image::New(...) to create an initialised object. */ Image(); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~Image(); @@ -157,14 +167,16 @@ public: using BaseHandle::operator=; /** - * Create an initialised image object + * @brief Create an initialised image object. + * * @param [in] filename The filename of the image file to use. * @return A handle to a newly allocated object */ static Image New(const std::string& filename); /** - * Create an initialised image object + * @brief Create an initialised image object. + * * @param [in] filename The filename of the image file to use. * @param [in] loadPol The LoadPolicy to apply when loading the image resource. * @param [in] releasePol The ReleasePolicy to apply to Image. @@ -173,7 +185,8 @@ public: static Image New(const std::string& filename, LoadPolicy loadPol, ReleasePolicy releasePol); /** - * Create an initialised image object + * @brief Create an initialised image object. + * * @param [in] filename The filename of the image file to use. * @param [in] attributes Requested parameters for loading (size, cropping etc.). * @return A handle to a newly allocated object @@ -181,7 +194,8 @@ public: static Image New(const std::string& filename, const ImageAttributes& attributes); /** - * Create an initialised image object + * @brief Create an initialised image object. + * * @param [in] filename The filename of the image file to use. * @param [in] attributes Requested parameters for loading (size, cropping etc.). * @param [in] loadPol The LoadPolicy to apply when loading the image resource. @@ -191,14 +205,16 @@ public: static Image New(const std::string& filename, const ImageAttributes& attributes, LoadPolicy loadPol, ReleasePolicy releasePol); /** - * Create an initialised image object + * @brief Create an initialised image object. + * * @param [in] filename The filename of the image file to use. * @return A handle to a newly allocated object */ static Image NewDistanceField(const std::string& filename); /** - * Create an initialised image object + * @brief Create an initialised image object. + * * @param [in] filename The filename of the image file to use. * @param [in] loadPol The LoadPolicy to apply when loading the image resource. * @param [in] releasePol The ReleasePolicy to apply to Image. @@ -207,7 +223,8 @@ public: static Image NewDistanceField(const std::string& filename, LoadPolicy loadPol, ReleasePolicy releasePol); /** - * Create an initialised image object + * @brief Create an initialised image object. + * * @param [in] filename The filename of the image file to use. * @param [in] attributes The minimum search radius to check for differing pixels * @return A handle to a newly allocated object @@ -215,7 +232,8 @@ public: static Image NewDistanceField(const std::string& filename, const ImageAttributes& attributes ); /** - * Create an initialised image object + * @brief Create an initialised image object. + * * @param [in] filename The filename of the image file to use. * @param [in] attributes The minimum search radius to check for differing pixels * @param [in] loadPol The LoadPolicy to apply when loading the image resource. @@ -225,8 +243,9 @@ public: static Image NewDistanceField(const std::string& filename, const ImageAttributes& attributes, LoadPolicy loadPol, ReleasePolicy releasePol); /** - * Creates object with already loaded NativeImage - * the maximum size of the image is limited by GL_MAX_TEXTURE_SIZE + * @brief Creates object with already loaded NativeImage. + * + * The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE * @pre nativeImg should be initialised * @param [in] nativeImg already initialised NativeImage * @return A handle to a newly allocated object @@ -234,8 +253,9 @@ public: static Image New(NativeImage& nativeImg); /** - * Creates object with already loaded NativeImage - * the maximum size of the image is limited by GL_MAX_TEXTURE_SIZE + * @brief Creates object with already loaded NativeImage. + * + * The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE * @pre nativeImg should be initialised * @param [in] nativeImg already initialised NativeImage * @param [in] loadPol The LoadPolicy to apply when allocating the GL resource. @@ -245,7 +265,9 @@ public: static Image New(NativeImage& nativeImg, LoadPolicy loadPol, ReleasePolicy releasePol); /** - * Downcast an Object handle to Image handle. If handle points to a Image object the + * @brief Downcast an Object handle to Image handle. + * + * If handle points to a Image object the * downcast produces valid handle. If not the returned handle is left uninitialized. * @param[in] handle to An object * @return handle to a Image object or an uninitialized handle @@ -253,7 +275,8 @@ public: static Image DownCast( BaseHandle handle ); /** - * Query whether the image data has loaded. + * @brief Query whether the image data has loaded. + * * The asynchronous loading begins when the Image object is created. * After the Image object is discarded, the image data will be released from memory. * @return The loading state, either Loading, Success or Failed. @@ -261,32 +284,36 @@ public: LoadingState GetLoadingState() const; /** - * Returns the filename of the image if the image is created from a file + * @brief Returns the filename of the image if the image is created from a file. + * * @return the image filename or empty string */ std::string GetFilename() const; /** - * Return load policy + * @brief Return load policy. + * * @return resource load policy */ LoadPolicy GetLoadPolicy () const; /** - * Return resource release policy + * @brief Return resource release policy. + * * @return resource release policy */ ReleasePolicy GetReleasePolicy () const; /** - * Reload image from filesystem. + * @brief Reload image from filesystem. + * * The set ImageAttributes are used when requesting the image again. * @note if Image is offstage and OnDemand policy is set, reload request is ignored. */ void Reload(); /** - * Returns the width of the image. + * @brief Returns the width of the image. * * Only to be used after the image has finished loading. * (Ticket's LoadingSucceeded callback was called) @@ -298,7 +325,7 @@ public: unsigned int GetWidth() const; /** - * Returns the height of the image. + * @brief Returns the height of the image. * * Only to be used after the image has finished loading. * (Ticket's LoadingSucceeded callback was called) @@ -310,7 +337,8 @@ public: unsigned int GetHeight() const; /** - * Get the attributes of an image. + * @brief Get the attributes of an image. + * * Only to be used after the image has finished loading. * (Ticket's LoadingSucceeded callback was called) * The returned value will reflect the true image dimensions once the asynchronous loading has finished. @@ -323,14 +351,16 @@ public: public: // Signals /** - * Emitted when the image data loads successfully, or when the loading fails. + * @brief Emitted when the image data loads successfully, or when the loading fails. + * * @return A signal object to Connect() with. */ ImageSignalV2& LoadingFinishedSignal(); /** - * This signal is emitted when the image data gets uploaded to - * GL. It Will be sent after an actor using the image is added to + * @brief This signal is emitted when the image data gets uploaded to GL. + * + * It Will be sent after an actor using the image is added to * the stage, when such a staged image is reloaded, or when a staged * BitmapImage calls Update(). * @return A signal object to Connect() with. diff --git a/capi/dali/public-api/images/native-image.h b/capi/dali/public-api/images/native-image.h index 07f72b3..65da3ec 100644 --- a/capi/dali/public-api/images/native-image.h +++ b/capi/dali/public-api/images/native-image.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_IMAGES_MODULE * @{ */ @@ -30,14 +30,17 @@ namespace Dali DALI_IMPORT_API { /** - * Abstract interface. Platform specific native support for handling image data. (EGL, GLX etc.) + * @brief Abstract interface to provide platform-specific support for handling image data. + * + * For example, an implementation could use EGL extensions, etc. */ class NativeImage : public Dali::RefObject { public: /** - * Create the GL resource for the NativeImage. + * @brief Create the GL resource for the NativeImage. + * * e.g. For the EglImageKHR extension, this corresponds to calling eglCreateImageKHR() * @pre There is a GL context for the current thread. * @return false If the initialization fails. @@ -45,40 +48,46 @@ public: virtual bool GlExtensionCreate() = 0; /** - * Destroy the GL resource for the NativeImage. + * @brief Destroy the GL resource for the NativeImage. + * * e.g. For the EglImageKHR extension, this corresponds to calling eglDestroyImageKHR() * @pre There is a GL context for the current thread. */ virtual void GlExtensionDestroy() = 0; /** - * Use the NativeImage as a texture for rendering + * @brief Use the NativeImage as a texture for rendering. + * * @pre There is a GL context for the current thread. * @return A GL error code */ virtual unsigned int TargetTexture() = 0; /** - * Called in each NativeTexture::Bind() call to allow implementation specific operations. + * @brief Called in each NativeTexture::Bind() call to allow implementation specific operations. + * * The correct texture sampler has already been bound before the function gets called. * @pre glAbstraction is being used by context in current thread */ virtual void PrepareTexture() = 0; /** - * Returns the width of the NativeImage + * @brief Returns the width of the NativeImage. + * * @return width */ virtual unsigned int GetWidth() const = 0; /** - * Returns the height of the NativeImage + * @brief Returns the height of the NativeImage. + * * @return height */ virtual unsigned int GetHeight() const = 0; /** - * Returns the internal pixel NativeImage::PixelFormat of the NativeImage + * @brief Returns the internal pixel NativeImage::PixelFormat of the NativeImage. + * * @return pixel format */ virtual Pixel::Format GetPixelFormat() const = 0; @@ -86,7 +95,8 @@ public: protected: /** - * A reference counted object may only be deleted by calling Unreference(). + * @brief A reference counted object may only be deleted by calling Unreference(). + * * The implementation should destroy the NativeImage resources. */ virtual ~NativeImage() @@ -94,6 +104,9 @@ protected: } }; +/** + * @brief Pointer to Dali::NativeImage + */ typedef IntrusivePtr NativeImagePtr; } // namespace Dali diff --git a/capi/dali/public-api/images/pixel.h b/capi/dali/public-api/images/pixel.h index 5a9dc39..8bd11dc 100644 --- a/capi/dali/public-api/images/pixel.h +++ b/capi/dali/public-api/images/pixel.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_IMAGES_MODULE * @{ */ @@ -29,12 +29,15 @@ namespace Dali DALI_IMPORT_API { /** - * Pixel format types and their properties. + * @brief Pixel format types and their properties. */ namespace Pixel { - -/// @note: BitmapImage::BufferUpdated might not work with BGR/BGRA formats! +/** + * @brief Pixel formats + * + * @note: BitmapImage::Update might not work with BGR/BGRA formats! + */ enum Format ///< pixel format, default color depth is RGBA 32 bit with alpha { // Start at > 0 to distinguish null data: @@ -69,31 +72,40 @@ enum Format ///< pixel format, default color depth is RGBA 32 bit with alpha ///! Update LAST_VALID_PIXEL_FORMAT below if you add an enum value here. }; -/** For asserting that a variable has a valid pixel format. - * Sync it to the first value above. */ +/** + * @brief For asserting that a variable has a valid pixel format. + * + * Sync it to the first value above. + */ const Format FIRST_VALID_PIXEL_FORMAT = A8; -/** For asserting that a variable has a valid pixel format. - * Sync it to the last value above. */ +/** + * @brief For asserting that a variable has a valid pixel format. + * + * Sync it to the last value above. + */ const Format LAST_VALID_PIXEL_FORMAT = COMPRESSED_RGB_PVRTC_4BPPV1; /** - * Whether specified pixel format contains an alpha value + * @brief Whether specified pixel format contains an alpha value. + * * @param [in] pixelformat pixel format * @return true if format has alpha, false otherwise */ bool HasAlpha(Format pixelformat); /** - * Returns The number of bytes per pixel for the specified pixel format + * @brief Returns The number of bytes per pixel for the specified pixel format. + * * @param [in] pixelFormat The pixel format * @return The number of bytes per pixel */ unsigned int GetBytesPerPixel(Format pixelFormat); /** - * Returns the offset of the byte containing the alpha mask from the start of the pixel data + * @brief Returns the offset of the byte containing the alpha mask from the start of the pixel data * and the bitmask of that byte to get the alpha value. + * * Bitmask is zero if the pixelFormat does not support alpha * @param[in] pixelFormat * @param[out] byteOffset the byte offset diff --git a/capi/dali/public-api/math/angle-axis.h b/capi/dali/public-api/math/angle-axis.h index 201fa06..455a5a6 100644 --- a/capi/dali/public-api/math/angle-axis.h +++ b/capi/dali/public-api/math/angle-axis.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_MATH_MODULE * @{ */ @@ -32,31 +32,37 @@ namespace Dali DALI_IMPORT_API struct Radian; /** - * An angle & axis pair. + * @brief An angle & axis pair. + * + * This is slightly easier to understand than quaternions for handling rotations + * of objects. Both elements should be non-zero to correctly describe a rotation. */ struct DALI_IMPORT_API AngleAxis { /** - * Create an angle-axis pair. + * @brief Create an angle-axis pair. + * */ AngleAxis(); /** - * Create an angle-axis pair. + * @brief Create an angle-axis pair. + * * @param[in] initialAngle The initial angle in degrees. * @param[in] initialAxis The initial axis. */ AngleAxis( Degree initialAngle, Vector3 initialAxis ); /** - * Create an angle-axis pair. + * @brief Create an angle-axis pair. + * * @param[in] initialAngle The initial angle in radians. * @param[in] initialAxis The initial axis. */ AngleAxis( Radian initialAngle, Vector3 initialAxis ); - Degree angle; - Vector3 axis; + Degree angle; ///< The angle in degrees + Vector3 axis; ///< The axis }; } // namespace Dali diff --git a/capi/dali/public-api/math/compile-time-assert.h b/capi/dali/public-api/math/compile-time-assert.h index 98127c4..76a7d4c 100644 --- a/capi/dali/public-api/math/compile-time-assert.h +++ b/capi/dali/public-api/math/compile-time-assert.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_MATH_MODULE * @{ */ @@ -31,13 +31,14 @@ namespace Dali DALI_IMPORT_API { -template struct CompileTimeAssertBool; -template <> struct CompileTimeAssertBool {}; +template struct CompileTimeAssertBool; ///< Bool Template to test condition +template <> struct CompileTimeAssertBool {}; ///< Specialize for true, but not for false -template struct CompileTimeAssertInt {}; +template struct CompileTimeAssertInt {}; ///< Template to wrap conditional template CompileTimeAsserBool /** - * Use DALI_COMPILE_TIME_ASSERT to test expressions at compile time. + * @brief Use DALI_COMPILE_TIME_ASSERT to test expressions at compile time. + * * If x is false, then 'sizeof' will be attempted with incomplete type. */ #define DALI_COMPILE_TIME_ASSERT( x ) typedef CompileTimeAssertInt< sizeof( CompileTimeAssertBool< ( x ) > ) > CompileTimeAssertType diff --git a/capi/dali/public-api/math/compile-time-math.h b/capi/dali/public-api/math/compile-time-math.h index a03449d..a497a2d 100644 --- a/capi/dali/public-api/math/compile-time-math.h +++ b/capi/dali/public-api/math/compile-time-math.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_MATH_MODULE * @{ */ @@ -31,7 +31,8 @@ namespace Dali DALI_IMPORT_API { /** - * Compile time template to calculate base to the power of N + * @brief Compile time template to calculate base to the power of N. + * * Note! values need to be compile time constants * Usage: Power< 10, 2 >::value; // value=100 * @param mantissa to raise to exponent @@ -44,7 +45,8 @@ struct Power }; /** - * Compile time template to calculate base to the power of N + * @brief Compile time template to calculate base to the power of N. + * * Specialisation for power of 1 * @param mantissa to raise to exponent */ @@ -55,7 +57,8 @@ struct Power< mantissa, 1 > }; /** - * Compile time template to calculate base to the power of N + * @brief Compile time template to calculate base to the power of N. + * * Specialisation for power of 0 * @param mantissa to raise to exponent */ @@ -66,7 +69,8 @@ struct Power< mantissa, 0 > }; /** - * Compile time template to calculate base logarithm of N + * @brief Compile time template to calculate base logarithm of N. + * * Note! values need to be compile time constants * Usage: Log< 100, 10 >::value; value equals 2 * @param number for which to calculate the logarithm @@ -79,7 +83,8 @@ struct Log }; /** - * Compile time template to calculate base logarithm of N + * @brief Compile time template to calculate base logarithm of N. + * * Specialisation for logarithm of 1 * @param base logarithm to calculate */ @@ -90,7 +95,8 @@ struct Log< 1, base > }; /** - * Compile time template to calculate base logarithm of N + * @brief Compile time template to calculate base logarithm of N. + * * Specialisation for logarithm of 0 * @param base logarithm to calculate */ @@ -102,7 +108,8 @@ struct Log< 0, base > /** - * Compile time template to calculate the machine epsilon for a given floating point number + * @brief Compile time template to calculate the machine epsilon for a given floating point number. + * * Note! value needs to be compile time constant * Usage: Epsilon<1000>::value; value equals 0.000119209 * @param N the number for which to calculate the machine epsilon @@ -120,7 +127,8 @@ struct Epsilon }; /** - * Compile time template to calculate the machine epsilon for a given floating point number + * @brief Compile time template to calculate the machine epsilon for a given floating point number. + * * Specialisation for epsilon of 1 * predefined value calculated on ARM Cortex A9 target */ @@ -135,7 +143,8 @@ struct Epsilon< 1 > }; /** - * Compile time template to calculate the machine epsilon for a given floating point number + * @brief Compile time template to calculate the machine epsilon for a given floating point number. + * * Specialisation for epsilon of 0 * predefined value calculated on ARM Cortex A9 target */ diff --git a/capi/dali/public-api/math/degree.h b/capi/dali/public-api/math/degree.h index 32fa4f6..6ff5c44 100644 --- a/capi/dali/public-api/math/degree.h +++ b/capi/dali/public-api/math/degree.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_MATH_MODULE * @{ */ @@ -31,60 +31,73 @@ namespace Dali DALI_IMPORT_API struct Radian; /** - * An angle in degrees. + * @brief An angle in degrees. + * * This reduces ambiguity when using methods which accept angles in degrees or radians. */ struct DALI_IMPORT_API Degree { /** - * Create an angle in degrees. + * @brief Create an angle in degrees. + * * @param[in] value The initial value in degrees. */ explicit Degree( float value ); /** - * Create an angle in degrees from an angle in radians. + * @brief Create an angle in degrees from an angle in radians. + * * @param[in] value The initial value in radians. */ Degree( const Radian& value ); /** - * Compare equality between two degrees + * @brief Compare equality between two degrees. + * * @param[in] rhs Degree to compare to + * @return true if the value is identical */ bool operator==( const Degree& rhs ) const; /** - * Compare inequality between two degrees + * @brief Compare inequality between two degrees. + * * @param[in] rhs Degree to compare to + * @return true if the value is not identical */ bool operator!=( const Degree& rhs ) const; /** - * Compare two degrees + * @brief Compare two degrees. + * * @param[in] rhs Degree to compare to + * @return true if this is less than the value */ bool operator<( const Degree& rhs ) const; /** - * Assign an angle from a float value + * @brief Assign an angle from a float value. + * * @param[in] value Float value in degrees + * @return a reference to this */ Degree& operator=( const float value ); /** - * Assign an angle in radians to a Degree + * @brief Assign an angle in radians to a Degree. + * * @param[in] rhs Radian to get the value from + * @return a reference to this */ Degree& operator=( const Radian& rhs ); /** - * Cast operator to const float reference + * @brief Cast operator to const float reference */ operator const float&() const; /** - * Cast operator to float reference + * @brief Cast operator to float reference. */ operator float&(); @@ -92,7 +105,9 @@ private: // member data float mValue; ///< The value in degrees - // disable default constructor + /** + * @brief Disable the default constructor. + */ Degree(); }; diff --git a/capi/dali/public-api/math/math-utils.h b/capi/dali/public-api/math/math-utils.h index 2a3495f..2d39f8a 100644 --- a/capi/dali/public-api/math/math-utils.h +++ b/capi/dali/public-api/math/math-utils.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_MATH_MODULE * @{ */ @@ -32,7 +32,8 @@ namespace Dali DALI_IMPORT_API { /** - * Returns the next power of two. + * @brief Returns the next power of two. + * * In case of numbers which are already a power of two this function returns the original number. * If i is zero returns 1 * @param[in] i input number @@ -41,14 +42,16 @@ namespace Dali DALI_IMPORT_API DALI_IMPORT_API unsigned int NextPowerOfTwo( unsigned int i ); /** - * Whether a number is power of two. + * @brief Whether a number is power of two. + * * @param[in] i input number * @return true if i is power of two */ DALI_IMPORT_API bool IsPowerOfTwo( unsigned int i ); /** - * Clamp a value. + * @brief Clamp a value. + * * @param[in] value The value to clamp. * @param[in] min The minimum allowed value. * @param[in] max The maximum allowed value. @@ -61,7 +64,8 @@ const T& Clamp( const T& value, const T& min, const T& max ) } /** - * Clamp a value directly. + * @brief Clamp a value directly. + * * @param[in,out] value The value that will be clamped. * @param[in] min The minimum allowed value. * @param[in] max The maximum allowed value. @@ -74,7 +78,8 @@ void ClampInPlace( T& value, const T& min, const T& max ) /** - * Linear interpolation between two values + * @brief Linear interpolation between two values. + * * @param[in] offset The offset through the range @p low to @p high. * This value is clamped between 0 and 1 * @param[in] low Lowest value in range @@ -88,7 +93,8 @@ inline const T Lerp( const float offset, const T& low, const T& high ) } /** - * Get an epsilon that is valid for the given range. + * @brief Get an epsilon that is valid for the given range. + * * @param[in] a the first value in the range * @param[in] b the second value in the range. * @return a suitable epsilon @@ -96,14 +102,16 @@ inline const T Lerp( const float offset, const T& low, const T& high ) DALI_IMPORT_API float GetRangedEpsilon(float a, float b); /** - * Helper function to compare equality of a floating point value with zero + * @brief Helper function to compare equality of a floating point value with zero. + * * @param[in] value the value to compare * @return true if the value is equal to zero */ DALI_IMPORT_API bool EqualsZero( float value ); /** - * Helper function to compare equality of two floating point values + * @brief Helper function to compare equality of two floating point values. + * * @param[in] a the first value to compare * @param[in] b the second value to compare * @return true if the values are equal within a minimal epsilon for their values @@ -111,7 +119,8 @@ DALI_IMPORT_API bool EqualsZero( float value ); DALI_IMPORT_API bool Equals( float a, float b ); /** - * Helper function to compare equality of two floating point values + * @brief Helper function to compare equality of two floating point values. + * * @param[in] a the first value to compare * @param[in] b the second value to compare * @param[in] epsilon the minimum epsilon value that will be used to consider the values different @@ -120,7 +129,8 @@ DALI_IMPORT_API bool Equals( float a, float b ); DALI_IMPORT_API bool Equals( float a, float b, float epsilon ); /** - * Get an float that is rounded at specified place of decimals + * @brief Get an float that is rounded at specified place of decimals. + * * @param[in] value float value * @param[in] pos decimal place * @return a rounded float @@ -128,7 +138,7 @@ DALI_IMPORT_API bool Equals( float a, float b, float epsilon ); DALI_IMPORT_API float Round( float value, int pos ); /** - * Wrap x in domain (start) to (end) + * @brief Wrap x in domain (start) to (end). * * This works like a floating point version * of the % modulo operation. But with an offset (start). @@ -162,8 +172,9 @@ DALI_IMPORT_API float Round( float value, int pos ); DALI_IMPORT_API float WrapInDomain(float x, float start, float end); /** - * Find the shortest distance (magnitude) and direction (sign) - * from (a) to (b) in domain (start) to (end) + * @brief Find the shortest distance (magnitude) and direction (sign) + * from (a) to (b) in domain (start) to (end). + * * (\ / start) (\ / end) * |-a b<----| * diff --git a/capi/dali/public-api/math/matrix.h b/capi/dali/public-api/math/matrix.h index edff782..845ef5c 100644 --- a/capi/dali/public-api/math/matrix.h +++ b/capi/dali/public-api/math/matrix.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_MATH_MODULE * @{ */ @@ -33,7 +33,7 @@ namespace Dali DALI_IMPORT_API class Quaternion; /** - * The Matrix class represents transformations and projections. + * @brief The Matrix class represents transformations and projections. * It is agnostic w.r.t. row/column major notation - it operates on a flat array. * Each axis is contiguous in memory, so the x axis corresponds to elements 0, 1, 2 and 3, the y axis dorresponds to elements 4, 5, 6, 7, etc. */ @@ -44,19 +44,22 @@ public: friend std::ostream& operator<< (std::ostream& o, const Matrix& matrix); /** - * Constructor + * @brief Constructor. + * * Zero initialises the matrix */ Matrix(); /** - * Constructor + * @brief Constructor. + * * @param initialize to zero or leave uninitialized */ explicit Matrix( bool initialize ); /** - * Constructor + * @brief Constructor + * * The matrix is initialised with the contents of 'array' which must contain 16 floats. * The order of the values for a transform matrix is: * @@ -70,103 +73,124 @@ public: explicit Matrix(const float* array); /** - * Constructs a matrix from quaternion + * @brief Constructs a matrix from quaternion. + * * @param rotation as quaternion */ explicit Matrix( const Quaternion& rotation ); /** - * Copy constructor + * @brief Copy constructor. + * * @param [in] matrix to copy values from */ Matrix( const Matrix& matrix ); /** - * Assignment operator + * @brief Assignment operator. + * * @param [in] matrix to copy values from + * @return a reference to this */ Matrix& operator=( const Matrix& matrix ); /** - * The identity matrix + * @brief The identity matrix. */ static const Matrix IDENTITY; /** - * Sets this matrix to be an identity matrix. + * @brief Sets this matrix to be an identity matrix. */ void SetIdentity(); /** - * Sets this matrix to be an identity matrix with scale + * @brief Sets this matrix to be an identity matrix with scale. + * * @param scale to set on top of identity matrix */ void SetIdentityAndScale( const Vector3& scale ); /** - * Invert a transform Matrix. Any Matrix representing only a rotation and/or translation + * @brief Invert a transform Matrix. + * + * Any Matrix representing only a rotation and/or translation * can be inverted using this function. It is faster and more accurate then using Invert(). * @param [out] result returns the inverse of this matrix */ void InvertTransform(Matrix& result) const; /** - * Generic brute force Matrix Invert. Using the Matrix invert function for the specific type + * @brief Generic brute force Matrix Invert. + * + * Using the Matrix invert function for the specific type * of matrix you are dealing with is faster, more accurate. * @return true if successful */ bool Invert(); /** - * Swaps the rows to columns + * @brief Swaps the rows to columns. */ void Transpose(); /** - * Returns the xAxis from a Transform matrix. + * @brief Returns the xAxis from a Transform matrix. + * * @return the x axis */ Vector3 GetXAxis() const; /** - * Returns the yAxis from a Transform matrix. + * @brief Returns the yAxis from a Transform matrix. + * * @return the y axis */ Vector3 GetYAxis() const; /** - * Returns the zAxis from a Transform matrix. + * @brief Returns the zAxis from a Transform matrix. + * * @return the z axis */ Vector3 GetZAxis() const; /** - * Sets the x axis. This assumes the matrix is a transform matrix. + * @brief Sets the x axis. + * + * This assumes the matrix is a transform matrix. * @param [in] axis the values to set the axis to */ void SetXAxis(const Vector3& axis); /** - * Sets the y axis. This assumes the matrix is a transform matrix. + * @brief Sets the y axis. + * + * This assumes the matrix is a transform matrix. * @param [in] axis the values to set the axis to */ void SetYAxis(const Vector3& axis); /** - * Sets the z axis. This assumes the matrix is a transform matrix. + * @brief Sets the z axis. + * + * This assumes the matrix is a transform matrix. * @param [in] axis the values to set the axis to */ void SetZAxis(const Vector3& axis); /** - * Gets the translation. This assumes the matrix is a transform matrix. + * @brief Gets the translation. + * + * This assumes the matrix is a transform matrix. * @note inlined for performance reasons (generates less code than a function call) * @return the translation */ const Vector4& GetTranslation() const { return reinterpret_cast(mMatrix[12]); } /** - * Gets the x,y and z components of the translation as a Vector3. + * @brief Gets the x,y and z components of the translation as a Vector3. + * * This assumes the matrix is a transform matrix. * @note inlined for performance reasons (generates less code than a function call) * @return the translation @@ -174,20 +198,24 @@ public: const Vector3& GetTranslation3() const { return reinterpret_cast(mMatrix[12]); } /** - * Sets the translation. This assumes the matrix is a transform matrix. + * @brief Sets the translation. + * + * This assumes the matrix is a transform matrix. * @param [in] translation the translation */ void SetTranslation(const Vector4& translation); /** - * Sets the x,y and z components of the translation from a Vector3. + * @brief Sets the x,y and z components of the translation from a Vector3. + * * This assumes the matrix is a transform matrix. * @param [in] translation the translation */ void SetTranslation(const Vector3& translation); /** - * Makes the axes of the matrix orthogonal to each other and of unit length. + * @brief Makes the axes of the matrix orthogonal to each other and of unit length. + * * This function is used to correct floating point errors which would otherwise accumulate * as operations are applied to the matrix. This function assumes the matrix is a transform * matrix. @@ -195,7 +223,8 @@ public: void OrthoNormalize(); /** - * Returns the contents of the matrix as an array of 16 floats. + * @brief Returns the contents of the matrix as an array of 16 floats. + * * The order of the values for a transform matrix is: * xAxis.x xAxis.y xAxis.z 0.0f * yAxis.x yAxis.y yAxis.z 0.0f @@ -207,7 +236,8 @@ public: const float* AsFloat() const {return mMatrix;} /** - * Returns the contents of the matrix as an array of 16 floats. + * @brief Returns the contents of the matrix as an array of 16 floats. + * * The order of the values for a transform matrix is: * * xAxis.x xAxis.y xAxis.z 0.0f @@ -220,7 +250,8 @@ public: float* AsFloat() {return mMatrix;} /** - * Function to multiply two matrices and store the result onto third + * @brief Function to multiply two matrices and store the result onto third. + * * Use this method in time critical path as it does not require temporaries * @param result of the multiplication * @param lhs matrix, this can be same matrix as result @@ -229,7 +260,8 @@ public: static void Multiply( Matrix& result, const Matrix& lhs, const Matrix& rhs ); /** - * Function to multiply a matrix and quaternion and store the result onto third + * @brief Function to multiply a matrix and quaternion and store the result onto third. + * * Use this method in time critical path as it does not require temporaries * @param result of the multiplication * @param lhs matrix, this can be same matrix as result @@ -238,14 +270,16 @@ public: static void Multiply( Matrix& result, const Matrix& lhs, const Quaternion& rhs ); /** - * The multiplication operator. + * @brief The multiplication operator. + * * @param [in] rhs the Matrix to multiply this by * @return A matrix containing the result */ Vector4 operator*(const Vector4& rhs) const; /** - * The equality operator. + * @brief The equality operator. + * * Utilises appropriate machine epsilon values. * * @param [in] rhs the Matrix to compare this to @@ -254,7 +288,8 @@ public: bool operator==(const Matrix & rhs) const; /** - * The inequality operator. + * @brief The inequality operator. + * * Utilises appropriate machine epsilon values. * @param [in] rhs the Matrix to compare this to * @return true if the matrices are not equal. @@ -262,7 +297,8 @@ public: bool operator!=(const Matrix & rhs) const; /** - * Sets this matrix to contain the position, scale and rotation components + * @brief Sets this matrix to contain the position, scale and rotation components. + * * Performs scale, rotation, then translation * @param[in] scale to apply * @param[in] rotation to apply @@ -273,7 +309,8 @@ public: const Vector3& translation ); /** - * Sets this matrix to contain the inverse of the position, scale and rotation components + * @brief Sets this matrix to contain the inverse of the position, scale and rotation components. + * * Performs translation, then rotation, then scale. * @param[in] scale to apply * @param[in] rotation to apply @@ -285,7 +322,8 @@ public: /** - * Sets this matrix to contain the inverse of the orthonormal basis and position components + * @brief Sets this matrix to contain the inverse of the orthonormal basis and position components. + * * Performs translation, then rotation. * @param[in] xAxis The X axis of the basis * @param[in] yAxis The Y axis of the basis @@ -298,7 +336,8 @@ public: const Vector3& translation ); /** - * Gets the position, scale and rotation components from the given transform matrix. + * @brief Gets the position, scale and rotation components from the given transform matrix. + * * @pre This matrix must not contain skews or shears. * @param[out] position to set * @param[out] rotation to set - only valid if the transform matrix has not been skewed or sheared @@ -310,11 +349,13 @@ public: private: - float mMatrix[16]; + float mMatrix[16]; ///< The elements of the matrix }; /** - * Print a matrix. It is printed in memory order, i.e. each printed row is contiguous in memory. + * @brief Print a matrix. + * + * It is printed in memory order, i.e. each printed row is contiguous in memory. * @param [in] o The output stream operator. * @param [in] matrix The matrix to print. * @return The output stream operator. diff --git a/capi/dali/public-api/math/matrix3.h b/capi/dali/public-api/math/matrix3.h index 730b984..42563a1 100644 --- a/capi/dali/public-api/math/matrix3.h +++ b/capi/dali/public-api/math/matrix3.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_MATH_MODULE * @{ */ @@ -33,7 +33,8 @@ class Matrix; struct Vector2; /** - * A 3x3 matrix. + * @brief A 3x3 matrix. + * */ class DALI_IMPORT_API Matrix3 { @@ -42,34 +43,61 @@ public: friend std::ostream& operator<< (std::ostream& o, const Matrix3& matrix); /** - * The identity matrix + * @brief The identity matrix */ static const Matrix3 IDENTITY; /** - * Constructors + * @brief Constructor. */ Matrix3(); + + /** + * @brief Copy Constructor. + * + * @param[in] m Another 3x3 matrix + */ Matrix3(const Matrix3& m); + + /** + * @brief Constructor. + * + * @param[in] m A 4x4 matrix. The translation and shear components are ignored. + */ Matrix3(const Matrix& m); + + /** + * @brief Constructor. + * + * @param[in] s00 First element + * @param[in] s01 Second element + * @param[in] s02 Third element + * @param[in] s10 Fourth element + * @param[in] s11 Fifth element + * @param[in] s12 Sixth element + * @param[in] s20 Seventh element + * @param[in] s21 Eighth element + * @param[in] s22 Ninth element + */ Matrix3(float s00, float s01, float s02, float s10, float s11, float s12, float s20, float s21, float s22); /** - * Assignment Operator + * @brief Assignment Operator * @param matrix from which to copy values * @return reference to this object */ Matrix3& operator=( const Matrix3& matrix ); /** - * Assignment Operator + * @brief Assignment Operator * @param matrix from which to copy values * @return reference to this object */ Matrix3& operator=( const Matrix& matrix ); /** - * The equality operator. + * @brief The equality operator. + * * Utilises appropriate machine epsilon values. * * @param [in] rhs the Matrix to compare this to @@ -78,7 +106,8 @@ public: bool operator==(const Matrix3 & rhs) const; /** - * The inequality operator. + * @brief The inequality operator. + * * Utilises appropriate machine epsilon values. * * @param [in] rhs the Matrix to compare this to @@ -87,19 +116,20 @@ public: bool operator!=(const Matrix3 & rhs) const; /** - * Destructor + * @brief Destructor. */ ~Matrix3() { } /** - * Sets the matrix to the identity matrix. + * @brief Sets the matrix to the identity matrix. */ void SetIdentity(); /** - * Returns the contents of the matrix as an array of 9 floats. + * @brief Returns the contents of the matrix as an array of 9 floats. + * * The order of the values for a matrix is: * xAxis.x yAxis.x zAxis.x * xAxis.y yAxis.y zAxis.y @@ -109,7 +139,8 @@ public: const float* AsFloat() const {return &mElements[0];} /** - * Returns the contents of the matrix as an array of 9 floats. + * @brief Returns the contents of the matrix as an array of 9 floats. + * * The order of the values for a matrix is: * xAxis.x yAxis.x zAxis.x * xAxis.y yAxis.y zAxis.y @@ -119,34 +150,40 @@ public: float* AsFloat() {return &mElements[0];} /** - * Inverts the matrix. + * @brief Inverts the matrix. + * * @return true if successful */ bool Invert(); /** - * Swaps the rows to columns + * @brief Swaps the rows to columns * @return true */ bool Transpose(); /** - * Multiplies all elements of the matrix by the scale value + * @brief Multiplies all elements of the matrix by the scale value. + * * @param scale - the value by which to scale the whole matrix. + */ void Scale(float scale); /** - * Magnitude returns the average of the absolute values of the - * elements * 3. (The Magnitude of the unit matrix is therefore 1) + * @brief Magnitude returns the average of the absolute values of the + * elements * 3. + * + * (The Magnitude of the unit matrix is therefore 1) * @return the magnitude - always positive. */ float Magnitude() const; /** - * If the matrix is invertible, then this method inverts, transposes + * @brief If the matrix is invertible, then this method inverts, transposes * and scales the matrix such that the resultant element values * average 1. + * * If the matrix is not invertible, then the matrix is left unchanged. * @return true if the matrix is invertible, otherwise false @@ -154,7 +191,8 @@ public: bool ScaledInverseTranspose(); /** - * Function to multiply two matrices and store the result onto third + * @brief Function to multiply two matrices and store the result onto third. + * * Use this method in time critical path as it does not require temporaries * @param result of the multiplication * @param lhs matrix, this can be same matrix as result @@ -164,11 +202,12 @@ public: private: - float mElements[9]; + float mElements[9]; ///< The elements of the matrix }; /** - * Print a 3x3 matrix. + * @brief Print a 3x3 matrix. + * * @param [in] o The output stream operator. * @param [in] matrix The matrix to print. * @return The output stream operator. diff --git a/capi/dali/public-api/math/quaternion.h b/capi/dali/public-api/math/quaternion.h index f5266af..81922e6 100644 --- a/capi/dali/public-api/math/quaternion.h +++ b/capi/dali/public-api/math/quaternion.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_MATH_MODULE * @{ */ @@ -38,19 +38,20 @@ namespace Dali DALI_IMPORT_API class Matrix; /** - * The Quaternion class encapsulates the mathematics of the quaternion. + * @brief The Quaternion class encapsulates the mathematics of the quaternion. */ class DALI_IMPORT_API Quaternion { public: /** - * Default Constructor + * @brief Default Constructor */ Quaternion(); /** - * Construct from a quaternion represented by floats + * @brief Construct from a quaternion represented by floats. + * * @param[in] cosThetaBy2 * @param[in] iBySineTheta * @param[in] jBySineTheta @@ -59,27 +60,31 @@ public: Quaternion(float cosThetaBy2, float iBySineTheta, float jBySineTheta, float kBySineTheta); /** - * Construct from a quaternion represented by a vector + * @brief Construct from a quaternion represented by a vector. + * * @param[in] vector - x,y,z fields represent i,j,k coefficients, w represents cos(theta/2) */ explicit Quaternion(const Vector4& vector); /** - * Constructor from an axis and angle + * @brief Constructor from an axis and angle. + * * @param[in] angle - the angle around the axis * @param[in] axis - the vector of the axis */ Quaternion(float angle, const Vector3 &axis); /** - * Constructor from an axis and angle + * @brief Constructor from an axis and angle. + * * @param[in] theta - the angle of the axis * @param[in] axis - the unit vector of the axis */ Quaternion(float theta, const Vector4 &axis); /** - * Construct from Euler angles + * @brief Construct from Euler angles. + * * @param[in] x - the X axis euler angle (pitch) * @param[in] y - the Y axis euler angle (yaw) * @param[in] z - the Z axis euler angle (roll) @@ -87,13 +92,15 @@ public: Quaternion(float x, float y, float z); /** - * Construct from a matrix + * @brief Construct from a matrix. + * * @param[in] matrix */ explicit Quaternion(const Matrix& matrix); /** - * Construct from 3 orthonormal axes + * @brief Construct from 3 orthonormal axes. + * * @param[in] xAxis The X axis * @param[in] yAxis The Y axis * @param[in] zAxis The Z axis @@ -101,7 +108,8 @@ public: explicit Quaternion( const Vector3& xAxis, const Vector3& yAxis, const Vector3& zAxis ); /** - * converts an axis + angle pair rotation to a Quaternion + * @brief Converts an axis + angle pair rotation to a Quaternion. + * * @param[in] axis * @param[in] angle * @return the represented quaternion @@ -109,7 +117,8 @@ public: static Quaternion FromAxisAngle(const Vector4 &axis, float angle); /** - * Destructor, nonvirtual as this is not a base class + * @brief Destructor, nonvirtual as this is not a base class. + * */ ~Quaternion(); @@ -118,7 +127,8 @@ public: static const Quaternion IDENTITY; ///< (0.0f,0.0f,0.0f,1.0f) /** - * Helper to check if this is an identity quaternion + * @brief Helper to check if this is an identity quaternion + * * @return true if this is identity quaternion */ bool IsIdentity() const @@ -132,7 +142,8 @@ public: } /** - * Convert the quaternion to an axis/angle pair + * @brief Convert the quaternion to an axis/angle pair. + * * @param[out] axis * @param[out] angle * @return true if converted correctly @@ -140,7 +151,8 @@ public: bool ToAxisAngle(Vector3 &axis, float &angle) const; /** - * Convert the quaternion to an axis/angle pair + * @brief Convert the quaternion to an axis/angle pair. + * * @param[out] axis * @param[out] angle * @return true if converted correctly @@ -148,13 +160,15 @@ public: bool ToAxisAngle(Vector4 &axis, float &angle) const; /** - * Return the quaternion as a vector + * @brief Return the quaternion as a vector. + * * @return the vector representation of the quaternion */ const Vector4& AsVector() const; /** - * SetEuler sets the quaternion from the Euler angles applied in x, y, z order. + * @brief SetEuler sets the quaternion from the Euler angles applied in x, y, z order. + * * @param[in] x - the X axis euler angle (pitch) * @param[in] y - the Y axis euler angle (yaw) * @param[in] z - the Z axis euler angle (roll) @@ -162,162 +176,187 @@ public: void SetEuler(float x, float y, float z); /** - * returns the Euler angles from a rotation Quaternion + * @brief returns the Euler angles from a rotation Quaternion. + * * @return a vector of Euler angles (x == pitch, y == yaw, z == roll) */ Vector4 EulerAngles() const; /** - * Addition operator + * @brief Addition operator. + * * @param[in] other The quaternion to add * @return A quaternion containing the result of the addition */ const Quaternion operator +(const Quaternion &other) const; /** - * Subtraction operator + * @brief Subtraction operator. + * * @param[in] other The quaternion to subtract * @return A quaternion containing the result of the subtract */ const Quaternion operator -(const Quaternion &other) const; /** - * Multiplication operator + * @brief Multiplication operator. + * * @param[in] other The quaternion to multiply * @return A quaternion containing the result */ const Quaternion operator *(const Quaternion &other) const; /** - * Multiplication operator + * @brief Multiplication operator. + * * @param[in] v The vector to multiply * @return A vector containing the result of the multiplication */ Vector3 operator *(const Vector3& v) const; /** - * Division operator + * @brief Division operator. + * * @param[in] other a quaternion to divide by * @return A quaternion containing the result */ const Quaternion operator /(const Quaternion &other) const; /** - * Scale operator + * @brief Scale operator. + * * @param[in] scale A value to scale by * @return A quaternion containing the result */ const Quaternion operator *(float scale) const; /** - * Scale operator + * @brief Scale operator. + * * @param[in] scale A value to scale by * @return A quaternion containing the result */ const Quaternion operator /(float scale) const; /** - * Unary Negation operator + * @brief Unary Negation operator. + * * @return A quaternion containing the negated result */ Quaternion operator -() const; /** - * Addition with Assignment operator + * @brief Addition with Assignment operator. + * * @param[in] other The quaternion to add * @return itself */ const Quaternion &operator +=(const Quaternion &other); /** - * Subtraction with Assignment operator + * @brief Subtraction with Assignment operator. + * * @param[in] other The quaternion to subtract * @return itself */ const Quaternion &operator -=(const Quaternion &other); /** - * Multiplication with Assignment operator + * @brief Multiplication with Assignment operator. + * * @param[in] other The quaternion to multiply * @return itself */ const Quaternion &operator *=(const Quaternion &other); /** - * Scale with Assignment operator + * @brief Scale with Assignment operator. + * * @param[in] scale the value to scale by * @return itself */ const Quaternion &operator *= (float scale); /** - * Scale with Assignment operator + * @brief Scale with Assignment operator. + * * @param[in] scale the value to scale by * @return itself */ const Quaternion &operator /= (float scale); /** - * Equality operator. + * @brief Equality operator. + * * @param[in] rhs The quaterion to compare with. * @return True if the quaternions are equal. */ bool operator== (const Quaternion& rhs) const; /** - * Inequality operator. + * @brief Inequality operator. + * * @param[in] rhs The quaterion to compare with. * @return True if the quaternions are not equal. */ bool operator!= (const Quaternion& rhs) const; /** - * Return the length of the quaternion + * @brief Return the length of the quaternion. + * * @return the length of the quaternion */ float Length() const; /** - * Return the squared length of the quaternion + * @brief Return the squared length of the quaternion. + * * @return the squared length of the quaternion */ float LengthSquared() const; /** - * Normalize this to unit length + * @brief Normalize this to unit length. + * */ void Normalize(); /** - * Normalized + * @brief Normalized. + * * @return a normalized version of this quaternion */ Quaternion Normalized() const; /** - * Conjugate this quaternion + * @brief Conjugate this quaternion. + * */ void Conjugate(); /** - * Invert this quaternion + * @brief Invert this quaternion. + * */ void Invert(); /** - * Performs the logarithm of a Quaternion = v*a where q = (cos(a),v*sin(a)) + * @brief Performs the logarithm of a Quaternion = v*a where q = (cos(a),v*sin(a)). + * * @return a quaternion representing the logarithm */ Quaternion Log() const; /** - * Performs an exponent e^Quaternion = Exp(v*a) = (cos(a),vsin(a)) + * @brief Performs an exponent e^Quaternion = Exp(v*a) = (cos(a),vsin(a)). + * * @return a quaternion representing the exponent */ Quaternion Exp() const; /** - * Return the dot product of two quaternions + * @brief Return the dot product of two quaternions. + * * @param[in] q1 - the first quaternion * @param[in] q2 - the second quaternion * @return the dot product of the two quaternions @@ -325,7 +364,8 @@ public: static float Dot(const Quaternion &q1, const Quaternion &q2); /** - * Linear Interpolation (using a straight line between the two quaternions) + * @brief Linear Interpolation (using a straight line between the two quaternions). + * * @param[in] q1 - the start quaternion * @param[in] q2 - the end quaternion * @param[in] t - a progress value between 0 and 1 @@ -334,8 +374,9 @@ public: static Quaternion Lerp(const Quaternion &q1, const Quaternion &q2, float t); /** - * Spherical Linear Interpolation (using the shortest arc of a great circle between + * @brief Spherical Linear Interpolation (using the shortest arc of a great circle between * the two quaternions). + * * @param[in] q1 - the start quaternion * @param[in] q2 - the end quaternion * @param[in] progress - a progress value between 0 and 1 @@ -344,7 +385,8 @@ public: static Quaternion Slerp(const Quaternion &q1, const Quaternion &q2, float progress); /** - * This version of Slerp, used by Squad, does not check for theta > 90. + * @brief This version of Slerp, used by Squad, does not check for theta > 90. + * * @param[in] q1 - the start quaternion * @param[in] q2 - the end quaternion * @param[in] t - a progress value between 0 and 1 @@ -353,7 +395,8 @@ public: static Quaternion SlerpNoInvert(const Quaternion &q1, const Quaternion &q2, float t); /** - * Spherical Cubic Interpolation + * @brief Spherical Cubic Interpolation. + * * @param[in] q1 - the start quaternion * @param[in] q2 - the end quaternion * @param[in] a - the control quaternion for q1 @@ -364,7 +407,8 @@ public: static Quaternion Squad(const Quaternion &q1,const Quaternion &q2,const Quaternion &a,const Quaternion &b,float t); /** - * Returns the shortest angle between two quaternions in Radians. + * @brief Returns the shortest angle between two quaternions in Radians. + * * @param[in] q1 - the first quaternion * @param[in] q2 - the second quaternion * @return the angle between the two quaternions. @@ -372,14 +416,16 @@ public: static float AngleBetween(const Quaternion &q1, const Quaternion &q2); /** - * Rotate v by this Quaternion (Quaternion must be unit) + * @brief Rotate v by this Quaternion (Quaternion must be unit). + * * @param[in] v - a vector to rotate * @return the rotated vector */ Vector4 Rotate(const Vector4 &v) const; /** - * Rotate v by this Quaternion (Quaternion must be unit) + * @brief Rotate v by this Quaternion (Quaternion must be unit). + * * @param[in] v - a vector to rotate * @return the rotated vector */ @@ -388,7 +434,8 @@ public: private: /** - * Set the quaternion from 3 orthonormal axes + * @brief Set the quaternion from 3 orthonormal axes. + * * @param[in] xAxis The X axis * @param[in] yAxis The Y axis * @param[in] zAxis The Z axis @@ -397,11 +444,12 @@ private: public: - Vector4 mVector; // w component is s ( = cos(theta/2.0) ) + Vector4 mVector; ///< w component is s ( = cos(theta/2.0) ) }; /** - * Print a Quaternion. + * @brief Print a Quaternion. + * * @param [in] o The output stream operator. * @param [in] quaternion The quaternion to print. * @return The output stream operator. diff --git a/capi/dali/public-api/math/radian.h b/capi/dali/public-api/math/radian.h index 12e953d..200f6ed 100644 --- a/capi/dali/public-api/math/radian.h +++ b/capi/dali/public-api/math/radian.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_MATH_MODULE * @{ */ @@ -31,60 +31,73 @@ namespace Dali DALI_IMPORT_API struct Degree; /** - * An angle in radians. + * @brief An angle in radians. + * * This reduces ambiguity when using methods which accept angles in degrees or radians. */ struct DALI_IMPORT_API Radian { /** - * Create an angle in radians. + * @brief Create an angle in radians. + * * @param[in] value The initial value in radians. */ explicit Radian( float value ); /** - * Create an angle in radians from an angle in degrees. + * @brief Create an angle in radians from an angle in degrees. + * * @param[in] value The initial value in degrees. */ Radian( const Degree& value ); /** - * Compare equality between two radians + * @brief Compare equality between two radians. + * * @param[in] rhs Radian to compare to + * @return true if the value is identical */ bool operator==( const Radian& rhs ) const; /** - * Compare inequality between two radians + * @brief Compare inequality between two radians. + * * @param[in] rhs Radian to compare to + * @return true if the value is not identical */ bool operator!=( const Radian& rhs ) const; /** - * Compare two radians + * @brief Compare two radians. + * * @param[in] rhs Radian to compare to + * @return true if this is less than the value */ bool operator<( const Radian& rhs ) const; /** - * Assign an angle from a float value + * @brief Assign an angle from a float value. + * * @param[in] value Float value in radians + * @return a reference to this object */ Radian& operator=( const float value ); /** - * Assign an angle in degrees to a Radian + * @brief Assign an angle in degrees to a Radian. + * * @param[in] rhs Degree to get the value from + * @return a reference to this object */ Radian& operator=( const Degree& rhs ); /** - * Cast operator to const float reference + * @brief Cast operator to const float reference. */ operator const float&() const; /** - * Cast operator to float reference + * @brief Cast operator to float reference. */ operator float&(); diff --git a/capi/dali/public-api/math/random.h b/capi/dali/public-api/math/random.h index ed2a92d..4d37807 100644 --- a/capi/dali/public-api/math/random.h +++ b/capi/dali/public-api/math/random.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_MATH_MODULE * @{ */ @@ -28,11 +28,16 @@ namespace Dali DALI_IMPORT_API { +/** + * @brief Provides methods to generate and use random values. + */ namespace Random { /** - * Returns a random number between f0 and f1. Note, uses a limited number of values. + * @brief Returns a random number between f0 and f1. + * + * Note, uses a limited number of values. * @param[in] f0 the lower bound * @param[in] f1 the upper bound * @return a random value between the lower and upper bound @@ -45,7 +50,8 @@ inline float Range(float f0, float f1) } /** - * Function to return a normalized axis in a random direction + * @brief Function to return a normalized axis in a random direction. + * * @return the axis */ inline Vector4 Axis() @@ -65,7 +71,8 @@ inline Vector4 Axis() } /** - * Returns true if the value given is greater than a random value between 0 and 1. + * @brief Returns true if the value given is greater than a random value between 0 and 1. + * * @param chance A value between 0 and 1. [Default: 0.5] * @return true if chance greater than the random value, otherwise false. */ diff --git a/capi/dali/public-api/math/rect.h b/capi/dali/public-api/math/rect.h index 2bc60e2..4b5588b 100644 --- a/capi/dali/public-api/math/rect.h +++ b/capi/dali/public-api/math/rect.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_MATH_MODULE * @{ */ @@ -31,13 +31,16 @@ namespace Dali DALI_IMPORT_API { +/** + * @brief Template class to create and operate on rectangles. + */ template< typename T = float > struct Rect { // Methods /** - * Constructor + * @brief Constructor. */ Rect() : x(0), @@ -48,7 +51,8 @@ struct Rect } /** - * Constructor + * @brief Constructor. + * * @param [in] x x coordinate * @param [in] y y coordinate * @param [in] width width @@ -63,7 +67,8 @@ struct Rect } /** - * Copy constructor + * @brief Copy constructor. + * * @param [in] rhs The original object */ Rect(const Rect& rhs) @@ -74,141 +79,159 @@ struct Rect height = rhs.height; } - /** - * Assignment operator - * @param [in] rhs The original object - */ - Rect& operator= (const Rect& rhs) - { - if (this != &rhs) - { - x = rhs.x; - y = rhs.y; - width = rhs.width; - height = rhs.height; - } - - return *this; - } - - /** - * Assignment from individual values - * @param[in] newX x coordinate - * @param[in] newY y coordinate - * @param[in] newWidth width - * @param[in] newHeight height - */ + /** + * @brief Assignment operator. + * + * @param [in] rhs The original object + * @return reference to this + */ + Rect& operator= (const Rect& rhs) + { + if (this != &rhs) + { + x = rhs.x; + y = rhs.y; + width = rhs.width; + height = rhs.height; + } + + return *this; + } + + /** + * @brief Assignment from individual values. + * + * @param[in] newX x coordinate + * @param[in] newY y coordinate + * @param[in] newWidth width + * @param[in] newHeight height + */ void Set(T newX, T newY, T newWidth, T newHeight) { - x = newX; - y = newY; - width = newWidth; - height = newHeight; + x = newX; + y = newY; + width = newWidth; + height = newHeight; + } + + /** + * @brief Determines whether or not this Rectangle is empty. + * + * @return true if width or height are zero + */ + bool IsEmpty() const + { + return width == 0 || + height == 0; + } + + /** + * @brief Get the left of the rectangle. + * + * @return The left edge of the rectangle + */ + T Left() const + { + return x; + } + /** + * @brief Get the right of the rectangle. + * + * @return The right edge of the rectangle + */ + T Right() const + { + return x + width; } - /** - * Determines whether or not this Rectangle is empty - * @return true if width or height are zero - */ - bool IsEmpty() const - { - return width == 0 || - height == 0; - } - - /** - * Get the left of the rectangle - * return The left edge of the rectangle - */ - T Left() const - { - return x; - } - /** - * Get the right of the rectangle - * return The right edge of the rectangle - */ - T Right() const - { - return x + width; - } - - /** - * Get the top of the rectangle - * return The top of the rectangle - */ - T Top() const - { - return y; - } - - /** - * Get the bottom of the rectangle - * return The bottom of the rectangle - */ - T Bottom() const - { - return y + height; - } - - /** - * Get the area of the rectangle - * @return The area of the rectangle - */ - T Area() const - { - return width * height; - } - - /** - * Determines whether or not this rectangle and the specified rectangle intersect - * @param[in] other The other rectangle to test against this rectangle - * @return true if the rectangles intersect - */ - bool Intersects(const Rect& other) const - { - return (other.x + other.width) > x && - other.x < (x + width) && - (other.y + other.height) > y && - other.y < (y + height); - } - - /** - * Determines whether or not this Rectangle contains the specified rectangle. - * @param[in] other The other rectangle to test against this rectangle - * @return true if the specified rectangle is contained - */ - bool Contains(const Rect& other) const - { - return other.x >= x && - (other.x + other.width) <= (x + width) && - other.y >= y && - (other.y + other.height) <= (y + height); - } + /** + * @brief Get the top of the rectangle. + * + * @return The top of the rectangle + */ + T Top() const + { + return y; + } + + /** + * @brief Get the bottom of the rectangle. + * + * @return The bottom of the rectangle + */ + T Bottom() const + { + return y + height; + } + + /** + * @brief Get the area of the rectangle. + * + * @return The area of the rectangle + */ + T Area() const + { + return width * height; + } + + /** + * @brief Determines whether or not this rectangle and the specified rectangle intersect. + * + * @param[in] other The other rectangle to test against this rectangle + * @return true if the rectangles intersect + */ + bool Intersects(const Rect& other) const + { + return (other.x + other.width) > x && + other.x < (x + width) && + (other.y + other.height) > y && + other.y < (y + height); + } + + /** + * @brief Determines whether or not this Rectangle contains the specified rectangle. + * + * @param[in] other The other rectangle to test against this rectangle + * @return true if the specified rectangle is contained + */ + bool Contains(const Rect& other) const + { + return other.x >= x && + (other.x + other.width) <= (x + width) && + other.y >= y && + (other.y + other.height) <= (y + height); + } public: // Data - T x; - T y; - T width; - T height; -}; // struct templateRect + T x; ///< X position of the rectangle + T y; ///< Y position of the rectangle + T width; ///< width of the rectangle + T height; ///< height of the rectangle +}; /** - * Equality operator + * @brief Equality operator. + * + * @param[in] lhs First operand + * @param[in] rhs Second operand * @return true if boxes are exactly same */ template< typename T > inline bool operator==( const Rect& lhs, const Rect& rhs ) { return ( lhs.x == rhs.x )&& - ( lhs.y == rhs.y )&& - ( lhs.width == rhs.width )&& - ( lhs.height == rhs.height ); + ( lhs.y == rhs.y )&& + ( lhs.width == rhs.width )&& + ( lhs.height == rhs.height ); } /** - * Inequality operator + * @brief Inequality operator. + * + * @param[in] lhs The first rectangle + * @param[in] rhs The second rectangle + * @return true if rectangles are not identical */ template< typename T > inline bool operator!=( const Rect& lhs, const Rect& rhs ) @@ -217,20 +240,25 @@ inline bool operator!=( const Rect& lhs, const Rect& rhs ) } /** - * Equality operator specialization for float - * @return true if boxes are exactly same + * @brief Equality operator specialization for float. + * + * @param[in] lhs The first rectangle + * @param[in] rhs The second rectangle + * @return true if rectangles are exactly same */ template<> inline bool operator==( const Rect& lhs, const Rect& rhs ) { return ( fabsf( lhs.x - rhs.x ) < GetRangedEpsilon(lhs.x, rhs.x) )&& - ( fabsf( lhs.y - rhs.y ) < GetRangedEpsilon(lhs.y, rhs.y) )&& - ( fabsf( lhs.width - rhs.width ) < GetRangedEpsilon(lhs.width, rhs.width) )&& - ( fabsf( lhs.height - rhs.height ) < GetRangedEpsilon(lhs.height, rhs.height) ); + ( fabsf( lhs.y - rhs.y ) < GetRangedEpsilon(lhs.y, rhs.y) )&& + ( fabsf( lhs.width - rhs.width ) < GetRangedEpsilon(lhs.width, rhs.width) )&& + ( fabsf( lhs.height - rhs.height ) < GetRangedEpsilon(lhs.height, rhs.height) ); } /** - * IsEmpty specialization for float + * @brief IsEmpty specialization for float. + * + * @return true if the rectangle has zero size. */ template<> inline bool Rect::IsEmpty() const diff --git a/capi/dali/public-api/math/vector2.h b/capi/dali/public-api/math/vector2.h index 7555573..0cdcb96 100644 --- a/capi/dali/public-api/math/vector2.h +++ b/capi/dali/public-api/math/vector2.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_MATH_MODULE * @{ */ @@ -36,18 +36,18 @@ struct Vector3; struct Vector4; /** - * 2D vector + * @brief A two dimensional vector. */ - // NOTE - // (x width) and (y height) must be consecutive in memory. - // No other data must be added before (x width) member. - // No virtual methods must be added to this struct. struct DALI_IMPORT_API Vector2 { +// (x width) and (y height) must be consecutive in memory. +// No other data must be added before (x width) member. +// No virtual methods must be added to this struct. + public: /** - * Constructor + * @brief Constructor. */ Vector2() : x(0.0f), @@ -56,7 +56,8 @@ public: } /** - * Constructor + * @brief Constructor. + * * @param[in] x x or width component * @param[in] y y or height component */ @@ -66,7 +67,8 @@ public: } /** - * Conversion constructor from an array of two floats + * @brief Conversion constructor from an array of two floats. + * * @param [in] array of xy */ explicit Vector2(const float* array) @@ -76,13 +78,15 @@ public: } /** - * Constructor + * @brief Constructor. + * * @param [in] vec3 Vector3 to create this vector from */ explicit Vector2(const Vector3& vec3); /** - * Constructor + * @brief Constructor. + * * @param [in] vec4 Vector4 to create this vector from */ explicit Vector2(const Vector4& vec4); @@ -99,7 +103,8 @@ public: // API /** - * Assignment operator + * @brief Assignment operator. + * * @param[in] array of floats * @return itself */ @@ -112,21 +117,24 @@ public: } /** - * Assignment operator + * @brief Assignment operator. + * * @param[in] rhs vector to assign. * @return itself */ Vector2& operator=(const Vector3& rhs); /** - * Assignment operator + * @brief Assignment operator. + * * @param[in] rhs vector to assign. * @return itself */ Vector2& operator=(const Vector4& rhs); /** - * Addition operator + * @brief Addition operator. + * * @param[in] rhs vector to add. * @return A vector containing the result of the addition */ @@ -138,7 +146,8 @@ public: } /** - * Addition assignment operator + * @brief Addition assignment operator. + * * @param[in] rhs vector to add. * @return itself */ @@ -151,7 +160,8 @@ public: } /** - * Subtraction operator + * @brief Subtraction operator. + * * @param[in] rhs the vector to subtract * @return A vector containing the result of the subtraction */ @@ -163,7 +173,8 @@ public: } /** - * Subtraction assignment operator + * @brief Subtraction assignment operator. + * * @param[in] rhs the vector to subtract * @return itself */ @@ -176,7 +187,8 @@ public: } /** - * Multiplication operator + * @brief Multiplication operator. + * * @param[in] rhs the vector to multiply * @return A vector containing the result of the multiplication */ @@ -186,7 +198,8 @@ public: } /** - * Multiplication operator + * @brief Multiplication operator. + * * @param[in] rhs the float value to scale the vector * @return A vector containing the result of the scaling */ @@ -196,7 +209,8 @@ public: } /** - * Multiplication assignment operator + * @brief Multiplication assignment operator. + * * @param[in] rhs the vector to multiply * @return itself */ @@ -209,7 +223,8 @@ public: } /** - * Multiplication assignment operator + * @brief Multiplication assignment operator. + * * @param[in] rhs the float value to scale the vector * @return itself */ @@ -222,7 +237,8 @@ public: } /** - * Division operator + * @brief Division operator. + * * @param[in] rhs the vector to divide * @return A vector containing the result of the division */ @@ -232,7 +248,8 @@ public: } /** - * Division operator + * @brief Division operator. + * * @param[in] rhs The float value to scale the vector by * @return A vector containing the result of the scaling */ @@ -243,7 +260,8 @@ public: /** - * Division assignment operator + * @brief Division assignment operator. + * * @param[in] rhs the vector to divide * @return itself */ @@ -256,7 +274,8 @@ public: } /** - * Division assignment operator + * @brief Division assignment operator. + * * @param[in] rhs the float value to scale the vector by * @return itself */ @@ -269,7 +288,8 @@ public: } /** - * Unary negation operator + * @brief Unary negation operator. + * * @return A vector containg the negation */ Vector2 operator-() const @@ -280,7 +300,8 @@ public: } /** - * Equality operator + * @brief Equality operator. + * * utilises appropriate machine epsilon values; * * @param[in] rhs The vector to test against @@ -289,7 +310,8 @@ public: bool operator==(const Vector2& rhs) const; /** - * Inequality operator + * @brief Inequality operator. + * * utilises appropriate machine epsilon values; * * @param[in] rhs The vector to test against @@ -301,7 +323,8 @@ public: } /** - * Const array subscript operator overload + * @brief Const array subscript operator overload. + * * Asserts if index is out of range. Should be 0 or 1 * @param[in] index Subscript * @return The float at the given index @@ -314,7 +337,8 @@ public: } /** - * Mutable array subscript operator overload + * @brief Mutable array subscript operator overload. + * * Asserts if index is out of range. Should be 0 or 1 * @param[in] index Subscript index * @return The float at the given index. @@ -327,32 +351,38 @@ public: } /** - * Returns the length of the vector. + * @brief Returns the length of the vector. + * * @return the length of the vector */ float Length() const; /** - * Returns the length of the vector squared. This is more efficient than Length() for threshold + * @brief Returns the length of the vector squared. + * + * This is more efficient than Length() for threshold * testing as it avoids the use of a square root. * @return the length of the vector squared. */ float LengthSquared() const; /** - * Sets the vector to be unit length, whilst maintaining its direction. + * @brief Sets the vector to be unit length, whilst maintaining its direction. + * */ void Normalize(); /** - * Clamps the vector between minimum and maximum vectors + * @brief Clamps the vector between minimum and maximum vectors. + * * @param [in] min the minimum vector * @param [in] max the maximum vector */ void Clamp( const Vector2& min, const Vector2& max ); /** - * Returns the contents of the vector as an array of 2 floats. + * @brief Returns the contents of the vector as an array of 2 floats. + * * The order of the values in this array are as follows: * 0: x (or width) * 1: y (or height) @@ -362,7 +392,8 @@ public: const float* AsFloat() const {return &x;} /** - * Returns the contents of the vector as an array of 2 floats. + * @brief Returns the contents of the vector as an array of 2 floats. + * * The order of the values in this array are as follows: * 0: x (or width) * 1: y (or height) @@ -391,10 +422,14 @@ public: // Data }; +/** + * @brief Size is an alias of Dali::Vector2 + */ typedef Vector2 Size; /** - * Print a Vector2. + * @brief Print a Vector2. + * * @param [in] o The output stream operator. * @param [in] vector The vector to print. * @return The output stream operator. @@ -402,7 +437,8 @@ typedef Vector2 Size; DALI_IMPORT_API std::ostream& operator<< (std::ostream& o, const Vector2& vector); /** - * Returns a vector with components set to the minimum of the corresponding component in a and b. + * @brief Returns a vector with components set to the minimum of the corresponding component in a and b. + * * If a=0,1 and b=1,0 returns a vector of 0,0. * @param [in] a a vector * @param [in] b a vector @@ -414,7 +450,8 @@ inline Vector2 Min( const Vector2& a, const Vector2& b ) } /** - * Returns a vector with components set to the maximum of the corresponding component in a and b. + * @brief Returns a vector with components set to the maximum of the corresponding component in a and b. + * * If a=0,1 and b=1,0 returns a vector of 1,1 * @param [in] a a vector * @param [in] b a vector @@ -426,7 +463,8 @@ inline Vector2 Max( const Vector2& a, const Vector2& b ) } /** - * Clamps each of vector v's components between minimum and maximum values + * @brief Clamps each of vector v's components between minimum and maximum values. + * * @param [in] v a vector * @param [in] min the minimum value * @param [in] max the maximum value @@ -435,7 +473,8 @@ inline Vector2 Max( const Vector2& a, const Vector2& b ) DALI_IMPORT_API Vector2 Clamp( const Vector2& v, const float& min, const float& max ); /** - * Fits source size inside the target size maintaining aspect ratio + * @brief Fits source size inside the target size maintaining aspect ratio. + * * @pre source width and height > 0 * @param [in] target size * @param [in] source size @@ -444,7 +483,8 @@ DALI_IMPORT_API Vector2 Clamp( const Vector2& v, const float& min, const float& DALI_IMPORT_API Size FitInside( const Size& target, const Size& source ); /** - * This function does two functions + * @brief Fits or scales to fill. + * * a) If target width and height are non-zero * Fits source size into target aspect ratio * If source is bigger, simply returns target. @@ -460,8 +500,9 @@ DALI_IMPORT_API Size FitInside( const Size& target, const Size& source ); DALI_IMPORT_API Size FitScaleToFill( const Size& target, const Size& source ); /** - * Shrinks source size inside the target size maintaining aspect ratio of source - * If source is smaller than target it returns source + * @brief Shrinks source size inside the target size maintaining aspect ratio of source. + * + * If source is smaller than target it returns source. * @pre source width and height > 0 * @param [in] target size * @param [in] source size diff --git a/capi/dali/public-api/math/vector3.h b/capi/dali/public-api/math/vector3.h index d4cdef6..2d8de7a 100644 --- a/capi/dali/public-api/math/vector3.h +++ b/capi/dali/public-api/math/vector3.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_MATH_MODULE * @{ */ @@ -38,14 +38,14 @@ struct Vector4; class Quaternion; /** - * 3d Vector + * @brief A three dimensional vector. */ struct DALI_IMPORT_API Vector3 { // Construction /** - * Constructor + * @brief Constructor. */ // NOTE // (x width r), (y height g), (z depth b) must be consecutive in memory. @@ -59,7 +59,8 @@ struct DALI_IMPORT_API Vector3 } /** - * Constructor + * @brief Constructor. + * * @param [in] x (or width) component * @param [in] y (or height) component * @param [in] z (or depth) component @@ -72,7 +73,8 @@ struct DALI_IMPORT_API Vector3 } /** - * Conversion constructor from an array of three floats + * @brief Conversion constructor from an array of three floats. + * * @param [in] array of xyz */ explicit Vector3(const float* array) @@ -83,13 +85,15 @@ struct DALI_IMPORT_API Vector3 } /** - * Constructor + * @brief Constructor. + * * @param [in] vec2 Vector2 to create this vector from */ explicit Vector3( const Vector2& vec2 ); /** - * Constructor + * @brief Constructor. + * * @param [in] vec4 Vector4 to create this vector from */ explicit Vector3( const Vector4& vec4 ); @@ -108,7 +112,8 @@ struct DALI_IMPORT_API Vector3 // API /** - * Assignment operator + * @brief Assignment operator. + * * @param[in] array of floats * @return itself */ @@ -122,21 +127,24 @@ struct DALI_IMPORT_API Vector3 } /** - * Assignment operator + * @brief Assignment operator. + * * @param[in] rhs vector to assign. * @return itself */ Vector3& operator=(const Vector2& rhs); /** - * Assignment operator + * @brief Assignment operator. + * * @param[in] rhs vector to assign. * @return itself */ Vector3& operator=(const Vector4& rhs); /** - * Addition operator + * @brief Addition operator. + * * @param[in] rhs vector to add. * @return A vector containing the result of the addition */ @@ -148,7 +156,8 @@ struct DALI_IMPORT_API Vector3 } /** - * Addition assignment operator + * @brief Addition assignment operator. + * * @param[in] rhs vector to add. * @return itself */ @@ -162,7 +171,8 @@ struct DALI_IMPORT_API Vector3 } /** - * Subtraction operator + * @brief Subtraction operator. + * * @param[in] rhs the vector to subtract * @return A vector containing the result of the subtraction */ @@ -174,7 +184,8 @@ struct DALI_IMPORT_API Vector3 } /** - * Subtraction assignment operator + * @brief Subtraction assignment operator. + * * @param[in] rhs the vector to subtract * @return itself */ @@ -188,7 +199,8 @@ struct DALI_IMPORT_API Vector3 } /** - * Multiplication operator + * @brief Multiplication operator. + * * @param[in] rhs the vector to multiply * @return A vector containing the result of the multiplication */ @@ -200,7 +212,8 @@ struct DALI_IMPORT_API Vector3 } /** - * Multiplication operator + * @brief Multiplication operator. + * * @param[in] rhs the float value to scale the vector * @return A vector containing the result of the scaling */ @@ -210,7 +223,8 @@ struct DALI_IMPORT_API Vector3 } /** - * Multiplication assignment operator + * @brief Multiplication assignment operator. + * * @param[in] rhs the vector to multiply * @return itself */ @@ -224,7 +238,8 @@ struct DALI_IMPORT_API Vector3 } /** - * Multiplication assignment operator + * @brief Multiplication assignment operator. + * * @param[in] rhs the float value to scale the vector * @return itself */ @@ -238,14 +253,16 @@ struct DALI_IMPORT_API Vector3 } /** - * Multiplication assignment operator + * @brief Multiplication assignment operator. + * * @param[in] rhs the Quaternion value to multiply the vector by * @return itself */ Vector3& operator*=(const Quaternion& rhs); /** - * Division operator + * @brief Division operator. + * * @param[in] rhs the vector to divide * @return A vector containing the result of the division */ @@ -257,7 +274,8 @@ struct DALI_IMPORT_API Vector3 } /** - * Division operator + * @brief Division operator. + * * @param[in] rhs The float value to scale the vector by * @return A vector containing the result of the scaling */ @@ -267,7 +285,8 @@ struct DALI_IMPORT_API Vector3 } /** - * Division assignment operator + * @brief Division assignment operator. + * * @param[in] rhs the vector to divide * @return itself */ @@ -281,7 +300,8 @@ struct DALI_IMPORT_API Vector3 } /** - * Division assignment operator + * @brief Division assignment operator. + * * @param[in] rhs the float value to scale the vector by * @return itself */ @@ -296,7 +316,8 @@ struct DALI_IMPORT_API Vector3 } /** - * Unary negation operator + * @brief Unary negation operator. + * * @return A vector containg the negation */ Vector3 operator-() const @@ -307,7 +328,8 @@ struct DALI_IMPORT_API Vector3 } /** - * Equality operator + * @brief Equality operator. + * * utilises appropriate machine epsilon values; * * @param[in] rhs The vector to test against @@ -316,7 +338,8 @@ struct DALI_IMPORT_API Vector3 bool operator==(const Vector3& rhs) const; /** - * Inequality operator + * @brief Inequality operator. + * * utilises appropriate machine epsilon values; * * @param[in] rhs The vector to test against @@ -328,7 +351,8 @@ struct DALI_IMPORT_API Vector3 } /** - * Const array subscript operator overload + * @brief Const array subscript operator overload. + * * Asserts if index is out of range. Should be 0, 1 or 2 * @param[in] index Subscript * @return The float at the given index. @@ -341,7 +365,8 @@ struct DALI_IMPORT_API Vector3 } /** - * Mutable array subscript operator overload + * @brief Mutable array subscript operator overload. + * * Asserts if index is out of range. Should be 0, 1 or 2 * @param[in] index Subscript index * @return The float at the given index. @@ -354,7 +379,8 @@ struct DALI_IMPORT_API Vector3 } /** - * Returns the dot product of this vector and another vector. + * @brief Returns the dot product of this vector and another vector. + * * The dot product is the length of one vector in the direction of another vector. * This is great for lighting, threshold testing the angle between two unit vectors, * calculating the distance between two points in a particular direction. @@ -364,7 +390,8 @@ struct DALI_IMPORT_API Vector3 float Dot(const Vector3& other) const; /** - * Returns the cross produce of this vector and another vector. + * @brief Returns the cross produce of this vector and another vector. + * * The cross produce of two vectors is a vector which is perpendicular to the plane of the * two vectors. This is great for calculating normals and making matrices orthogonal. * @@ -374,32 +401,38 @@ struct DALI_IMPORT_API Vector3 Vector3 Cross(const Vector3& other) const; /** - * Returns the length of the vector. + * @brief Returns the length of the vector. + * * @return the length of the vector */ float Length() const; /** - * Returns the length of the vector squared. This is more efficient than Length() for threshold + * @brief Returns the length of the vector squared. + * + * This is more efficient than Length() for threshold * testing as it avoids the use of a square root. * @return the length of the vector squared. */ float LengthSquared() const; /** - * Sets the vector to be unit length, whilst maintaining its direction. + * @brief Sets the vector to be unit length, whilst maintaining its direction. + * */ void Normalize(); /** - * Clamps the vector between minimum and maximum vectors + * @brief Clamps the vector between minimum and maximum vectors. + * * @param [in] min the minimum vector * @param [in] max the maximum vector */ void Clamp( const Vector3& min, const Vector3& max ); /** - * Returns the contents of the vector as an array of 3 floats. + * @brief Returns the contents of the vector as an array of 3 floats. + * * The order of the values in this array are as follows: * 0: x (or width, or r) * 1: y (or height, or g) @@ -410,7 +443,8 @@ struct DALI_IMPORT_API Vector3 const float* AsFloat() const {return &x;} /** - * Returns the contents of the vector as an array of 3 floats. + * @brief Returns the contents of the vector as an array of 3 floats. + * * The order of the values in this array are as follows: * 0: x (or width, or r) * 1: y (or height, or g) @@ -421,32 +455,32 @@ struct DALI_IMPORT_API Vector3 float* AsFloat() {return &x;} /** - * Returns the x & y components (or width & height, or r & g) - * as a Vector2 + * @brief Returns the x & y components (or width & height, or r & g) as a Vector2. + * * @note inlined for performance reasons (generates less code than a function call) * @return the partial vector contents as Vector2 (x,y) */ const Vector2& GetVectorXY() const {return reinterpret_cast(x);} /** - * Returns the x & y components (or width & height, or r & g) - * as a Vector2 + * @brief Returns the x & y components (or width & height, or r & g) as a Vector2. + * * @note inlined for performance reasons (generates less code than a function call) * @return the partial vector contents as Vector2 (x,y) */ Vector2& GetVectorXY() {return reinterpret_cast(x);} /** - * Returns the y & z components (or height & depth, or g & b) - * as a Vector2 + * @brief Returns the y & z components (or height & depth, or g & b) as a Vector2. + * * @note inlined for performance reasons (generates less code than a function call) * @return the partial vector contents as Vector2 (y,z) */ const Vector2& GetVectorYZ() const {return reinterpret_cast(y);} /** - * Returns the y & z components (or height & depth, or g & b) - * as a Vector2 + * @brief Returns the y & z components (or height & depth, or g & b) as a Vector2. + * * @note inlined for performance reasons (generates less code than a function call) * @return the partial vector contents as Vector2 (y,z) */ @@ -479,7 +513,8 @@ struct DALI_IMPORT_API Vector3 }; /** - * Print a Vector3. + * @brief Print a Vector3. + * * @param [in] o The output stream operator. * @param [in] vector The vector to print. * @return The output stream operator. @@ -487,7 +522,8 @@ struct DALI_IMPORT_API Vector3 DALI_IMPORT_API std::ostream& operator<< (std::ostream& o, const Vector3& vector); /** - * Returns a vector with components set to the minimum of the corresponding component in a and b. + * @brief Returns a vector with components set to the minimum of the corresponding component in a and b. + * * If a=0,1,2 and b=2,1,0 returns a vector of 2,1,2. * @param [in] a a vector * @param [in] b a vector @@ -499,7 +535,8 @@ inline Vector3 Min( const Vector3& a, const Vector3& b ) } /** - * Returns a vector with components set to the maximum of the corresponding component in a and b. + * @brief Returns a vector with components set to the maximum of the corresponding component in a and b. + * * If a=0,1 and b=1,0 returns a vector of 1,1 * @param [in] a a vector * @param [in] b a vector @@ -511,7 +548,8 @@ inline Vector3 Max( const Vector3& a, const Vector3& b ) } /** - * Clamps each of vector v's components between minimum and maximum values + * @brief Clamps each of vector v's components between minimum and maximum values. + * * @param [in] v a vector * @param [in] min the minimum value * @param [in] max the maximum value @@ -520,7 +558,8 @@ inline Vector3 Max( const Vector3& a, const Vector3& b ) DALI_IMPORT_API Vector3 Clamp( const Vector3& v, const float& min, const float& max ); /** - * Scales an Actor, such that it fits within its Parent's Size Keeping the aspect ratio. + * @brief Scales an Actor, such that it fits within its Parent's Size Keeping the aspect ratio. + * * f(target, source) = Vector3( min( target.X / source.X, min( target.Y / source.Y, target.Z / source.Z ) ) * If any of the source dimensions is zero it will be ignored in the calculation * @@ -531,7 +570,8 @@ DALI_IMPORT_API Vector3 Clamp( const Vector3& v, const float& min, const float& DALI_IMPORT_API Vector3 FitKeepAspectRatio( const Vector3& target, const Vector3& source ); /** - * Scales an Actor, such that it fill its Parent's Size Keeping the aspect ratio. + * @brief Scales an Actor, such that it fill its Parent's Size Keeping the aspect ratio. + * * f(target, source) = Vector3( max( target.X / source.X, max( target.Y / source.Y, target.Z / source.Z ) ) * If any of the source dimensions is zero it will be ignored in the calculation * @@ -542,7 +582,8 @@ DALI_IMPORT_API Vector3 FitKeepAspectRatio( const Vector3& target, const Vector3 DALI_IMPORT_API Vector3 FillKeepAspectRatio( const Vector3& target, const Vector3& source ); /** - * Scales an Actor, such that it fill its Parent's Size in the X and Y coordinates Keeping the aspect ratio. + * @brief Scales an Actor, such that it fill its Parent's Size in the X and Y coordinates Keeping the aspect ratio. + * * f(target, source) = Vector3( max( target.X / sizeX, target.Y / sizeY ) ) * If any of the source dimensions is zero it will be ignored in the calculation * @@ -553,7 +594,8 @@ DALI_IMPORT_API Vector3 FillKeepAspectRatio( const Vector3& target, const Vector DALI_IMPORT_API Vector3 FillXYKeepAspectRatio( const Vector3& target, const Vector3& source ); /** - * Shrinks source size inside the target size maintaining aspect ratio of source + * @brief Shrinks source size inside the target size maintaining aspect ratio of source. + * * If source is smaller than target it returns source * @pre source width and height > 0 * @param [in] target size diff --git a/capi/dali/public-api/math/vector4.h b/capi/dali/public-api/math/vector4.h index 90d59cc..eafaf46 100644 --- a/capi/dali/public-api/math/vector4.h +++ b/capi/dali/public-api/math/vector4.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_MATH_MODULE * @{ */ @@ -36,19 +36,22 @@ struct Vector2; struct Vector3; /** - * 4 Dimensional Vector + * @brief A four dimensional vector. + * * Components can be used as position or offset (x,y,z,w); color (r,g,b,a) or texture coords(s,t,p,q) */ +struct DALI_IMPORT_API Vector4 +{ // NOTE // xrs, ygt, zbp and waq must be consecutive in memory. // No other data must be added before xrs member. // No virtual methods must be added to this struct. -struct DALI_IMPORT_API Vector4 -{ + // Construction /** - * Default constructor, initializes the vector to 0 + * @brief Default constructor, initializes the vector to 0. + * */ Vector4() : x(0.0f), @@ -59,7 +62,8 @@ struct DALI_IMPORT_API Vector4 } /** - * Conversion constructor from four floats + * @brief Conversion constructor from four floats. + * * @param [in] x (or r/s) component * @param [in] y (or g/t) component * @param [in] z (or b/p) component @@ -75,7 +79,8 @@ struct DALI_IMPORT_API Vector4 /** - * Conversion constructor from an array of four floats + * @brief Conversion constructor from an array of four floats. + * * @param [in] array of either xyzw/rgba/stpq */ explicit Vector4(const float* array) @@ -87,28 +92,31 @@ struct DALI_IMPORT_API Vector4 } /** - * Conversion constructor from Vector2 + * @brief Conversion constructor from Vector2. + * * @param [in] vec2 to copy from, z and w are initialized to 0 */ explicit Vector4( const Vector2& vec2 ); /** - * Conversion constructor from Vector3 + * @brief Conversion constructor from Vector3. + * * @param [in] vec3 to copy from, w is initialized to 0 */ explicit Vector4( const Vector3& vec3 ); // Constants - static const Vector4 ONE; // (1.0f,1.0f,1.0f,1.0f) - static const Vector4 XAXIS; - static const Vector4 YAXIS; - static const Vector4 ZAXIS; - static const Vector4 ZERO; // (0.0f, 0.0f, 0.0f, 0.0f) + static const Vector4 ONE; ///< (1.0f,1.0f,1.0f,1.0f) + static const Vector4 XAXIS; ///< (1.0f,0.0f,0.0f,0.0f) + static const Vector4 YAXIS; ///< (0.0f,1.0f,0.0f,0.0f) + static const Vector4 ZAXIS; ///< (0.0f,0.0f,1.0f,0.0f) + static const Vector4 ZERO; ///< (0.0f, 0.0f, 0.0f, 0.0f) // API /** - * Assignment operator + * @brief Assignment operator. + * * @param [in] array of floats * @return itself */ @@ -123,7 +131,8 @@ struct DALI_IMPORT_API Vector4 } /** - * Assignment operator + * @brief Assignment operator. + * * Only sets x and y. z and w are left as they were * @param [in] vec2 to assign from. * @return itself @@ -131,7 +140,8 @@ struct DALI_IMPORT_API Vector4 Vector4& operator=(const Vector2& vec2 ); /** - * Assignment operator + * @brief Assignment operator. + * * Only sets x and y and z. w is left as it was * @param [in] vec3 to assign from * @return itself @@ -139,7 +149,8 @@ struct DALI_IMPORT_API Vector4 Vector4& operator=(const Vector3& vec3 ); /** - * Addition operator + * @brief Addition operator. + * * @param[in] rhs vector to add. * @return A vector containing the result of the addition */ @@ -151,7 +162,8 @@ struct DALI_IMPORT_API Vector4 } /** - * Addition assignment operator + * @brief Addition assignment operator. + * * @param[in] rhs vector to add. * @return itself */ @@ -166,7 +178,8 @@ struct DALI_IMPORT_API Vector4 } /** - * Subtraction operator + * @brief Subtraction operator. + * * @param[in] rhs the vector to subtract * @return A vector containing the result of the subtraction */ @@ -180,7 +193,8 @@ struct DALI_IMPORT_API Vector4 } /** - * Subtraction assignment operator + * @brief Subtraction assignment operator. + * * @param[in] rhs the vector to subtract * @return itself */ @@ -195,7 +209,8 @@ struct DALI_IMPORT_API Vector4 } /** - * Multiplication operator + * @brief Multiplication operator. + * * @param[in] rhs the vector to multiply * @return A vector containing the result of the multiplication */ @@ -207,7 +222,8 @@ struct DALI_IMPORT_API Vector4 } /** - * Multiplication operator + * @brief Multiplication operator. + * * @param[in] rhs the float value to scale the vector * @return A vector containing the result of the scaling */ @@ -217,7 +233,8 @@ struct DALI_IMPORT_API Vector4 } /** - * Multiplication assignment operator + * @brief Multiplication assignment operator. + * * @param[in] rhs the vector to multiply * @return itself */ @@ -232,7 +249,8 @@ struct DALI_IMPORT_API Vector4 } /** - * Multiplication assignment operator + * @brief Multiplication assignment operator. + * * @param[in] rhs the float value to scale the vector * @return itself */ @@ -247,7 +265,8 @@ struct DALI_IMPORT_API Vector4 } /** - * Division operator + * @brief Division operator. + * * @param[in] rhs the vector to divide * @return A vector containing the result of the division */ @@ -259,7 +278,8 @@ struct DALI_IMPORT_API Vector4 } /** - * Division operator + * @brief Division operator. + * * @param[in] rhs The float value to scale the vector by * @return A vector containing the result of the scaling */ @@ -270,7 +290,8 @@ struct DALI_IMPORT_API Vector4 } /** - * Division assignment operator + * @brief Division assignment operator. + * * @param[in] rhs the vector to divide * @return itself */ @@ -285,7 +306,8 @@ struct DALI_IMPORT_API Vector4 } /** - * Division assignment operator + * @brief Division assignment operator. + * * @param[in] rhs the float value to scale the vector by * @return itself */ @@ -301,7 +323,8 @@ struct DALI_IMPORT_API Vector4 } /** - * Unary negation operator + * @brief Unary negation operator. + * * @return the negative value */ Vector4 operator-() const @@ -312,7 +335,8 @@ struct DALI_IMPORT_API Vector4 } /** - * Equality operator + * @brief Equality operator. + * * Utilises appropriate machine epsilon values. * * @param[in] rhs The vector to test against @@ -321,7 +345,8 @@ struct DALI_IMPORT_API Vector4 bool operator==(const Vector4 &rhs) const; /** - * Inequality operator + * @brief Inequality operator. + * * Utilises appropriate machine epsilon values. * * @param[in] rhs The vector to test against @@ -333,7 +358,8 @@ struct DALI_IMPORT_API Vector4 } /** - * Const array subscript operator overload + * @brief Const array subscript operator overload. + * * Asserts if index is out of range. Should be 0, 1, 2 or 3 * @param[in] index Subscript * @return The float at the given index @@ -346,7 +372,8 @@ struct DALI_IMPORT_API Vector4 } /** - * Mutable array subscript operator overload + * @brief Mutable array subscript operator overload. + * * Asserts if index is out of range. Should be 0, 1, 2 or 3 * @param[in] index Subscript index * @return The float at the given index @@ -359,7 +386,8 @@ struct DALI_IMPORT_API Vector4 } /** - * Returns the dot product of this vector (4d) and another vector (3d). + * @brief Returns the dot product of this vector (4d) and another vector (3d). + * * The dot product is the length of one vector in the direction of another vector. * This is great for lighting, threshold testing the angle between two unit vectors, * calculating the distance between two points in a particular direction. @@ -369,7 +397,8 @@ struct DALI_IMPORT_API Vector4 float Dot(const Vector3& other) const; /** - * Returns the dot product of this vector and another vector. + * @brief Returns the dot product of this vector and another vector. + * * The dot product is the length of one vector in the direction of another vector. * This is great for lighting, threshold testing the angle between two unit vectors, * calculating the distance between two points in a particular direction. @@ -379,14 +408,16 @@ struct DALI_IMPORT_API Vector4 float Dot(const Vector4& other) const; /** - * Returns the 4d dot product of this vector and another vector. + * @brief Returns the 4d dot product of this vector and another vector. + * * @param [in] other the other vector * @return the dot product */ float Dot4(const Vector4& other) const; /** - * Returns the cross produce of this vector and another vector. + * @brief Returns the cross produce of this vector and another vector. + * * The cross produce of two vectors is a vector which is perpendicular to the plane of the * two vectors. This is great for calculating normals and making matrices orthogonal. * @@ -396,31 +427,39 @@ struct DALI_IMPORT_API Vector4 Vector4 Cross(const Vector4& other) const; /** - * Returns the length of the vector. + * @brief Returns the length of the vector. + * * @return the length. */ float Length() const; /** - * Returns the length of the vector squared. This is faster than using Length() when performing + * @brief Returns the length of the vector squared. + * + * This is faster than using Length() when performing * threshold checks as it avoids use of the square root. + * @return the length of the vector squared. */ float LengthSquared() const; /** - * Normalizes the vector. Sets the vector to unit length whilst maintaining its direction. + * @brief Normalizes the vector. + * + * Sets the vector to unit length whilst maintaining its direction. */ void Normalize(); /** - * Clamps the vector between minimum and maximum vectors + * @brief Clamps the vector between minimum and maximum vectors. + * * @param [in] min the minimum vector * @param [in] max the maximum vector */ void Clamp( const Vector4& min, const Vector4& max ); /** - * Returns the contents of the vector as an array of 4 floats. + * @brief Returns the contents of the vector as an array of 4 floats. + * * The order of the values in this array are as follows: * 0: x (or r, or s) * 1: y (or g, or t) @@ -432,7 +471,8 @@ struct DALI_IMPORT_API Vector4 const float* AsFloat() const {return &x;} /** - * Returns the contents of the vector as an array of 4 floats. + * @brief Returns the contents of the vector as an array of 4 floats. + * * The order of the values in this array are as follows: * 0: x (or r, or s) * 1: y (or g, or t) @@ -477,7 +517,8 @@ struct DALI_IMPORT_API Vector4 }; /** - * Print a Vector4. + * @brief Print a Vector4. + * * @param [in] o The output stream operator. * @param [in] vector The vector to print. * @return The output stream operator. @@ -485,7 +526,8 @@ struct DALI_IMPORT_API Vector4 DALI_IMPORT_API std::ostream& operator<<(std::ostream& o, const Vector4& vector); /** - * Returns a vector with components set to the minimum of the corresponding component in a and b. + * @brief Returns a vector with components set to the minimum of the corresponding component in a and b. + * * If a=0,1,2,3 and b=4,0,1,2 returns a vector of 0,0,1,2 * @param [in] a a vector * @param [in] b a vector @@ -497,7 +539,8 @@ inline Vector4 Min( const Vector4& a, const Vector4& b ) } /** - * Returns a vector with components set to the maximum of the corresponding component in a and b. + * @brief Returns a vector with components set to the maximum of the corresponding component in a and b. + * * If a=0,1,2,3 and b=4,0,1,2 returns a vector of 4,1,2,3 * @param [in] a a vector * @param [in] b a vector @@ -509,7 +552,8 @@ inline Vector4 Max( const Vector4& a, const Vector4& b ) } /** - * Clamps each of vector v's components between minimum and maximum values + * @brief Clamps each of vector v's components between minimum and maximum values. + * * @param [in] v a vector * @param [in] min the minimum value * @param [in] max the maximum value diff --git a/capi/dali/public-api/math/viewport.h b/capi/dali/public-api/math/viewport.h index b6e1bca..15276e7 100644 --- a/capi/dali/public-api/math/viewport.h +++ b/capi/dali/public-api/math/viewport.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_MATH_MODULE * @{ */ @@ -28,6 +28,9 @@ namespace Dali DALI_IMPORT_API { +/** + * @brief Typedef for a viewport ( a rectangle representing a screen area ). + */ typedef Rect Viewport; } // namespace Dali diff --git a/capi/dali/public-api/modeling/material.h b/capi/dali/public-api/modeling/material.h index 6b4c5d6..89e388d 100644 --- a/capi/dali/public-api/modeling/material.h +++ b/capi/dali/public-api/modeling/material.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_MODELING_MODULE * @{ */ @@ -38,17 +38,21 @@ class Material; class Material; -typedef std::vector MaterialContainer; -typedef MaterialContainer::iterator MaterialIter; -typedef MaterialContainer::const_iterator MaterialConstIter; +typedef std::vector MaterialContainer; ///< Container for Dali::Material +typedef MaterialContainer::iterator MaterialIter; ///< Iterator for Dali::MaterialContainer +typedef MaterialContainer::const_iterator MaterialConstIter; ///< Const iterator for Dali::MaterialContainer /** - * Encapsulates the data describing a material + * @brief Encapsulates the data describing a material. + * * Color, opacity, shininess, shading mode, texture/normal/height mapping... */ class Material : public BaseHandle { public: + /** + * @brief How the material's texture is sampled outside the range 0..1 + */ enum MappingMode { MAPPING_MODE_WRAP = 0x0, ///< A texture coordinate u|v is translated to u%1|v%1 @@ -57,27 +61,30 @@ public: MAPPING_MODE_DECAL = 0x3, ///< If the texture coordinates for a pixel are outside [0...1] the texture is not applied to that pixel }; - static const float DEFAULT_OPACITY; - static const float DEFAULT_SHININESS; - static const Vector4 DEFAULT_AMBIENT_COLOR; - static const Vector4 DEFAULT_DIFFUSE_COLOR; - static const Vector4 DEFAULT_SPECULAR_COLOR; - static const Vector4 DEFAULT_EMISSIVE_COLOR; - static const MappingMode DEFAULT_MAPPING_MODE; - static const size_t DEFAULT_DIFFUSE_UV_INDEX; - static const size_t DEFAULT_OPACITY_UV_INDEX; - static const size_t DEFAULT_NORMAL_UV_INDEX; - static const bool DEFAULT_HAS_HEIGHT_MAP; - - /** - * Create an initialized Material. + static const float DEFAULT_OPACITY; ///< 1.0f + static const float DEFAULT_SHININESS; ///< 0.5f + static const Vector4 DEFAULT_AMBIENT_COLOR; ///< (0.2f, 0.2f, 0.2f, 1.0f) + static const Vector4 DEFAULT_DIFFUSE_COLOR; ///< (0.8f, 0.8f, 0.8f, 1.0f) + static const Vector4 DEFAULT_SPECULAR_COLOR; ///< (0.0f, 0.0f, 0.0f, 1.0f) + static const Vector4 DEFAULT_EMISSIVE_COLOR; ///< (0.0f, 0.0f, 0.0f, 1.0f) + static const MappingMode DEFAULT_MAPPING_MODE; ///< Material::MAPPING_MODE_WRAP + static const size_t DEFAULT_DIFFUSE_UV_INDEX; ///< 0 + static const size_t DEFAULT_OPACITY_UV_INDEX; ///< 0 + static const size_t DEFAULT_NORMAL_UV_INDEX; ///< 0 + static const bool DEFAULT_HAS_HEIGHT_MAP; ///< false + + /** + * @brief Create an initialized Material. + * * @param[in] name The material's name * @return A handle to a newly allocated Dali resource. */ static Material New(const std::string& name); /** - * Downcast an Object handle to Material handle. If handle points to a Material object the + * @brief Downcast an Object handle to Material handle. + * + * If handle points to a Material object the * downcast produces valid handle. If not the returned handle is left uninitialized. * @param[in] handle to An object * @return handle to a Material object or an uninitialized handle @@ -85,13 +92,14 @@ public: static Material DownCast( BaseHandle handle ); /** - * Create an uninitialized material; this can be initialized with Material::New() + * @brief Create an uninitialized material; this can be initialized with Material::New(). + * * Calling member functions with an uninitialized Dali::Object is not allowed. */ Material(); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~Material(); @@ -101,229 +109,266 @@ public: using BaseHandle::operator=; /** - * Set the material's name + * @brief Set the material's name. + * * @param[in] name The material's name */ void SetName(const std::string& name); /** - * Get the material's name. + * @brief Get the material's name. */ const std::string& GetName() const; /** - * Set the material's opacity + * @brief Set the material's opacity. + * * @param[in] opacity The new opacity value */ void SetOpacity(const float opacity); /** - * Get the material's opacity + * @brief Get the material's opacity. + * * @return The opacity. */ float GetOpacity() const; /** - * Set the material's shininess (used for specular highlighting) + * @brief Set the material's shininess (used for specular highlighting). + * * @param[in] shininess The new shininess value */ void SetShininess(const float shininess); /** - * Get the material's shininess - * @@return The shininess. + * @brief Get the material's shininess. + * + * @return The shininess. */ float GetShininess() const; /** - * Set the material's ambient color + * @brief Set the material's ambient color. + * * @param[in] color The new color value */ void SetAmbientColor(const Vector4& color); /** - * Get the material's ambient color + * @brief Get the material's ambient color. + * * @return The color value */ const Vector4& GetAmbientColor() const; /** - * Set the material's diffuse color + * @brief Set the material's diffuse color. + * * @param[in] color The new color value */ void SetDiffuseColor(const Vector4& color); /** - * Get the material's diffuse color + * @brief Get the material's diffuse color. + * * @return The color value */ const Vector4& GetDiffuseColor() const; /** - * Set the material's specular color + * @brief Set the material's specular color. + * * @param[in] color The new color value */ void SetSpecularColor(const Vector4& color); /** - * Get the material's specular color + * @brief Get the material's specular color. + * * @return The color value */ const Vector4& GetSpecularColor() const; /** - * Set the material's emissive color + * @brief Set the material's emissive color. + * * @param[in] color The new color value */ void SetEmissiveColor(const Vector4& color); /** - * Get the material's emissive color + * @brief Get the material's emissive color. + * * @return The color value */ const Vector4& GetEmissiveColor() const; /** - * Set the diffuse texture image + * @brief Set the diffuse texture image. + * * @param[in] image The new texture image */ void SetDiffuseTexture(Image image); /** - * Set the diffuse texture image + * @brief Set the diffuse texture image. + * * @param[in] filename The name of the image file */ void SetDiffuseTextureFileName(const std::string filename); /** - * Get the diffuse texture image + * @brief Get the diffuse texture image. + * * @return The texture image */ Image GetDiffuseTexture() const; /** - * Get the diffuse texture image filename + * @brief Get the diffuse texture image filename. + * * @return the filename */ const std::string& GetDiffuseFileName() const; /** - * Set the opacity texture image + * @brief Set the opacity texture image. + * * @param[in] image The new texture image */ void SetOpacityTexture(Image image); /** - * Set the opacity texture image + * @brief Set the opacity texture image. + * * @param[in] filename The opacity texture image filename */ void SetOpacityTextureFileName(const std::string filename); /** - * Get the opacity texture image + * @brief Get the opacity texture image. + * * @return The texture image */ Image GetOpacityTexture() const; /** - * Get the opacity texture image filename + * @brief Get the opacity texture image filename. + * * @return The texture image's filename */ const std::string& GetOpacityTextureFileName() const; /** - * Set the normal/height map texture image + * @brief Set the normal/height map texture image. + * * @param[in] image The new texture image */ void SetNormalMap(Image image); /** - * Set the normal/height map texture image filename + * @brief Set the normal/height map texture image filename. + * * @param[in] filename The new texture image filename */ void SetNormalMapFileName(const std::string filename); /** - * Get the normal/height map texture image + * @brief Get the normal/height map texture image. + * * @return The texture image */ Image GetNormalMap() const; /** - * Get the normal/height map texture image filename + * @brief Get the normal/height map texture image filename. + * * @return The texture image filename */ const std::string& GetNormalMapFileName() const; /** - * Set the U mapping mode + * @brief Set the U mapping mode. + * * @param[in] map The mapping mode */ void SetMapU(const unsigned int map); /** - * Get the U mapping mode + * @brief Get the U mapping mode. + * * @return The mapping mode */ const unsigned int GetMapU() const; /** - * Set the V mapping mode + * @brief Set the V mapping mode. + * * @param[in] map The mapping mode */ void SetMapV(const unsigned int map); /** - * Get the U mapping mode + * @brief Get the U mapping mode. + * * @return The mapping mode */ const unsigned int GetMapV() const; /** - * Set the index into the bound mesh's array of UV's for the diffuse texture coordinates + * @brief Set the index into the bound mesh's array of UV's for the diffuse texture coordinates. + * * @param[in] index The diffuse uv index */ void SetDiffuseUVIndex(const int index); /** - * Get the index into the bound mesh's array of UV's for the diffuse texture coordinates + * @brief Get the index into the bound mesh's array of UV's for the diffuse texture coordinates. + * * @return The uv index */ const unsigned int GetDiffuseUVIndex() const; /** - * Set the index into the bound mesh's array of UV's for the opacity texture coordinates + * @brief Set the index into the bound mesh's array of UV's for the opacity texture coordinates. + * * @param[in] index The opacity uv index */ void SetOpacityUVIndex(const int index); /** - * Get the index into the bound mesh's array of UV's for the opacity texture coordinates + * @brief Get the index into the bound mesh's array of UV's for the opacity texture coordinates. + * * @return The uv index */ const unsigned int GetOpacityUVIndex() const; /** - * Set the index into the bound mesh's array of UV's for the normal/height map texture coordinates + * @brief Set the index into the bound mesh's array of UV's for the normal/height map texture coordinates. + * * @param[in] index The normal/height map uv index */ void SetNormalUVIndex(const int index); /** - * Get the index into the bound mesh's array of UV's for the normal/height map texture coordinates + * @brief Get the index into the bound mesh's array of UV's for the normal/height map texture coordinates. + * * @return The uv index */ const unsigned int GetNormalUVIndex() const; /** - * Set whether the normal texture contains a normal or height map + * @brief Set whether the normal texture contains a normal or height map. + * * @param[in] flag true if the normal map contains a height map */ void SetHasHeightMap(const bool flag); /** - * Get whether the normal texture contains a normal or height map + * @brief Get whether the normal texture contains a normal or height map. + * * @return true if the normal map contains a height map, false otherwise */ const bool GetHasHeightMap() const; @@ -331,7 +376,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] material A pointer to an internal material resource */ explicit DALI_INTERNAL Material(Internal::Material* material); diff --git a/capi/dali/public-api/object/base-handle.h b/capi/dali/public-api/object/base-handle.h index 4d17b9a..9300c93 100644 --- a/capi/dali/public-api/object/base-handle.h +++ b/capi/dali/public-api/object/base-handle.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_OBJECT_MODULE * @{ */ @@ -39,7 +39,8 @@ class BaseObject; class ConnectionTrackerInterface; /** - * Dali::BaseHandle is a handle to an internal Dali resource. + * @brief Dali::BaseHandle is a handle to an internal Dali resource. + * * Each Dali handle consists of a single private pointer, and a set of non-virtual forwarding functions. * This hides the internal implementation, so it may be modified without affecting the public interface. * @@ -57,20 +58,24 @@ class BaseHandle { public: - // Used for null pointer assignment below + /** + * @brief Used for null pointer assignment below + */ class NullType { NullType() { } }; /** - * This constructor is used by Dali New() methods. + * @brief This constructor is used by Dali New() methods. + * * @param [in] handle A pointer to a newly allocated Dali resource */ BaseHandle(Dali::BaseObject* handle); /** - * This constructor provides an uninitialized Dali::BaseHandle. + * @brief This constructor provides an uninitialized Dali::BaseHandle. + * * This should be initialized with a Dali New() method before use. * Methods called on an uninitialized Dali::BaseHandle will assert. * @code @@ -84,18 +89,20 @@ public: BaseHandle(); /** - * Dali::BaseHandle is intended as a base class + * @brief Dali::BaseHandle is intended as a base class. */ virtual ~BaseHandle(); /** - * This copy constructor is required for (smart) pointer semantics + * @brief This copy constructor is required for (smart) pointer semantics. + * * @param [in] handle A reference to the copied handle */ BaseHandle(const BaseHandle& handle); /** - * This assignment operator is required for (smart) pointer semantics + * @brief This assignment operator is required for (smart) pointer semantics. + * * It makes this handle use the same BaseObject as the copied handle * @param [in] rhs A reference to the copied handle * @return A reference to this handle @@ -103,8 +110,9 @@ public: BaseHandle& operator=(const BaseHandle& rhs); /** - * This method is defined to allow assignment of the NULL value, + * @brief This method is defined to allow assignment of the NULL value, * and will throw an exception if passed any other value. + * * Assigning to NULL is an alias for Reset(). * @param [in] rhs A NULL pointer * @return A reference to this handle @@ -112,7 +120,8 @@ public: BaseHandle& operator=(NullType* rhs); /** - * Connects a void() functor to a specified signal. + * @brief Connects a void() functor to a specified signal. + * * @pre The signal must be available in this object. * @param [in] connectionTracker A connection tracker which can be used to disconnect. * @param [in] signalName Name of the signal to connect to. @@ -126,7 +135,8 @@ public: } /** - * Perform action on this object with the given action name and attributes. + * @brief Perform action on this object with the given action name and attributes. + * * @param [in] actionName The command for the action. * @param [in] attributes The list of attributes for the action. * @return The action is performed by the object or not. @@ -134,7 +144,8 @@ public: bool DoAction(const std::string& actionName, const std::vector& attributes); /** - * Returns the type name for the Handle. + * @brief Returns the type name for the Handle. + * * @return The type name. */ const std::string& GetTypeName() const; @@ -144,7 +155,8 @@ public: // BaseHandle accessors /** - * Retrieve the internal Dali resource. + * @brief Retrieve the internal Dali resource. + * * This is useful for checking the reference count of the internal resource. * This method will assert, if the Dali::BaseHandle has not been initialized. * @return The BaseObject which is referenced by the BaseHandle. @@ -152,7 +164,8 @@ public: BaseObject& GetBaseObject(); /** - * Retrieve the internal Dali resource. + * @brief Retrieve the internal Dali resource. + * * This is useful for checking the reference count of the internal resource. * This method will assert, if the Dali::BaseHandle has not been initialized. * @return The BaseObject which is referenced by the BaseHandle. @@ -160,7 +173,8 @@ public: const BaseObject& GetBaseObject() const; /** - * Resets the handle. + * @brief Resets the handle. + * * If no other handle copies exist, the internal Dali resouce will be deleted. * Calling this is not required i.e. it will happen automatically when a Dali::BaseHandle is destroyed. */ @@ -169,32 +183,37 @@ public: // BaseHandle comparisons - This is a variation of the safe bool idiom /** - * Pointer-to-member type. Objects can be implicitly converted to this for validity checks. + * @brief Pointer-to-member type. + * Objects can be implicitly converted to this for validity checks. */ typedef void (BaseHandle::*BooleanType)() const; /** - * Converts an handle to a BooleanType. + * @brief Converts an handle to a BooleanType. + * * This is useful for checking whether the handle is empty. */ operator BooleanType() const; /** - * Equality operator overload. + * @brief Equality operator overload. + * * @param [in] rhs A reference to the compared handle. * @return true if the handle handles point to the same Dali resource, or if both are NULL. */ bool operator==(const BaseHandle& rhs) const; /** - * Inequality operator overload. + * @brief Inequality operator overload. + * * @param [in] rhs A reference to the compared handle. * @return true if the handle handles point to the different Dali resources. */ bool operator!=(const BaseHandle& rhs) const; /** - * Get the reference counted object pointer. + * @brief Get the reference counted object pointer. + * * @return A pointer to the reference counted object. */ Dali::RefObject* GetObjectPtr() const; @@ -202,7 +221,8 @@ public: private: /** - * Not intended for application developers. + * @brief Not intended for application developers. + * * @param [in] connectionTracker A connection tracker which can be used to disconnect. * @param [in] signalName Name of the signal to connect to. * @param [in] functorDelegate A newly allocatated functor delegate (takes ownership). @@ -211,17 +231,19 @@ private: bool DoConnectSignal( ConnectionTrackerInterface* connectionTracker, const std::string& signalName, FunctorDelegate* functorDelegate ); /** - * Used by the safe bool idiom. + * @brief Used by the safe bool idiom. + * */ void ThisIsSaferThanReturningVoidStar() const {} private: - IntrusivePtr mObjectHandle; + IntrusivePtr mObjectHandle; ///< Object this handle points at. }; /** - * Template wrapper to downcast an base object handle to derived class handle + * @brief Template wrapper to downcast an base object handle to derived class handle. + * * @pre The BaseHandle has been initialized. * @param handle to a base object * @return handle pointer to either a valid deriving handle or an uninitialized handle @@ -234,6 +256,9 @@ T DownCast( BaseHandle handle ) // See also BaseHandle::BooleanType() conversion +/** + * @brief Equality operator + */ template bool operator==(const BaseHandle& lhs, const T& rhs) { @@ -241,6 +266,9 @@ bool operator==(const BaseHandle& lhs, const T& rhs) return lhs == static_cast(rhs); } +/** + * @brief Equality operator + */ template bool operator!=(const BaseHandle& lhs, const T& rhs) { @@ -250,6 +278,9 @@ bool operator!=(const BaseHandle& lhs, const T& rhs) // More Operators +/** + * @brief Less than operator + */ bool operator<(const BaseHandle& lhs, const BaseHandle& rhs); } // namespace Dali diff --git a/capi/dali/public-api/object/base-object.h b/capi/dali/public-api/object/base-object.h index 95d1a03..74e5940 100644 --- a/capi/dali/public-api/object/base-object.h +++ b/capi/dali/public-api/object/base-object.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_OBJECT_MODULE * @{ */ @@ -34,14 +34,15 @@ namespace Dali DALI_IMPORT_API class BaseHandle; /** - * A base class for objects. + * @brief A base class for objects. */ class BaseObject : public Dali::RefObject { public: /** - * Connects a void() functor to a specified signal. + * @brief Connects a void() functor to a specified signal. + * * @pre The signal must be available in this object. * @param [in] connectionTracker A connection tracker which can be used to disconnect. * @param [in] signalName Name of the signal to connect to. @@ -74,22 +75,22 @@ public: // Not intended for application developers protected: /** - * Default constructor. + * @brief Default constructor. */ BaseObject(); /** - * A reference counted object may only be deleted by calling Unreference() + * @brief A reference counted object may only be deleted by calling Unreference(). */ virtual ~BaseObject(); /** - * Registers the object as created with the Object registry + * @brief Registers the object as created with the Object registry. */ void RegisterObject(); /** - * Unregisters the object from Object registry. + * @brief Unregisters the object from Object registry. */ void UnregisterObject(); @@ -104,18 +105,30 @@ private: // Helpers for public-api forwarding methods -inline BaseObject& GetImplementation(Dali::BaseHandle& object) +/** + * @brief Get the implementation of a handle. + * + * @param[in] handle The handle + * @return A reference to the object the handle points at. + */ +inline BaseObject& GetImplementation(Dali::BaseHandle& handle) { - DALI_ASSERT_ALWAYS( object && "BaseObject handle is empty" ); + DALI_ASSERT_ALWAYS( handle && "BaseObject handle is empty" ); - return object.GetBaseObject(); + return handle.GetBaseObject(); } -inline const BaseObject& GetImplementation(const Dali::BaseHandle& object) +/** + * @brief Get the implementation of a handle. + * + * @param[in] handle The handle + * @return A reference to the object the handle points at. + */ +inline const BaseObject& GetImplementation(const Dali::BaseHandle& handle) { - DALI_ASSERT_ALWAYS( object && "BaseObject handle is empty" ); + DALI_ASSERT_ALWAYS( handle && "BaseObject handle is empty" ); - return object.GetBaseObject(); + return handle.GetBaseObject(); } } // namespace Dali @@ -123,4 +136,4 @@ inline const BaseObject& GetImplementation(const Dali::BaseHandle& object) /** * @} */ -#endif // __DALI_BASE_OBJECT_H__ +# endif // __DALI_BASE_OBJECT_H__ diff --git a/capi/dali/public-api/object/constrainable.h b/capi/dali/public-api/object/constrainable.h index 4fbdd7e..17e3998 100644 --- a/capi/dali/public-api/object/constrainable.h +++ b/capi/dali/public-api/object/constrainable.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_OBJECT_MODULE * @{ */ @@ -38,7 +38,7 @@ class Object; class Constraint; /** - * Dali::Constrainable is a handle to an internal property owning Dali object that + * @brief Dali::Constrainable is a handle to an internal property owning Dali object that * can have constraints applied to it. */ class Constrainable : public Handle @@ -46,13 +46,15 @@ class Constrainable : public Handle public: /** - * Create a constrainable object. + * @brief Create a constrainable object. + * * @return A handle to a newly allocated object. */ static Constrainable New(); /** - * This constructor provides an uninitialized Dali::Constrainable. + * @brief This constructor provides an uninitialized Dali::Constrainable. + * * This should be initialized with a Dali New() method before use. * Methods called on an uninitialized Dali::Constrainable will assert. * @code @@ -66,26 +68,30 @@ public: Constrainable(); /** - * Downcast a handle to a custom object. + * @brief Downcast a handle to a custom object. + * * @param[in] handle The handle to cast. * @return A handle to a custom object or an empty handle. */ static Constrainable DownCast( BaseHandle handle ); /** - * Dali::Handle is intended as a base class + * @brief Dali::Handle is intended as a base class. */ virtual ~Constrainable(); /** - * This copy constructor is required for (smart) pointer semantics + * @brief This copy constructor is required for (smart) pointer semantics. + * * @param [in] handle A reference to the copied handle */ Constrainable(const Constrainable& handle); /** - * This assignment operator is required for (smart) pointer semantics + * @brief This assignment operator is required for (smart) pointer semantics. + * * @param [in] rhs A reference to the copied handle + * @return A reference to this */ Constrainable& operator=(const Handle& rhs); @@ -95,7 +101,8 @@ public: using BaseHandle::operator=; /** - * Constrain one of the properties of an Actor. + * @brief Constrain one of the properties of an Actor. + * * @note The constraint will be copied by the Actor. This means that modifying the apply-time etc. * of the constraint, will not affect actors which are already being constrained. * @pre The Actor has been initialized. @@ -105,22 +112,26 @@ public: ActiveConstraint ApplyConstraint( Constraint constraint ); /** - * Remove one constraint from an Object. + * @brief Remove one constraint from an Object. + * * @pre The Object has been intialized. * @param[in] activeConstraint The active-constraint to remove. */ void RemoveConstraint(ActiveConstraint activeConstraint); /** - * Remove all constraints from an Object. + * @brief Remove all constraints from an Object. + * * @pre The object has been initialized. */ void RemoveConstraints(); public: + /** - * This constructor is used by Dali New() methods. + * @brief This constructor is used by Dali New() methods. + * * @param [in] handle A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL Constrainable(Dali::Internal::Object* handle); diff --git a/capi/dali/public-api/object/handle.h b/capi/dali/public-api/object/handle.h index b7e11da..7a613f6 100644 --- a/capi/dali/public-api/object/handle.h +++ b/capi/dali/public-api/object/handle.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_OBJECT_MODULE * @{ */ @@ -45,20 +45,20 @@ class Object; } /** - * Dali::Handle is a handle to an internal property owning Dali object. - * + * @brief Dali::Handle is a handle to an internal property owning Dali object. */ class Handle : public BaseHandle { public: /** - * An Handle's capabilities can be queried using Handle::Supports() + * @brief An Handle's capabilities can be queried using Handle::Supports() */ enum Capability { /** - * Some objects support dynamic property creation at run-time. + * @brief Some objects support dynamic property creation at run-time. + * * New properties are registered by calling RegisterProperty() with an unused property name. */ DYNAMIC_PROPERTIES = 0x01, @@ -67,13 +67,15 @@ public: public: /** - * This constructor is used by Dali New() methods. + * @brief This constructor is used by Dali New() methods. + * * @param [in] handle A pointer to a newly allocated Dali resource */ Handle(Dali::Internal::Object* handle); /** - * This constructor provides an uninitialized Dali::Handle. + * @brief This constructor provides an uninitialized Dali::Handle. + * * This should be initialized with a Dali New() method before use. * Methods called on an uninitialized Dali::Handle will assert. * @code @@ -87,19 +89,23 @@ public: Handle(); /** - * Dali::Handle is intended as a base class + * @brief Dali::Handle is intended as a base class. + * */ virtual ~Handle(); /** - * This copy constructor is required for (smart) pointer semantics + * @brief This copy constructor is required for (smart) pointer semantics. + * * @param [in] handle A reference to the copied handle */ Handle(const Handle& handle); /** - * This assignment operator is required for (smart) pointer semantics + * @brief This assignment operator is required for (smart) pointer semantics. + * * @param [in] rhs A reference to the copied handle + * @return A reference to this */ Handle& operator=(const Handle& rhs); @@ -109,7 +115,9 @@ public: using BaseHandle::operator=; /** - * Downcast to a handle. If not the returned handle is left uninitialized. + * @brief Downcast to a handle. + * + * If not the returned handle is left uninitialized. * @param[in] handle to An object * @return handle or an uninitialized handle */ @@ -118,21 +126,24 @@ public: public: /** - * Query whether an handle supports a given capability. + * @brief Query whether an handle supports a given capability. + * * @param[in] capability The queried capability. * @return True if the capability is supported. */ bool Supports(Capability capability) const; /** - * Query how many properties are provided by an handle. + * @brief Query how many properties are provided by an handle. + * * This may vary between instances of a class, if dynamic properties are supported. * @return The number of properties. */ unsigned int GetPropertyCount() const; /** - * Query the name of a property. + * @brief Query the name of a property. + * * @pre Property::INVALID_INDEX < index < GetPropertyCount(). * @param [in] index The index of the property. * @return The name of the property. @@ -140,14 +151,16 @@ public: const std::string& GetPropertyName(Property::Index index) const; /** - * Query the index of a property. + * @brief Query the index of a property. + * * @param [in] name The name of the property. * @return The index of the property, or Property::INVALID_INDEX if no property exists with the given name. */ Property::Index GetPropertyIndex(std::string name) const; /** - * Query whether a property can be set using SetProperty(). + * @brief Query whether a property can be set using SetProperty(). + * * @pre Property::INVALID_INDEX < index < GetPropertyCount(). * @param [in] index The index of the property. * @return True if the property is writable. @@ -155,7 +168,8 @@ public: bool IsPropertyWritable(Property::Index index) const; /** - * Query whether a writable property can be the target of an animation or constraint. + * @brief Query whether a writable property can be the target of an animation or constraint. + * * @pre Property::INVALID_INDEX < index < GetPropertyCount(). * @param [in] index The index of the property. * @return True if the property is animatable. @@ -163,7 +177,8 @@ public: bool IsPropertyAnimatable(Property::Index index) const; /** - * Query the type of a property. + * @brief Query the type of a property. + * * @pre Property::INVALID_INDEX < index < GetPropertyCount(). * @param [in] index The index of the property. * @return The type of the property. @@ -171,7 +186,8 @@ public: Property::Type GetPropertyType(Property::Index index) const; /** - * Set the value of an existing property. + * @brief Set the value of an existing property. + * * @pre Handle::IsPropertyWritable(index) returns true. * @pre Property::INVALID_INDEX < index < GetPropertyCount(). * @pre The property types match i.e. propertyValue.GetType() is equal to GetPropertyType(index). @@ -181,27 +197,32 @@ public: void SetProperty(Property::Index index, Property::Value propertyValue); /** - * Register a new property. + * @brief Register a new property. + * * @pre The handle supports dynamic properties i.e. Supports(Handle::DYNAMIC_PROPERTIES) returns true. * @pre name is unused i.e. GetPropertyIndex(name) returns PropertyIndex::INVALID. * @param [in] name The name of the property. * @param [in] propertyValue The new value of the property. + * @return The index of the property */ Property::Index RegisterProperty(std::string name, Property::Value propertyValue); /** - * Register a new property. + * @brief Register a new property. + * * Properties can be set as non animatable using property attributes. * @pre The handle supports dynamic properties i.e. Supports(Handle::DYNAMIC_PROPERTIES) returns true. * @pre name is unused i.e. GetPropertyIndex(name) returns PropertyIndex::INVALID. * @param [in] name The name of the property. * @param [in] propertyValue The new value of the property. * @param [in] accessMode The property access mode (writable, animatable etc). + * @return The index of the property */ Property::Index RegisterProperty(std::string name, Property::Value propertyValue, Property::AccessMode accessMode); /** - * Retrieve a property value. + * @brief Retrieve a property value. + * * @pre Property::INVALID_INDEX < index < GetPropertyCount(). * @param [in] index The index of the property. * @return The property value. @@ -209,7 +230,8 @@ public: Property::Value GetProperty(Property::Index index) const; /** - * Convenience function for obtaining a property of a known type. + * @brief Convenience function for obtaining a property of a known type. + * * @pre Property::INVALID_INDEX < index < GetPropertyCount(). * @pre The property types match i.e. PropertyTypes::Get() is equal to GetPropertyType(index). * @param [in] index The index of the property. @@ -224,14 +246,16 @@ public: } /** - * Retrieve all the property indices for this object (including custom properties). + * @brief Retrieve all the property indices for this object (including custom properties). + * * @param[out] indices A container of property indices for this object. * @note the added container is cleared */ void GetPropertyIndices( Property::IndexContainer& indices ) const; /** - * Add a property notification to this object. + * @brief Add a property notification to this object. + * * @pre Property::INVALID_INDEX < index < GetPropertyCount(). * @param [in] index The index of the property. * @param [in] condition The notification will be triggered when this condition is satisfied. @@ -242,7 +266,8 @@ public: const PropertyCondition& condition); /** - * Add a property notification to this object. + * @brief Add a property notification to this object. + * * @pre Property::INVALID_INDEX < index < GetPropertyCount(). * @param [in] index The index of the property. * @param [in] componentIndex Index to the component of a complex property such as a Vector @@ -255,13 +280,14 @@ public: const PropertyCondition& condition); /** - * Remove a property notification from this object. + * @brief Remove a property notification from this object. + * * @param [in] propertyNotification The propertyNotification to be removed. */ void RemovePropertyNotification(Dali::PropertyNotification propertyNotification); /** - * Remove all property notifications from this object. + * @brief Remove all property notifications from this object. */ void RemovePropertyNotifications(); diff --git a/capi/dali/public-api/object/object-registry.h b/capi/dali/public-api/object/object-registry.h index dafd743..3970411 100644 --- a/capi/dali/public-api/object/object-registry.h +++ b/capi/dali/public-api/object/object-registry.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_OBJECT_MODULE * @{ */ @@ -38,7 +38,8 @@ class ObjectRegistry; } /** - * The ObjectRegistry notifies it's observers when an object is created. + * @brief The ObjectRegistry notifies it's observers when an object is created. + * * Handle to the created Object is passed in the call back function. * The Handle is passed as Dali::Object handle, which can be DownCast * to the appropriate type. @@ -57,25 +58,32 @@ class ObjectRegistry : public BaseHandle public: //Signal Names - static const char* const SIGNAL_OBJECT_CREATED; - static const char* const SIGNAL_OBJECT_DESTROYED; + static const char* const SIGNAL_OBJECT_CREATED; ///< Created signal name + static const char* const SIGNAL_OBJECT_DESTROYED; ///< Destroyed signal name // Typedefs - //Object created signal + /** + * @brief Object created signal + */ typedef SignalV2< void (BaseHandle) > ObjectCreatedSignalV2; - //Object destroyed signal + /** + * @brief Object destroyed signal + */ typedef SignalV2< void (const Dali::RefObject*) > ObjectDestroyedSignalV2; /** - * Allows the creation of an empty objectRegistry handle. To retrieve the current objectRegistry, + * @brief Allows the creation of an empty objectRegistry handle. + * + * To retrieve the current objectRegistry, * this handle can be set using Stage::GetCurrent().GetObjectRegistry(). */ ObjectRegistry(); /** - * destructor. + * @brief Destructor. + * * Dali::Object derived classes typically do not contain member data. */ ~ObjectRegistry(); @@ -88,7 +96,8 @@ public: public: // Signals /** - * This signal is emitted when an object is created. + * @brief This signal is emitted when an object is created. + * * A callback of the following type may be connected: * @code * void YourCallbackName(BaseHandle object); @@ -99,7 +108,7 @@ public: // Signals ObjectCreatedSignalV2& ObjectCreatedSignal(); /** - * This signal is emitted when an object is destroyed. + * @brief This signal is emitted when an object is destroyed. * * WARNING: Since this signal is emitted when the object is * in the process of being destroyed, the RefObject pointer @@ -124,7 +133,8 @@ public: // Signals public: // Not intended for application developers /** - * This constructor is used by Dali Get() method + * @brief This constructor is used by Dali Get() method. + * * @param [in] objectRegistry A pointer to a Dali resource */ explicit DALI_INTERNAL ObjectRegistry(Internal::ObjectRegistry* objectRegistry); diff --git a/capi/dali/public-api/object/property-conditions.h b/capi/dali/public-api/object/property-conditions.h index da8c324..30b4867 100644 --- a/capi/dali/public-api/object/property-conditions.h +++ b/capi/dali/public-api/object/property-conditions.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_OBJECT_MODULE * @{ */ @@ -36,30 +36,28 @@ class PropertyCondition; } /** - * PropertyCondition class represents a condition that - * can be evaluated on a Property::Value. + * @brief This represents a condition that can be evaluated on a Property::Value. */ class PropertyCondition : public BaseHandle { public: /** - * Argument container, represents the arguments to be supplied - * to the condition function. + * @brief Argument container, represents the arguments to be supplied to the condition function. */ - typedef std::vector ArgumentContainer; - typedef ArgumentContainer::iterator ArgumentIter; - typedef ArgumentContainer::const_iterator ArgumentConstIter; + typedef std::vector ArgumentContainer; + typedef ArgumentContainer::iterator ArgumentIter; ///< Iterator for Dali::PropertyCondition::ArgumentContainer + typedef ArgumentContainer::const_iterator ArgumentConstIter;///< Const Iterator for Dali::PropertyCondition::ArgumentContainer public: /** - * Constructor for condition clause + * @brief Constructor for condition clause. */ PropertyCondition(); /** - * Destructor + * @brief Destructor. */ ~PropertyCondition(); @@ -71,13 +69,15 @@ public: public: /** - * Retrieve the arguments that this condition uses. + * @brief Retrieve the arguments that this condition uses. + * * @return The arguments used for this condition */ ArgumentContainer GetArguments(); /** - * Retrieve the arguments that this condition uses. + * @brief Retrieve the arguments that this condition uses. + * * @return The arguments used for this condition * @note The container will only be valid as long PropertyCondition is valid. */ @@ -86,8 +86,8 @@ public: }; /** - * LessThanCondition compares - * whether property is less than arg: + * @brief LessThanCondition compares whether property is less than arg. + * * property type: * bool (false = 0.0f, true = 1.0f) * float (float) @@ -95,12 +95,13 @@ public: * vector3 (the 3D length) * vector4 (the 4D length) * @param[in] arg The argument for the condition + * @return A property condition function object */ PropertyCondition LessThanCondition(float arg); /** - * GreaterThanCondition compares - * whether property is greater than arg: + * @brief GreaterThanCondition compares whether property is greater than arg. + * * property type: * bool (false = 0.0f, true = 1.0f) * float (float) @@ -108,12 +109,13 @@ PropertyCondition LessThanCondition(float arg); * vector3 (the 3D length) * vector4 (the 4D length) * @param[in] arg The argument for the condition + * @return A property condition function object */ PropertyCondition GreaterThanCondition(float arg); /** - * InsideCondition compares - * whether property is greater than arg0 and less than arg1: + * @brief InsideCondition compares whether property is greater than arg0 and less than arg1. + * * property type: * bool (false = 0.0f, true = 1.0f) * float (float) @@ -122,12 +124,13 @@ PropertyCondition GreaterThanCondition(float arg); * vector4 (the 4D length) * @param[in] arg0 The first argument for the condition * @param[in] arg1 The second argument for the condition + * @return A property condition function object */ PropertyCondition InsideCondition(float arg0, float arg1); /** - * OutsideCondition compares - * whether property is less than arg0 or greater than arg1: + * @brief OutsideCondition compares whether property is less than arg0 or greater than arg1. + * * property type: * bool (false = 0.0f, true = 1.0f) * float (float) @@ -136,6 +139,7 @@ PropertyCondition InsideCondition(float arg0, float arg1); * vector4 (the 4D length) * @param[in] arg0 The first argument for the condition * @param[in] arg1 The second argument for the condition + * @return A property condition function object */ PropertyCondition OutsideCondition(float arg0, float arg1); diff --git a/capi/dali/public-api/object/property-index.h b/capi/dali/public-api/object/property-index.h index 92b53bb..63330dd 100644 --- a/capi/dali/public-api/object/property-index.h +++ b/capi/dali/public-api/object/property-index.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_OBJECT_MODULE * @{ */ @@ -29,11 +29,12 @@ namespace Dali DALI_IMPORT_API { /** - * PropertyRegistration indices should be between this range. + * @brief PropertyRegistration indices should be between this range. + * * Enumerations are being used here rather than static constants so that switch statements can be * used to compare property indices. */ -enum +enum PropertyRegistrationIndices { PROPERTY_REGISTRATION_START_INDEX = 10000000, ///< The index when registering a property should start from this number PROPERTY_REGISTRATION_MAX_INDEX = 19999999 ///< The maximum index supported when registering a property diff --git a/capi/dali/public-api/object/property-input.h b/capi/dali/public-api/object/property-input.h index 748c8e5..1478796 100644 --- a/capi/dali/public-api/object/property-input.h +++ b/capi/dali/public-api/object/property-input.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_OBJECT_MODULE * @{ */ @@ -36,74 +36,83 @@ class Matrix; class Quaternion; /** - * An abstract interface for receiving property values. + * @brief An abstract interface for receiving property values. */ class PropertyInput { public: /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~PropertyInput() = 0; /** - * Query the type of property input. + * @brief Query the type of property input. + * * @return The property type. */ virtual Property::Type GetType() const = 0; /** - * Retrieve a boolean value. + * @brief Retrieve a boolean value. + * * @pre GetType() returns Property::BOOLEAN. * @return The boolean value. */ virtual const bool& GetBoolean() const = 0; /** - * Retrieve a float value. + * @brief Retrieve a float value. + * * @pre GetType() returns Property::FLOAT. * @return The float value. */ virtual const float& GetFloat() const = 0; /** - * Retrieve a Vector2 value. + * @brief Retrieve a Vector2 value. + * * @pre GetType() returns Property::VECTOR2. * @return The Vector2 value. */ virtual const Vector2& GetVector2() const = 0; /** - * Retrieve a Vector3 value. + * @brief Retrieve a Vector3 value. + * * @pre GetType() returns Property::VECTOR3. * @return The Vector3 value. */ virtual const Vector3& GetVector3() const = 0; /** - * Retrieve a Vector4 value. + * @brief Retrieve a Vector4 value. + * * @pre GetType() returns Property::VECTOR4. * @return The Vector4 value. */ virtual const Vector4& GetVector4() const = 0; /** - * Retrieve a Matrix (3x3) value. + * @brief Retrieve a Matrix (3x3) value. + * * @pre GetType() returns Property::Matrix3. * @return The Matrix value. */ virtual const Matrix3& GetMatrix3() const = 0; /** - * Retrieve a Matrix (4x4) value. + * @brief Retrieve a Matrix (4x4) value. + * * @pre GetType() returns Property::Matrix4. * @return The Matrix value. */ virtual const Matrix& GetMatrix() const = 0; /** - * Retrieve a Quaternion value. + * @brief Retrieve a Quaternion value. + * * @pre GetType() returns Property::Quaternion. * @return The Quaternion value. */ diff --git a/capi/dali/public-api/object/property-notification-declarations.h b/capi/dali/public-api/object/property-notification-declarations.h index 5fd846f..3f16aee 100644 --- a/capi/dali/public-api/object/property-notification-declarations.h +++ b/capi/dali/public-api/object/property-notification-declarations.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_OBJECT_MODULE * @{ */ @@ -34,8 +34,14 @@ namespace Dali DALI_IMPORT_API class PropertyNotification; +/** + * @brief Signal type for Dali::PropertyNotification::NotifySignal(). + */ typedef SignalV2< void (PropertyNotification& source) > PropertyNotifySignalV2; +/** + * @brief Function signature for Dali::PropertyNotification::NotifySignal() signal callbacks. + */ typedef boost::function PropertyNotifyCallbackType; } // namespace Dali diff --git a/capi/dali/public-api/object/property-notification.h b/capi/dali/public-api/object/property-notification.h index afeec7c..867fbc4 100644 --- a/capi/dali/public-api/object/property-notification.h +++ b/capi/dali/public-api/object/property-notification.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_OBJECT_MODULE * @{ */ @@ -37,14 +37,17 @@ class PropertyNotification; } /** - * PropertyNotification is used to issue a notification upon - * a condition of the property being met. For example checking - * if Actor::POSITION_X > 100.0 + * @brief This is used to issue a notification upon a condition of the property being met. + * + * For example checking if Actor::POSITION_X > 100.0. + * @see Dali::PropertyCondition */ class DALI_IMPORT_API PropertyNotification : public BaseHandle { public: - + /** + * @brief Enumeration to describe how to check condition + */ enum NotifyMode { Disabled, ///< Don't notify, regardless of result of Condition @@ -56,21 +59,26 @@ public: public: /** - * Create an uninitialized PropertyNotification; this can be initialized with PropertyNotification::New() + * @brief Create an uninitialized PropertyNotification; this can be initialized with PropertyNotification::New(). + * * Calling member functions with an uninitialized Dali::Object is not allowed. */ PropertyNotification(); /** - * Downcast an Object handle to PropertyNotification. If handle points to an PropertyNotification object the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to PropertyNotification. + * + * If handle points to an PropertyNotification object the downcast + * produces valid handle. If not the returned handle is left + * uninitialized. + * * @param[in] handle to An object * @return handle to a PropertyNotification object or an uninitialized handle */ static PropertyNotification DownCast( BaseHandle handle ); /** - * Destructor + * @brief Destructor. */ virtual ~PropertyNotification(); @@ -80,28 +88,26 @@ public: using BaseHandle::operator=; /** - * Get the condition of this notification + * @brief Get the condition of this notification * * @return The condition is returned */ PropertyCondition GetCondition(); /** - * Get the condition of this notification + * @brief Get the condition of this notification * * @return The condition is returned */ const PropertyCondition& GetCondition() const; /** - * Get the target handle that this notification - * is observing. - * + * @brief Get the target handle that this notification is observing. */ Dali::Handle GetTarget() const; /** - * Get the target handle's property index that this notification + * @brief Get the target handle's property index that this notification * is observing. * * @return The target property. @@ -109,7 +115,7 @@ public: Property::Index GetTargetProperty() const; /** - * Sets the Notification mode. This determines how the property + * @brief Sets the Notification mode. This determines how the property * notification should respond to the result of a condition. * * @param[in] mode Notification mode @@ -117,14 +123,14 @@ public: void SetNotifyMode( NotifyMode mode ); /** - * Retrieves the current Notification mode. + * @brief Retrieves the current Notification mode. * * @return Notification mode. */ NotifyMode GetNotifyMode(); /** - * Gets the result of the last condition check that caused a signal emit, + * @brief Gets the result of the last condition check that caused a signal emit, * useful when using NotifyOnChanged mode and need to know what it changed to. * * @return whether condition result that triggered last emit was true or false @@ -132,7 +138,8 @@ public: bool GetNotifyResult() const; /** - * Connect to this signal to be notified when the notification has occurred. + * @brief Connect to this signal to be notified when the notification has occurred. + * * @return A signal object to Connect() with. */ PropertyNotifySignalV2& NotifySignal(); @@ -140,7 +147,8 @@ public: public: // Not intended for use by Application developers /** - * This constructor is used by Dali New() methods + * @brief This constructor is used by Dali New() methods. + * * @param [in] propertyNotification A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL PropertyNotification(Internal::PropertyNotification* propertyNotification); diff --git a/capi/dali/public-api/object/property-types.h b/capi/dali/public-api/object/property-types.h index c01e8b7..4149614 100644 --- a/capi/dali/public-api/object/property-types.h +++ b/capi/dali/public-api/object/property-types.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_OBJECT_MODULE * @{ */ @@ -38,18 +38,23 @@ namespace Dali DALI_IMPORT_API { +/** + * @brief Template function instances for property getters. + */ namespace PropertyTypes { /** - * Retrieve the name of a property type. + * @brief Retrieve the name of a property type. + * * @param [in] type The property type. * @return The name of this type. */ const char* GetName(Property::Type type); /** - * Retrieve an enumerated property type. + * @brief Retrieve an enumerated property type. + * * New versions of this templated function must be defined for future types. * @return The property type. */ diff --git a/capi/dali/public-api/object/property-value.h b/capi/dali/public-api/object/property-value.h index d4dc325..7e10625 100644 --- a/capi/dali/public-api/object/property-value.h +++ b/capi/dali/public-api/object/property-value.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_OBJECT_MODULE * @{ */ @@ -37,150 +37,176 @@ struct Vector4; class Matrix3; class Matrix; +/** + * @brief Container of Dali::Property::Value%s. + */ typedef std::vector PropertyValueContainer; -typedef PropertyValueContainer::iterator PropertyValueIter; -typedef PropertyValueContainer::const_iterator PropertyValueConstIter; +typedef PropertyValueContainer::iterator PropertyValueIter; ///< Iterator for Dali::PropertyValueContainer +typedef PropertyValueContainer::const_iterator PropertyValueConstIter; ///< Const iterator for Dali::PropertyValueContainer /** - * A value-type representing a property value. + * @brief A value-type representing a property value. */ class Property::Value { public: /** - * Default constructor. + * @brief Default constructor. + * * This creates a property with type Property::INVALID. */ Value(); /** - * Create a boolean property value. + * @brief Create a boolean property value. + * * @param [in] boolValue A boolean value. */ Value(bool boolValue); /** - * Create a float property value. + * @brief Create a float property value. + * * @param [in] floatValue A floating-point value. */ Value(float floatValue); /** - * Create an integer property value. + * @brief Create an integer property value. + * * @param [in] integerValue An integer value. */ Value(int integerValue); /** - * Create an unsigned integer property value. + * @brief Create an unsigned integer property value. + * * @param [in] unsignedIntegerValue An unsinged integer value. */ Value(unsigned int unsignedIntegerValue); /** - * Create a Vector2 property value. + * @brief Create a Vector2 property value. + * * @param [in] vectorValue A vector of 2 floating-point values. */ Value(const Vector2& vectorValue); /** - * Create a Vector3 property value. + * @brief Create a Vector3 property value. + * * @param [in] vectorValue A vector of 3 floating-point values. */ Value(const Vector3& vectorValue); /** - * Create a Vector4 property value. + * @brief Create a Vector4 property value. + * * @param [in] vectorValue A vector of 4 floating-point values. */ Value(const Vector4& vectorValue); /** - * Create a Matrix3 property value. + * @brief Create a Matrix3 property value. + * * @param [in] matrixValue A matrix of 3x3 floating-point values. */ Value(const Matrix3& matrixValue); /** - * Create a Matrix property value. + * @brief Create a Matrix property value. + * * @param [in] matrixValue A matrix of 4x4 floating-point values. */ Value(const Matrix& matrixValue); /** - * Create a Vector4 property value. + * @brief Create a Vector4 property value. + * * @param [in] vectorValue A vector of 4 integer values. */ Value(const Rect& vectorValue); /** - * Create an rotation property value. + * @brief Create an rotation property value. + * * @param [in] angleAxis An angle-axis representing the rotation. */ Value(const AngleAxis& angleAxis); /** - * Create an rotation property value. + * @brief Create an rotation property value. + * * @param [in] quaternion A quaternion representing the rotation. */ Value(const Quaternion& quaternion); /** - * Create an string property value. + * @brief Create an string property value. + * * @param [in] stringValue A string. */ Value(const std::string& stringValue); /** - * Create an string property value. + * @brief Create an string property value. + * * @param [in] stringValue A string. */ Value(const char* stringValue); /** - * Copy a property value. + * @brief Copy a property value. + * * @param [in] value The property value to copy. */ Value(const Value& value); /** - * Create an array property value. + * @brief Create an array property value. + * * @param [in] arrayValue An array */ Value(Property::Array& arrayValue); /** - * Create a map property value. + * @brief Create a map property value. + * * @param [in] mapValue An array */ Value(Property::Map& mapValue); /** - * Explicitly set a type and initialize it. + * @brief Explicitly set a type and initialize it. + * * @param [in] type The property value type. */ explicit Value(Type type); /** - * Assign a property value. + * @brief Assign a property value. + * * @param [in] value The property value to assign from. + * @return a reference to this */ Value& operator=(const Value& value); /** - * Non-virtual destructor. + * @brief Non-virtual destructor. */ ~Value(); /** - * Query the type of this property value. + * @brief Query the type of this property value. + * * @return The type ID. */ Type GetType() const; /** - * Retrieve a specific value. + * @brief Retrieve a specific value. + * * @pre GetType() returns the Property::Type for type T. * @return A value of type T. */ @@ -193,112 +219,128 @@ public: } /** - * Retrieve a boolean value. + * @brief Retrieve a boolean value. + * * @pre GetType() returns Property::BOOLEAN. * @param [out] boolValue On return, a boolean value. */ void Get(bool& boolValue) const; /** - * Retrieve a floating-point value. + * @brief Retrieve a floating-point value. + * * @pre GetType() returns Property::FLOAT. * @param [out] floatValue On return, a floating-point value. */ void Get(float& floatValue) const; /** - * Retrieve an integer value. + * @brief Retrieve an integer value. + * * @pre GetType() returns Property::INTEGER. * @param [out] integerValue On return, an integer value. */ void Get(int& integerValue) const; /** - * Retrieve an unsigned integer value. + * @brief Retrieve an unsigned integer value. + * * @pre GetType() returns Property::UNSIGNED_INTEGER. * @param [out] unsignedIntegerValue On return, an unsigned integer value. */ void Get(unsigned int& unsignedIntegerValue) const; /** - * Retrieve an integer rectangle. + * @brief Retrieve an integer rectangle. + * * @pre GetType() returns Property::RECTANGLE. * @param [out] rect On return, an integer rectangle. */ void Get(Rect& rect) const; /** - * Retrieve a vector value. + * @brief Retrieve a vector value. + * * @pre GetType() returns Property::VECTOR2. * @param [out] vectorValue On return, a vector value. */ void Get(Vector2& vectorValue) const; /** - * Retrieve a vector value. + * @brief Retrieve a vector value. + * * @pre GetType() returns Property::VECTOR3. * @param [out] vectorValue On return, a vector value. */ void Get(Vector3& vectorValue) const; /** - * Retrieve a vector value. + * @brief Retrieve a vector value. + * * @pre GetType() returns Property::VECTOR4. * @param [out] vectorValue On return, a vector value. */ void Get(Vector4& vectorValue) const; /** - * Retrieve a matrix3 value. + * @brief Retrieve a matrix3 value. + * * @pre GetType() returns Property::MATRIX3. * @param [out] matrixValue On return, a matrix3 value. */ void Get(Matrix3& matrixValue) const; /** - * Retrieve a matrix value. + * @brief Retrieve a matrix value. + * * @pre GetType() returns Property::MATRIX. * @param [out] matrixValue On return, a matrix value. */ void Get(Matrix& matrixValue) const; /** - * Retrieve an angle-axis value. + * @brief Retrieve an angle-axis value. + * * @pre GetType() returns Property::ROTATION. * @param [out] angleAxisValue On return, a angle-axis value. */ void Get(AngleAxis& angleAxisValue) const; /** - * Retrieve a quaternion value. + * @brief Retrieve a quaternion value. + * * @pre GetType() returns Property::ROTATION. * @param [out] quaternionValue On return, a quaternion value. */ void Get(Quaternion& quaternionValue) const; /** - * Retrieve an string property value. + * @brief Retrieve an string property value. + * * @pre GetType() returns Property::STRING. * @param [out] stringValue A string. */ void Get(std::string& stringValue) const; /** - * Retrieve an array property value. + * @brief Retrieve an array property value. + * * @pre GetType() returns Property::ARRAY. * @param [out] arrayValue The array as a vector Property Values */ void Get(Property::Array& arrayValue) const; /** - * Retrieve an map property value. + * @brief Retrieve an map property value. + * * @pre GetType() returns Property::MAP. * @param [out] mapValue The map as vector of string and Property Value pairs */ void Get(Property::Map& mapValue) const; /** - * Retrieve a property value from the internal map + * @brief Retrieve a property value from the internal map. + * * @pre GetType() returns Property::MAP. * @param [in] key A string. * @return Property value if avaiable at key or Invalid @@ -306,14 +348,16 @@ public: Property::Value& GetValue(const std::string& key) const; /** - * Retrieve a property value from the internal map + * @brief Retrieve a property value from the internal map. + * * @param [in] key A string. * @return true if the key exists, false if not a map or key does not exist */ bool HasKey(const std::string& key) const; /** - * Retrieve a property value from the internal array or map + * @brief Retrieve a property value from the internal array or map. + * * @pre GetType() returns Property::ARRAY or Property::MAP. * @param [in] index The item index. * @return Key at the index or empty if index is out of range @@ -321,7 +365,8 @@ public: const std::string& GetKey(const int index) const; /** - * Set a property value in the map + * @brief Set a property value in the map. + * * @pre GetType() returns Property::MAP. * @param [in] key A string key. * @param [in] value The value to set. @@ -330,7 +375,8 @@ public: void SetValue(const std::string& key, const Property::Value &value); /** - * Retrieve a property value from the internal array or map + * @brief Retrieve a property value from the internal array or map. + * * @pre GetType() returns Property::ARRAY or Property::MAP. * @param [in] index The item index. * @return Property value if avaiable at key or Invalid @@ -338,7 +384,8 @@ public: Property::Value& GetItem(const int index) const; /** - * Set a property value in the array or map + * @brief Set a property value in the array or map. + * * @pre GetType() returns Property::ARRAY or Property::MAP. * @pre index < GetSize() * @param [in] index The property value index @@ -348,7 +395,8 @@ public: void SetItem(const int index, const Property::Value &value); /** - * Set a property value in the array. + * @brief Set a property value in the array. + * * @pre GetType() returns Property::ARRAY. * @param [in] value The value to set. * @return THe index of the item just added @@ -356,7 +404,9 @@ public: int AppendItem(const Property::Value &value); /** - * Retrieve the length of the array or map. Zero if neither + * @brief Retrieve the length of the array or map. + * + * Zero if neither. * @pre GetType() returns Property::ARRAY or Property::MAP * @return The length of the array */ @@ -365,7 +415,7 @@ public: private: struct Impl; - Impl* mImpl; + Impl* mImpl; ///< Pointer to the implementation }; } // namespace Dali diff --git a/capi/dali/public-api/object/property.h b/capi/dali/public-api/object/property.h index acca905..6ab5ef6 100644 --- a/capi/dali/public-api/object/property.h +++ b/capi/dali/public-api/object/property.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_OBJECT_MODULE * @{ */ @@ -36,12 +36,12 @@ namespace Dali DALI_IMPORT_API class Handle; /** - * An object + property pair. + * @brief An object + property pair. */ struct Property { /** - * A valid property index is zero or greater. + * @brief A valid property index is zero or greater. */ typedef int Index; @@ -51,59 +51,64 @@ struct Property typedef std::vector< Index > IndexContainer; ///< A vector of property indices /** - * A value-type representing a property value. + * @brief A value-type representing a property value. */ class Value; /** - * A Map of property values + * @brief A pair of property values. */ typedef std::pair StringValuePair; + + /** + * @brief A Map of property values. + */ typedef std::vector Map; /** - * An Array of property values + * @brief An Array of property values. */ typedef std::vector Array; /** - * The property types supported. + * @brief The property types supported. */ enum Type { - NONE, - - BOOLEAN, - FLOAT, - INTEGER, - UNSIGNED_INTEGER, - VECTOR2, // a vector array of size=2 with float precision - VECTOR3, - VECTOR4, - MATRIX3, // a 3x3 matrix - MATRIX, // a 4x4 matrix - RECTANGLE, // an integer array of size=4 - ROTATION, // either a quaternion or an axis angle rotation - STRING, - ARRAY, // an array of Property::Value - MAP, // a string key to Property:value mapping - TYPE_COUNT + NONE, ///< No type + + BOOLEAN, ///< A boolean type + FLOAT, ///< A float type + INTEGER, ///< An integer type + UNSIGNED_INTEGER,///< An unsigned integer type + VECTOR2, ///< a vector array of size=2 with float precision + VECTOR3, ///< a vector array of size=3 with float precision + VECTOR4, ///< a vector array of size=4 with float precision + MATRIX3, ///< a 3x3 matrix + MATRIX, ///< a 4x4 matrix + RECTANGLE, ///< an integer array of size=4 + ROTATION, ///< either a quaternion or an axis angle rotation + STRING, ///< A string type + ARRAY, ///< an array of Property::Value + MAP, ///< a string key to Property:value mapping + TYPE_COUNT ///< The number of supported property types }; - /* - * The access mode for custom properties + /** + * @brief The access mode for custom properties */ enum AccessMode { - READ_ONLY, - READ_WRITE, - ANIMATABLE, - ACCESS_MODE_COUNT + READ_ONLY, ///< if the property is read-only + READ_WRITE, ///< If the property is read/writeable + ANIMATABLE, ///< If the property can be animated or constrained + ACCESS_MODE_COUNT ///< The number of access modes }; /** - * Create a Property instance. + * @brief Create a Property instance. + * * @param [in] object A valid handle to the target object. * @param [in] propertyIndex The index of a property. */ @@ -111,7 +116,8 @@ struct Property /** - * Create a Property instance. + * @brief Create a Property instance. + * * @param [in] object A valid handle to the target object. * @param [in] propertyIndex The index of a property. * @param [in] componentIndex Index to a sub component of a property, for use with Vector2, Vector3 and Vector4. -1 for main property (default is -1) @@ -119,7 +125,8 @@ struct Property Property( Handle& object, Property::Index propertyIndex, int componentIndex ); /** - * Create a Property instance. + * @brief Create a Property instance. + * * @note This performs a property index query and is therefore slower than * constructing a Property directly with the index. * @param [in] object A valid handle to the target object. @@ -128,7 +135,8 @@ struct Property Property( Handle& object, const std::string& propertyName ); /** - * Create a Property instance. + * @brief Create a Property instance. + * * @note This performs a property index query and is therefore slower than * constructing a Property directly with the index. * @param [in] object A valid handle to the target object. @@ -138,7 +146,7 @@ struct Property Property( Handle& object, const std::string& propertyName, int componentIndex ); /** - * Non-virtual destructor; Property is not intended as a base class. + * @brief Non-virtual destructor; Property is not intended as a base class. */ ~Property(); diff --git a/capi/dali/public-api/object/ref-object.h b/capi/dali/public-api/object/ref-object.h index e91189e..a9cb7fc 100644 --- a/capi/dali/public-api/object/ref-object.h +++ b/capi/dali/public-api/object/ref-object.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_OBJECT_MODULE * @{ */ @@ -32,7 +32,8 @@ namespace Dali DALI_IMPORT_API class Value; /** - * Base class for reference counted objects. + * @brief Base class for reference counted objects. + * * Typically this should be used with a Boost instrusive pointer, * instead of calling Reference() and Unreference() methods directly. */ @@ -41,18 +42,20 @@ class RefObject public: /** - * Increment the object's reference count. + * @brief Increment the object's reference count. */ void Reference(); /** - * Decrement the object's reference count. + * @brief Decrement the object's reference count. + * * When the reference count drops to zero, the object will self-destruct. */ void Unreference(); /** - * Retrieve the object's reference count. + * @brief Retrieve the object's reference count. + * * @return The reference count */ int ReferenceCount(); @@ -60,31 +63,37 @@ public: protected: /** - * Default constructor + * @brief Default constructor. */ RefObject(); /** - * RefObject is intended as a base class. + * @brief RefObject is intended as a base class. + * * A RefObject may only be deleted when its reference count is zero. */ virtual ~RefObject(); /** - * Copy constructor. + * @brief Copy constructor. + * * The newly copied object will have a reference count of zero. + * @param[in] rhs The object to copy */ RefObject(const RefObject& rhs); /** - * Assignment operator. + * @brief Assignment operator. + * * The newly copied object will have a reference count of zero. + * @param[in] rhs The object to copy + * @return a reference to this */ RefObject& operator=(const RefObject& rhs); private: - volatile int mCount; + volatile int mCount; ///< Reference count }; } // namespace Dali diff --git a/capi/dali/public-api/render-tasks/render-task-list.h b/capi/dali/public-api/render-tasks/render-task-list.h index 9755630..51f4246 100644 --- a/capi/dali/public-api/render-tasks/render-task-list.h +++ b/capi/dali/public-api/render-tasks/render-task-list.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_RENDER_TASKS_MODULE * @{ */ @@ -37,29 +37,34 @@ class RenderTaskList; } /** - * An ordered list of render-tasks. - * These tasks describe how the Dali scene should be rendered; see render-task.h from more details. + * @brief An ordered list of Dali::RenderTask%s. + * + * These tasks describe how the Dali scene should be rendered; @see Dali::RenderTask for more details. */ class RenderTaskList : public BaseHandle { public: /** - * Create an empty RenderTaskList handle. + * @brief Create an empty RenderTaskList handle. + * * This can be initialised with Stage::GetRenderTaskList(). */ RenderTaskList(); /** - * Downcast a handle to RenderTaskList handle. If handle points to a RenderTaskList the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast a handle to RenderTaskList handle. + * + * If handle points to a RenderTaskList the downcast produces valid + * handle. If not the returned handle is left uninitialized. + * * @param[in] handle A handle to an object. * @return A handle to a RenderTaskList or an uninitialized handle. */ static RenderTaskList DownCast( BaseHandle handle ); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~RenderTaskList(); @@ -69,28 +74,32 @@ public: using BaseHandle::operator=; /** - * Create a new RenderTask. + * @brief Create a new RenderTask. + * * This will be appended to the list of render-tasks. * @return A valid handle to a new RenderTask. */ RenderTask CreateTask(); /** - * Remove a RenderTask from the list of render-tasks. + * @brief Remove a RenderTask from the list of render-tasks. * @param[in] task The render-task to remove. */ void RemoveTask( RenderTask task ); /** - * Query the number of render-tasks in the list. + * @brief Query the number of render-tasks in the list. + * * This is ordered i.e. the task with index 0 is the first to be processed each frame. * @return The number of render-tasks. */ unsigned int GetTaskCount() const; /** - * Retrieve a render-task. + * @brief Retrieve a render-task. + * * @pre index should be in range i.e. less than GetTaskCount(). + * @param[in] index The index of the render task to retrieve * @return A handle to the render-task. */ RenderTask GetTask( unsigned int index ) const; @@ -98,7 +107,7 @@ 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] renderTask A pointer to a newly allocated render-task */ explicit DALI_INTERNAL RenderTaskList( Internal::RenderTaskList* renderTask ); diff --git a/capi/dali/public-api/render-tasks/render-task.h b/capi/dali/public-api/render-tasks/render-task.h index 8f2505f..ca738f5 100644 --- a/capi/dali/public-api/render-tasks/render-task.h +++ b/capi/dali/public-api/render-tasks/render-task.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_RENDER_TASKS_MODULE * @{ */ @@ -41,7 +41,8 @@ class RenderTask; } /** - * RenderTasks describe how the Dali scene should be rendered. + * @brief RenderTasks describe how the Dali scene should be rendered. + * * The Stage::GetRenderTaskList() method provides access to an ordered list of render-tasks. * * Each RenderTask must specify the source actors to be rendered, and a camera actor from @@ -73,7 +74,9 @@ class RenderTask; class RenderTask : public Constrainable { public: - + /** + * @brief Typedef for signals sent by this class. + */ typedef SignalV2< void (RenderTask& source) > RenderTaskSignalV2; // Default Properties @@ -82,30 +85,40 @@ public: static const Property::Index CLEAR_COLOR; ///< Property 2, name "clear-color", type VECTOR4 //Signal Names - static const char* const SIGNAL_FINISHED; + static const char* const SIGNAL_FINISHED; ///< Name for Finished signal /** - * A pointer to a function for converting screen to frame-buffer coordinates. + * @brief A pointer to a function for converting screen to frame-buffer coordinates. * @param[in,out] coordinates The screen coordinates to convert where (0,0) is the top-left of the screen. * @return True if the conversion was successful, otherwise coordinates should be unmodified. */ typedef bool (* ScreenToFrameBufferFunction)( Vector2& coordinates ); + + /** + * @brief A pointer to a function for converting screen to frame-buffer coordinates. + * @param[in,out] coordinates The screen coordinates to convert where (0,0) is the top-left of the screen. + * @return True if the conversion was successful, otherwise coordinates should be unmodified. + */ typedef bool (* const ConstScreenToFrameBufferFunction)( Vector2& coordinates ); /** - * The default conversion function returns false for any screen coordinates. + * @brief The default conversion function returns false for any screen coordinates. + * * This effectively disables hit-testing for RenderTasks rendering to a frame buffer. * See also FULLSCREEN_FRAMEBUFFER_FUNCTION below. */ static ConstScreenToFrameBufferFunction DEFAULT_SCREEN_TO_FRAMEBUFFER_FUNCTION; /** - * This conversion function outputs the (unmodified) screen coordinates as frame-buffer coordinates. + * @brief This conversion function outputs the (unmodified) screen coordinates as frame-buffer coordinates. + * * Therefore the contents of an off-screen image is expected to be rendered "full screen". */ static ConstScreenToFrameBufferFunction FULLSCREEN_FRAMEBUFFER_FUNCTION; - // The refresh-rate of the RenderTask. + /** + * @brief The refresh-rate of the RenderTask. + */ enum RefreshRate { REFRESH_ONCE = 0, ///< Process once only e.g. take a snap-shot of the scene. @@ -119,13 +132,16 @@ public: static const unsigned int DEFAULT_REFRESH_RATE; ///< REFRESH_ALWAYS /** - * Create an empty RenderTask handle. + * @brief Create an empty RenderTask handle. + * * This can be initialised with RenderTaskList::CreateRenderTask(). */ RenderTask(); /** - * Downcast a handle to RenderTask handle. If handle points to a RenderTask the + * @brief Downcast a handle to RenderTask handle. + * + * If handle points to a RenderTask the * downcast produces valid handle. If not the returned handle is left uninitialized. * @param[in] handle A handle to an object. * @return A handle to a RenderTask or an uninitialized handle. @@ -133,7 +149,7 @@ public: static RenderTask DownCast( BaseHandle handle ); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~RenderTask(); @@ -143,32 +159,33 @@ public: using BaseHandle::operator=; /** - * Set the actors to be rendered. + * @brief Set the actors to be rendered. * @param[in] actor This actor and its children will be rendered. * If actor is an empty handle, then nothing will be rendered. */ void SetSourceActor( Actor actor ); /** - * Retrieve the actors to be rendered. + * @brief Retrieve the actors to be rendered. * @return This actor and its children will be rendered. */ Actor GetSourceActor() const; /** - * Set whether the RenderTask has exclusive access to the source actors; the default is false. + * @brief Set whether the RenderTask has exclusive access to the source actors; the default is false. * @param[in] exclusive True if the source actors will only be rendered by this render-task. */ void SetExclusive( bool exclusive ); /** - * Query whether the RenderTask has exclusive access to the source actors. + * @brief Query whether the RenderTask has exclusive access to the source actors. * @return True if the source actors will only be rendered by this render-task. */ bool IsExclusive() const; /** - * Set whether the render-task should be considered for input handling; the default is true. + * @brief Set whether the render-task should be considered for input handling; the default is true. + * * The task used for input handling will be last task in the RenderTaskList which has input enabled, * and has a valid source & camera actor. * A RenderTask targetting a frame-buffer can still be hit-tested, provided that the screen->frame-buffer @@ -178,50 +195,52 @@ public: void SetInputEnabled( bool enabled ); /** - * Query whether the render-task should be considered for input handling. + * @brief Query whether the render-task should be considered for input handling. * @return True if the render-task should be considered for input handling. */ bool GetInputEnabled() const; /** - * Set the actor from which the scene is viewed. + * @brief Set the actor from which the scene is viewed. * @param[in] cameraActor The scene is viewed from the perspective of this actor. */ void SetCameraActor( CameraActor cameraActor ); /** - * Retrieve the actor from which the scene is viewed. + * @brief Retrieve the actor from which the scene is viewed. * @return The scene is viewed from the perspective of this actor. */ CameraActor GetCameraActor() const; /** - * Set the frame-buffer used as a render target. + * @brief Set the frame-buffer used as a render target. * @param[in] frameBuffer A valid frame-buffer handle to enable off-screen rendering, or an uninitialized handle to disable. */ void SetTargetFrameBuffer( FrameBufferImage frameBuffer ); /** - * Retrieve the frame-buffer used as a render target. + * @brief Retrieve the frame-buffer used as a render target. * @return A valid frame-buffer handle, or an uninitialised handle if off-screen rendering is disabled. */ FrameBufferImage GetTargetFrameBuffer() const; /** - * Set the function used to convert screen coordinates to frame-buffer coordinates. + * @brief Set the function used to convert screen coordinates to frame-buffer coordinates. + * * This is useful for hit-testing actors which are rendered off-screen. * @param[in] conversionFunction The conversion function. */ void SetScreenToFrameBufferFunction( ScreenToFrameBufferFunction conversionFunction ); /** - * Retrieve the function used to convert screen coordinates to frame-buffer coordinates. + * @brief Retrieve the function used to convert screen coordinates to frame-buffer coordinates. * @return The conversion function. */ ScreenToFrameBufferFunction GetScreenToFrameBufferFunction() const; /** - * Set the actor used to convert screen coordinates to frame-buffer coordinates. + * @brief Set the actor used to convert screen coordinates to frame-buffer coordinates. + * * The local coordinates of the actor are mapped as frame-buffer coordinates. * This is useful for hit-testing actors which are rendered off-screen. * Note: The mapping actor needs to be rendered by the default render task to make the mapping work properly. @@ -230,13 +249,14 @@ public: void SetScreenToFrameBufferMappingActor( Actor mappingActor ); /** - * Retrieve the actor used to convert screen coordinates to frame-buffer coordinates. + * @brief Retrieve the actor used to convert screen coordinates to frame-buffer coordinates. * @return The actor used for conversion. */ Actor GetScreenToFrameBufferMappingActor() const; /** - * Set the GL viewport position used when rendering. + * @brief Set the GL viewport position used when rendering. + * * This specifies the transformation between normalized device coordinates and target window (or frame-buffer) coordinates. * By default this will match the target window or frame-buffer size. * @note Unlike the glViewport method, the x & y coordinates refer to the top-left of the viewport rectangle. @@ -245,13 +265,14 @@ public: void SetViewportPosition( Vector2 position ); /** - * Retrieve the GL viewport position used when rendering. + * @brief Retrieve the GL viewport position used when rendering. * @return The viewport. */ Vector2 GetCurrentViewportPosition() const; /** - * Set the GL viewport size used when rendering. + * @brief Set the GL viewport size used when rendering. + * * This specifies the transformation between normalized device coordinates and target window (or frame-buffer) coordinates. * By default this will match the target window or frame-buffer size. * @param[in] size The viewports size (width,height) @@ -259,13 +280,14 @@ public: void SetViewportSize( Vector2 size ); /** - * Retrieve the GL viewport size used when rendering. + * @brief Retrieve the GL viewport size used when rendering. * @return The viewport. */ Vector2 GetCurrentViewportSize() const; /** - * Set the GL viewport used when rendering. + * @brief Set the GL viewport used when rendering. + * * This specifies the transformation between normalized device coordinates and target window (or frame-buffer) coordinates. * By default this will match the target window or frame-buffer size. * @note Unlike the glViewport method, the x & y coordinates refer to the top-left of the viewport rectangle. @@ -274,40 +296,47 @@ public: void SetViewport( Viewport viewport ); /** - * Retrieve the GL viewport used when rendering. + * @brief Retrieve the GL viewport used when rendering. * @return The viewport. */ Viewport GetViewport() const; /** - * Set the clear color used when SetClearEnabled(true) is used. + * @brief Set the clear color used when SetClearEnabled(true) is used. * @param[in] color The new clear color. */ void SetClearColor( const Vector4& color ); /** - * Retrieve the clear color used when SetClearEnabled(true) is used. + * @brief Retrieve the clear color used when SetClearEnabled(true) is used. * @note This property can be animated; the return value may not match the value written with SetClearColor(). * @return The clear color. */ Vector4 GetClearColor() const; /** - * Set whether the render-task will clear the results of previous render-tasks. The default is false. - * @note The default GL surface is cleared automatically at the beginning of each frame; this setting is only useful when 2+ - * render-tasks are used, and the result of the first task needs to be (partially) cleared before rendering the second. + * @brief Set whether the render-task will clear the results of previous render-tasks. + * + * The default is false. + * + * @note The default GL surface is cleared automatically at the + * beginning of each frame; this setting is only useful when 2+ + * render-tasks are used, and the result of the first task needs to + * be (partially) cleared before rendering the second. + * * @param[in] enabled True if the render-task should clear. */ void SetClearEnabled( bool enabled ); /** - * Query whether the render-task will clear the results of previous render-tasks. + * @brief Query whether the render-task will clear the results of previous render-tasks. * @return True if the render-task should clear. */ bool GetClearEnabled() const; /** - * Set the refresh-rate of the RenderTask. + * @brief Set the refresh-rate of the RenderTask. + * * The default is REFRESH_ALWAYS (1), meaning that the RenderTask will be processed every frame. * It may be desirable to process less frequently e.g. SetRefreshRate(3) will process once every 3 frames. * The REFRESH_ONCE value means that the RenderTask will be processed once only, to take a snap-shot of the scene. @@ -317,7 +346,7 @@ public: void SetRefreshRate( unsigned int refreshRate ); /** - * Query the refresh-rate of the RenderTask. + * @brief Query the refresh-rate of the RenderTask. * @return The refresh-rate. */ unsigned int GetRefreshRate() const; @@ -325,14 +354,14 @@ public: public: // Signals /** - * If the refresh rate is REFRESH_ONCE, connect to this signal to be notified when a RenderTask has finished. + * @brief If the refresh rate is REFRESH_ONCE, connect to this signal to be notified when a RenderTask has finished. */ RenderTaskSignalV2& FinishedSignal(); 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] renderTask A pointer to a newly allocated render-task */ explicit DALI_INTERNAL RenderTask( Internal::RenderTask* renderTask ); diff --git a/capi/dali/public-api/shader-effects/shader-effect.h b/capi/dali/public-api/shader-effects/shader-effect.h index 55fd601..8e932d3 100644 --- a/capi/dali/public-api/shader-effects/shader-effect.h +++ b/capi/dali/public-api/shader-effects/shader-effect.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_SHADER_EFFECTS_MODULE * @{ */ @@ -30,7 +30,8 @@ namespace Dali DALI_IMPORT_API { /** - * DALI_COMPOSE_SHADER macro provides convenient way to write shader source code. + * @brief DALI_COMPOSE_SHADER macro provides a convenient way to write shader source code. + * * We normally use double quotation marks to write a string such as "Hello World". * However many symbols are needed to add multiple lines of string. * We don't need to write quotation marks using this macro at every line. @@ -64,9 +65,8 @@ namespace Internal DALI_INTERNAL class ShaderEffect; } - -/* - * GeometryType determines how geometry is shaped. +/** + * @brief GeometryType determines how geometry is shaped. */ enum GeometryType { @@ -78,7 +78,8 @@ enum GeometryType }; /** - * Shader effects can be added to actors, to provide a visual effect. + * @brief Shader effects provide a visual effect for actors. + * * For a Custom shader you can provide the vertex and fragment shader code as strings. * These shader snippets get concatenated with the default attributes and uniforms. * For a vertex shader this part contains the following code: @@ -154,7 +155,7 @@ class ShaderEffect : public Constrainable { public: /** - * The Extension class is a base class for objects that can be attached to the + * @brief The Extension class is a base class for objects that can be attached to the * ShaderEffects as extensions. * * Extensions are useful to create pimpled implementations of custom shaders. @@ -164,12 +165,12 @@ public: { protected: /** - * Disable default constructor. This a base class is not meant to be initialised on its own. + * @brief Disable default constructor. This a base class is not meant to be initialised on its own. */ Extension(); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~Extension(); }; @@ -191,10 +192,10 @@ public: static const Property::Index PROGRAM; ///< name "program", type MAP; {"vertex-filename":"",...} static const Property::Index GEOMETRY_HINTS; ///< name "geometry-hints", type INT (bitfield) - static const float DEFAULT_GRID_DENSITY; + static const float DEFAULT_GRID_DENSITY; ///< The default density is 40 pixels /** - * Hints for rendering/subdividing geometry + * @brief Hints for rendering/subdividing geometry. */ enum GeometryHints { @@ -207,7 +208,8 @@ public: }; /** - * Coordinate type of the shader uniform + * @brief Coordinate type of the shader uniform. + * * Viewport coordinate types will convert from viewport to view space. * Use this coordinate type if your are doing a transformation in view space. * The texture coordinate type converts a value in actor local space to texture coodinates. @@ -222,13 +224,15 @@ public: }; /** - * Create an empty ShaderEffect. + * @brief Create an empty ShaderEffect. + * * This can be initialised with ShaderEffect::New(...) */ ShaderEffect(); /** - * Create ShaderEffect. + * @brief Create ShaderEffect. + * * @param vertexShader code for the effect. If you pass in an empty string, the default version will be used * @param fragmentShader code for the effect. If you pass in an empty string, the default version will be used * @param type GeometryType to define the shape of the geometry @@ -241,7 +245,7 @@ public: GeometryHints hints = GeometryHints(HINT_NONE) ); /** - * Create ShaderEffect. + * @brief Create ShaderEffect. * @param vertexShaderPrefix code for the effect. It will be inserted before the default uniforms (ideal for \#defines) * @param vertexShader code for the effect. If you pass in an empty string, the default version will be used * @param fragmentShaderPrefix code for the effect. It will be inserted before the default uniforms (ideal for \#defines) @@ -258,7 +262,7 @@ public: GeometryHints hints = GeometryHints(HINT_NONE) ); /** - * Create ShaderEffect. + * @brief Create ShaderEffect. * @param imageVertexShader code for the effect. If you pass in an empty string, the default version will be used * @param imageFragmentShader code for the effect. If you pass in an empty string, the default version will be used * @param textVertexShader code for the effect. If you pass in an empty string, the default version will be used @@ -273,7 +277,7 @@ public: GeometryHints hints = GeometryHints(HINT_NONE) ); /** - * Create ShaderEffect. + * @brief Create ShaderEffect. * @param imageVertexShader code for the effect. If you pass in an empty string, the default version will be used * @param imageFragmentShader code for the effect. If you pass in an empty string, the default version will be used * @param textVertexShader code for the effect. If you pass in an empty string, the default version will be used @@ -296,21 +300,26 @@ public: GeometryHints hints = GeometryHints(HINT_NONE) ); /** - * Downcast an Object handle to ShaderEffect. If handle points to a ShaderEffect the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to ShaderEffect. + * + * If handle points to a ShaderEffect the downcast produces valid + * handle. If not the returned handle is left uninitialized. + * * @param[in] handle to An object * @return handle to a ShaderEffect object or an uninitialized handle */ static ShaderEffect DownCast( BaseHandle handle ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~ShaderEffect(); /** - * Copy constructor + * @brief Copy constructor + * * @param object A reference to a ShaderEffect object */ ShaderEffect(const ShaderEffect& object); @@ -321,14 +330,17 @@ public: using BaseHandle::operator=; /** - * Sets image for using as effect texture. This image texture will be bound to - * the "sEffectTexture" sampler so it can be used in fragment shader for effects + * @brief Sets image for using as effect texture. + * + * This image texture will be bound to the "sEffectTexture" sampler + * so it can be used in fragment shader for effects + * * @param[in] image to use as effect texture */ void SetEffectImage( Image image ); /** - * Set a uniform value. + * @brief Set a uniform value. * This will register a property of type Property::FLOAT; see Object::RegisterProperty() for more details. * If name matches a uniform in the shader source, this value will be uploaded when rendering. * @pre Either the property name is not in use, or a property exists with the correct name & type. @@ -341,7 +353,8 @@ public: UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) ); /** - * Set a uniform value. + * @brief Set a uniform value. + * * This will register a property of type Property::VECTOR2; see Object::RegisterProperty() for more details. * If name matches a uniform in the shader source, this value will be uploaded when rendering. * @pre Either the property name is not in use, or a property exists with the correct name & type. @@ -354,7 +367,8 @@ public: UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) ); /** - * Set a uniform value. + * @brief Set a uniform value. + * * This will register a property of type Property::VECTOR3; see Object::RegisterProperty() for more details. * If name matches a uniform in the shader source, this value will be uploaded when rendering. * @pre Either the property name is not in use, or a property exists with the correct name & type. @@ -367,7 +381,8 @@ public: UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) ); /** - * Set a uniform value. + * @brief Set a uniform value. + * * This will register a property of type Property::VECTOR4; see Object::RegisterProperty() for more details. * If name matches a uniform in the shader source, this value will be uploaded when rendering. * @pre Either the property name is not in use, or a property exists with the correct name & type. @@ -380,7 +395,8 @@ public: UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) ); /** - * Set a uniform value. + * @brief Set a uniform value. + * * This will register a property of type Property::MATRIX; see Object::RegisterProperty() for more details. * If name matches a uniform in the shader source, this value will be uploaded when rendering. * @pre Either the property name is not in use, or a property exists with the correct name & type. @@ -393,7 +409,8 @@ public: UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) ); /** - * Set a uniform value. + * @brief Set a uniform value. + * * This will register a property of type Property::MATRIX3; see Object::RegisterProperty() for more details. * If name matches a uniform in the shader source, this value will be uploaded when rendering. * @pre Either the property name is not in use, or a property exists with the correct name & type. @@ -406,7 +423,9 @@ public: UniformCoordinateType uniformCoordinateType = UniformCoordinateType(COORDINATE_TYPE_DEFAULT) ); /** - * Attach an extension object. This object is reference counted and will be automatically deleted. + * @brief Attach an extension object. + * + * This object is reference counted and will be automatically deleted. * This object can be retrieved back with the GetExtension function. * @param object Pointer to a Extension. * @pre extension is not NULL @@ -414,7 +433,8 @@ public: void AttachExtension( Extension *object ); /** - * Retrieve the attached extension object. + * @brief Retrieve the attached extension object. + * * This object can be set with the AttachExtension function. * @return implementation Pointer to a Extension. * @pre An extension needs to be attached previously. @@ -422,7 +442,8 @@ public: Extension& GetExtension(); /** - * Retrieve the attached extension object. + * @brief Retrieve the attached extension object. + * * This object can be set with the AttachExtension function. * @return implementation Pointer to a Extension. * @pre An extension needs to be attached previously. @@ -433,7 +454,7 @@ 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] effect A pointer to a newly allocated Dali resource. */ explicit DALI_INTERNAL ShaderEffect(Internal::ShaderEffect* effect); diff --git a/capi/dali/public-api/signals/base-signal.h b/capi/dali/public-api/signals/base-signal.h index 888e8ba..e77b3be 100644 --- a/capi/dali/public-api/signals/base-signal.h +++ b/capi/dali/public-api/signals/base-signal.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_SIGNALS_MODULE * @{ */ @@ -33,23 +33,27 @@ namespace Dali DALI_IMPORT_API { /** + * @brief Implementation class for Dali::SignalV2%s. + * * A slot can be connected to many signals * A signal can be connected to many slots * * To provide automatic disconnection when either a signal or the object owning the slot dies, * observers are used. * - * A signal is an object with state. It holds a list of SignalConnections. + * A signal is an object with state. It holds a list of SignalConnection%s. * * E.g. - * Signal OnTouch. mSignalConnections - * | Callback 0 | Signal Observer 0 | - * | Callback 1 | Signal Observer 1 | - * | Callback 2 | Signal Observer 2 | + * Signal OnTouch. mSignalConnections contains + * + * + * + * + *
%Callback 0 Signal Observer 0
%Callback 1 Signal Observer 1
%Callback 2 Signal Observer 2
* - * OnTouch.Emit( ..), will run callbacks 0,1,2. + * OnTouch.Emit() will run callbacks 0, 1 and 2. * - * When the signal is destroyed. SignalDisconnected(...) is called on each Signal Observer. + * When the signal is destroyed. SignalDisconnected() is called on each Signal Observer. * * Slots are just static or member functions, so have no state. E.g. they can't keep * track of how many signals they are connected to. @@ -59,9 +63,11 @@ namespace Dali DALI_IMPORT_API * To keep track of connections between slots and signals, a Connection tracker is used. * It holds a list of SlotConnections. * - * | Callback 0 | Slot Observer 0 | - * | Callback 1 | Slot Observer 1 | - * | Callback 2 | Slot Observer 2 | + * + * + * + * + *
%Callback 0 Slot Observer 0
%Callback 1 Slot Observer 1
%Callback 2 Slot Observer 2
* * When the connection tracker is destroyed, SlotDisconnected() is called on every slot observer ( signal ) * Signals implement the Slot Observer interface, to be told when a slot has disconnected @@ -73,59 +79,69 @@ class BaseSignal : public SlotObserver public: /** - * Constructor. + * @brief Constructor. */ BaseSignal(); /** - * Virtual destructor. + * @brief Virtual destructor. */ virtual ~BaseSignal(); /** - * Query whether there are any connected slots. + * @brief Query whether there are any connected slots. + * * @return True if there are any slots connected to the signal. */ bool Empty() const; /** - * Query the number of slots. + * @brief Query the number of slots. + * * @return The number of slots connected to this signal. */ std::size_t GetConnectionCount() const; // Templated Emit functions for the Signal implementations - // Used to guard against nested Emit() calls + /** + * @brief Used to guard against nested Emit() calls. + */ struct EmitGuard { /** - * Create the guard. + * @brief Create the guard. + * * @param[in,out] flag This flag will be set to true during Emit() calls. */ EmitGuard( bool& flag ); /** - * Non-virtual destructor. + * @brief Non-virtual destructor. + * */ ~EmitGuard(); /** + * @brief Determine if an error occured. + * * @return True if an error occurred i.e. if Emit() was called during Emit() */ bool ErrorOccurred(); - bool* mFlag; + bool* mFlag; ///< Pointer to the emit guard flag. }; /** - * Emit a signal with no parameters. + * @brief Emit a signal with no parameters. + * * @pre Cannot be called from inside the same Signal's Emit methods. */ void Emit(); /** - * Emit a signal with no parameters. + * @brief Emit a signal with no parameters. + * * @pre Cannot be called from inside the same Signal's Emit methods. * @return The value returned by the last callback. */ @@ -164,7 +180,8 @@ public: } /** - * Emit a signal with 1 parameter. + * @brief Emit a signal with 1 parameter. + * * @pre Cannot be called from inside the same Signal's Emit methods. * @param[in] arg0 The first parameter. */ @@ -199,7 +216,8 @@ public: } /** - * Emit a signal with 1 parameter. + * @brief Emit a signal with 1 parameter. + * * @pre Cannot be called from inside the same Signal's Emit methods. * @param[in] arg0 The first parameter. * @return The value returned by the last callback. @@ -239,7 +257,8 @@ public: } /** - * Emit a signal with 2 parameters. + * @brief Emit a signal with 2 parameters. + * * @pre Cannot be called from inside the same Signal's Emit methods. * @param[in] arg0 The first parameter. * @param[in] arg1 The second parameter. @@ -275,7 +294,8 @@ public: } /** - * Emit a signal with 2 parameters. + * @brief Emit a signal with 2 parameters. + * * @pre Cannot be called from inside the same Signal's Emit methods. * @param[in] arg0 The first parameter. * @param[in] arg1 The second parameter. @@ -316,7 +336,8 @@ public: } /** - * Emit a signal with 3 parameters. + * @brief Emit a signal with 3 parameters. + * * @pre Cannot be called from inside the same Signal's Emit methods. * @param[in] arg0 The first parameter. * @param[in] arg1 The second parameter. @@ -353,7 +374,8 @@ public: } /** - * Emit a signal with 3 parameters. + * @brief Emit a signal with 3 parameters. + * * @pre Cannot be called from inside the same Signal's Emit methods. * @param[in] arg0 The first parameter. * @param[in] arg1 The second parameter. @@ -397,26 +419,30 @@ public: // Connect / Disconnect function for use by Signal implementations /** - * Called by Signal implementations, when the user calls Signal.Connect( ... ) + * @brief Called by Signal implementations, when the user calls Signal.Connect( ... ) + * * @param[in] callback A newly allocated callback object (takes ownership). */ void OnConnect( CallbackBase* callback ); /** - * Called by Signal implementations, when the user calls Signal.Disconnect( ... ) + * @brief Called by Signal implementations, when the user calls Signal.Disconnect( ... ) + * * @param[in] callback A newly allocated callback object (takes ownership). */ void OnDisconnect( CallbackBase* callback ); /** - * Called by Signal implementations, when the user calls Signal.Connect( ... ) + * @brief Called by Signal implementations, when the user calls Signal.Connect( ... ) + * * @param[in] tracker The connection tracker. * @param[in] callback A newly allocated callback object (takes ownership). */ void OnConnect( ConnectionTrackerInterface* tracker, CallbackBase* callback ); /** - * Called by Signal implementations, when the user calls Signal.Disconnect( ... ) + * @brief Called by Signal implementations, when the user calls Signal.Disconnect( ... ) + * * @param[in] tracker The connection tracker. * @param[in] callback A newly allocated callback object (takes ownership). */ @@ -432,27 +458,30 @@ private: // SlotObserver interface, to be told when a slot disconnects private: /** - * Returns a callback given an index in to the connection array. + * @brief Returns a callback given an index in to the connection array. + * * @param[in] connectionIndex The index of the callback. * @return The callback, or NULL if the connection has been deleted. */ CallbackBase* GetCallback( std::size_t connectionIndex ) const; /** - * Helper to find whether a callback is connected. + * @brief Helper to find whether a callback is connected. + * * @param[in] callback The call back object. * @return A valid index if the callback is connected. */ int FindCallback( CallbackBase* callback ); /** - * Deletes a connection object from the list of connections. + * @brief Deletes a connection object from the list of connections. + * * @param[in] connectionIndex The index of the callback. */ void DeleteConnection( std::size_t connectionIndex ); /** - * Helper to remove NULL items from mSignalConnections, which is only safe at the end of Emit() + * @brief Helper to remove NULL items from mSignalConnections, which is only safe at the end of Emit() * i.e. not from methods which can be called during a signal Emit(), such as Disconnect(). */ void CleanupConnections(); diff --git a/capi/dali/public-api/signals/callback.h b/capi/dali/public-api/signals/callback.h index b84191b..4aead2d 100644 --- a/capi/dali/public-api/signals/callback.h +++ b/capi/dali/public-api/signals/callback.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_SIGNALS_MODULE * @{ */ @@ -32,29 +32,30 @@ namespace Dali DALI_IMPORT_API class CallbackBase; /** - * Callback base class to hold the data for callback function and member function calls. + * @brief Callback base class to hold the data for callback function and member function calls. */ class CallbackBase { public: /** - * Default constructor + * @brief Default constructor */ CallbackBase(); /** - * Destructor + * @brief Destructor */ ~CallbackBase(); /** - * Resets the object pointer so that we know not to call methods of this object any more + * @brief Resets the object pointer so that we know not to call methods of this object any more. */ void Reset(); /** - * Function to call the function or member function dispatcher + * @brief Function to call the function or member function dispatcher + * * @param[in] callback The callback to call. */ static void Execute( CallbackBase& callback ) @@ -77,7 +78,8 @@ public: } /** - * Function to call the function or member function dispatcher + * @brief Function to call the function or member function dispatcher. + * * @param[in] callback The callback to call. * @return value from the function */ @@ -105,7 +107,8 @@ public: } /** - * Function to call the function or member function dispatcher + * @brief Function to call the function or member function dispatcher. + * * This function template gets instantiated at the call site * @param[in] callback The callback to call. * @param[in] param1 The first parameter to pass into the function. @@ -132,7 +135,8 @@ public: } /** - * Function to call the function or member function dispatcher + * @brief Function to call the function or member function dispatcher. + * * This function template gets instantiated at the call site * @param[in] callback The callback to call. * @param[in] param1 The first parameter to pass into the function. @@ -163,7 +167,8 @@ public: } /** - * Function to call the function or member function dispatcher. + * @brief Function to call the function or member function dispatcher. + * * This function template gets instantiated at the call site. * @param[in] callback The callback to call. * @param[in] param1 The first parameter to pass into the function. @@ -191,11 +196,13 @@ public: } /** - * Function to call the function or member function dispatcher + * @brief Function to call the function or member function dispatcher. + * * This function template gets instantiated at the call site * @param[in] callback The callback to call. * @param[in] param1 The first parameter to pass into the function. * @param[in] param2 The second parameter to pass into the function. + * @return The return value from the function */ template< typename R, typename P1, typename P2 > static R ExecuteReturn( CallbackBase& callback, P1 param1, P2 param2 ) @@ -222,7 +229,8 @@ public: } /** - * Function to call the function or member function dispatcher. + * @brief Function to call the function or member function dispatcher. + * * This function template gets instantiated at the call site. * @param[in] callback The callback to call. * @param[in] param1 The first parameter to pass into the function. @@ -251,12 +259,14 @@ public: } /** - * Function to call the function or member function dispatcher + * @brief Function to call the function or member function dispatcher. + * * This function template gets instantiated at the call site * @param[in] callback The callback to call. * @param[in] param1 The first parameter to pass into the function. * @param[in] param2 The second parameter to pass into the function. * @param[in] param3 The third parameter to pass into the function. + * @return The return value from the function */ template< typename R, typename P1, typename P2, typename P3 > static R ExecuteReturn( CallbackBase& callback, P1 param1, P2 param2, P3 param3 ) @@ -284,32 +294,45 @@ public: protected: // Constructors for deriving classes - /// Function with static linkage + /** + * @brief Function with static linkage + */ typedef void(*Function)(void); - /// Member function + /** + * @brief Member function + */ typedef void (CallbackBase::*MemberFunction)( void ); - /// Used to call the correct member function + /** + * @brief Used to call the correct member function + */ typedef void (*Dispatcher)( CallbackBase& base ); - /// Used to destroy mObjectPointer (NULL if not mObjectPointer is not owned) + /** + * @brief Used to destroy mObjectPointer (NULL if not mObjectPointer is not owned) + */ typedef void(*Destructor)(void* object); /** - * Copy constructor and assignment operator not declared. + * @brief Copy constructor operator not declared. */ CallbackBase( const CallbackBase& rhs ); + /** + * @brief assignment operator not declared. + */ const CallbackBase& operator=( const CallbackBase& rhs ); /** - * Constructor for function with static linkage + * @brief Constructor for function with static linkage. + * * @param[in] function The function to call. */ CallbackBase( Function function ); /** - * Constructor for member function + * @brief Constructor for member function. + * * @param[in] object The object to call (not owned). * @param[in] function The member function of the object. * @param[in] dispatcher Used to call the actual object. @@ -317,7 +340,8 @@ protected: // Constructors for deriving classes CallbackBase( void* object, MemberFunction function, Dispatcher dispatcher ); /** - * Constructor for member function. + * @brief Constructor for member function. + * * @param[in] object The object to call (owned). * @param[in] function The member function of the object. * @param dispatcher Used to call the actual object. @@ -327,35 +351,39 @@ protected: // Constructors for deriving classes public: // Data for deriving classes & Dispatchers - // struct to hold the extra data needed for member functions + /** + * @brief struct to hold the extra data needed for member functions. + */ struct Impl { - Impl(); + Impl(); ///< Default constructor void* mObjectPointer; ///< Object whose member function will be called. Not owned if mDestructorDispatcher is NULL. Dispatcher mMemberFunctionDispatcher; ///< Dispatcher for member functions Destructor mDestructorDispatcher; ///< Destructor for owned objects. NULL if mDestructorDispatcher is not owned. }; - Impl* mImpl; + Impl* mImpl; ///< Implementation pointer union { - MemberFunction mMemberFunction; ///< Pointer to member function - Function mFunction; ///< Static function + MemberFunction mMemberFunction; ///< Pointer to member function + Function mFunction; ///< Static function }; }; -// Non-member equality operator +/** + * @brief Non-member equality operator + */ bool operator==( const CallbackBase& lhs, const CallbackBase& rhs ); /** - * Dispatcher to delete an object + * @brief Dispatcher to delete an object. */ template< class T > struct Destroyer { /** - * Dispatcher to delete an object + * @brief Dispatcher to delete an object. */ static void Delete( void* object ) { @@ -366,13 +394,14 @@ struct Destroyer }; /** - * Dispatcher to call the actual member function + * @brief Dispatcher to call the actual member function. */ template< class T > struct Dispatcher0 { /** - * Call an actual member function. + * @brief Call an actual member function. + * * @param[in] callback The callback information. */ static void Dispatch( CallbackBase& callback ) @@ -386,13 +415,14 @@ struct Dispatcher0 }; /** - * Dispatcher to call the actual member function + * @brief Dispatcher to call the actual member function. */ template< class T, typename P1 > struct Dispatcher1 { /** - * Call an actual member function. + * @brief Call an actual member function. + * * @param[in] callback The callback information. * @param[in] param1 The first parameter to pass to the real member function. */ @@ -407,13 +437,14 @@ struct Dispatcher1 }; /** - * Dispatcher to call the actual member function + * @brief Dispatcher to call the actual member function. */ template< class T, typename P1, typename P2 > struct Dispatcher2 { /** - * Call an actual member function. + * @brief Call an actual member function. + * * @param[in] callback The callback information. * @param[in] param1 The first parameter to pass to the real member function. * @param[in] param2 The second parameter to pass to the real member function. @@ -429,13 +460,14 @@ struct Dispatcher2 }; /** - * Dispatcher to call the actual member function + * @brief Dispatcher to call the actual member function. */ template< class T, typename P1, typename P2, typename P3 > struct Dispatcher3 { /** - * Call an actual member function. + * @brief Call an actual member function. + * * @param[in] callback The callback information. * @param[in] param1 The first parameter to pass to the real member function. * @param[in] param2 The second parameter to pass to the real member function. @@ -452,13 +484,14 @@ struct Dispatcher3 }; /** - * Dispatcher to call the actual member function + * @brief Dispatcher to call the actual member function. */ template< class T, typename R > struct DispatcherReturn0 { /** - * Call an actual member function. + * @brief Call an actual member function. + * * @param[in] callback The callback information. * @return the value. */ @@ -473,15 +506,17 @@ struct DispatcherReturn0 }; /** - * Dispatcher to call the actual member function + * @brief Dispatcher to call the actual member function. */ template< class T, typename R, typename P1 > struct DispatcherReturn1 { /** - * Call an actual member function. + * @brief Call an actual member function. + * * @param[in] callback The callback information. * @param[in] param1 The first parameter to pass to the real member function. + * @return The return value from the function */ static R Dispatch( CallbackBase& callback, P1 param1 ) { @@ -494,16 +529,18 @@ struct DispatcherReturn1 }; /** - * Dispatcher to call the actual member function + * @brief Dispatcher to call the actual member function. */ template< class T, typename R, typename P1, typename P2 > struct DispatcherReturn2 { /** - * Call an actual member function. + * @brief Call an actual member function. + * * @param[in] callback The callback information. * @param[in] param1 The first parameter to pass to the real member function. * @param[in] param2 The second parameter to pass to the real member function. + * @return The return value from the function */ static R Dispatch( CallbackBase& callback, P1 param1, P2 param2 ) { @@ -516,17 +553,19 @@ struct DispatcherReturn2 }; /** - * Dispatcher to call the actual member function + * @brief Dispatcher to call the actual member function. */ template< class T, typename R, typename P1, typename P2, typename P3 > struct DispatcherReturn3 { /** - * Call an actual member function. + * @brief Call an actual member function. + * * @param[in] callback The callback information. * @param[in] param1 The first parameter to pass to the real member function. * @param[in] param2 The second parameter to pass to the real member function. * @param[in] param3 The third parameter to pass to the real member function. + * @return The return value from the function */ static R Dispatch( CallbackBase& callback, P1 param1, P2 param2, P3 param3 ) { @@ -539,13 +578,14 @@ struct DispatcherReturn3 }; /** - * Dispatcher to call a functor + * @brief Dispatcher to call a functor. */ template< class T > struct FunctorDispatcher0 { /** - * Call a function object. + * @brief Call a function object. + * * @param[in] callback The callback information. */ static void Dispatch( CallbackBase& callback ) @@ -557,13 +597,14 @@ struct FunctorDispatcher0 }; /** - * Dispatcher to call a functor + * @brief Dispatcher to call a functor. */ template< class T, typename P1 > struct FunctorDispatcher1 { /** - * Call a function object. + * @brief Call a function object. + * * @param[in] callback The callback information. * @param[in] param1 The first parameter to pass to the real member function. */ @@ -576,13 +617,14 @@ struct FunctorDispatcher1 }; /** - * Dispatcher to call a functor + * @brief Dispatcher to call a functor. */ template< class T, typename P1, typename P2 > struct FunctorDispatcher2 { /** - * Call a function object. + * @brief Call a function object. + * * @param[in] callback The callback information. * @param[in] param1 The first parameter to pass to the real member function. * @param[in] param2 The second parameter to pass to the real member function. @@ -596,13 +638,14 @@ struct FunctorDispatcher2 }; /** - * Dispatcher to call a functor + * @brief Dispatcher to call a functor. */ template< class T, typename P1, typename P2, typename P3 > struct FunctorDispatcher3 { /** - * Call a function object. + * @brief Call a function object. + * * @param[in] callback The callback information. * @param[in] param1 The first parameter to pass to the real member function. * @param[in] param2 The second parameter to pass to the real member function. @@ -617,13 +660,14 @@ struct FunctorDispatcher3 }; /** - * Dispatcher to call a functor + * @brief Dispatcher to call a functor. */ template< class T, typename R > struct FunctorDispatcherReturn0 { /** - * Call a function object. + * @brief Call a function object. + * * @param[in] callback The callback information. * @return the value. */ @@ -636,15 +680,17 @@ struct FunctorDispatcherReturn0 }; /** - * Dispatcher to call a functor + * @brief Dispatcher to call a functor. */ template< class T, typename R, typename P1 > struct FunctorDispatcherReturn1 { /** - * Call a function object. + * @brief Call a function object. + * * @param[in] callback The callback information. * @param[in] param1 The first parameter to pass to the real member function. + * @return The return value from the function */ static R Dispatch( CallbackBase& callback, P1 param1 ) { @@ -655,16 +701,18 @@ struct FunctorDispatcherReturn1 }; /** - * Dispatcher to call a functor + * @brief Dispatcher to call a functor. */ template< class T, typename R, typename P1, typename P2 > struct FunctorDispatcherReturn2 { /** - * Call a function object. + * @brief Call a function object. + * * @param[in] callback The callback information. * @param[in] param1 The first parameter to pass to the real member function. * @param[in] param2 The second parameter to pass to the real member function. + * @return The return value from the function */ static R Dispatch( CallbackBase& callback, P1 param1, P2 param2 ) { @@ -675,17 +723,19 @@ struct FunctorDispatcherReturn2 }; /** - * Dispatcher to call a functor + * @brief Dispatcher to call a functor. */ template< class T, typename R, typename P1, typename P2, typename P3 > struct FunctorDispatcherReturn3 { /** - * Call a function object. + * @brief Call a function object. + * * @param[in] callback The callback information. * @param[in] param1 The first parameter to pass to the real member function. * @param[in] param2 The second parameter to pass to the real member function. * @param[in] param3 The third parameter to pass to the real member function. + * @return The return value from the function */ static R Dispatch( CallbackBase& callback, P1 param1, P2 param2, P3 param3 ) { @@ -696,14 +746,15 @@ struct FunctorDispatcherReturn3 }; /** - * Dispatcher to call a functor. + * @brief Dispatcher to call a functor. * This variant calls a specific void() member function. */ template< class T > struct VoidFunctorDispatcher0 { /** - * Call a function object. + * @brief Call a function object. + * * @param[in] callback The callback information. */ static void Dispatch( CallbackBase& callback ) @@ -717,14 +768,16 @@ struct VoidFunctorDispatcher0 }; /** - * Dispatcher to call a functor + * @brief Dispatcher to call a functor. + * * This variant calls a void() member, ignoring any signal parameters */ template< class T, typename P1 > struct VoidFunctorDispatcher1 { /** - * Call a function object. + * @brief Call a function object. + * * @param[in] callback The callback information. * @param[in] param1 The first parameter to pass to the real member function. */ @@ -739,14 +792,16 @@ struct VoidFunctorDispatcher1 }; /** - * Dispatcher to call a functor + * @brief Dispatcher to call a functor. + * * This variant calls a void() member, ignoring any signal parameters */ template< class T, typename P1, typename P2 > struct VoidFunctorDispatcher2 { /** - * Call a function object. + * @brief Call a function object. + * * @param[in] callback The callback information. * @param[in] param1 The first parameter to pass to the real member function. * @param[in] param2 The second parameter to pass to the real member function. @@ -762,14 +817,16 @@ struct VoidFunctorDispatcher2 }; /** - * Dispatcher to call a functor + * @brief Dispatcher to call a functor. + * * This variant calls a void() member, ignoring any signal parameters */ template< class T, typename P1, typename P2, typename P3 > struct VoidFunctorDispatcher3 { /** - * Call a function object. + * @brief Call a function object. + * * @param[in] callback The callback information. * @param[in] param1 The first parameter to pass to the real member function. * @param[in] param2 The second parameter to pass to the real member function. @@ -786,14 +843,16 @@ struct VoidFunctorDispatcher3 }; /** - * Dispatcher to call a functor + * @brief Dispatcher to call a functor. + * * This variant calls a void() member, and returns a default-constructed value */ template< class T, typename R > struct VoidFunctorDispatcherReturn0 { /** - * Call a function object. + * @brief Call a function object. + * * @param[in] callback The callback information. * @return the value. */ @@ -809,16 +868,19 @@ struct VoidFunctorDispatcherReturn0 }; /** - * Dispatcher to call a functor + * @brief Dispatcher to call a functor. + * * This variant calls a void() member, and returns a default-constructed value */ template< class T, typename R, typename P1 > struct VoidFunctorDispatcherReturn1 { /** - * Call a function object. + * @brief Call a function object. + * * @param[in] callback The callback information. * @param[in] param1 The first parameter to pass to the real member function. + * @return The return value from the function */ static R Dispatch( CallbackBase& callback, P1 param1 ) { @@ -832,17 +894,20 @@ struct VoidFunctorDispatcherReturn1 }; /** - * Dispatcher to call a functor + * @brief Dispatcher to call a functor. + * * This variant calls a void() member, and returns a default-constructed value */ template< class T, typename R, typename P1, typename P2 > struct VoidFunctorDispatcherReturn2 { /** - * Call a function object. + * @brief Call a function object. + * * @param[in] callback The callback information. * @param[in] param1 The first parameter to pass to the real member function. * @param[in] param2 The second parameter to pass to the real member function. + * @return The return value from the function */ static R Dispatch( CallbackBase& callback, P1 param1, P2 param2 ) { @@ -856,18 +921,21 @@ struct VoidFunctorDispatcherReturn2 }; /** - * Dispatcher to call a functor + * @brief Dispatcher to call a functor. + * * This variant calls a void() member, and returns a default-constructed value */ template< class T, typename R, typename P1, typename P2, typename P3 > struct VoidFunctorDispatcherReturn3 { /** - * Call a function object. + * @brief Call a function object. + * * @param[in] callback The callback information. * @param[in] param1 The first parameter to pass to the real member function. * @param[in] param2 The second parameter to pass to the real member function. * @param[in] param3 The third parameter to pass to the real member function. + * @return The return value from the function */ static R Dispatch( CallbackBase& callback, P1 param1, P2 param2, P3 param3 ) { @@ -881,7 +949,8 @@ struct VoidFunctorDispatcherReturn3 }; /** - * Thin template to provide type safety for member function callbacks + * @brief Thin template to provide type safety for member function callbacks. + * * version with two parameters and return value */ template< class T > @@ -890,7 +959,8 @@ class Callback : public CallbackBase public: /** - * Default constructor + * @brief Default constructor. + * */ Callback() : CallbackBase() @@ -898,7 +968,9 @@ public: } /** - * Constructor for member function. Copies the function object + * @brief Constructor for member function. + * + * Copies the function object. * @param[in] object The object to call. * @param[in] memberFunction The member function of the object. */ @@ -945,14 +1017,14 @@ public: }; /** - * Specializations for static function callbacks + * @brief Specializations for static function callbacks. */ class CallbackFunction : public CallbackBase { public: /** - * Default constructor + * @brief Default constructor. */ CallbackFunction() : CallbackBase() @@ -960,7 +1032,8 @@ public: } /** - * Constructors for functions with static linkage + * @brief Constructors for functions with static linkage. + * * @param[in] function The function to call. */ CallbackFunction( void(*function)() ) @@ -998,7 +1071,7 @@ public: }; /** - * Specializations for function object callbacks + * @brief Specializations for function object callbacks. */ template< class T > class CallbackFunctor0 : public CallbackBase @@ -1006,7 +1079,8 @@ class CallbackFunctor0 : public CallbackBase public: /** - * Constructor which copies a function object. + * @brief Constructor which copies a function object. + * * @param[in] object The object to copy. */ CallbackFunctor0( const T& object ) @@ -1016,12 +1090,16 @@ public: reinterpret_cast< CallbackBase::Destructor >( &Destroyer::Delete ) ) { } }; +/** + * @brief Function object callback for connecting void() methods + */ class CallbackFunctorDelegate0 : public CallbackBase { public: /** - * Constructor which copies a function object. + * @brief Constructor which copies a function object. + * * This variant calls a void() member, ignoring any signal parameters. * @param[in] object A newly allocated object (ownership is transferred). */ @@ -1032,13 +1110,17 @@ public: reinterpret_cast< CallbackBase::Destructor >( &Destroyer::Delete ) ) { } }; +/** + * @brief Function object callback for matching callbacks to signal signature. + */ template< class T, typename P1 > class CallbackFunctor1 : public CallbackBase { public: /** - * Constructor which copies a function object. + * @brief Constructor which copies a function object. + * * @param[in] object The object to copy. */ CallbackFunctor1( const T& object ) @@ -1048,13 +1130,17 @@ public: reinterpret_cast< CallbackBase::Destructor >( &Destroyer::Delete ) ) { } }; +/** + * @brief Function object callback for connecting void() methods. + */ template< typename P1 > class CallbackFunctorDelegate1 : public CallbackBase { public: /** - * Constructor which copies a function object. + * @brief Constructor which copies a function object. + * * This variant calls a void() member, ignoring any signal parameters. * @param[in] object The object to copy. */ @@ -1065,13 +1151,17 @@ public: reinterpret_cast< CallbackBase::Destructor >( &Destroyer::Delete ) ) { } }; +/** + * @brief Function object callback for matching callbacks to signal signature + */ template< class T, typename P1, typename P2 > class CallbackFunctor2 : public CallbackBase { public: /** - * Constructor which copies a function object. + * @brief Constructor which copies a function object. + * * @param[in] object The object to copy. */ CallbackFunctor2( const T& object ) @@ -1081,13 +1171,17 @@ public: reinterpret_cast< CallbackBase::Destructor >( &Destroyer::Delete ) ) { } }; +/** + * @brief Function object callback for connecting void() methods + */ template< typename P1, typename P2 > class CallbackFunctorDelegate2 : public CallbackBase { public: /** - * Constructor which copies a function object. + * @brief Constructor which copies a function object. + * * This variant calls a void() member, ignoring any signal parameters. * @param[in] object The object to copy. */ @@ -1098,13 +1192,17 @@ public: reinterpret_cast< CallbackBase::Destructor >( &Destroyer::Delete ) ) { } }; +/** + * @brief Function object callback for matching callbacks to signal signature + */ template< class T, typename P1, typename P2, typename P3 > class CallbackFunctor3 : public CallbackBase { public: /** - * Constructor which copies a function object. + * @brief Constructor which copies a function object. + * * @param[in] object The object to copy. */ CallbackFunctor3( const T& object ) @@ -1114,6 +1212,9 @@ public: reinterpret_cast< CallbackBase::Destructor >( &Destroyer::Delete ) ) { } }; +/** + * @brief Function object callback for connecting void() methods + */ template< typename P1, typename P2, typename P3 > class CallbackFunctorDelegate3 : public CallbackBase { @@ -1121,7 +1222,8 @@ public: /** - * Constructor which copies a function object. + * @brief Constructor which copies a function object. + * * This variant calls a void() member, ignoring any signal parameters. * @param[in] object The object to copy. */ @@ -1132,13 +1234,17 @@ public: reinterpret_cast< CallbackBase::Destructor >( &Destroyer::Delete ) ) { } }; +/** + * @brief Function object callback for matching callbacks to signal signature + */ template< class T, typename R > class CallbackFunctorReturn0 : public CallbackBase { public: /** - * Constructor which copies a function object. + * @brief Constructor which copies a function object. + * * @param[in] object The object to copy. */ CallbackFunctorReturn0( const T& object ) @@ -1148,14 +1254,17 @@ public: reinterpret_cast< CallbackBase::Destructor >( &Destroyer::Delete ) ) { } }; +/** + * @brief Function object callback for connecting void() methods + */ template< typename R > class CallbackFunctorDelegateReturn0 : public CallbackBase { public: - /** - * Constructor which copies a function object. + * @brief Constructor which copies a function object. + * * This variant calls a void() member, ignoring any signal parameters. * @param[in] object The object to copy. */ @@ -1166,13 +1275,17 @@ public: reinterpret_cast< CallbackBase::Destructor >( &Destroyer::Delete ) ) { } }; +/** + * @brief Function object callback for matching callbacks to signal signature + */ template< class T, typename P1, typename R > class CallbackFunctorReturn1 : public CallbackBase { public: /** - * Constructor which copies a function object. + * @brief Constructor which copies a function object. + * * @param[in] object The object to copy. */ CallbackFunctorReturn1( const T& object ) @@ -1182,13 +1295,17 @@ public: reinterpret_cast< CallbackBase::Destructor >( &Destroyer::Delete ) ) { } }; +/** + * @brief Function object callback for connecting void() methods + */ template< typename P1, typename R > class CallbackFunctorDelegateReturn1 : public CallbackBase { public: /** - * Constructor which copies a function object. + * @brief Constructor which copies a function object. + * * This variant calls a void() member, ignoring any signal parameters. * @param[in] object The object to copy. */ @@ -1199,13 +1316,17 @@ public: reinterpret_cast< CallbackBase::Destructor >( &Destroyer::Delete ) ) { } }; +/** + * @brief Function object callback for matching callbacks to signal signature + */ template< class T, typename P1, typename P2, typename R > class CallbackFunctorReturn2 : public CallbackBase { public: /** - * Constructor which copies a function object. + * @brief Constructor which copies a function object. + * * @param[in] object The object to copy. */ CallbackFunctorReturn2( const T& object ) @@ -1215,13 +1336,17 @@ public: reinterpret_cast< CallbackBase::Destructor >( &Destroyer::Delete ) ) { } }; +/** + * @brief Function object callback for connecting void() methods + */ template< typename P1, typename P2, typename R > class CallbackFunctorDelegateReturn2 : public CallbackBase { public: /** - * Constructor which copies a function object. + * @brief Constructor which copies a function object. + * * This variant calls a void() member, ignoring any signal parameters. * @param[in] object The object to copy. */ @@ -1232,13 +1357,17 @@ public: reinterpret_cast< CallbackBase::Destructor >( &Destroyer::Delete ) ) { } }; +/** + * @brief Function object callback for matching callbacks to signal signature + */ template< class T, typename P1, typename P2, typename P3, typename R > class CallbackFunctorReturn3 : public CallbackBase { public: /** - * Constructor which copies a function object. + * @brief Constructor which copies a function object. + * * @param[in] object The object to copy. */ CallbackFunctorReturn3( const T& object ) @@ -1248,13 +1377,17 @@ public: reinterpret_cast< CallbackBase::Destructor >( &Destroyer::Delete ) ) { } }; +/** + * @brief Function object callback for connecting void() methods + */ template< typename P1, typename P2, typename P3, typename R > class CallbackFunctorDelegateReturn3 : public CallbackBase { public: /** - * Constructor which copies a function object. + * @brief Constructor which copies a function object. + * * This variant calls a void() member, ignoring any signal parameters. * @param[in] object The object to copy. */ @@ -1268,7 +1401,8 @@ public: // Callback creation thin templates /** - * Creates a callback from a C function or static member function with no parameters + * @brief Creates a callback from a C function or static member function with no parameters. + * * @param[in] function The function to call. * @return a newly allocated Callback object, ownership transferred to caller */ @@ -1276,36 +1410,85 @@ inline CallbackBase* MakeCallback( void(*function)(void) ) { return new CallbackFunction( function ); } + +/** + * @brief Creates a callback from a C function or static member function with one parameter. + * + * @param[in] function The function to call. + * @return a newly allocated Callback object, ownership transferred to caller + */ template< typename P1 > inline CallbackBase* MakeCallback( void(*function)(P1) ) { return new CallbackFunction( function ); } + +/** + * @brief Creates a callback from a C function or static member function with no parameters and a return type. + * + * @param[in] function The function to call. + * @return a newly allocated Callback object, ownership transferred to caller + */ template< typename R > inline CallbackBase* MakeCallback( R(*function)(void) ) { return new CallbackFunction( function ); } + +/** + * @brief Creates a callback from a C function or static member function with one parameter and a return type. + * + * @param[in] function The function to call. + * @return a newly allocated Callback object, ownership transferred to caller + */ template< typename R, typename P1 > inline CallbackBase* MakeCallback( R(*function)(P1) ) { return new CallbackFunction( function ); } + +/** + * @brief Creates a callback from a C function or static member function with two parameters. + * + * @param[in] function The function to call. + * @return a newly allocated Callback object, ownership transferred to caller + */ template< typename P1, typename P2 > inline CallbackBase* MakeCallback( void(*function)(P1,P2) ) { return new CallbackFunction( function ); } + +/** + * @brief Creates a callback from a C function or static member function with two parameters and a return type. + * + * @param[in] function The function to call. + * @return a newly allocated Callback object, ownership transferred to caller + */ template< typename R, typename P1, typename P2 > inline CallbackBase* MakeCallback( R(*function)(P1,P2) ) { return new CallbackFunction( function ); } + +/** + * @brief Creates a callback from a C function or static member function with three parameters. + * + * @param[in] function The function to call. + * @return a newly allocated Callback object, ownership transferred to caller + */ template< typename P1, typename P2, typename P3 > inline CallbackBase* MakeCallback( void(*function)(P1,P2,P3) ) { return new CallbackFunction( function ); } + +/** + * @brief Creates a callback from a C function or static member function with three parameters and a return type. + * + * @param[in] function The function to call. + * @return a newly allocated Callback object, ownership transferred to caller + */ template< typename R, typename P1, typename P2, typename P3 > inline CallbackBase* MakeCallback( R(*function)(P1,P2,P3) ) { @@ -1313,7 +1496,8 @@ inline CallbackBase* MakeCallback( R(*function)(P1,P2,P3) ) } /** - * Creates a callback from a class member function with no parameters + * @brief Creates a callback from a class member function with no parameters. + * * requires the function to be member of the same class * @param[in] object The object to call. * @param[in] function The member function to call. @@ -1324,46 +1508,126 @@ inline CallbackBase* MakeCallback( T* object, void(T::*function)(void) ) { return new Callback< T >( object, function ); } + +/** + * @brief Creates a callback from a class member function with one parameter. + * + * requires the function to be member of the same class + * @param[in] object The object to call. + * @param[in] function The member function to call. + * @return a newly allocated Callback object, ownership transferred to caller + */ template< class T, typename P1 > inline CallbackBase* MakeCallback( T* object, void(T::*function)(P1) ) { return new Callback< T >( object, function ); } + +/** + * @brief Creates a callback from a class member function with two parameters. + * + * requires the function to be member of the same class + * @param[in] object The object to call. + * @param[in] function The member function to call. + * @return a newly allocated Callback object, ownership transferred to caller + */ template< class T, typename P1, typename P2 > inline CallbackBase* MakeCallback( T* object, void(T::*function)(P1,P2) ) { return new Callback< T >( object, function ); } + +/** + * @brief Creates a callback from a class member function with three parameters. + * + * requires the function to be member of the same class + * @param[in] object The object to call. + * @param[in] function The member function to call. + * @return a newly allocated Callback object, ownership transferred to caller + */ template< class T, typename P1, typename P2, typename P3 > inline CallbackBase* MakeCallback( T* object, void(T::*function)(P1,P2,P3) ) { return new Callback< T >( object, function ); } + +/** + * @brief Creates a callback from a class member function with no parameters and a return type. + * + * requires the function to be member of the same class + * @param[in] object The object to call. + * @param[in] function The member function to call. + * @return a newly allocated Callback object, ownership transferred to caller + */ template< class T, typename R > inline CallbackBase* MakeCallback( T* object, R(T::*function)() ) { return new Callback< T >( object, function ); } + +/** + * @brief Creates a callback from a class member function with one parameter and a return type. + * + * requires the function to be member of the same class + * @param[in] object The object to call. + * @param[in] function The member function to call. + * @return a newly allocated Callback object, ownership transferred to caller + */ template< class T, typename P1, typename R > inline CallbackBase* MakeCallback( T* object, R(T::*function)(P1) ) { return new Callback< T >( object, function ); } + +/** + * @brief Creates a callback from a class member function with two parameters and a return type. + * + * requires the function to be member of the same class + * @param[in] object The object to call. + * @param[in] function The member function to call. + * @return a newly allocated Callback object, ownership transferred to caller + */ template< class T, typename P1, typename P2, typename R > inline CallbackBase* MakeCallback( T* object, R(T::*function)(P1,P2) ) { return new Callback< T >( object, function ); } + +/** + * @brief Creates a callback from a class member function with three parameters and a return type. + * + * requires the function to be member of the same class + * @param[in] object The object to call. + * @param[in] function The member function to call. + * @return a newly allocated Callback object, ownership transferred to caller + */ template< class T, typename P1, typename P2, typename P3, typename R > inline CallbackBase* MakeCallback( T* object, R(T::*function)(P1,P2,P3) ) { return new Callback< T >( object, function ); } + +/** + * @brief Creates a callback from a class's parent member function with no parameters. + * + * requires the function to be member of the same class + * @param[in] object The object to call. + * @param[in] function The member function to call. + * @return a newly allocated Callback object, ownership transferred to caller + */ template< class T, class Base > inline CallbackBase* MakeCallback( T* object, void(Base::*function)(void) ) { return new Callback< T >( object, function ); } +/** + * @brief Creates a callback from a class's parent member function with no parameters. + * + * requires the function to be member of the same class + * @param[in] object The object to call. + * @param[in] function The member function to call. + * @return a newly allocated Callback object, ownership transferred to caller + */ template< class T, class Base > inline CallbackBase* MakeCallback( T& object, void(Base::*function)(void) ) { diff --git a/capi/dali/public-api/signals/connection-tracker-interface.h b/capi/dali/public-api/signals/connection-tracker-interface.h index 5975e0f..2d1c409 100644 --- a/capi/dali/public-api/signals/connection-tracker-interface.h +++ b/capi/dali/public-api/signals/connection-tracker-interface.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_SIGNALS_MODULE * @{ */ @@ -30,7 +30,8 @@ namespace Dali DALI_IMPORT_API { /** - * Interface used to track connections between signals and slots. + * @brief Interface used to track connections between signals and slots. + * * Performs automatic connection and disconnection when either the slot or signal dies. * * @code @@ -54,24 +55,26 @@ class ConnectionTrackerInterface : public SignalObserver public: /** - * Constructor + * @brief Constructor. */ ConnectionTrackerInterface(); /** - * Virtual destructor + * @brief Virtual destructor. */ virtual ~ConnectionTrackerInterface(); /** - * Called when a signal is connected. + * @brief Called when a signal is connected. + * * @param[in] slotObserver The slot observer i.e. a signal. * @param[in] callback The call back. */ virtual void SignalConnected( SlotObserver* slotObserver, CallbackBase* callback ) = 0; /** - * Query the connection count. + * @brief Query the connection count. + * * @return The number of signal/slot connections know by the connection tracker. */ virtual std::size_t GetConnectionCount() const = 0; diff --git a/capi/dali/public-api/signals/connection-tracker.h b/capi/dali/public-api/signals/connection-tracker.h index da957eb..5db0500 100644 --- a/capi/dali/public-api/signals/connection-tracker.h +++ b/capi/dali/public-api/signals/connection-tracker.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_SIGNALS_MODULE * @{ */ @@ -35,24 +35,24 @@ class SlotObserver; class SlotConnection; /** - * Connection tracker concrete implementation + * @brief Connection tracker concrete implementation */ class ConnectionTracker : public ConnectionTrackerInterface { public: /** - * Constructor + * @brief Constructor. */ ConnectionTracker(); /** - * Virtual destructor + * @brief Virtual destructor. */ virtual ~ConnectionTracker(); /** - * Disconnect all signals from this object + * @brief Disconnect all signals from this object. */ void DisconnectAll(); diff --git a/capi/dali/public-api/signals/dali-signal-v2.h b/capi/dali/public-api/signals/dali-signal-v2.h index 105ed4d..c2721c4 100644 --- a/capi/dali/public-api/signals/dali-signal-v2.h +++ b/capi/dali/public-api/signals/dali-signal-v2.h @@ -18,8 +18,39 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_SIGNALS_MODULE * @{ + * + * @section CAPI_DALI_SIGNALS_MODULE_CONNECTION Connecting signals to C++ member functions + * The class should implement Dali::ConnectionTrackerInterface, or inherit from Dali::ConnectionTracker. + * This enforces automatic disconnection when an object is destroyed, so you don't have + * to manually disconnect from signals. + * + * Alternatively, you can use a Dali::SlotDelegate if you don't want to inherit. + * + * E.g: + * @code + * class MyClass : public ConnectionTracker + * { + * + * void Callback( Actor actor, const TouchEvent& event ) + * { + * ... + * } + * + * void Init() + * { + * Actor actor = Actor::New(); + * + * actor.TouchedSignal().Connect( this, &MyClass::Callback ); + * } + * + * ~MyClass() + * { + * // ConnectionTracker base class automatically disconnects + * } + * } + * @endcode */ // INTERNAL INCLUDES @@ -32,14 +63,16 @@ namespace Dali DALI_IMPORT_API { -// This is to allow Signal style syntax +/** + * @brief Base Template class to provide signals. + */ template< typename _Signature > class SignalV2 { }; /** - * A template for Signals with no parameters or return value. + * @brief A template for Signals with no parameters or return value. */ template <> class SignalV2< void () > @@ -47,21 +80,22 @@ class SignalV2< void () > public: /** - * Default constructor. + * @brief Default constructor. */ SignalV2() { } /** - * Non-virtual destructor. + * @brief Non-virtual destructor. */ ~SignalV2() { } /** - * Query whether there are any connected slots. + * @brief Query whether there are any connected slots. + * * @return True if there are any slots connected to the signal. */ bool Empty() const @@ -70,7 +104,8 @@ public: } /** - * Query the number of slots. + * @brief Query the number of slots. + * * @return The number of slots connected to this signal. */ std::size_t GetConnectionCount() const @@ -79,7 +114,8 @@ public: } /** - * Connect a function. + * @brief Connect a function. + * * @param[in] func The function to connect. */ void Connect( void (*func)() ) @@ -88,7 +124,8 @@ public: } /** - * Disconnect a function. + * @brief Disconnect a function. + * * @param[in] func The function to disconnect. */ void Disconnect( void (*func)() ) @@ -97,7 +134,8 @@ public: } /** - * Connect a member function. + * @brief Connect a member function. + * * @param[in] obj An object which must implement the ConnectionTrackerInterface. * @param[in] func The member function to connect. */ @@ -108,7 +146,8 @@ public: } /** - * Disconnect a member function. + * @brief Disconnect a member function. + * * @param[in] obj An object which must implement the ConnectionTrackerInterface. * @param[in] func The member function to disconnect. */ @@ -119,7 +158,8 @@ public: } /** - * Connect a member function. + * @brief Connect a member function. + * * @param[in] delegate A slot delegate. * @param[in] func The member function to connect. */ @@ -130,7 +170,8 @@ public: } /** - * Disconnect a member function. + * @brief Disconnect a member function. + * * @param[in] delegate A slot delegate. * @param[in] func The member function to disconnect. */ @@ -141,7 +182,8 @@ public: } /** - * Connect a function object. + * @brief Connect a function object. + * * @param[in] connectionTracker A connection tracker which can be used to disconnect. * @param[in] func The function object to copy. */ @@ -152,7 +194,8 @@ public: } /** - * Connect a function object using FunctorDelegate. + * @brief Connect a function object using FunctorDelegate. + * * @param[in] connectionTracker A connection tracker which can be used to disconnect. * @param[in] delegate A newly allocated FunctorDelegate (ownership is taken). */ @@ -162,7 +205,7 @@ public: } /** - * Emit the signal. + * @brief Emit the signal. */ void Emit() { @@ -177,11 +220,11 @@ private: private: // Use composition instead of inheritance (virtual methods don't mix well with templates) - BaseSignal mImpl; + BaseSignal mImpl; ///< The base signal implementation }; /** - * A template for Signals with no parameters and a return value. + * @brief A template for Signals with no parameters and a return value. */ template < typename Ret > class SignalV2< Ret() > @@ -189,21 +232,22 @@ class SignalV2< Ret() > public: /** - * Default constructor. + * @brief Default constructor. */ SignalV2() { } /** - * Non-virtual destructor. + * @brief Non-virtual destructor. */ ~SignalV2() { } /** - * Query whether there are any connected slots. + * @brief Query whether there are any connected slots. + * * @return True if there are any slots connected to the signal. */ bool Empty() const @@ -212,7 +256,8 @@ public: } /** - * Query the number of slots. + * @brief Query the number of slots. + * * @return The number of slots connected to this signal. */ std::size_t GetConnectionCount() const @@ -220,7 +265,8 @@ public: return mImpl.GetConnectionCount(); } /** - * Connect a function. + * @brief Connect a function. + * * @param[in] func The function to connect. */ void Connect( Ret (*func)() ) @@ -229,7 +275,8 @@ public: } /** - * Disconnect a function. + * @brief Disconnect a function. + * * @param[in] func The function to disconnect. */ void Disconnect( Ret (*func)() ) @@ -238,7 +285,8 @@ public: } /** - * Connect a member function. + * @brief Connect a member function. + * * @param[in] obj An object which must implement the ConnectionTrackerInterface. * @param[in] func The member function to connect. */ @@ -249,7 +297,8 @@ public: } /** - * Disconnect a member function. + * @brief Disconnect a member function. + * * @param[in] obj An object which must implement the ConnectionTrackerInterface. * @param[in] func The member function to disconnect. */ @@ -260,7 +309,8 @@ public: } /** - * Connect a member function. + * @brief Connect a member function. + * * @param[in] delegate A slot delegate. * @param[in] func The member function to connect. */ @@ -271,7 +321,8 @@ public: } /** - * Disconnect a member function. + * @brief Disconnect a member function. + * * @param[in] delegate A slot delegate. * @param[in] func The member function to disconnect. */ @@ -282,7 +333,8 @@ public: } /** - * Connect a function object. + * @brief Connect a function object. + * * @param[in] connectionTracker A connection tracker which can be used to disconnect. * @param[in] func The function object to copy. */ @@ -293,7 +345,8 @@ public: } /** - * Connect a function object using FunctorDelegate. + * @brief Connect a function object using FunctorDelegate. + * * @param[in] connectionTracker A connection tracker which can be used to disconnect. * @param[in] delegate A newly allocated FunctorDelegate (ownership is taken). */ @@ -303,7 +356,8 @@ public: } /** - * Emit the signal. + * @brief Emit the signal. + * * @return The value returned by the last callback, or a default constructed value if no callbacks are connected. */ Ret Emit() @@ -319,11 +373,11 @@ private: private: // Use composition instead of inheritance (virtual methods don't mix well with templates) - BaseSignal mImpl; + BaseSignal mImpl; ///< Implementation }; /** - * A template for Signals with 1 parameter. + * @brief A template for Signals with 1 parameter. */ template < typename Arg0 > class SignalV2< void ( Arg0 ) > @@ -331,21 +385,22 @@ class SignalV2< void ( Arg0 ) > public: /** - * Default constructor. + * @brief Default constructor. */ SignalV2() { } /** - * Non-virtual destructor. + * @brief Non-virtual destructor. */ ~SignalV2() { } /** - * Query whether there are any connected slots. + * @brief Query whether there are any connected slots. + * * @return True if there are any slots connected to the signal. */ bool Empty() const @@ -354,7 +409,8 @@ public: } /** - * Query the number of slots. + * @brief Query the number of slots. + * * @return The number of slots connected to this signal. */ std::size_t GetConnectionCount() const @@ -362,7 +418,8 @@ public: return mImpl.GetConnectionCount(); } /** - * Connect a function. + * @brief Connect a function. + * * @param[in] func The function to connect. */ void Connect( void (*func)( Arg0 arg0 ) ) @@ -371,7 +428,8 @@ public: } /** - * Disconnect a function. + * @brief Disconnect a function. + * * @param[in] func The function to disconnect. */ void Disconnect( void (*func)( Arg0 arg0 ) ) @@ -380,7 +438,8 @@ public: } /** - * Connect a member function. + * @brief Connect a member function. + * * @param[in] obj An object which must implement the ConnectionTrackerInterface. * @param[in] func The member function to connect. */ @@ -391,7 +450,8 @@ public: } /** - * Disconnect a member function. + * @brief Disconnect a member function. + * * @param[in] obj An object which must implement the ConnectionTrackerInterface. * @param[in] func The member function to disconnect. */ @@ -402,7 +462,8 @@ public: } /** - * Connect a member function. + * @brief Connect a member function. + * * @param[in] delegate A slot delegate. * @param[in] func The member function to connect. */ @@ -413,7 +474,8 @@ public: } /** - * Disconnect a member function. + * @brief Disconnect a member function. + * * @param[in] delegate A slot delegate. * @param[in] func The member function to disconnect. */ @@ -424,7 +486,8 @@ public: } /** - * Connect a function object. + * @brief Connect a function object. + * * @param[in] connectionTracker A connection tracker which can be used to disconnect. * @param[in] func The function object to copy. */ @@ -435,7 +498,8 @@ public: } /** - * Connect a function object using FunctorDelegate. + * @brief Connect a function object using FunctorDelegate. + * * @param[in] connectionTracker A connection tracker which can be used to disconnect. * @param[in] delegate A newly allocated FunctorDelegate (ownership is taken). */ @@ -445,7 +509,8 @@ public: } /** - * Emit the signal. + * @brief Emit the signal. + * * @param[in] arg0 The first value to pass to callbacks. */ void Emit( Arg0 arg0 ) @@ -461,11 +526,11 @@ private: private: // Use composition instead of inheritance (virtual methods don't mix well with templates) - BaseSignal mImpl; + BaseSignal mImpl; ///< Implementation }; /** - * A template for Signals with 1 parameter and a return value. + * @brief A template for Signals with 1 parameter and a return value. */ template < typename Ret, typename Arg0 > class SignalV2< Ret( Arg0 ) > @@ -473,21 +538,22 @@ class SignalV2< Ret( Arg0 ) > public: /** - * Default constructor. + * @brief Default constructor. */ SignalV2() { } /** - * Non-virtual destructor. + * @brief Non-virtual destructor. */ ~SignalV2() { } /** - * Query whether there are any connected slots. + * @brief Query whether there are any connected slots. + * * @return True if there are any slots connected to the signal. */ bool Empty() const @@ -496,7 +562,8 @@ public: } /** - * Query the number of slots. + * @brief Query the number of slots. + * * @return The number of slots connected to this signal. */ std::size_t GetConnectionCount() const @@ -504,7 +571,8 @@ public: return mImpl.GetConnectionCount(); } /** - * Connect a function. + * @brief Connect a function. + * * @param[in] func The function to connect. */ void Connect( Ret (*func)( Arg0 arg0 ) ) @@ -513,7 +581,8 @@ public: } /** - * Disconnect a function. + * @brief Disconnect a function. + * * @param[in] func The function to disconnect. */ void Disconnect( Ret (*func)( Arg0 arg0 ) ) @@ -522,7 +591,8 @@ public: } /** - * Connect a member function. + * @brief Connect a member function. + * * @param[in] obj An object which must implement the ConnectionTrackerInterface. * @param[in] func The member function to connect. */ @@ -533,7 +603,8 @@ public: } /** - * Disconnect a member function. + * @brief Disconnect a member function. + * * @param[in] obj An object which must implement the ConnectionTrackerInterface. * @param[in] func The member function to disconnect. */ @@ -544,7 +615,8 @@ public: } /** - * Connect a member function. + * @brief Connect a member function. + * * @param[in] delegate A slot delegate. * @param[in] func The member function to connect. */ @@ -555,7 +627,8 @@ public: } /** - * Disconnect a member function. + * @brief Disconnect a member function. + * * @param[in] delegate A slot delegate. * @param[in] func The member function to disconnect. */ @@ -566,7 +639,8 @@ public: } /** - * Connect a function object. + * @brief Connect a function object. + * * @param[in] connectionTracker A connection tracker which can be used to disconnect. * @param[in] func The function object to copy. */ @@ -577,7 +651,8 @@ public: } /** - * Connect a function object using FunctorDelegate. + * @brief Connect a function object using FunctorDelegate. + * * @param[in] connectionTracker A connection tracker which can be used to disconnect. * @param[in] delegate A newly allocated FunctorDelegate (ownership is taken). */ @@ -587,7 +662,8 @@ public: } /** - * Emit the signal. + * @brief Emit the signal. + * * @param[in] arg0 The first value to pass to callbacks. * @return The value returned by the last callback, or a default constructed value if no callbacks are connected. */ @@ -604,11 +680,12 @@ private: private: // Use composition instead of inheritance (virtual methods don't mix well with templates) - BaseSignal mImpl; + BaseSignal mImpl; ///< Implementation }; /** - * A template for Signals with 2 parameters. + * @brief A template for Signals with 2 parameters. + * */ template < typename Arg0, typename Arg1 > class SignalV2< void ( Arg0, Arg1 ) > @@ -616,21 +693,24 @@ class SignalV2< void ( Arg0, Arg1 ) > public: /** - * Default constructor. + * @brief Default constructor. + * */ SignalV2() { } /** - * Non-virtual destructor. + * @brief Non-virtual destructor. + * */ ~SignalV2() { } /** - * Query whether there are any connected slots. + * @brief Query whether there are any connected slots. + * * @return True if there are any slots connected to the signal. */ bool Empty() const @@ -639,7 +719,8 @@ public: } /** - * Query the number of slots. + * @brief Query the number of slots. + * * @return The number of slots connected to this signal. */ std::size_t GetConnectionCount() const @@ -647,7 +728,8 @@ public: return mImpl.GetConnectionCount(); } /** - * Connect a function. + * @brief Connect a function. + * * @param[in] func The function to connect. */ void Connect( void (*func)( Arg0 arg0, Arg1 arg1 ) ) @@ -656,7 +738,8 @@ public: } /** - * Disconnect a function. + * @brief Disconnect a function. + * * @param[in] func The function to disconnect. */ void Disconnect( void (*func)( Arg0 arg0, Arg1 arg1 ) ) @@ -665,7 +748,8 @@ public: } /** - * Connect a member function. + * @brief Connect a member function. + * * @param[in] obj An object which must implement the ConnectionTrackerInterface. * @param[in] func The member function to connect. */ @@ -676,7 +760,8 @@ public: } /** - * Disconnect a member function. + * @brief Disconnect a member function. + * * @param[in] obj An object which must implement the ConnectionTrackerInterface. * @param[in] func The member function to disconnect. */ @@ -687,7 +772,8 @@ public: } /** - * Connect a member function. + * @brief Connect a member function. + * * @param[in] delegate A slot delegate. * @param[in] func The member function to connect. */ @@ -698,7 +784,8 @@ public: } /** - * Disconnect a member function. + * @brief Disconnect a member function. + * * @param[in] delegate A slot delegate. * @param[in] func The member function to disconnect. */ @@ -709,7 +796,8 @@ public: } /** - * Connect a function object. + * @brief Connect a function object. + * * @param[in] connectionTracker A connection tracker which can be used to disconnect. * @param[in] func The function object to copy. */ @@ -720,7 +808,8 @@ public: } /** - * Connect a function object using FunctorDelegate. + * @brief Connect a function object using FunctorDelegate. + * * @param[in] connectionTracker A connection tracker which can be used to disconnect. * @param[in] delegate A newly allocated FunctorDelegate (ownership is taken). */ @@ -730,7 +819,8 @@ public: } /** - * Emit the signal. + * @brief Emit the signal. + * * @param[in] arg0 The first value to pass to callbacks. * @param[in] arg1 The second value to pass to callbacks. */ @@ -747,11 +837,11 @@ private: private: // Use composition instead of inheritance (virtual methods don't mix well with templates) - BaseSignal mImpl; + BaseSignal mImpl; ///< Implementation }; /** - * A template for Signals with 2 parameters and a return value. + * @brief A template for Signals with 2 parameters and a return value. */ template < typename Ret, typename Arg0, typename Arg1 > class SignalV2< Ret( Arg0, Arg1 ) > @@ -759,21 +849,22 @@ class SignalV2< Ret( Arg0, Arg1 ) > public: /** - * Default constructor. + * @brief Default constructor. */ SignalV2() { } /** - * Non-virtual destructor. + * @brief Non-virtual destructor. */ ~SignalV2() { } /** - * Query whether there are any connected slots. + * @brief Query whether there are any connected slots. + * * @return True if there are any slots connected to the signal. */ bool Empty() const @@ -782,7 +873,8 @@ public: } /** - * Query the number of slots. + * @brief Query the number of slots. + * * @return The number of slots connected to this signal. */ std::size_t GetConnectionCount() const @@ -790,7 +882,7 @@ public: return mImpl.GetConnectionCount(); } /** - * Connect a function. + * @brief Connect a function. * @param[in] func The function to connect. */ void Connect( Ret (*func)( Arg0 arg0, Arg1 arg1 ) ) @@ -799,7 +891,8 @@ public: } /** - * Disconnect a function. + * @brief Disconnect a function. + * * @param[in] func The function to disconnect. */ void Disconnect( Ret (*func)( Arg0 arg0, Arg1 arg1 ) ) @@ -808,7 +901,8 @@ public: } /** - * Connect a member function. + * @brief Connect a member function. + * * @param[in] obj An object which must implement the ConnectionTrackerInterface. * @param[in] func The member function to connect. */ @@ -819,7 +913,8 @@ public: } /** - * Disconnect a member function. + * @brief Disconnect a member function. + * * @param[in] obj An object which must implement the ConnectionTrackerInterface. * @param[in] func The member function to disconnect. */ @@ -830,7 +925,8 @@ public: } /** - * Connect a member function. + * @brief Connect a member function. + * * @param[in] delegate A slot delegate. * @param[in] func The member function to connect. */ @@ -841,7 +937,8 @@ public: } /** - * Disconnect a member function. + * @brief Disconnect a member function. + * * @param[in] delegate A slot delegate. * @param[in] func The member function to disconnect. */ @@ -852,7 +949,8 @@ public: } /** - * Connect a function object. + * @brief Connect a function object. + * * @param[in] connectionTracker A connection tracker which can be used to disconnect. * @param[in] func The function object to copy. */ @@ -863,7 +961,8 @@ public: } /** - * Connect a function object using FunctorDelegate. + * @brief Connect a function object using FunctorDelegate. + * * @param[in] connectionTracker A connection tracker which can be used to disconnect. * @param[in] delegate A newly allocated FunctorDelegate (ownership is taken). */ @@ -873,7 +972,8 @@ public: } /** - * Emit the signal. + * @brief Emit the signal. + * * @param[in] arg0 The first value to pass to callbacks. * @param[in] arg1 The second value to pass to callbacks. * @return The value returned by the last callback, or a default constructed value if no callbacks are connected. @@ -891,11 +991,11 @@ private: private: // Use composition instead of inheritance (virtual methods don't mix well with templates) - BaseSignal mImpl; + BaseSignal mImpl; ///< Implementation }; /** - * A template for Signals with 3 parameters. + * @brief A template for Signals with 3 parameters. */ template < typename Arg0, typename Arg1, typename Arg2 > class SignalV2< void ( Arg0, Arg1, Arg2 ) > @@ -903,21 +1003,22 @@ class SignalV2< void ( Arg0, Arg1, Arg2 ) > public: /** - * Default constructor. + * @brief Default constructor. */ SignalV2() { } /** - * Non-virtual destructor. + * @brief Non-virtual destructor. */ ~SignalV2() { } /** - * Query whether there are any connected slots. + * @brief Query whether there are any connected slots. + * * @return True if there are any slots connected to the signal. */ bool Empty() const @@ -926,7 +1027,8 @@ public: } /** - * Query the number of slots. + * @brief Query the number of slots. + * * @return The number of slots connected to this signal. */ std::size_t GetConnectionCount() const @@ -934,7 +1036,8 @@ public: return mImpl.GetConnectionCount(); } /** - * Connect a function. + * @brief Connect a function. + * * @param[in] func The function to connect. */ void Connect( void (*func)( Arg0 arg0, Arg1 arg1, Arg2 arg2 ) ) @@ -943,7 +1046,8 @@ public: } /** - * Disconnect a function. + * @brief Disconnect a function. + * * @param[in] func The function to disconnect. */ void Disconnect( void (*func)( Arg0 arg0, Arg1 arg1, Arg2 arg2 ) ) @@ -952,7 +1056,8 @@ public: } /** - * Connect a member function. + * @brief Connect a member function. + * * @param[in] obj An object which must implement the ConnectionTrackerInterface. * @param[in] func The member function to connect. */ @@ -963,7 +1068,8 @@ public: } /** - * Disconnect a member function. + * @brief Disconnect a member function. + * * @param[in] obj An object which must implement the ConnectionTrackerInterface. * @param[in] func The member function to disconnect. */ @@ -974,7 +1080,8 @@ public: } /** - * Connect a member function. + * @brief Connect a member function. + * * @param[in] delegate A slot delegate. * @param[in] func The member function to connect. */ @@ -985,7 +1092,8 @@ public: } /** - * Disconnect a member function. + * @brief Disconnect a member function. + * * @param[in] delegate A slot delegate. * @param[in] func The member function to disconnect. */ @@ -996,7 +1104,8 @@ public: } /** - * Connect a function object. + * @brief Connect a function object. + * * @param[in] connectionTracker A connection tracker which can be used to disconnect. * @param[in] func The function object to copy. */ @@ -1007,7 +1116,8 @@ public: } /** - * Connect a function object using FunctorDelegate. + * @brief Connect a function object using FunctorDelegate. + * * @param[in] connectionTracker A connection tracker which can be used to disconnect. * @param[in] delegate A newly allocated FunctorDelegate (ownership is taken). */ @@ -1017,7 +1127,8 @@ public: } /** - * Emit the signal. + * @brief Emit the signal. + * * @param[in] arg0 The first value to pass to callbacks. * @param[in] arg1 The second value to pass to callbacks. * @param[in] arg2 The third value to pass to callbacks. @@ -1035,11 +1146,11 @@ private: private: // Use composition instead of inheritance (virtual methods don't mix well with templates) - BaseSignal mImpl; + BaseSignal mImpl; ///< Implementation }; /** - * A template for Signals with 2 parameters and a return value. + * @brief A template for Signals with 2 parameters and a return value. */ template < typename Ret, typename Arg0, typename Arg1, typename Arg2 > class SignalV2< Ret( Arg0, Arg1, Arg2 ) > @@ -1047,21 +1158,22 @@ class SignalV2< Ret( Arg0, Arg1, Arg2 ) > public: /** - * Default constructor. + * @brief Default constructor. */ SignalV2() { } /** - * Non-virtual destructor. + * @brief Non-virtual destructor. */ ~SignalV2() { } /** - * Query whether there are any connected slots. + * @brief Query whether there are any connected slots. + * * @return True if there are any slots connected to the signal. */ bool Empty() const @@ -1070,7 +1182,8 @@ public: } /** - * Query the number of slots. + * @brief Query the number of slots. + * * @return The number of slots connected to this signal. */ std::size_t GetConnectionCount() const @@ -1079,7 +1192,8 @@ public: } /** - * Connect a function. + * @brief Connect a function. + * * @param[in] func The function to connect. */ void Connect( Ret (*func)( Arg0 arg0, Arg1 arg1, Arg2 arg2 ) ) @@ -1088,7 +1202,8 @@ public: } /** - * Disconnect a function. + * @brief Disconnect a function. + * * @param[in] func The function to disconnect. */ void Disconnect( Ret (*func)( Arg0 arg0, Arg1 arg1, Arg2 arg2 ) ) @@ -1097,7 +1212,8 @@ public: } /** - * Connect a member function. + * @brief Connect a member function. + * * @param[in] obj An object which must implement the ConnectionTrackerInterface. * @param[in] func The member function to connect. */ @@ -1108,7 +1224,8 @@ public: } /** - * Disconnect a member function. + * @brief Disconnect a member function. + * * @param[in] obj An object which must implement the ConnectionTrackerInterface. * @param[in] func The member function to disconnect. */ @@ -1119,7 +1236,8 @@ public: } /** - * Connect a member function. + * @brief Connect a member function. + * * @param[in] delegate A slot delegate. * @param[in] func The member function to connect. */ @@ -1130,7 +1248,8 @@ public: } /** - * Disconnect a member function. + * @brief Disconnect a member function. + * * @param[in] delegate A slot delegate. * @param[in] func The member function to disconnect. */ @@ -1141,7 +1260,8 @@ public: } /** - * Connect a function object. + * @brief Connect a function object. + * * @param[in] connectionTracker A connection tracker which can be used to disconnect. * @param[in] func The function object to copy. */ @@ -1152,7 +1272,8 @@ public: } /** - * Connect a function object using FunctorDelegate. + * @brief Connect a function object using FunctorDelegate. + * * @param[in] connectionTracker A connection tracker which can be used to disconnect. * @param[in] delegate A newly allocated FunctorDelegate (ownership is taken). */ @@ -1162,7 +1283,8 @@ public: } /** - * Emit the signal. + * @brief Emit the signal. + * * @param[in] arg0 The first value to pass to callbacks. * @param[in] arg1 The second value to pass to callbacks. * @param[in] arg2 The third value to pass to callbacks. @@ -1181,7 +1303,7 @@ private: private: // Use composition instead of inheritance (virtual methods don't mix well with templates) - BaseSignal mImpl; + BaseSignal mImpl; ///< Implementation }; } // namespace Dali diff --git a/capi/dali/public-api/signals/functor-delegate.h b/capi/dali/public-api/signals/functor-delegate.h index d5bb45b..3cbfbba 100644 --- a/capi/dali/public-api/signals/functor-delegate.h +++ b/capi/dali/public-api/signals/functor-delegate.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_SIGNALS_MODULE * @{ */ @@ -29,13 +29,14 @@ namespace Dali DALI_IMPORT_API { /** - * Dispatcher to call a functor + * @brief Dispatcher to call a functor */ template< class T > struct FunctorDispatcher { /** - * Call a function object. + * @brief Call a function object. + * * @param[in] objectPtr The object to call. */ static void Dispatch( void* objectPtr ) @@ -47,13 +48,13 @@ struct FunctorDispatcher }; /** - * Dispatcher to delete an object + * @brief Dispatcher to delete an object */ template< class T > struct FunctorDestroyer { /** - * Dispatcher to delete an object + * @brief Dispatcher to delete an object */ static void Delete( void* object ) { @@ -64,15 +65,17 @@ struct FunctorDestroyer }; /** - * Used to connect a void() functor to a signal via BaseObject::SignalConnect() + * @brief Used to connect a void() functor to a signal via BaseObject::SignalConnect() */ class FunctorDelegate { public: /** - * Constructor which copies a function object. + * @brief Constructor which copies a function object. + * * @param[in] object The object to copy. + * @return A pointer to the new function object */ template< class T > static FunctorDelegate* New( const T& object ) @@ -83,29 +86,40 @@ public: } /** - * Non-virtual destructor; not intended as a base class. + * @brief Non-virtual destructor; not intended as a base class. */ ~FunctorDelegate(); /** - * Function to call the function or member function dispatcher + * @brief Function to call the function or member function dispatcher */ void Execute(); private: - /// Used to call the correct member function + /** + * @brief Used to call the correct member function. + */ typedef void (*Dispatcher)( void* objectPtr ); - /// Used to destroy mObjectPointer (NULL if not mObjectPointer is not owned) + /** + * @brief Used to destroy mObjectPointer (NULL if not mObjectPointer is not owned). + */ typedef void(*Destructor)( void* objectPtr ); - // Not defined + /** + * @brief Not defined + */ FunctorDelegate( const FunctorDelegate& rhs ); + + /** + * @brief Not defined + */ const FunctorDelegate& operator=( const FunctorDelegate& rhs ); /** - * Private constructor. + * @brief Private constructor. + * * @param[in] objectPtr A newly allocated object (takes ownership) * @param dispatcher Used to call the actual object. * @param destructor Used to delete the owned object. diff --git a/capi/dali/public-api/signals/signal-slot-connections.h b/capi/dali/public-api/signals/signal-slot-connections.h index 8c9d206..ec07482 100644 --- a/capi/dali/public-api/signals/signal-slot-connections.h +++ b/capi/dali/public-api/signals/signal-slot-connections.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_SIGNALS_MODULE * @{ */ @@ -31,7 +31,7 @@ namespace Dali DALI_IMPORT_API class CallbackBase; /** - * Slot connection is the connection information held by a connection tracker. + * @brief Slot connection is the connection information held by a connection tracker. * * A slot can have zero to many connection objects, depending * on how many signals it is connected to. @@ -48,25 +48,28 @@ class SlotConnection public: /** - * Constructor + * @brief Constructor. + * * @param[in] slotObserver The slot observer. * @param[in] callback Ownership of this callback object is taken. */ SlotConnection(SlotObserver* slotObserver, CallbackBase* callback); /** - * Non-virtual destructor, not intended as a base class. + * @brief Non-virtual destructor, not intended as a base class. */ ~SlotConnection(); /** - * Retrieve the callback. + * @brief Retrieve the callback. + * * @return A pointer to the callback. */ CallbackBase* GetCallback(); /** - * Retrieve the slot observer. + * @brief Retrieve the slot observer. + * * @return A pointer to the slot observer. */ SlotObserver* GetSlotObserver(); @@ -83,7 +86,7 @@ private: }; /** - * SignalConnection is the connection information held by the signal. + * @brief SignalConnection is the connection information held by the signal. * * A signal can have zero to many connections, depending on how * many slots are connected to this signal. @@ -100,31 +103,35 @@ class SignalConnection public: /** - * Constructor + * @brief Constructor. + * * @param[in] callback The callback which should be a C function. */ SignalConnection( CallbackBase* callback ); /** - * Constructor + * @brief Constructor. + * * @param[in] signalObserver The signal observer. * @param[in] callback The callback which should be a member function of the signalObserver. */ SignalConnection( SignalObserver* signalObserver, CallbackBase* callback ); /** - * Non-virtual destructor, not intended as a base class. + * @brief Non-virtual destructor, not intended as a base class. */ ~SignalConnection(); /** - * Disconnect the signal from the slot. + * @brief Disconnect the signal from the slot. + * * @param[in] slotObserver The signal disconnecting from the slot. */ void Disconnect( SlotObserver* slotObserver ); /** - * Retrieve the callback. + * @brief Retrieve the callback. + * * @return A pointer to the callback. */ CallbackBase* GetCallback(); diff --git a/capi/dali/public-api/signals/signal-slot-observers.h b/capi/dali/public-api/signals/signal-slot-observers.h index 5911d69..6aa7922 100644 --- a/capi/dali/public-api/signals/signal-slot-observers.h +++ b/capi/dali/public-api/signals/signal-slot-observers.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_SIGNALS_MODULE * @{ */ @@ -32,27 +32,27 @@ class SlotObserver; class CallbackBase; /** + * @brief Abstract interface used by a signal to inform a slot it is disconnecting. * - * Abstract interface used by a signal to inform a slot it is disconnecting. * This will happen if the object owning the signal is destroyed. - * */ class SignalObserver { public: /** - * Constructor + * @brief Constructor. */ SignalObserver(); /** - * Virtual destructor + * @brief Virtual destructor. */ virtual ~SignalObserver(); /** - * This method is called when the signal is disconnecting. + * @brief This method is called when the signal is disconnecting. + * * @param[in] slotObserver The signal that has disconnected. * @param[in] callback The callback attached to the signal disconnected. */ @@ -60,7 +60,8 @@ public: }; /** - * Interface used by a slot to inform a signal it is disconnecting. + * @brief Abstract Interface used by a slot to inform a signal it is disconnecting. + * * This is used by the slot if wants to disconnect or is deleted. */ class SlotObserver @@ -68,17 +69,18 @@ class SlotObserver public: /** - * Constructor + * @brief Constructor. */ SlotObserver(); /** - * Virtual destructor + * @brief Virtual destructor. */ virtual ~SlotObserver(); /** - * This method is called when the slot is disconnecting. + * @brief This method is called when the slot is disconnecting. + * * @param[in] callback The callback attached to the signal disconnected. */ virtual void SlotDisconnected( CallbackBase* callback ) = 0; diff --git a/capi/dali/public-api/signals/slot-delegate.h b/capi/dali/public-api/signals/slot-delegate.h index 45a98e7..f6cf5e4 100644 --- a/capi/dali/public-api/signals/slot-delegate.h +++ b/capi/dali/public-api/signals/slot-delegate.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_SIGNALS_MODULE * @{ */ @@ -30,7 +30,8 @@ namespace Dali DALI_IMPORT_API { /** - * SlotDelegates can be used to connect member functions to signals, without inheriting from SlotDelegateInterface. + * @brief SlotDelegates can be used to connect member functions to signals, without inheriting from SlotDelegateInterface. + * * Note that the object providing the member function is expected to own the SlotDelegate; therefore when the object * is destroyed, the SlotDelegate destructor will automatically disconnect. * @@ -70,17 +71,14 @@ namespace Dali DALI_IMPORT_API * * @endcode */ - -/** - * A template for SlotDelegates with no parameters or return value. - */ template class SlotDelegate { public: /** - * Constructor + * @brief Constructor. + * * @param[in] slot The object with a callback. */ SlotDelegate( Slot* slot ) @@ -89,14 +87,16 @@ public: } /** - * Non-virtual destructor. + * @brief Non-virtual destructor. + * */ ~SlotDelegate() { } /** - * Disconnect all signals from this object + * @brief Disconnect all signals from this object. + * */ void DisconnectAll() { @@ -112,7 +112,8 @@ public: } /** - * Retrieve the slot object. + * @brief Retrieve the slot object. + * * @return The object with a callback. */ Slot* GetSlot() @@ -121,7 +122,8 @@ public: } /** - * Retrieve the connection tracker component. + * @brief Retrieve the connection tracker component. + * * @return The connection tracker component. */ ConnectionTracker* GetConnectionTracker() @@ -136,10 +138,10 @@ private: private: - Slot* mSlot; + Slot* mSlot; ///< The slot object // Use composition instead of inheritance (virtual methods don't mix well with templates) - ConnectionTracker mConnectionTracker; + ConnectionTracker mConnectionTracker; ///< A connection tracker }; } // namespace Dali diff --git a/capi/dali/public-api/text/character.h b/capi/dali/public-api/text/character.h index 93d7872..1522d0e 100644 --- a/capi/dali/public-api/text/character.h +++ b/capi/dali/public-api/text/character.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TEXT_MODULE * @{ */ @@ -34,7 +34,8 @@ namespace Internal DALI_INTERNAL } /** - * Character class encapsulates a character implementation to support multiple languages. + * @brief The Character class encapsulates a character implementation to support multiple languages. + * * This class is provided for convenience. A user can't instantiate Characters directly. * However, by instantiating a Text object, Characters are returned by Text::operator[]. */ @@ -43,7 +44,7 @@ class Character public: /** - * CharacterDirection + * @brief CharacterDirection * * Characters can be classified under one of five direction types, which determines the * direction in which they are displayed. @@ -64,50 +65,60 @@ public: public: /** - * Copy constructor. + * @brief Copy constructor. + * * @param [in] character Character to be copied. */ Character( const Character& character ); /** - * Assignment operator. + * @brief Assignment operator. + * * @param [in] character Character to be assigned. + * @return a reference to this */ Character& operator=( const Character& character ); /** - * Non virtual destructor. + * @brief Non virtual destructor. */ ~Character(); /** - * Equality operator. + * @brief Equality operator. + * * @param [in] character The character to be compared. + * @return true if the character is identical */ bool operator==( const Character& character ) const; /** - * Inequality operator. + * @brief Inequality operator. + * * @param [in] character The character to be compared. + * @return true if the character is not identical */ bool operator!=( const Character& character ) const; /** - * Returns direction of this character + * @brief Returns direction of this character. + * * @return The character's direction is returned see CharacterDirection */ CharacterDirection GetCharacterDirection() const; /** - * Returns whether this character is white space (true) - * or not (false) + * @brief Returns whether this character is white space (true) + * or not (false). + * * @return true if a whitespace character, false otherwise. */ bool IsWhiteSpace() const; /** - * Returns whether this character is a new line character (true) - * or not (false) + * @brief Returns whether this character is a new line character (true). + * + * or not (false). * @return true if a new line character, false otherwise. */ bool IsNewLine() const; @@ -116,7 +127,9 @@ private: Internal::Character* mImpl; /** - * Default constructor. Not defined. + * @brief Default constructor. + * + * Not defined. */ DALI_INTERNAL Character(); diff --git a/capi/dali/public-api/text/font-parameters.h b/capi/dali/public-api/text/font-parameters.h index 8fd59a0..87108ff 100644 --- a/capi/dali/public-api/text/font-parameters.h +++ b/capi/dali/public-api/text/font-parameters.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TEXT_MODULE * @{ */ @@ -30,28 +30,35 @@ namespace Dali DALI_IMPORT_API { /** - * Font size in points. + * @brief Font size in points. + * * This reduces ambiguity when using methods which accept size in pixels or points. */ struct PointSize { /** - * Create size in points. + * @brief Create size in points. + * * @param[in] value The value in points. */ explicit PointSize(float value); + /** + * @brief Float cast operator. + */ operator float() const; /** - * Equality operator. + * @brief Equality operator. + * * @param pointSize The point size to be compared. * @return \e true if \e pointSize is equal to the point size stored in this object. */ bool operator==( PointSize pointSize ); /** - * Inequality operator. + * @brief Inequality operator. + * * @param pointSize The point size to be compared. * @return \e true if \e pointSize is not equal to the point size stored in this object. */ @@ -61,44 +68,62 @@ struct PointSize }; /** - * Font size in pixels. + * @brief Font size in pixels. + * * This reduces ambiguity when using methods which accept size in pixels or points. */ struct PixelSize { /** - * Create size in pixels. + * @brief Create size in pixels. + * * @param[in] value The value in pixels. */ explicit PixelSize(unsigned int value); + /** + * @brief Cast operator + */ operator unsigned int() const; unsigned int value; ///< The value in pixels }; +/** + * @brief Font size in Caps height + */ struct CapsHeight { + /** + * @brief Size in CapsHeight + */ explicit CapsHeight( unsigned int value); + /** + * @brief Cast operator + */ operator unsigned int() const; - unsigned int value; + unsigned int value; ///< The value in pixels }; /** - * Encapsulates all font parameters. + * @brief Encapsulates all font parameters. */ struct FontParameters { /** - * Default constructor. Default system font family name, default system font style and default system size + * @brief Default constructor. + * + * Default system font family name, default system font style and default system size * will be used to build the font. */ FontParameters(); /** - * Contructor. Creates font parameters with the given family's name, style and size in points from the font requested. + * @brief Constructor. + * + * Creates font parameters with the given family's name, style and size in points from the font requested. * @param[in] familyName The family's name of the font requested. * @param[in] style The style of the font requested. * @param[in] size The size of the font requested in points. @@ -106,7 +131,9 @@ struct FontParameters FontParameters( const std::string& familyName, const std::string& style, PointSize size ); /** - * Contructor. Creates font parameters with the given family's name, style and size in pixels from the font requested. + * @brief Constructor. + * + * Creates font parameters with the given family's name, style and size in pixels from the font requested. * @param[in] familyName The family's name of the font requested. * @param[in] style The style of the font requested. * @param[in] size The size of the font requested in pixels. @@ -114,7 +141,9 @@ struct FontParameters FontParameters( const std::string& familyName, const std::string& style, PixelSize size ); /** - * Contructor. Creates font parameters with the given family's name, style and the caps-height size in pixels from the font requested. + * @brief Constructor. + * + * Creates font parameters with the given family's name, style and the caps-height size in pixels from the font requested. * @param[in] familyName The family's name of the font requested. * @param[in] style The style of the font requested. * @param[in] size The caps-height of the font requested in pixels. @@ -122,38 +151,45 @@ struct FontParameters FontParameters( const std::string& familyName, const std::string& style, CapsHeight size ); /** - * Destructor. + * @brief Destructor. + * * Destroys the internal implementation. */ ~FontParameters(); /** - * Copy constructor. + * @brief Copy constructor. + * * Reset the internal implementation with new given values. * @param[in] parameters The new font parameters. */ FontParameters( const FontParameters& parameters ); /** - * Assignment operator. + * @brief Assignment operator. + * * @param[in] parameters The new font parameters. + * @return A reference to this */ FontParameters& operator=( const FontParameters& parameters ); /** - * Retrieves the name of the font's family. + * @brief Retrieves the name of the font's family. + * * @return The name of the font's family. */ const std::string& GetFamilyName() const; /** - * Retrieves the style of the font. + * @brief Retrieves the style of the font. + * * @return The style of the font. */ const std::string& GetStyle() const; /** - * Retrieves the size of the font. + * @brief Retrieves the size of the font. + * * @return The size of the font in Points. */ PointSize GetSize() const; @@ -164,7 +200,7 @@ private: }; -extern FontParameters DEFAULT_FONT_PARAMETERS; +extern FontParameters DEFAULT_FONT_PARAMETERS; ///< Used to choose the platform's font parameters } // namespace Dali diff --git a/capi/dali/public-api/text/font.h b/capi/dali/public-api/text/font.h index bffda52..8041b79 100644 --- a/capi/dali/public-api/text/font.h +++ b/capi/dali/public-api/text/font.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TEXT_MODULE * @{ */ @@ -38,7 +38,7 @@ class Font; } /** - * Class to encapsulate a font. + * @brief Encapsulates a font resource. * Fonts are managed by the font manager, which loads any new fonts requested by applications. The font * manager keeps a cache of the most recently used fonts, and if a new font is requested when the cache * is full it will delete an old one (if there is one not in use). @@ -47,12 +47,12 @@ class Font; * * Fonts will be created from a font name (like courier or comic) and font size (specified in points). */ - class Font : public BaseHandle { public: /** - * Stores glyph's metrics. + * @brief Stores glyph's metrics. + * *

    *
  • \e Advance. The distance between the glyph's current pen position and the pen's position of the next glyph. *
  • \e Bearing. The horizontal top side bearing. Is the distance between the baseline and the top of the glyph. @@ -64,49 +64,58 @@ public: { public: /** - * Default constructor. + * @brief Default constructor. + * * Creates the implentation instance. */ Metrics(); /** - * Destructor. + * @brief Destructor. + * * Destroyes the implementaiton instance. */ virtual ~Metrics(); /** - * Copy constructor. + * @brief Copy constructor. + * * @param [in] metrics Metrics to be copied. */ Metrics( const Metrics& metrics ); /** - * Assignment operator. + * @brief Assignment operator. + * * @param [in] metrics Metrics to be assigned. + * @return a reference to this */ Metrics& operator=( const Metrics& metrics ); /** - * Retrieves the advance metric. + * @brief Retrieves the advance metric. + * * @return the advance metric. */ float GetAdvance() const; /** - * Retrieves the bearing metric. + * @brief Retrieves the bearing metric. + * * @return the bearing metric. */ float GetBearing() const; /** - * Retrieves the width metric. + * @brief Retrieves the width metric. + * * @return the width metric. */ float GetWidth() const; /** - * Retrieves the height metric. + * @brief Retrieves the height metric. + * * @return the height metric. */ float GetHeight() const; @@ -115,7 +124,9 @@ public: struct Impl; /** - * Constructor. Initialization with metrics data. + * @brief Constructor. + * + * Initialization with metrics data. * @param implementation Glyph's metrics. */ Metrics( const Impl& implementation ); @@ -126,28 +137,36 @@ public: public: /** - * Create an empty Font. This can be initialised with Font::New(...) + * @brief Create an empty Font. + * + * This can be initialised with Font::New(...) */ Font(); /** - * Create an initialised Font with the given parameters. If no parameters are given, system defaults are used. + * @brief Create an initialised Font with the given parameters. If no parameters are given, system defaults are used. + * * @param [in] fontParameters The font parameters. * @return A handle to a newly allocated font. */ static Font New( const FontParameters& fontParameters = DEFAULT_FONT_PARAMETERS ); /** - * Downcast an Object handle to Font handle. If handle points to a Font object the - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcast an Object handle to Font handle. + * + * If handle points to a Font object the downcast produces valid + * handle. If not the returned handle is left uninitialized. + * * @param[in] handle to An object * @return handle to a Font object or an uninitialized handle */ static Font DownCast( BaseHandle handle ); /** - * Try to detect font for text. + * @brief Try to detect font for text. + * * @param [in] text displayed text + * @return string containing a font name, or an empty string. */ static const std::string GetFamilyForText(const std::string& text); @@ -157,13 +176,16 @@ public: static const std::string GetFamilyForText(const Text& text); /** - * Try to detect font for character. + * @brief Try to detect font for character. + * * @param [in] character displayed character + * @return string containing a font name, or an empty string. */ static const std::string GetFamilyForText(const Character& character); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~Font(); @@ -174,7 +196,8 @@ public: using BaseHandle::operator=; /** - * Convert a PixelSize from CapsHeight to it's equivalent LineHeight. + * @brief Convert a PixelSize from CapsHeight to it's equivalent LineHeight. + * * @param [in] fontFamily The family's name of the font requested * @param [in] fontStyle The style of the font requested. * @param [in] capsHeight The size of the font ascenders required in pixels @@ -183,7 +206,7 @@ public: static PixelSize GetLineHeightFromCapsHeight(const std::string& fontFamily, const std::string& fontStyle, const CapsHeight& capsHeight); /** - * The mode for GetInstalledFonts() + * @brief The mode for GetInstalledFonts() */ enum FontListMode { @@ -193,14 +216,16 @@ public: }; /** - * Gets the list of available fonts. + * @brief Gets the list of available fonts. + * * @param mode which fonts to include in the list, default is LIST_SYSTEM_FONTS * @return a list of font family names */ static std::vector GetInstalledFonts( FontListMode mode = LIST_SYSTEM_FONTS ); /** - * Returns the width of the area needed to display some text if the text is textHeightPx pixels high. + * @brief Returns the width of the area needed to display some text if the text is textHeightPx pixels high. + * * Note that the text is not processed in any way before this calculation is performed (no stretching/scaling) * @param [in] text The text to measure * @param [in] textHeightPx The text height required @@ -214,7 +239,8 @@ public: float MeasureTextWidth(const Text& text, float textHeightPx) const; /** - * Returns the width of the area needed to display the character if the text is textHeightPx pixels high. + * @brief Returns the width of the area needed to display the character if the text is textHeightPx pixels high. + * * Note that the character is not processed in any way before this calculation is performed (no stretching/scaling) * @param [in] character The character to measure * @param [in] textHeightPx The text height required @@ -223,7 +249,8 @@ public: float MeasureTextWidth(const Character& character, float textHeightPx) const; /** - * Returns the height of the area needed to display the text if the text is textWidthPx pixels wide. + * @brief Returns the height of the area needed to display the text if the text is textWidthPx pixels wide. + * * Note that the text is not processed in any way before this calculation is performed (no stretching/scaling) * @param [in] text The text to measure * @param [in] textWidthPx The text width required @@ -237,7 +264,8 @@ public: float MeasureTextHeight(const Text& text, float textWidthPx) const; /** - * Returns the height of the area needed to display the character if the text is textWidthPx pixels wide. + * @brief Returns the height of the area needed to display the character if the text is textWidthPx pixels wide. + * * Note that the character is not processed in any way before this calculation is performed (no stretching/scaling) * @param [in] character The character to measure * @param [in] textWidthPx The text width required @@ -246,7 +274,8 @@ public: float MeasureTextHeight(const Character& character, float textWidthPx) const; /** - * Measure the natural size of a text string, as displayed in this font. + * @brief Measure the natural size of a text string, as displayed in this font. + * * @param[in] text The text string to measure. * @return The natural size of the text. */ @@ -258,45 +287,55 @@ public: Vector3 MeasureText(const Text& text) const; /** - * Measure the natural size of a character, as displayed in this font. + * @brief Measure the natural size of a character, as displayed in this font. + * * @param[in] character The character to measure. * @return The natural size of the character. */ Vector3 MeasureText(const Character& character) const; /** - * Tells whether text is supported with font. - * @param [in] text displayed text + * @brief Tells whether text is supported with font. + * + * @param [in] text glyphs to test + * @return true if the glyphs are all supported by the font */ bool AllGlyphsSupported(const std::string& text) const; /** * @copydoc AllGlyphsSupported(const std::string& text) const + * @param [in] text glyphs to test + * @return true if the glyphs are all supported by the font */ bool AllGlyphsSupported(const Text& text) const; /** - * Tells whether character is supported with font. - * @param [in] character displayed character. + * @brief Tells whether character is supported with font. + * + * @param [in] character The character to test + * @return true if the glyph is supported by the font */ bool AllGlyphsSupported(const Character& character) const; /** - * Retrieves the line height. + * @brief Retrieves the line height. + * * The line height is the distance between two consecutive base lines. * @return The line height. */ float GetLineHeight() const; /** - * Retrieves the ascender metric. + * @brief Retrieves the ascender metric. + * * The ascender metric is the distance between the base line and the top of the highest character in the font. * @return The ascender metric. */ float GetAscender() const; /** - * Retrieves the underline's thickness. + * @brief Retrieves the underline's thickness. + * * * It includes the vertical pad adjust used to add effects like glow or shadow. * @@ -305,7 +344,8 @@ public: float GetUnderlineThickness() const; /** - * Retrieves the underline's position. + * @brief Retrieves the underline's position. + * * * It includes the vertical pad adjust used to add effects like glow or shadow. * @@ -314,7 +354,8 @@ public: float GetUnderlinePosition() const; /** - * Retrieves glyph metrics. + * @brief Retrieves glyph metrics. + * * @see Font::Metrics. * @param [in] character The character which its metrics are going to be retrieved. * @return The glyph metrics. @@ -322,51 +363,59 @@ public: Metrics GetMetrics(const Character& character) const; /** - * Retrieves whether this font was created with a default system font. + * @brief Retrieves whether this font was created with a default system font. + * * @return \e true if this font was created as a default system font. */ bool IsDefaultSystemFont() const; /** - * Retrieves whether this font was created with a default system size. + * @brief Retrieves whether this font was created with a default system size. + * * @return \e true if this font was created as a default system size. */ bool IsDefaultSystemSize() const; /** - * Gets the name of the font's family. + * @brief Gets the name of the font's family. + * * @return The name of the font's family. */ const std::string& GetName() const; /** - * Gets the font's style. + * @brief Gets the font's style. + * * @return The font's style. */ const std::string& GetStyle() const; /** - * Return font size in points. + * @brief Return font size in points. + * * @return size in points */ float GetPointSize() const; /** - * Return font size in pixels. + * @brief Return font size in pixels. + * * @return size in pixels */ unsigned int GetPixelSize() const; /** - * Retrieves the size of the font in pixels from a given size in points. + * @brief Retrieves the size of the font in pixels from a given size in points. + * * @param[in] pointSize Size of the font in points. * @return size of the font in pixels. */ static unsigned int PointsToPixels( float pointSize ); /** - * Retrieves the size of the font in points from a given size in pixels + * @brief Retrieves the size of the font in points from a given size in pixels * @param[in] pixelsSize Size of the font in pixels. + * * @return size of the font in points. */ static float PixelsToPoints( unsigned int pixelsSize ); @@ -374,7 +423,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] font A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL Font(Internal::Font* font); diff --git a/capi/dali/public-api/text/text-style.h b/capi/dali/public-api/text/text-style.h index 25ac39d..90e8213 100644 --- a/capi/dali/public-api/text/text-style.h +++ b/capi/dali/public-api/text/text-style.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TEXT_MODULE * @{ */ @@ -32,13 +32,13 @@ namespace Dali DALI_IMPORT_API { /** - * Class to encapsulate a text style. + * @brief Encapsulates style properties for text, such as weight, italics, underline, shadow, etc. */ class TextStyle { public: /** - * Mask used to set text styles. + * @brief Mask used to set text styles. */ enum Mask { @@ -55,6 +55,9 @@ public: ALL = -1 ///< Sets all given style parameters. }; + /** + * @brief Enumeration of various text weights. + */ enum Weight { THIN = 0, @@ -90,42 +93,51 @@ public: public: /** - * Default constructor. + * @brief Default constructor. + * * The style created used a default font @see Dali::Font, color is white, and is neither underlined nor italics. */ TextStyle(); /** - * Copy constructor. + * @brief Copy constructor. + * * @param[in] textStyle The text style to be copied. */ TextStyle( const TextStyle& textStyle ); /** - * Destructor. + * @brief Destructor. */ virtual ~TextStyle(); /** - * Assignment operator. + * @brief Assignment operator. + * * @param[in] textStyle The text style to be assigned. + * @return A reference to this */ TextStyle& operator=( const TextStyle& textStyle ); /** - * Equality operator. + * @brief Equality operator. + * * @param [in] textStyle The text style to be compared. + * @return true if the style is identical */ bool operator==( const TextStyle& textStyle ) const; /** - * Inequality operator. + * @brief Inequality operator. + * * @param [in] textStyle The text style to be compared. + * @return true if the text style is not identical */ bool operator!=( const TextStyle& textStyle ) const; /** - * Copies from the given text style those parameters specified in the given mask. + * @brief Copies from the given text style those parameters specified in the given mask. + * * * @param[in] textStyle The given text style. * @param[in] mask Specifies which text style parameters are going to be copied. By default all parateres are copied. @@ -133,153 +145,176 @@ public: void Copy( const TextStyle& textStyle, const Mask mask = ALL ); /** - * Retrieves the font name. + * @brief Retrieves the font name. + * * @return The font name. */ const std::string& GetFontName() const; /** - * Sets the font name. + * @brief Sets the font name. + * * @param[in] fontName */ void SetFontName( const std::string& fontName ); /** - * Retrieves the font style. + * @brief Retrieves the font style. + * * @return The font style. */ const std::string& GetFontStyle() const; /** - * Sets the font style. + * @brief Sets the font style. + * * @param[in] fontStyle */ void SetFontStyle( const std::string& fontStyle ); /** - * Retrieves the font point size. + * @brief Retrieves the font point size. + * * @return the point size. */ PointSize GetFontPointSize() const; /** - * Sets the font point size. + * @brief Sets the font point size. + * * @param[in] fontPointSize The font point size. */ void SetFontPointSize( PointSize fontPointSize ); /** - * Retrieves the style weight. + * @brief Retrieves the style weight. + * * @return The style weight. */ Weight GetWeight() const; /** - * Sets the style weight. + * @brief Sets the style weight. + * * @param[in] weight The style weight */ void SetWeight( Weight weight ); /** - * Retrieves the text color. + * @brief Retrieves the text color. + * * @return The text color. */ const Vector4& GetTextColor() const; /** - * Sets the text color. + * @brief Sets the text color. + * * @param[in] textColor The text color */ void SetTextColor( const Vector4& textColor ); /** - * Whether the style italics option is enabled or not. + * @brief Whether the style italics option is enabled or not. + * * @return \e true if italics is enabled. */ bool GetItalics() const; /** - * Sets the italics option. + * @brief Sets the italics option. + * * @param[in] italics The italics option. */ void SetItalics( bool italics ); /** - * Retrieves the italics angle. + * @brief Retrieves the italics angle. + * * @return \e The italics angle in degree. */ Degree GetItalicsAngle() const; /** - * Sets the italics angle. + * @brief Sets the italics angle. + * * @param[in] angle The italics angle in degree. */ void SetItalicsAngle( Degree angle ); /** - * Whether the style underline option is enabled or not. + * @brief Whether the style underline option is enabled or not. + * * @return \e true if underline is enabled. */ bool GetUnderline() const; /** - * Sets the underline option. + * @brief Sets the underline option. + * * @param[in] underline The underline option. */ void SetUnderline( bool underline ); /** - * Retrieves the underline thickness. + * @brief Retrieves the underline thickness. + * * @return The underline thickness. */ float GetUnderlineThickness() const; /** - * Sets the underline thickness. + * @brief Sets the underline thickness. * * @param[in] thickness The underline thickness. */ void SetUnderlineThickness( float thickness ); /** - * Retrieves the underline position. + * @brief Retrieves the underline position. + * * @return The underline position. */ float GetUnderlinePosition() const; /** - * Sets the underline position. + * @brief Sets the underline position. * * @param[in] position The underline position. */ void SetUnderlinePosition( float position ); /** - * Whether the style shadow option is enabled or not. + * @brief Whether the style shadow option is enabled or not. + * * @return \e true if shadow is enabled. */ bool GetShadow() const; /** - * Retrieves the shadow color. + * @brief Retrieves the shadow color. + * * @return The shadow color. */ const Vector4& GetShadowColor() const; /** - * Retrieves the shadow offset + * @brief Retrieves the shadow offset * @return The shadow offset. + * */ const Vector2& GetShadowOffset() const; /** - * Retrieves the shadow size + * @brief Retrieves the shadow size * @return The shadow size. + * */ float GetShadowSize() const; /** - * Sets the shadow option. + * @brief Sets the shadow option. + * * @param[in] shadow The shadow option. * @param[in] shadowColor The color of the shadow * @param[in] shadowOffset Offset in pixels. @@ -291,25 +326,29 @@ public: const float shadowSize = DEFAULT_SHADOW_SIZE ); /** - * Whether the glow option is enabled or not. + * @brief Whether the glow option is enabled or not. + * * @return \e true if glow is enabled. */ bool GetGlow() const; /** - * Retrieves the glow color. + * @brief Retrieves the glow color. + * * @return The glow color. */ const Vector4& GetGlowColor() const; /** - * Retrieve the glow intensity. + * @brief Retrieve the glow intensity. + * * @return The glow intensity. */ float GetGlowIntensity() const; /** - * Sets the glow option and color. + * @brief Sets the glow option and color. + * * @param[in] glow The glow option. * @param[in] glowColor The color of the glow. * @param[in] glowIntensity Determines the amount of glow around text. @@ -319,38 +358,44 @@ public: void SetGlow( bool glow, const Vector4& glowColor = DEFAULT_GLOW_COLOR, float glowIntensity = DEFAULT_GLOW_INTENSITY ); /** - * Retrieves the soft smooth edge. + * @brief Retrieves the soft smooth edge. + * * @return The soft smooth edge. */ float GetSmoothEdge() const; /** - * Set soft edge smoothing + * @brief Set soft edge smoothing. + * * @param[in] smoothEdge Specify the distance field value for the center of the text edge. * 0 <= smoothEdge <= 1 */ void SetSmoothEdge( float smoothEdge = DEFAULT_SMOOTH_EDGE_DISTANCE_FIELD ); /** - * Whether the outline option is enabled or not. + * @brief Whether the outline option is enabled or not. + * * @return \e true if outline is enabled. */ bool GetOutline() const; /** - * Retrieves the outline color. + * @brief Retrieves the outline color. + * * @return The outline color. */ const Vector4& GetOutlineColor() const; /** - * Retrieves the outline thickness. + * @brief Retrieves the outline thickness. + * * @return The outline thickness. */ const Vector2& GetOutlineThickness() const; /** - * Sets the outline option and color. + * @brief Sets the outline option and color. + * * @param[in] outline The outline option. * @param[in] outlineColor The color of the outline. * @param[in] outlineThickness Thickness of outline. The outline thickness is determined by two parameters. @@ -364,7 +409,7 @@ public: private: struct Impl; - Impl* mImpl; + Impl* mImpl; ///< Implementation pointer }; } // namespace Dali diff --git a/capi/dali/public-api/text/text.h b/capi/dali/public-api/text/text.h index 1f7dd92..098b8aa 100644 --- a/capi/dali/public-api/text/text.h +++ b/capi/dali/public-api/text/text.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TEXT_MODULE * @{ */ @@ -38,63 +38,73 @@ namespace Internal DALI_INTERNAL } /** - * Text class, encapsulates a string of characters implementation to support multiple languages. + * @brief Encapsulates a string of characters implementation to support multiple languages. */ class Text { public: /** - * Default constructor. + * @brief Default constructor. + * * It creates an empty Text. */ Text(); /** - * Constructor. + * @brief Constructor. + * * Creates a Text object with the given string. * @param [in] text An ASCII or UTF-8 encoded string. */ Text( const std::string& text ); /** - * Constructor. + * @brief Constructor. + * * Creates a Text object with the given character. * @param [in] character The character. */ Text( const Character& character ); /** - * Copy Constructor. + * @brief Copy Constructor. + * * @param [in] text Text to be copied. */ Text( const Text& text ); /** - * Assignment operator. + * @brief Assignment operator. + * * @param [in] text Text to be assigned. + * @return A reference to this */ Text& operator=( const Text& text ); /** - * Non-virtual destructor. + * @brief Non-virtual destructor. + * */ ~Text(); /** - * Retrieves the stored text. + * @brief Retrieves the stored text. + * * @return An std::string with the stored text. */ std::string GetText() const; /** - * Sets the given text. + * @brief Sets the given text. + * * @param [in] text The text to be set. */ void SetText( const std::string& text ); /** - * Sets the given character. + * @brief Sets the given character. + * * @param [in] character The character to be set. */ void SetText( const Character& character ); @@ -105,32 +115,38 @@ public: void SetText( const Text& text ); /** - * Retrieves the characters stored in the given position. + * @brief Retrieves the character stored in the given position. + * * @pre The given \e position must be a positive value less than the total length of the text. * @param [in] position The character position. + * @return The character */ Character operator[]( size_t position ) const; /** - * Whether the text is empty or not. + * @brief Whether the text is empty or not. + * * @return \e true if the text is empty. */ bool IsEmpty() const; /** - * Retrieves the number of characters. + * @brief Retrieves the number of characters. + * * @return the number of characters. */ size_t GetLength() const; /** - * Appends the given text. + * @brief Appends the given text. + * * @param [in] text The text to be appended. */ void Append( const std::string& text ); /** - * Appends the given character. + * @brief Appends the given character. + * * @param [in] character The character to be appended. */ void Append( const Character& character ); @@ -141,7 +157,7 @@ public: void Append( const Text& text ); /** - * Removes a number of characters starting from a given position. + * @brief Removes a number of characters starting from a given position. * * @pre The given \e position plus \e numberOfCharacters must be a positive value less or equal than the total length of the text. * @param[in] position The position from where characters are going to be removed. @@ -151,12 +167,12 @@ public: private: - Internal::Text* mImpl; + Internal::Text* mImpl; ///< Pointer to implementation object public: // Not intended for application developers /** - * Retrieves the internal implementation. + * @brief Retrieves the internal implementation. * * @note Application developers shouldn't call any GetImplementation() method. * @@ -165,7 +181,7 @@ public: // Not intended for application developers DALI_INTERNAL const Internal::Text& GetImplementation() const; /** - * Retrieves the internal implementation. + * @brief Retrieves the internal implementation. * * @note Application developers shouldn't call any GetImplementation() method. * diff --git a/capi/dali_doc.h b/capi/dali_doc.h new file mode 100644 index 0000000..64eae78 --- /dev/null +++ b/capi/dali_doc.h @@ -0,0 +1,323 @@ +#ifndef __DALI_DOC_H__ +#define __DALI_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_UI_FRAMEWORK + * @defgroup CAPI_DALI_FRAMEWORK Dali + * @brief The Dali provides a cross-platform C++ 3D UI toolkit based on + * OpenGL ES 2.0. + * + * + * + *
    APIDescription
    @ref CAPI_DALI_MODULEA library to provide a C++ scene graph based on OpenGL ES 2.0.
    @ref CAPI_DALI_TOOLKIT_MODULEA library to provide a user interface toolkit on top of Dali.
    + */ + +/** + * @ingroup CAPI_DALI_FRAMEWORK + * @defgroup CAPI_DALI_MODULE Dali Core + * @brief The Dali library provides a C++ scene graph based on OpenGL ES 2.0. + * + * @section CAPI_DALI_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_MODULE_OVERVIEW Overview + * + * + * + * + * + * + * Meshes. + * Image resource types. + * Math classes and utilities. + * + * Registered Object and property system. + * + * + * + * Classes for manipulating text. + *
    APIDescription
    @ref CAPI_DALI_ACTORS_MODULEThe set of interactive objects that can be placed on the Dali::Stage.
    @ref CAPI_DALI_ADAPTOR_MODULEInterface to the platform.
    @ref CAPI_DALI_ANIMATION_MODULEThe property animation and constraints system.
    @ref CAPI_DALI_COMMON_MODULEGeneral classes.
    @ref CAPI_DALI_EVENTS_MODULEEvents, gestures and gesture detectors.
    @ref CAPI_DALI_GEOMETRY_MODULE
    @ref CAPI_DALI_IMAGES_MODULE
    @ref CAPI_DALI_MATH_MODULE
    @ref CAPI_DALI_MODELING_MODULEAncilliary classes for meshes and 3D models
    @ref CAPI_DALI_OBJECT_MODULE
    @ref CAPI_DALI_RENDER_TASKS_MODULEClasses to describe how the scene is rendered.
    @ref CAPI_DALI_SHADER_EFFECTS_MODULEClasses to change how actors are visualised.
    @ref CAPI_DALI_SIGNALS_MODULESignals and Slots - a type-safe, loosely-coupled callback system.
    @ref CAPI_DALI_TEXT_MODULE
    + */ + + +/** + * @ingroup CAPI_DALI_MODULE + * + * @defgroup CAPI_DALI_ACTORS_MODULE Actors + * + * @section CAPI_DALI_ACTORS_MODULE_HEADER RequiredHeader + * \#include + * + * @section CAPI_DALI_ACTORS_MODULE_OVERVIEW Overview + * + * + * + * + * + * + * + * + * + * An actor for grouping and sorting other actors. + *
    APIDescription
    @ref Dali::Actor Primary class for application interaction.
    @ref Dali::CameraActor An actor which controls a camera.
    @ref Dali::CustomActor CustomActor is a base class for custom UI controls.
    @ref Dali::CustomActorImpl CustomActorImpl is an abstract base class for custom control implementations.
    @ref Dali::RenderableActor A base class for renderable actors.
    @ref Dali::ImageActor An actor for displaying images.
    @ref Dali::MeshActor An actor for displaying mesh geometries.
    @ref Dali::TextActor An actor for display simple text.
    @ref Dali::Layer
    + */ + +/** + * @ingroup CAPI_DALI_MODULE + * @defgroup CAPI_DALI_ANIMATION_MODULE Animation + * @section CAPI_DALI_ANIMATION_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_ANIMATION_MODULE_OVERVIEW Overview + * + * + * + * + * + * + * + * + * + * + *
    APIDescription
    @ref Dali::ActiveConstraint A constraint which is being applied to an object.
    Dali::AlphaFunctions Various functions that control progress of an animation.
    @ref Dali::Animation Dali::Animation can be used to animate the properties of any number of objects, typically Dali::Actor%s.
    @ref Dali::Constraint An abstract base class for Constraints.
    ConstraintsVarious constraints for properties: +@ref Dali::ScaleToFitConstraint +@ref Dali::ScaleToFitKeepAspectRatioConstraint +@ref Dali::ScaleToFillKeepAspectRatioConstraint +@ref Dali::ScaleToFillXYKeepAspectRatioConstraint +@ref Dali::ShrinkInsideKeepAspectRatioConstraint +@ref Dali::MultiplyConstraint +@ref Dali::DivideConstraint +@ref Dali::EqualToConstraint +@ref Dali::RelativeToConstraint +@ref Dali::RelativeToConstraintFloat +@ref Dali::InverseOfConstraint +@ref Dali::SourceWidthFixedHeight +@ref Dali::SourceHeightFixedWidth +Dali::LookAt() +@ref Dali::OrientedLookAt
    Interpolator Functions Dali::LerpBoolean(), Dali::LerpFloat(), Dali::LerpVector2(), Dali::LerpVector3(), Dali::LerpVector4(), Dali::SlerpQuaternion()
    @ref Dali::KeyFrames A set of key frames for a property that can be animated using @ref Dali::Animation::AnimateBetween()
    Constraint SourcesSpecifies the location of a property for use in a constraint: + * @ref Dali::SourceType +@ref Dali::LocalSource +@ref Dali::ParentSource +@ref Dali::Source +@ref Dali::ConstraintSource
    @ref Dali::TimePeriod A value-type representing a period of time within an animation.
    + */ + +/** + * @ingroup CAPI_DALI_MODULE + * @defgroup CAPI_DALI_COMMON_MODULE Common + * @section CAPI_DALI_COMMON_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_COMMON_MODULE_OVERVIEW Overview + * + * + * + * + * + * + * + * + *
    APIDescription
    @ref Dali::ParentOrigin Constants to specify the origin of an actor within it's parent volume, used by Dali::Actor::SetParentOrigin()
    @ref Dali::AnchorPoint Constants to specify the anchor point of an actor, used by Dali::Actor::SetAnchorPoint()
    @ref Dali::Color Constants to specify primary colors
    @ref Dali::Math Epsilon and Pi constants
    @ref Dali::String String constants
    @ref Dali::LoadingState The status during resource loading operations.
    @ref Dali::Stage The Stage is a top-level object used for displaying a tree of Actors.
    + */ + +/** + * @ingroup CAPI_DALI_MODULE + * @defgroup CAPI_DALI_EVENTS_MODULE Events + * @section CAPI_DALI_EVENTS_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_EVENTS_MODULE_OVERVIEW Overview + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
    APIDescription
    @ref Dali::GestureDetector GestureDetectors analyse a stream of touch events and attempt to determine the intention of the user.
    @ref Dali::Gesture Base structure for different gestures that an application can receive.
    @ref Dali::KeyEvent The key event structure is used to store a key press.
    @ref Dali::LongPressGestureDetectorThis emits a signal when a long press gesture occurs.
    @ref Dali::LongPressGesture A LongPressGesture is emitted when the user touches and holds the screen with the stated number of fingers.
    @ref Dali::PanGestureDetector This class looks for panning (or dragging) gestures.
    @ref Dali::PanGesture A PanGesture is emitted when the user moves one or more fingers in a particular direction.
    @ref Dali::PinchGestureDetector This class looks for pinching gestures involving two touches.
    @ref Dali::PinchGesture A PinchGesture is emitted when the user moves two fingers towards or away from each other.
    @ref Dali::TapGestureDetector This class emits a signal when a tap gesture occurs
    @ref Dali::TapGesture A TapGesture is emitted when the user taps the screen
    @ref Dali::TouchEvent Touch events are a collection of touch points at a specific moment in time.
    @ref Dali::TouchPoint A TouchPoint represents a point on the screen that is currently being touched or where touch + * has stopped.
    + */ + +/** + * @ingroup CAPI_DALI_MODULE + * @defgroup CAPI_DALI_GEOMETRY_MODULE Geometry + * @section CAPI_DALI_GEOMETRY_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_GEOMETRY_MODULE_OVERVIEW Overview + * + * + * + *
    APIDescription
    @ref Dali::AnimatableMesh A mesh geometry that can be animated using the Dali property animation system.
    @ref Dali::AnimatableVertex Represents a vertex in a Dali::AnimatableMesh.
    + */ + +/** + * @ingroup CAPI_DALI_MODULE + * @defgroup CAPI_DALI_IMAGES_MODULE Images + * @section CAPI_DALI_IMAGES_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_IMAGES_MODULE_OVERVIEW Overview + * + * + * + * + * + * + * + * + *
    APIDescription
    @ref Dali::BitmapImage This represents an image resource supplied by Application writer that can be added to Dali::ImageActor.
    @ref Dali::EncodedBufferImage This represents an encoded image supplied by Application writer that can be added to Dali::ImageActor.
    @ref Dali::FrameBufferImage This represents a GLES frame buffer object and contains the result of an 'off-screen' render pass of a Dali::RenderTask
    @ref Dali::ImageAttributes Describes Image properties like width or pixel format.
    @ref Dali::Image An Image object represents an image resource that can be added to ImageActors.
    @ref Dali::NativeImage Abstract interface to provide platform-specific support for handling image data.
    @ref Dali::Pixel Pixel format types and their properties.
    + */ + +/** + * @ingroup CAPI_DALI_MODULE + * @defgroup CAPI_DALI_MATH_MODULE Math + * @section CAPI_DALI_MATH_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_MATH_MODULE_OVERVIEW Overview + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
    APIDescription
    @ref Dali::AngleAxis An angle & axis pair.
    @ref Dali::Degree An angle in degrees.
    @ref Dali::Radian An angle in radians.
    @ref Dali::Matrix The Matrix class represents transformations and projections.
    @ref Dali::Matrix3 A 3x3 matrix.
    @ref Dali::Quaternion The Quaternion class encapsulates the mathematics of the quaternion.
    @ref Dali::Rect Template class to create and operate on rectangles.
    @ref Dali::Vector2 A two-dimensional vector.
    @ref Dali::Vector3 A three-dimensional vector.
    @ref Dali::Vector4 A four-dimensional vector.
    @ref Dali::Random Provides methods to generate and use random values.
    @ref Dali::Viewport Screen area in pixels
    Math Utilities +Dali::NextPowerOfTwo() +Dali::IsPowerOfTwo() +Dali::Clamp() +Dali::ClampInPlace() +Dali::Lerp() +Dali::GetRangedEpsilon() +Dali::EqualsZero() +Dali::Equals() +Dali::Round() +Dali::WrapInDomain() +Dali::ShortestDistanceInDomain() + *
    + */ + +/** + * @ingroup CAPI_DALI_MODULE + * @defgroup CAPI_DALI_MODELING_MODULE Modeling + * @section CAPI_DALI_MODELING_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_MODELING_MODULE_OVERVIEW Overview + * + * + *
    APIDescription
    @ref Dali::Material Encapsulates the data describing a material.
    + */ + +/** + * @ingroup CAPI_DALI_MODULE + * @defgroup CAPI_DALI_OBJECT_MODULE Object + * @section CAPI_DALI_OBJECT_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_OBJECT_MODULE_OVERVIEW Overview + * + * + * + * + * + * + * + * + * + * + * + * a + * + * + *
    APIDescription
    @ref Dali::BaseHandle Dali::BaseHandle is a handle to an internal Dali resource.
    @ref Dali::BaseObject A base class for objects.
    @ref Dali::Constrainable A handle to an internal property owning Dali object that + * can have constraints applied to it.
    @ref Dali::Handle A handle to an internal property owning Dali object.
    @ref Dali::ObjectRegistry The ObjectRegistry notifies it's observers when an object is created.
    @ref Dali::PropertyCondition This represents a condition that can be evaluated on a Property::Value. Factory methods include Dali::LessThanCondition(), Dali::GreaterThanCondition(), Dali::InsideCondition() and Dali::OutsideCondition()
    @ref Dali::PropertyInput An abstract interface for receiving property values.
    @ref Dali::PropertyNotification This is used to issue a notification upon a condition of the property being met.
    @ref Dali::PropertyTypes Template function instances for property getters.
    @ref Dali::Property An object + property pair.
    @ref Dali::Property::Value A value-type representing a property value.
    @ref Dali::RefObject Base class for reference counted objects.
    @ref Dali::IntrusivePtr Template class used to point at Dali::RefObjects
    + */ + +/** + * @ingroup CAPI_DALI_MODULE + * @defgroup CAPI_DALI_RENDER_TASKS_MODULE Render Tasks + * @section CAPI_DALI_RENDER_TASKS_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_RENDER_TASKS_MODULE_OVERVIEW Overview + * + * + * + *
    APIDescription
    @ref Dali::RenderTask A RenderTask describes how all or part of the Dali scene should be rendered.
    @ref Dali::RenderTaskList An ordered list of Dali::RenderTask%s.
    + */ + +/** + * @ingroup CAPI_DALI_MODULE + * @defgroup CAPI_DALI_SHADER_EFFECTS_MODULE Shader effects + * @section CAPI_DALI_SHADER_EFFECTS_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_SHADER_EFFECTS_MODULE_OVERVIEW Overview + * + * + *
    APIDescription
    @ref Dali::ShaderEffect Shader effects provide a visual effect for actors.
    + */ + +/** + * @ingroup CAPI_DALI_MODULE + * @defgroup CAPI_DALI_SIGNALS_MODULE Signals + * @section CAPI_DALI_SIGNALS_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_SIGNALS_MODULE_OVERVIEW Overview + * + * + * + * + * + * + * + * + * + * + * + * + *
    APIDescription
    @ref Dali::BaseSignal Implementation class for Dali::SignalV2%s.
    @ref Dali::Callback Templates to provide type safety for member function callbacks.
    @ref Dali::ConnectionTracker Connection tracker concrete implementation
    @ref Dali::ConnectionTrackerInterface Interface used to track connections between signals and slots.
    @ref Dali::SignalV2 Template classes that provide signals
    @ref Dali::FunctorDelegate Used to connect a void() functor to a signal via Dali::BaseObject::SignalConnect()
    @ref Dali::SlotConnection SlotConnection is the connection information held by a connection tracker.
    @ref Dali::SignalConnection SignalConnection is the connection information held by the signal.
    @ref Dali::SignalObserver Abstract interface used by a signal to inform a slot it is disconnecting.
    @ref Dali::SlotObserver Abstract Interface used by a slot to inform a signal it is disconnecting.
    @ref Dali::SlotDelegate SlotDelegates can be used to connect member functions to signals, without inheriting from SlotDelegateInterface.
    + */ + +/** + * @ingroup CAPI_DALI_MODULE + * @defgroup CAPI_DALI_TEXT_MODULE Text + * @section CAPI_DALI_TEXT_MODULE_HEADER Required Header + * \#include + * @section CAPI_DALI_TEXT_MODULE_OVERVIEW Overview + * + * + * + * + * + * + * + * + * + *
    APIDescription
    @ref Dali::Character Character class encapsulates a character implementation to support multiple languages.
    @ref Dali::PointSize Font size in points.
    @ref Dali::PixelSize Font size in pixels.
    @ref Dali::CapsHeight Font size in caps height.
    @ref Dali::FontParameters Encapsulates all font parameters.
    @ref Dali::Font Encapsulates a font resource
    @ref Dali::TextStyle Encapsulates style properties for text, such as weight, italics, underline, shadow, etc.
    @ref Dali::Text Encapsulates a string of characters implementation to support multiple languages.
    + */ + + + +#endif //__DALI_DOC_H__ -- 2.7.4