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

   1 #ifndef __DALI_TYPE_REGISTRY_H__
   2 #define __DALI_TYPE_REGISTRY_H__
   3
   4 //
   5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
   6 //
   7 // Licensed under the Flora License, Version 1.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://floralicense.org/license/
  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  * @addtogroup CAPI_DALI_FRAMEWORK
  22  * @{
  23  */
  24
  25 // EXTERNAL INCLUDES
  26 #include <typeinfo>
  27
  28 // INTERNAL INCLUDES
  29 #include <dali/public-api/object/base-handle.h>
  30 #include <dali/public-api/object/type-info.h>
  31
  32 namespace Dali DALI_IMPORT_API
  33 {
  34
  35 namespace Internal DALI_INTERNAL
  36 {
  37 class TypeRegistry;
  38 }
  39
  40 /**
  41  * The TypeRegistry allows registration of type instance creation functions.
  42  * These can then be created later by name and down cast to the appropriate type.
  43  *
  44  * Usage: (Registering)
  45  *
  46  * In my-actor.cpp
  47  * @code
  48  * // Note: object construction in namespace scope is defined in a translation unit as being
  49  * //       in appearance order (C++ standard 3.6/2). So TypeRegistration is declared first in
  50  * //       the cpp file below. Signal, action and property declarations follow in any order.
  51  * namespace
  52  * {
  53  *   TypeRegistration myActorType(typeid(MyActor), typeid(Actor), CreateMyActor );
  54  *
  55  *   SignalConnectorType( myActorType, "highlighted", ConnectSignalForMyActor );
  56  *   TypeAction( myActorType, "open", DoMyActorAction );
  57  *   TypeAction( myActorType, "close", DoMyActorAction );
  58  *   PropertyRegistration( myActorType, "status", PropertyRegistration::START_INDEX, Property::BOOLEAN, SetPropertyFunction, GetPropertyFunction );
  59  * }
  60  * @endcode
  61  *
  62  * Usage: (Creation)
  63  *
  64  * @code
  65  *   TypeRegistry::TypeInfo type = TypeRegistry::Get().GetTypeInfo("MyActor");
  66  *   MyActor a = MyActor::DownCast(type.CreateInstance());
  67  *   if(a)
  68  *   {
  69  *     ...
  70  *   }
  71  * @endcode
  72  *
  73  * CustomActor
  74  *
  75  *  Actors that inherit from the CustomActor framework must ensure the implementation
  76  *  class has an identical name to the Actor class. This is to ensure the class can be
  77  *  found at runtime for signals and actions. Otherwise these will silently fail.
  78  *
  79  *  As namespaces are discarded the convention is to use a namespace ie
  80  *
  81  *    'class MyActor {}; namespace Internal { class MyActor {}; }'
  82  *
  83  *  Warning: this arrangement will silently fail
  84  *
  85  *    'class MyActor {}; class MyActorImpl {};'
  86  *
  87  * Naming Conventions
  88  *
  89  *   Signal and action names follow properties and are by convention lower case hyphen
  90  *   separated ie 'next-page'. This maintains consistency with the scripted interface.
  91  *
  92  */
  93 class TypeRegistry : public BaseHandle
  94 {
  95 public:
  96   typedef std::vector<std::string> NameContainer;
  97
  98   /**
  99    * Get Type Registry handle
 100    * @return TypeRegistry handle
 101    */
 102   static TypeRegistry Get();
 103
 104   /**
 105    * Allows the creation of an empty typeRegistry handle.
 106    */
 107   TypeRegistry();
 108
 109   /**
 110    * destructor.
 111    */
 112   ~TypeRegistry();
 113
 114   /**
 115    * @copydoc Dali::BaseHandle::operator=
 116    */
 117   using BaseHandle::operator=;
 118
 119   /**
 120    * Get TypeInfo for a registered type
 121    * @param [in] uniqueTypeName A unique type name
 122    * @return TypeInfo if the type exists otherwise an empty handle
 123    */
 124   TypeInfo GetTypeInfo( const std::string &uniqueTypeName );
 125
 126   /**
 127    * Get TypeInfo for a registered type
 128    * @param [in] registerType The registered type info
 129    * @return TypeInfo if the type exists otherwise an empty handle
 130    */
 131   TypeInfo GetTypeInfo( const std::type_info& registerType );
 132
 133   /**
 134    * Get type names
 135    * @return list of known types by name
 136    */
 137   NameContainer GetTypeNames() const;
 138
 139 public: // Not intended for application developers
 140
 141   /**
 142    * This constructor is used by Dali Get() method
 143    * @param [in] typeRegistry A pointer to a Dali resource
 144    */
 145   explicit DALI_INTERNAL TypeRegistry(Internal::TypeRegistry*typeRegistry);
 146 };
 147
 148 /**
 149  * Register a type from type info
 150  */
 151 class TypeRegistration
 152 {
 153 public:
 154   /**
 155    * Constructor registers the type creation function
 156    * @param [in] registerType the type info for the type to be registered
 157    * @param [in] baseType the base type info of registerType
 158    * @param [in] f registerType instance creation function
 159    */
 160   TypeRegistration( const std::type_info& registerType, const std::type_info& baseType,
 161                     TypeInfo::CreateFunction f );
 162
 163   /**
 164    * Constructor registers the type creation function
 165    * @param [in] registerType the type info for the type to be registered
 166    * @param [in] baseType the base type info of registerType
 167    * @param [in] f registerType instance creation function
 168    * @param [in] callCreateOnInit If true the creation function is called as part of Dali initialisation
 169    */
 170   TypeRegistration( const std::type_info& registerType, const std::type_info& baseType,
 171                     TypeInfo::CreateFunction f, bool callCreateOnInit );
 172
 173   /**
 174    * Constructor registers the type creation function for a named class or type.
 175    * This allows types to be created dynamically from script. The name must be
 176    * unique for successful registration.
 177    * @param [in] name the name of the type to be registered
 178    * @param [in] baseType the base type info of registerType
 179    * @param [in] f registerType instance creation function
 180    */
 181   TypeRegistration( const std::string& name, const std::type_info& baseType,
 182                     TypeInfo::CreateFunction f );
 183
 184   /**
 185    * The name the type is registered under (derived from type_info)
 186    * @return the registered name or empty if unregistered
 187    */
 188   const std::string RegisteredName() const;
 189
 190 private:
 191   TypeRegistry mReference;
 192   std::string mName;
 193 };
 194
 195 /**
 196  * Register a signal connector function to a registered type
 197  */
 198 class SignalConnectorType
 199 {
 200 public:
 201   /**
 202    * Constructor registers the type creation function
 203    * @param [in] typeRegistration The TypeRegistration object
 204    * @param [in] name The signal name
 205    * @param [in] func The signal connector function
 206    */
 207   SignalConnectorType( TypeRegistration& typeRegistration, const std::string& name, TypeInfo::SignalConnectorFunctionV2 func );
 208 };
 209
 210 /**
 211  * Register an action function
 212  */
 213 class TypeAction
 214 {
 215 public:
 216   /**
 217    * Constructor registers the type creation function
 218    * @param [in] registered The TypeRegistration object
 219    * @param [in] name The action name
 220    * @param [in] f The action function
 221    */
 222   TypeAction( TypeRegistration &registered, const std::string &name, TypeInfo::ActionFunction f);
 223 };
 224
 225 /**
 226  * Register a property for the given type.
 227  */
 228 class PropertyRegistration
 229 {
 230 public:
 231
 232   // Enumerations are being used here rather than static constants so that switch statements can be used to compare property indices
 233   enum
 234   {
 235     START_INDEX = 10000000,   ///< The index for this type should start from this number
 236     MAX_INDEX   = 19999999    ///< The maximum index supported for this type
 237   };
 238
 239   /**
 240    * This constructor registers the property with the registered type. This constructor is for event-thread
 241    * only properties where the value of the property can be retrieved and set via specified functions.
 242    *
 243    * Functions of the following type may be used for setFunc and getFunc respectively:
 244    * @code
 245    *   void SetProperty( BaseObject* object, Property::Index index, const Property::Value& value );
 246    *   Property::Value GetProperty( BaseObject* object, Property::Index index );
 247    * @endcode
 248    *
 249    * @param [in] registered The TypeRegistration object
 250    * @param [in] name The name of the property
 251    * @param [in] index The property index. Must be a value between START_INDEX and MAX_INDEX inclusive.
 252    * @param [in] type The property value type.
 253    * @param [in] setFunc The function to call when setting the property. If NULL, then the property becomes read-only.
 254    * @param [in] getFunc The function to call to retrieve the current value of the property. MUST be provided.
 255    *
 256    * @note The "index" value must be between START_INDEX and MAX_INDEX inclusive.
 257    * @note If "setFunc" is NULL, then the property becomes a read-only property.
 258    * @note "getFunc" MUST be provided
 259    *
 260    * @pre "registered" must be registered with the TypeRegistry.
 261    */
 262   PropertyRegistration( TypeRegistration& registered,
 263                         const std::string& name, Property::Index index, Property::Type type,
 264                         TypeInfo::SetPropertyFunction setFunc, TypeInfo::GetPropertyFunction getFunc );
 265 };
 266
 267 } // namespace Dali
 268
 269 /**
 270  * @}
 271  */
 272 #endif // header