[dali_1.2.10] Merge branch 'devel/master'
[platform/core/uifw/dali-core.git] / 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  * @SINCE_1_0.0
58  */
59 class DALI_IMPORT_API BaseHandle
60 {
61 public:
62
63   /**
64    * @brief This constructor is used by Dali New() methods.
65    *
66    * @SINCE_1_0.0
67    * @param [in] handle A pointer to a newly allocated Dali resource
68    */
69   BaseHandle(Dali::BaseObject* handle);
70
71   /**
72    * @brief This constructor provides an uninitialized Dali::BaseHandle.
73    *
74    * This should be initialized with a Dali New() method before use.
75    * Methods called on an uninitialized Dali::BaseHandle will assert.
76    * @code
77    * BaseHandle handle; // uninitialized
78    * handle.SomeMethod(); // unsafe! This will assert
79    *
80    * handle = SomeClass::New(); // now initialized
81    * handle.SomeMethod(); // safe
82    * @endcode
83    * @SINCE_1_0.0
84    */
85   BaseHandle();
86
87   /**
88    * @brief Dali::BaseHandle is intended as a base class
89    *
90    * This is non-virtual since derived BaseHandle types must not contain data.
91    * @SINCE_1_0.0
92    */
93   ~BaseHandle();
94
95   /**
96    * @brief This copy constructor is required for (smart) pointer semantics.
97    *
98    * @SINCE_1_0.0
99    * @param [in] handle A reference to the copied handle
100    */
101   BaseHandle(const BaseHandle& handle);
102
103   /**
104    * @brief This assignment operator is required for (smart) pointer semantics.
105    *
106    * It makes this handle use the same BaseObject as the copied handle
107    * @SINCE_1_0.0
108    * @param [in] rhs  A reference to the copied handle
109    * @return A reference to this handle
110    */
111   BaseHandle& operator=(const BaseHandle& rhs);
112
113   /**
114    * @brief Connects a void() functor to a specified signal.
115    *
116    * @SINCE_1_0.0
117    * @param [in] connectionTracker A connection tracker which can be used to disconnect.
118    * @param [in] signalName Name of the signal to connect to.
119    * @param [in] functor The functor to copy.
120    * @return True if the signal was available.
121    * @pre The signal must be available in this object.
122    */
123   template <class T>
124   bool ConnectSignal( ConnectionTrackerInterface* connectionTracker, const std::string& signalName, const T& functor )
125   {
126     return DoConnectSignal( connectionTracker, signalName, FunctorDelegate::New( functor ) );
127   }
128
129   /**
130    * @brief Perform action on this object with the given action name and attributes.
131    *
132    * Usage example: -
133    * @code
134    * BaseHandle handle = SomeClass::New(); // Initialized with New() method
135    *
136    * Property::Map attributes; // Type is Property Map
137    * handle.DoAction("show", attributes);
138    * @endcode
139    * @SINCE_1_0.0
140    * @param [in] actionName The command for the action.
141    * @param [in] attributes The list of attributes for the action.
142    * @return The action is performed by the object or not.
143    */
144   bool DoAction(const std::string& actionName, const Property::Map& attributes);
145
146   /**
147    * @brief Returns the type name for the Handle.
148    *
149    * Will return an empty string if the typename does not exist. This will happen for types that
150    * have not registered with type-registry.
151    *
152    * @SINCE_1_0.0
153    * @return The type name. Empty string if the typename does not exist.
154    */
155   const std::string& GetTypeName() const;
156
157   /**
158    * @brief Returns the type info for the Handle.
159    *
160    * @SINCE_1_0.0
161    * @param[in] info The type information
162    * @return The type info
163    */
164   bool GetTypeInfo(Dali::TypeInfo& info) const;
165
166 public:
167
168   // BaseHandle accessors
169
170   /**
171    * @brief Retrieve the internal Dali resource.
172    *
173    * This is useful for checking the reference count of the internal resource.
174    * This method will not check the validity of the handle so the caller is expected to check it by using if (handle)
175    * @SINCE_1_0.0
176    * @return The BaseObject which is referenced by the BaseHandle.
177    */
178   BaseObject& GetBaseObject();
179
180   /**
181    * @brief Retrieve the internal Dali resource.
182    *
183    * This is useful for checking the reference count of the internal resource.
184    * This method will not check the validity of the handle so the caller is expected to check it by using if (handle)
185    * @SINCE_1_0.0
186    * @return The BaseObject which is referenced by the BaseHandle.
187    */
188   const BaseObject& GetBaseObject() const;
189
190   /**
191    * @brief Resets the handle.
192    *
193    * If no other handle copies exist, the internal Dali resouce will be deleted.
194    * Calling this is not required i.e. it will happen automatically when a Dali::BaseHandle is destroyed.
195    * @SINCE_1_0.0
196    */
197   void Reset();
198
199   // BaseHandle comparisons - This is a variation of the safe bool idiom
200
201   /**
202    * @brief Pointer-to-member type.
203    * Objects can be implicitly converted to this for validity checks.
204    */
205   typedef void (BaseHandle::*BooleanType)() const;
206
207   /**
208    * @brief Converts an handle to a BooleanType.
209    *
210    * This is useful for checking whether the handle is empty.
211    * @SINCE_1_0.0
212    */
213   operator BooleanType() const;
214
215   /**
216    * @brief Equality operator overload.
217    *
218    * @SINCE_1_0.0
219    * @param [in] rhs A reference to the compared handle.
220    * @return true if the handle handles point to the same Dali resource, or if both are NULL.
221    */
222   bool operator==(const BaseHandle& rhs) const;
223
224   /**
225    * @brief Inequality operator overload.
226    *
227    * @SINCE_1_0.0
228    * @param [in] rhs A reference to the compared handle.
229    * @return true if the handle handles point to the different Dali resources.
230    */
231   bool operator!=(const BaseHandle& rhs) const;
232
233   /**
234    * @brief Get the reference counted object pointer.
235    *
236    * @SINCE_1_0.0
237    * @return A pointer to the reference counted object.
238    */
239   Dali::RefObject* GetObjectPtr() const;
240
241 private:
242
243   /**
244    * @brief Not intended for application developers.
245    *
246    * @SINCE_1_0.0
247    * @param [in] connectionTracker A connection tracker which can be used to disconnect.
248    * @param [in] signalName Name of the signal to connect to.
249    * @param [in] functorDelegate A newly allocatated functor delegate (takes ownership).
250    * @return True if the signal was available.
251    */
252   bool DoConnectSignal( ConnectionTrackerInterface* connectionTracker, const std::string& signalName, FunctorDelegate* functorDelegate );
253
254 protected:
255
256   /**
257    * @brief Used by the safe bool idiom.
258    *
259    * The safe bool idiom basically provides a Boolean test for classes. It validates objects
260    * in a boolean context without the usual harmful side effects.
261    * @SINCE_1_0.0
262    */
263   void ThisIsSaferThanReturningVoidStar() const {}
264
265 private:
266
267   IntrusivePtr<Dali::RefObject> mObjectHandle; ///< Object this handle points at.
268
269 };
270
271 /**
272  * @brief Template wrapper to downcast a base object handle to derived class handle.
273  *
274  * @SINCE_1_0.0
275  * @param handle to a base object
276  * @return handle pointer to either a valid deriving handle or an uninitialized handle
277  * @pre The BaseHandle has been initialized.
278  */
279 template< class T >
280 inline T DownCast( BaseHandle handle )
281 {
282   return T::DownCast( handle );
283 }
284
285 // See also BaseHandle::BooleanType() conversion
286
287 /**
288  * @brief Equality operator
289  * @SINCE_1_0.0
290  * @param[in] lhs A reference to compare
291  * @param[in] rhs A reference to compare to
292  * @return true if the handle handles point to the same Dali resource, or if both are NULL
293  */
294 template <typename T>
295 inline bool operator==(const BaseHandle& lhs, const T& rhs)
296 {
297   // We depart from the safe bool idiom to allow Dali::BaseHandle derived classes to be compared
298   return lhs == static_cast<const BaseHandle&>(rhs);
299 }
300
301 /**
302  * @brief Equality operator
303  * @SINCE_1_0.0
304  * @param[in] lhs A reference to compare
305  * @param[in] rhs A reference to compare to
306  * @return true if the handle handles point to the different Dali resources
307  */
308 template <typename T>
309 inline bool operator!=(const BaseHandle& lhs, const T& rhs)
310 {
311   // We depart from the safe bool idiom to allow Dali::BaseHandle derived classes to be compared
312   return lhs != static_cast<const BaseHandle&>(rhs);
313 }
314
315 /**
316  * @brief Less than operator
317  * @SINCE_1_0.0
318  * @param[in] lhs A reference to compare
319  * @param[in] rhs A reference to compare to
320  * @return true if lhs less than rhs
321  */
322 inline bool operator<(const BaseHandle& lhs, const BaseHandle& rhs)
323 {
324   return lhs.GetObjectPtr() < rhs.GetObjectPtr();
325 }
326
327 /**
328  * @}
329  */
330 } // namespace Dali
331
332 #endif // __DALI_BASE_HANDLE_H__