/*! \page markup-processor Markup processor
*
*
Overview
*
* Dali::Toolkit::MarkupProcessor functions provide mechanisms to build and modify a Dali::Toolkit::MarkupProcessor::StyledTextArray used to store text with style.
*
* Build a styled text array from a markup string
*
* 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
* define the text's style as follows:
*
*
* - \e \\ Bold text.
* i.e. \Bold text\"
* \image html text-view/Bold.png
*
*
- \e \\ Italic text.
* i.e. \Italic text\"
* \image html text-view/Italic.png
*
*
- \e \\ Underlined text.
* i.e. \Underline text\"
* \image html text-view/Underline.png
*
*
- \e \
New line.
*
* - \e \\ Specifies font properties:
*
* - \e face The name of a font or font family.
*
- \e style The style of a font.
*
- \e size Font point size. @see Dali::PointSize.
*
- \e color Font color. See the \ref color section for more details.
*
*
* i.e. \FreeSerif font\
* \image html text-view/FreeSerifFont.png
*
* - \e \\ Specifies shadow properties.
*
* - \e paramx X offset.
*
- \e paramy Y offset.
*
- \e color Shadow color. See the \ref color section for more details.
*
*
* i.e. \Black shadow\
* \image html text-view/Black-Shadow.png
*
* @see Dali::TextActor::SetShadow()
*
* - \e \\ Specifies glow properties.
*
* - \e param Glow around the text.
*
- \e color Glow color. See the \ref color section for more details.
*
*
* i.e. \\Blue glow\\
* \image html text-view/Blue-Glow.png
*
* @see Dali::TextActor::SetGlow()
*
* - \e \\ Specifies outline properties.
*
* - \e paramx X thickness.
*
- \e paramy Y thickness.
*
- \e color Outline color. See the \ref color section for more details.
*
*
* i.e. \Red outline\
* \image html text-view/Red-Outline.png
*
* @see Dali::TextActor::SetOutline()
*
* - \e \\ Specify the smooth edge.
*
* - \e param Distance field.
*
*
* i.e. \Smooth text\
* \image html text-view/Smooth-Text.png
*
* @see Dali::TextActor::SetSmoothEdge()
*
*
* See also \ref color, \ref special_characters and \ref example for more details.
*
* Get a markup string from a styled text array
*
* Dali::Toolkit::MarkupProcessor::GetMarkupString() could be used to convert a styled text array into an html-ish markup string.
*
* Modify a styled text array
*
* 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.
*
* @see Dali::Toolkit::MarkupProcessor::SetTextStyle( StyledTextArray& styledTextArray, const TextStyle& style, TextStyle::Mask mask )
* @see Dali::Toolkit::MarkupProcessor::SetTextStyle( const Text& text, StyledTextArray& styledTextArray, const TextStyle& style, TextStyle::Mask mask )
* @see Dali::Toolkit::MarkupProcessor::SetTextStyleToRange( StyledTextArray& styledTextArray, const TextStyle& style, TextStyle::Mask mask, std::size_t begin, std::size_t end )
*
* Appendix
* \section color Color
*
* Different options could be used to define a color:
*
*
* - Hexadecimal with alpha channel. 0xAARRGGBB with the alpha channel in the most significant bits.
*
- Hexadecimal without alpha channel. 0xRRGGBB.
*
- Web color format (six or three digits). \#RRGGBB, \#RGB
*
- Some colors could be defined with natural language: black, white, red, green, blue, yellow, magenta, cyan and \e transparent.
*
*
* \section special_characters Special characters
*
* \< 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.
* @note in c and c++ the back slash is represented with a double back slash '\\\\'.
*
* i.e. text.SetText("a \\< b \\< c");
* \image html text-view/AlessBlessC.png
*
* It transform any pair CR+LF new line characters into a single LF new line character.
*
* \section fonts Font Style, Weight and Smooth
*
* This appendix shows the differences and relations between the font style, the font weight, the smoothness and the italics.
*
* When a font is loaded, Dali uses different mechanisms to modify the render of glyphs.
* i.e \Hello World\ produces the "Hello World" bellow.
* \image html text-view/FontAppendix01.png
* By adding the \ \ \ tags to the markup string or using the Dali::TextStyle::SetItalics(), Dali::TextStyle::SetWeight() or Dali::TextStyle::SetSmoothEdge() methods,
* Dali modifies how glyphs of the same font are rendered.
* i.e \\Hello World\\
* \image html text-view/FontAppendix02.png
* i.e \\Hello World\\
* \image html text-view/FontAppendix03.png
*
* The smooth parameter can be used to adjust the thickness of the rendered glyphs.
* i.e
\\Hello World\\\
* \Hello World\\
* \\Hello World\\\
* \\Hello World\\\
* \\Hello World\\
*
* \image html text-view/FontAppendix04.png
*
* All "Hello World" above have been rendered using the same font, saving some memory. Alternatively, the platform can provide fonts with different styles.
*
* i.e. Samsung platform provides among others:
* Samsung Sans:style=Light
* Samsung Sans:style=Regular
* Samsung Sans:style=Medium
*
* \Hello World\\
* \Hello World\\
* \Hello World\
* \image html text-view/FontAppendix05.png
*
* The three "Hello World" above have been rendered with three different fonts.
*
* The fc-list command can be executed on the platform command line to check with fonts and which styles are supported.
*
* \section example Example
*
* \code
* const std::string text( ""
* "Italics: 기울임 꼴
"
* "Underline: 밑줄
"
* "Bold: 두꺼운
"
* "Font FreeSerif
"
* "Shadow: 그림자
"
* "Glow: 빛나다
"
* "Outline: 윤곽선
"
* "Smooth: 부드럽게
"
* "" );
*
* Toolkit::MarkupProcessor::StyledTextArray styledText;
* Toolkit::MarkupProcessor::GetStyledTextArray( text, styledText, true );
*
* Toolkit::TextView textView = Toolkit::TextView::New( styledText );
* textView.SetParentOrigin( ParentOrigin::CENTER );
*
* Stage::GetCurrent().Add( textView );
* \endcode
*
* \image html text-view/text-view.png
* Text generated with the example above.
*/