projects / platform / core / uifw / dali-toolkit.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
(Programming Guide) Initial chapter on creating a custom control
[platform/core/uifw/dali-toolkit.git] / docs / content / programming-guide / properties.h
diff --git a/docs/content/programming-guide/properties.h b/docs/content/programming-guide/properties.h
index b9c87e9..b445a2e 100644 (file)
--- a/docs/content/programming-guide/properties.h
+++ b/docs/content/programming-guide/properties.h
@@ -26,34 +26,34 @@ There are some pre-defined macros designed to help with and standardise the defi
 
 These macros generate an array of property details which allow efficient lookup of flags like "animatable" or "constraint input".
 
 
 These macros generate an array of property details which allow efficient lookup of flags like "animatable" or "constraint input".
 
-<b>Example: ImageActor</b>
+<b>Example: Layer</b>
 
 
-Within the public-api header file; image-actor.h:
+Within the public-api header file; layer.h:
 
 @code
 
 @code
-/**
- * @brief An enumeration of properties belonging to the ImageActor class.
- * Properties additional to Actor.
- */
-struct Property
-{
-  enum
+  /**
+   * @brief An enumeration of properties belonging to the Layer class.
+   *
+   * Properties additional to Actor.
+   */
+  struct Property
   {
   {
-    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":...}
+    enum
+    {
+      CLIPPING_ENABLE = DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX, ///< name "clippingEnable",   type bool @SINCE_1_0.0
+      CLIPPING_BOX,                                                 ///< name "clippingBox",      type Rect<int> @SINCE_1_0.0
+      BEHAVIOR,                                                     ///< name "behavior",         type String @SINCE_1_0.0
+    };
   };
   };
-};
 @endcode
 @endcode
-From @ref Dali::ImageActor::Property
+From @ref Dali::Layer::Property
 
 <b>Notes:</b>
 
 - The properties are enumerated within a named struct to give them a namespace.
 - The properties are then refered to as &lt;OBJECT&gt;::%Property::&lt;PROPERTY_NAME&gt;.
 
 
 <b>Notes:</b>
 
 - The properties are enumerated within a named struct to give them a namespace.
 - The properties are then refered to as &lt;OBJECT&gt;::%Property::&lt;PROPERTY_NAME&gt;.
 
-Within the internal implementation; <b>image-actor-impl.cpp</b>:
+Within the internal implementation; <b>layer-impl.cpp</b>:
 
 @code
 namespace // Unnamed namespace
 
 @code
 namespace // Unnamed namespace
@@ -61,12 +61,11 @@ namespace // Unnamed namespace
 
 // Properties
 
 
 // Properties
 
-//              Name           Type   writable animatable constraint-input  enum for index-checking
+//              Name                Type      writable animatable constraint-input  enum for index-checking
 DALI_PROPERTY_TABLE_BEGIN
 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( "clippingEnable",    BOOLEAN,    true,    false,   true,             Dali::Layer::Property::CLIPPING_ENABLE )
+DALI_PROPERTY( "clippingBox",       RECTANGLE,  true,    false,   true,             Dali::Layer::Property::CLIPPING_BOX    )
+DALI_PROPERTY( "behavior",          STRING,     true,    false,   false,            Dali::Layer::Property::BEHAVIOR        )
 DALI_PROPERTY_TABLE_END( DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX )
 @endcode
 
 DALI_PROPERTY_TABLE_END( DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX )
 @endcode
 
@@ -82,22 +81,23 @@ DALI_PROPERTY_TABLE_END( DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX )
 <br>
 <h2 class="pg">How to implement a property within Dali-toolkit:</h2>
 
 <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:
+Macros are used to define properties 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.
 
 
-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.
+Two different macros are provided depending on whether the property is to be an event-side only property or an animatable property.
 
 <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>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>
