projects / platform / core / uifw / dali-toolkit.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Merge "If the height is small even if scrolling is enabled, it should be elide."...
[platform/core/uifw/dali-toolkit.git] / docs / content / shared-javascript-and-cpp-documentation / text-label.md
diff --git a/docs/content/shared-javascript-and-cpp-documentation/text-label.md b/docs/content/shared-javascript-and-cpp-documentation/text-label.md
old mode 100644 (file)
new mode 100755 (executable)
index 908fedd..8b9d4d6
--- a/docs/content/shared-javascript-and-cpp-documentation/text-label.md
+++ b/docs/content/shared-javascript-and-cpp-documentation/text-label.md
@@ -1,5 +1,5 @@
-/**
- *
+<!--
+/**-->
 
 # Text Label {#text-label}
 
 
 # Text Label {#text-label}
 
@@ -12,6 +12,8 @@ Text labels are lightweight, non-editable and do not respond to user input.
 
 To display a TextLabel the TEXT property must be set using a UTF-8 string.
 
 
 To display a TextLabel the TEXT property must be set using a UTF-8 string.
 
+Note *CR+LF* new line characters are replaced by a *LF* one.
+
 ~~~{.cpp}
 // C++
 
 ~~~{.cpp}
 // C++
 
@@ -33,7 +35,7 @@ dali.stage.add( label );
 ~~~
 
 The label must also be added to the stage, or to an actor which is on the stage.  
 ~~~
 
 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.  
+The position of the label on-screen is dependent on the parentOrigin and anchorPoint properties.  
 
 |  |  |
 |--|--|
 
 |  |  |
 |--|--|
@@ -41,91 +43,11 @@ The position of the label on-screen is dependent on the parent-origin and anchor
 
 ### Font Selection
 
 
 ### 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++
+By default TextLabel will automatically select a suitable font from the platform. However, a different font could be selected. See the [Font Selection](@ref font-selection) section for more details.
 
 
-label.SetProperty( TextLabel::Property::FONT_FAMILY, "HelveticaNue" );
-label.SetProperty( TextLabel::Property::FONT_STYLE,  "Regular" );
-label.SetProperty( TextLabel::Property::POINT_SIZE,  12.0f );
-~~~
+### Mark-up Style
 
 
-~~~{.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.  
+Mark-up tags can be used to change the style of the text. See the [Mark-up Style](@ref markup-style) section for more details.
 
 ### Text Alignment
 
 
 ### Text Alignment
 
@@ -167,6 +89,41 @@ label.HorizontalAlignment = "BEGIN"; // "CENTER" or "END"
 | ![ ](../assets/img/text-controls/LatinEnd.png) ![ ](LatinEnd.png) | ![ ](../assets/img/text-controls/ArabicEnd.png) ![ ](ArabicEnd.png) |
 
 
 | ![ ](../assets/img/text-controls/LatinEnd.png) ![ ](LatinEnd.png) | ![ ](../assets/img/text-controls/ArabicEnd.png) ![ ](ArabicEnd.png) |
 
 
+
+The text's alignment and order can be modified to match the direction of the system language.
+
+If the MATCH_SYSTEM_LANGUAGE_DIRECTION property is set to true then the direction of the text is ignored, instead the text is aligned and ordered as the system default language.
+
+~~~{.cpp}
+// C++
+
+label.SetProperty( Toolkit::DevelTextLabel::Property::MATCH_SYSTEM_LANGUAGE_DIRECTION, true );
+~~~
+
+~~~{.js}
+// JavaScript
+
+label.matchSystemLanguageDirection = true;
+~~~
+
+|  |  |
+|--|--|
+| Current system language direction left-to-right | |
+| MATCH_SYSTEM_LANGUAGE_DIRECTION set to TRUE. | MATCH_SYSTEM_LANGUAGE_DIRECTION set to FALSE (default). |
+| BEGIN alignment | BEGIN alignment  |
+| ![ ](../assets/img/text-controls/HelloWorld-System-BEGIN.png) ![ ](HelloWorld-System-BEGIN.png) | ![ ](../assets/img/text-controls/HelloWorld-Default-BEGIN.png) ![ ](HelloWorld-Default-BEGIN.png) |
+| CENTER alignment | CENTER alignment  |
+| ![ ](../assets/img/text-controls/HelloWorld-System-CENTER.png) ![ ](HelloWorld-System-CENTER.png) | ![ ](../assets/img/text-controls/HelloWorld-Default-CENTER.png) ![ ](HelloWorld-Default-CENTER.png) |
+| END alignment | END alignment  |
+| ![ ](../assets/img/text-controls/HelloWorld-System-END.png) ![ ](HelloWorld-System-END.png) | ![ ](../assets/img/text-controls/HelloWorld-Default-END.png) ![ ](HelloWorld-Default-END.png) |
+
+
+|  |  |
+|--|--|
+| Current system language direction left-to-right | Current system language direction right-to-left |
+| ![ ](../assets/img/text-controls/LTR_order.png) ![ ](LTR_order.png)  | ![ ](../assets/img/text-controls/RTL_order.png) ![ ](RTL_order.png) |
+
+
 The examples above assume that the TextLabel size greater than the minimum required.  
 The next section provides details about the other size related options.
 
 The examples above assume that the TextLabel size greater than the minimum required.  
 The next section provides details about the other size related options.
 
@@ -285,8 +242,7 @@ label.textColor = dali.COLOR_RED;
 
 #### Drop Shadow
 
 
 #### 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.  
+To add a drop-shadow to the text, simply set the SHADOW property. Shadow parameters can be set through a json string or through a property map, see the examples below.
 
 ~~~{.cpp}
  // C++
 
 ~~~{.cpp}
  // C++
@@ -296,16 +252,19 @@ stage.SetBackgroundColor( Color::BLUE );
 label1.SetProperty( TextLabel::Property::TEXT, "Plain Text" );
 
 label2.SetProperty( TextLabel::Property::TEXT, "Text with Shadow" );
 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 );
+label2.SetProperty( TextLabel::Property::SHADOW, "{\"offset\":\"1 1\",\"color\":\"black\"}" );
 
 label3.SetProperty( TextLabel::Property::TEXT, "Text with Bigger Shadow" );
 
 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 );
+label3.SetProperty( TextLabel::Property::SHADOW, "{\"offset\":\"2 2\",\"color\":\"black\"}" );
+
+label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Soft Shadow" );
+
+Property::Map shadow;
+shadow.Insert( "offset", Vector2(1.0f, 1.0f) );
+shadow.Insert( "color", Color::RED );
+shadow.Insert( "blurRadius", 2.0f ); // A value of 0 indicates no blur. The bigger the radius, the more blurry.
+label4.SetProperty( TextLabel::Property::SHADOW, shadow );
 
 
-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}
 ~~~
 
 ~~~{.js}
@@ -317,16 +276,19 @@ label1.text = "Plain Text";
 
 
 label2.text = "Text with Shadow";
 
 
 label2.text = "Text with Shadow";
-label2.shadowOffset = [1, 1];
-label2.shadowColor = dali.COLOR_BLACK;
+label2.shadow = "{\"offset\":\"1 1\",\"color\":\"black\"}";
 
 label3.text = "Text with Bigger Shadow";
 
 label3.text = "Text with Bigger Shadow";
-label3.shadowOffset = [2, 2];
-label3.shadowColor = dali.COLOR_BLACK;
+label3.shadow = "{\"offset\":\"2 2\",\"color\":\"black\"}";
+
+label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Soft Shadow" );
+var shadow = {
+    "offset" : [ 1.0, 1.0 ],
+    "color" : dali.COLOR_RED;
+    "blurRadius" : 2.0
+};
+label4.shadow = shadow;
 
 
-label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Shadow" );
-label3.shadowOffset = [1, 1];
-label3.shadowColor = dali.COLOR_RED;
 ~~~
 
 
 ~~~
 
 
@@ -394,26 +356,16 @@ label1.underlineHeight = 1;
 ![ ](../assets/img/text-controls/TextWith1pxUnderline.png)
 ![ ](TextWith1pxUnderline.png)
 
 ![ ](../assets/img/text-controls/TextWith1pxUnderline.png)
 ![ ](TextWith1pxUnderline.png)
 
-### Text Label Properties
+### Auto Scrolling
+
+![ ](../assets/img/text-controls/AutoScroll.gif)
+![ ](AutoScroll.gif)
 
 
- Name (JavaScript)   |  Name (C++)         |  Type        | Writable     | Animatable
----------------------|---------------------|--------------|--------------|-----------
- renderingBackend    | RENDERING_BACKEND   |  INTEGER     | &#10004;     | &#10008;
- text                | TEXT                |  STRING      | &#10004;     | &#10008;
- fontFamily          | FONT_FAMILY         |  STRING      | &#10004;     | &#10008;
- fontStyle           | FONT_STYLE          |  STRING      | &#10004;     | &#10008;
- pointSize           | POINT_SIZE          |  FLOAT       | &#10004;     | &#10008;
- multiLine           | MULTI_LINE          |  BOOLEAN     | &#10004;     | &#10008;
- horizontalAlignment | HORIZONTAL_ALIGNMENT|  STRING      | &#10004;     | &#10008;
- verticalAlignment   | VERTICAL_ALIGNMENT  |  STRING      | &#10004;     | &#10008;
- textColor           | TEXT_COLOR          |  VECTOR4     | &#10004;     | &#10008;
- shadowOffset        | SHADOW_OFFSET       |  VECTOR2     | &#10004;     | &#10008;
- shadowColor         | SHADOW_COLOR        |  VECTOR4     | &#10004;     | &#10008;
- underlineEnabled    | UNDERLINE_ENABLED   |  BOOLEAN     | &#10004;     | &#10008;
- underlineColor      | UNDERLINE_COLOR     |  VECTOR4     | &#10004;     | &#10008;
- underlineHeight     | UNDERLINE_HEIGHT    |  FLOAT       | &#10004;     | &#10008;
+The \link text-auto-scrolling Auto text scrolling \endlink section details how to scroll text automatically.
 
 
+### Text Label Properties
 
 
+The properties used by TextLabel are listed [here](@ref TextLabelProperties)
 
 @class TextLabel
 
 
 @class TextLabel
 
Domain: Graphics System / DALi;