dali/public-api/object/type-registry.h

   1 #ifndef DALI_TYPE_REGISTRY_H
   2 #define DALI_TYPE_REGISTRY_H
   3
   4 /*
   5  * Copyright (c) 2020 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 <typeinfo>
  23 #include <cstdint> // uint32_t
  24
  25 // INTERNAL INCLUDES
  26 #include <dali/public-api/object/base-handle.h>
  27 #include <dali/public-api/object/type-info.h>
  28
  29 namespace Dali
  30 {
  31 /**
  32  * @addtogroup dali_core_object
  33  * @{
  34  */
  35
  36 namespace Internal DALI_INTERNAL
  37 {
  38 class TypeRegistry;
  39 }
  40 struct DefaultPropertyMetadata;
  41
  42 /**
  43  * @brief The TypeRegistry allows registration of type instance creation functions.
  44  *
  45  * These can then be created later by name and down cast to the appropriate type.
  46  *
  47  * Usage: (Registering)
  48  *
  49  * In my-actor.cpp
  50  * @code
  51  * // Note: object construction in namespace scope is defined in a translation unit as being
  52  * //       in appearance order (C++ standard 3.6/2). So TypeRegistration is declared first in
  53  * //       the cpp file below. Signal, action and property declarations follow in any order.
  54  * namespace
  55  * {
  56  *   TypeRegistration myActorType(typeid(MyActor), typeid(Actor), CreateMyActor );
  57  *
  58  *   SignalConnectorType( myActorType, "highlighted", ConnectSignalForMyActor );
  59  *   TypeAction( myActorType, "open", DoMyActorAction );
  60  *   TypeAction( myActorType, "close", DoMyActorAction );
  61  *   PropertyRegistration( myActorType, "status", PropertyRegistration::START_INDEX, Property::BOOLEAN, SetPropertyFunction, GetPropertyFunction );
  62  * }
  63  * @endcode
  64  *
  65  * Usage: (Creation)
  66  *
  67  * @code
  68  *   TypeRegistry::TypeInfo type = TypeRegistry::Get().GetTypeInfo("MyActor");
  69  *   MyActor a = MyActor::DownCast(type.CreateInstance());
  70  *   if(a)
  71  *   {
  72  *     ...
  73  *   }
  74  * @endcode
  75  *
  76  * CustomActor
  77  *
  78  *  Actors that inherit from the CustomActor framework must ensure the implementation
  79  *  class has an identical name to the Actor class. This is to ensure the class can be
  80  *  found at runtime for signals and actions. Otherwise these will silently fail.
  81  *
  82  *  As namespaces are discarded the convention is to use a namespace ie
  83  *
  84  *    'class MyActor {}; namespace Internal { class MyActor {}; }'
  85  *
  86  *  Warning: this arrangement will silently fail
  87  *
  88  *    'class MyActor {}; class MyActorImpl {};'
  89  *
  90  * Naming Conventions
  91  *
  92  *   Signal and action names follow properties and are by convention lower case hyphen
  93  *   separated ie 'next-page'. This maintains consistency with the scripted interface.
  94  *
  95  * @SINCE_1_0.0
  96  */
  97 class DALI_CORE_API TypeRegistry : public BaseHandle
  98 {
  99 public:
 100   /**
 101    * @brief Gets Type Registry handle.
 102    *
 103    * @SINCE_1_0.0
 104    * @return TypeRegistry handle
 105    */
 106   static TypeRegistry Get();
 107
 108   /**
 109    * @brief Allows the creation of an empty typeRegistry handle.
 110    * @SINCE_1_0.0
 111    */
 112   TypeRegistry();
 113
 114   /**
 115    * @brief Destructor.
 116    * @SINCE_1_0.0
 117    */
 118   ~TypeRegistry();
 119
 120   /**
 121    * @brief This copy constructor is required for (smart) pointer semantics.
 122    *
 123    * @SINCE_1_0.0
 124    * @param[in] handle A reference to the copied handle
 125    */
 126   TypeRegistry(const TypeRegistry& handle);
 127
 128   /**
 129    * @brief This assignment operator is required for (smart) pointer semantics.
 130    *
 131    * @SINCE_1_0.0
 132    * @param[in] rhs A reference to the copied handle
 133    * @return A reference to this
 134    */
 135   TypeRegistry& operator=(const TypeRegistry& rhs);
 136
 137   /**
 138    * @brief Move constructor.
 139    *
 140    * @SINCE_1_9.22
 141    * @param[in] rhs A reference to the moved handle
 142    */
 143   TypeRegistry( TypeRegistry&& rhs );
 144
 145   /**
 146    * @brief Move assignment operator.
 147    *
 148    * @SINCE_1_9.22
 149    * @param[in] rhs A reference to the moved handle
 150    * @return A reference to this handle
 151    */
 152   TypeRegistry& operator=( TypeRegistry&& rhs );
 153
 154   /**
 155    * @brief Gets TypeInfo for a registered type.
 156    *
 157    * @SINCE_1_0.0
 158    * @param[in] uniqueTypeName A unique type name
 159    * @return TypeInfo if the type exists, otherwise an empty handle
 160    */
 161   TypeInfo GetTypeInfo( const std::string &uniqueTypeName );
 162
 163   /**
 164    * @brief Gets TypeInfo for a registered type.
 165    *
 166    * @SINCE_1_0.0
 167    * @param[in] registerType The registered type info
 168    * @return TypeInfo if the type exists, otherwise an empty handle
 169    */
 170   TypeInfo GetTypeInfo( const std::type_info& registerType );
 171
 172   /**
 173    * @brief Gets type name count.
 174    *
 175    * @SINCE_1_0.0
 176    * @return The count
 177    */
 178   size_t GetTypeNameCount() const;
 179
 180   /**
 181    * @brief Gets type names by index.
 182    *
 183    * @SINCE_1_0.0
 184    * @param[in] index The index to get the type name
 185    * @return The type name or an empty string when index is not valid
 186    */
 187   std::string GetTypeName(size_t index) const;
 188
 189 public: // Not intended for application developers
 190
 191   /// @cond internal
 192   /**
 193    * @brief This constructor is used by Dali Get() method.
 194    *
 195    * @SINCE_1_0.0
 196    * @param[in] typeRegistry A pointer to a Dali resource
 197    */
 198   explicit DALI_INTERNAL TypeRegistry(Internal::TypeRegistry*typeRegistry);
 199   /// @endcond
 200 };
 201
 202 /**
 203  * @brief Registers a type from type info.
 204  * @SINCE_1_0.0
 205  */
 206 class DALI_CORE_API TypeRegistration
 207 {
 208 public:
 209   /**
 210    * @brief Constructor registers the type creation function.
 211    *
 212    * @SINCE_1_0.0
 213    * @param[in] registerType The type info for the type to be registered
 214    * @param[in] baseType The base type info of registerType
 215    * @param[in] f registerType Instance creation function
 216    */
 217   TypeRegistration( const std::type_info& registerType, const std::type_info& baseType,
 218                     TypeInfo::CreateFunction f );
 219
 220   /**
 221    * @brief Constructor registers the type creation function.
 222    *
 223    * @SINCE_1_0.0
 224    * @param[in] registerType the type info for the type to be registered
 225    * @param[in] baseType the base type info of registerType
 226    * @param[in] f registerType instance creation function
 227    * @param[in] callCreateOnInit If true the creation function is called as part of Dali initialization
 228    */
 229   TypeRegistration( const std::type_info& registerType, const std::type_info& baseType,
 230                     TypeInfo::CreateFunction f, bool callCreateOnInit );
 231
 232   /**
 233    * @brief Constructor registers the type creation function.
 234    *
 235    * @SINCE_1_4.0
 236    * @param[in] registerType the type info for the type to be registered
 237    * @param[in] baseType the base type info of registerType
 238    * @param[in] f registerType instance creation function
 239    * @param[in] defaultProperties the default property meta-data
 240    */
 241   TypeRegistration( const std::type_info& registerType, const std::type_info& baseType,
 242                     TypeInfo::CreateFunction f, const DefaultPropertyMetadata& defaultProperties );
 243
 244   /**
 245    * @brief Constructor registers the type creation function for a named class or type.
 246    *
 247    * This allows types to be created dynamically from script. The name must be
 248    * unique for successful registration.
 249    * @SINCE_1_0.0
 250    * @param[in] name the name of the type to be registered
 251    * @param[in] baseType the base type info of registerType
 252    * @param[in] f registerType instance creation function
 253    */
 254   TypeRegistration( const std::string& name, const std::type_info& baseType,
 255                     TypeInfo::CreateFunction f );
 256
 257   /**
 258    * @brief The name the type is registered under (derived from type_info).
 259    *
 260    * @SINCE_1_0.0
 261    * @return The registered name or empty if unregistered
 262    */
 263   const std::string RegisteredName() const;
 264
 265 private:
 266   TypeRegistry mReference; ///< Reference to the type registry
 267   std::string mName;       ///< Name of the type
 268 };
 269
 270 /**
 271  * @brief Registers a signal connector function to a registered type.
 272  * @SINCE_1_0.0
 273  */
 274 class DALI_CORE_API SignalConnectorType
 275 {
 276 public:
 277   /**
 278    * @brief Constructor registers the type creation function.
 279    *
 280    * @SINCE_1_0.0
 281    * @param[in] typeRegistration The TypeRegistration object
 282    * @param[in] name The signal name
 283    * @param[in] func The signal connector function
 284    */
 285   SignalConnectorType( TypeRegistration& typeRegistration, const std::string& name, TypeInfo::SignalConnectorFunction func );
 286 };
 287
 288 /**
 289  * @brief Registers an action function.
 290  * @SINCE_1_0.0
 291  */
 292 class DALI_CORE_API TypeAction
 293 {
 294 public:
 295   /**
 296    * @brief Constructor registers the type creation function.
 297    *
 298    * @SINCE_1_0.0
 299    * @param[in] registered The TypeRegistration object
 300    * @param[in] name The action name
 301    * @param[in] f The action function
 302    */
 303   TypeAction( TypeRegistration &registered, const std::string &name, TypeInfo::ActionFunction f);
 304 };
 305
 306 /**
 307  * @brief Registers a property for the given type.
 308  * @SINCE_1_0.0
 309  */
 310 class DALI_CORE_API PropertyRegistration
 311 {
 312 public:
 313
 314   /**
 315    * @brief This constructor registers the property with the registered type.
 316    *
 317    * This constructor is for event-thread only properties where the
 318    * value of the property can be retrieved and set via specified
 319    * functions.
 320    *
 321    * Functions of the following type may be used for setFunc and getFunc respectively:
 322    * @code
 323    *   void SetProperty( BaseObject* object, Property::Index index, const Property::Value& value );
 324    *   Property::Value GetProperty( BaseObject* object, Property::Index index );
 325    * @endcode
 326    *
 327    * @SINCE_1_0.0
 328    * @param[in] registered The TypeRegistration object
 329    * @param[in] name The name of the property
 330    * @param[in] index The property index. Must be a value between PROPERTY_REGISTRATION_START_INDEX and PROPERTY_REGISTRATION_MAX_INDEX inclusive
 331    * @param[in] type The property value type
 332    * @param[in] setFunc The function to call when setting the property. If NULL, then the property becomes read-only
 333    * @param[in] getFunc The function to call to retrieve the current value of the property. MUST be provided
 334    * @pre "registered" must be registered with the TypeRegistry.
 335    * @note The "index" value must be between START_INDEX and MAX_INDEX inclusive.
 336    * @note If "setFunc" is NULL, then the property becomes a read-only property.
 337    * @note "getFunc" MUST be provided.
 338    *
 339    */
 340   PropertyRegistration( TypeRegistration& registered,
 341                         const std::string& name, Property::Index index, Property::Type type,
 342                         TypeInfo::SetPropertyFunction setFunc, TypeInfo::GetPropertyFunction getFunc );
 343 };
 344
 345 /**
 346  * @brief Registers an animatable property for the given type.
 347  * @SINCE_1_0.0
 348  */
 349 class DALI_CORE_API AnimatablePropertyRegistration
 350 {
 351 public:
 352
 353   /**
 354    * @brief This constructor registers the animatable property with the registered type.
 355    *
 356    * This constructor is for scene-graph only properties where the
 357    * value of the property can be retrieved and set via specified
 358    * functions.
 359    *
 360    * @SINCE_1_0.0
 361    * @param[in] registered The TypeRegistration object
 362    * @param[in] name The name of the property
 363    * @param[in] index The property index. Must be a value between ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX and ANIMATABLE_PROPERTY_REGISTRATION_MAX_INDEX inclusive
 364    * @param[in] type The property value type
 365    * @pre "registered" must be registered with the TypeRegistry.
 366    */
 367   AnimatablePropertyRegistration( TypeRegistration& registered, const std::string& name, Property::Index index, Property::Type type );
 368
 369   /**
 370    * @brief This constructor registers the animatable property with the registered default value.
 371    *
 372    * This constructor is for scene-graph only properties where the
 373    * value of the property can be retrieved and set via specified
 374    * functions.
 375    *
 376    * @SINCE_1_1.18
 377    * @param[in] registered The TypeRegistration object
 378    * @param[in] name The name of the property
 379    * @param[in] index The property index. Must be a value between ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX and ANIMATABLE_PROPERTY_REGISTRATION_MAX_INDEX inclusive
 380    * @param[in] value The property default value
 381    * @pre "registered" must be registered with the TypeRegistry.
 382    */
 383   AnimatablePropertyRegistration( TypeRegistration& registered, const std::string& name, Property::Index index, const Property::Value& value );
 384 };
 385
 386 /**
 387  * @brief Registers a component of animatable property for the given component index.
 388  * @SINCE_1_0.0
 389  */
 390 class DALI_CORE_API AnimatablePropertyComponentRegistration
 391 {
 392 public:
 393
 394   /**
 395    * @brief This constructor registers a component of an animatable property where
 396    * the base animatable property must be a property that supports property component
 397    * (i.e. Vector2, Vector3 or Vector4) and the base animatable property must have
 398    * been registered.
 399    *
 400    * This constructor is for a component of scene-graph only properties where the
 401    * value of the property can be retrieved and set via specified functions.
 402    *
 403    * @SINCE_1_0.0
 404    * @param[in] registered The TypeRegistration object
 405    * @param[in] name The name of the component
 406    * @param[in] index The property index. Must be a value between ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX and ANIMATABLE_PROPERTY_REGISTRATION_MAX_INDEX inclusive
 407    * @param[in] baseIndex The index of the base animatable property. Must be a value between ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX and ANIMATABLE_PROPERTY_REGISTRATION_MAX_INDEX inclusive
 408    * @param[in] componentIndex The index of the component (e.g. 0 for the x component of a Vector2 property and 1 for the y component of a Vector2 property)
 409    * @pre "registered" must be registered with the TypeRegistry.
 410    */
 411   AnimatablePropertyComponentRegistration( TypeRegistration& registered, const std::string& name, Property::Index index, Property::Index baseIndex, uint32_t componentIndex );
 412 };
 413
 414 /**
 415  * @brief Registers a child property for the given type.
 416  * @SINCE_1_1.35
 417  */
 418 class DALI_CORE_API ChildPropertyRegistration
 419 {
 420 public:
 421
 422   /**
 423    * @brief This constructor registers an event-thread only child property (i.e. a property
 424    * that the parent supports in its children) with the registered type.
 425    *
 426    * @SINCE_1_1.35
 427    * @param[in] registered The TypeRegistration object
 428    * @param[in] name The name of the property
 429    * @param[in] index The property index. Must be a value between CHILD_PROPERTY_REGISTRATION_START_INDEX and CHILD_PROPERTY_REGISTRATION_MAX_INDEX inclusive
 430    * @param[in] type The property value type
 431    * @pre "registered" must be registered with the TypeRegistry.
 432    */
 433   ChildPropertyRegistration( TypeRegistration& registered, const std::string& name, Property::Index index, Property::Type type );
 434
 435   /**
 436    * @brief This constructor registers an event-thread only child property (i.e. a property
 437    * that the parent supports in its children) with the registered type.
 438    *
 439    * @SINCE_1_3.20
 440    * @param[in] registered The name of the registered type
 441    * @param[in] name The name of the property
 442    * @param[in] index The property index. Must be a value between CHILD_PROPERTY_REGISTRATION_START_INDEX and CHILD_PROPERTY_REGISTRATION_MAX_INDEX inclusive
 443    * @param[in] type The property value type
 444    * @pre "registered" must be registered with the TypeRegistry.
 445    */
 446   ChildPropertyRegistration( const std::string& registered, const std::string& name, Property::Index index, Property::Type type );
 447 };
 448
 449
 450 /**
 451  * @}
 452  */
 453 } // namespace Dali
 454
 455 #endif // header