+<b>Example: ImageView</b>
 
 
-Source file: <b>button.h</b>:
-Note that the “PropertyRange” contents “PROPERTY_START_INDEX” is also used by the macro for order checking.
+Source file: <b>image-view.h</b>:
+Note that the “PropertyRange” contents “PROPERTY_START_INDEX” & "ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX" are also used by the macro for order checking.
 
 @code
   /**
 
 @code
   /**
@@ -105,8 +105,11 @@ Note that the “PropertyRange” contents “PROPERTY_START_INDEX” is also us
    */
   enum PropertyRange
   {
    */
   enum PropertyRange
   {
-    PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1,
-    PROPERTY_END_INDEX =   PROPERTY_START_INDEX + 1000              ///< Reserve property indices
+    PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1,  ///< @SINCE_1_0.0
+    PROPERTY_END_INDEX =   PROPERTY_START_INDEX + 1000,              ///< Reserve property indices @SINCE_1_0.0
+
+    ANIMATABLE_PROPERTY_START_INDEX = ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX,        ///< @SINCE_1_1.18
+    ANIMATABLE_PROPERTY_END_INDEX =   ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX + 1000  ///< Reserve animatable property indices, @SINCE_1_1.18
   };
 
   /**
   };
 
   /**
@@ -116,23 +119,41 @@ Note that the “PropertyRange” contents “PROPERTY_START_INDEX” is also us
   {
     enum
     {
   {
     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
+      // Event side properties
+
+      /**
+       * @DEPRECATED_1_1.16. Use IMAGE instead.
+       * @brief name "resourceUrl", type string
+       * @SINCE_1_0.0
+       */
+      RESOURCE_URL = PROPERTY_START_INDEX,
+      /**
+       * @brief name "image", type string if it is a url, map otherwise
+       * @SINCE_1_0.0
+       */
+      IMAGE,
+      /**
+       * @brief name "preMultipliedAlpha", type Boolean
+       * @SINCE_1_1.18
+       * @pre image must be initialized.
+       */
+      PRE_MULTIPLIED_ALPHA,
+
+      // Animatable properties
+
+      /**
+       * @brief name "pixelArea", type Vector4
+       * @details Pixel area is a relative value with the whole image area as [0.0, 0.0, 1.0, 1.0].
+       * @SINCE_1_0.18
+       */
+      PIXEL_AREA = ANIMATABLE_PROPERTY_START_INDEX,
     };
   };
 @endcode
 
     };
   };
 @endcode
 
-Source file: <b>button-impl.cpp</b>, within an unnamed namespace:
+Source file: <b>image-view-impl.cpp</b>, within an unnamed namespace:
 
 
-@clip{"button-impl.cpp",DALI_TYPE_REGISTRATION_BEGIN,DALI_TYPE_REGISTRATION_END}
+@clip{"image-view-impl.cpp",DALI_TYPE_REGISTRATION_BEGIN,DALI_TYPE_REGISTRATION_END}
 
 <b>Notes:</b>
 
 
 <b>Notes:</b>
 
@@ -141,7 +162,6 @@ Source file: <b>button-impl.cpp</b>, within an unnamed namespace:
 - 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.
 
 - 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>
 @section property-indices Property Indices
 <br>
 <hr>
 @section property-indices Property Indices
@@ -158,16 +178,14 @@ There are some predefined start indecies and ranges that should be used for comm
 DALi has a property system and provides several different kinds of properties. The following table
 shows the index range of the different properties in place.
 
 DALi has a property system and provides several different kinds of properties. The following table
 shows the index range of the different properties in place.
 
-<table>
-  <tr> <td><b>Kind</b></td>     <td><b>Description</b></td>                                                                                <td style="text-align:center;"><b>Start Index</b></td><td><b>End Index</b></td>         </tr>
-  <tr> <td>Default</td>         <td>Properties defined within DALi Core, e.g. Dali::Actor, Dali::ShaderEffect default properties etc.</td> <td style="text-align:center;">\link Dali::DEFAULT_OBJECT_PROPERTY_START_INDEX DEFAULT_OBJECT_PROPERTY_START_INDEX\endlink (0)</td><td>9999999</td>         </tr>
-  <tr> <td>Registered</td>      <td>Properties registered using Dali::PropertyRegistration</td>                                            <td style="text-align:center;">\link Dali::PROPERTY_REGISTRATION_START_INDEX PROPERTY_REGISTRATION_START_INDEX\endlink (10000000)</td><td>\link Dali::PROPERTY_REGISTRATION_MAX_INDEX PROPERTY_REGISTRATION_MAX_INDEX\endlink (19999999)</td> </tr>
-  <tr> <td>Control</td>         <td>Property range reserved by Dali::Toolkit::Control</td>                                                 <td style="text-align:center;">\link Dali::Toolkit::Control::CONTROL_PROPERTY_START_INDEX CONTROL_PROPERTY_START_INDEX\endlink (10000000)</td><td>
-  \link Dali::Toolkit::Control::CONTROL_PROPERTY_END_INDEX CONTROL_PROPERTY_END_INDEX\endlink (10001000)</td></tr>
-  <tr> <td>Derived Control</td> <td>Property range for control deriving directly from Dali::Toolkit::Control</td>                          <td style="text-align:center;">10001001</td><td>\link Dali::PROPERTY_REGISTRATION_MAX_INDEX PROPERTY_REGISTRATION_MAX_INDEX\endlink (19999999)</td> </tr>
-  <tr> <td>Custom</td>          <td>Custom properties added to instance using Dali::Handle::RegisterProperty</td>                          <td style="text-align:center;">\link Dali::PROPERTY_CUSTOM_START_INDEX PROPERTY_CUSTOM_START_INDEX\endlink (50000000)</td><td>Onwards...</td>     </tr>
-</table>
-
+| Kind                  | Description                                                                                       | Start Index                                                                                                | End Index                                                                                                                          |
+|:----------------------|:--------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------:|:----------------------------------------------------------------------------------------------------------------------------------:|
+| Default               | Properties defined within DALi Core, e.g. Dali::Actor, Dali::ShaderEffect 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)                                                |
+| 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)                                     |
+| Registered Animatable | Animatable properties registered using Dali::PropertyRegistration                                 | \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) |
+| 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)                             |
+| 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)                                     |
+| Custom                | Custom properties added to instance using Dali::Handle::RegisterProperty                          | \link Dali::PROPERTY_CUSTOM_START_INDEX PROPERTY_CUSTOM_START_INDEX\endlink (50000000)                     | Onwards...                                                                                                                         |
 
 <br>
 <hr>
 
 <br>
 <hr>
