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_FRAMEWORK
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 * TextView is a layout container with alignment, multi-line wrapping and formatting support.
46 * Different multi-line and exceed policies could be chosen to represent the given text.
47 * \see Toolkit::TextView::SetMultilinePolicy \see Toolkit::TextView::SetExceedPolicy
49 * Multi-line policies:
51 * <li>\e Split by new line character.
52 * Text will split when a '\\n' character is found.
54 * <li>\e Split by word.
55 * Text will split when a '\\n' character is found or if the text doesn't fit in the text view width.
56 * In that case, some words will be moved to a new line.
58 * <li>\e Split by character.
59 * Text will split when a '\\n' character is found or if the text doesn't fit in the text view width.
60 * In that case, words which doesn't fit will be split in two and the remaining text moved to a new line.
63 * Exceed policies work in combination with multi-line policies:
65 * <li>\e Original size.
66 * Text will be displayed with its original size.
69 * Text will be truncated.
72 * Text will be faded out.
75 * Text will be split and moved to a new line.
77 * <li>\e Shrink to fit.
78 * Text will be shrink to fit in the text view's boundary.
80 * <li>\e EllipsizeEnd.
81 * Text will be ellipsized at the end.
85 * Text alignment could be set to align the whole text block inside the text view's boundary. \see Toolkit::TextView::SetTextAlignment.
87 * Line justification could be set to align lines inside a text block. \see Toolkit::TextView::SetLineJustification.
89 * 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.
92 * 1) Use the font specified in text decoration.
93 * 2) Use automatic font detection.
95 * Integration with other classes (GetSizeAndPositionTable )
97 * Text decoration ( Color, Font, Size, italic and all features supported in TextActor )
99 class TextView : public Control
104 static const char* const SIGNAL_TEXT_SCROLLED; ///< Signal emitted when the scroll position changes. @see SignalScrolled()
107 * Structure used to retrieve Layout info per character.
109 struct CharacterLayoutInfo
112 * Default constructor.
114 * Initializes all members to their default values.
116 CharacterLayoutInfo();
121 * @note Added to increase coverage.
123 ~CharacterLayoutInfo();
128 CharacterLayoutInfo( const CharacterLayoutInfo& characterLayoutInfo );
131 * Assignment operator.
133 CharacterLayoutInfo& operator=( const CharacterLayoutInfo& character );
138 * @param[in] size of the character.
139 * @param[in] position of the character.
140 * @param[in] isNewLineChar Whether the character is a new line character.
141 * @param[in] isRightToLeftCharacter Whether is a right to left character.
142 * @param[in] visible Whether is visible.
143 * @param[in] descender of the character (distance from the base line to the bottom of the character.)
145 CharacterLayoutInfo( const Size& size,
146 const Vector3& position,
148 bool isRightToLeftCharacter,
152 Size mSize; ///< Size of the group of characters.
153 Vector3 mPosition; ///< Position of the group of characters within the text view.
154 bool mIsNewLineChar:1; ///< Whether this group of characters represent a new line.
155 bool mIsRightToLeftCharacter:1; ///< Whether it's a right-to-left character.
156 bool mIsVisible:1; ///< Whether this group of characters is visible or not.
157 float mDescender; ///< The character's descender which is the distance from the baseline to the bottom of the character
160 typedef std::vector<CharacterLayoutInfo> CharacterLayoutInfoContainer;
163 * Stores some info about a laid-out line.
165 struct LineLayoutInfo
167 std::size_t mCharacterGlobalIndex; ///< Global index within the whole text of the first character of current laid-out line.
168 Size mSize; ///< Size of the current laid-out line.
169 float mAscender; ///< The max ascender of the current laid-out line.
171 typedef std::vector<LineLayoutInfo> LineLayoutInfoContainer;
173 struct TextLayoutInfo
176 * Default constructor.
183 * @note Added to increase coverage.
190 TextLayoutInfo( const TextLayoutInfo& textLayoutInfo );
193 * Assignment operator.
195 TextLayoutInfo& operator=( const TextLayoutInfo& textLayoutInfo );
197 CharacterLayoutInfoContainer mCharacterLayoutInfoTable; ///< The table of character positions and sizes sorted by the characters' visual index.
198 LineLayoutInfoContainer mLines; ///< For each laid-out line, it stores an index to the first character of the line.
199 std::vector<int> mCharacterLogicalToVisualMap; ///< The map to store the character's logical (input) index according to its visual (reordered) index.
200 std::vector<int> mCharacterVisualToLogicalMap; ///< The map to store the character's visual (reordered) index according to its logical (input) index.
201 Size mTextSize; ///< Text size after relayout.
202 Vector2 mScrollOffset; ///< Scroll's position.
206 * It represents a fade boundary.
207 * 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.
208 * 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.
213 * Default constructor.
214 * Initializes all values to 0. It means no fade boundary.
220 * Initializes the fade boundary with the given values.
222 * @param[in] left value in pixels.
223 * @param[in] right value in pixels.
224 * @param[in] top value in pixels.
225 * @param[in] bottom value in pixels.
227 FadeBoundary( PixelSize left, PixelSize right, PixelSize top, PixelSize bottom );
236 * Define how to split the text in lines.
237 * SplitByNewLineChar will split the text in lines when a '\\n' character is found.
238 * SplitByWord has effect only when TextView size is assigned.
239 * 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.
240 * SplitByChar has effect only when TextView size is assigned.
241 * 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.
242 * The default value is SplitByNewLineChar.
246 SplitByNewLineChar, ///< Text lines will split when '\\n' character is found.
247 SplitByWord, ///< Text lines will split by word or if '\\n' character is found. It has effect only when TextView size is assigned.
248 SplitByChar ///< Text lines will split by char or if '\\n' character is found. It has effect only when TextView size is assigned.
252 * Define how to display the text when it doesn't fit inside the TextView.
253 * The default value is ShrinkToFit.
257 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.
258 Truncate, ///< Will display the text in its original size. It won't display the text which exceeds the TextView boundary.
259 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.
260 Split, ///< Will split the text in a new line.
261 ShrinkToFit, ///< Will shrink the text to fit the TextView boundary.
262 EllipsizeEnd ///< Will ellipsize the text by the end.
266 * Define how to justify lines inside the text area.
267 * The default value is Left.
269 enum LineJustification
271 Left, ///< Justify to the left.
272 Center, ///< Centered.
273 Right, ///< Justify to the right.
274 Justified ///< Line justified.
279 * Create an TextView handle; this can be initialised with TextView::New()
280 * Calling member functions with an uninitialised Dali::Object handle is not allowed.
285 * Copy constructor. Creates another handle that points to the same real object
287 TextView( const TextView& handle );
290 * Assignment operator. Changes this handle to point to another real object
292 TextView& operator=( const TextView& handle );
295 * Create a TextView control with no text
296 * @return A handle the TextView control.
298 static TextView New();
301 * Create a TextView control.
302 * @param[in] text to display.
303 * @return A handle the TextView control.
305 static TextView New( const std::string& text );
308 * @copydoc TextView New( const std::string& text )
310 static TextView New( const MarkupProcessor::StyledTextArray& text );
313 * Downcast an Object handle to TextView. If handle points to a TextView the
314 * downcast produces valid handle. If not the returned handle is left uninitialized.
315 * @param[in] handle Handle to an object
316 * @return handle to a TextView or an uninitialized handle
318 static TextView DownCast( BaseHandle handle );
321 * Virtual destructor.
322 * Dali::Object derived classes typically do not contain member data.
327 * Replace the current text with a new text string.
328 * @param[in] text to display. The string may contain style tags.
330 void SetText( const std::string& text );
333 * Replace the current text with a new text string with style.
334 * @param[in] text with style to display.
336 void SetText( const MarkupProcessor::StyledTextArray& text );
339 * Inserts the given text in the specified position
341 * @param[in] position Where the given text is going to be added.
342 * @param[in] text The text to be added.
344 void InsertTextAt( std::size_t position, const std::string& text );
347 * @copydoc InsertTextAt( std::size_t position, const std::string& text )
349 void InsertTextAt( std::size_t position, const MarkupProcessor::StyledTextArray& text );
352 * Replaces part of the text.
354 * It removes the specified number of characters from the given position and inserts the given text in the same specified position.
356 * @param[in] position of the first character to be removed and Where the given text is going to be added.
357 * @param[in] numberOfCharacters number of characters to be removed.
358 * @param[in] text The text to be added.
360 void ReplaceTextFromTo( std::size_t position, std::size_t numberOfCharacters, const std::string& text );
363 * @copydoc ReplaceTextFromTo( std::size_t position, std::size_t numberOfCharacters, const std::string& text )
365 void ReplaceTextFromTo( std::size_t position, std::size_t numberOfCharacters, const MarkupProcessor::StyledTextArray& text );
368 * 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 * Get the currently displayed text.
377 * @return The currently displayed text.
379 std::string GetText() const;
382 * 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 * Retrieves the line height offset.
390 * @return The line height offset in PointSize units.
392 PointSize GetLineHeightOffset() const;
395 * Sets the given style to the current text.
396 * By default all style settings are applied but a bit mask could be used to modify only certain style settings.
397 * @note TextView doesn't store a copy of the given style, it applies the given style to the current text only.
398 * Subsequent calls to SetText() will override any style set by this method.
399 * @param[in] style The given style
400 * @param[in] mask The bit mask.
402 void SetStyleToCurrentText( const TextStyle& style, TextStyle::Mask mask = TextStyle::ALL );
405 * Set the current text alignment.
406 * Default alignment is (HorizontalCenter | VerticalCenter)
407 * @param[in] align The new alignment option.
409 void SetTextAlignment( Alignment::Type align );
412 * Get the current text alignment combined into a single value.
413 * The values can be tested by using the & operator
414 * and the desired flag. e.g. if (GetTextAlignment() & HorizontalCentre) ...
416 Alignment::Type GetTextAlignment() const;
419 * Sets how to split the text in lines policy.
420 * @param policy The multi-line policy. SplitByNewLineChar is set by default.
422 void SetMultilinePolicy( MultilinePolicy policy );
425 * Gets the split in lines policy.
426 * @return The multi-line policy.
428 MultilinePolicy GetMultilinePolicy() const;
431 * Sets how to display the text inside the TextView when it exceeds the text-view's width.
432 * @param policy The exceed policy. Original is set by default.
434 void SetWidthExceedPolicy( ExceedPolicy policy );
437 * Gets the width exceed policy.
438 * @return The exceed policy.
440 ExceedPolicy GetWidthExceedPolicy() const;
443 * Sets how to display the text inside the TextView when it exceeds the text-view's height.
444 * @param policy The exceed policy. Original is set by default.
446 void SetHeightExceedPolicy( ExceedPolicy policy );
449 * Gets the height exceed policy.
450 * @return The exceed policy.
452 ExceedPolicy GetHeightExceedPolicy() const;
455 * Sets how to justify lines inside the text area.
456 * @param justification The line justification. Left is set by default.
458 void SetLineJustification( LineJustification justification );
461 * Gets the line justification.
462 * @return The line justification.
464 LineJustification GetLineJustification() const;
467 * Sets a fade boundary.
471 * @param[in] fadeBoundary The given fade boundary.
473 void SetFadeBoundary( const FadeBoundary& fadeBoundary );
476 * Retrieves the fade boundary.
480 * @return The fade boundary.
482 const FadeBoundary& GetFadeBoundary() const;
485 * Sets the ellipsize text.
487 * @param[in] ellipsizeText The new text. The string may contain style tags. By default the ellipsize text is '...'
489 void SetEllipsizeText( const std::string& ellipsizeText );
492 * Sets the ellipsize text.
494 * @param[in] ellipsizeText The new text with its style.
496 void SetEllipsizeText( const MarkupProcessor::StyledTextArray& ellipsizeText );
499 * Retrieves the ellipsize text.
501 * @return The ellipsize text.
503 std::string GetEllipsizeText() const;
506 * A mechanism to retrieve layout information from the TextView.
508 * It produces a vector of CharcterLayoutInfo structures which describe the size and position of each character,
509 * two vectors which maps the logical and visual positions of the characters in a bidirectional text, the size
510 * of the whole laid-out text and the scroll offset value.
512 * @see TextLayoutInfo.
514 * @param[out] textLayoutInfo A structure with text layout information.
516 void GetTextLayoutInfo( TextLayoutInfo& textLayoutInfo );
519 * Allows modification of text-actor's position in the depth sort algorithm.
521 * @see Dali::RenderableActor::SetSortModifier()
522 * @param [in] depthOffset the offset to be given to the internal text-actors. Positive values pushing it further back.
524 void SetSortModifier( float depthOffset );
527 * Sets whether text-view renders text using a previously generated snapshot.
529 * Rendering long text using a snapshot may increase performance. The default value is \e true (render using a snapshot).
531 * @param[in] enable Whether text-view is using a snapshot to render text.
533 void SetSnapshotModeEnabled( bool enable );
536 * Retrieves whether text-view is using a snapshot to render text
538 * @return \e true if text-view is using a snapshot to render text, otherwhise it returns \e false.
540 bool IsSnapshotModeEnabled() const;
543 * Enables or disables the text scroll.
545 * When scroll is enabled, snapshot mode will be enabled automatically. Equally, if scroll is disabled
546 * the snapshot mode is restored to the previous value.
548 * @param[in] enable Whether to enable the text scroll.
550 void SetScrollEnabled( bool enable );
553 * Retrieves whether the text scroll is enabled.
555 * @return \e true if the scroll is enabled.
557 bool IsScrollEnabled() const;
560 * Sets a new scroll position.
562 * The new scroll position set could be trimmed if the text doesn't cover the whole text-view.
563 * i.e. If a text-view is 100x100 and a text is 200x100 a scroll position beyond 50x0 will be trimmed to 50x0.
565 * Call IsScrollPositionTrimmed() to know if the last scroll position set has been trimmed.
567 * A signal is emitted. @see ScrolledSignal().
569 * @param[in] position The new scroll position.
571 void SetScrollPosition( const Vector2& position );
574 * Recrieves current scroll position.
576 * @return The scroll position.
578 const Vector2& GetScrollPosition() const;
581 * Whether the last scroll position set was trimmed.
583 * @return \e true if the last scroll position set was trimmed, otherwise \e false.
585 bool IsScrollPositionTrimmed() const;
589 typedef SignalV2< void ( TextView textView, Vector2 scrollDelta ) > ScrolledSignalV2;
592 * Signal emitted when the scroll position changes.
594 * A callback with the following prototype can be connected to this signal.
596 * Callback(TextView textView, Vector2 scrollDelta)
598 * \e textView is the handle of the text-view emitting the signal.
599 * \e scrollDelta is the differente of the current scroll position with the previous one.
601 ScrolledSignalV2& ScrolledSignal();
603 public: // Not intended for application developers
606 * Creates a handle using the Toolkit::Internal implementation.
607 * @param[in] implementation The Control implementation.
609 TextView( Internal::TextView& implementation );
612 * Allows the creation of this Control from an Internal::CustomActor pointer.
613 * @param[in] internal A pointer to the internal CustomActor.
615 TextView( Dali::Internal::CustomActor* internal );
618 } // namespace Toolkit
625 #endif // __DALI_TOOLKIT_ITEM_VIEW_H__