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

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