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