1 #ifndef __DALI_TOOLKIT_TEXT_VIEW_H__
2 #define __DALI_TOOLKIT_TEXT_VIEW_H__
5 * Copyright (c) 2014 Samsung Electronics Co., Ltd.
7 * Licensed under the Apache License, Version 2.0 (the "License");
8 * you may not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
11 * http://www.apache.org/licenses/LICENSE-2.0
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
25 #include <dali-toolkit/public-api/controls/alignment/alignment.h>
26 #include <dali-toolkit/public-api/markup-processor/markup-processor.h>
34 namespace Internal DALI_INTERNAL
40 * @brief The TextView class is a UI Dali::Toolkit::Control designed to extend the capabilities of the basic Dali::TextActor.
42 * It provides support for multi-line wrapping, multi-language font detection, text alignment, scrolling and styling.
44 * See the \link text-view Text View \endlink page of the Programming Guide for more details and examples.
47 * | %Signal Name | Method |
48 * |-------------------|---------------------------|
49 * | scrolled | @ref ScrolledSignal() |
51 class DALI_IMPORT_API TextView : public Control
56 static const Property::Index PROPERTY_MARKUP_ENABLED; ///< name "markup-enabled", @see SetMarkupProcessingEnabled(), type BOOLEAN
57 static const Property::Index PROPERTY_TEXT; ///< name "text", @see SetText(), type STRING
58 static const Property::Index PROPERTY_MULTILINE_POLICY; ///< name "multiline-policy", @see SetMultilinePolicy(), type STRING
59 static const Property::Index PROPERTY_WIDTH_EXCEED_POLICY; ///< name "width-exceed-policy", @see SetWidthExceedPolicy(), type STRING
60 static const Property::Index PROPERTY_HEIGHT_EXCEED_POLICY; ///< name "height-exceed-policy", @see SetHeightExceedPolicy(), type STRING
61 static const Property::Index PROPERTY_LINE_JUSTIFICATION; ///< name "line-justification", @see SetLineJustification(), type STRING
62 static const Property::Index PROPERTY_FADE_BOUNDARY; ///< name "fade-boundary", @see SetFadeBoundary(), type VECTOR4
63 static const Property::Index PROPERTY_LINE_HEIGHT_OFFSET; ///< name "line-height-offset", @see SetLineHeightOffset(), type FLOAT
64 static const Property::Index PROPERTY_HORIZONTAL_ALIGNMENT; ///< name "horizontal-alignment", @see SetTextAlignment(), type STRING
65 static const Property::Index PROPERTY_VERTICAL_ALIGNMENT; ///< name "vertical-alignment", @see SetTextAlignment(), type STRING
68 * @brief Structure used to retrieve Layout info per character.
70 struct CharacterLayoutInfo
73 * @brief Default constructor.
75 * Initializes all members to their default values.
77 CharacterLayoutInfo();
80 * @brief Empty destructor.
82 * @note Added to increase coverage.
84 ~CharacterLayoutInfo();
87 * @brief Copy constructor.
89 CharacterLayoutInfo( const CharacterLayoutInfo& characterLayoutInfo );
92 * @brief Assignment operator.
94 CharacterLayoutInfo& operator=( const CharacterLayoutInfo& character );
99 * @param[in] size of the character.
100 * @param[in] position of the character.
101 * @param[in] isNewParagraphChar Whether the character is a new paragraph character.
102 * @param[in] isRightToLeftCharacter Whether is a right to left character.
103 * @param[in] visible Whether is visible.
104 * @param[in] descender of the character (distance from the base line to the bottom of the character.)
106 CharacterLayoutInfo( const Size& size,
107 const Vector3& position,
108 bool isNewParagraphChar,
109 bool isRightToLeftCharacter,
113 Size mSize; ///< Size of the character.
114 Vector3 mPosition; ///< Position of the character within the text view.
115 bool mIsNewLineChar:1; ///< @deprecated. Use mIsNewParagraphChar instead.
116 bool mIsNewParagraphChar:1; ///< Whether this character represent a new paragraph.
117 bool mIsRightToLeftCharacter:1; ///< Whether it's a right-to-left character.
118 bool mIsVisible:1; ///< Whether this character is visible or not.
119 float mDescender; ///< The character's descender which is the distance from the baseline to the bottom of the character
122 typedef std::vector<CharacterLayoutInfo> CharacterLayoutInfoContainer; ///< Container of layout info per character.
125 * @brief Stores some info about a line.
127 struct LineLayoutInfo
129 std::size_t mCharacterGlobalIndex; ///< Global index within the whole text of the first character of current line.
130 Size mSize; ///< Size of the current line.
131 float mAscender; ///< The max ascender of the current line.
134 typedef std::vector<LineLayoutInfo> LineLayoutInfoContainer; ///< Container of layout info per line.
137 * @brief How text is laid out.
139 struct TextLayoutInfo
142 * @brief Default constructor.
147 * @brief Empty destructor.
149 * @note Added to increase coverage.
154 * @brief Copy constructor.
156 TextLayoutInfo( const TextLayoutInfo& textLayoutInfo );
159 * @brief Assignment operator.
161 TextLayoutInfo& operator=( const TextLayoutInfo& textLayoutInfo );
163 CharacterLayoutInfoContainer mCharacterLayoutInfoTable; ///< The table of character's positions and sizes sorted by the character's visual index.
164 LineLayoutInfoContainer mLines; ///< For each line, it stores an index to the first character of the line.
165 std::vector<int> mCharacterLogicalToVisualMap; ///< The map to store the character's logical (input) index according to its visual (reordered) index.
166 std::vector<int> mCharacterVisualToLogicalMap; ///< The map to store the character's visual (reordered) index according to its logical (input) index.
167 Size mTextSize; ///< Text size after relayout.
168 Vector2 mScrollOffset; ///< Scroll's position.
172 * @brief This structure represents a fade boundary.
174 * If the Exceed policy is set to Fade all text which does not fit within the text-view fade boundary is faded out. Text which exceeds the text-view boundary becomes invisible.
175 * The \e left, \e right, \e top and \e bottom values are positive, in pixels and set the distances between the text-view and fade boundaries.
180 * @brief Default constructor.
182 * Initializes all values to 0. It means no fade boundary.
187 * @brief Constructor.
189 * Initializes the fade boundary with the given values.
191 * @param[in] left value in pixels.
192 * @param[in] right value in pixels.
193 * @param[in] top value in pixels.
194 * @param[in] bottom value in pixels.
196 FadeBoundary( PixelSize left, PixelSize right, PixelSize top, PixelSize bottom );
198 PixelSize mLeft; ///< The left fade boundary
199 PixelSize mRight; ///< The right fade boundary
200 PixelSize mTop; ///< The top fade boundary
201 PixelSize mBottom; ///< The bottom fade bounday
205 * @brief Define how to wrap the text's paragraphs in lines.
207 * \e SplitByNewLineChar will wrap the text's paragraphs in lines when a '\\n' character or a \<br /\> is found.
208 * \e SplitByWord has effect only when TextView size is assigned.
209 * It will wrap the text's paragraphs in lines when a '\\n' character or a \<br /\> is found or if a paragraph exceeds the TextView's boundary. This option won't split a word in two.
210 * \e SplitByChar has effect only when TextView size is assigned.
211 * It will wrap the text's paragraphs in lines when a '\\n' character or a \<br /\> is found or if a paragraph exceeds the TextView's boundary. This option might split a word in two.
212 * The default value is \e SplitByNewLineChar.
216 SplitByNewLineChar, ///< Text's paragraphs will wrap in lines when '\\n' character is found.
217 SplitByWord, ///< Text's paragraphs will wrap in lines by word or if '\\n' character is found. It has effect only when TextView size is assigned.
218 SplitByChar ///< Text's paragraphs will wrap in lines by char or if '\\n' character is found. It has effect only when TextView size is assigned.
222 * @brief Define how to display the lines when they doesn't fit inside the TextView after the text's paragraphs are wrapped in lines.
224 * The default value is \e Original.
228 Original, ///< Will display the lines in their original size. If a line, a word or a character is bigger than the TextView size it may exceed its boundary.
229 Fade, ///< Will display the lines in their original size. It won't display the part of the line which exceeds the TextView boundary. It fades the text out.
230 Split, ///< Will split the lines in a new line(s).
231 ShrinkToFit, ///< Will shrink the lines to fit the TextView boundary.
232 EllipsizeEnd ///< Will ellipsize the lines by the end.
236 * @brief Define how to justify lines inside the text's boundary.
238 * The default value is \e Left.
240 enum LineJustification
242 Left, ///< Justify to the left.
243 Center, ///< Centered.
244 Right, ///< Justify to the right.
245 Justified ///< Line justified.
250 * @brief Create a TextView handle; this can be initialised with TextView::New().
252 * Calling member functions with an uninitialised Dali::Object handle is not allowed.
257 * @brief Copy constructor.
259 * Creates another handle that points to the same real object
260 * @param[in] handle The handle to copy from
262 TextView( const TextView& handle );
265 * @brief Assignment operator.
267 * Changes this handle to point to another real object
268 * @param[in] handle The handle to copy from
269 * @return a reference to this
271 TextView& operator=( const TextView& handle );
274 * @brief Create a TextView control with no text.
276 * @return A handle the TextView control.
278 static TextView New();
281 * @brief Create a TextView control.
283 * @param[in] text to display.
284 * @return A handle the TextView control.
286 static TextView New( const std::string& text );
289 * @brief Create a TextView control with styled text.
291 * @param[in] text The text with style to display.
292 * @return A handle the TextView control.
294 static TextView New( const MarkupProcessor::StyledTextArray& text );
297 * @brief Downcast an Object handle to TextView.
299 * If handle points to a TextView the
300 * downcast produces valid handle. If not the returned handle is left uninitialized.
301 * @param[in] handle Handle to an object
302 * @return handle to a TextView or an uninitialized handle
304 static TextView DownCast( BaseHandle handle );
309 * This is non-virtual since derived Handle types must not contain data or virtual methods.
314 * @brief Replace the current text with a new text string.
316 * @param[in] text to display. The string may contain style tags.
318 void SetText( const std::string& text );
321 * @brief Replace the current text with a new text string with style.
323 * @param[in] text The text with style to display.
325 void SetText( const MarkupProcessor::StyledTextArray& text );
328 * @brief Inserts the given text in the specified position.
330 * @param[in] position Where the given text is going to be added.
331 * @param[in] text The text to be added.
333 void InsertTextAt( std::size_t position, const std::string& text );
336 * @brief Inserts the given text with style in the specified position.
338 * @param[in] position Where the given text is going to be added.
339 * @param[in] text The text with style to be added.
341 void InsertTextAt( std::size_t position, const MarkupProcessor::StyledTextArray& text );
344 * @brief Replaces part of the text.
346 * It removes the specified number of characters from the given position and inserts the given text in the same specified position.
348 * @param[in] position of the first character to be removed and Where the given text is going to be added.
349 * @param[in] numberOfCharacters number of characters to be removed.
350 * @param[in] text The text to be added.
352 void ReplaceTextFromTo( std::size_t position, std::size_t numberOfCharacters, const std::string& text );
355 * @brief Replaces part of the text.
357 * It removes the specified number of characters from the given position and inserts the given text with style in the same specified position.
359 * @param[in] position of the first character to be removed and Where the given text is going to be added.
360 * @param[in] numberOfCharacters number of characters to be removed.
361 * @param[in] text The text with style to be added.
363 void ReplaceTextFromTo( std::size_t position, std::size_t numberOfCharacters, const MarkupProcessor::StyledTextArray& text );
366 * @brief Removes the specified number of characters from the given position.
368 * @param[in] position of the first character to be removed.
369 * @param[in] numberOfCharacters number of characters to be removed.
371 void RemoveTextFrom( std::size_t position, std::size_t numberOfCharacters );
374 * @brief Get the currently displayed text.
376 * @return The currently displayed text.
378 std::string GetText() const;
381 * @brief Sets a line height offset.
383 * The line height offset will be added to the font line height.
384 * @param [in] offset The height offset in PointSize units.
386 void SetLineHeightOffset( PointSize offset );
389 * @brief Retrieves the line height offset.
391 * @return The line height offset in PointSize units.
393 PointSize GetLineHeightOffset() const;
396 * @brief Sets the given style to the current text.
398 * By default all style settings are applied but a bit mask could be used to modify only certain style settings.
399 * @note TextView doesn't store a copy of the given style, it applies the given style to the current text only.
400 * Subsequent calls to SetText() will override any style set by this method.
401 * @param[in] style The given style
402 * @param[in] mask The bit mask.
404 void SetStyleToCurrentText( const TextStyle& style, TextStyle::Mask mask = TextStyle::ALL );
407 * @brief Set the current text alignment.
409 * Default alignment is (HorizontalCenter | VerticalCenter)
410 * @param[in] align The new alignment option.
412 void SetTextAlignment( Alignment::Type align );
415 * @brief Get the current text alignment combined into a single value.
417 * The values can be tested by using the & operator
418 * and the desired flag. e.g. if (GetTextAlignment() & HorizontalCentre) ...
419 * @return the combined alignment
421 Alignment::Type GetTextAlignment() const;
424 * @brief Sets how to split the paragraphs into lines.
426 * @param policy The multi-line policy. \e SplitByNewLineChar is set by default.
428 void SetMultilinePolicy( MultilinePolicy policy );
431 * @brief Gets the wrap in lines policy.
433 * @return The multi-line policy.
435 MultilinePolicy GetMultilinePolicy() const;
438 * @brief Sets how to display the text inside the TextView when it exceeds the text-view's width.
440 * @param policy The exceed policy. Original is set by default.
442 void SetWidthExceedPolicy( ExceedPolicy policy );
445 * @brief Gets the width exceed policy.
447 * @return The exceed policy.
449 ExceedPolicy GetWidthExceedPolicy() const;
452 * @brief Sets how to display the text inside the TextView when it exceeds the text-view's height.
454 * @param policy The exceed policy. Original is set by default.
456 void SetHeightExceedPolicy( ExceedPolicy policy );
459 * @brief Gets the height exceed policy.
461 * @return The exceed policy.
463 ExceedPolicy GetHeightExceedPolicy() const;
466 * @brief Sets how to justify lines inside the text's boundary.
468 * @param justification The line justification. Left is set by default.
470 void SetLineJustification( LineJustification justification );
473 * @brief Gets the line justification.
475 * @return The line justification.
477 LineJustification GetLineJustification() const;
480 * @brief Sets a fade boundary.
484 * @param[in] fadeBoundary The given fade boundary.
486 void SetFadeBoundary( const FadeBoundary& fadeBoundary );
489 * @brief Retrieves the fade boundary.
493 * @return The fade boundary.
495 const FadeBoundary& GetFadeBoundary() const;
498 * @brief Sets the ellipsize text.
500 * @param[in] ellipsizeText The new text. The string may contain style tags. By default the ellipsize text is '...'
502 void SetEllipsizeText( const std::string& ellipsizeText );
505 * @brief Sets the ellipsize text with style.
507 * @param[in] ellipsizeText The new text with its style.
509 void SetEllipsizeText( const MarkupProcessor::StyledTextArray& ellipsizeText );
512 * @brief Retrieves the ellipsize text.
514 * @return The ellipsize text.
516 std::string GetEllipsizeText() const;
519 * @brief A mechanism to retrieve layout information from the TextView.
521 * It produces a vector of CharcterLayoutInfo structures which describe the size and position of each character,
522 * two vectors which maps the logical and visual positions of the characters in a bidirectional text, the size
523 * of the whole laid-out text and the scroll offset value.
525 * @see TextLayoutInfo.
527 * @param[out] textLayoutInfo A structure with text layout information.
529 void GetTextLayoutInfo( TextLayoutInfo& textLayoutInfo );
532 * @brief Allows modification of text-actor's position in the depth sort algorithm.
534 * @see Dali::RenderableActor::SetSortModifier()
535 * @param [in] depthOffset the offset to be given to the internal text-actors. Positive values pushing it further back.
537 void SetSortModifier( float depthOffset );
540 * @brief Sets whether text-view renders text using a previously generated snapshot.
542 * Rendering long text using a snapshot may increase performance. The default value is \e false (render without using a snapshot).
544 * @param[in] enable Whether text-view is using a snapshot to render text.
546 void SetSnapshotModeEnabled( bool enable );
549 * @brief Retrieves whether text-view is using a snapshot to render text.
551 * @return \e true if text-view is using a snapshot to render text, otherwhise it returns \e false.
553 bool IsSnapshotModeEnabled() const;
556 * @brief Sets whether markup processing should be carried out.
558 * To use markup, applications need to SetMarkupProcessingEnabled first, then SetText().
561 * @param[in] enable whether markup processing is carried out or not.
563 void SetMarkupProcessingEnabled( bool enable );
566 * @brief Retrieves whether text-view is processing markup text
568 * @return \e true if text-view markup processing is enabled, otherwhise it returns \e false.
570 bool IsMarkupProcessingEnabled() const;
573 * @brief Enables or disables the text scroll.
575 * When scroll is enabled, snapshot mode will be enabled automatically. Equally, if scroll is disabled
576 * the snapshot mode is restored to the previous value.
578 * @param[in] enable Whether to enable the text scroll.
580 void SetScrollEnabled( bool enable );
583 * @brief Retrieves whether the text scroll is enabled.
585 * @return \e true if the scroll is enabled.
587 bool IsScrollEnabled() const;
590 * @brief Sets a new scroll position.
592 * The new scroll position set could be trimmed if the text doesn't cover the whole text-view.
593 * i.e. If a text-view is 100x100 and a text is 200x100 a scroll position beyond 50x0 will be trimmed to 50x0.
595 * Call IsScrollPositionTrimmed() to know if the last scroll position set has been trimmed.
597 * A signal is emitted. @see ScrolledSignal().
599 * @param[in] position The new scroll position.
601 void SetScrollPosition( const Vector2& position );
604 * @brief Recrieves current scroll position.
606 * @return The scroll position.
608 const Vector2& GetScrollPosition() const;
611 * @brief Whether the last scroll position set was trimmed.
613 * @return \e true if the last scroll position set was trimmed, otherwise \e false.
615 bool IsScrollPositionTrimmed() const;
618 /// @brief Signal types
619 typedef Signal< void ( TextView textView, Vector2 scrollDelta ) > ScrolledSignalType;
622 * @brief Signal emitted when the text is scrolled inside the text-view.
624 * A callback with the following prototype can be connected to this signal.
626 * Callback(TextView textView, Vector2 scrollDelta)
628 * \e textView is the handle of the text-view emitting the signal.
629 * \e scrollDelta is the differente of the current scroll position with the previous one.
630 * @return The signal to connect to
632 ScrolledSignalType& ScrolledSignal();
634 public: // Not intended for application developers
637 * @brief Creates a handle using the Toolkit::Internal implementation.
638 * @note Not intended for application developers
640 * @param[in] implementation The Control implementation.
642 DALI_INTERNAL TextView( Internal::TextView& implementation );
645 * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
646 * @note Not intended for application developers
648 * @param[in] internal A pointer to the internal CustomActor.
650 explicit DALI_INTERNAL TextView( Dali::Internal::CustomActor* internal );
653 } // namespace Toolkit
657 #endif // __DALI_TOOLKIT_ITEM_VIEW_H__