/*! \page text-view Text View
*
* \section overview Overview
*
* The Dali::Toolkit::TextView class is a UI Dali::Toolkit::Control designed to extend the capabilities of the basic Dali::TextActor.
* It provides support for multi-line wrapping, multi-language font detection, text alignment, scrolling and styling.
*
* Dali::Toolkit::TextView also provides text layout information which could be used in other UI Dali::Toolkit::Control classes or other applications.
*
* \section multiline Multi-line wrapping
*
* Different multi-line and exceed policies could be set to layout the given text.
*
* Both multi-line and exceed policies work together.
* Dali::Toolkit::TextView::MultilinePolicy policies define how to wrap a line if it doesn't fit inside the boundary's width
* whereas Dali::Toolkit::TextView::ExceedPolicy policies define what to do if the wrapped text is bigger than the text view's boundary.
*
* 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
* 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
* used as 'height exceed policy' to render only the text which fits inside the boundaries of the text-view.
*
* @see more \ref examples.
*
* \subsection multiline_policies Multi-line policies
*
*
* - Split by new line character.
* Text will be wrapped when an end of line \\n or \
is found.
*
* - Split by word.
* Text will be wrapped when an end of line \\n or \
is found or if the text doesn't fit in the text view width.
* In that case, some words will be moved to a new line.
*
* - Split by character.
* Text will be wrapped when an end of line \\n or \
is found or if the text doesn't fit in the text view width.
* In that case, words which don't fit will be wrapped in two and the remaining text moved to a new line.
*
* Dali::Toolkit::TextView::SplitByNewLineChar is set by default.
*
* \subsection exceed_policies Exceed policies
*
*
* - Original size.
* Text will be displayed with its original size.
*
*
- Fade.
* Text will be faded out.
*
*
- Split.
* Text will be wrapped and moved to a new line.
*
*
- Shrink to fit.
* Text will be shrunk to fit in the text view's boundary.
*
*
- Ellipsize at the end.
* Text will be truncated to fit in the text view's boundary and the ellipsize text will be added. ( '...' by default).
*
* Dali::Toolkit::TextView::Original is set by default.
*
* @see Dali::Toolkit::TextView::SetMultilinePolicy
* @see Dali::Toolkit::TextView::SetWidthExceedPolicy
* @see Dali::Toolkit::TextView::SetHeightExceedPolicy
* @see Dali::Toolkit::TextView::SetFadeBoundary
* @see Dali::Toolkit::TextView::SetEllipsizeText
*
* @note Multiple combinations are possible but not all of them are already implemented.
* @see \ref exceed_policies_combinations table to check which combinations are implemented
*
* \section scroll Scroll
*
* Text could be scrolled if it exceeds the boundaries of the text-view.
*
* @see Dali::Toolkit::TextView::SetScrollEnabled
* @see Dali::Toolkit::TextView::SetScrollPosition
*
* \section line_height_spacing Line height spacing
*
* The default space between lines could be modified by setting an offset with Dali::Toolkit::TextView::SetLineHeightOffset().
*
* Font support and multi-language detection
*
* Dali::Toolit::TextView uses the font specified in the styled text array to display the given text.
*
* See \link markup-processor Markup Processor \endlink for more details on how to create styling markup strings and styled text arrays.
*
* To support multi-language texts, text-view does the following actions per character:
*
* - Check if there is a font defined in the styled text array.
*
- If there isn't, try to use the default platform font.
*
- Check if the character is supported by the font.
*
- If isn't, find the most suitable font for the character.
*
*
* \section text_alignment Text alignment and justification
*
* 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
* inside the text.
*
* The Dali::Toolkit::Alignment::Type is used to align the whole text in the text view's area.
* A text could be horizontally aligned (left, center, right) and/or vertically aligned (top, center, bottom).
* Dali::Toolkit::Alignment::HorizontalCenter | Dali::Toolkit::Alignment::VerticalCenter is set by default.
*
* The Dali::Toolkit::TextView::LineJustification is used to justify each line inside the text (left, center, right, justified).
* Dali::Toolkit::TextView::Left is set by default.
*
* @see Dali::Toolkit::TextView::SetTextAlignment @see Dali::Toolkit::TextView::SetLineJustification
*
* \section text_styling Text styling
*
* Dali::Toolkit::TextView supports all text styling features provided by Dali::TextActor (font type, color, size, outline, etc).
*
* Different techniques are provided to set or modify the text view's style:
*
*
* - By setting a Dali::Toolkit::MarkupProcessor::StyledTextArray with the Dali::Toolkit::TextView::SetText(const MarkupProcessor::StyledTextArray& text) method.
*
- By setting a new Dali::TextStyle to the current text with the Dali::Toolkit::TextView::SetStyleToCurrentText() method.
*
- By setting an html-ish markup string which contains both text and style with the Dali::Toolkit::TextView::SetText(const std::string& text) method.
@note By default the style markup processor is disabled. @see Dali::Toolkit::TextView::SetMarkupProcessingEnabled to enable the markup processing.
*
*
* See \link markup-processor Markup Processor \endlink for more details on how to create styling markup strings and styled text arrays.
*
* \section retrieve Retrieve text layout information
*
* The Dali::Toolkit::TextView::GetTextLayoutInfo() retrieves how the input text has been laid out.
*
* For each character it retrieves its size and position, visibility, etc. @see Dali::Toolkit::TextView::CharacterLayoutInfo.
*
* For each laid-out line it retrieves the index of the first character of the line, size, etc. @see Dali::Toolkit::TextView::LineLayoutInfo.
*
* \section appendix Appendix
* \subsection examples Examples
*
* 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.
*
* Creation of a text view actor with all its parameters by default.
* \code
* Toolkit::TextView textView = Toolkit::TextView::New( "Hello world!" );
* textView.SetParentOrigin( ParentOrigin::CENTER );
*
* Stage::GetCurrent().Add( textView );
* \endcode
*
* 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.
* \code
* const std::string text( ""
* "Lorem ipsum dolor sit amet, consectetur adipisicing elit,\n"
* "sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
* "" );
*
* Toolkit::TextView textView = Toolkit::TextView::New( "" );
* textView.SetMarkupProcessingEnabled( true );
* textView.SetText( text );
* textView.SetParentOrigin( ParentOrigin::CENTER );
*
* textView.SetMultilinePolicy( Toolkit::TextView::SplitByNewLineChar );
* textView.SetWidthExceedPolicy( Toolkit::TextView::Original );
* textView.SetHeightExceedPolicy( Toolkit::TextView::Original );
* textView.SetLineJustification( Toolkit::TextView::Center );
*
* Stage::GetCurrent().Add( textView );
* \endcode
* \image html text-view/text-view-example-01.png
*
* 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.
*
* \code
* const std::string text( ""
* "Lorem ipsum dolor sit amet, consectetur adipisicing elit, "
* "sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
* "" );
*
* Toolkit::TextView textView = Toolkit::TextView::New( "" );
* textView.SetMarkupProcessingEnabled( true );
* textView.SetText( text );
* textView.SetParentOrigin( ParentOrigin::CENTER );
* textView.SetSize( 300.f, 125.f );
*
* textView.SetMultilinePolicy( Toolkit::TextView::SplitByWord );
* textView.SetWidthExceedPolicy( Toolkit::TextView::Original );
* textView.SetHeightExceedPolicy( Toolkit::TextView::Original );
* textView.SetLineJustification( Toolkit::TextView::Center );
*
* Stage::GetCurrent().Add( textView );
* \endcode
* \image html text-view/text-view-example-02.png
*
* 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.
*
* \code
* const std::string text( ""
* "Loremipsumdolorsitametconsectetur adipisicing elit,\n"
* "sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
* "" );
* const std::string ellipsizeText( "..." );
*
* Toolkit::TextView textView = Toolkit::TextView::New( "" );
* textView.SetMarkupProcessingEnabled( true );
* textView.SetText( text );
* textView.SetEllipsizeText( ellipsizeText );
* textView.SetParentOrigin( ParentOrigin::CENTER );
* textView.SetSize( 300.f, 125.f );
*
* textView.SetMultilinePolicy( Toolkit::TextView::SplitByWord );
* textView.SetWidthExceedPolicy( Toolkit::TextView::Split );
* textView.SetHeightExceedPolicy( Toolkit::TextView::EllipsizeEnd );
* textView.SetLineJustification( Toolkit::TextView::Center );
*
* Stage::GetCurrent().Add( textView );
* \endcode
* \image html text-view/text-view-example-03.png
*
* This example is similar to the one above but the ellipsized text has been set to "" so nothing is shown.
*
* \code
* const std::string text( ""
* "Loremipsumdolorsitametconsecteturadipisicingelit"
* "seddoeiusmodtemporincididuntutlaboreetdoloremagnaaliqua."
* "" );
* const std::string ellipsizeText( "" );
*
* Toolkit::TextView textView = Toolkit::TextView::New( "" );
* textView.SetMarkupProcessingEnabled( true );
* textView.SetText( text );
* textView.SetEllipsizeText( ellipsizeText );
* textView.SetParentOrigin( ParentOrigin::CENTER );
* textView.SetSize( 300.f, 125.f );
*
* textView.SetMultilinePolicy( Toolkit::TextView::SplitByWord );
* textView.SetWidthExceedPolicy( Toolkit::TextView::Split );
* textView.SetHeightExceedPolicy( Toolkit::TextView::EllipsizeEnd );
* textView.SetLineJustification( Toolkit::TextView::Center );
*
* Stage::GetCurrent().Add( textView );
* \endcode
* \image html text-view/text-view-example-04.png
*
* This example shows how to fade the text out when it exceeds the boundaries of the text-view.
*
* \code
* const std::string text( ""
* "Lorem ipsum dolor sit amet,\n"
* "consectetur adipisicing elit,\n"
* "sed do eiusmod tempor incididunt\n"
* "ut labore et dolore magna aliqua."
* "" );
*
* Toolkit::TextView textView = Toolkit::TextView::New();
* textView.SetMarkupProcessingEnabled( true );
* textView.SetText( text );
* textView.SetParentOrigin( ParentOrigin::CENTER );
* textView.SetSize( 300.f, 100.f );
*
* Toolkit::TextView::FadeBoundary fadeBoundary( PixelSize( 10 ), PixelSize( 10 ), PixelSize( 10 ), PixelSize( 10 ) );
* textView.SetFadeBoundary( fadeBoundary );
*
* textView.SetMultilinePolicy( Toolkit::TextView::SplitByNewLineChar );
* textView.SetWidthExceedPolicy( Toolkit::TextView::Fade );
* textView.SetHeightExceedPolicy( Toolkit::TextView::Fade );
* textView.SetLineJustification( Toolkit::TextView::Center );
*
* Stage::GetCurrent().Add( textView );
* \endcode
* \image html text-view/text-view-example-05.png
*
* This example enables the scroll feature. The screen-shots show three different images of the same text in different scroll positions.
*
* \code
* const std::string text( ""
* "Lorem ipsum dolor sit amet, consectetur adipisicing elit,\n"
* "sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
* "" );
*
* Toolkit::TextView textView = Toolkit::TextView::New();
* textView.SetMarkupProcessingEnabled( true );
* textView.SetText( text );
* textView.SetParentOrigin( ParentOrigin::CENTER );
* textView.SetSize( 300.f, 60.f );
*
* textView.SetMultilinePolicy( Toolkit::TextView::SplitByNewLineChar );
* textView.SetWidthExceedPolicy( Toolkit::TextView::Original );
* textView.SetHeightExceedPolicy( Toolkit::TextView::Original );
* textView.SetLineJustification( Toolkit::TextView::Center );
*
* textView.SetScrollEnabled( true );
*
* Stage::GetCurrent().Add( textView );
* \endcode
* \image html text-view/text-view-example-06.png
* \image html text-view/text-view-example-07.png
* \image html text-view/text-view-example-08.png
*
* See \link markup-processor Markup Processor \endlink \ref example for more styling markup string examples.
*
* \subsection exceed_policies_combinations Implemented exceed policies combinations
*
* 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),
* each row has one height exceed policy (Original, Fade, ShrinkToFit and EllipsizeEnd).
*
* @note The Split value is not valid for the height exceed policy.
*
* \htmlonly
*
*
* SplitByNewLineChar |
*
*
* | Width exceed policies |
*
*
* Original | Fade | Split | ShrinkToFit | EllipsizeEnd |
*
*
* Height exceed policies |
* Original |
* ✓ |
* ✓ |
* ✓ |
* ✓ |
* ✓ |
*
*
* Fade |
* ✓ |
* ✓ |
* ✓ |
* ✗ |
* ✗ |
*
*
* ShrinkToFit |
* ✗ |
* ✗ |
* ✗ |
* ✓ |
* ✗ |
*
*
* EllipsizeEnd |
* ✗ |
* ✗ |
* ✓ |
* ✗ |
* ✓ |
*
*
* \endhtmlonly
*
* \n
*
* \htmlonly
*
*
* SplitByWord |
*
*
* | Width exceed policies |
*
*
* Original | Fade | Split | ShrinkToFit | EllipsizeEnd |
*
*
* Height exceed policies |
* Original |
* ✓ |
* ✓ |
* ✓ |
* ✓ |
* ✓ |
*
*
* Fade |
* ✓ |
* ✓ |
* ✓ |
* ✗ |
* ✗ |
*
*
* ShrinkToFit |
* ✗ |
* ✗ |
* ✗ |
* ✓ |
* ✗ |
*
*
* EllipsizeEnd |
* ✗ |
* ✗ |
* ✓ |
* ✗ |
* ✓ |
*
*
* \endhtmlonly
*
* \n
*
* \htmlonly
*
*
* SplitByChar |
*
*
* | Width exceed policies |
*
*
* Original | Fade | Split | ShrinkToFit | EllipsizeEnd |
*
*
* Height exceed policies |
* Original |
* ✓ |
* ✓ |
* ✗ |
* ✗ |
* ✗ |
*
*
* Fade |
* ✓ |
* ✓ |
* ✗ |
* ✗ |
* ✗ |
*
*
* ShrinkToFit |
* ✗ |
* ✗ |
* ✗ |
* ✗ |
* ✗ |
*
*
* EllipsizeEnd |
* ✗ |
* ✗ |
* ✗ |
* ✗ |
* ✗ |
*
*
* \endhtmlonly
*/