Dali 3D User Interface Engine
Properties

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.

What is a property used for?

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.

How to implement a property within Dali-core:

There are two stages:

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".

Example: Layer

Within the public-api header file; layer.h:

struct Property
{
enum
{
CLIPPING_BOX,
BEHAVIOR,
};
};

From Dali::Layer::Property

Notes:

Within the internal implementation; layer-impl.cpp:

namespace // Unnamed namespace
{
// Properties
// Name Type writable animatable constraint-input enum for index-checking
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 )

Notes:


How to implement a property within Dali-toolkit:

Macros are used to define properties for the following reasons:

Two different macros are provided depending on whether the property is to be an event-side only property or an animatable property.

There are two stages:

Example: ImageView

Source file: image-view.h: Note that the “PropertyRange” contents “PROPERTY_START_INDEX” & "ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX" are also used by the macro for order checking.

enum PropertyRange
{
PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1,
PROPERTY_END_INDEX = PROPERTY_START_INDEX + 1000,
ANIMATABLE_PROPERTY_START_INDEX = ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX,
ANIMATABLE_PROPERTY_END_INDEX = ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX + 1000
};
struct Property
{
enum
{
// Event side properties
RESOURCE_URL = PROPERTY_START_INDEX,
IMAGE,
PRE_MULTIPLIED_ALPHA,
// Animatable properties
PIXEL_AREA = ANIMATABLE_PROPERTY_START_INDEX,
};
};

Source file: image-view-impl.cpp, within an unnamed namespace:

{"image-view-impl.cpp",DALI_TYPE_REGISTRATION_BEGIN,DALI_TYPE_REGISTRATION_END}

Notes:



Property Indices

The properties are enumerated to give them a unique index. This index can be used to access them. The indecies must be unique per flattened derivation heirachy. EG:

There are some predefined start indecies and ranges that should be used for common cases, these are defined below:

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.

Kind Description Start Index End Index
Default Properties defined within DALi Core, e.g. Dali::Actor, Dali::ShaderEffect default properties etc. DEFAULT_OBJECT_PROPERTY_START_INDEX DEFAULT_PROPERTY_MAX_COUNT (9999999)
Registered Properties registered using Dali::PropertyRegistration PROPERTY_REGISTRATION_START_INDEX (10000000) PROPERTY_REGISTRATION_MAX_INDEX (19999999)
Registered Animatable Animatable properties registered using Dali::PropertyRegistration ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX (20000000) ANIMATABLE_PROPERTY_REGISTRATION_MAX_INDEX (29999999)
Control Property range reserved by Dali::Toolkit::Control CONTROL_PROPERTY_START_INDEX (10000000) CONTROL_PROPERTY_END_INDEX (10001000)
Derived Control Property range for control deriving directly from Dali::Toolkit::Control 10001001 PROPERTY_REGISTRATION_MAX_INDEX (19999999)
Custom Custom properties added to instance using Dali::Handle::RegisterProperty PROPERTY_CUSTOM_START_INDEX (50000000) Onwards...



Property use example C++

Common uses for properties are constraints and animations.

An application developer can use an existing property, or, if necessary, register their own.

Here is a code example.

This example shows how to register and look-up custom properties. 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 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.

{"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.



Property use in JavaScript

Note that constraints cannot be used within JavaScript, so below is a simple example that sets one of the default properties; scale:

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
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
dali.stage.add( imageView );

For a more detailed example see the ShaderEffect example in the JavaScript documentation.



Property use in JSON

This is a basic example of a button defined in JSON by setting the default properties.

{
"stage":
[
{
"type": "ImageView",
"parentOrigin": "CENTER",
"anchorPoint": "CENTER",
"position": [0, 0, 0],
"image":
{
"rendererType" : "image",
"imageUrl" : "images/icon-0.png",
"width" : 100,
"height" : 100
}
}
]
}
Dali Docs Home
Read more about Dali