-/*! \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 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.
-\subsection basictextlabelusage Basic usage
+### Basic usage
To display a TextLabel the TEXT property must be set using a UTF-8 string.
-\code
+~~~{.cpp}
+// C++
+
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
+~~~
+
+~~~{.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:
-\code
+
+~~~{.cpp}
+// C++
+
label.SetProperty( TextLabel::Property::FONT_FAMILY, "HelveticaNue" );
label.SetProperty( TextLabel::Property::FONT_STYLE, "Regular" );
label.SetProperty( TextLabel::Property::POINT_SIZE, 12.0f );
-\endcode
+~~~
+
+~~~{.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.
-\subsection fontStyles Font Styles
+### 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
+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:
-\code
+~~~{.cpp}
+// C++
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
+~~~{.json}
{
"styles":
{
}
}
}
-\endcode
+~~~
-However the same point-size is unlikely to be suitable for all labels in an application.\n
+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:
-\code
+~~~{.cpp}
+ // C++
+
label.SetProperty( Control::Property::STYLE_NAME, "custom" );
-\endcode
+~~~
+~~~{.js}
+ // JavaScript
+
+ label.styleName = "custom"';
+~~~
-\code
+~~~{.json}
{
"styles":
{
}
}
}
-\endcode
+~~~
-In the example above, standard text labels will have point-size 8, and "custom" labels will have point-size 10.\n
+In the example above, standard text labels will have point-size 8, and "custom" labels will have point-size 10.
-\subsection textAlignment Text Alignment
+### Text Alignment
+
+Wrapping can be enabled using the MULTI_LINE property:
+
+~~~{.cpp}
+// C++
-Wrapping can be enabled using the MULTI_LINE property:\n
-\code
label.SetProperty( TextLabel::Property::MULTI_LINE, true );
-\endcode
+~~~
+
+~~~{.js}
+// JavaScript
+
+label.mutliLine = true;
+~~~
The text can be either aligned horizontally to the beginning, end, or center of the available area:
-\code
+
+~~~{.cpp}
+// C++
+
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
+~~~
+
+~~~{.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.
-\subsection negotiatingSize Negotiating size
+## 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:
-\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
+### Using natural size
-<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.
+Therefore in this example the same result would be displayed, regardless of the alignment or multi-line properties.
-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
+~~~{.cpp}
+// C++
-\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
+~~~
+
+~~~{.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 );
+~~~
+
+
+ 
+ 
-<table border=0 cellpadding=10>
-<tr>
- <td>
- \image html HelloWorld-NaturalSize.png
- </td>
-</tr>
-</table>
-<h3>Height-for-width negotiation</h3>
+### Height-for-width negotiation
-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
+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:
-\code
+~~~{.cpp}
+// C++
TableView parent = TableView::New( 3, 1 );
parent.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH );
parent.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::HEIGHT );
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
+### TextLabel Decorations
-<h3>Color</h3>
+#### Color
-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
+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.
-\code
+~~~{.cpp}
+// C++
label.SetProperty( TextLabel::Property::TEXT, "Red Text" );
label.SetProperty( TextLabel::Property::TEXT_COLOR, Color::RED );
-\endcode
+~~~
+
+~~~{.js}
+// JavaScript
+
+label.text = "Red Text";
+label.textColor = dali.COLOR_RED;
+~~~
-<table border=0 cellpadding=10>
-<tr>
- <td>
- \image html RedText.png
- </td>
-</tr>
-</table>
+ 
+ 
-<h3>Drop Shadow</h3>
+#### Drop Shadow
-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
+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++
-\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 );
+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 ) );
-label4.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::BLACK );
+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 );
-\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
+~~~
+
+~~~{.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 );
-\endcode
-
-<table border=0 cellpadding=10>
-<tr>
- <td>
- \image html TextWithUnderline.png
- </td>
-</tr>
-<tr>
- <td>
- \image html TextWithColorUnderline.png
- </td>
-</tr>
-</table>
+~~~
+~~~{.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:
-\code
+~~~{.cpp}
+// C++
+
label1.SetProperty( TextLabel::Property::UNDERLINE_HEIGHT, 1.0f );
-\endcode
-
-<table border=0 cellpadding=10>
-<tr>
- <td>
- \image html TextWith1pxUnderline.png
- </td>
-</tr>
-</table>
+~~~
+
+~~~{.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
*/
projects / platform / core / uifw / dali-toolkit.git / blobdiff