+@section what-is-a-property What is a property?
+
+A property is a value used by an object that can be modified or read externally to that object.
+This could be from within DALi or externally by an application.
+
+<h2 class="pg">What is a property used for?</h2>
+
+Properties can be set externally by an application, allowing that application to change the configuration or behaviour of an actor.
+This could include the physical geometry of the actor, or how it is drawn or moves.
+
+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).
+
+Properties can be used to expose any useful information or behaviour of an actor.
+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.
+
+<h2 class="pg">How to implement a property within Dali-core:</h2>
+
+<b>There are two stages:</b>
+
+- Define the properties as an enum in the public-api header file.
+- Define the property details using the pre-defined macros to build up a table of property information.
+
+There are some pre-defined macros designed to help with and standardise the definition of the propery details table per class.
+
+These macros generate an array of property details which allow efficient lookup of flags like "animatable" or "constraint input".
+
+<b>Example: ImageActor</b>
+
+Within the public-api header file; image-actor.h:
+
+@code
+/**
+ * @brief An enumeration of properties belonging to the ImageActor class.
+ * Properties additional to Actor.
+ */
+struct Property
+{
+ enum
+ {
+ PIXEL_AREA = DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX, ///< name "pixelArea", type Rect<int>
+ STYLE, ///< name "style", type std::string
+ BORDER, ///< name "border", type Vector4
+ IMAGE, ///< name "image", type Map {"filename":"", "loadPolicy":...}
+ };
+};
+@endcode
+From @ref Dali::ImageActor::Property
+
+<b>Notes:</b>
+
+- The properties are enumerated within a named struct to give them a namespace.
+- The properties are then refered to as <OBJECT>::%Property::<PROPERTY_NAME>.
+
+Within the internal implementation; <b>image-actor-impl.cpp</b>:
+
+@code
+namespace // Unnamed namespace
+{
+
+// Properties
+
+// Name Type writable animatable constraint-input enum for index-checking
+DALI_PROPERTY_TABLE_BEGIN
+DALI_PROPERTY( "pixelArea", RECTANGLE, true, false, true, Dali::ImageActor::Property::PIXEL_AREA )
+DALI_PROPERTY( "style", STRING, true, false, true, Dali::ImageActor::Property::STYLE )
+DALI_PROPERTY( "border", VECTOR4, true, false, true, Dali::ImageActor::Property::BORDER )
+DALI_PROPERTY( "image", MAP, true, false, false, Dali::ImageActor::Property::IMAGE )
+DALI_PROPERTY_TABLE_END( DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX )
+@endcode
+
+<b>Notes:</b>
+
+- The table lays within an unnamed namespace.
+- The table should be in the same order as the enum.
+- The table should be the only place where the text names of the properties are defined.
+- The information in the table should be used within the classes IsDefaultPropertyWritable / Animatable / ConstraintInput methods for quick lookup.
+- The last entry in the table is optionally used in debug builds for index checking.
+- The parameter to DALI_PROPERTY_TABLE_END should match the start index of the property enumeration.
+
+<br>
+<h2 class="pg">How to implement a property within Dali-toolkit:</h2>
+
+Note that toolkit properties have extra limitations in that they cannot be animated or used as a constraint input. For this reason there is no requirement for a table of property details.
+Macros are still used to define properties, but for the following reasons:
+
+To standardise the way properties are defined.
+To handle type-registering for properties, signals and actions in one place.
+To facilitate the posibility of running the code with the type-registry disabled.
+
+<b>There are two stages:</b>
+
+- Define the properties as an enum in the public-api header file, along with a definition of the property ranges.
+- 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.
+
+<b>Example: Button</b>
+
+Source file: <b>button.h</b>:
+Note that the “PropertyRange” contents “PROPERTY_START_INDEX” is also used by the macro for order checking.
+
+@code
+ /**
+ * @brief The start and end property ranges for this control.
+ */
+ enum PropertyRange
+ {
+ PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1,
+ PROPERTY_END_INDEX = PROPERTY_START_INDEX + 1000 ///< Reserve property indices
+ };
+
+ /**
+ * @brief An enumeration of properties belonging to the Button class.
+ */
+ struct Property
+ {
+ enum
+ {
+ DISABLED = PROPERTY_START_INDEX, ///< name "disabled", @see SetDisabled(), type bool
+ AUTO_REPEATING, ///< name "autoRepeating", @see SetAutoRepeating(), type bool
+ INITIAL_AUTO_REPEATING_DELAY, ///< name "initialAutoRepeatingDelay", @see SetInitialAutoRepeatingDelay(), type float
+ NEXT_AUTO_REPEATING_DELAY, ///< name "nextAutoRepeatingDelay", @see SetNextAutoRepeatingDelay(), type float
+ TOGGLABLE, ///< name "togglable", @see SetTogglableButton(), type bool
+ SELECTED, ///< name "selected", @see SetSelected(), type bool
+ NORMAL_STATE_ACTOR, ///< name "normalStateActor", @see SetButtonImage(), type Map
+ SELECTED_STATE_ACTOR, ///< name "selectedStateActor", @see SetSelectedImage(), type Map
+ DISABLED_STATE_ACTOR, ///< name "disabledStateActor", @see SetDisabledImage(), type Map
+ LABEL_ACTOR, ///< name "labelActor", @see SetLabel(), type Map
+ };
+ };
+@endcode
+
+Source file: <b>button-impl.cpp</b>, within an unnamed namespace:
+
+@clip{"button-impl.cpp",DALI_TYPE_REGISTRATION_BEGIN,DALI_TYPE_REGISTRATION_END}
+
+<b>Notes:</b>
+
+- The “Create” parameter to the begin macro is the function pointer to the creation function.
+- Properties should be in the same order as in the enum.
+- Signals and actions are registered likewise in that order.
+- 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.
+
+
+<br>
+<hr>