docs/content/programming-guide/properties.h

   1 /*! \page properties Properties
   2  *
   3 @section what-is-a-property What is a property?
   4
   5 A property is a value used by an object that can be modified or read externally to that object.
   6 This could be from within DALi or externally by an application.
   7
   8 <h2 class="pg">What is a property used for?</h2>
   9
  10 Properties can be set externally by an application, allowing that application to change the configuration or behaviour of an actor.
  11 This could include the physical geometry of the actor, or how it is drawn or moves.
  12
  13 Properties can also be read. This feature can be used in conjunction with constraints to allow changes to a property within one actor to cause changes to the property of another actor. For example, an actor following the movement of another separate actor (that it is not a child of).
  14
  15 Properties can be used to expose any useful information or behaviour of an actor.
  16 Other actor variables that are used to implement this bevahiour, or do not make useful sense from an application developers point of view should not be exposed.
  17
  18 <h2 class="pg">How to implement a property within DALi Core:</h2>
  19
  20 <b>There are two stages:</b>
  21
  22 - Define the properties as an enum in the public-api header file.
  23 - Define the property details using the pre-defined macros to build up a table of property information.
  24
  25 There are some pre-defined macros designed to help with and standardise the definition of the propery details table per class.
  26
  27 These macros generate an array of property details which allow efficient lookup of flags like "animatable" or "constraint input".
  28
  29 <b>Example: Layer</b>
  30
  31 Within the public-api header file; layer.h:
  32
  33 @code
  34   /**
  35    * @brief An enumeration of properties belonging to the Layer class.
  36    *
  37    * Properties additional to Actor.
  38    */
  39   struct Property
  40   {
  41     enum
  42     {
  43       CLIPPING_ENABLE = DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX, ///< name "clippingEnable",   type bool @SINCE_1_0.0
  44       CLIPPING_BOX,                                                 ///< name "clippingBox",      type Rect<int> @SINCE_1_0.0
  45       BEHAVIOR,                                                     ///< name "behavior",         type String @SINCE_1_0.0
  46     };
  47   };
  48 @endcode
  49 From @ref Dali::Layer::Property
  50
  51 <b>Notes:</b>
  52
  53 - The properties are enumerated within a named struct to give them a namespace.
  54 - The properties are then refered to as &lt;OBJECT&gt;::%Property::&lt;PROPERTY_NAME&gt;.
  55
  56 Within the internal implementation; <b>layer-impl.cpp</b>:
  57
  58 @code
  59 namespace // Unnamed namespace
  60 {
  61
  62 // Properties
  63
  64 //              Name                Type      writable animatable constraint-input  enum for index-checking
  65 DALI_PROPERTY_TABLE_BEGIN
  66 DALI_PROPERTY( "clippingEnable",    BOOLEAN,    true,    false,   true,             Dali::Layer::Property::CLIPPING_ENABLE )
  67 DALI_PROPERTY( "clippingBox",       RECTANGLE,  true,    false,   true,             Dali::Layer::Property::CLIPPING_BOX    )
  68 DALI_PROPERTY( "behavior",          STRING,     true,    false,   false,            Dali::Layer::Property::BEHAVIOR        )
  69 DALI_PROPERTY_TABLE_END( DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX )
  70 @endcode
  71
  72 <b>Notes:</b>
  73
  74 - The table lays within an unnamed namespace.
  75 - The table should be in the same order as the enum.
  76 - The table should be the only place where the text names of the properties are defined.
  77 - The information in the table should be used within the classes IsDefaultPropertyWritable / Animatable / ConstraintInput methods for quick lookup.
  78 - The last entry in the table is optionally used in debug builds for index checking.
  79 - The parameter to DALI_PROPERTY_TABLE_END should match the start index of the property enumeration.
  80
  81 <br>
  82 <h2 class="pg">How to implement a property within DALi Toolkit controls and application-side custom controls:</h2>
  83
  84 Macros are used to define properties for the following reasons:
  85
  86 - To standardise the way properties are defined.
  87 - To handle type-registering for properties, signals and actions in one place.
  88 - To facilitate the posibility of running the code with the type-registry disabled.
  89
  90 Two different macros are provided depending on whether the property is to be an event-side only property or an animatable property.
  91
  92 <b>There are three stages:</b>
  93
  94 - Define the property ranges as an enum in the public-api header file. There are two ranges, one for event-side only properties, and one for animatable properties. Each range should follow on from the range defined in the parent class.
  95 - Define the properties as an enum in the public-api header file
  96 - Define the property details using the pre-defined macros to perform the type-registering of the properties. This is done for signals and actions also.
  97
  98 <b>Example: ImageView</b>
  99
 100 Source file: <b>image-view.h</b>:
 101   Note that the “PropertyRange” contents “PROPERTY_START_INDEX” & "ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX" are also used by the macro for order checking, so should always have these names.
 102
 103 @code
 104   /**
 105    * @brief The start and end property ranges for this control.
 106    */
 107   enum PropertyRange
 108   {
 109     PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1,  ///< @SINCE_1_0.0
 110     PROPERTY_END_INDEX =   PROPERTY_START_INDEX + 1000,              ///< Reserve property indices @SINCE_1_0.0
 111
 112     ANIMATABLE_PROPERTY_START_INDEX = ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX,        ///< @SINCE_1_1.18
 113     ANIMATABLE_PROPERTY_END_INDEX =   ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX + 1000  ///< Reserve animatable property indices, @SINCE_1_1.18
 114   };
 115
 116   /**
 117    * @brief An enumeration of properties belonging to the Button class.
 118    */
 119   struct Property
 120   {
 121     enum
 122     {
 123       // Event side properties
 124
 125       /**
 126        * @DEPRECATED_1_1.16. Use IMAGE instead.
 127        * @brief name "resourceUrl", type string
 128        * @SINCE_1_0.0
 129        */
 130       RESOURCE_URL = PROPERTY_START_INDEX,
 131       /**
 132        * @brief name "image", type string if it is a url, map otherwise
 133        * @SINCE_1_0.0
 134        */
 135       IMAGE,
 136       /**
 137        * @brief name "preMultipliedAlpha", type Boolean
 138        * @SINCE_1_1.18
 139        * @pre image must be initialized.
 140        */
 141       PRE_MULTIPLIED_ALPHA,
 142
 143       // Animatable properties
 144
 145       /**
 146        * @brief name "pixelArea", type Vector4
 147        * @details Pixel area is a relative value with the whole image area as [0.0, 0.0, 1.0, 1.0].
 148        * @SINCE_1_0.18
 149        */
 150       PIXEL_AREA = ANIMATABLE_PROPERTY_START_INDEX,
 151     };
 152   };
 153 @endcode
 154
 155 Source file: <b>image-view-impl.cpp</b>, within an unnamed namespace:
 156
 157 @code
 158 #include <dali/public-api/object/type-registry-helper.h>
 159 @endcode
 160
 161 @clip{"image-view-impl.cpp",DALI_TYPE_REGISTRATION_BEGIN,DALI_TYPE_REGISTRATION_END}
 162
 163 <b>Notes:</b>
 164
 165 - The “Create” parameter to the begin macro is the function pointer to the creation function.
 166 - Properties should be in the same order as in the enum.
 167 - Signals and actions are registered likewise in that order.
 168 - Properties type-registered using these macros will have their order checked at compile time. If you get an indexing compile error, check the order matches the enum order.
 169     The error will look like this: " error: invalid application of 'sizeof' to incomplete type 'Dali::CompileTimeAssertBool<false>' "
 170 - If using the Pimpl design pattern when creating a custom control from within an application, the Handle (public) and Object (internal) classes should have the same name. They can be separated by different namespaces.
 171     This requirement is actually due to how the type-registry in DALi looks up properties.
 172
 173 <br>
 174 <hr>
 175 @section property-indices Property Indices
 176
 177 The properties are enumerated to give them a unique index. This index can be used to access them.
 178 The indecies must be unique per flattened derivation heirachy.
 179 EG:
 180 - CameraActor derives from Actor. No property indicies in either CameraActor or Actor should collide with each other.
 181 - ActiveConstraintBase derives from Object. It CAN have property indices that match Actor or CameraActor.
 182
 183 There are some predefined start indecies and ranges that should be used for common cases, these are defined below:
 184
 185
 186 DALi has a property system and provides several different kinds of properties. The following table
 187 shows the index range of the different properties in place.
 188
 189 | Kind                  | Description                                                                                       | Start Index                                                                                                | End Index                                                                                                                          |
 190 |:----------------------|:--------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------:|:----------------------------------------------------------------------------------------------------------------------------------:|
 191 | Default               | Properties defined within DALi Core, e.g. Dali::Actor default properties etc.                     | \link Dali::DEFAULT_OBJECT_PROPERTY_START_INDEX DEFAULT_OBJECT_PROPERTY_START_INDEX\endlink                | \link Dali::DEFAULT_PROPERTY_MAX_COUNT DEFAULT_PROPERTY_MAX_COUNT\endlink (9999999)                                                |
 192 | Registered            | Properties registered using Dali::PropertyRegistration                                            | \link Dali::PROPERTY_REGISTRATION_START_INDEX PROPERTY_REGISTRATION_START_INDEX\endlink (10000000)         | \link Dali::PROPERTY_REGISTRATION_MAX_INDEX PROPERTY_REGISTRATION_MAX_INDEX\endlink (19999999)                                     |
 193 | Control               | Property range reserved by Dali::Toolkit::Control                                                 | \link Dali::Toolkit::Control::CONTROL_PROPERTY_START_INDEX CONTROL_PROPERTY_START_INDEX\endlink (10000000) | \link Dali::Toolkit::Control::CONTROL_PROPERTY_END_INDEX CONTROL_PROPERTY_END_INDEX\endlink (10001000)                             |
 194 | Derived Control       | Property range for control deriving directly from Dali::Toolkit::Control                          | 10001001                                                                                                   | \link Dali::PROPERTY_REGISTRATION_MAX_INDEX PROPERTY_REGISTRATION_MAX_INDEX\endlink (19999999)                                     |
 195 | Registered Animatable | Animatable properties registered using Dali::AnimatablePropertyRegistration                       | \link Dali::ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX\endlink (20000000) | \link Dali::ANIMATABLE_PROPERTY_REGISTRATION_MAX_INDEX ANIMATABLE_PROPERTY_REGISTRATION_MAX_INDEX\endlink (29999999) |
 196 | Registered Child      | Child properties (which parent supports in its children) registered using Dali::ChildPropertyRegistration   | \link Dali::CHILD_PROPERTY_REGISTRATION_START_INDEX CHILD_PROPERTY_REGISTRATION_START_INDEX\endlink (45000000) | \link Dali::CHILD_PROPERTY_REGISTRATION_MAX_INDEX CHILD_PROPERTY_REGISTRATION_MAX_INDEX\endlink (49999999) |
 197 | Custom                | Custom properties added to instance using Dali::Handle::RegisterProperty                          | \link Dali::PROPERTY_CUSTOM_START_INDEX PROPERTY_CUSTOM_START_INDEX\endlink (50000000)                     | Onwards...                                                                                                                         |
 198
 199 <br>
 200 <hr>
 201 @section property-use-example-cpp Property use example C++
 202
 203 Common uses for properties are constraints and animations.
 204
 205 An application developer can use an existing property, or, if necessary, register their own.
 206
 207 Here is a code example.
 208
 209 This example shows how to register and look-up custom properties.
 210 An image is added to the screen which changes and a custom property is added to the image-view.
 211 This value is incremented every time the image is touched and the text-label is updated.
 212 When touched, the property is looked up by index (as this is much faster than a text lookup of the property name).
 213
 214 Property lookup via index should always be used unless the indicies cannot be known. If the property reader was completely decoupled from the creation, e.g. A custom control with a custom property being used by external application code, then it may be necessary. In this case the application writer should aim to perform the text lookup once at start-up, and cache the property index locally.
 215
 216 @clip{"properties.cpp", // C++ EXAMPLE, // C++ EXAMPLE END}
 217
 218 <br>
 219 <hr>
 220 @section property-use-example-json Property use in JSON
 221
 222 This is a basic example of a button defined in JSON by setting the default properties.
 223
 224 @code
 225 {
 226   "stage":
 227   [
 228     {
 229       "type": "ImageView",
 230       "parentOrigin": "CENTER",
 231       "anchorPoint": "CENTER",
 232       "position": [0, 0, 0],
 233       "image":
 234       {
 235         "visualType" : "IMAGE",
 236         "url" : "images/icon-0.png",
 237         "desiredWidth" : 100,
 238         "desiredHeight" : 100
 239       }
 240     }
 241   ]
 242 }
 243 @endcode
 244
 245 *
 246 */