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 Flora License, Version 1.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://floralicense.org/license/
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.
21 * @addtogroup CAPI_DALI_TOOLKIT_TEXT_VIEW_MODULE
29 #include <dali-toolkit/public-api/controls/alignment/alignment.h>
30 #include <dali-toolkit/public-api/markup-processor/markup-processor.h>
32 namespace Dali DALI_IMPORT_API
38 namespace Internal DALI_INTERNAL
44 * @brief The TextView class is a UI Dali::Toolkit::Control designed to extend the capabilities of the basic Dali::TextActor.
46 * It provides support for multi-line wrapping, multi-language font detection, text alignment, scrolling and styling.
48 * See the \link text-view Text View \endlink page of the Programming Guide for more details and examples.
50 class TextView : public Control
55 static const char* const SIGNAL_TEXT_SCROLLED; ///< Signal emitted when the scroll position changes. @see ScrolledSignal()
58 static const Property::Index PROPERTY_MARKUP_ENABLED; ///< name "markup-enabled", @see SetMarkupProcessingEnabled(), type BOOLEAN
59 static const Property::Index PROPERTY_TEXT; ///< name "text", @see SetText(), type STRING
60 static const Property::Index PROPERTY_MULTILINE_POLICY; ///< name "multiline-policy", @see SetMultilinePolicy(), type STRING
61 static const Property::Index PROPERTY_WIDTH_EXCEED_POLICY; ///< name "width-exceed-policy", @see SetWidthExceedPolicy(), type STRING
62 static const Property::Index PROPERTY_HEIGHT_EXCEED_POLICY; ///< name "height-exceed-policy", @see SetHeightExceedPolicy(), type STRING
63 static const Property::Index PROPERTY_LINE_JUSTIFICATION; ///< name "line-justification", @see SetLineJustification(), type STRING
64 static const Property::Index PROPERTY_FADE_BOUNDARY; ///< name "fade-boundary", @see SetFadeBoundary(), type VECTOR4
65 static const Property::Index PROPERTY_LINE_HEIGHT_OFFSET; ///< name "line-height-offset", @see SetLineHeightOffset(), type FLOAT
66 static const Property::Index PROPERTY_HORIZONTAL_ALIGNMENT; ///< name "horizontal-alignment", @see SetTextAlignment(), type STRING
67 static const Property::Index PROPERTY_VERTICAL_ALIGNMENT; ///< name "vertical-alignment", @see SetTextAlignment(), type STRING
70 * @brief Structure used to retrieve Layout info per character.
72 struct CharacterLayoutInfo
75 * @brief Default constructor.
77 * Initializes all members to their default values.
79 CharacterLayoutInfo();
82 * @brief Empty destructor.
84 * @note Added to increase coverage.
86 ~CharacterLayoutInfo();
89 * @brief Copy constructor.
91 CharacterLayoutInfo( const CharacterLayoutInfo& characterLayoutInfo );
94 * @brief Assignment operator.
96 CharacterLayoutInfo& operator=( const CharacterLayoutInfo& character );
101 * @param[in] size of the character.
102 * @param[in] position of the character.
103 * @param[in] isNewLineChar Whether the character is a new line character.
104 * @param[in] isRightToLeftCharacter Whether is a right to left character.
105 * @param[in] visible Whether is visible.
106 * @param[in] descender of the character (distance from the base line to the bottom of the character.)
108 CharacterLayoutInfo( const Size& size,
109 const Vector3& position,
111 bool isRightToLeftCharacter,
115 Size mSize; ///< Size of the group of characters.
116 Vector3 mPosition; ///< Position of the character within the text view.
117 bool mIsNewLineChar:1; ///< Whether this character represent a new line.
118 bool mIsRightToLeftCharacter:1; ///< Whether it's a right-to-left character.
119 bool mIsVisible:1; ///< Whether this character is visible or not.
120 float mDescender; ///< The character's descender which is the distance from the baseline to the bottom of the character
123 typedef std::vector<CharacterLayoutInfo> CharacterLayoutInfoContainer; ///< Container of layout info per character.
126 * @brief Stores some info about a laid-out line.
128 struct LineLayoutInfo
130 std::size_t mCharacterGlobalIndex; ///< Global index within the whole text of the first character of current laid-out line.
131 Size mSize; ///< Size of the current laid-out line.
132 float mAscender; ///< The max ascender of the current laid-out line.
135 typedef std::vector<LineLayoutInfo> LineLayoutInfoContainer; ///< Container of layout info per line.
138 * @brief How text is laid out.
140 struct TextLayoutInfo
143 * @brief Default constructor.
148 * @brief Empty destructor.
150 * @note Added to increase coverage.
155 * @brief Copy constructor.
157 TextLayoutInfo( const TextLayoutInfo& textLayoutInfo );
160 * @brief Assignment operator.
162 TextLayoutInfo& operator=( const TextLayoutInfo& textLayoutInfo );
164 CharacterLayoutInfoContainer mCharacterLayoutInfoTable; ///< The table of character's positions and sizes sorted by the character's visual index.
165 LineLayoutInfoContainer mLines; ///< For each laid-out line, it stores an index to the first character of the line.
166 std::vector<int> mCharacterLogicalToVisualMap; ///< The map to store the character's logical (input) index according to its visual (reordered) index.
167 std::vector<int> mCharacterVisualToLogicalMap; ///< The map to store the character's visual (reordered) index according to its logical (input) index.
168 Size mTextSize; ///< Text size after relayout.
169 Vector2 mScrollOffset; ///< Scroll's position.
173 * @brief This structure represents a fade boundary.
175 * 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.
176 * 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.
181 * @brief Default constructor.
183 * Initializes all values to 0. It means no fade boundary.
188 * @brief Constructor.
190 * Initializes the fade boundary with the given values.
192 * @param[in] left value in pixels.
193 * @param[in] right value in pixels.
194 * @param[in] top value in pixels.
195 * @param[in] bottom value in pixels.
197 FadeBoundary( PixelSize left, PixelSize right, PixelSize top, PixelSize bottom );
199 PixelSize mLeft; ///< The left fade boundary
200 PixelSize mRight; ///< The right fade boundary
201 PixelSize mTop; ///< The top fade boundary
202 PixelSize mBottom; ///< The bottom fade bounday
206 * @brief Define how to wrap the text in lines.
208 * \e SplitByNewLineChar will wrap the text in lines when a '\\n' character or a \<br /\> is found.
209 * \e SplitByWord has effect only when TextView size is assigned.
210 * It will wrap the text in lines when a '\\n' character or a \<br /\> is found or if a line exceeds the TextView's boundary. This option won't split a word in two.
211 * \e SplitByChar has effect only when TextView size is assigned.
212 * It will wrap the text in lines when a '\\n' character or a \<br /\> is found or if a line exceeds the TextView's boundary. This option might split a word in two.
213 * The default value is \e SplitByNewLineChar.
217 SplitByNewLineChar, ///< Text lines will wrap when '\\n' character is found.
218 SplitByWord, ///< Text lines will wrap by word or if '\\n' character is found. It has effect only when TextView size is assigned.
219 SplitByChar ///< Text lines will wrap by char or if '\\n' character is found. It has effect only when TextView size is assigned.
223 * @brief Define how to display the text when it doesn't fit inside the TextView after the line wrap.
225 * The default value is \e Original.
229 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.
230 Truncate, ///< @deprecated. Use Fade instead.
231 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.
232 Split, ///< Will split the text in a new line.
233 ShrinkToFit, ///< Will shrink the text to fit the TextView boundary.
234 EllipsizeEnd ///< Will ellipsize the text by the end.
238 * @brief Define how to justify lines inside the text area.
240 * The default value is \e Left.
242 enum LineJustification
244 Left, ///< Justify to the left.
245 Center, ///< Centered.
246 Right, ///< Justify to the right.
247 Justified ///< Line justified.
252 * @brief Create a TextView handle; this can be initialised with TextView::New().
254 * Calling member functions with an uninitialised Dali::Object handle is not allowed.
259 * @brief Copy constructor.
261 * Creates another handle that points to the same real object
262 * @param[in] handle The handle to copy from
264 TextView( const TextView& handle );
267 * @brief Assignment operator.
269 * Changes this handle to point to another real object
270 * @param[in] handle The handle to copy from
271 * @return a reference to this
273 TextView& operator=( const TextView& handle );
276 * @brief Create a TextView control with no text.
278 * @return A handle the TextView control.
280 static TextView New();
283 * @brief Create a TextView control.
285 * @param[in] text to display.
286 * @return A handle the TextView control.
288 static TextView New( const std::string& text );
291 * @brief Create a TextView control with styled text.
293 * @param[in] text The text with style to display.
294 * @return A handle the TextView control.
296 static TextView New( const MarkupProcessor::StyledTextArray& text );
299 * @brief Downcast an Object handle to TextView.
301 * If handle points to a TextView the
302 * downcast produces valid handle. If not the returned handle is left uninitialized.
303 * @param[in] handle Handle to an object
304 * @return handle to a TextView or an uninitialized handle
306 static TextView DownCast( BaseHandle handle );
309 * @brief Virtual destructor.
311 * Dali::Object derived classes typically do not contain member data.
316 * @brief Replace the current text with a new text string.
318 * @param[in] text to display. The string may contain style tags.
320 void SetText( const std::string& text );
323 * @brief Replace the current text with a new text string with style.
325 * @param[in] text The text with style to display.
327 void SetText( const MarkupProcessor::StyledTextArray& text );
330 * @brief Inserts the given text in the specified position.
332 * @param[in] position Where the given text is going to be added.
333 * @param[in] text The text to be added.
335 void InsertTextAt( std::size_t position, const std::string& text );
338 * @brief Inserts the given text with style in the specified position.
340 * @param[in] position Where the given text is going to be added.
341 * @param[in] text The text with style to be added.
343 void InsertTextAt( std::size_t position, const MarkupProcessor::StyledTextArray& text );
346 * @brief Replaces part of the text.
348 * It removes the specified number of characters from the given position and inserts the given text in the same specified position.
350 * @param[in] position of the first character to be removed and Where the given text is going to be added.
351 * @param[in] numberOfCharacters number of characters to be removed.
352 * @param[in] text The text to be added.
354 void ReplaceTextFromTo( std::size_t position, std::size_t numberOfCharacters, const std::string& text );
357 * @brief Replaces part of the text.
359 * It removes the specified number of characters from the given position and inserts the given text with style in the same specified position.
361 * @param[in] position of the first character to be removed and Where the given text is going to be added.
362 * @param[in] numberOfCharacters number of characters to be removed.
363 * @param[in] text The text with style to be added.
365 void ReplaceTextFromTo( std::size_t position, std::size_t numberOfCharacters, const MarkupProcessor::StyledTextArray& text );
368 * @brief Removes the specified number of characters from the given position.
370 * @param[in] position of the first character to be removed.
371 * @param[in] numberOfCharacters number of characters to be removed.
373 void RemoveTextFrom( std::size_t position, std::size_t numberOfCharacters );
376 * @brief Get the currently displayed text.
378 * @return The currently displayed text.
380 std::string GetText() const;
383 * @brief Sets a line height offset.
385 * The line height offset will be added to the font line height.
386 * @param [in] offset The height offset in PointSize units.
388 void SetLineHeightOffset( PointSize offset );
391 * @brief Retrieves the line height offset.
393 * @return The line height offset in PointSize units.
395 PointSize GetLineHeightOffset() const;
398 * @brief Sets the given style to the current text.
400 * By default all style settings are applied but a bit mask could be used to modify only certain style settings.
401 * @note TextView doesn't store a copy of the given style, it applies the given style to the current text only.
402 * Subsequent calls to SetText() will override any style set by this method.
403 * @param[in] style The given style
404 * @param[in] mask The bit mask.
406 void SetStyleToCurrentText( const TextStyle& style, TextStyle::Mask mask = TextStyle::ALL );
409 * @brief Set the current text alignment.
411 * Default alignment is (HorizontalCenter | VerticalCenter)
412 * @param[in] align The new alignment option.
414 void SetTextAlignment( Alignment::Type align );
417 * @brief Get the current text alignment combined into a single value.
419 * The values can be tested by using the & operator
420 * and the desired flag. e.g. if (GetTextAlignment() & HorizontalCentre) ...
421 * @return the combined alignment
423 Alignment::Type GetTextAlignment() const;
426 * @brief Sets how to wrap the text in lines policy.
428 * @param policy The multi-line policy. \e SplitByNewLineChar is set by default.
430 void SetMultilinePolicy( MultilinePolicy policy );
433 * @brief Gets the wrap in lines policy.
435 * @return The multi-line policy.
437 MultilinePolicy GetMultilinePolicy() const;
440 * @brief Sets how to display the text inside the TextView when it exceeds the text-view's width.
442 * @param policy The exceed policy. Original is set by default.
444 void SetWidthExceedPolicy( ExceedPolicy policy );
447 * @brief Gets the width exceed policy.
449 * @return The exceed policy.
451 ExceedPolicy GetWidthExceedPolicy() const;
454 * @brief Sets how to display the text inside the TextView when it exceeds the text-view's height.
456 * @param policy The exceed policy. Original is set by default.
458 void SetHeightExceedPolicy( ExceedPolicy policy );
461 * @brief Gets the height exceed policy.
463 * @return The exceed policy.
465 ExceedPolicy GetHeightExceedPolicy() const;
468 * @brief Sets how to justify lines inside the text area.
470 * @param justification The line justification. Left is set by default.
472 void SetLineJustification( LineJustification justification );
475 * @brief Gets the line justification.
477 * @return The line justification.
479 LineJustification GetLineJustification() const;
482 * @brief Sets a fade boundary.
486 * @param[in] fadeBoundary The given fade boundary.
488 void SetFadeBoundary( const FadeBoundary& fadeBoundary );
491 * @brief Retrieves the fade boundary.
495 * @return The fade boundary.
497 const FadeBoundary& GetFadeBoundary() const;
500 * @brief Sets the ellipsize text.
502 * @param[in] ellipsizeText The new text. The string may contain style tags. By default the ellipsize text is '...'
504 void SetEllipsizeText( const std::string& ellipsizeText );
507 * @brief Sets the ellipsize text with style.
509 * @param[in] ellipsizeText The new text with its style.
511 void SetEllipsizeText( const MarkupProcessor::StyledTextArray& ellipsizeText );
514 * @brief Retrieves the ellipsize text.
516 * @return The ellipsize text.
518 std::string GetEllipsizeText() const;
521 * @brief A mechanism to retrieve layout information from the TextView.
523 * It produces a vector of CharcterLayoutInfo structures which describe the size and position of each character,
524 * two vectors which maps the logical and visual positions of the characters in a bidirectional text, the size
525 * of the whole laid-out text and the scroll offset value.
527 * @see TextLayoutInfo.
529 * @param[out] textLayoutInfo A structure with text layout information.
531 void GetTextLayoutInfo( TextLayoutInfo& textLayoutInfo );
534 * @brief Allows modification of text-actor's position in the depth sort algorithm.
536 * @see Dali::RenderableActor::SetSortModifier()
537 * @param [in] depthOffset the offset to be given to the internal text-actors. Positive values pushing it further back.
539 void SetSortModifier( float depthOffset );
542 * @brief Sets whether text-view renders text using a previously generated snapshot.
544 * Rendering long text using a snapshot may increase performance. The default value is \e false (render without using a snapshot).
546 * @param[in] enable Whether text-view is using a snapshot to render text.
548 void SetSnapshotModeEnabled( bool enable );
551 * @brief Retrieves whether text-view is using a snapshot to render text.
553 * @return \e true if text-view is using a snapshot to render text, otherwhise it returns \e false.
555 bool IsSnapshotModeEnabled() const;
558 * @brief Sets whether markup processing should be carried out.
560 * @param[in] enable whether markup processing is carried out or not.
562 void SetMarkupProcessingEnabled( bool enable );
565 * @brief Retrieves whether text-view is processing markup text
567 * @return \e true if text-view markup processing is enabled, otherwhise it returns \e false.
569 bool IsMarkupProcessingEnabled() const;
572 * @brief Enables or disables the text scroll.
574 * When scroll is enabled, snapshot mode will be enabled automatically. Equally, if scroll is disabled
575 * the snapshot mode is restored to the previous value.
577 * @param[in] enable Whether to enable the text scroll.
579 void SetScrollEnabled( bool enable );
582 * @brief Retrieves whether the text scroll is enabled.
584 * @return \e true if the scroll is enabled.
586 bool IsScrollEnabled() const;
589 * @brief Sets a new scroll position.
591 * The new scroll position set could be trimmed if the text doesn't cover the whole text-view.
592 * i.e. If a text-view is 100x100 and a text is 200x100 a scroll position beyond 50x0 will be trimmed to 50x0.
594 * Call IsScrollPositionTrimmed() to know if the last scroll position set has been trimmed.
596 * A signal is emitted. @see ScrolledSignal().
598 * @param[in] position The new scroll position.
600 void SetScrollPosition( const Vector2& position );
603 * @brief Recrieves current scroll position.
605 * @return The scroll position.
607 const Vector2& GetScrollPosition() const;
610 * @brief Whether the last scroll position set was trimmed.
612 * @return \e true if the last scroll position set was trimmed, otherwise \e false.
614 bool IsScrollPositionTrimmed() const;
617 /// @brief Signal types
618 typedef SignalV2< void ( TextView textView, Vector2 scrollDelta ) > ScrolledSignalV2;
621 * @brief Signal emitted when the text is scrolled inside the text-view.
623 * A callback with the following prototype can be connected to this signal.
625 * Callback(TextView textView, Vector2 scrollDelta)
627 * \e textView is the handle of the text-view emitting the signal.
628 * \e scrollDelta is the differente of the current scroll position with the previous one.
629 * @return The signal to connect to
631 ScrolledSignalV2& ScrolledSignal();
633 public: // Not intended for application developers
636 * @brief Creates a handle using the Toolkit::Internal implementation.
637 * @note Not intended for application developers
639 * @param[in] implementation The Control implementation.
641 TextView( Internal::TextView& implementation );
644 * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
645 * @note Not intended for application developers
647 * @param[in] internal A pointer to the internal CustomActor.
649 TextView( Dali::Internal::CustomActor* internal );
652 } // namespace Toolkit
659 #endif // __DALI_TOOLKIT_ITEM_VIEW_H__