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

   1 #ifndef __DALI_TYPE_REGISTRY_H__
   2 #define __DALI_TYPE_REGISTRY_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
  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  */
  95 class DALI_IMPORT_API TypeRegistry : public BaseHandle
  96 {
  97 public:
  98   /**
  99    * @brief Get Type Registry handle.
 100    *
 101    * @return TypeRegistry handle
 102    */
 103   static TypeRegistry Get();
 104
 105   /**
 106    * @brief Allows the creation of an empty typeRegistry handle.
 107    */
 108   TypeRegistry();
 109
 110   /**
 111    * @brief destructor.
 112    */
 113   ~TypeRegistry();
 114
 115   /**
 116    * @brief This copy constructor is required for (smart) pointer semantics.
 117    *
 118    * @param [in] handle A reference to the copied handle
 119    */
 120   TypeRegistry(const TypeRegistry& handle);
 121
 122   /**
 123    * @brief This assignment operator is required for (smart) pointer semantics.
 124    *
 125    * @param [in] rhs  A reference to the copied handle
 126    * @return A reference to this
 127    */
 128   TypeRegistry& operator=(const TypeRegistry& rhs);
 129
 130   /**
 131    * @brief Get TypeInfo for a registered type.
 132    *
 133    * @param [in] uniqueTypeName A unique type name
 134    * @return TypeInfo if the type exists otherwise an empty handle
 135    */
 136   TypeInfo GetTypeInfo( const std::string &uniqueTypeName );
 137
 138   /**
 139    * @brief Get TypeInfo for a registered type.
 140    *
 141    * @param [in] registerType The registered type info
 142    * @return TypeInfo if the type exists otherwise an empty handle
 143    */
 144   TypeInfo GetTypeInfo( const std::type_info& registerType );
 145
 146   /**
 147    * @brief Get type name count.
 148    *
 149    * @return The count
 150    */
 151   size_t GetTypeNameCount() const;
 152
 153   /**
 154    * @brief Get type names by index.
 155    *
 156    * @return The type name or an empty string when index is not valid
 157    */
 158   std::string GetTypeName(size_t index) const;
 159
 160 public: // Not intended for application developers
 161
 162   /**
 163    * @brief This constructor is used by Dali Get() method.
 164    *
 165    * @param [in] typeRegistry A pointer to a Dali resource
 166    */
 167   explicit DALI_INTERNAL TypeRegistry(Internal::TypeRegistry*typeRegistry);
 168 };
 169
 170 /**
 171  * @brief Register a type from type info.
 172  */
 173 class DALI_IMPORT_API TypeRegistration
 174 {
 175 public:
 176   /**
 177    * @brief Constructor registers the type creation function.
 178    *
 179    * @param [in] registerType the type info for the type to be registered
 180    * @param [in] baseType the base type info of registerType
 181    * @param [in] f registerType instance creation function
 182    */
 183   TypeRegistration( const std::type_info& registerType, const std::type_info& baseType,
 184                     TypeInfo::CreateFunction f );
 185
 186   /**
 187    * @brief Constructor registers the type creation function.
 188    *
 189    * @param [in] registerType the type info for the type to be registered
 190    * @param [in] baseType the base type info of registerType
 191    * @param [in] f registerType instance creation function
 192    * @param [in] callCreateOnInit If true the creation function is called as part of Dali initialisation
 193    */
 194   TypeRegistration( const std::type_info& registerType, const std::type_info& baseType,
 195                     TypeInfo::CreateFunction f, bool callCreateOnInit );
 196
 197   /**
 198    * @brief Constructor registers the type creation function for a named class or type.
 199    *
 200    * This allows types to be created dynamically from script. The name must be
 201    * unique for successful registration.
 202    * @param [in] name the name of the type to be registered
 203    * @param [in] baseType the base type info of registerType
 204    * @param [in] f registerType instance creation function
 205    */
 206   TypeRegistration( const std::string& name, const std::type_info& baseType,
 207                     TypeInfo::CreateFunction f );
 208
 209   /**
 210    * @brief The name the type is registered under (derived from type_info).
 211    *
 212    * @return the registered name or empty if unregistered
 213    */
 214   const std::string RegisteredName() const;
 215
 216 private:
 217   TypeRegistry mReference; ///< Reference to the type registry
 218   std::string mName;       ///< Name of the type
 219 };
 220
 221 /**
 222  * @brief Register a signal connector function to a registered type.
 223  */
 224 class DALI_IMPORT_API SignalConnectorType
 225 {
 226 public:
 227   /**
 228    * @brief Constructor registers the type creation function.
 229    *
 230    * @param [in] typeRegistration The TypeRegistration object
 231    * @param [in] name The signal name
 232    * @param [in] func The signal connector function
 233    */
 234   SignalConnectorType( TypeRegistration& typeRegistration, const std::string& name, TypeInfo::SignalConnectorFunction func );
 235 };
 236
 237 /**
 238  * @brief Register an action function.
 239  */
 240 class DALI_IMPORT_API TypeAction
 241 {
 242 public:
 243   /**
 244    * @brief Constructor registers the type creation function.
 245    *
 246    * @param [in] registered The TypeRegistration object
 247    * @param [in] name The action name
 248    * @param [in] f The action function
 249    */
 250   TypeAction( TypeRegistration &registered, const std::string &name, TypeInfo::ActionFunction f);
 251 };
 252
 253 /**
 254  * @brief Register a property for the given type.
 255  */
 256 class DALI_IMPORT_API PropertyRegistration
 257 {
 258 public:
 259
 260   /**
 261    * @brief This constructor registers the property with the registered type.
 262    *
 263    * This constructor is for event-thread only properties where the
 264    * value of the property can be retrieved and set via specified
 265    * functions.
 266    *
 267    * Functions of the following type may be used for setFunc and getFunc respectively:
 268    * @code
 269    *   void SetProperty( BaseObject* object, Property::Index index, const Property::Value& value );
 270    *   Property::Value GetProperty( BaseObject* object, Property::Index index );
 271    * @endcode
 272    *
 273    * @param [in] registered The TypeRegistration object
 274    * @param [in] name The name of the property
 275    * @param [in] index The property index. Must be a value between PROPERTY_REGISTRATION_START_INDEX and PROPERTY_REGISTRATION_MAX_INDEX inclusive.
 276    * @param [in] type The property value type.
 277    * @param [in] setFunc The function to call when setting the property. If NULL, then the property becomes read-only.
 278    * @param [in] getFunc The function to call to retrieve the current value of the property. MUST be provided.
 279    *
 280    * @note The "index" value must be between START_INDEX and MAX_INDEX inclusive.
 281    * @note If "setFunc" is NULL, then the property becomes a read-only property.
 282    * @note "getFunc" MUST be provided
 283    *
 284    * @pre "registered" must be registered with the TypeRegistry.
 285    */
 286   PropertyRegistration( TypeRegistration& registered,
 287                         const std::string& name, Property::Index index, Property::Type type,
 288                         TypeInfo::SetPropertyFunction setFunc, TypeInfo::GetPropertyFunction getFunc );
 289 };
 290
 291 /**
 292  * @brief Register an animatable property for the given type.
 293  */
 294 class DALI_IMPORT_API AnimatablePropertyRegistration
 295 {
 296 public:
 297
 298   /**
 299    * @brief This constructor registers the animatable property with the registered type.
 300    *
 301    * This constructor is for scene-graph only properties where the
 302    * value of the property can be retrieved and set via specified
 303    * functions.
 304    *
 305    * @param [in] registered The TypeRegistration object
 306    * @param [in] name The name of the property
 307    * @param [in] index The property index. Must be a value between ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX and ANIMATABLE_PROPERTY_REGISTRATION_MAX_INDEX inclusive.
 308    * @param [in] type The property value type.
 309    *
 310    * @pre "registered" must be registered with the TypeRegistry.
 311    */
 312   AnimatablePropertyRegistration( TypeRegistration& registered, const std::string& name, Property::Index index, Property::Type type );
 313 };
 314
 315 /**
 316  * @brief Register a component of animatable property for the given component index.
 317  */
 318 class DALI_IMPORT_API AnimatablePropertyComponentRegistration
 319 {
 320 public:
 321
 322   /**
 323    * @brief This constructor registers a component of an animatable property where
 324    * the base animatable property must be a property that supports property component
 325    * (i.e. Vector2, Vector3 or Vector4) and the base animatable property must have
 326    * been registered.
 327    *
 328    * This constructor is for a component of scene-graph only properties where the
 329    * value of the property can be retrieved and set via specified functions.
 330    *
 331    * @param [in] registered The TypeRegistration object
 332    * @param [in] name The name of the component
 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] 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.
 335    * @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).
 336    *
 337    * @pre "registered" must be registered with the TypeRegistry.
 338    */
 339   AnimatablePropertyComponentRegistration( TypeRegistration& registered, const std::string& name, Property::Index index, Property::Index baseIndex, unsigned int componentIndex );
 340 };
 341
 342 /**
 343  * @}
 344  */
 345 } // namespace Dali
 346
 347 #endif // header