X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Fanimation%2Fconstraint.h;h=b847a98e8a697bf15c103f62bb5e4458b0ea573b;hb=51f1960564f0d2daca007112a49e4af2b6506a39;hp=6f51a6850c20cbbea937282e19a406bfbc97cb99;hpb=14a7ce57b6b0a71869185a5218d59180f60ef892;p=platform%2Fcore%2Fuifw%2Fdali-core.git diff --git a/dali/public-api/animation/constraint.h b/dali/public-api/animation/constraint.h index 6f51a68..b847a98 100644 --- a/dali/public-api/animation/constraint.h +++ b/dali/public-api/animation/constraint.h @@ -1,8 +1,8 @@ -#ifndef __DALI_CONSTRAINT_H__ -#define __DALI_CONSTRAINT_H__ +#ifndef DALI_CONSTRAINT_H +#define DALI_CONSTRAINT_H /* - * Copyright (c) 2015 Samsung Electronics Co., Ltd. + * Copyright (c) 2019 Samsung Electronics Co., Ltd. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -18,6 +18,9 @@ * */ +// EXTERNAL INCLUDES +#include // uint32_t + // INTERNAL INCLUDES #include #include @@ -28,6 +31,10 @@ namespace Dali { +/** + * @addtogroup dali_core_animation + * @{ + */ class Handle; @@ -59,8 +66,9 @@ typedef Vector< PropertyInput* > PropertyInputContainer; * constraint.AddSource( LocalSource( INPUT_PROPERTY_INDEX ) ); * constraint.Apply(); * @endcode + * @SINCE_1_0.0 */ -class DALI_IMPORT_API Constraint : public BaseHandle +class DALI_CORE_API Constraint : public BaseHandle { public: @@ -83,7 +91,8 @@ public: * should change this value to the desired one. The PropertyInputContainer is a const reference to the property inputs * added to the Constraint in the order they were added via AddSource(). * - * @tparam P The property type to constrain. + * @SINCE_1_0.0 + * @tparam P The property type to constrain */ template< typename P > class DALI_INTERNAL Function : public CallbackBase @@ -98,7 +107,8 @@ public: * void MyFunction( P&, const PropertyInputContainer& ); * @endcode * - * @param[in] function The function to call. + * @SINCE_1_0.0 + * @param[in] function The function to call */ Function( void( *function )( P&, const PropertyInputContainer& ) ) : CallbackBase( reinterpret_cast< CallbackBase::Function >( function ) ), @@ -114,9 +124,9 @@ public: * void operator()( P&, const PropertyInputContainer& ); * @endcode * - * @param[in] object The object to copy. - * - * @tparam T The type of the object. + * @SINCE_1_0.0 + * @param[in] object The object to copy + * @tparam T The type of the object */ template< class T > Function( const T& object ) @@ -136,10 +146,10 @@ public: * void MyObject::MyMethod( P&, const PropertyInputContainer& ); * @endcode * - * @param[in] object The object to copy. - * @param[in] memberFunction The member function to call. This has to be a member of the same class. - * - * @tparam T The type of the object. + * @SINCE_1_0.0 + * @param[in] object The object to copy + * @param[in] memberFunction The member function to call. This has to be a member of the same class + * @tparam T The type of the object */ template< class T > Function( const T& object, void ( T::*memberFunction ) ( P&, const PropertyInputContainer& ) ) @@ -156,7 +166,8 @@ public: * * The object, if held by this object, is also copied. * - * @return A pointer to a newly-allocation Function. + * @SINCE_1_0.0 + * @return A pointer to a newly-allocated Function */ CallbackBase* Clone() { @@ -186,24 +197,26 @@ public: class UndefinedClass; /** - * @brief Used to call the function to copy the stored object + * @brief Used to call the function to copy the stored object. + * @SINCE_1_0.0 */ typedef UndefinedClass* (*CopyConstructorDispatcher) ( UndefinedClass* object ); /** * @brief Copies the actual object in Constraint::Function. * - * @tparam T The type of the object. + * @SINCE_1_0.0 + * @tparam T The type of the object */ template< class T > struct ObjectCopyConstructorDispatcher { /** - * @brief Copy the object stored in Constraint::Function. - * - * @param[in] object The object to copy. + * @brief Copies the object stored in Constraint::Function. * - * @return Newly allocated clone of the object. + * @SINCE_1_0.0 + * @param[in] object The object to copy + * @return Newly allocated clone of the object */ static UndefinedClass* Copy( const UndefinedClass* object ) { @@ -213,23 +226,26 @@ public: }; /** - * @brief Undefined copy constructor + * @brief Undefined copy constructor. + * @SINCE_1_0.0 */ Function( const Function& ); /** - * @brief Undefined assignment operator + * @brief Undefined assignment operator. + * @SINCE_1_0.0 */ Function& operator=( const Function& ); /** * @brief Constructor used when copying the stored object. * + * @SINCE_1_0.0 * @param[in] object A newly copied object - * @param[in] memberFunction The member function of the object. - * @param[in] dispatcher Used to call the actual object. - * @param[in] destructor Used to delete the owned object. - * @param[in] copyConstructorDispatcher Used to create a copy of the owned object. + * @param[in] memberFunction The member function of the object + * @param[in] dispatcher Used to call the actual object + * @param[in] destructor Used to delete the owned object + * @param[in] copyConstructorDispatcher Used to create a copy of the owned object */ Function( void* object, CallbackBase::MemberFunction memberFunction, @@ -244,7 +260,8 @@ public: /** * @brief Constructor used when copying a simple stored function. * - * @param[in] function The function to call. + * @SINCE_1_0.0 + * @param[in] function The function to call */ Function( CallbackBase::Function function ) : CallbackBase( function ), @@ -258,28 +275,30 @@ public: }; /** - * @brief The action that will happen when the constraint is removed. + * @brief Enumeration for the action that will happen when the constraint is removed. * * The final value may be "baked" i.e. saved permanently. * Alternatively the constrained value may be discarded when the constraint is removed. + * @SINCE_1_0.0 */ enum RemoveAction { - Bake, ///< When the constraint is fully-applied, the constrained value is saved. - Discard ///< When the constraint is removed, the constrained value is discarded. + Bake, ///< When the constraint is fully-applied, the constrained value is saved. @SINCE_1_0.0 + Discard ///< When the constraint is removed, the constrained value is discarded. @SINCE_1_0.0 }; static const RemoveAction DEFAULT_REMOVE_ACTION; ///< Bake /** - * @brief Create an uninitialized Constraint; this can be initialized with Constraint::New(). + * @brief Creates an uninitialized Constraint; this can be initialized with Constraint::New(). * - * Calling member functions with an uninitialized Dali::Object is not allowed. + * Calling member functions with an uninitialized Constraint handle is not allowed. + * @SINCE_1_0.0 */ Constraint(); /** - * @brief Create a constraint which targets a property using a function or a static class member. + * @brief Creates a constraint which targets a property using a function or a static class member. * * The expected signature, for a Vector3 type for example, of the function is: * @code @@ -287,16 +306,18 @@ public: * @endcode * * Create the constraint with this function as follows: + * * @code * Constraint constraint = Constraint::New< Vector3 >( handle, CONSTRAINING_PROPERTY_INDEX, &MyFunction ); * @endcode * - * @param[in] handle The handle to the property-owning object. - * @param[in] targetIndex The index of the property to constrain. - * @param[in] function The function to call to set the constrained property value. - * @return The new constraint. + * @SINCE_1_0.0 + * @param[in] handle The handle to the property-owning object + * @param[in] targetIndex The index of the property to constrain + * @param[in] function The function to call to set the constrained property value * - * @tparam P The type of the property to constrain. + * @tparam P The type of the property to constrain + * @return The new constraint */ template< class P > static Constraint New( Handle handle, Property::Index targetIndex, void( *function )( P&, const PropertyInputContainer& ) ) @@ -306,7 +327,7 @@ public: } /** - * @brief Create a constraint which targets a property using a functor object. + * @brief Creates a constraint which targets a property using a functor object. * * The expected structure, for a Vector3 type for example, of the functor object is: * @code @@ -317,17 +338,19 @@ public: * @endcode * * Create the constraint with this object as follows: + * * @code * Constraint constraint = Constraint::New< Vector3 >( handle, CONSTRAINING_PROPERTY_INDEX, MyObject() ); * @endcode * - * @param[in] handle The handle to the property-owning object. - * @param[in] targetIndex The index of the property to constrain. - * @param[in] object The functor object whose functor is called to set the constrained property value. - * @return The new constraint. + * @SINCE_1_0.0 + * @param[in] handle The handle to the property-owning object + * @param[in] targetIndex The index of the property to constraint + * @param[in] object The functor object whose functor is called to set the constrained property value * - * @tparam P The type of the property to constrain. - * @tparam T The type of the object. + * @tparam P The type of the property to constrain + * @tparam T The type of the object + * @return The new constraint */ template< class P, class T > static Constraint New( Handle handle, Property::Index targetIndex, const T& object ) @@ -337,7 +360,7 @@ public: } /** - * @brief Create a constraint which targets a property using an object method. + * @brief Creates a constraint which targets a property using an object method. * * The expected structure, for a Vector3 type for example, of the object is: * @code @@ -348,18 +371,20 @@ public: * @endcode * * Create the constraint with this object as follows: + * * @code * Constraint constraint = Constraint::New< Vector3 >( handle, CONSTRAINING_PROPERTY_INDEX, MyObject(), &MyObject::MyMethod ); * @endcode * - * @param[in] handle The handle to the property-owning object. - * @param[in] targetIndex The index of the property to constrain. - * @param[in] object The object whose member function is called to set the constrained property value. - * @param[in] memberFunction The member function to call to set the constrained property value. - * @return The new constraint. + * @SINCE_1_0.0 + * @param[in] handle The handle to the property-owning object + * @param[in] targetIndex The index of the property to constraint + * @param[in] object The object whose member function is called to set the constrained property value + * @param[in] memberFunction The member function to call to set the constrained property value + * @return The new constraint * - * @tparam P The type of the property to constrain. - * @tparam T The type of the object. + * @tparam P The type of the property to constrain + * @tparam T The type of the object */ template< class P, class T > static Constraint New( Handle handle, Property::Index targetIndex, const T& object, void ( T::*memberFunction ) ( P&, const PropertyInputContainer& ) ) @@ -369,49 +394,54 @@ public: } /** - * @brief Creates a clones of this constraint for another object. - * - * @param[in] handle The handle to the property-owning object this constraint is to be cloned for. + * @brief Creates a clone of this constraint for another object. * - * @return The new constraint. + * @SINCE_1_0.0 + * @param[in] handle The handle to the property-owning object this constraint is to be cloned for + * @return The new constraint */ Constraint Clone( Handle handle ); /** - * @brief Destructor + * @brief Destructor. * * This is non-virtual since derived Handle types must not contain data or virtual methods. + * @SINCE_1_0.0 */ ~Constraint(); /** * @brief This copy constructor is required for (smart) pointer semantics. * - * @param [in] constraint A reference to the copied handle + * @SINCE_1_0.0 + * @param[in] constraint A reference to the copied handle */ Constraint( const Constraint& constraint ); /** * @brief This assignment operator is required for (smart) pointer semantics. * - * @param [in] rhs A reference to the copied handle + * @SINCE_1_0.0 + * @param[in] rhs A reference to the copied handle * @return A reference to this */ Constraint& operator=( const Constraint& rhs ); /** - * @brief Downcast an Object handle to Constraint handle. + * @brief Downcasts a 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] baseHandle to An object - * @return handle to a Constraint object or an uninitialized handle + * If handle points to a Constraint object, the downcast produces valid handle. + * If not, the returned handle is left uninitialized. + * @SINCE_1_0.0 + * @param[in] baseHandle BaseHandle to an object + * @return Handle to a Constraint object or an uninitialized handle */ static Constraint DownCast( BaseHandle baseHandle ); /** - * @brief Adds a constraint source to the constraint + * @brief Adds a constraint source to the constraint. * + * @SINCE_1_0.0 * @param[in] source The constraint source input to add */ void AddSource( ConstraintSource source ); @@ -419,84 +449,100 @@ public: /** * @brief Applies this constraint. * - * @pre The constraint must be initialized - * @pre The target object must still be alive - * @pre The source inputs should not have been destroyed + * @SINCE_1_0.0 + * @pre The constraint must be initialized. + * @pre The target object must still be alive. + * @pre The source inputs should not have been destroyed. */ void Apply(); /** * @brief Removes this constraint. + * @SINCE_1_0.0 */ void Remove(); /** - * @brief Retrieve the object which this constraint is targeting. + * @brief Retrieves the object which this constraint is targeting. * - * @return The target object. + * @SINCE_1_0.0 + * @return The target object */ Handle GetTargetObject(); /** - * @brief Retrieve the property which this constraint is targeting. + * @brief Retrieves the property which this constraint is targeting. * - * @return The target property. + * @SINCE_1_0.0 + * @return The target property */ Dali::Property::Index GetTargetProperty(); /** - * @brief Set whether the constraint will "bake" a value when fully-applied. + * @brief Sets the remove action. Constraint::Bake will "bake" a value when fully-applied. * - * Otherwise the constrained value will be discarded, when the constraint is removed. + * In case of Constraint::Discard, the constrained value will be discarded, when the constraint is removed. * The default value is Constraint::Bake. - * @param[in] action The remove-action. + * @SINCE_1_0.0 + * @param[in] action The remove-action */ void SetRemoveAction( RemoveAction action ); /** - * @brief Query whether the constraint will "bake" a value when fully-applied. + * @brief Retrieves the remove action that will happen when the constraint is removed. * - * Otherwise the constrained value will be discarded, when the constraint is removed. - * @return The apply-action. + * @SINCE_1_0.0 + * @return The remove-action */ RemoveAction GetRemoveAction() const; /** - * @brief Set a tag for the constraint so it can be identified later + * @brief Sets a tag for the constraint so it can be identified later. * + * @SINCE_1_0.0 * @param[in] tag An integer to identify the constraint */ - void SetTag( const unsigned int tag ); + void SetTag( const uint32_t tag ); /** - * @brief Get the tag + * @brief Gets the tag. * + * @SINCE_1_0.0 * @return The tag */ - unsigned int GetTag() const; + uint32_t GetTag() const; public: // Not intended for use by Application developers + /// @cond internal /** - * @brief This constructor is used by Dali New() methods - * @param [in] constraint A pointer to a newly allocated Dali resource + * @brief This constructor is used by Constraint::New() methods. + * @SINCE_1_0.0 + * @param[in] constraint A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL Constraint( Internal::ConstraintBase* constraint ); + /// @endcond private: // Not intended for use by Application developers + /// @cond internal /** - * @brief Construct a new constraint which targets a property. - * - * @param[in] handle The handle to the property-owning object. - * @param[in] targetIndex The index of the property to constrain. - * @param[in] targetType Type The type of the constrained property. - * @param[in] function The constraint function. - * @return The new constraint. + * @brief Constructs a new constraint which targets a property. + * + * @SINCE_1_0.0 + * @param[in] handle The handle to the property-owning object + * @param[in] targetIndex The index of the property to constrain + * @param[in] targetType Type The type of the constrained property + * @param[in] function The constraint function + * @return The new constraint */ static Constraint New( Handle handle, Property::Index targetIndex, Property::Type targetType, CallbackBase* function ); + /// @endcond }; +/** + * @} + */ } // namespace Dali -#endif // __DALI_CONSTRAINT_H__ +#endif // DALI_CONSTRAINT_H