dali/public-api/object/base-handle.h

   1 #ifndef __DALI_BASE_HANDLE_H__
   2 #define __DALI_BASE_HANDLE_H__
   3
   4 /*
   5  * Copyright (c) 2015 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // EXTERNAL INCLUDES
  22 #include <string>
  23
  24 // INTERNAL INCLUDES
  25 #include <dali/public-api/common/dali-common.h>
  26 #include <dali/public-api/object/property-types.h>
  27 #include <dali/public-api/object/property-value.h>
  28 #include <dali/public-api/object/ref-object.h>
  29 #include <dali/public-api/signals/functor-delegate.h>
  30
  31 namespace Dali
  32 {
  33 /**
  34  * @addtogroup dali_core_object
  35  * @{
  36  */
  37
  38 class BaseObject;
  39 class ConnectionTrackerInterface;
  40 class TypeInfo;
  41
  42 /**
  43  * @brief Dali::BaseHandle is a handle to an internal Dali resource.
  44  *
  45  * Each Dali handle consists of a single private pointer, and a set of non-virtual forwarding functions.
  46  * This hides the internal implementation, so it may be modified without affecting the public interface.
  47  *
  48  * Dali handles have implicit smart-pointer semantics.
  49  * This avoids the need to match resource allocation methods like new/delete (the RAII idiom).
  50  *
  51  * Dali handles can be copied by value.
  52  * When a Dali handle is copied, both the copy and original will point to the same Dali resource.
  53  *
  54  * The internal Dali resources are reference counted. copying a Dali handle will increase the reference count.
  55  * A resource will not be deleted until all its Dali::BaseHandle handles are destroyed, or reset.
  56  *
  57  */
  58 class DALI_IMPORT_API BaseHandle
  59 {
  60 public:
  61
  62   /**
  63    * @brief This constructor is used by Dali New() methods.
  64    *
  65    * @param [in] handle A pointer to a newly allocated Dali resource
  66    */
  67   BaseHandle(Dali::BaseObject* handle);
  68
  69   /**
  70    * @brief This constructor provides an uninitialized Dali::BaseHandle.
  71    *
  72    * This should be initialized with a Dali New() method before use.
  73    * Methods called on an uninitialized Dali::BaseHandle will assert.
  74    * @code
  75    * BaseHandle handle; // uninitialized
  76    * handle.SomeMethod(); // unsafe! This will assert
  77    *
  78    * handle = SomeClass::New(); // now initialized
  79    * handle.SomeMethod(); // safe
  80    * @endcode
  81    */
  82   BaseHandle();
  83
  84   /**
  85    * @brief Dali::BaseHandle is intended as a base class
  86    *
  87    * This is non-virtual since derived BaseHandle types must not contain data.
  88    */
  89   ~BaseHandle();
  90
  91   /**
  92    * @brief This copy constructor is required for (smart) pointer semantics.
  93    *
  94    * @param [in] handle A reference to the copied handle
  95    */
  96   BaseHandle(const BaseHandle& handle);
  97
  98   /**
  99    * @brief This assignment operator is required for (smart) pointer semantics.
 100    *
 101    * It makes this handle use the same BaseObject as the copied handle
 102    * @param [in] rhs  A reference to the copied handle
 103    * @return A reference to this handle
 104    */
 105   BaseHandle& operator=(const BaseHandle& rhs);
 106
 107   /**
 108    * @brief Connects a void() functor to a specified signal.
 109    *
 110    * @pre The signal must be available in this object.
 111    * @param [in] connectionTracker A connection tracker which can be used to disconnect.
 112    * @param [in] signalName Name of the signal to connect to.
 113    * @param [in] functor The functor to copy.
 114    * @return True if the signal was available.
 115    */
 116   template <class T>
 117   bool ConnectSignal( ConnectionTrackerInterface* connectionTracker, const std::string& signalName, const T& functor )
 118   {
 119     return DoConnectSignal( connectionTracker, signalName, FunctorDelegate::New( functor ) );
 120   }
 121
 122   /**
 123    * @brief Perform action on this object with the given action name and attributes.
 124    *
 125    * @param [in] actionName The command for the action.
 126    * @param [in] attributes The list of attributes for the action.
 127    * @return The action is performed by the object or not.
 128    */
 129   bool DoAction(const std::string& actionName, const Property::Map& attributes);
 130
 131   /**
 132    * @brief Returns the type name for the Handle.
 133    *
 134    * Will return an empty string if the typename does not exist. This will happen for types that
 135    * have not registered with type-registry.
 136    *
 137    * @return The type name. Empty string if the typename does not exist.
 138    */
 139   const std::string& GetTypeName() const;
 140
 141   /**
 142    * @brief Returns the type info for the Handle.
 143    *
 144    * @return The type info.
 145    */
 146   bool GetTypeInfo(Dali::TypeInfo& info) const;
 147
 148 public:
 149
 150   // BaseHandle accessors
 151
 152   /**
 153    * @brief Retrieve the internal Dali resource.
 154    *
 155    * This is useful for checking the reference count of the internal resource.
 156    * This method will not check the validity of the handle so the caller is expected to check it by using if (handle)
 157    * @return The BaseObject which is referenced by the BaseHandle.
 158    */
 159   BaseObject& GetBaseObject();
 160
 161   /**
 162    * @brief Retrieve the internal Dali resource.
 163    *
 164    * This is useful for checking the reference count of the internal resource.
 165    * This method will not check the validity of the handle so the caller is expected to check it by using if (handle)
 166    * @return The BaseObject which is referenced by the BaseHandle.
 167    */
 168   const BaseObject& GetBaseObject() const;
 169
 170   /**
 171    * @brief Resets the handle.
 172    *
 173    * If no other handle copies exist, the internal Dali resouce will be deleted.
 174    * Calling this is not required i.e. it will happen automatically when a Dali::BaseHandle is destroyed.
 175    */
 176   void Reset();
 177
 178   // BaseHandle comparisons - This is a variation of the safe bool idiom
 179
 180   /**
 181    * @brief Pointer-to-member type.
 182    * Objects can be implicitly converted to this for validity checks.
 183    */
 184   typedef void (BaseHandle::*BooleanType)() const;
 185
 186   /**
 187    * @brief Converts an handle to a BooleanType.
 188    *
 189    * This is useful for checking whether the handle is empty.
 190    */
 191   operator BooleanType() const;
 192
 193   /**
 194    * @brief Equality operator overload.
 195    *
 196    * @param [in] rhs A reference to the compared handle.
 197    * @return true if the handle handles point to the same Dali resource, or if both are NULL.
 198    */
 199   bool operator==(const BaseHandle& rhs) const;
 200
 201   /**
 202    * @brief Inequality operator overload.
 203    *
 204    * @param [in] rhs A reference to the compared handle.
 205    * @return true if the handle handles point to the different Dali resources.
 206    */
 207   bool operator!=(const BaseHandle& rhs) const;
 208
 209   /**
 210    * @brief Get the reference counted object pointer.
 211    *
 212    * @return A pointer to the reference counted object.
 213    */
 214   Dali::RefObject* GetObjectPtr() const;
 215
 216 private:
 217
 218   /**
 219    * @brief Not intended for application developers.
 220    *
 221    * @param [in] connectionTracker A connection tracker which can be used to disconnect.
 222    * @param [in] signalName Name of the signal to connect to.
 223    * @param [in] functorDelegate A newly allocatated functor delegate (takes ownership).
 224    * @return True if the signal was available.
 225    */
 226   bool DoConnectSignal( ConnectionTrackerInterface* connectionTracker, const std::string& signalName, FunctorDelegate* functorDelegate );
 227
 228 protected:
 229
 230   /**
 231    * @brief Used by the safe bool idiom.
 232    *
 233    */
 234   void ThisIsSaferThanReturningVoidStar() const {}
 235
 236 private:
 237
 238   IntrusivePtr<Dali::RefObject> mObjectHandle; ///< Object this handle points at.
 239
 240 };
 241
 242 /**
 243  * @brief Template wrapper to downcast an base object handle to derived class handle.
 244  *
 245  * @pre The BaseHandle has been initialized.
 246  * @param handle to a base object
 247  * @return handle pointer to either a valid deriving handle or an uninitialized handle
 248  */
 249 template< class T >
 250 inline T DownCast( BaseHandle handle )
 251 {
 252   return T::DownCast( handle );
 253 }
 254
 255 // See also BaseHandle::BooleanType() conversion
 256
 257 /**
 258  * @brief Equality operator
 259  */
 260 template <typename T>
 261 inline bool operator==(const BaseHandle& lhs, const T& rhs)
 262 {
 263   // We depart from the safe bool idiom to allow Dali::BaseHandle derived classes to be compared
 264   return lhs == static_cast<const BaseHandle&>(rhs);
 265 }
 266
 267 /**
 268  * @brief Equality operator
 269  */
 270 template <typename T>
 271 inline bool operator!=(const BaseHandle& lhs, const T& rhs)
 272 {
 273   // We depart from the safe bool idiom to allow Dali::BaseHandle derived classes to be compared
 274   return lhs != static_cast<const BaseHandle&>(rhs);
 275 }
 276
 277 /**
 278  * @brief Less than operator
 279  */
 280 inline bool operator<(const BaseHandle& lhs, const BaseHandle& rhs)
 281 {
 282   return lhs.GetObjectPtr() < rhs.GetObjectPtr();
 283 }
 284
 285 /**
 286  * @}
 287  */
 288 } // namespace Dali
 289
 290 #endif // __DALI_BASE_HANDLE_H__