1 /*! \page text-view Text View
3 * \section overview Overview
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.
8 * Dali::Toolkit::TextView also provides text layout information which could be used in other UI Dali::Toolkit::Control classes or other applications.
10 * \section multiline Multi-line wrapping
12 * Different multi-line and exceed policies could be set to layout the given text.
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.
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.
22 * @see more \ref examples.
24 * \subsection multiline_policies Multi-line policies
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.
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.
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.
38 * Dali::Toolkit::TextView::SplitByNewLineChar is set by default.
40 * \subsection exceed_policies Exceed policies
43 * <li><em>Original size</em>.
44 * Text will be displayed with its original size.
47 * Text will be faded out.
50 * Text will be wrapped and moved to a new line.
52 * <li><em>Shrink to fit</em>.
53 * Text will be shrunk to fit in the text view's boundary.
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).
58 * Dali::Toolkit::TextView::Original is set by default.
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
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
69 * \section scroll Scroll
71 * Text could be scrolled if it exceeds the boundaries of the text-view.
73 * @see Dali::Toolkit::TextView::SetScrollEnabled
74 * @see Dali::Toolkit::TextView::SetScrollPosition
76 * \section line_height_spacing Line height spacing
78 * The default space between lines could be modified by setting an offset with Dali::Toolkit::TextView::SetLineHeightOffset().
80 * <h1 class="pg">Font support and multi-language detection</h1>
82 * Dali::Toolit::TextView uses the font specified in the styled text array to display the given text.
84 * See \link markup-processor Markup Processor \endlink for more details on how to create styling markup strings and styled text arrays.
86 * To support multi-language texts, text-view does the following actions per character:
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.
94 * \section text_alignment Text alignment and justification
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
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.
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.
106 * @see Dali::Toolkit::TextView::SetTextAlignment @see Dali::Toolkit::TextView::SetLineJustification
108 * \section text_styling Text styling
110 * Dali::Toolkit::TextView supports all text styling features provided by Dali::TextActor (font type, color, size, outline, etc).
112 * Different techniques are provided to set or modify the text view's style:
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.
121 * See \link markup-processor Markup Processor \endlink for more details on how to create styling markup strings and styled text arrays.
123 * \section retrieve Retrieve text layout information
125 * The Dali::Toolkit::TextView::GetTextLayoutInfo() retrieves how the input text has been laid out.
127 * For each character it retrieves its size and position, visibility, etc. @see Dali::Toolkit::TextView::CharacterLayoutInfo.
129 * For each laid-out line it retrieves the index of the first character of the line, size, etc. @see Dali::Toolkit::TextView::LineLayoutInfo.
131 * \section appendix Appendix
132 * \subsection examples Examples
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.
136 * Creation of a text view actor with all its parameters by default.
138 * Toolkit::TextView textView = Toolkit::TextView::New( "Hello world!" );
139 * textView.SetParentOrigin( ParentOrigin::CENTER );
141 * Stage::GetCurrent().Add( textView );
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.
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."
151 * Toolkit::TextView textView = Toolkit::TextView::New( "" );
152 * textView.SetMarkupProcessingEnabled( true );
153 * textView.SetText( text );
154 * textView.SetParentOrigin( ParentOrigin::CENTER );
156 * textView.SetMultilinePolicy( Toolkit::TextView::SplitByNewLineChar );
157 * textView.SetWidthExceedPolicy( Toolkit::TextView::Original );
158 * textView.SetHeightExceedPolicy( Toolkit::TextView::Original );
159 * textView.SetLineJustification( Toolkit::TextView::Center );
161 * Stage::GetCurrent().Add( textView );
163 * \image html text-view/text-view-example-01.png
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.
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."
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 );
179 * textView.SetMultilinePolicy( Toolkit::TextView::SplitByWord );
180 * textView.SetWidthExceedPolicy( Toolkit::TextView::Original );
181 * textView.SetHeightExceedPolicy( Toolkit::TextView::Original );
182 * textView.SetLineJustification( Toolkit::TextView::Center );
184 * Stage::GetCurrent().Add( textView );
186 * \image html text-view/text-view-example-02.png
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.
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."
195 * const std::string ellipsizeText( "<font color='black'>...</font>" );
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 );
204 * textView.SetMultilinePolicy( Toolkit::TextView::SplitByWord );
205 * textView.SetWidthExceedPolicy( Toolkit::TextView::Split );
206 * textView.SetHeightExceedPolicy( Toolkit::TextView::EllipsizeEnd );
207 * textView.SetLineJustification( Toolkit::TextView::Center );
209 * Stage::GetCurrent().Add( textView );
211 * \image html text-view/text-view-example-03.png
213 * This example is similar to the one above but the ellipsized text has been set to "" so nothing is shown.
216 * const std::string text( "<font color='black'>"
217 * "Loremipsumdolorsitametconsecteturadipisicingelit"
218 * "seddoeiusmodtemporincididuntutlaboreetdoloremagnaaliqua."
220 * const std::string ellipsizeText( "" );
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 );
229 * textView.SetMultilinePolicy( Toolkit::TextView::SplitByWord );
230 * textView.SetWidthExceedPolicy( Toolkit::TextView::Split );
231 * textView.SetHeightExceedPolicy( Toolkit::TextView::EllipsizeEnd );
232 * textView.SetLineJustification( Toolkit::TextView::Center );
234 * Stage::GetCurrent().Add( textView );
236 * \image html text-view/text-view-example-04.png
238 * This example shows how to fade the text out when it exceeds the boundaries of the text-view.
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."
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 );
254 * Toolkit::TextView::FadeBoundary fadeBoundary( PixelSize( 10 ), PixelSize( 10 ), PixelSize( 10 ), PixelSize( 10 ) );
255 * textView.SetFadeBoundary( fadeBoundary );
257 * textView.SetMultilinePolicy( Toolkit::TextView::SplitByNewLineChar );
258 * textView.SetWidthExceedPolicy( Toolkit::TextView::Fade );
259 * textView.SetHeightExceedPolicy( Toolkit::TextView::Fade );
260 * textView.SetLineJustification( Toolkit::TextView::Center );
262 * Stage::GetCurrent().Add( textView );
264 * \image html text-view/text-view-example-05.png
266 * This example enables the scroll feature. The screen-shots show three different images of the same text in different scroll positions.
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."
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 );
280 * textView.SetMultilinePolicy( Toolkit::TextView::SplitByNewLineChar );
281 * textView.SetWidthExceedPolicy( Toolkit::TextView::Original );
282 * textView.SetHeightExceedPolicy( Toolkit::TextView::Original );
283 * textView.SetLineJustification( Toolkit::TextView::Center );
285 * textView.SetScrollEnabled( true );
287 * Stage::GetCurrent().Add( textView );
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
293 * See \link markup-processor Markup Processor \endlink \ref example for more styling markup string examples.
295 * \subsection exceed_policies_combinations Implemented exceed policies combinations
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).
300 * @note The Split value is not valid for the height exceed policy.
303 * <table border="1" align="center">
304 * <tr align="center">
305 * <th align="center" colspan="7">SplitByNewLineChar</th>
307 * <tr align="center">
308 * <th colspan="2" rowspan="2"></th><th align="center" colspan="6">Width exceed policies</th>
311 * <th>Original</th><th>Fade</th><th>Split</th><th>ShrinkToFit</th><th>EllipsizeEnd</th>
313 * <tr align="center">
314 * <th rowspan="4">Height<br />exceed<br />policies</th>
316 * <td><font color=#0A0>✓</font></td>
317 * <td><font color=#0A0>✓</font></td>
318 * <td><font color=#0A0>✓</font></td>
319 * <td><font color=#0A0>✓</font></td>
320 * <td><font color=#0A0>✓</font></td>
322 * <tr align="center">
324 * <td><font color=#0A0>✓</font></td>
325 * <td><font color=#0A0>✓</font></td>
326 * <td><font color=#0A0>✓</font></td>
327 * <td><font color=#A00>✗</font></td>
328 * <td><font color=#A00>✗</font></td>
330 * <tr align="center">
331 * <th>ShrinkToFit</th>
332 * <td><font color=#A00>✗</font></td>
333 * <td><font color=#A00>✗</font></td>
334 * <td><font color=#A00>✗</font></td>
335 * <td><font color=#0A0>✓</font></td>
336 * <td><font color=#A00>✗</font></td>
338 * <tr align="center">
339 * <th>EllipsizeEnd</th>
340 * <td><font color=#A00>✗</font></td>
341 * <td><font color=#A00>✗</font></td>
342 * <td><font color=#0A0>✓</font></td>
343 * <td><font color=#A00>✗</font></td>
344 * <td><font color=#0A0>✓</font></td>
352 * <table border="1" align="center">
353 * <tr align="center">
354 * <th align="center" colspan="7">SplitByWord</th>
356 * <tr align="center">
357 * <th colspan="2" rowspan="2"></th><th align="center" colspan="6">Width exceed policies</th>
360 * <th>Original</th><th>Fade</th><th>Split</th><th>ShrinkToFit</th><th>EllipsizeEnd</th>
362 * <tr align="center">
363 * <th rowspan="4">Height<br />exceed<br />policies</th>
365 * <td><font color=#0A0>✓</font></td>
366 * <td><font color=#0A0>✓</font></td>
367 * <td><font color=#0A0>✓</font></td>
368 * <td><font color=#0A0>✓</font></td>
369 * <td><font color=#0A0>✓</font></td>
371 * <tr align="center">
373 * <td><font color=#0A0>✓</font></td>
374 * <td><font color=#0A0>✓</font></td>
375 * <td><font color=#0A0>✓</font></td>
376 * <td><font color=#A00>✗</font></td>
377 * <td><font color=#A00>✗</font></td>
379 * <tr align="center">
380 * <th>ShrinkToFit</th>
381 * <td><font color=#A00>✗</font></td>
382 * <td><font color=#A00>✗</font></td>
383 * <td><font color=#A00>✗</font></td>
384 * <td><font color=#0A0>✓</font></td>
385 * <td><font color=#A00>✗</font></td>
387 * <tr align="center">
388 * <th>EllipsizeEnd</th>
389 * <td><font color=#A00>✗</font></td>
390 * <td><font color=#A00>✗</font></td>
391 * <td><font color=#0A0>✓</font></td>
392 * <td><font color=#A00>✗</font></td>
393 * <td><font color=#0A0>✓</font></td>
401 * <table border="1" align="center">
402 * <tr align="center">
403 * <th align="center" colspan="7">SplitByChar</th>
405 * <tr align="center">
406 * <th colspan="2" rowspan="2"></th><th align="center" colspan="6">Width exceed policies</th>
409 * <th>Original</th><th>Fade</th><th>Split</th><th>ShrinkToFit</th><th>EllipsizeEnd</th>
411 * <tr align="center">
412 * <th rowspan="4">Height<br />exceed<br />policies</th>
414 * <td><font color=#0A0>✓</font></td>
415 * <td><font color=#0A0>✓</font></td>
416 * <td><font color=#A00>✗</font></td>
417 * <td><font color=#A00>✗</font></td>
418 * <td><font color=#A00>✗</font></td>
420 * <tr align="center">
422 * <td><font color=#0A0>✓</font></td>
423 * <td><font color=#0A0>✓</font></td>
424 * <td><font color=#A00>✗</font></td>
425 * <td><font color=#A00>✗</font></td>
426 * <td><font color=#A00>✗</font></td>
428 * <tr align="center">
429 * <th>ShrinkToFit</th>
430 * <td><font color=#A00>✗</font></td>
431 * <td><font color=#A00>✗</font></td>
432 * <td><font color=#A00>✗</font></td>
433 * <td><font color=#A00>✗</font></td>
434 * <td><font color=#A00>✗</font></td>
436 * <tr align="center">
437 * <th>EllipsizeEnd</th>
438 * <td><font color=#A00>✗</font></td>
439 * <td><font color=#A00>✗</font></td>
440 * <td><font color=#A00>✗</font></td>
441 * <td><font color=#A00>✗</font></td>
442 * <td><font color=#A00>✗</font></td>