X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Fobject%2Fbase-handle.h;h=e275473fa41cc740358284fc53731779226a029f;hb=b8153c3ab592e6ebeaeebf31137538f972c27653;hp=e726bcd070e39e8d28a8d1d468b8b07ca5f77c1a;hpb=a372475ad8ce462bd0bd2001fdb4433affc36859;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 e726bcd..e275473 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) 2014 Samsung Electronics Co., Ltd. + * Copyright (c) 2020 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,15 +54,16 @@ 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); @@ -74,20 +79,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); @@ -95,34 +103,61 @@ 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); /** + * @brief Move constructor. + * + * @SINCE_1_9.22 + * @param[in] rhs A reference to the moved handle + */ + BaseHandle(BaseHandle&& rhs); + + /** + * @brief Move assignment operator. + * + * @SINCE_1_9.22 + * @param[in] rhs A reference to the moved handle + * @return A reference to this handle + */ + BaseHandle& operator=(BaseHandle&& rhs); + + /** * @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 ) + template + bool ConnectSignal(ConnectionTrackerInterface* connectionTracker, const std::string& signalName, const T& functor) { - return DoConnectSignal( connectionTracker, signalName, FunctorDelegate::New( functor ) ); + return DoConnectSignal(connectionTracker, signalName, FunctorDelegate::New(functor)); } /** - * @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 std::vector& attributes); + bool DoAction(const std::string& actionName, const Property::Map& attributes); /** * @brief Returns the type name for the Handle. @@ -130,152 +165,159 @@ 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; 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(); - // BaseHandle comparisons - This is a variation of the safe bool idiom - - /** - * @brief Pointer-to-member type. - * Objects can be implicitly converted to this for validity checks. - */ - typedef void (BaseHandle::*BooleanType)() const; + // BaseHandle comparisons /** - * @brief Converts an handle to a BooleanType. + * @brief Converts an handle to a bool. * * This is useful for checking whether the handle is empty. + * @SINCE_1_0.0 */ - operator BooleanType() const; + explicit operator bool() 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; 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. - */ - bool DoConnectSignal( ConnectionTrackerInterface* connectionTracker, const std::string& signalName, FunctorDelegate* functorDelegate ); - - /** - * @brief Used by the safe bool idiom. - * + * @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 */ - void ThisIsSaferThanReturningVoidStar() const {} + bool DoConnectSignal(ConnectionTrackerInterface* connectionTracker, const std::string& signalName, FunctorDelegate* functorDelegate); private: - IntrusivePtr mObjectHandle; ///< Object this handle points at. - }; /** - * @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 ) +template +inline T DownCast(BaseHandle handle) { - return T::DownCast( handle ); + return T::DownCast(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 +template inline bool operator==(const BaseHandle& lhs, const T& rhs) { - // We depart from the safe bool idiom to allow Dali::BaseHandle derived classes to be compared return lhs == static_cast(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 +template inline bool operator!=(const BaseHandle& lhs, const T& rhs) { - // We depart from the safe bool idiom to allow Dali::BaseHandle derived classes to be compared return lhs != static_cast(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) { return lhs.GetObjectPtr() < rhs.GetObjectPtr(); } +/** + * @} + */ } // namespace Dali -#endif // __DALI_BASE_HANDLE_H__ +#endif // DALI_BASE_HANDLE_H