X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Fobject%2Fbase-handle.h;h=cca565ad192a4e80ac9a9ddb5774dd904309ea6f;hb=baad1726f5f7f05d98da7ca591f24dbe3c49dab2;hp=2f5641a8bcbded57b7009207b6754defd3c9f34d;hpb=54dff6a35a504884c076a370b660ed9a0a6c6bdb;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 2f5641a..cca565a 100644 --- a/dali/public-api/object/base-handle.h +++ b/dali/public-api/object/base-handle.h @@ -1,8 +1,8 @@ -#ifndef __DALI_BASE_HANDLE_H__ -#define __DALI_BASE_HANDLE_H__ +#ifndef DALI_BASE_HANDLE_H +#define DALI_BASE_HANDLE_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. @@ -31,7 +31,7 @@ namespace Dali { /** - * @addtogroup dali-core-object + * @addtogroup dali_core_object * @{ */ @@ -54,15 +54,17 @@ 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 +class DALI_CORE_API BaseHandle { public: /** * @brief This constructor is used by Dali New() methods. * - * @param [in] handle A pointer to a newly allocated Dali resource + * @SINCE_1_0.0 + * @param[in] handle A pointer to a newly allocated Dali resource */ BaseHandle(Dali::BaseObject* handle); @@ -78,20 +80,23 @@ public: * handle = SomeClass::New(); // now initialized * handle.SomeMethod(); // safe * @endcode + * @SINCE_1_0.0 */ BaseHandle(); /** - * @brief Dali::BaseHandle is intended as a base class + * @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. * - * @param [in] handle A reference to the copied handle + * @SINCE_1_0.0 + * @param[in] handle A reference to the copied handle */ BaseHandle(const BaseHandle& handle); @@ -99,7 +104,8 @@ public: * @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 + * @SINCE_1_0.0 + * @param[in] rhs A reference to the copied handle * @return A reference to this handle */ BaseHandle& operator=(const BaseHandle& rhs); @@ -107,11 +113,12 @@ public: /** * @brief Connects a void() functor to a specified signal. * + * @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. - * @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. */ template bool ConnectSignal( ConnectionTrackerInterface* connectionTracker, const std::string& signalName, const T& functor ) @@ -120,11 +127,19 @@ public: } /** - * @brief Perform action on this object with the given action name and attributes. + * @brief Performs an 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. + * Usage example: - + * @code + * BaseHandle handle = SomeClass::New(); // Initialized with New() method + * + * Property::Map attributes; // Type is Property Map + * 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 Property::Map& attributes); @@ -134,14 +149,17 @@ public: * Will return an empty string if the typename does not exist. This will happen for types that * have not registered with type-registry. * - * @return The type name. Empty string if the typename does not exist. + * @SINCE_1_0.0 + * @return The type name. Empty string if the typename does not exist */ const std::string& GetTypeName() const; /** * @brief Returns the type info for the Handle. * - * @return The type info. + * @SINCE_1_0.0 + * @param[out] info The type information + * @return true if the type info exists */ bool GetTypeInfo(Dali::TypeInfo& info) const; @@ -150,28 +168,31 @@ public: // BaseHandle accessors /** - * @brief Retrieve the internal Dali resource. + * @brief Retrieves the internal Dali resource. * * This is useful for checking the reference count of the internal resource. - * This method will not check the validity of the handle so the caller is expected to check it by using if (handle) - * @return The BaseObject which is referenced by the BaseHandle. + * 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(); /** - * @brief Retrieve the internal Dali resource. + * @brief Retrieves the internal Dali resource. * * This is useful for checking the reference count of the internal resource. - * This method will not check the validity of the handle so the caller is expected to check it by using if (handle) - * @return The BaseObject which is referenced by the BaseHandle. + * 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; /** * @brief Resets the handle. * - * If no other handle copies exist, the internal Dali resouce will be deleted. + * If no other handle copies exist, the internal Dali resource 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(); @@ -187,29 +208,33 @@ 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. * - * @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. + * @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 */ bool operator==(const BaseHandle& rhs) const; /** * @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. + * @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 */ bool operator!=(const BaseHandle& rhs) const; /** - * @brief Get the reference counted object pointer. + * @brief Gets the reference counted object pointer. * - * @return A pointer to the reference counted object. + * @SINCE_1_0.0 + * @return A pointer to the reference counted object */ Dali::RefObject* GetObjectPtr() const; @@ -218,10 +243,11 @@ private: /** * @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). - * @return True if the signal was available. + * @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 allocated functor delegate (takes ownership) + * @return True if the signal was available */ bool DoConnectSignal( ConnectionTrackerInterface* connectionTracker, const std::string& signalName, FunctorDelegate* functorDelegate ); @@ -230,6 +256,9 @@ 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 {} @@ -240,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. * + * @SINCE_1_0.0 + * @param[in] handle Handle to a base object + * @return Handle pointer to either a valid deriving handle or an uninitialized 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 */ template< class T > inline T DownCast( BaseHandle handle ) @@ -255,7 +285,11 @@ inline T DownCast( BaseHandle handle ) // See also BaseHandle::BooleanType() conversion /** - * @brief Equality operator + * @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) @@ -265,7 +299,11 @@ inline bool operator==(const BaseHandle& lhs, const T& rhs) } /** - * @brief Equality operator + * @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) @@ -275,7 +313,11 @@ inline bool operator!=(const BaseHandle& lhs, const T& rhs) } /** - * @brief Less than operator + * @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) { @@ -287,4 +329,4 @@ inline bool operator<(const BaseHandle& lhs, const BaseHandle& rhs) */ } // namespace Dali -#endif // __DALI_BASE_HANDLE_H__ +#endif // DALI_BASE_HANDLE_H