-#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.
namespace Dali
{
+/**
+ * @addtogroup dali_core_object
+ * @{
+ */
class BaseObject;
class ConnectionTrackerInterface;
* 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);
* 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);
* @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 <class T>
- bool ConnectSignal( ConnectionTrackerInterface* connectionTracker, const std::string& signalName, const T& functor )
+ template<class T>
+ 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<Property::Value>& attributes);
+ bool DoAction(const std::string& actionName, const Property::Map& attributes);
/**
* @brief Returns the type name for the Handle.
* 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 assert, if the Dali::BaseHandle has not been initialized.
- * @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 assert, if the Dali::BaseHandle has not been initialized.
- * @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<Dali::RefObject> 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<class T>
+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 <typename T>
+template<typename T>
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<const BaseHandle&>(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 <typename T>
+template<typename T>
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<const BaseHandle&>(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