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