1 #ifndef DALI_BASE_HANDLE_H
2 #define DALI_BASE_HANDLE_H
5 * Copyright (c) 2020 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
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>
34 * @addtogroup dali_core_object
39 class ConnectionTrackerInterface;
43 * @brief Dali::BaseHandle is a handle to an internal Dali resource.
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.
48 * Dali handles have implicit smart-pointer semantics.
49 * This avoids the need to match resource allocation methods like new/delete (the RAII idiom).
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.
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.
59 class DALI_CORE_API BaseHandle
64 * @brief This constructor is used by Dali New() methods.
67 * @param[in] handle A pointer to a newly allocated Dali resource
69 BaseHandle(Dali::BaseObject* handle);
72 * @brief This constructor provides an uninitialized Dali::BaseHandle.
74 * This should be initialized with a Dali New() method before use.
75 * Methods called on an uninitialized Dali::BaseHandle will assert.
77 * BaseHandle handle; // uninitialized
78 * handle.SomeMethod(); // unsafe! This will assert
80 * handle = SomeClass::New(); // now initialized
81 * handle.SomeMethod(); // safe
88 * @brief Dali::BaseHandle is intended as a base class.
90 * This is non-virtual since derived BaseHandle types must not contain data.
96 * @brief This copy constructor is required for (smart) pointer semantics.
99 * @param[in] handle A reference to the copied handle
101 BaseHandle(const BaseHandle& handle);
104 * @brief This assignment operator is required for (smart) pointer semantics.
106 * It makes this handle use the same BaseObject as the copied handle
108 * @param[in] rhs A reference to the copied handle
109 * @return A reference to this handle
111 BaseHandle& operator=(const BaseHandle& rhs);
114 * @brief Move constructor.
117 * @param[in] rhs A reference to the moved handle
119 BaseHandle( BaseHandle&& rhs );
122 * @brief Move assignment operator.
125 * @param[in] rhs A reference to the moved handle
126 * @return A reference to this handle
128 BaseHandle& operator=( BaseHandle&& rhs );
131 * @brief Connects a void() functor to a specified signal.
134 * @param[in] connectionTracker A connection tracker which can be used to disconnect
135 * @param[in] signalName Name of the signal to connect to
136 * @param[in] functor The functor to copy
137 * @return True if the signal was available
138 * @pre The signal must be available in this object.
141 bool ConnectSignal( ConnectionTrackerInterface* connectionTracker, const std::string& signalName, const T& functor )
143 return DoConnectSignal( connectionTracker, signalName, FunctorDelegate::New( functor ) );
147 * @brief Performs an action on this object with the given action name and attributes.
151 * BaseHandle handle = SomeClass::New(); // Initialized with New() method
153 * Property::Map attributes; // Type is Property Map
154 * handle.DoAction("show", attributes);
157 * @param[in] actionName The command for the action
158 * @param[in] attributes The list of attributes for the action
159 * @return The action is performed by the object or not
161 bool DoAction(const std::string& actionName, const Property::Map& attributes);
164 * @brief Returns the type name for the Handle.
166 * Will return an empty string if the typename does not exist. This will happen for types that
167 * have not registered with type-registry.
170 * @return The type name. Empty string if the typename does not exist
172 const std::string& GetTypeName() const;
175 * @brief Returns the type info for the Handle.
178 * @param[out] info The type information
179 * @return true if the type info exists
181 bool GetTypeInfo(Dali::TypeInfo& info) const;
185 // BaseHandle accessors
188 * @brief Retrieves the internal Dali resource.
190 * This is useful for checking the reference count of the internal resource.
191 * This method will not check the validity of the handle so the caller is expected to check it by using if (handle).
193 * @return The BaseObject which is referenced by the BaseHandle
195 BaseObject& GetBaseObject();
198 * @brief Retrieves the internal Dali resource.
200 * This is useful for checking the reference count of the internal resource.
201 * This method will not check the validity of the handle so the caller is expected to check it by using if (handle).
203 * @return The BaseObject which is referenced by the BaseHandle
205 const BaseObject& GetBaseObject() const;
208 * @brief Resets the handle.
210 * If no other handle copies exist, the internal Dali resource will be deleted.
211 * Calling this is not required i.e. it will happen automatically when a Dali::BaseHandle is destroyed.
216 // BaseHandle comparisons - This is a variation of the safe bool idiom
219 * @brief Pointer-to-member type.
220 * Objects can be implicitly converted to this for validity checks.
222 typedef void (BaseHandle::*BooleanType)() const;
225 * @brief Converts an handle to a BooleanType.
227 * This is useful for checking whether the handle is empty.
230 operator BooleanType() const;
233 * @brief Equality operator overload.
236 * @param[in] rhs A reference to the compared handle
237 * @return True if the handle handles point to the same Dali resource, or if both are NULL
239 bool operator==(const BaseHandle& rhs) const;
242 * @brief Inequality operator overload.
245 * @param[in] rhs A reference to the compared handle
246 * @return True if the handle handles point to the different Dali resources
248 bool operator!=(const BaseHandle& rhs) const;
251 * @brief Gets the reference counted object pointer.
254 * @return A pointer to the reference counted object
256 Dali::RefObject* GetObjectPtr() const;
261 * @brief Not intended for application developers.
264 * @param[in] connectionTracker A connection tracker which can be used to disconnect
265 * @param[in] signalName Name of the signal to connect to
266 * @param[in] functorDelegate A newly allocated functor delegate (takes ownership)
267 * @return True if the signal was available
269 bool DoConnectSignal( ConnectionTrackerInterface* connectionTracker, const std::string& signalName, FunctorDelegate* functorDelegate );
274 * @brief Used by the safe bool idiom.
276 * The safe bool idiom basically provides a Boolean test for classes. It validates objects
277 * in a boolean context without the usual harmful side effects.
280 void ThisIsSaferThanReturningVoidStar() const {}
284 IntrusivePtr<Dali::RefObject> mObjectHandle; ///< Object this handle points at.
289 * @brief Template wrapper to downcast a base object handle to derived class handle.
292 * @param[in] handle Handle to a base object
293 * @return Handle pointer to either a valid deriving handle or an uninitialized handle
294 * @pre The BaseHandle has been initialized.
297 inline T DownCast( BaseHandle handle )
299 return T::DownCast( handle );
302 // See also BaseHandle::BooleanType() conversion
305 * @brief Equality operator.
307 * @param[in] lhs A reference to compare
308 * @param[in] rhs A reference to compare to
309 * @return True if the handle handles point to the same Dali resource, or if both are NULL
311 template <typename T>
312 inline bool operator==(const BaseHandle& lhs, const T& rhs)
314 // We depart from the safe bool idiom to allow Dali::BaseHandle derived classes to be compared
315 return lhs == static_cast<const BaseHandle&>(rhs);
319 * @brief Equality operator.
321 * @param[in] lhs A reference to compare
322 * @param[in] rhs A reference to compare to
323 * @return True if the handle handles point to the different Dali resources
325 template <typename T>
326 inline bool operator!=(const BaseHandle& lhs, const T& rhs)
328 // We depart from the safe bool idiom to allow Dali::BaseHandle derived classes to be compared
329 return lhs != static_cast<const BaseHandle&>(rhs);
333 * @brief Less than operator.
335 * @param[in] lhs A reference to compare
336 * @param[in] rhs A reference to compare to
337 * @return True if lhs less than rhs
339 inline bool operator<(const BaseHandle& lhs, const BaseHandle& rhs)
341 return lhs.GetObjectPtr() < rhs.GetObjectPtr();
349 #endif // DALI_BASE_HANDLE_H