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.
22 * @addtogroup CAPI_DALI_TOOLKIT_TEXT_VIEW_MODULE
30 #include <dali-toolkit/public-api/controls/alignment/alignment.h>
31 #include <dali-toolkit/public-api/markup-processor/markup-processor.h>
33 namespace Dali DALI_IMPORT_API
39 namespace Internal DALI_INTERNAL
45 * @brief TextView is a layout container for text with alignment, multi-line wrapping and formatting support.
47 * Different multi-line and exceed policies could be chosen to represent the given text.
48 * \see Toolkit::TextView::SetMultilinePolicy \see Toolkit::TextView::SetExceedPolicy
50 * Multi-line policies:
52 * <li>\e Split by new line character.
53 * Text will split when a '\\n' character is found.
55 * <li>\e Split by word.
56 * Text will split when a '\\n' character is found or if the text doesn't fit in the text view width.
57 * In that case, some words will be moved to a new line.
59 * <li>\e Split by character.
60 * Text will split when a '\\n' character is found or if the text doesn't fit in the text view width.
61 * In that case, words which doesn't fit will be split in two and the remaining text moved to a new line.
64 * Exceed policies work in combination with multi-line policies:
66 * <li>\e Original size.
67 * Text will be displayed with its original size.
70 * Text will be truncated.
73 * Text will be faded out.
76 * Text will be split and moved to a new line.
78 * <li>\e Shrink to fit.
79 * Text will be shrink to fit in the text view's boundary.
81 * <li>\e EllipsizeEnd.
82 * Text will be ellipsized at the end.
86 * Text alignment could be set to align the whole text block inside the text view's boundary. \see Toolkit::TextView::SetTextAlignment.
88 * Line justification could be set to align lines inside a text block. \see Toolkit::TextView::SetLineJustification.
90 * A default font could be set through the \see Toolkit::TextView::SetFont method. If any font is set, text view automatically detects a suitable font for every character.
93 * 1) Use the font specified in text decoration.
94 * 2) Use automatic font detection.
96 * Integration with other classes (GetSizeAndPositionTable )
98 * Text decoration ( Color, Font, Size, italic and all features supported in TextActor )
100 class TextView : public Control
105 static const char* const SIGNAL_TEXT_SCROLLED; ///< Signal emitted when the scroll position changes. @see SignalScrolled()
108 static const Property::Index PROPERTY_MARKUP_ENABLED; ///< name "markup-enabled", @see SetMarkupProcessingEnabled(), type BOOLEAN
109 static const Property::Index PROPERTY_TEXT; ///< name "text", type STRING
110 static const Property::Index PROPERTY_MULTILINE_POLICY; ///< name "multiline-policy", type STRING
111 static const Property::Index PROPERTY_WIDTH_EXCEED_POLICY; ///< name "width-exceed-policy", type STRING
112 static const Property::Index PROPERTY_HEIGHT_EXCEED_POLICY; ///< name "height-exceed-policy", type STRING
113 static const Property::Index PROPERTY_LINE_JUSTIFICATION; ///< name "line-justification", type STRING
114 static const Property::Index PROPERTY_FADE_BOUNDARY; ///< name "fade-boundary", type VECTOR4
115 static const Property::Index PROPERTY_LINE_HEIGHT_OFFSET; ///< name "line-height-offset", type FLOAT
116 static const Property::Index PROPERTY_HORIZONTAL_ALIGNMENT; ///< name "horizontal-alignment", type STRING
117 static const Property::Index PROPERTY_VERTICAL_ALIGNMENT; ///< name "vertical-alignment", type STRING
120 * @brief Structure used to retrieve Layout info per character.
122 struct CharacterLayoutInfo
125 * @brief Default constructor.
127 * Initializes all members to their default values.
129 CharacterLayoutInfo();
132 * @brief Empty destructor.
134 * @note Added to increase coverage.
136 ~CharacterLayoutInfo();
139 * @brief Copy constructor.
141 CharacterLayoutInfo( const CharacterLayoutInfo& characterLayoutInfo );
144 * @brief Assignment operator.
146 CharacterLayoutInfo& operator=( const CharacterLayoutInfo& character );
149 * @brief Constructor.
151 * @param[in] size of the character.
152 * @param[in] position of the character.
153 * @param[in] isNewLineChar Whether the character is a new line character.
154 * @param[in] isRightToLeftCharacter Whether is a right to left character.
155 * @param[in] visible Whether is visible.
156 * @param[in] descender of the character (distance from the base line to the bottom of the character.)
158 CharacterLayoutInfo( const Size& size,
159 const Vector3& position,
161 bool isRightToLeftCharacter,
165 Size mSize; ///< Size of the group of characters.
166 Vector3 mPosition; ///< Position of the group of characters within the text view.
167 bool mIsNewLineChar:1; ///< Whether this group of characters represent a new line.
168 bool mIsRightToLeftCharacter:1; ///< Whether it's a right-to-left character.
169 bool mIsVisible:1; ///< Whether this group of characters is visible or not.
170 float mDescender; ///< The character's descender which is the distance from the baseline to the bottom of the character
173 typedef std::vector<CharacterLayoutInfo> CharacterLayoutInfoContainer; ///< Container of Character layouts
176 * @brief Stores some info about a laid-out line.
178 struct LineLayoutInfo
180 std::size_t mCharacterGlobalIndex; ///< Global index within the whole text of the first character of current laid-out line.
181 Size mSize; ///< Size of the current laid-out line.
182 float mAscender; ///< The max ascender of the current laid-out line.
185 typedef std::vector<LineLayoutInfo> LineLayoutInfoContainer; ///< Container of line layouts
188 * @brief How text is laid out.
190 struct TextLayoutInfo
193 * @brief Default constructor.
198 * @brief Empty destructor.
200 * @note Added to increase coverage.
205 * @brief Copy constructor.
207 TextLayoutInfo( const TextLayoutInfo& textLayoutInfo );
210 * @brief Assignment operator.
212 TextLayoutInfo& operator=( const TextLayoutInfo& textLayoutInfo );
214 CharacterLayoutInfoContainer mCharacterLayoutInfoTable; ///< The table of character positions and sizes sorted by the characters' visual index.
215 LineLayoutInfoContainer mLines; ///< For each laid-out line, it stores an index to the first character of the line.
216 std::vector<int> mCharacterLogicalToVisualMap; ///< The map to store the character's logical (input) index according to its visual (reordered) index.
217 std::vector<int> mCharacterVisualToLogicalMap; ///< The map to store the character's visual (reordered) index according to its logical (input) index.
218 Size mTextSize; ///< Text size after relayout.
219 Vector2 mScrollOffset; ///< Scroll's position.
223 * @brief This structure represents a fade boundary.
225 * If 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.
226 * 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.
231 * @brief Default constructor.
233 * Initializes all values to 0. It means no fade boundary.
238 * @brief Constructor.
240 * Initializes the fade boundary with the given values.
242 * @param[in] left value in pixels.
243 * @param[in] right value in pixels.
244 * @param[in] top value in pixels.
245 * @param[in] bottom value in pixels.
247 FadeBoundary( PixelSize left, PixelSize right, PixelSize top, PixelSize bottom );
249 PixelSize mLeft; ///< The left fade boundary
250 PixelSize mRight; ///< The right fade boundary
251 PixelSize mTop; ///< The top fade boundary
252 PixelSize mBottom; ///< The bottom fade bounday
256 * @brief Define how to split the text in lines.
258 * SplitByNewLineChar will split the text in lines when a '\\n' character is found.
259 * SplitByWord has effect only when TextView size is assigned.
260 * It will split the text in lines when a '\\n' character is found or if a line exceeds the TextView's boundary. This option won't split a word in two.
261 * SplitByChar has effect only when TextView size is assigned.
262 * It will split the text in lines when a '\\n' character is found or if a line exceeds the TextView's boundary. This option might split a word in two.
263 * The default value is SplitByNewLineChar.
267 SplitByNewLineChar, ///< Text lines will split when '\\n' character is found.
268 SplitByWord, ///< Text lines will split by word or if '\\n' character is found. It has effect only when TextView size is assigned.
269 SplitByChar ///< Text lines will split by char or if '\\n' character is found. It has effect only when TextView size is assigned.
273 * @brief Define how to display the text when it doesn't fit inside the TextView.
275 * The default value is ShrinkToFit.
279 Original, ///< Will display the text in its original size. If a line, a word or a character is bigger than the TextView size it may exceed its boundary.
280 Truncate, ///< Will display the text in its original size. It won't display the text which exceeds the TextView boundary.
281 Fade, ///< Will display the text in its original size. It won't display the text which exceeds the TextView boundary. It fades the text out.
282 Split, ///< Will split the text in a new line.
283 ShrinkToFit, ///< Will shrink the text to fit the TextView boundary.
284 EllipsizeEnd ///< Will ellipsize the text by the end.
288 * @brief Define how to justify lines inside the text area.
290 * The default value is Left.
292 enum LineJustification
294 Left, ///< Justify to the left.
295 Center, ///< Centered.
296 Right, ///< Justify to the right.
297 Justified ///< Line justified.
302 * @brief Create an TextView handle; this can be initialised with TextView::New().
304 * Calling member functions with an uninitialised Dali::Object handle is not allowed.
309 * @brief Copy constructor.
311 * Creates another handle that points to the same real object
312 * @param[in] handle The handle to copy from
314 TextView( const TextView& handle );
317 * @brief Assignment operator.
319 * Changes this handle to point to another real object
320 * @param[in] handle The handle to copy from
321 * @return a reference to this
323 TextView& operator=( const TextView& handle );
326 * @brief Create a TextView control with no text.
328 * @return A handle the TextView control.
330 static TextView New();
333 * @brief Create a TextView control.
335 * @param[in] text to display.
336 * @return A handle the TextView control.
338 static TextView New( const std::string& text );
341 * @copydoc TextView New( const std::string& text )
343 static TextView New( const MarkupProcessor::StyledTextArray& text );
346 * @brief Downcast an Object handle to TextView.
348 * If handle points to a TextView the
349 * downcast produces valid handle. If not the returned handle is left uninitialized.
350 * @param[in] handle Handle to an object
351 * @return handle to a TextView or an uninitialized handle
353 static TextView DownCast( BaseHandle handle );
356 * @brief Virtual destructor.
358 * Dali::Object derived classes typically do not contain member data.
363 * @brief Replace the current text with a new text string.
365 * @param[in] text to display. The string may contain style tags.
367 void SetText( const std::string& text );
370 * @brief Replace the current text with a new text string with style.
372 * @param[in] text with style to display.
374 void SetText( const MarkupProcessor::StyledTextArray& text );
377 * @brief Inserts the given text in the specified position.
379 * @param[in] position Where the given text is going to be added.
380 * @param[in] text The text to be added.
382 void InsertTextAt( std::size_t position, const std::string& text );
385 * @copydoc InsertTextAt( std::size_t position, const std::string& text )
387 void InsertTextAt( std::size_t position, const MarkupProcessor::StyledTextArray& text );
390 * @brief Replaces part of the text.
392 * It removes the specified number of characters from the given position and inserts the given text in the same specified position.
394 * @param[in] position of the first character to be removed and Where the given text is going to be added.
395 * @param[in] numberOfCharacters number of characters to be removed.
396 * @param[in] text The text to be added.
398 void ReplaceTextFromTo( std::size_t position, std::size_t numberOfCharacters, const std::string& text );
401 * @copydoc ReplaceTextFromTo( std::size_t position, std::size_t numberOfCharacters, const std::string& text )
403 void ReplaceTextFromTo( std::size_t position, std::size_t numberOfCharacters, const MarkupProcessor::StyledTextArray& text );
406 * @brief Removes the specified number of characters from the given position.
408 * @param[in] position of the first character to be removed.
409 * @param[in] numberOfCharacters number of characters to be removed.
411 void RemoveTextFrom( std::size_t position, std::size_t numberOfCharacters );
414 * @brief Get the currently displayed text.
416 * @return The currently displayed text.
418 std::string GetText() const;
421 * @brief Sets a line height offset.
423 * The line height offset will be added to the font line height.
424 * @param [in] offset The height offset in PointSize units.
426 void SetLineHeightOffset( PointSize offset );
429 * @brief Retrieves the line height offset.
431 * @return The line height offset in PointSize units.
433 PointSize GetLineHeightOffset() const;
436 * @brief Sets the given style to the current text.
438 * By default all style settings are applied but a bit mask could be used to modify only certain style settings.
439 * @note TextView doesn't store a copy of the given style, it applies the given style to the current text only.
440 * Subsequent calls to SetText() will override any style set by this method.
441 * @param[in] style The given style
442 * @param[in] mask The bit mask.
444 void SetStyleToCurrentText( const TextStyle& style, TextStyle::Mask mask = TextStyle::ALL );
447 * @brief Set the current text alignment.
449 * Default alignment is (HorizontalCenter | VerticalCenter)
450 * @param[in] align The new alignment option.
452 void SetTextAlignment( Alignment::Type align );
455 * @brief Get the current text alignment combined into a single value.
457 * The values can be tested by using the & operator
458 * and the desired flag. e.g. if (GetTextAlignment() & HorizontalCentre) ...
459 * @return the combined alignment
461 Alignment::Type GetTextAlignment() const;
464 * @brief Sets how to split the text in lines policy.
466 * @param policy The multi-line policy. SplitByNewLineChar is set by default.
468 void SetMultilinePolicy( MultilinePolicy policy );
471 * @brief Gets the split in lines policy.
473 * @return The multi-line policy.
475 MultilinePolicy GetMultilinePolicy() const;
478 * @brief Sets how to display the text inside the TextView when it exceeds the text-view's width.
480 * @param policy The exceed policy. Original is set by default.
482 void SetWidthExceedPolicy( ExceedPolicy policy );
485 * @brief Gets the width exceed policy.
487 * @return The exceed policy.
489 ExceedPolicy GetWidthExceedPolicy() const;
492 * @brief Sets how to display the text inside the TextView when it exceeds the text-view's height.
494 * @param policy The exceed policy. Original is set by default.
496 void SetHeightExceedPolicy( ExceedPolicy policy );
499 * @brief Gets the height exceed policy.
501 * @return The exceed policy.
503 ExceedPolicy GetHeightExceedPolicy() const;
506 * @brief Sets how to justify lines inside the text area.
508 * @param justification The line justification. Left is set by default.
510 void SetLineJustification( LineJustification justification );
513 * @brief Gets the line justification.
515 * @return The line justification.
517 LineJustification GetLineJustification() const;
520 * @brief Sets a fade boundary.
524 * @param[in] fadeBoundary The given fade boundary.
526 void SetFadeBoundary( const FadeBoundary& fadeBoundary );
529 * @brief Retrieves the fade boundary.
533 * @return The fade boundary.
535 const FadeBoundary& GetFadeBoundary() const;
538 * @brief Sets the ellipsize text.
540 * @param[in] ellipsizeText The new text. The string may contain style tags. By default the ellipsize text is '...'
542 void SetEllipsizeText( const std::string& ellipsizeText );
545 * @brief Sets the ellipsize text.
547 * @param[in] ellipsizeText The new text with its style.
549 void SetEllipsizeText( const MarkupProcessor::StyledTextArray& ellipsizeText );
552 * @brief Retrieves the ellipsize text.
554 * @return The ellipsize text.
556 std::string GetEllipsizeText() const;
559 * @brief A mechanism to retrieve layout information from the TextView.
561 * It produces a vector of CharcterLayoutInfo structures which describe the size and position of each character,
562 * two vectors which maps the logical and visual positions of the characters in a bidirectional text, the size
563 * of the whole laid-out text and the scroll offset value.
565 * @see TextLayoutInfo.
567 * @param[out] textLayoutInfo A structure with text layout information.
569 void GetTextLayoutInfo( TextLayoutInfo& textLayoutInfo );
572 * @brief Allows modification of text-actor's position in the depth sort algorithm.
574 * @see Dali::RenderableActor::SetSortModifier()
575 * @param [in] depthOffset the offset to be given to the internal text-actors. Positive values pushing it further back.
577 void SetSortModifier( float depthOffset );
580 * @brief Sets whether text-view renders text using a previously generated snapshot.
582 * Rendering long text using a snapshot may increase performance. The default value is \e true (render using a snapshot).
584 * @param[in] enable Whether text-view is using a snapshot to render text.
586 void SetSnapshotModeEnabled( bool enable );
589 * @brief Retrieves whether text-view is using a snapshot to render text.
591 * @return \e true if text-view is using a snapshot to render text, otherwhise it returns \e false.
593 bool IsSnapshotModeEnabled() const;
596 * @brief Sets whether markup processing should be carried out.
598 * @param[in] enable whether markup processing is carried out or not.
600 void SetMarkupProcessingEnabled( bool enable );
603 * @brief Retrieves whether text-view is processing markup text
605 * @return \e true if text-view markup processing is enabled, otherwhise it returns \e false.
607 bool IsMarkupProcessingEnabled() const;
610 * @brief Enables or disables the text scroll.
612 * When scroll is enabled, snapshot mode will be enabled automatically. Equally, if scroll is disabled
613 * the snapshot mode is restored to the previous value.
615 * @param[in] enable Whether to enable the text scroll.
617 void SetScrollEnabled( bool enable );
620 * @brief Retrieves whether the text scroll is enabled.
622 * @return \e true if the scroll is enabled.
624 bool IsScrollEnabled() const;
627 * @brief Sets a new scroll position.
629 * The new scroll position set could be trimmed if the text doesn't cover the whole text-view.
630 * i.e. If a text-view is 100x100 and a text is 200x100 a scroll position beyond 50x0 will be trimmed to 50x0.
632 * Call IsScrollPositionTrimmed() to know if the last scroll position set has been trimmed.
634 * A signal is emitted. @see ScrolledSignal().
636 * @param[in] position The new scroll position.
638 void SetScrollPosition( const Vector2& position );
641 * @brief Recrieves current scroll position.
643 * @return The scroll position.
645 const Vector2& GetScrollPosition() const;
648 * @brief Whether the last scroll position set was trimmed.
650 * @return \e true if the last scroll position set was trimmed, otherwise \e false.
652 bool IsScrollPositionTrimmed() const;
655 /// @brief Signal types
656 typedef SignalV2< void ( TextView textView, Vector2 scrollDelta ) > ScrolledSignalV2;
659 * @brief Signal emitted when the scroll position changes.
661 * A callback with the following prototype can be connected to this signal.
663 * Callback(TextView textView, Vector2 scrollDelta)
665 * \e textView is the handle of the text-view emitting the signal.
666 * \e scrollDelta is the differente of the current scroll position with the previous one.
667 * @return The signal to connect to
669 ScrolledSignalV2& ScrolledSignal();
671 public: // Not intended for application developers
674 * @brief Creates a handle using the Toolkit::Internal implementation.
676 * @param[in] implementation The Control implementation.
678 TextView( Internal::TextView& implementation );
681 * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
683 * @param[in] internal A pointer to the internal CustomActor.
685 TextView( Dali::Internal::CustomActor* internal );
688 } // namespace Toolkit
695 #endif // __DALI_TOOLKIT_ITEM_VIEW_H__