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 * @brief The start and end property ranges for this control.
60 PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1,
61 PROPERTY_END_INDEX = PROPERTY_START_INDEX + 1000 ///< Reserve property indices
65 * @brief An enumeration of properties belonging to the TextView class.
71 MARKUP_ENABLED = PROPERTY_START_INDEX, ///< name "markup-enabled", @see SetMarkupProcessingEnabled(), type BOOLEAN
72 TEXT, ///< name "text", @see SetText(), type STRING
73 MULTILINE_POLICY, ///< name "multiline-policy", @see SetMultilinePolicy(), type STRING
74 WIDTH_EXCEED_POLICY, ///< name "width-exceed-policy", @see SetWidthExceedPolicy(), type STRING
75 HEIGHT_EXCEED_POLICY, ///< name "height-exceed-policy", @see SetHeightExceedPolicy(), type STRING
76 LINE_JUSTIFICATION, ///< name "line-justification", @see SetLineJustification(), type STRING
77 FADE_BOUNDARY, ///< name "fade-boundary", @see SetFadeBoundary(), type VECTOR4
78 LINE_HEIGHT_OFFSET, ///< name "line-height-offset", @see SetLineHeightOffset(), type FLOAT
79 HORIZONTAL_ALIGNMENT, ///< name "horizontal-alignment", @see SetTextAlignment(), type STRING
80 VERTICAL_ALIGNMENT, ///< name "vertical-alignment", @see SetTextAlignment(), type STRING
85 * @brief Structure used to retrieve Layout info per character.
87 struct CharacterLayoutInfo
90 * @brief Default constructor.
92 * Initializes all members to their default values.
94 CharacterLayoutInfo();
97 * @brief Empty destructor.
99 * @note Added to increase coverage.
101 ~CharacterLayoutInfo();
104 * @brief Copy constructor.
106 CharacterLayoutInfo( const CharacterLayoutInfo& characterLayoutInfo );
109 * @brief Assignment operator.
111 CharacterLayoutInfo& operator=( const CharacterLayoutInfo& character );
114 * @brief Constructor.
116 * @param[in] size of the character.
117 * @param[in] position of the character.
118 * @param[in] isNewParagraphChar Whether the character is a new paragraph character.
119 * @param[in] isRightToLeftCharacter Whether is a right to left character.
120 * @param[in] visible Whether is visible.
121 * @param[in] descender of the character (distance from the base line to the bottom of the character.)
123 CharacterLayoutInfo( const Size& size,
124 const Vector3& position,
125 bool isNewParagraphChar,
126 bool isRightToLeftCharacter,
130 Size mSize; ///< Size of the character.
131 Vector3 mPosition; ///< Position of the character within the text view.
132 bool mIsNewLineChar:1; ///< @deprecated. Use mIsNewParagraphChar instead.
133 bool mIsNewParagraphChar:1; ///< Whether this character represent a new paragraph.
134 bool mIsRightToLeftCharacter:1; ///< Whether it's a right-to-left character.
135 bool mIsVisible:1; ///< Whether this character is visible or not.
136 float mDescender; ///< The character's descender which is the distance from the baseline to the bottom of the character
139 typedef std::vector<CharacterLayoutInfo> CharacterLayoutInfoContainer; ///< Container of layout info per character.
142 * @brief Stores some info about a line.
144 struct LineLayoutInfo
146 std::size_t mCharacterGlobalIndex; ///< Global index within the whole text of the first character of current line.
147 Size mSize; ///< Size of the current line.
148 float mAscender; ///< The max ascender of the current line.
151 typedef std::vector<LineLayoutInfo> LineLayoutInfoContainer; ///< Container of layout info per line.
154 * @brief How text is laid out.
156 struct TextLayoutInfo
159 * @brief Default constructor.
164 * @brief Empty destructor.
166 * @note Added to increase coverage.
171 * @brief Copy constructor.
173 TextLayoutInfo( const TextLayoutInfo& textLayoutInfo );
176 * @brief Assignment operator.
178 TextLayoutInfo& operator=( const TextLayoutInfo& textLayoutInfo );
180 CharacterLayoutInfoContainer mCharacterLayoutInfoTable; ///< The table of character's positions and sizes sorted by the character's visual index.
181 LineLayoutInfoContainer mLines; ///< For each line, it stores an index to the first character of the line.
182 std::vector<int> mCharacterLogicalToVisualMap; ///< The map to store the character's logical (input) index according to its visual (reordered) index.
183 std::vector<int> mCharacterVisualToLogicalMap; ///< The map to store the character's visual (reordered) index according to its logical (input) index.
184 Size mTextSize; ///< Text size after relayout.
185 Vector2 mScrollOffset; ///< Scroll's position.
189 * @brief This structure represents a fade boundary.
191 * 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.
192 * 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.
197 * @brief Default constructor.
199 * Initializes all values to 0. It means no fade boundary.
204 * @brief Constructor.
206 * Initializes the fade boundary with the given values.
208 * @param[in] left value in pixels.
209 * @param[in] right value in pixels.
210 * @param[in] top value in pixels.
211 * @param[in] bottom value in pixels.
213 FadeBoundary( PixelSize left, PixelSize right, PixelSize top, PixelSize bottom );
215 PixelSize mLeft; ///< The left fade boundary
216 PixelSize mRight; ///< The right fade boundary
217 PixelSize mTop; ///< The top fade boundary
218 PixelSize mBottom; ///< The bottom fade bounday
222 * @brief Define how to wrap the text's paragraphs in lines.
224 * \e SplitByNewLineChar will wrap the text's paragraphs in lines when a '\\n' character or a \<br /\> is found.
225 * \e SplitByWord has effect only when TextView size is assigned.
226 * 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.
227 * \e SplitByChar has effect only when TextView size is assigned.
228 * 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.
229 * The default value is \e SplitByNewLineChar.
233 SplitByNewLineChar, ///< Text's paragraphs will wrap in lines when '\\n' character is found.
234 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.
235 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.
239 * @brief Define how to display the lines when they doesn't fit inside the TextView after the text's paragraphs are wrapped in lines.
241 * The default value is \e Original.
245 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.
246 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.
247 Split, ///< Will split the lines in a new line(s).
248 ShrinkToFit, ///< Will shrink the lines to fit the TextView boundary.
249 EllipsizeEnd ///< Will ellipsize the lines by the end.
253 * @brief Define how to justify lines inside the text's boundary.
255 * The default value is \e Left.
257 enum LineJustification
259 Left, ///< Justify to the left.
260 Center, ///< Centered.
261 Right, ///< Justify to the right.
262 Justified ///< Line justified.
267 * @brief Create a TextView handle; this can be initialised with TextView::New().
269 * Calling member functions with an uninitialised Dali::Object handle is not allowed.
274 * @brief Copy constructor.
276 * Creates another handle that points to the same real object
277 * @param[in] handle The handle to copy from
279 TextView( const TextView& handle );
282 * @brief Assignment operator.
284 * Changes this handle to point to another real object
285 * @param[in] handle The handle to copy from
286 * @return a reference to this
288 TextView& operator=( const TextView& handle );
291 * @brief Create a TextView control with no text.
293 * @return A handle the TextView control.
295 static TextView New();
298 * @brief Create a TextView control.
300 * @param[in] text to display.
301 * @return A handle the TextView control.
303 static TextView New( const std::string& text );
306 * @brief Create a TextView control with styled text.
308 * @param[in] text The text with style to display.
309 * @return A handle the TextView control.
311 static TextView New( const MarkupProcessor::StyledTextArray& text );
314 * @brief Downcast an Object handle to TextView.
316 * If handle points to a TextView the
317 * downcast produces valid handle. If not the returned handle is left uninitialized.
318 * @param[in] handle Handle to an object
319 * @return handle to a TextView or an uninitialized handle
321 static TextView DownCast( BaseHandle handle );
326 * This is non-virtual since derived Handle types must not contain data or virtual methods.
331 * @brief Replace the current text with a new text string.
333 * @param[in] text to display. The string may contain style tags.
335 void SetText( const std::string& text );
338 * @brief Replace the current text with a new text string with style.
340 * @param[in] text The text with style to display.
342 void SetText( const MarkupProcessor::StyledTextArray& text );
345 * @brief Inserts the given text in the specified position.
347 * @param[in] position Where the given text is going to be added.
348 * @param[in] text The text to be added.
350 void InsertTextAt( std::size_t position, const std::string& text );
353 * @brief Inserts the given text with style in the specified position.
355 * @param[in] position Where the given text is going to be added.
356 * @param[in] text The text with style to be added.
358 void InsertTextAt( std::size_t position, const MarkupProcessor::StyledTextArray& text );
361 * @brief Replaces part of the text.
363 * It removes the specified number of characters from the given position and inserts the given text in the same specified position.
365 * @param[in] position of the first character to be removed and Where the given text is going to be added.
366 * @param[in] numberOfCharacters number of characters to be removed.
367 * @param[in] text The text to be added.
369 void ReplaceTextFromTo( std::size_t position, std::size_t numberOfCharacters, const std::string& text );
372 * @brief Replaces part of the text.
374 * It removes the specified number of characters from the given position and inserts the given text with style in the same specified position.
376 * @param[in] position of the first character to be removed and Where the given text is going to be added.
377 * @param[in] numberOfCharacters number of characters to be removed.
378 * @param[in] text The text with style to be added.
380 void ReplaceTextFromTo( std::size_t position, std::size_t numberOfCharacters, const MarkupProcessor::StyledTextArray& text );
383 * @brief Removes the specified number of characters from the given position.
385 * @param[in] position of the first character to be removed.
386 * @param[in] numberOfCharacters number of characters to be removed.
388 void RemoveTextFrom( std::size_t position, std::size_t numberOfCharacters );
391 * @brief Get the currently displayed text.
393 * @return The currently displayed text.
395 std::string GetText() const;
398 * @brief Sets a line height offset.
400 * The line height offset will be added to the font line height.
401 * @param [in] offset The height offset in PointSize units.
403 void SetLineHeightOffset( PointSize offset );
406 * @brief Retrieves the line height offset.
408 * @return The line height offset in PointSize units.
410 PointSize GetLineHeightOffset() const;
413 * @brief Sets the given style to the current text.
415 * By default all style settings are applied but a bit mask could be used to modify only certain style settings.
416 * @note TextView doesn't store a copy of the given style, it applies the given style to the current text only.
417 * Subsequent calls to SetText() will override any style set by this method.
418 * @param[in] style The given style
419 * @param[in] mask The bit mask.
421 void SetStyleToCurrentText( const TextStyle& style, TextStyle::Mask mask = TextStyle::ALL );
424 * @brief Set the current text alignment.
426 * Default alignment is (HorizontalCenter | VerticalCenter)
427 * @param[in] align The new alignment option.
429 void SetTextAlignment( Alignment::Type align );
432 * @brief Get the current text alignment combined into a single value.
434 * The values can be tested by using the & operator
435 * and the desired flag. e.g. if (GetTextAlignment() & HorizontalCentre) ...
436 * @return the combined alignment
438 Alignment::Type GetTextAlignment() const;
441 * @brief Sets how to split the paragraphs into lines.
443 * @param policy The multi-line policy. \e SplitByNewLineChar is set by default.
445 void SetMultilinePolicy( MultilinePolicy policy );
448 * @brief Gets the wrap in lines policy.
450 * @return The multi-line policy.
452 MultilinePolicy GetMultilinePolicy() const;
455 * @brief Sets how to display the text inside the TextView when it exceeds the text-view's width.
457 * @param policy The exceed policy. Original is set by default.
459 void SetWidthExceedPolicy( ExceedPolicy policy );
462 * @brief Gets the width exceed policy.
464 * @return The exceed policy.
466 ExceedPolicy GetWidthExceedPolicy() const;
469 * @brief Sets how to display the text inside the TextView when it exceeds the text-view's height.
471 * @param policy The exceed policy. Original is set by default.
473 void SetHeightExceedPolicy( ExceedPolicy policy );
476 * @brief Gets the height exceed policy.
478 * @return The exceed policy.
480 ExceedPolicy GetHeightExceedPolicy() const;
483 * @brief Sets how to justify lines inside the text's boundary.
485 * @param justification The line justification. Left is set by default.
487 void SetLineJustification( LineJustification justification );
490 * @brief Gets the line justification.
492 * @return The line justification.
494 LineJustification GetLineJustification() const;
497 * @brief Sets a fade boundary.
501 * @param[in] fadeBoundary The given fade boundary.
503 void SetFadeBoundary( const FadeBoundary& fadeBoundary );
506 * @brief Retrieves the fade boundary.
510 * @return The fade boundary.
512 const FadeBoundary& GetFadeBoundary() const;
515 * @brief Sets the ellipsize text.
517 * @param[in] ellipsizeText The new text. The string may contain style tags. By default the ellipsize text is '...'
519 void SetEllipsizeText( const std::string& ellipsizeText );
522 * @brief Sets the ellipsize text with style.
524 * @param[in] ellipsizeText The new text with its style.
526 void SetEllipsizeText( const MarkupProcessor::StyledTextArray& ellipsizeText );
529 * @brief Retrieves the ellipsize text.
531 * @return The ellipsize text.
533 std::string GetEllipsizeText() const;
536 * @brief A mechanism to retrieve layout information from the TextView.
538 * It produces a vector of CharcterLayoutInfo structures which describe the size and position of each character,
539 * two vectors which maps the logical and visual positions of the characters in a bidirectional text, the size
540 * of the whole laid-out text and the scroll offset value.
542 * @see TextLayoutInfo.
544 * @param[out] textLayoutInfo A structure with text layout information.
546 void GetTextLayoutInfo( TextLayoutInfo& textLayoutInfo );
549 * @brief Allows modification of text-actor's position in the depth sort algorithm.
551 * @see Dali::RenderableActor::SetSortModifier()
552 * @param [in] depthOffset the offset to be given to the internal text-actors. Positive values pushing it further back.
554 void SetSortModifier( float depthOffset );
557 * @brief Sets whether text-view renders text using a previously generated snapshot.
559 * Rendering long text using a snapshot may increase performance. The default value is \e false (render without using a snapshot).
561 * @param[in] enable Whether text-view is using a snapshot to render text.
563 void SetSnapshotModeEnabled( bool enable );
566 * @brief Retrieves whether text-view is using a snapshot to render text.
568 * @return \e true if text-view is using a snapshot to render text, otherwhise it returns \e false.
570 bool IsSnapshotModeEnabled() const;
573 * @brief Sets whether markup processing should be carried out.
575 * To use markup, applications need to SetMarkupProcessingEnabled first, then SetText().
578 * @param[in] enable whether markup processing is carried out or not.
580 void SetMarkupProcessingEnabled( bool enable );
583 * @brief Retrieves whether text-view is processing markup text
585 * @return \e true if text-view markup processing is enabled, otherwhise it returns \e false.
587 bool IsMarkupProcessingEnabled() const;
590 * @brief Enables or disables the text scroll.
592 * When scroll is enabled, snapshot mode will be enabled automatically. Equally, if scroll is disabled
593 * the snapshot mode is restored to the previous value.
595 * @param[in] enable Whether to enable the text scroll.
597 void SetScrollEnabled( bool enable );
600 * @brief Retrieves whether the text scroll is enabled.
602 * @return \e true if the scroll is enabled.
604 bool IsScrollEnabled() const;
607 * @brief Sets a new scroll position.
609 * The new scroll position set could be trimmed if the text doesn't cover the whole text-view.
610 * i.e. If a text-view is 100x100 and a text is 200x100 a scroll position beyond 50x0 will be trimmed to 50x0.
612 * Call IsScrollPositionTrimmed() to know if the last scroll position set has been trimmed.
614 * A signal is emitted. @see ScrolledSignal().
616 * @param[in] position The new scroll position.
618 void SetScrollPosition( const Vector2& position );
621 * @brief Recrieves current scroll position.
623 * @return The scroll position.
625 const Vector2& GetScrollPosition() const;
628 * @brief Whether the last scroll position set was trimmed.
630 * @return \e true if the last scroll position set was trimmed, otherwise \e false.
632 bool IsScrollPositionTrimmed() const;
635 /// @brief Signal types
636 typedef Signal< void ( TextView textView, Vector2 scrollDelta ) > ScrolledSignalType;
639 * @brief Signal emitted when the text is scrolled inside the text-view.
641 * A callback with the following prototype can be connected to this signal.
643 * Callback(TextView textView, Vector2 scrollDelta)
645 * \e textView is the handle of the text-view emitting the signal.
646 * \e scrollDelta is the differente of the current scroll position with the previous one.
647 * @return The signal to connect to
649 ScrolledSignalType& ScrolledSignal();
651 public: // Not intended for application developers
654 * @brief Creates a handle using the Toolkit::Internal implementation.
655 * @note Not intended for application developers
657 * @param[in] implementation The Control implementation.
659 DALI_INTERNAL TextView( Internal::TextView& implementation );
662 * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
663 * @note Not intended for application developers
665 * @param[in] internal A pointer to the internal CustomActor.
667 explicit DALI_INTERNAL TextView( Dali::Internal::CustomActor* internal );
670 } // namespace Toolkit
674 #endif // __DALI_TOOLKIT_ITEM_VIEW_H__