@@ -180,12 +198,13 @@ An application developer can use an existing property, or, if necessary, registe
 Here is a code example.
 
 This example shows how to register and look-up custom properties.
 Here is a code example.
 
 This example shows how to register and look-up custom properties.
-A grid of buttons is created, each with a new "tag" property which is set to a unique value. The index to this property is cached for later use.
-When pressed, the property is looked up by index (as this is much faster than a text lookup of the property name).
+An image is added to the screen which changes and a custom property is added to the image-view.
+This value is incremented every time the image is touched and the text-label is updated.
+When touched, the property is looked up by index (as this is much faster than a text lookup of the property name).
 
 
-Property lookup via index should always be used unless the indecies cannot be known. If the property reader was completely decoupled from the creation, EG. 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.
+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.
 
 
-@clip{"property-example.cpp", void Create, return true;}
+@clip{"properties.cpp", // C++ EXAMPLE, // C++ EXAMPLE END}
 
 Once run, a grid of buttons will appear. When a button is pressed, the unique number stored in the property (in this case the index) is displayed at the bottom of the screen.
 
 
 Once run, a grid of buttons will appear. When a button is pressed, the unique number stored in the property (in this case the index) is displayed at the bottom of the screen.
 
@@ -196,18 +215,22 @@ Once run, a grid of buttons will appear. When a button is pressed, the unique nu
 Note that constraints cannot be used within JavaScript, so below is a simple example that sets one of the default properties; scale:
 
 @code
 Note that constraints cannot be used within JavaScript, so below is a simple example that sets one of the default properties; scale:
 
 @code
-var image = new dali.ResourceImage( {url:"background.png"} );
-var imageActor = new dali.ImageActor( image );
+var imageView = new dali.Control( "ImageView" );
 
 // by default an actor is anchored to the top-left of it's parent actor
 // change it to the middle
 
 // by default an actor is anchored to the top-left of it's parent actor
 // change it to the middle
-imageActor.parentOrigin = dali.CENTER;
-
-// scale it up by 2 times  in x,y
-imageActor.scale = [ 2, 2, 1  ];
+imageView.parentOrigin = dali.CENTER;
+
+// Set an image view property
+imageView.image = {
+  "rendererType" : "image",
+  "imageUrl" : "images/icon-0.png",
+  "width" : 100,
+  "height" : 100
+};
 
 // add to the stage
 
 // add to the stage
-dali.stage.add( imageActor );
+dali.stage.add( imageView );
 @endcode
 
 For a more detailed example see the ShaderEffect example in the JavaScript documentation.
 @endcode
 
 For a more detailed example see the ShaderEffect example in the JavaScript documentation.
@@ -220,32 +243,19 @@ This is a basic example of a button defined in JSON by setting the default prope
 
 @code
 {
 
 @code
 {
-  "constants": {
-    "CONFIG_SCRIPT_LOG_LEVEL": "Verbose"
-  },
-  "stage": [
-    // First Button
+  "stage":
+  [
     {
     {
-      "type": "PushButton",
-      "parentOrigin": "TOP_CENTER",
-      "anchorPoint": "TOP_CENTER",
+      "type": "ImageView",
+      "parentOrigin": "CENTER",
+      "anchorPoint": "CENTER",
       "position": [0, 0, 0],
       "position": [0, 0, 0],
-      "size": [0, 200, 0],
-      "normalStateActor": {
-        "type": "ImageActor",
-        "image": {
-          "filename": "{DALI_IMAGE_DIR}blocks-brick-1.png"
-        }
-      },
-      "selectedStateActor": {
-        "type": "ImageActor",
-        "image": {
-          "filename": "{DALI_IMAGE_DIR}blocks-brick-2.png"
-        }
-      },
-      "labelActor": {
-        "type": "TextLabel",
-        "text": "Normal"
+      "image":
+      {
+        "rendererType" : "image",
+        "imageUrl" : "images/icon-0.png",
+        "width" : 100,
+        "height" : 100
       }
     }
   ]
       }
     }
   ]
Domain: Graphics System / DALi;