X-Git-Url: http://review.tizen.org/git/?p=platform%2Fcore%2Fuifw%2Fdali-toolkit.git;a=blobdiff_plain;f=docs%2Fcontent%2Fprogramming-guide%2Fproperties.h;h=b445a2ee0936769b3baaa80b8e13c5a94aa4a6bd;hp=b9c87e9ae32a00ee23e601b4bced63d99a6ed7f5;hb=971bfa9c6730fefc49e45c5df796ce7e34e43ae3;hpb=864042717041b6d9ad114b2e2f360f5f07c7682b diff --git a/docs/content/programming-guide/properties.h b/docs/content/programming-guide/properties.h index b9c87e9..b445a2e 100644 --- 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". -Example: ImageActor +Example: Layer -Within the public-api header file; image-actor.h: +Within the public-api header file; layer.h: @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 - 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 @SINCE_1_0.0 + BEHAVIOR, ///< name "behavior", type String @SINCE_1_0.0 + }; }; -}; @endcode -From @ref Dali::ImageActor::Property +From @ref Dali::Layer::Property Notes: - 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; image-actor-impl.cpp: +Within the internal implementation; layer-impl.cpp: @code namespace // Unnamed namespace @@ -61,12 +61,11 @@ namespace // Unnamed namespace // 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( "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 @@ -82,22 +81,23 @@ DALI_PROPERTY_TABLE_END( DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX )

How to implement a property within Dali-toolkit:

-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. There are two stages: - 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. -Example: Button +Example: ImageView -Source file: button.h: -Note that the “PropertyRange” contents “PROPERTY_START_INDEX” is also used by the macro for order checking. +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. @code /** @@ -105,8 +105,11 @@ Note that the “PropertyRange” contents “PROPERTY_START_INDEX” is also us */ 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 { - 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 -Source file: button-impl.cpp, within an unnamed namespace: +Source file: image-view-impl.cpp, 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} Notes: @@ -141,7 +162,6 @@ Source file: button-impl.cpp, 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. -
@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. - - - - - - - -
Kind Description Start IndexEnd 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 (0)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)
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...
- +| 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... |
@@ -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. -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. @@ -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 -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 -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 -dali.stage.add( imageActor ); +dali.stage.add( imageView ); @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 { - "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], - "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 } } ]