X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Fobject%2Fbase-handle.h;h=8acba6dfdb28f1c06ece79dc2e700e70242a87f6;hb=refs%2Ftags%2Faccepted%2Ftizen%2F3.0%2Fivi%2F20170118.041123;hp=77bd59e6bc8ddb667c078781c4c77dc74a8bdd49;hpb=4201fc9ccb4f5a06b44cd45407e6f3c8c6bd449c;p=platform%2Fcore%2Fuifw%2Fdali-core.git diff --git a/dali/public-api/object/base-handle.h b/dali/public-api/object/base-handle.h index 77bd59e..8acba6d 100644 --- a/dali/public-api/object/base-handle.h +++ b/dali/public-api/object/base-handle.h @@ -2,7 +2,7 @@ #define __DALI_BASE_HANDLE_H__ /* - * Copyright (c) 2014 Samsung Electronics Co., Ltd. + * Copyright (c) 2015 Samsung Electronics Co., Ltd. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -30,6 +30,10 @@ namespace Dali { +/** + * @addtogroup dali_core_object + * @{ + */ class BaseObject; class ConnectionTrackerInterface; @@ -50,6 +54,7 @@ class TypeInfo; * The internal Dali resources are reference counted. copying a Dali handle will increase the reference count. * A resource will not be deleted until all its Dali::BaseHandle handles are destroyed, or reset. * + * @SINCE_1_0.0 */ class DALI_IMPORT_API BaseHandle { @@ -58,6 +63,7 @@ public: /** * @brief This constructor is used by Dali New() methods. * + * @SINCE_1_0.0 * @param [in] handle A pointer to a newly allocated Dali resource */ BaseHandle(Dali::BaseObject* handle); @@ -74,6 +80,7 @@ public: * handle = SomeClass::New(); // now initialized * handle.SomeMethod(); // safe * @endcode + * @SINCE_1_0.0 */ BaseHandle(); @@ -81,12 +88,14 @@ public: * @brief Dali::BaseHandle is intended as a base class * * This is non-virtual since derived BaseHandle types must not contain data. + * @SINCE_1_0.0 */ ~BaseHandle(); /** * @brief This copy constructor is required for (smart) pointer semantics. * + * @SINCE_1_0.0 * @param [in] handle A reference to the copied handle */ BaseHandle(const BaseHandle& handle); @@ -95,6 +104,7 @@ public: * @brief This assignment operator is required for (smart) pointer semantics. * * It makes this handle use the same BaseObject as the copied handle + * @SINCE_1_0.0 * @param [in] rhs A reference to the copied handle * @return A reference to this handle */ @@ -103,11 +113,12 @@ public: /** * @brief Connects a void() functor to a specified signal. * - * @pre The signal must be available in this object. + * @SINCE_1_0.0 * @param [in] connectionTracker A connection tracker which can be used to disconnect. * @param [in] signalName Name of the signal to connect to. * @param [in] functor The functor to copy. * @return True if the signal was available. + * @pre The signal must be available in this object. */ template bool ConnectSignal( ConnectionTrackerInterface* connectionTracker, const std::string& signalName, const T& functor ) @@ -118,11 +129,19 @@ public: /** * @brief Perform action on this object with the given action name and attributes. * + * Usage example: - + * @code + * BaseHandle handle = SomeClass::New(); // Initialized with New() method + * + * Property::Map attributes; // Use empty Property::Map because "show" action doesn't need parameter + * handle.DoAction("show", attributes); + * @endcode + * @SINCE_1_0.0 * @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. */ - bool DoAction(const std::string& actionName, const std::vector& attributes); + bool DoAction(const std::string& actionName, const Property::Map& attributes); /** * @brief Returns the type name for the Handle. @@ -130,6 +149,7 @@ public: * Will return an empty string if the typename does not exist. This will happen for types that * have not registered with type-registry. * + * @SINCE_1_0.0 * @return The type name. Empty string if the typename does not exist. */ const std::string& GetTypeName() const; @@ -137,7 +157,9 @@ public: /** * @brief Returns the type info for the Handle. * - * @return The type info. + * @SINCE_1_0.0 + * @param[in] info The type information + * @return The type info */ bool GetTypeInfo(Dali::TypeInfo& info) const; @@ -149,7 +171,8 @@ public: * @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. + * This method will not check the validity of the handle so the caller is expected to check it by using if (handle) + * @SINCE_1_0.0 * @return The BaseObject which is referenced by the BaseHandle. */ BaseObject& GetBaseObject(); @@ -158,7 +181,8 @@ public: * @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. + * This method will not check the validity of the handle so the caller is expected to check it by using if (handle) + * @SINCE_1_0.0 * @return The BaseObject which is referenced by the BaseHandle. */ const BaseObject& GetBaseObject() const; @@ -168,6 +192,7 @@ public: * * 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. + * @SINCE_1_0.0 */ void Reset(); @@ -183,12 +208,14 @@ public: * @brief Converts an handle to a BooleanType. * * This is useful for checking whether the handle is empty. + * @SINCE_1_0.0 */ operator BooleanType() const; /** * @brief Equality operator overload. * + * @SINCE_1_0.0 * @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. */ @@ -197,6 +224,7 @@ public: /** * @brief Inequality operator overload. * + * @SINCE_1_0.0 * @param [in] rhs A reference to the compared handle. * @return true if the handle handles point to the different Dali resources. */ @@ -205,6 +233,7 @@ public: /** * @brief Get the reference counted object pointer. * + * @SINCE_1_0.0 * @return A pointer to the reference counted object. */ Dali::RefObject* GetObjectPtr() const; @@ -214,6 +243,7 @@ private: /** * @brief Not intended for application developers. * + * @SINCE_1_0.0 * @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). @@ -221,9 +251,14 @@ private: */ bool DoConnectSignal( ConnectionTrackerInterface* connectionTracker, const std::string& signalName, FunctorDelegate* functorDelegate ); +protected: + /** * @brief Used by the safe bool idiom. * + * The safe bool idiom basically provides a Boolean test for classes. It validates objects + * in a boolean context without the usual harmful side effects. + * @SINCE_1_0.0 */ void ThisIsSaferThanReturningVoidStar() const {} @@ -234,11 +269,12 @@ private: }; /** - * @brief Template wrapper to downcast an base object handle to derived class handle. + * @brief Template wrapper to downcast a base object handle to derived class handle. * - * @pre The BaseHandle has been initialized. - * @param handle to a base object + * @SINCE_1_0.0 + * @param[in] handle to a base object * @return handle pointer to either a valid deriving handle or an uninitialized handle + * @pre The BaseHandle has been initialized. */ template< class T > inline T DownCast( BaseHandle handle ) @@ -250,6 +286,10 @@ inline T DownCast( BaseHandle handle ) /** * @brief Equality operator + * @SINCE_1_0.0 + * @param[in] lhs A reference to compare + * @param[in] rhs A reference to compare to + * @return true if the handle handles point to the same Dali resource, or if both are NULL */ template inline bool operator==(const BaseHandle& lhs, const T& rhs) @@ -260,6 +300,10 @@ inline bool operator==(const BaseHandle& lhs, const T& rhs) /** * @brief Equality operator + * @SINCE_1_0.0 + * @param[in] lhs A reference to compare + * @param[in] rhs A reference to compare to + * @return true if the handle handles point to the different Dali resources */ template inline bool operator!=(const BaseHandle& lhs, const T& rhs) @@ -270,12 +314,19 @@ inline bool operator!=(const BaseHandle& lhs, const T& rhs) /** * @brief Less than operator + * @SINCE_1_0.0 + * @param[in] lhs A reference to compare + * @param[in] rhs A reference to compare to + * @return true if lhs less than rhs */ inline bool operator<(const BaseHandle& lhs, const BaseHandle& rhs) { return lhs.GetObjectPtr() < rhs.GetObjectPtr(); } +/** + * @} + */ } // namespace Dali #endif // __DALI_BASE_HANDLE_H__