docs/content/programming-guide/markup-processor.h

   1 /*! \page markup-processor Markup processor
   2  *
   3  * <h1 class="pg">Overview</h1>
   4  *
   5  * Dali::Toolkit::MarkupProcessor functions provide mechanisms to build and modify a Dali::Toolkit::MarkupProcessor::StyledTextArray used to store text with style.
   6  *
   7  * <h1 class="pg">Build a styled text array from a markup string</h1>
   8  *
   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:
  11  *
  12  * <ul>
  13  *   <li>\e \<b\>\</b\> Bold text.
  14  *   i.e. \<b\>Bold text\</b\>"
  15  *   \image html text-view/Bold.png
  16  *
  17  *   <li>\e \<i\>\</i\> Italic text.
  18  *   i.e. \<i\>Italic text\</i\>"
  19  *   \image html text-view/Italic.png
  20  *
  21  *   <li>\e \<u\>\</u\> Underlined text.
  22  *   i.e. \<u\>Underline text\</u\>"
  23  *   \image html text-view/Underline.png
  24  *
  25  *   <li>\e \<br /\> New line.
  26  *
  27  *   <li>\e \<font\>\</font\> Specifies font properties:
  28  *     <ul>
  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.
  33  *     </ul>
  34  *
  35  *     i.e. \<font face='FreeSerif' style='Regular'\>FreeSerif font\</font\>
  36  *     \image html text-view/FreeSerifFont.png
  37  *
  38  *   <li>\e \<shadow\>\</shadow\> Specifies shadow properties.
  39  *     <ul>
  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.
  43  *     </ul>
  44  *
  45  *     i.e. \<shadow color='black' paramx='1.5' paramy='1.5'\>Black shadow\</shadow\>
  46  *     \image html text-view/Black-Shadow.png
  47  *
  48  *     @see Dali::TextActor::SetShadow()
  49  *     <br><br>
  50  *   <li>\e \<glow\>\</glow\> Specifies glow properties.
  51  *     <ul>
  52  *       <li> \e param Glow around the text.
  53  *       <li> \e color Glow color. See the \ref color section for more details.
  54  *     </ul>
  55  *
  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
  58  *
  59  *     @see Dali::TextActor::SetGlow()
  60  *     <br><br>
  61  *   <li>\e \<outline\>\</outline\> Specifies outline properties.
  62  *     <ul>
  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.
  66  *     </ul>
  67  *
  68  *     i.e. \<outline color='red' paramx='0.5' paramy='0.5'\>Red outline\</outline\>
  69  *     \image html text-view/Red-Outline.png
  70  *
  71  *     @see Dali::TextActor::SetOutline()
  72  *     <br><br>
  73  *   <li>\e \<smooth\>\</smooth\> Specify the smooth edge.
  74  *     <ul>
  75  *       <li> \e param Distance field.
  76  *     </ul>
  77  *
  78  *     i.e. \<smooth param='0.3'\>Smooth text\</smooth\>
  79  *     \image html text-view/Smooth-Text.png
  80  *
  81  *     @see Dali::TextActor::SetSmoothEdge()
  82  * </ul>
  83  *
  84  * See also \ref color, \ref special_characters and \ref example for more details.
  85  *
  86  * <h1 class="pg">Get a markup string from a styled text array</h1>
  87  *
  88  * Dali::Toolkit::MarkupProcessor::GetMarkupString() could be used to convert a styled text array into an html-ish markup string.
  89  *
  90  * <h1 class="pg">Modify a styled text array</h1>
  91  *
  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.
  93  *
  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 )
  97  *
  98  * <h1 class="pg">Appendix</h1>
  99  * \section color Color
 100  *
 101  * Different options could be used to define a color:
 102  *
 103  * <ul>
 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.
 108  * </ul>
 109  *
 110  * \section special_characters Special characters
 111  *
 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 '\\\\'.
 114  *
 115  * i.e. text.SetText("a \\< b \\< c");
 116  * \image html text-view/AlessBlessC.png
 117  *
 118  * It transform any pair CR+LF new line characters into a single LF new line character.
 119  *
 120  * \section fonts Font Style, Weight and Smooth
 121  *
 122  * This appendix shows the differences and relations between the font style, the font weight, the smoothness and the italics.
 123  *
 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
 133  *
 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\>
 140  *
 141  * \image html text-view/FontAppendix04.png
 142  *
 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>
 144  *
 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>
 149  *
 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
 154  *
 155  * The three "Hello World" above have been rendered with three different fonts.<br>
 156  *
 157  * The <i>fc-list</i> command can be executed on the platform command line to check with fonts and which styles are supported.
 158  *
 159  * \section example Example
 160  *
 161  * \code
 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/>"
 171  *                           "</font>" );
 172  *
 173  *   Toolkit::MarkupProcessor::StyledTextArray styledText;
 174  *   Toolkit::MarkupProcessor::GetStyledTextArray( text, styledText, true );
 175  *
 176  *   Toolkit::TextView textView = Toolkit::TextView::New( styledText );
 177  *   textView.SetParentOrigin( ParentOrigin::CENTER );
 178  *
 179  *   Stage::GetCurrent().Add( textView );
 180  * \endcode
 181  *
 182  * \image html text-view/text-view.png
 183  * Text generated with the example above.
 184  */