1 /*! \page markup-processor Markup processor
3 * <h1 class="pg">Overview</h1>
5 * Dali::Toolkit::MarkupProcessor functions provide mechanisms to build and modify a Dali::Toolkit::MarkupProcessor::StyledTextArray used to store text with style.
7 * <h1 class="pg">Build a styled text array from a markup string</h1>
9 * Dali::Toolkit::MarkupProcessor::GetStyledTextArray() could be used to convert an html-ish markup string into a styled text array. This string uses html-ish tags to
10 * define the text's style as follows:
13 * <li>\e \<b\>\</b\> Bold text.
14 * i.e. \<b\>Bold text\</b\>"
15 * \image html text-view/Bold.png
17 * <li>\e \<i\>\</i\> Italic text.
18 * i.e. \<i\>Italic text\</i\>"
19 * \image html text-view/Italic.png
21 * <li>\e \<u\>\</u\> Underlined text.
22 * i.e. \<u\>Underline text\</u\>"
23 * \image html text-view/Underline.png
25 * <li>\e \<br /\> New line.
27 * <li>\e \<font\>\</font\> Specifies font properties:
29 * <li> \e face The name of a font or font family.
30 * <li> \e style The style of a font.
31 * <li> \e size Font point size. @see Dali::PointSize.
32 * <li> \e color Font color. See the \ref color section for more details.
35 * i.e. \<font face='FreeSerif' style='Regular'\>FreeSerif font\</font\>
36 * \image html text-view/FreeSerifFont.png
38 * <li>\e \<shadow\>\</shadow\> Specifies shadow properties.
40 * <li> \e paramx X offset.
41 * <li> \e paramy Y offset.
42 * <li> \e color Shadow color. See the \ref color section for more details.
45 * i.e. \<shadow color='black' paramx='1.5' paramy='1.5'\>Black shadow\</shadow\>
46 * \image html text-view/Black-Shadow.png
48 * @see Dali::TextActor::SetShadow()
50 * <li>\e \<glow\>\</glow\> Specifies glow properties.
52 * <li> \e param Glow around the text.
53 * <li> \e color Glow color. See the \ref color section for more details.
56 * i.e. \<smooth param='0.65'\>\<glow color='blue' param='0.05'\>Blue glow\</glow\>\</smooth\>
57 * \image html text-view/Blue-Glow.png
59 * @see Dali::TextActor::SetGlow()
61 * <li>\e \<outline\>\</outline\> Specifies outline properties.
63 * <li> \e paramx X thickness.
64 * <li> \e paramy Y thickness.
65 * <li> \e color Outline color. See the \ref color section for more details.
68 * i.e. \<outline color='red' paramx='0.5' paramy='0.5'\>Red outline\</outline\>
69 * \image html text-view/Red-Outline.png
71 * @see Dali::TextActor::SetOutline()
73 * <li>\e \<smooth\>\</smooth\> Specify the smooth edge.
75 * <li> \e param Distance field.
78 * i.e. \<smooth param='0.3'\>Smooth text\</smooth\>
79 * \image html text-view/Smooth-Text.png
81 * @see Dali::TextActor::SetSmoothEdge()
84 * See also \ref color, \ref special_characters and \ref example for more details.
86 * <h1 class="pg">Get a markup string from a styled text array</h1>
88 * Dali::Toolkit::MarkupProcessor::GetMarkupString() could be used to convert a styled text array into an html-ish markup string.
90 * <h1 class="pg">Modify a styled text array</h1>
92 * Different functions are provided to modify whole or part of a styled text array with a given style. A mask could be used to modify only some properties of the style.
94 * @see Dali::Toolkit::MarkupProcessor::SetTextStyle( StyledTextArray& styledTextArray, const TextStyle& style, TextStyle::Mask mask )
95 * @see Dali::Toolkit::MarkupProcessor::SetTextStyle( const Text& text, StyledTextArray& styledTextArray, const TextStyle& style, TextStyle::Mask mask )
96 * @see Dali::Toolkit::MarkupProcessor::SetTextStyleToRange( StyledTextArray& styledTextArray, const TextStyle& style, TextStyle::Mask mask, std::size_t begin, std::size_t end )
98 * <h1 class="pg">Appendix</h1>
99 * \section color Color
101 * Different options could be used to define a color:
104 * <li> Hexadecimal with alpha channel. 0xAARRGGBB with the alpha channel in the most significant bits.
105 * <li> Hexadecimal without alpha channel. 0xRRGGBB.
106 * <li> Web color format (six or three digits). \#RRGGBB, \#RGB
107 * <li> Some colors could be defined with natural language: <em>black, white, red, green, blue, yellow, magenta, cyan</em> and \e transparent.
110 * \section special_characters Special characters
112 * \< and \> characters are used to build the html-ish tags. To type them is needed to add a back slash character in front of them.
113 * @note in c and c++ the back slash is represented with a double back slash '\\\\'.
115 * i.e. text.SetText("a \\< b \\< c");
116 * \image html text-view/AlessBlessC.png
118 * It transform any pair CR+LF new line characters into a single LF new line character.
120 * \section fonts Font Style, Weight and Smooth
122 * This appendix shows the differences and relations between the font style, the font weight, the smoothness and the italics.
124 * When a font is loaded, Dali uses different mechanisms to modify the render of glyphs.<br><br>
125 * i.e \<font face='Samsung Sans' size='24'\>Hello World\</font\> produces the "Hello World" bellow.
126 * \image html text-view/FontAppendix01.png
127 * By adding the \<i\> \<b\> \<smooth\> tags to the markup string or using the Dali::TextStyle::SetItalics(), Dali::TextStyle::SetWeight() or Dali::TextStyle::SetSmoothEdge() methods,
128 * Dali modifies how glyphs of the same font are rendered.<br><br>
129 * i.e \<i\>\<font face='Samsung Sans' size='24'\>Hello World\</font\>\</i\>
130 * \image html text-view/FontAppendix02.png
131 * i.e \<b\>\<font face='Samsung Sans' size='24'\>Hello World\</font\>\</b\>
132 * \image html text-view/FontAppendix03.png
134 * The smooth parameter can be used to adjust the thickness of the rendered glyphs.<br><br>
135 * i.e<br> \<smooth param=0.65\>\<font face='Samsung Sans' size='24'\>Hello World\</font\>\</smooth\>\<br /\><br>
136 * \<font face='Samsung Sans' size='24'\>Hello World\</font\>\<br /\><br>
137 * \<smooth param=0.4\>\<font face='Samsung Sans' size='24'\>Hello World\</font\>\</smooth\>\<br /\><br>
138 * \<b\>\<font face='Samsung Sans' size='24'\>Hello World\</font\>\</b\>\<br /\><br>
139 * \<smooth param=0.2\>\<font face='Samsung Sans' size='24'\>Hello World\</font\>\</smooth\>
141 * \image html text-view/FontAppendix04.png
143 * All "Hello World" above have been rendered using the same font, saving some memory. Alternatively, the platform can provide fonts with different styles.<br>
145 * i.e. Samsung platform provides among others:<br>
146 * Samsung Sans:style=Light<br>
147 * Samsung Sans:style=Regular<br>
148 * Samsung Sans:style=Medium<br>
150 * \<font face='Samsung Sans' style='Light' size='24'\>Hello World\</font\>\<br /\><br>
151 * \<font face='Samsung Sans' style='Regular' size='24'\>Hello World\</font\>\<br /\><br>
152 * \<font face='Samsung Sans' style='Medium' size='24'\>Hello World\</font\>
153 * \image html text-view/FontAppendix05.png
155 * The three "Hello World" above have been rendered with three different fonts.<br>
157 * The <i>fc-list</i> command can be executed on the platform command line to check with fonts and which styles are supported.
159 * \section example Example
162 * const std::string text( "<font size='16' color='black'>"
163 * "<i>Italics: 기울임 꼴</i><br/>"
164 * "<u>Underline: 밑줄</u><br/>"
165 * "<b>Bold: 두꺼운</b><br/>"
166 * "<font face='FreeSerif'>Font FreeSerif</font><br/>"
167 * "<font color='white'><shadow color='black' paramx='1.5' paramy='1.5'>Shadow: 그림자</shadow></font><br/>"
168 * "<font color='white'><smooth param='0.75'><glow color='blue' param='0.1'>Glow: 빛나다</glow></smooth></font><br/>"
169 * "<font color='white'><outline color='red' paramx='0.5' paramy='0.5'>Outline: 윤곽선</outline></font><br/>"
170 * "<smooth param='0.3'>Smooth: 부드럽게</smooth><br/>"
173 * Toolkit::MarkupProcessor::StyledTextArray styledText;
174 * Toolkit::MarkupProcessor::GetStyledTextArray( text, styledText, true );
176 * Toolkit::TextView textView = Toolkit::TextView::New( styledText );
177 * textView.SetParentOrigin( ParentOrigin::CENTER );
179 * Stage::GetCurrent().Add( textView );
182 * \image html text-view/text-view.png
183 * Text generated with the example above.