- \link handle-body-idiom Handle – body idiom \endlink
## Actors
- - \link image-mesh-actor Image, Text and Mesh actors \endlink
+ - \link image-mesh-actor Image and Mesh actors \endlink
- \link event-system Event Handling \endlink
- \link custom-actor Custom Actor \endlink
- \link size-negotiation Size Negotiation \endlink
## UI Controls
+ - \link text-label Text Label\endlink
- \link scroll-view Scroll View \endlink
- \link size-negotiation-controls Size Negotiation for Controls \endlink
- \link type-registration Type Registration \endlink
- \link dynamics-collisions Collision Detection and Filtering\endlink
## Scripting
- - \link scriptoverview.html JSON and JavaScript Overview \endlink
- - \link javascriptwrapping.html JavaScript Wrapping Guide for DALi developers\endlink
- - \link script-hello Hello World in script \endlink
+ - \link scriptoverview JSON and JavaScript Overview \endlink
- \link script-json-specification JSON Specification\endlink
+ - \link script-hello Hello World in script \endlink
+ - \link javascriptwrapping JavaScript Wrapping Guide for DALi developers\endlink
## Rendering
- \link viewing-modes Viewing modes \endlink
## Profiling
- - \link performanceprofiling.html Performance Profiling \endlink
- - \link resourcetracking.html Resource Tracking \endlink
+ - \link performanceprofiling Performance Profiling \endlink
+ - \link resourcetracking Resource Tracking \endlink
## Performance
- - \link performancetips.html Performance Tips \endlink
- - \link textureatlases.html Texture Atlases \endlink
- - \link texturecompression.html Compressing Textures \endlink
+ - \link performancetips Performance Tips \endlink
+ - \link textureatlases Texture Atlases \endlink
+ - \link texturecompression Compressing Textures \endlink
## Testing
See [Automated Tests](@ref auto_testing) for instructions.
## Modifying this documentation
-- \link documentationguide.html Modifying this documentation \endlink
+- \link documentationguide Modifying this documentation \endlink
+++ /dev/null
-/*! \page fundamentals Dali Fundamentals
- *
-<h2 class="pg">Actors and the Stage</h2>
-
-A Dali application uses a hierachy of Dali::Actor objects to position visible content. An actor inherits a position relative to its parent, and can be moved relative to this point. UI controls can be built by combining multiple actors.
-
-To display the contents of an actor, it must be connected to the Dali::Stage. This provides an invisible root (top-level) actor, to which all other actors are added. A direct or indirect child of the root actor is considered "on-stage". Multi-touch events are received through signals emitted by on-stage actors.
-
-The following example shows how to connect a new actor to the stage:
-
-@code
-Actor actor = Actor::New();
-Stage::GetCurrent().Add(actor);
-@endcode
-
-<h2 class="pg">The Coordinate System</h2>
-
-The Stage has a 2D size, which matches the size of the application window. The default coordinate system in Dali has the origin at the top-left corner, with positive X to right, and position Y going
-downwards. This is intended to be convenient when laying-out 2D views.
-
-
-
-<h2 class="pg">Positioning Actors</h2>
-
-An actor inherits its parent's position. The relative position between the actor & parent is determined by 3 properties:
-
-1) ParentOrigin. This Vector3 property defines a point within the parent actor's area.
-
-
-
-The default is "top-left", which can be visualized in 2D as (0, 0), but is actually Vector3(0, 0, 0.5) in the 3D Dali world. The actor's position is relative to this point.
-
-2) AnchorPoint. This Vector3 property defines a point within the child actor's area.
-
-
-
-The default is "center", which can be visualized in 2D as (0.5, 0.5), but is actually Vector3(0.5, 0.5, 0.5) in the 3D Dali world. The actor's position is also relative to this point.
-
-3) Position. This is the position vector between the parent-origin and anchor-point.
-
-
-
-Therefore by default, an actors position is the distance between its center and the top-left corner of its parent.
-
-An actor added directly to the stage with position (X = stageWidth*0.5, Y = stageHeight*0.5), would appear in the center of the screen. Likewise an actor with position (X = actorWidth*0.5, Y = actorWidth*0.5), would appear at the top-left of the screen.
-
-Note that since Dali is a 3D toolkit, this behaviour is the result of a default perspective camera setup.
-
-*
-*/
+++ /dev/null
-/*! \page script-hello Scripting Hello World
- *
- * <h2 class="pg">Hello World - JSON layout</h2>
- *
- * The following JSON code is the minimum required to put the sentence "Hello World" on the screen.
- *
- * @code
- * {
- * // a tree of actors
- * "stage": [{
- * "name": "text-label",
- * "type": "TextLabel",
- * "text": "Hello World",
- * "parent-origin": "CENTER"
- * }]
- * }
- * @endcode
- *
- * The following c++ code loads the JSON file
- *
- * @code
- * Builder builder = Builder::New();
- *
- * std::string json_data(ReadFile("layout.json"));
- *
- * builder.LoadFromString(json_data);
- *
- * Actor actor = builder.GetActor("text-label");
- *
- * Stage::GetCurrent().Add(actor);
- * @endcode
- *
- * <h2 class="pg">Hello World - Javascript</h2>
- *
- * Hello world can also be executed via Javascript.
- *
- * The Dali script application is needed to run the Javascript which provides a Javascript runtime and an interface to Dali.
- *
- * @code
- * daliscript hello-world.js
- * @endcode
- *
- * The TextLabel control to display Hello World can be constructed using Javascript dot notation accessing Dali Actor Properties.
- *
- * @code
- * var textLabel = Dali.TextLabel();
- *
- * textLabel.text = "Hello World";
- * textLabel.font-family = "FreeSans";
- * textLabel.font-style = "Regular";
- * textLabel.parent-origin = "CENTER";
- *
- * Dali.Run();
- * @endcode
- *
- */
-
-
+++ /dev/null
-/**
- *
-[TOC]
-
-# DALi JSON Specification {#script-json-specification}
-
-## Overview {#overview}
-
-This document describes the Dali JSON specification.
-The format is not yet formally versioned within the JSON.
-
-# General format {#format}
-
-The JSON format supports
-
-- Named templates for on demand creation of
- - Actors/ Controls
- - Animations
-- Style sets
- - Dynamically change the style of Actor hierarchies
- - Animate to a style set
-- Includes
- - Build style sets up by merging JSON
-- Creating Scene content on load
- - Controls created without any code
-
-
-Concrete Actors and Controls can be created from types registered in the
-Dali Type Registry.
-
-Template, style and scene sections all configure Actors and Controls via
-the Dali property system.
-
-The JSON format deviates from the formal JSON specification and allows C style comments.
-
-~~~
- { //
- "version": 0, // Version Number
- "includes": // Include section
- [ //
- "base-theme.json" // Include file to merge into the
- // JSON
- ] //
- "constants": // Constant replacement section
- { //
- ... //
- }, //
- "templates": // Template library section
- { //
- "basic-text": // A named template
- { // } key value properties
- ... //
- "actors": // A tree of sub actors
- [ //
- ... //
- ] //
- } //
- }, //
- "styles": // Named Style set section
- { //
- "light-theme": // Style set name
- { //
- ... //
- }, //
- dark-theme": //
- { //
- ... //
- }, //
- } //
- "stage": // Stage section
- [ //
- { // Actors|Controls to create on JSON file load
- "type": "basic-text", // A Dali Control or a template name
- "styles":["base-theme","light-theme"] // Style list to apply to this instance
- } //
- ] //
- } //
-~~~
-
-# Top level sections {#sections}
-
-## Includes {#includes}
-
-The "includes" section is an array of filenames to be merged in order to
-create a final in memory JSON tree.
-
-The merge process will walk key, value attributes from the root JSON
-node and overwrite previous values with the newer values.
-
-- If the key does not exist then it will be created.
-- If the newer value is a different type then the newer type will persist.
-- Where both values are objects the merge will descend into the object.
-- Where both values are arrays the merge will replace the old array entirely.
-
-The merge is relatively simple and is expected to be used to build up
-from base themes to custom themes where there are few conflicts and
-simple direct replacements are desired.
-
-### Constants {#constants}
-
-The merge behaviour when a file has constants and includes is
-
-1. Constants are loaded first
-2. Includes file list is merged in order
-3. All other (non constant) data is merged
-
-The include merge is recursive, so step (2) above will cause the
-constants in the first included file to be merged first.
-
-## Constants {#constantdetail}
-
-The constants section supports sub-string and full property replacement.
-
-~~~
- {
- "constants": // Constant replacement section
- { //
- "IMAGES": "/usr/share/images/", // Constants can be set here or in code.
- "SIZE": [100,100,1] //
- }, //
- ... //
- { //
- "type":"ImageActor" // An Dali type or a template name
- "image": //
- { //
- "filename":"{IMAGES}b.jpg" // Image filename substring replacement
- }, //
- "size": "{SIZE}" //
- } // Property replacement
- } //
-~~~
-
-The type of the constant should match the expected type of the property.
-
-A property constant cannot be used for sub string replacement; a string
-constant should be used.
-
-With a property replacement, the replace site must contain a string
-where the first and last positions are braces.
-
-## Templates {#templates}
-
-The template section supports the creation of actor instances. The
-template name can be used in code to create an actor tree.
-
-~~~
-actorTree = builder.Create("basic-text");
-~~~
-
-Templates consist of a name, multiple property-value configurations and
-an optional actor sub hierarchy.
-
-~~~
- { //
- "templates": // Template library section
- { //
- "basic-text": // The template name
- { //
- "type":"ImageActor", // Concrete Dali Type/Class to create
- "styles":["base-style"], // Style list to apply
- "name":"image", // }
- "image": // } property name : value
- { // }
- "filename":"{IMAGES}/b.jpg" //
- }, //
- "parent-origin": "CENTER" //
- ... //
- "actors": // A tree of sub actors
- [ //
- { //
- "type":"TextView" //
- "name":"text", //
- "text":"Hello World", //
- "parent-origin": "CENTER", //
- } //
- ] //
- } //
- } //
-~~~
-
-A template has a special 'type' property which must contain a concrete
-Dali Actor or Control type name.
-
-A template has a special 'styles' property which contains a list of
-styles to apply when creating using the template.
-
-## Styles {#styles}
-
-The styles section supports a named set of properties that can be
-applied to an actor or actor tree.
-
-~~~
-Builder.ApplyStyle("light-theme", myActor);
-~~~
-
-The styles can also be applied as an animation.
-
-~~~
-Builder.AnimateTo("light-theme", myActor, TimePeriod(0, 10));
-~~~
-
-~~~
- { //
- "styles": // Style set section
- { //
- "light-theme": // Style-set name
- { //
- "color":[1,1,1,1] // }
- "position":[0,-120,0], // } properties to set on the given actor
- "rotation":[0,0,30], // }
- "actors": //
- { // Sub Actors are referenced by name
- "title-text": // Actor name to search for under given actor
- { //
- "color":[1,1,1,1] // }
- "position":[0,-120,0], // } properties to set if 'title-text' is found
- "rotation":[0,0,30], // }
- }
- }, //
- "icon": //
- { //
- "color":[1,1,1,1] //
- } //
- }, //
- "dark-theme": //
- { //
- } //
- } //
-~~~
-
-When applied to an actor tree the actors are referenced by name. Names
-are not unique in Dali.
-
-When a style is applied in code Dali will perform a depth first search
-stopping with the first matching name.
-
-Typically an application developer will apply the style to the template
-root actor and not the stage root actor. Therefore in most uses cases
-name conflicts are not expected.
-
-## Animations {#animations}
-
-The animation section defines a library of animation definitions.
-
-The animations can be created by name from code.
-
-They can also be created automatically from JSON in an actor signal.
-
-~~~
- { //
- "animations": // Animation library
- { //
- "rotate": // An Animation named rotate
- { //
- "duration": 10, // Duration in seconds
- "loop": false, // Whether to loop.
- "end-action": "Bake", // Whether to set final value(bake) or
- // reset
- "disconnect-aciton": "Discard", // Whether 'Bake' or 'Discard' when disconnected
- "properties":
- [
- // Properties changed in this animation
- {
- "actor":"image", // Actor found by name from the stage
- "property":"rotation", // Property to change
- "value":[0, 0.1, 0, 0], // Value to set
- "alpha-function": "EASE\_IN\_OUT", // Interpolation function
- //
- "time-period": // Time period for change
- {"delay": 0,
- "duration": 3
- }
- },
- ... // 1 or more property changes per animation
- }, //
- ... //
- }, //
-~~~
-
-### Splines {#splines}
-
-An animation property can be defined with a path and forward direction
-instead of a single final value.
-
-Paths are defined in a top level path section and referenced by the
-animation property.
-
-~~~~
- { //
- "paths": // Path library
- { //
- "path0": // Path definition by name
- { //
- "points":[ // points
- [-150, -50, 0],
- [0.0,70.0,0.0],
- [190.0,-150.0,0.0]
- ],
- // curvature automatically creates
- "curvature":0.35, // control-points
- //
- "control-points": [...] // Otherwise control-points can be
- // directly specified.
- } //
- }, //
- "animations": //
- { //
- "path-animation":
- {
- "duration": 3.0,
- "properties":
- [
- {
- "actor": "greeting2",
- // Path is mandatory for spline
- "path":"path0", // animation.
- "forward":[1,0,0], // Forward vector specifies orientation
- // whilst travelling along the path
- "alpha-function": "EASE\_IN\_OUT", // (optional)
- "time-period":
- {
- "delay": 0,
- "duration": 3
- }
- },
- ...
- // Other properties changes can use
- ] // paths or values in the same
- // animation.
- }, //
- } //
-~~~~
-
-## Shaders {#shaders}
-
-The shader section of the JSON file defines a library of shader effect
-instances that are created on demand.
-
-The shaders are referred to by name from the template, style, stage or
-animation sections.
-
-Multiple actors can set the same shader as the name refers to a single
-instance.
-
-Similarly one named shader instance can be set to several actors and can
-be animated by one animation.
-
-~~~~
- { //
- "shader-effects": // Shader Effect section
- { //
- "myshader1": // Shader instance name
- { //
- "program": //
- { // Prefixs are placed before DALi uniforms.
- "vertexPrefix": "", // (Useful for \#defines.)
- "vertex":"", // Glsl vertex program
- "fragmentPrefix": "",
- "fragment": "", // Glsl fragment program.
- "geometry-type": "GEOMETRY_TYPE_IMAGE", // Geometry type(see DALi documentation)
- },
- "geometry-hints": "HINT_NONE": // Geometry hints (see DALi documentation)
- "grid-density": 0, // Grid density(see DALi documentation)
- "image":
- {
- "filename": "" // Effect image available as a second texture unit.
- }
- },
- ...
- },
- "stage":
- [{
- "type": "ImageActor",
- "effect": "myshader1",
- ...
- }]
- }
-~~~~
-
-At least one of the vertex or fragment fields is mandatory. All
-other fields are optional will use internal defaults.
-
-Actors have an "effect" field that refers to the shader effect
-instance to use with that actor.
-
-### Animating shaders {#animatingshaders}
-
-Shader uniforms can be animated as if they are properties of the actor.
-
-When the animation is created from code (or from a signal) the property
-name search begins on the actor, if it isn't found the search continues
-on the attached shader object.
-
-The actor property names and shader uniform names must not clash for the
-uniform to animate correctly. The convention in DALi is to prepend
-uniforms with 'u'.
-
-~~~~
- { \\
- "animations": \\ Animation library
- { \\
- "rotate": \\ An Animation named rotate
- { \\
- "duration": 10, \\
- "properties": \\ Properties changed in this animation
- [ \\
- {
- "actor":"image", \\ Actor found by name from the stage
- "property":"uTranslate", \\ Uniform name specified as if it is a
- \\ property of the object.
- "value":[10, 20],
- ...
- },
- ...
- ]
- },
- "shader-effects":
- {
- "myshader1":
- {
- \\ Shader program with uniform
- "program": {...} \\ "uTranslate"
- }
- },
- "actors":
- [
- {
- "name": "image",
- "effect": "myshader1" \\ Actor using shader effect instance
- \\ "myshader1"
- }
- ]
- },
-~~~~
-
-## Stage {#stage}
-
-The stage section supports the immediate creation of actors at the time
-the JSON is loaded.
-
-The stage is a tree of actors that can be added to Dali's stage object.
-
-~~~
-builder = Dali.Builder();
-json_text = load("layout.json");
-builder.Load(json\_text);
-stage = Dali.Stage.GetCurrent();
-builder.AddActors( stage.GetRootLayer()); // Add actors to the stage root layer
-~~~
-
-~~~
- { \\
- "stage": \\ Stage Section Number
- [ \\ An array of actors
- {
- "type": "ImageActor",
- ...
- "actors": \\ Each actor can have children
- \\ creating a tree
- [
- {
- "type": "TextView",
- \\ The Type to create; this can be a
- ... \\ concrete Dali type (actor/control)
- \\ or a template name.
- "styles": ["base-style"]
- \\ A list of styles to apply to the
- } \\ created type.
- ]
- }
- ]
- }
-~~~
-
-# Actor and Control Properties {#actorprop}
-
-Each control has a set of supported properties documented in the "Dali
-UI Control Specification".
-
-Please refer to the above document for further information about specific
-controls.
-
-@class ScriptJsonSpecification
-*/
+++ /dev/null
-/*! \page text-label Text Label
- *
-\section overview Overview
-The Dali::Toolkit::TextLabel is a Dali::Toolkit::Control which renders a short text string.\n
-Text labels are lightweight, non-editable and do not respond to user input.
-
-\subsection basictextlabelusage Basic usage
-
-To display a TextLabel the TEXT property must be set using a UTF-8 string.
-
-\code
-TextLabel label = TextLabel::New();
-label.SetProperty( TextLabel::Property::TEXT, "Hello World" );
-label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
-Stage::GetCurrent().Add( label );
-\endcode
-
-The label must also be added to the stage, or to an actor which is on the stage.\n
-The position of the label on-screen is dependent on the parent-origin and anchor-point properties.\n
-
-<table border=0 cellpadding=10>
-<tr>
- <td>
- \image html TextLabelTopLeft.png
- </td>
-</tr>
-<tr>
- <td>
- (ParentOrigin::TOP_LEFT, AnchorPoint::TOP_LEFT)
- </td>
-</tr>
-</table>
-
-\subsection fontSelection Font Selection
-
-By default TextLabel will automatically select a suitable font from the platform.\n
-Typically fonts do not support all scripts, for example Latin fonts often do not provide Arabic glyphs.\n
-Therefore you should expect TextLabel to select different fonts for each script.
-
-Alternatively a font may be requested using either or all of FONT_FAMILY, FONT_STYLE, and POINT_SIZE properties:
-\code
-label.SetProperty( TextLabel::Property::FONT_FAMILY, "HelveticaNue" );
-label.SetProperty( TextLabel::Property::FONT_STYLE, "Regular" );
-label.SetProperty( TextLabel::Property::POINT_SIZE, 12.0f );
-\endcode
-However the TextLabel will fall-back to using the default font, if the requested font does not support the required scripts.
-
-\subsection fontStyles Font Styles
-
-Setting a font size programmatically is not ideal for applications which support multiple screen resolutions etc.\n
-A more flexible approach is to prepare various JSON stylesheets, and request a different style for each platform:\n
-
-\code
-StyleManager styleManager = StyleManager::Get();
-styleManager.RequestThemeChange( "example-path/example.json" );
-\endcode
-
-To change the font for standard text labels, this JSON syntax can be used:
-
-\code
-{
- "styles":
- {
- "textlabel":
- {
- "font-family":"Arial",
- "font-style":"Regular",
- "point-size":8
- }
- }
-}
-\endcode
-
-However the same point-size is unlikely to be suitable for all labels in an application.\n
-To set custom sizes simply set a "style name" for each case, and then provide a style override in JSON:
-
-\code
- label.SetProperty( Control::Property::STYLE_NAME, "custom" );
-\endcode
-
-\code
-{
- "styles":
- {
- "textlabel":
- {
- "font-family":"Arial",
- "font-style":"Regular",
- "point-size":8
- },
-
- "custom":
- {
- "point-size":10
- }
- }
-}
-\endcode
-
-In the example above, standard text labels will have point-size 8, and "custom" labels will have point-size 10.\n
-
-\subsection textAlignment Text Alignment
-
-Wrapping can be enabled using the MULTI_LINE property:\n
-\code
-label.SetProperty( TextLabel::Property::MULTI_LINE, true );
-\endcode
-
-The text can be either aligned horizontally to the beginning, end, or center of the available area:
-\code
-label.SetProperty( TextLabel::Property::HORIZONTAL_ALIGNMENT, "BEGIN" ); // "CENTER" or "END"
-\endcode
-
-<table border=0 cellpadding=10>
-<tr>
- <td>
- Here is the "BEGIN" alignment shown for left-to-right (Latin) and right-to-left (Arabic) scripts:
- </td>
-</tr>
-<tr>
- <td>
- \image html LatinBegin.png
- </td>
- <td>
- \image html ArabicBegin.png
- </td>
-</tr>
-<tr>
- <td>
- Here is the "CENTER" alignment shown for left-to-right (Latin) and right-to-left (Arabic) scripts:
- </td>
-</tr>
-<tr>
- <td>
- \image html LatinCenter.png
- </td>
- <td>
- \image html ArabicCenter.png
- </td>
-</tr>
-<tr>
- <td>
- Here is the "END" alignment shown for left-to-right (Latin) and right-to-left (Arabic) scripts:
- </td>
-</tr>
-<tr>
- <td>
- \image html LatinEnd.png
- </td>
- <td>
- \image html ArabicEnd.png
- </td>
-</tr>
-</table>
-
-The examples above assume that the TextLabel size greater than the minimum required.\n
-The next section provides details about the other size related options.
-
-\subsection negotiatingSize Negotiating size
-
-\link size-negotiation Size negotiation \endlink is a layouting feature supported by UI controls such as TextLabel.\n
-There are several resize policies which are commonly used with TextLabels.\n
-The following examples show TextLabels actual size by setting a colored background, whilst the black area represents the size of the parent control:\n
-
-<h3>Using natural size</h3>
-
-With a "natural" size TextLabel will be large enough to display the text without wrapping, and will not have extra space to align the text within.\n
-Therefore in this example the same result would be displayed, regardless of the alignment or multi-line properties.\n
-
-\code
-TextLabel label = TextLabel::New( "Hello World" );
-label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
-label.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::ALL_DIMENSIONS );
-label.SetBackgroundColor( Color::BLUE );
-Stage::GetCurrent().Add( label );
-\endcode
-
-<table border=0 cellpadding=10>
-<tr>
- <td>
- \image html HelloWorld-NaturalSize.png
- </td>
-</tr>
-</table>
-
-<h3>Height-for-width negotiation</h3>
-
-To layout text labels vertically, a fixed (maximum) width should be provided by the parent control.\n
-Each TextLabel will then report a desired height for the given width.\n
-Here is an example of this behavior using TableView as the parent:
-
-\code
-TableView parent = TableView::New( 3, 1 );
-parent.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
-parent.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::HEIGHT );
-parent.SetAnchorPoint( AnchorPoint::TOP_LEFT );
-Stage::GetCurrent().Add( parent );
-
-TextLabel label = TextLabel::New( "Hello World" );
-label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
-label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
-label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
-label.SetBackgroundColor( Color::BLUE );
-parent.AddChild( label, TableView::CellPosition( 0, 0 ) );
-parent.SetFitHeight( 0 );
-
-label = TextLabel::New( "A Quick Brown Fox Jumps Over The Lazy Dog" );
-label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
-label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
-label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
-label.SetBackgroundColor( Color::GREEN );
-label.SetProperty( TextLabel::Property::MULTI_LINE, true );
-parent.AddChild( label, TableView::CellPosition( 1, 0 ) );
-parent.SetFitHeight( 1 );
-
-label = TextLabel::New( "لإعادة ترتيب الشاشات، يجب تغيير نوع العرض إلى شبكة قابلة للتخصيص." );
-label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
-label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
-label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
-label.SetBackgroundColor( Color::BLUE );
-label.SetProperty( TextLabel::Property::MULTI_LINE, true );
-parent.AddChild( label, TableView::CellPosition( 2, 0 ) );
-parent.SetFitHeight( 2 );
-\endcode
-
-<table border=0 cellpadding=10>
-<tr>
- <td>
- \image html HelloWorld-HeightForWidth.png
- </td>
-</tr>
-</table>
-
-Note that the "Hello World" text label (above) has been given the full width, not the natural width.
-
-\subsection textLabelDecorations TextLabel Decorations
-
-<h3>Color</h3>
-
-To change the color of the text, the recommended way is to use the TEXT_COLOR property.\n
-Note that unlike the Actor::COLOR property, this will not affect child Actors added to the TextLabel.\n
-
-\code
-label.SetProperty( TextLabel::Property::TEXT, "Red Text" );
-label.SetProperty( TextLabel::Property::TEXT_COLOR, Color::RED );
-\endcode
-
-<table border=0 cellpadding=10>
-<tr>
- <td>
- \image html RedText.png
- </td>
-</tr>
-</table>
-
-<h3>Drop Shadow</h3>
-
-To add a drop-shadow to the text, simply set the SHADOW_OFFSET property with non-zero values.\n
-The color can also be selected using the SHADOW_COLOR property.\n
-
-\code
-stage.SetBackgroundColor( Color::BLUE );
-
-label1.SetProperty( TextLabel::Property::TEXT, "Plain Text" );
-
-label2.SetProperty( TextLabel::Property::TEXT, "Text with Shadow" );
-label2.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 1.0f, 1.0f ) );
-label4.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::BLACK );
-
-label3.SetProperty( TextLabel::Property::TEXT, "Text with Bigger Shadow" );
-label3.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 2.0f, 2.0f ) );
-label4.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::BLACK );
-
-label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Shadow" );
-label4.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 1.0f, 1.0f ) );
-label4.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::RED );
-\endcode
-
-<table border=0 cellpadding=10>
-<tr>
- <td>
- \image html PlainText.png
- </td>
-</tr>
-<tr>
- <td>
- \image html TextWithShadow.png
- </td>
-</tr>
-<tr>
- <td>
- \image html TextWithBiggerShadow.png
- </td>
-</tr>
-<tr>
- <td>
- \image html TextWithColorShadow.png
- </td>
-</tr>
-</table>
-
-<h3>Underline</h3>
-
-The text can be underlined by setting UNDERLINE_ENABLED.\n
-The color can also be selected using the UNDERLINE_COLOR property.\n
-
-\code
-label1.SetProperty( TextLabel::Property::TEXT, "Text with Underline" );
-label1.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
-
-label2.SetProperty( TextLabel::Property::TEXT, "Text with Color Underline" );
-label2.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
-label2.SetProperty( TextLabel::Property::UNDERLINE_COLOR, Color::GREEN );
-\endcode
-
-<table border=0 cellpadding=10>
-<tr>
- <td>
- \image html TextWithUnderline.png
- </td>
-</tr>
-<tr>
- <td>
- \image html TextWithColorUnderline.png
- </td>
-</tr>
-</table>
-
-By default the underline height will be taken from the font metrics, however this can be overridden using the UNDERLINE_HEIGHT property:
-
-\code
-label1.SetProperty( TextLabel::Property::UNDERLINE_HEIGHT, 1.0f );
-\endcode
-
-<table border=0 cellpadding=10>
-<tr>
- <td>
- \image html TextWith1pxUnderline.png
- </td>
-</tr>
-</table>
-
-*/
+++ /dev/null
-
-/*! \page Texture_Compression Texture Compression
-
-
-Using compressing the textures will:
-<ul>
-<li> Speed up rendering in time the GPU == less power used due to less texture data being transferred.
-<li> Reduce texture memory usage.
-<li> Speed up load times. Smaller files mean quicker load times.
-</ul>
-<br><br>
-DALi supports the KTX file format.
-You just load the compressed texture like you would any other image.
-\code
-Image::New("my_compressed_file.ktx");
-\endcode
-<br>
-ARMS texture compression tool<br>
-http://malideveloper.arm.com/develop-for-mali/tools/asset-creation/mali-gpu-texture-compression-tool/ <br>
-
-Here is an example of using the ARM compression tool.
-\image html compression-options.jpg
-
-<br><br>
-
-\image html compression-example.jpg
-<br>
-<br>
-As shown above the ETC-1 compression format does not support alpha.<br> As a work around the tool will export
-the alpha as a seperate compressed image.<br>
-In order to combine both the images you need to use a custom shader.<br>
-Here is an example shader:<br>
-\code
- const char* const COMPRESSED_RGB_PLUS_SEPARATE_ALPHA_FRAGMENT_SOURCE =
- "\n"
- "void main()\n"
- "{\n"
- " vec4 v4Color = (texture2D(sTexture, vTexCoord) * uColor);\n"
- " v4Color.a = texture2D(sEffect, vTexCoord ).r;\n"
- " gl_FragColor = v4Color;"
- "}\n";
-
-
- mShaderEffect = ShaderEffect::New( "", COMPRESSED_RGB_PLUS_SEPARATE_ALPHA_FRAGMENT_SOURCE);
-
- mAtlasImageRGB = Image::New( ATLAS_RGB_FILENAME.KTX);
-
- mAtlasImageAlpha = Image::New( ATLAS_ALPHA_FILENAME.KTX );
-
- mShaderEffect.SetEffectImage( mAtlasImageAlpha );
-
-
-
- // to create Image Actor
- ImageActor imageActor = ImageActor::New( mAtlasImageRGB, GetImagePosition( info) );
-
- imageActor.SetShaderEffect( mShaderEffect );
-
- imageActor.SetBlendMode(BlendingMode::ON);
-
-\endcode
-
-
- */
--- /dev/null
+/**
+ *
+# Dali Fundamentals {#fundamentals}
+
+## Actors and the Stage
+
+A Dali application uses a hierachy of Dali::Actor objects to position visible content. An actor inherits a position relative to its parent, and can be moved relative to this point. UI controls can be built by combining multiple actors.
+
+To display the contents of an actor, it must be connected to the Dali::Stage. This provides an invisible root (top-level) actor, to which all other actors are added. A direct or indirect child of the root actor is considered "on-stage". Multi-touch events are received through signals emitted by on-stage actors.
+
+The following example shows how to connect a new actor to the stage:
+
+~~~{.cpp}
+Actor actor = Actor::New();
+Stage::GetCurrent().Add(actor);
+~~~
+
+~~~{.js}
+var actor = new dali.Actor();
+dali.stage.add( actor );
+~~~
+
+## The Coordinate System
+
+The Stage has a 2D size, which matches the size of the application window. The default coordinate system in Dali has the origin at the top-left corner, with positive X to right, and position Y going
+downwards. This is intended to be convenient when laying-out 2D views.
+
+
+
+
+## Positioning Actors
+
+An actor inherits its parent's position. The relative position between the actor & parent is determined by 3 properties:
+1) ParentOrigin. This Vector3 property defines a point within the parent actor's area.
+
+
+
+
+The default is "top-left", which can be visualized in 2D as (0, 0), but is actually Vector3(0, 0, 0.5) in the 3D Dali world. The actor's position is relative to this point.
+
+2) AnchorPoint. This Vector3 property defines a point within the child actor's area.
+
+
+
+
+The default is "center", which can be visualized in 2D as (0.5, 0.5), but is actually Vector3(0.5, 0.5, 0.5) in the 3D Dali world. The actor's position is also relative to this point.
+
+3) Position. This is the position vector between the parent-origin and anchor-point.
+
+
+
+
+Therefore by default, an actors position is the distance between its center and the top-left corner of its parent.
+
+An actor added directly to the stage with position (X = stageWidth*0.5, Y = stageHeight*0.5), would appear in the center of the screen. Likewise an actor with position (X = actorWidth*0.5, Y = actorWidth*0.5), would appear at the top-left of the screen.
+
+Note that since Dali is a 3D toolkit, this behaviour is the result of a default perspective camera setup.
+
+@class _Guide_DALi_Fundamentals
+
+*/
Each wrapped object registers with Dali garbage collector so they can be deleted
when Dali shuts down
-@class _Guide_JavaScript_Wrapping`
+@class _Guide_JavaScript_Wrapping
*/
\ No newline at end of file
/**
*
-# Performance Tips {#performancetips}
+# Performance Tips {#performancetips}
## High CPU occupancy
- Reduce visible actor count ( == less draw calls)
- For 2D UI graphics which require no z sorting you can use
+
~~~{.cpp}
- // In this mode depth testing is turned off and order is determined by the hierachy (depth-first search order).
- // Not always recommended if there is going to be a lot of overdraw ( if lots of actors are on top of each other)
+// C++
+// In this mode depth testing is turned off and order is determined by the hierachy (depth-first search order).
+// Not always recommended if there is going to be a lot of overdraw ( if lots of actors are on top of each other)
+
+Actor::SetDrawMode( DrawMode::OVERLAY ); // C++
+~~~
- Actor::SetDrawMode( DrawMode::OVERLAY ); // C++
-~~~~
~~~{.js}
- actor.drawMode = dali.DRAW_MODE_OVERLAY; // JavaScript
+// JavaScript
+// In this mode depth testing is turned off and order is determined by the hierachy (depth-first search order).
+// Not always recommended if there is going to be a lot of overdraw ( if lots of actors are on top of each other)
+
+actor.drawMode = dali.DRAW_MODE_OVERLAY;
~~~
- Use TextureAtlases ( reduces state changes in the GPU)
- Use compressed textures
@class _Guide_Performance_Tips
+
*/
--- /dev/null
+/**
+ *
+ # Hello World - JSON layout{#script-hello}
+
+ The following JSON code is the minimum required to put the sentence "Hello World" on the screen.
+
+~~~{.json}
+{
+ // a tree of actors
+ "stage": [{
+ "name": "text-label",
+ "type": "TextLabel",
+ "text": "Hello World",
+ "parent-origin": "CENTER"
+ }]
+}
+~~~
+
+ The following code loads the JSON file
+
+~~~{.cpp}
+ // C++
+ Builder builder = Builder::New();
+
+ std::string json_data(ReadFile("layout.json"));
+
+ builder.LoadFromString(json_data);
+
+ builder.AddActors( Stage::GetCurrent().GetRootLayer() );
+
+ ~~~
+
+ ~~~{.js}
+ // JavaScript
+
+ var builder = new dali.Builder();
+
+ builder.loadFromFile("layout.json");
+
+ builder.addActors( dali.stage.getRootLayer )
+
+~~~
+ ## Hello World - Javascript
+
+ The Dali script application is needed to run the Javascript which provides a Javascript runtime and an interface to Dali.
+
+~~~
+ scripting.example hello-world.js
+~~~
+
+ The TextLabel control to display Hello World can be constructed using Javascript dot notation accessing Dali Actor Properties.
+
+~~~{.js}
+// JavaScript
+
+ var textLabel = new dali.TextLabel();
+
+ textLabel.text = "Hello World";
+ textLabel.fontFamily = "FreeSans";
+ textLabel.fontStyle = "Regular";
+ textLabel.parentOrigin = dali.CENTER;
+
+ dali.stage.add( textLabel );
+~~~
+
+@class _Guide_Script_Hello_World
+ */
\ No newline at end of file
--- /dev/null
+/**
+ *
+[TOC]
+
+# DALi JSON Specification {#script-json-specification}
+
+## Overview {#overview}
+
+This document describes the Dali JSON specification.
+The format is not yet formally versioned within the JSON.
+
+# General format {#format}
+
+The JSON format supports
+
+- Named templates for on demand creation of
+ - Actors/ Controls
+ - Animations
+- Style sets
+ - Dynamically change the style of Actor hierarchies
+ - Animate to a style set
+- Includes
+ - Build style sets up by merging JSON
+- Creating Scene content on load
+ - Controls created without any code
+
+
+Concrete Actors and Controls can be created from types registered in the
+Dali Type Registry.
+
+Template, style and scene sections all configure Actors and Controls via
+the Dali property system.
+
+The JSON format deviates from the formal JSON specification and allows C style comments.
+
+~~~
+ { //
+ "version": 0, // Version Number
+ "includes": // Include section
+ [ //
+ "base-theme.json" // Include file to merge into the
+ // JSON
+ ] //
+ "constants": // Constant replacement section
+ { //
+ ... //
+ }, //
+ "templates": // Template library section
+ { //
+ "basic-text": // A named template
+ { // } key value properties
+ ... //
+ "actors": // A tree of sub actors
+ [ //
+ ... //
+ ] //
+ } //
+ }, //
+ "styles": // Named Style set section
+ { //
+ "light-theme": // Style set name
+ { //
+ ... //
+ }, //
+ dark-theme": //
+ { //
+ ... //
+ }, //
+ } //
+ "stage": // Stage section
+ [ //
+ { // Actors|Controls to create on JSON file load
+ "type": "basic-text", // A Dali Control or a template name
+ "styles":["base-theme","light-theme"] // Style list to apply to this instance
+ } //
+ ] //
+ } //
+~~~
+
+# Top level sections {#sections}
+
+## Includes {#includes}
+
+The "includes" section is an array of filenames to be merged in order to
+create a final in memory JSON tree.
+
+The merge process will walk key, value attributes from the root JSON
+node and overwrite previous values with the newer values.
+
+- If the key does not exist then it will be created.
+- If the newer value is a different type then the newer type will persist.
+- Where both values are objects the merge will descend into the object.
+- Where both values are arrays the merge will replace the old array entirely.
+
+The merge is relatively simple and is expected to be used to build up
+from base themes to custom themes where there are few conflicts and
+simple direct replacements are desired.
+
+### Constants {#constants}
+
+The merge behaviour when a file has constants and includes is
+
+1. Constants are loaded first
+2. Includes file list is merged in order
+3. All other (non constant) data is merged
+
+The include merge is recursive, so step (2) above will cause the
+constants in the first included file to be merged first.
+
+## Constants {#constantdetail}
+
+The constants section supports sub-string and full property replacement.
+
+~~~
+ {
+ "constants": // Constant replacement section
+ { //
+ "IMAGES": "/usr/share/images/", // Constants can be set here or in code.
+ "SIZE": [100,100,1] //
+ }, //
+ ... //
+ { //
+ "type":"ImageActor" // An Dali type or a template name
+ "image": //
+ { //
+ "filename":"{IMAGES}b.jpg" // Image filename substring replacement
+ }, //
+ "size": "{SIZE}" //
+ } // Property replacement
+ } //
+~~~
+
+The type of the constant should match the expected type of the property.
+
+A property constant cannot be used for sub string replacement; a string
+constant should be used.
+
+With a property replacement, the replace site must contain a string
+where the first and last positions are braces.
+
+## Templates {#templates}
+
+The template section supports the creation of actor instances. The
+template name can be used in code to create an actor tree.
+
+~~~{.js}
+// JavaScript
+
+var builder = new dali.Builder();
+builder.loadFromFile( "my-app.json");
+var userActorTree = builder.create( { template:"basic-text"} );
+~~~
+
+~~~{.cpp}
+// C++
+
+Builder builder = Builder::New();
+std::string jsonData = loadFile("my-app.json");
+builder.LoadFromString( jsonData );
+
+actorTree = builder.Create("basic-text");
+~~~
+
+Templates consist of a name, multiple property-value configurations and
+an optional actor sub hierarchy.
+
+~~~{.json}
+ { //
+ "templates": // Template library section
+ { //
+ "basic-text": // The template name
+ { //
+ "type":"ImageActor", // Concrete Dali Type/Class to create
+ "styles":["base-style"], // Style list to apply
+ "name":"image", // }
+ "image": // } property name : value
+ { // }
+ "filename":"{IMAGES}/b.jpg" //
+ }, //
+ "parent-origin": "CENTER" //
+ ... //
+ "actors": // A tree of sub actors
+ [ //
+ { //
+ "type":"TextView" //
+ "name":"text", //
+ "text":"Hello World", //
+ "parent-origin": "CENTER", //
+ } //
+ ] //
+ } //
+ } //
+~~~
+
+A template has a special 'type' property which must contain a concrete
+Dali Actor or Control type name.
+
+A template has a special 'styles' property which contains a list of
+styles to apply when creating using the template.
+
+## Styles {#styles}
+
+The styles section supports a named set of properties that can be
+applied to an actor or actor tree.
+
+~~~{.cpp}
+// C++
+
+Builder.ApplyStyle("light-theme", myActor);
+~~~
+
+~~~{.js}
+// JavaScript
+
+builder.applyStyle("light-theme", myActor);
+~~~
+
+
+The styles can also be applied as an animation.
+
+~~~{.cpp}
+Builder.AnimateTo("light-theme", myActor, TimePeriod(0, 10));
+~~~
+
+
+
+~~~
+ { //
+ "styles": // Style set section
+ { //
+ "light-theme": // Style-set name
+ { //
+ "color":[1,1,1,1] // }
+ "position":[0,-120,0], // } properties to set on the given actor
+ "rotation":[0,0,30], // }
+ "actors": //
+ { // Sub Actors are referenced by name
+ "title-text": // Actor name to search for under given actor
+ { //
+ "color":[1,1,1,1] // }
+ "position":[0,-120,0], // } properties to set if 'title-text' is found
+ "rotation":[0,0,30], // }
+ }
+ }, //
+ "icon": //
+ { //
+ "color":[1,1,1,1] //
+ } //
+ }, //
+ "dark-theme": //
+ { //
+ } //
+ } //
+~~~
+
+When applied to an actor tree the actors are referenced by name. Names
+are not unique in Dali.
+
+When a style is applied in code Dali will perform a depth first search
+stopping with the first matching name.
+
+Typically an application developer will apply the style to the template
+root actor and not the stage root actor. Therefore in most uses cases
+name conflicts are not expected.
+
+## Animations {#animations}
+
+The animation section defines a library of animation definitions.
+
+The animations can be created by name from code.
+
+They can also be created automatically from JSON in an actor signal.
+
+~~~
+ { //
+ "animations": // Animation library
+ { //
+ "rotate": // An Animation named rotate
+ { //
+ "duration": 10, // Duration in seconds
+ "loop": false, // Whether to loop.
+ "end-action": "Bake", // Whether to set final value(bake) or
+ // reset
+ "disconnect-aciton": "Discard", // Whether 'Bake' or 'Discard' when disconnected
+ "properties":
+ [
+ // Properties changed in this animation
+ {
+ "actor":"image", // Actor found by name from the stage
+ "property":"rotation", // Property to change
+ "value":[0, 0.1, 0, 0], // Value to set
+ "alpha-function": "EASE\_IN\_OUT", // Interpolation function
+ //
+ "time-period": // Time period for change
+ {"delay": 0,
+ "duration": 3
+ }
+ },
+ ... // 1 or more property changes per animation
+ }, //
+ ... //
+ }, //
+~~~
+
+### Splines {#splines}
+
+An animation property can be defined with a path and forward direction
+instead of a single final value.
+
+Paths are defined in a top level path section and referenced by the
+animation property.
+
+~~~
+ { //
+ "paths": // Path library
+ { //
+ "path0": // Path definition by name
+ { //
+ "points":[ // points
+ [-150, -50, 0],
+ [0.0,70.0,0.0],
+ [190.0,-150.0,0.0]
+ ],
+ // curvature automatically creates
+ "curvature":0.35, // control-points
+ //
+ "control-points": [...] // Otherwise control-points can be
+ // directly specified.
+ } //
+ }, //
+ "animations": //
+ { //
+ "path-animation":
+ {
+ "duration": 3.0,
+ "properties":
+ [
+ {
+ "actor": "greeting2",
+ // Path is mandatory for spline
+ "path":"path0", // animation.
+ "forward":[1,0,0], // Forward vector specifies orientation
+ // whilst travelling along the path
+ "alpha-function": "EASE\_IN\_OUT", // (optional)
+ "time-period":
+ {
+ "delay": 0,
+ "duration": 3
+ }
+ },
+ ...
+ // Other properties changes can use
+ ] // paths or values in the same
+ // animation.
+ }, //
+ } //
+~~~
+
+## Shaders {#shaders}
+
+The shader section of the JSON file defines a library of shader effect
+instances that are created on demand.
+
+The shaders are referred to by name from the template, style, stage or
+animation sections.
+
+Multiple actors can set the same shader as the name refers to a single
+instance.
+
+Similarly one named shader instance can be set to several actors and can
+be animated by one animation.
+
+~~~
+ { //
+ "shader-effects": // Shader Effect section
+ { //
+ "myshader1": // Shader instance name
+ { //
+ "program": //
+ { // Prefixs are placed before DALi uniforms.
+ "vertexPrefix": "", // (Useful for \#defines.)
+ "vertex":"", // Glsl vertex program
+ "fragmentPrefix": "",
+ "fragment": "", // Glsl fragment program.
+ "geometry-type": "GEOMETRY_TYPE_IMAGE", // Geometry type(see DALi documentation)
+ },
+ "geometry-hints": "HINT_NONE": // Geometry hints (see DALi documentation)
+ "grid-density": 0, // Grid density(see DALi documentation)
+ "image":
+ {
+ "filename": "" // Effect image available as a second texture unit.
+ }
+ },
+ ...
+ },
+ "stage":
+ [{
+ "type": "ImageActor",
+ "effect": "myshader1",
+ ...
+ }]
+ }
+~~~
+
+At least one of the vertex or fragment fields is mandatory. All
+other fields are optional will use internal defaults.
+
+Actors have an "effect" field that refers to the shader effect
+instance to use with that actor.
+
+### Animating shaders {#animatingshaders}
+
+Shader uniforms can be animated as if they are properties of the actor.
+
+When the animation is created from code (or from a signal) the property
+name search begins on the actor, if it isn't found the search continues
+on the attached shader object.
+
+The actor property names and shader uniform names must not clash for the
+uniform to animate correctly. The convention in DALi is to prepend
+uniforms with 'u'.
+
+~~~
+ { \\
+ "animations": \\ Animation library
+ { \\
+ "rotate": \\ An Animation named rotate
+ { \\
+ "duration": 10, \\
+ "properties": \\ Properties changed in this animation
+ [ \\
+ {
+ "actor":"image", \\ Actor found by name from the stage
+ "property":"uTranslate", \\ Uniform name specified as if it is a
+ \\ property of the object.
+ "value":[10, 20],
+ ...
+ },
+ ...
+ ]
+ },
+ "shader-effects":
+ {
+ "myshader1":
+ {
+ \\ Shader program with uniform
+ "program": {...} \\ "uTranslate"
+ }
+ },
+ "actors":
+ [
+ {
+ "name": "image",
+ "effect": "myshader1" \\ Actor using shader effect instance
+ \\ "myshader1"
+ }
+ ]
+ },
+~~~
+
+## Stage {#stage}
+
+The stage section supports the immediate creation of actors at the time
+the JSON is loaded.
+
+The stage is a tree of actors that can be added to Dali's stage object.
+
+~~~
+// C++
+builder = Dali.Builder();
+json_text = load("layout.json");
+builder.Load(json\_text);
+stage = Dali.Stage.GetCurrent();
+builder.AddActors( stage.GetRootLayer()); // Add actors to the stage root layer
+~~~
+
+~~~{.js}
+// JavaScript
+
+builder.addActors( dali.stage.getRootLayer() );
+~~~
+
+~~~
+ { \\
+ "stage": \\ Stage Section Number
+ [ \\ An array of actors
+ {
+ "type": "ImageActor",
+ ...
+ "actors": \\ Each actor can have children
+ \\ creating a tree
+ [
+ {
+ "type": "TextView",
+ \\ The Type to create; this can be a
+ ... \\ concrete Dali type (actor/control)
+ \\ or a template name.
+ "styles": ["base-style"]
+ \\ A list of styles to apply to the
+ } \\ created type.
+ ]
+ }
+ ]
+ }
+~~~
+
+# Actor and Control Properties {#actorprop}
+
+Each control has a set of supported properties documented in the "Dali
+UI Control Specification".
+
+Please refer to the above document for further information about specific
+controls.
+
+@class _Guide_JSON_Specification
+*/
#### JavaScript example
~~~{.js}
-builder.applyStyle = builder.create( "live-tv-focus", tvIcon );
+builder.applyStyle( "live-tv-focus", tvIcon );
~~~
#### C++ example
#### JavaScript example
~~~{.js}
+// JavaScript
+
var anim = builder.createAnimation( { animation:"animate-show", actor: myActor } );
~~~
-#### C++ example
-
~~~{.cpp}
+// C+++
+
Animation anim = builder.createAnimation( "animate-show", propertyMap );
~~~
--- /dev/null
+/**
+ *
+
+# Text Label {#text-label}
+
+## Overview
+
+The Dali::Toolkit::TextLabel is a Dali::Toolkit::Control which renders a short text string.
+Text labels are lightweight, non-editable and do not respond to user input.
+
+### Basic usage
+
+To display a TextLabel the TEXT property must be set using a UTF-8 string.
+
+~~~{.cpp}
+// C++
+
+TextLabel label = TextLabel::New();
+label.SetProperty( TextLabel::Property::TEXT, "Hello World" );
+label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
+Stage::GetCurrent().Add( label );
+~~~
+
+~~~{.js}
+// JavaScript
+
+var label = new dali.TextLabel();
+
+label.text = "Hello World";
+label.anchorPoint = dali.TOP_LEFT;
+
+dali.stage.add( label );
+~~~
+
+The label must also be added to the stage, or to an actor which is on the stage.
+The position of the label on-screen is dependent on the parent-origin and anchor-point properties.
+
+| | |
+|--|--|
+| (ParentOrigin::TOP_LEFT, AnchorPoint::TOP_LEFT) |   |
+
+### Font Selection
+
+By default TextLabel will automatically select a suitable font from the platform.
+Typically fonts do not support all scripts, for example Latin fonts often do not provide Arabic glyphs.
+Therefore you should expect TextLabel to select different fonts for each script.
+
+Alternatively a font may be requested using either or all of FONT_FAMILY, FONT_STYLE, and POINT_SIZE properties:
+
+~~~{.cpp}
+// C++
+
+label.SetProperty( TextLabel::Property::FONT_FAMILY, "HelveticaNue" );
+label.SetProperty( TextLabel::Property::FONT_STYLE, "Regular" );
+label.SetProperty( TextLabel::Property::POINT_SIZE, 12.0f );
+~~~
+
+~~~{.js}
+// JavaScript
+
+label.fontFamily = "HelveticaNue";
+label.fontStyle = "Regular";
+label.pointSize = 12;
+~~~
+
+However the TextLabel will fall-back to using the default font, if the requested font does not support the required scripts.
+
+### Font Styles
+
+Setting a font size programmatically is not ideal for applications which support multiple screen resolutions etc.
+A more flexible approach is to prepare various JSON stylesheets, and request a different style for each platform:
+
+~~~{.cpp}
+// C++
+StyleManager styleManager = StyleManager::Get();
+styleManager.RequestThemeChange( "example-path/example.json" );
+~~~
+
+To change the font for standard text labels, this JSON syntax can be used:
+
+~~~{.json}
+{
+ "styles":
+ {
+ "textlabel":
+ {
+ "font-family":"Arial",
+ "font-style":"Regular",
+ "point-size":8
+ }
+ }
+}
+~~~
+
+However the same point-size is unlikely to be suitable for all labels in an application.
+To set custom sizes simply set a "style name" for each case, and then provide a style override in JSON:
+
+~~~{.cpp}
+ // C++
+
+ label.SetProperty( Control::Property::STYLE_NAME, "custom" );
+~~~
+~~~{.js}
+ // JavaScript
+
+ label.styleName = "custom"';
+~~~
+
+~~~{.json}
+{
+ "styles":
+ {
+ "textlabel":
+ {
+ "font-family":"Arial",
+ "font-style":"Regular",
+ "point-size":8
+ },
+
+ "custom":
+ {
+ "point-size":10
+ }
+ }
+}
+~~~
+
+In the example above, standard text labels will have point-size 8, and "custom" labels will have point-size 10.
+
+### Text Alignment
+
+Wrapping can be enabled using the MULTI_LINE property:
+
+~~~{.cpp}
+// C++
+
+label.SetProperty( TextLabel::Property::MULTI_LINE, true );
+~~~
+
+~~~{.js}
+// JavaScript
+
+label.mutliLine = true;
+~~~
+
+The text can be either aligned horizontally to the beginning, end, or center of the available area:
+
+~~~{.cpp}
+// C++
+
+label.SetProperty( TextLabel::Property::HORIZONTAL_ALIGNMENT, "BEGIN" ); // "CENTER" or "END"
+~~~
+
+~~~{.js}
+// JavaScript
+
+label.HorizontalAlignment = "BEGIN"; // "CENTER" or "END"
+~~~
+
+| | |
+|--|--|
+| Here is the "BEGIN" alignment shown for left-to-right (Latin) | right-to-left (Arabic) scripts |
+|   |   |
+| Here is the "CENTER" alignment shown for left-to-right (Latin) | right-to-left (Arabic) scripts:|
+|   |   |
+| Here is the "END" alignment shown for left-to-right (Latin) | right-to-left (Arabic) scripts:|
+|   |   |
+
+
+The examples above assume that the TextLabel size greater than the minimum required.
+The next section provides details about the other size related options.
+
+## Negotiating size
+
+\link size-negotiation Size negotiation \endlink is a layouting feature supported by UI controls such as TextLabel.
+
+There are several resize policies which are commonly used with TextLabels.
+
+The following examples show TextLabels actual size by setting a colored background, whilst the black area represents the size of the parent control:
+
+### Using natural size
+
+With a "natural" size TextLabel will be large enough to display the text without wrapping, and will not have extra space to align the text within.
+Therefore in this example the same result would be displayed, regardless of the alignment or multi-line properties.
+
+~~~{.cpp}
+// C++
+
+TextLabel label = TextLabel::New( "Hello World" );
+label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
+label.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::ALL_DIMENSIONS );
+label.SetBackgroundColor( Color::BLUE );
+Stage::GetCurrent().Add( label );
+~~~
+
+~~~{.js}
+// JavaScript
+
+var label = new dali.Textlabel;
+label.text = "Hello World";
+label.anchorPoint = dali.TOP_LEFT;
+
+label.widthResizePolicy = "USE_NATURAL_SIZE";
+label.heightResizePolicy = "USE_NATURAL_SIZE";
+
+label.textColor = dali.COLOR_WHITE;
+// background color not available as it's currently not a property of control
+dali.stage.add( label );
+~~~
+
+
+ 
+ 
+
+
+### Height-for-width negotiation
+
+To layout text labels vertically, a fixed (maximum) width should be provided by the parent control.
+Each TextLabel will then report a desired height for the given width.
+Here is an example of this behavior using TableView as the parent:
+
+~~~{.cpp}
+// C++
+TableView parent = TableView::New( 3, 1 );
+parent.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
+parent.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::HEIGHT );
+parent.SetAnchorPoint( AnchorPoint::TOP_LEFT );
+Stage::GetCurrent().Add( parent );
+
+TextLabel label = TextLabel::New( "Hello World" );
+label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
+label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
+label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
+label.SetBackgroundColor( Color::BLUE );
+parent.AddChild( label, TableView::CellPosition( 0, 0 ) );
+parent.SetFitHeight( 0 );
+
+label = TextLabel::New( "A Quick Brown Fox Jumps Over The Lazy Dog" );
+label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
+label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
+label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
+label.SetBackgroundColor( Color::GREEN );
+label.SetProperty( TextLabel::Property::MULTI_LINE, true );
+parent.AddChild( label, TableView::CellPosition( 1, 0 ) );
+parent.SetFitHeight( 1 );
+
+label = TextLabel::New( "لإعادة ترتيب الشاشات، يجب تغيير نوع العرض إلى شبكة قابلة للتخصيص." );
+label.SetAnchorPoint( AnchorPoint::TOP_LEFT );
+label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
+label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT );
+label.SetBackgroundColor( Color::BLUE );
+label.SetProperty( TextLabel::Property::MULTI_LINE, true );
+parent.AddChild( label, TableView::CellPosition( 2, 0 ) );
+parent.SetFitHeight( 2 );
+~~~
+
+ 
+ 
+
+
+Note that the "Hello World" text label (above) has been given the full width, not the natural width.
+
+### TextLabel Decorations
+
+#### Color
+
+To change the color of the text, the recommended way is to use the TEXT_COLOR property.
+Note that unlike the Actor::COLOR property, this will not affect child Actors added to the TextLabel.
+
+~~~{.cpp}
+// C++
+label.SetProperty( TextLabel::Property::TEXT, "Red Text" );
+label.SetProperty( TextLabel::Property::TEXT_COLOR, Color::RED );
+~~~
+
+~~~{.js}
+// JavaScript
+
+label.text = "Red Text";
+label.textColor = dali.COLOR_RED;
+~~~
+
+ 
+ 
+
+#### Drop Shadow
+
+To add a drop-shadow to the text, simply set the SHADOW_OFFSET property with non-zero values.
+The color can also be selected using the SHADOW_COLOR property.
+
+~~~{.cpp}
+ // C++
+
+stage.SetBackgroundColor( Color::BLUE );
+
+label1.SetProperty( TextLabel::Property::TEXT, "Plain Text" );
+
+label2.SetProperty( TextLabel::Property::TEXT, "Text with Shadow" );
+label2.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 1.0f, 1.0f ) );
+label2.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::BLACK );
+
+label3.SetProperty( TextLabel::Property::TEXT, "Text with Bigger Shadow" );
+label3.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 2.0f, 2.0f ) );
+label3.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::BLACK );
+
+label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Shadow" );
+label4.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 1.0f, 1.0f ) );
+label4.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::RED );
+~~~
+
+~~~{.js}
+// JavaScript
+
+dali.stage.setBackgroundColor( dali.COLOR_BLUE );
+
+label1.text = "Plain Text";
+
+
+label2.text = "Text with Shadow";
+label2.shadowOffset = [1, 1];
+label2.shadowColor = dali.COLOR_BLACK;
+
+label3.text = "Text with Bigger Shadow";
+label3.shadowOffset = [2, 2];
+label3.shadowColor = dali.COLOR_BLACK;
+
+label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Shadow" );
+label3.shadowOffset = [1, 1];
+label3.shadowColor = dali.COLOR_RED;
+~~~
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+#### Underline
+
+The text can be underlined by setting UNDERLINE_ENABLED.
+The color can also be selected using the UNDERLINE_COLOR property.
+
+~~~{.cpp}
+// C++
+label1.SetProperty( TextLabel::Property::TEXT, "Text with Underline" );
+label1.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
+
+label2.SetProperty( TextLabel::Property::TEXT, "Text with Color Underline" );
+label2.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true );
+label2.SetProperty( TextLabel::Property::UNDERLINE_COLOR, Color::GREEN );
+~~~
+~~~{.js}
+// JavaScript
+label1.Text = "Text with Underline";
+label1.underlineEnabled = true;
+
+label2.Text = "Text with Color Underline";
+label2.underlineEnabled = true;
+label2.underlineColor = dali.COLOR_GREEN;
+~~~
+
+
+
+
+
+
+
+
+
+By default the underline height will be taken from the font metrics, however this can be overridden using the UNDERLINE_HEIGHT property:
+
+~~~{.cpp}
+// C++
+
+label1.SetProperty( TextLabel::Property::UNDERLINE_HEIGHT, 1.0f );
+~~~
+
+~~~{.js}
+// JavaScript
+
+label1.underlineHeight = 1;
+~~~
+
+
+
+
+### Text Label Properties
+
+ Name (JavaScript) | Name (C++) | Type | Writable | Animatable
+---------------------|---------------------|--------------|--------------|-----------
+ renderingBackend | RENDERING_BACKEND | INTEGER | ✔ | ✘
+ text | TEXT | STRING | ✔ | ✘
+ fontFamily | FONT_FAMILY | STRING | ✔ | ✘
+ fontStyle | FONT_STYLE | STRING | ✔ | ✘
+ pointSize | POINT_SIZE | FLOAT | ✔ | ✘
+ multiLine | MULTI_LINE | BOOLEAN | ✔ | ✘
+ horizontalAlignment | HORIZONTAL_ALIGNMENT| STRING | ✔ | ✘
+ verticalAlignment | VERTICAL_ALIGNMENT | STRING | ✔ | ✘
+ textColor | TEXT_COLOR | VECTOR4 | ✔ | ✘
+ shadowOffset | SHADOW_OFFSET | VECTOR2 | ✔ | ✘
+ shadowColor | SHADOW_COLOR | VECTOR4 | ✔ | ✘
+ underlineEnabled | UNDERLINE_ENABLED | BOOLEAN | ✔ | ✘
+ underlineColor | UNDERLINE_COLOR | VECTOR4 | ✔ | ✘
+ underlineHeight | UNDERLINE_HEIGHT | FLOAT | ✔ | ✘
+
+
+
+@class TextLabel
+
+*/
## Atlas creation tips
-- Compress the atlas - \link Texture_Compression Compressing Textures \endlink
+- Compress the atlas - \link texturecompression Compressing Textures \endlink
- Avoid adding large images to the Atlas.
- E.g. don't add background images to it. Medium to large images should be kept seperate.
+++ /dev/null
-/**
-## Text Actor API
-TextActor is a basic actor for displaying a text label
-
-By default the text actor always uses the natural size of the text, when the text property is set,
-unless SetSize is called to override the size or size is animated to some other size.
-
-Natural size for TextActor is the same as the size returned by dali.font.MeasureText( string )
-using the font that the TextActor is using.
-
-By default {{#crossLink "RenderableActor/setCullFace:method"}}CullFaceMode{{/crossLink}} is set to CullNone to enable the TextActor to be viewed from all angles.
-
-### Simple example
-```
-var textActor = new dali.TextActor( "Hello world" );
-
-// by default an actor is anchored to the top-left of it's parent actor
-// change it to the middle
-textActor.parentOrigin = [0.5,0.5,0.5];
-
-// scale it up by 4 times in x,y
-textActor.scale = [ 4, 4, 1 ];
-
-// add to the stage
-dali.stage.add( textActor );
-```
-
-### Example using a font and text options ###
-```
-var fontInfo =
-{
- family : "Arial",
- style :"Bold",
- pointSize:20
-}
-
-var arialFont = new dali.Font( fontInfo );
-var textOptions =
-{
- font: arialFont,
- isRightToLeft: true,
- fontDetection: true // default is true
-}
-
-var textActor1 = new dali.TextActor( "Hello-world" , textOptions );
-
-// this will automatically chose a different font that can display the text
-var textActor2 = new dali.TextActor( "繁體中文" , textOptions );
-```
-
-| Name | Type | Writable | Animatable|
-|------------------------|------------|--------------|-----------|
-| text | STRING | ✔ |✘ |
-| font | STRING | ✔ |✘ |
-| font-style | STRING | ✔ |✘ |
-| outline-enable | BOOLEAN | ✔ |✘ |
-| outline-color | VECTOR4 | ✔ |✘ |
-| outline-thickness-width| VECTOR2 | ✔ |✘ |
-| smooth-edge | FLOAT | ✔ |✘ |
-| glow-enable | BOOLEAN | ✔ |✘ |
-| glow-color | VECTOR4 | ✔ |✘ |
-| glow-intensity | FLOAT | ✔ |✘ |
-| shadow-enable | BOOLEAN | ✔ |✘ |
-| shadow-color | VECTOR4 | ✔ |✘ |
-| shadow-offset | VECTOR2 | ✔ |✘ |
-| italics-angle | FLOAT | ✔ |✘ |
-| underline | BOOLEAN | ✔ |✘ |
-| weight | INTEGER | ✔ |✘ |
-| font-detection-automati| BOOLEAN | ✔ |✘ |
-| gradient-color | VECTOR4 | ✔ |✘ |
-| gradient-start-point | VECTOR2 | ✔ |✘ |
-| gradient-end-point | VECTOR2 | ✔ |✘ |
-| shadow-size | FLOAT | ✔ |✘ |
-| text-color | VECTOR4 | ✔ |✘ |
-
-@class TextActor
-@extends RenderableActor
- */
-
projects / platform / core / uifw / dali-toolkit.git / commitdiff
