docs/content/programming-guide/text-view.h

   1 /*! \page text-view Text View
   2  *
   3  * \section overview Overview
   4  *
   5  * The Dali::Toolkit::TextView class is a UI Dali::Toolkit::Control designed to extend the capabilities of the basic Dali::TextActor.
   6  * It provides support for multi-line wrapping, multi-language font detection, text alignment, scrolling and styling.
   7  *
   8  * Dali::Toolkit::TextView also provides text layout information which could be used in other UI Dali::Toolkit::Control classes or other applications.
   9  *
  10  * \section multiline Multi-line wrapping
  11  *
  12  * Different multi-line and exceed policies could be set to layout the given text.
  13  *
  14  * Both multi-line and exceed policies work together.
  15  * Dali::Toolkit::TextView::MultilinePolicy policies define how to wrap a line if it doesn't fit inside the boundary's width
  16  * whereas Dali::Toolkit::TextView::ExceedPolicy policies define what to do if the wrapped text is bigger than the text view's boundary.
  17  *
  18  * i.e. \e SplitByWord could be used as 'multi-line policy' to wrap a line if it's too long. If one of the words is longer than the text-view's width, \e Split could be
  19  *      used as 'width exceed policy' to split a word in different lines. If the text is too long and exceeds the text-view's height, \e EllipsizedEnd could be
  20  *      used as 'height exceed policy' to render only the text which fits inside the boundaries of the text-view.
  21  *
  22  * @see more \ref examples.
  23  *
  24  * \subsection multiline_policies Multi-line policies
  25  *
  26  * <ul>
  27  *   <li><em>Split by new line character</em>.
  28  *           Text will be wrapped when an <em>end of line \\n</em> or <em>\<br /\></em> is found.
  29  *
  30  *   <li><em>Split by word</em>.
  31  *           Text will be wrapped when an <em>end of line \\n</em> or <em>\<br /\></em> is found or if the text doesn't fit in the text view width.
  32  *           In that case, some words will be moved to a new line.
  33  *
  34  *   <li><em>Split by character</em>.
  35  *           Text will be wrapped when an <em>end of line \\n</em> or <em>\<br /\></em> is found or if the text doesn't fit in the text view width.
  36  *           In that case, words which don't fit will be wrapped in two and the remaining text moved to a new line.
  37  * </ul>
  38  * Dali::Toolkit::TextView::SplitByNewLineChar is set by default.
  39  *
  40  * \subsection exceed_policies Exceed policies
  41  *
  42  * <ul>
  43  *   <li><em>Original size</em>.
  44  *           Text will be displayed with its original size.
  45  *
  46  *   <li><em>Fade</em>.
  47  *           Text will be faded out.
  48  *
  49  *   <li><em>Split</em>.
  50  *           Text will be wrapped and moved to a new line.
  51  *
  52  *   <li><em>Shrink to fit</em>.
  53  *           Text will be shrunk to fit in the text view's boundary.
  54  *
  55  *   <li><em>Ellipsize at the end</em>.
  56  *           Text will be truncated to fit in the text view's boundary and the ellipsize text will be added. ( '...' by default).
  57  * </ul>
  58  * Dali::Toolkit::TextView::Original is set by default.
  59  *
  60  * @see Dali::Toolkit::TextView::SetMultilinePolicy
  61  * @see Dali::Toolkit::TextView::SetWidthExceedPolicy
  62  * @see Dali::Toolkit::TextView::SetHeightExceedPolicy
  63  * @see Dali::Toolkit::TextView::SetFadeBoundary
  64  * @see Dali::Toolkit::TextView::SetEllipsizeText
  65  *
  66  * @note Multiple combinations are possible but not all of them are already implemented.
  67  * @see \ref exceed_policies_combinations table to check which combinations are implemented
  68  *
  69  * \section scroll Scroll
  70  *
  71  * Text could be scrolled if it exceeds the boundaries of the text-view.
  72  *
  73  * @see  Dali::Toolkit::TextView::SetScrollEnabled
  74  * @see  Dali::Toolkit::TextView::SetScrollPosition
  75  *
  76  * \section line_height_spacing Line height spacing
  77  *
  78  * The default space between lines could be modified by setting an offset with Dali::Toolkit::TextView::SetLineHeightOffset().
  79  *
  80  * <h1 class="pg">Font support and multi-language detection</h1>
  81  *
  82  * Dali::Toolit::TextView uses the font specified in the styled text array to display the given text.
  83  *
  84  * See \link markup-processor Markup Processor \endlink for more details on how to create styling markup strings and styled text arrays.
  85  *
  86  * To support multi-language texts, text-view does the following actions per character:
  87  * <ul>
  88  *   <li> Check if there is a font defined in the styled text array.
  89  *   <li> If there isn't, try to use the default platform font.
  90  *   <li> Check if the character is supported by the font.
  91  *   <li> If isn't, find the most suitable font for the character.
  92  * </ul>
  93  *
  94  * \section text_alignment Text alignment and justification
  95  *
  96  * Dali::Toolkit::TextView provides a method to align the whole text inside the text view's boundary as well as a method to justify each line
  97  * inside the text.
  98  *
  99  * The Dali::Toolkit::Alignment::Type is used to align the whole text in the text view's area.
 100  * A text could be horizontally aligned (left, center, right) and/or vertically aligned (top, center, bottom).
 101  * Dali::Toolkit::Alignment::HorizontalCenter | Dali::Toolkit::Alignment::VerticalCenter is set by default.
 102  *
 103  * The Dali::Toolkit::TextView::LineJustification is used to justify each line inside the text (left, center, right, justified).
 104  * Dali::Toolkit::TextView::Left is set by default.
 105  *
 106  * @see Dali::Toolkit::TextView::SetTextAlignment @see Dali::Toolkit::TextView::SetLineJustification
 107  *
 108  * \section text_styling Text styling
 109  *
 110  * Dali::Toolkit::TextView supports all text styling features provided by Dali::TextActor (font type, color, size, outline, etc).
 111  *
 112  *  Different techniques are provided to set or modify the text view's style:
 113  *
 114  * <ul>
 115  *  <li> By setting a Dali::Toolkit::MarkupProcessor::StyledTextArray with the Dali::Toolkit::TextView::SetText(const MarkupProcessor::StyledTextArray& text) method.
 116  *  <li> By setting a new Dali::TextStyle to the current text with the Dali::Toolkit::TextView::SetStyleToCurrentText() method.
 117  *  <li> By setting an html-ish markup string which contains both text and style with the Dali::Toolkit::TextView::SetText(const std::string& text) method.
 118          @note By default the style markup processor is disabled. @see Dali::Toolkit::TextView::SetMarkupProcessingEnabled to enable the markup processing.
 119  * </ul>
 120  *
 121  * See \link markup-processor Markup Processor \endlink for more details on how to create styling markup strings and styled text arrays.
 122  *
 123  * \section retrieve Retrieve text layout information
 124  *
 125  * The Dali::Toolkit::TextView::GetTextLayoutInfo() retrieves how the input text has been laid out.
 126  *
 127  * For each character it retrieves its size and position, visibility, etc. @see Dali::Toolkit::TextView::CharacterLayoutInfo.
 128  *
 129  * For each laid-out line it retrieves the index of the first character of the line, size, etc. @see Dali::Toolkit::TextView::LineLayoutInfo.
 130  *
 131  * \section appendix Appendix
 132  * \subsection examples Examples
 133  *
 134  * The following examples show how to use TextView. The grey square is an actor which has been added just to show the size of the text-view.
 135  *
 136  * Creation of a text view actor with all its parameters by default.
 137  * \code
 138  *   Toolkit::TextView textView = Toolkit::TextView::New( "Hello world!" );
 139  *   textView.SetParentOrigin( ParentOrigin::CENTER );
 140  *
 141  *   Stage::GetCurrent().Add( textView );
 142  * \endcode
 143  *
 144  * This example wraps the text in lines only when a \\n character is found. The size of the text-view will be automatically resized to fit the whole text inside.
 145  * \code
 146  *   const std::string text( "<font color='black'>"
 147  *                           "Lorem ipsum dolor sit amet, consectetur adipisicing elit,\n"
 148  *                           "sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
 149  *                           "</font>" );
 150  *
 151  *   Toolkit::TextView textView = Toolkit::TextView::New( "" );
 152  *   textView.SetMarkupProcessingEnabled( true );
 153  *   textView.SetText( text );
 154  *   textView.SetParentOrigin( ParentOrigin::CENTER );
 155  *
 156  *   textView.SetMultilinePolicy( Toolkit::TextView::SplitByNewLineChar );
 157  *   textView.SetWidthExceedPolicy( Toolkit::TextView::Original );
 158  *   textView.SetHeightExceedPolicy( Toolkit::TextView::Original );
 159  *   textView.SetLineJustification( Toolkit::TextView::Center );
 160  *
 161  *   Stage::GetCurrent().Add( textView );
 162  * \endcode
 163  * \image html text-view/text-view-example-01.png
 164  *
 165  * This example wraps the lines by the next word when it exceeds the width of the text-view. The height exceed policy is set to \e Original so it may exceed the height of the text-view.
 166  *
 167  * \code
 168  *   const std::string text( "<font color='black'>"
 169  *                           "Lorem ipsum dolor sit amet, consectetur adipisicing elit, "
 170  *                           "sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
 171  *                           "</font>" );
 172  *
 173  *   Toolkit::TextView textView = Toolkit::TextView::New( "" );
 174  *   textView.SetMarkupProcessingEnabled( true );
 175  *   textView.SetText( text );
 176  *   textView.SetParentOrigin( ParentOrigin::CENTER );
 177  *   textView.SetSize( 300.f, 125.f );
 178  *
 179  *   textView.SetMultilinePolicy( Toolkit::TextView::SplitByWord );
 180  *   textView.SetWidthExceedPolicy( Toolkit::TextView::Original );
 181  *   textView.SetHeightExceedPolicy( Toolkit::TextView::Original );
 182  *   textView.SetLineJustification( Toolkit::TextView::Center );
 183  *
 184  *   Stage::GetCurrent().Add( textView );
 185  * \endcode
 186  * \image html text-view/text-view-example-02.png
 187  *
 188  * This example wraps the lines by the next word when it exceeds the width of the text-view. If a word is bigger than the text-view's width, it splits the word. If the text exceeds the height of the text-view, the text is ellipsized.
 189  *
 190  * \code
 191  *   const std::string text( "<font color='black'>"
 192  *                           "Loremipsumdolorsitametconsectetur adipisicing elit,\n"
 193  *                           "sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
 194  *                           "</font>" );
 195  *   const std::string ellipsizeText( "<font color='black'>...</font>" );
 196  *
 197  *   Toolkit::TextView textView = Toolkit::TextView::New( "" );
 198  *   textView.SetMarkupProcessingEnabled( true );
 199  *   textView.SetText( text );
 200  *   textView.SetEllipsizeText( ellipsizeText );
 201  *   textView.SetParentOrigin( ParentOrigin::CENTER );
 202  *   textView.SetSize( 300.f, 125.f );
 203  *
 204  *   textView.SetMultilinePolicy( Toolkit::TextView::SplitByWord );
 205  *   textView.SetWidthExceedPolicy( Toolkit::TextView::Split );
 206  *   textView.SetHeightExceedPolicy( Toolkit::TextView::EllipsizeEnd );
 207  *   textView.SetLineJustification( Toolkit::TextView::Center );
 208  *
 209  *   Stage::GetCurrent().Add( textView );
 210  * \endcode
 211  * \image html text-view/text-view-example-03.png
 212  *
 213  * This example is similar to the one above but the ellipsized text has been set to "" so nothing is shown.
 214  *
 215  * \code
 216  *   const std::string text( "<font color='black'>"
 217  *                           "Loremipsumdolorsitametconsecteturadipisicingelit"
 218  *                           "seddoeiusmodtemporincididuntutlaboreetdoloremagnaaliqua."
 219  *                           "</font>" );
 220  *   const std::string ellipsizeText( "" );
 221  *
 222  *   Toolkit::TextView textView = Toolkit::TextView::New( "" );
 223  *   textView.SetMarkupProcessingEnabled( true );
 224  *   textView.SetText( text );
 225  *   textView.SetEllipsizeText( ellipsizeText );
 226  *   textView.SetParentOrigin( ParentOrigin::CENTER );
 227  *   textView.SetSize( 300.f, 125.f );
 228  *
 229  *   textView.SetMultilinePolicy( Toolkit::TextView::SplitByWord );
 230  *   textView.SetWidthExceedPolicy( Toolkit::TextView::Split );
 231  *   textView.SetHeightExceedPolicy( Toolkit::TextView::EllipsizeEnd );
 232  *   textView.SetLineJustification( Toolkit::TextView::Center );
 233  *
 234  *   Stage::GetCurrent().Add( textView );
 235  * \endcode
 236  * \image html text-view/text-view-example-04.png
 237  *
 238  * This example shows how to fade the text out when it exceeds the boundaries of the text-view.
 239  *
 240  * \code
 241  *   const std::string text( "<font color='black'>"
 242  *                           "Lorem ipsum dolor sit amet,\n"
 243  *                           "consectetur adipisicing elit,\n"
 244  *                           "sed do eiusmod tempor incididunt\n"
 245  *                           "ut labore et dolore magna aliqua."
 246  *                           "</font>" );
 247  *
 248  *   Toolkit::TextView textView = Toolkit::TextView::New();
 249  *   textView.SetMarkupProcessingEnabled( true );
 250  *   textView.SetText( text );
 251  *   textView.SetParentOrigin( ParentOrigin::CENTER );
 252  *   textView.SetSize( 300.f, 100.f );
 253  *
 254  *   Toolkit::TextView::FadeBoundary fadeBoundary( PixelSize( 10 ), PixelSize( 10 ), PixelSize( 10 ), PixelSize( 10 ) );
 255  *   textView.SetFadeBoundary( fadeBoundary );
 256  *
 257  *   textView.SetMultilinePolicy( Toolkit::TextView::SplitByNewLineChar );
 258  *   textView.SetWidthExceedPolicy( Toolkit::TextView::Fade );
 259  *   textView.SetHeightExceedPolicy( Toolkit::TextView::Fade );
 260  *   textView.SetLineJustification( Toolkit::TextView::Center );
 261  *
 262  *   Stage::GetCurrent().Add( textView );
 263  * \endcode
 264  * \image html text-view/text-view-example-05.png
 265  *
 266  * This example enables the scroll feature. The screen-shots show three different images of the same text in different scroll positions.
 267  *
 268  * \code
 269  *   const std::string text( "<font color='black'>"
 270  *                           "Lorem ipsum dolor sit amet, consectetur adipisicing elit,\n"
 271  *                           "sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
 272  *                           "</font>" );
 273  *
 274  *   Toolkit::TextView textView = Toolkit::TextView::New();
 275  *   textView.SetMarkupProcessingEnabled( true );
 276  *   textView.SetText( text );
 277  *   textView.SetParentOrigin( ParentOrigin::CENTER );
 278  *   textView.SetSize( 300.f, 60.f );
 279  *
 280  *   textView.SetMultilinePolicy( Toolkit::TextView::SplitByNewLineChar );
 281  *   textView.SetWidthExceedPolicy( Toolkit::TextView::Original );
 282  *   textView.SetHeightExceedPolicy( Toolkit::TextView::Original );
 283  *   textView.SetLineJustification( Toolkit::TextView::Center );
 284  *
 285  *   textView.SetScrollEnabled( true );
 286  *
 287  *   Stage::GetCurrent().Add( textView );
 288  * \endcode
 289  * \image html text-view/text-view-example-06.png
 290  * \image html text-view/text-view-example-07.png
 291  * \image html text-view/text-view-example-08.png
 292  *
 293  * See \link markup-processor Markup Processor \endlink \ref example for more styling markup string examples.
 294  *
 295  * \subsection exceed_policies_combinations Implemented exceed policies combinations
 296  *
 297  * The following tables show which exceed policies are implemented for each multi-line policy. Each column has one width exceed policy (Original, Fade, Split, ShrinkToFit and EllipsizeEnd),
 298  * each row has one height exceed policy (Original, Fade, ShrinkToFit and EllipsizeEnd).
 299  *
 300  * @note The Split value is not valid for the height exceed policy.
 301  *
 302  * \htmlonly
 303  * <table border="1" align="center">
 304  * <tr align="center">
 305  *   <th align="center" colspan="7">SplitByNewLineChar</th>
 306  * </tr>
 307  * <tr align="center">
 308  *   <th colspan="2" rowspan="2"></th><th align="center" colspan="6">Width exceed policies</th>
 309  * </tr>
 310  * <tr>
 311  *   <th>Original</th><th>Fade</th><th>Split</th><th>ShrinkToFit</th><th>EllipsizeEnd</th>
 312  * </tr>
 313  * <tr align="center">
 314  *   <th rowspan="4">Height<br />exceed<br />policies</th>
 315  *         <th>Original</th>
 316  *                        <td><font color=#0A0>&#x2713</font></td>
 317  *                        <td><font color=#0A0>&#x2713</font></td>
 318  *                        <td><font color=#0A0>&#x2713</font></td>
 319  *                        <td><font color=#0A0>&#x2713</font></td>
 320  *                        <td><font color=#0A0>&#x2713</font></td>
 321  * </tr>
 322  * <tr align="center">
 323  *         <th>Fade</th>
 324  *                        <td><font color=#0A0>&#x2713</font></td>
 325  *                        <td><font color=#0A0>&#x2713</font></td>
 326  *                        <td><font color=#0A0>&#x2713</font></td>
 327  *                        <td><font color=#A00>&#x2717</font></td>
 328  *                        <td><font color=#A00>&#x2717</font></td>
 329  * </tr>
 330  * <tr align="center">
 331  *         <th>ShrinkToFit</th>
 332  *                        <td><font color=#A00>&#x2717</font></td>
 333  *                        <td><font color=#A00>&#x2717</font></td>
 334  *                        <td><font color=#A00>&#x2717</font></td>
 335  *                        <td><font color=#0A0>&#x2713</font></td>
 336  *                        <td><font color=#A00>&#x2717</font></td>
 337  * </tr>
 338  * <tr align="center">
 339  *         <th>EllipsizeEnd</th>
 340  *                        <td><font color=#A00>&#x2717</font></td>
 341  *                        <td><font color=#A00>&#x2717</font></td>
 342  *                        <td><font color=#0A0>&#x2713</font></td>
 343  *                        <td><font color=#A00>&#x2717</font></td>
 344  *                        <td><font color=#0A0>&#x2713</font></td>
 345  * </tr>
 346  * </table>
 347  * \endhtmlonly
 348  *
 349  * \n
 350  *
 351  * \htmlonly
 352  * <table border="1" align="center">
 353  * <tr align="center">
 354  *   <th align="center" colspan="7">SplitByWord</th>
 355  * </tr>
 356  * <tr align="center">
 357  *   <th colspan="2" rowspan="2"></th><th align="center" colspan="6">Width exceed policies</th>
 358  * </tr>
 359  * <tr>
 360  *   <th>Original</th><th>Fade</th><th>Split</th><th>ShrinkToFit</th><th>EllipsizeEnd</th>
 361  * </tr>
 362  * <tr align="center">
 363  *   <th rowspan="4">Height<br />exceed<br />policies</th>
 364  *         <th>Original</th>
 365  *                        <td><font color=#0A0>&#x2713</font></td>
 366  *                        <td><font color=#0A0>&#x2713</font></td>
 367  *                        <td><font color=#0A0>&#x2713</font></td>
 368  *                        <td><font color=#0A0>&#x2713</font></td>
 369  *                        <td><font color=#0A0>&#x2713</font></td>
 370  * </tr>
 371  * <tr align="center">
 372  *         <th>Fade</th>
 373  *                        <td><font color=#0A0>&#x2713</font></td>
 374  *                        <td><font color=#0A0>&#x2713</font></td>
 375  *                        <td><font color=#0A0>&#x2713</font></td>
 376  *                        <td><font color=#A00>&#x2717</font></td>
 377  *                        <td><font color=#A00>&#x2717</font></td>
 378  * </tr>
 379  * <tr align="center">
 380  *         <th>ShrinkToFit</th>
 381  *                        <td><font color=#A00>&#x2717</font></td>
 382  *                        <td><font color=#A00>&#x2717</font></td>
 383  *                        <td><font color=#A00>&#x2717</font></td>
 384  *                        <td><font color=#0A0>&#x2713</font></td>
 385  *                        <td><font color=#A00>&#x2717</font></td>
 386  * </tr>
 387  * <tr align="center">
 388  *         <th>EllipsizeEnd</th>
 389  *                        <td><font color=#A00>&#x2717</font></td>
 390  *                        <td><font color=#A00>&#x2717</font></td>
 391  *                        <td><font color=#0A0>&#x2713</font></td>
 392  *                        <td><font color=#A00>&#x2717</font></td>
 393  *                        <td><font color=#0A0>&#x2713</font></td>
 394  * </tr>
 395  * </table>
 396  * \endhtmlonly
 397  *
 398  * \n
 399  *
 400  * \htmlonly
 401  * <table border="1" align="center">
 402  * <tr align="center">
 403  *   <th align="center" colspan="7">SplitByChar</th>
 404  * </tr>
 405  * <tr align="center">
 406  *   <th colspan="2" rowspan="2"></th><th align="center" colspan="6">Width exceed policies</th>
 407  * </tr>
 408  * <tr>
 409  *   <th>Original</th><th>Fade</th><th>Split</th><th>ShrinkToFit</th><th>EllipsizeEnd</th>
 410  * </tr>
 411  * <tr align="center">
 412  *   <th rowspan="4">Height<br />exceed<br />policies</th>
 413  *         <th>Original</th>
 414  *                        <td><font color=#0A0>&#x2713</font></td>
 415  *                        <td><font color=#0A0>&#x2713</font></td>
 416  *                        <td><font color=#A00>&#x2717</font></td>
 417  *                        <td><font color=#A00>&#x2717</font></td>
 418  *                        <td><font color=#A00>&#x2717</font></td>
 419  * </tr>
 420  * <tr align="center">
 421  *         <th>Fade</th>
 422  *                        <td><font color=#0A0>&#x2713</font></td>
 423  *                        <td><font color=#0A0>&#x2713</font></td>
 424  *                        <td><font color=#A00>&#x2717</font></td>
 425  *                        <td><font color=#A00>&#x2717</font></td>
 426  *                        <td><font color=#A00>&#x2717</font></td>
 427  * </tr>
 428  * <tr align="center">
 429  *         <th>ShrinkToFit</th>
 430  *                        <td><font color=#A00>&#x2717</font></td>
 431  *                        <td><font color=#A00>&#x2717</font></td>
 432  *                        <td><font color=#A00>&#x2717</font></td>
 433  *                        <td><font color=#A00>&#x2717</font></td>
 434  *                        <td><font color=#A00>&#x2717</font></td>
 435  * </tr>
 436  * <tr align="center">
 437  *         <th>EllipsizeEnd</th>
 438  *                        <td><font color=#A00>&#x2717</font></td>
 439  *                        <td><font color=#A00>&#x2717</font></td>
 440  *                        <td><font color=#A00>&#x2717</font></td>
 441  *                        <td><font color=#A00>&#x2717</font></td>
 442  *                        <td><font color=#A00>&#x2717</font></td>
 443  * </tr>
 444  * </table>
 445  * \endhtmlonly
 446  */
 447