DALi Version 1.0.23
[platform/core/uifw/dali-toolkit.git] / base / dali-toolkit / public-api / controls / text-view / text-view.h
1 #ifndef __DALI_TOOLKIT_TEXT_VIEW_H__
2 #define __DALI_TOOLKIT_TEXT_VIEW_H__
3
4 /*
5  * Copyright (c) 2014 Samsung Electronics Co., Ltd.
6  *
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
10  *
11  * http://www.apache.org/licenses/LICENSE-2.0
12  *
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.
18  *
19  */
20
21 // EXTERNAL INCLUDES
22 #include <string>
23
24 // INTERNAL INCLUDES
25 #include <dali-toolkit/public-api/controls/alignment/alignment.h>
26 #include <dali-toolkit/public-api/markup-processor/markup-processor.h>
27
28 namespace Dali
29 {
30
31 namespace Toolkit
32 {
33
34 namespace Internal DALI_INTERNAL
35 {
36 class TextView;
37 }
38
39 /**
40  * @brief The TextView class is a UI Dali::Toolkit::Control designed to extend the capabilities of the basic Dali::TextActor.
41  *
42  * It provides support for multi-line wrapping, multi-language font detection, text alignment, scrolling and styling.
43  *
44  * See the \link text-view Text View \endlink page of the Programming Guide for more details and examples.
45  */
46 class DALI_IMPORT_API TextView : public Control
47 {
48 public:
49
50   // Signal Names
51   static const char* const SIGNAL_TEXT_SCROLLED; ///< Signal emitted when the scroll position changes. @see ScrolledSignal()
52
53   // Properties
54   static const Property::Index PROPERTY_MARKUP_ENABLED;         ///< name "markup-enabled",       @see SetMarkupProcessingEnabled(), type BOOLEAN
55   static const Property::Index PROPERTY_TEXT;                   ///< name "text",                 @see SetText(),                    type STRING
56   static const Property::Index PROPERTY_MULTILINE_POLICY;       ///< name "multiline-policy",     @see SetMultilinePolicy(),         type STRING
57   static const Property::Index PROPERTY_WIDTH_EXCEED_POLICY;    ///< name "width-exceed-policy",  @see SetWidthExceedPolicy(),       type STRING
58   static const Property::Index PROPERTY_HEIGHT_EXCEED_POLICY;   ///< name "height-exceed-policy", @see SetHeightExceedPolicy(),      type STRING
59   static const Property::Index PROPERTY_LINE_JUSTIFICATION;     ///< name "line-justification",   @see SetLineJustification(),       type STRING
60   static const Property::Index PROPERTY_FADE_BOUNDARY;          ///< name "fade-boundary",        @see SetFadeBoundary(),            type VECTOR4
61   static const Property::Index PROPERTY_LINE_HEIGHT_OFFSET;     ///< name "line-height-offset",   @see SetLineHeightOffset(),        type FLOAT
62   static const Property::Index PROPERTY_HORIZONTAL_ALIGNMENT;   ///< name "horizontal-alignment", @see SetTextAlignment(),           type STRING
63   static const Property::Index PROPERTY_VERTICAL_ALIGNMENT;     ///< name "vertical-alignment",   @see SetTextAlignment(),           type STRING
64
65   /**
66    * @brief Structure used to retrieve Layout info per character.
67    */
68   struct CharacterLayoutInfo
69   {
70     /**
71      * @brief Default constructor.
72      *
73      * Initializes all members to their default values.
74      */
75     CharacterLayoutInfo();
76
77     /**
78      * @brief Empty destructor.
79      *
80      * @note Added to increase coverage.
81      */
82     ~CharacterLayoutInfo();
83
84     /**
85      * @brief Copy constructor.
86      */
87     CharacterLayoutInfo( const CharacterLayoutInfo& characterLayoutInfo );
88
89     /**
90      * @brief Assignment operator.
91      */
92     CharacterLayoutInfo& operator=( const CharacterLayoutInfo& character );
93
94     /**
95      * @brief Constructor.
96      *
97      * @param[in] size of the character.
98      * @param[in] position of the character.
99      * @param[in] isNewParagraphChar Whether the character is a new paragraph character.
100      * @param[in] isRightToLeftCharacter Whether is a right to left character.
101      * @param[in] visible Whether is visible.
102      * @param[in] descender of the character (distance from the base line to the bottom of the character.)
103      */
104     CharacterLayoutInfo( const Size& size,
105                          const Vector3& position,
106                          bool isNewParagraphChar,
107                          bool isRightToLeftCharacter,
108                          bool visible,
109                          float descender );
110
111     Size    mSize;                     ///< Size of the character.
112     Vector3 mPosition;                 ///< Position of the character within the text view.
113     bool    mIsNewLineChar:1;          ///< @deprecated. Use mIsNewParagraphChar instead.
114     bool    mIsNewParagraphChar:1;     ///< Whether this character represent a new paragraph.
115     bool    mIsRightToLeftCharacter:1; ///< Whether it's a right-to-left character.
116     bool    mIsVisible:1;              ///< Whether this character is visible or not.
117     float   mDescender;                ///< The character's descender which is the distance from the baseline to the bottom of the character
118   };
119
120   typedef std::vector<CharacterLayoutInfo> CharacterLayoutInfoContainer; ///< Container of layout info per character.
121
122   /**
123    * @brief Stores some info about a line.
124    */
125   struct LineLayoutInfo
126   {
127     std::size_t mCharacterGlobalIndex; ///< Global index within the whole text of the first character of current line.
128     Size        mSize;                 ///< Size of the current line.
129     float       mAscender;             ///< The max ascender of the current line.
130   };
131
132   typedef std::vector<LineLayoutInfo> LineLayoutInfoContainer; ///< Container of layout info per line.
133
134   /**
135    * @brief How text is laid out.
136    */
137   struct TextLayoutInfo
138   {
139     /**
140      * @brief Default constructor.
141      */
142     TextLayoutInfo();
143
144     /**
145      * @brief Empty destructor.
146      *
147      * @note Added to increase coverage.
148      */
149     ~TextLayoutInfo();
150
151     /**
152      * @brief Copy constructor.
153      */
154     TextLayoutInfo( const TextLayoutInfo& textLayoutInfo );
155
156     /**
157      * @brief Assignment operator.
158      */
159     TextLayoutInfo& operator=( const TextLayoutInfo& textLayoutInfo );
160
161     CharacterLayoutInfoContainer mCharacterLayoutInfoTable;    ///< The table of character's positions and sizes sorted by the character's visual index.
162     LineLayoutInfoContainer      mLines;                       ///< For each line, it stores an index to the first character of the line.
163     std::vector<int>             mCharacterLogicalToVisualMap; ///< The map to store the character's logical (input) index according to its visual (reordered) index.
164     std::vector<int>             mCharacterVisualToLogicalMap; ///< The map to store the character's visual (reordered) index according to its logical (input) index.
165     Size                         mTextSize;                    ///< Text size after relayout.
166     Vector2                      mScrollOffset;                ///< Scroll's position.
167   };
168
169   /**
170    * @brief This structure represents a fade boundary.
171    *
172    * 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.
173    * 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.
174    */
175   struct FadeBoundary
176   {
177     /**
178      * @brief Default constructor.
179      *
180      * Initializes all values to 0. It means no fade boundary.
181      */
182     FadeBoundary();
183
184     /**
185      * @brief Constructor.
186      *
187      * Initializes the fade boundary with the given values.
188      *
189      * @param[in] left value in pixels.
190      * @param[in] right value in pixels.
191      * @param[in] top value in pixels.
192      * @param[in] bottom value in pixels.
193      */
194     FadeBoundary( PixelSize left, PixelSize right, PixelSize top, PixelSize bottom );
195
196     PixelSize mLeft;   ///< The left fade boundary
197     PixelSize mRight;  ///< The right fade boundary
198     PixelSize mTop;    ///< The top fade boundary
199     PixelSize mBottom; ///< The bottom fade bounday
200   };
201
202   /**
203    * @brief Define how to wrap the text's paragraphs in lines.
204    *
205    * \e SplitByNewLineChar will wrap the text's paragraphs in lines when a '\\n' character or a \<br /\> is found.
206    * \e SplitByWord has effect only when TextView size is assigned.
207    * 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.
208    * \e SplitByChar 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 might split a word in two.
210    * The default value is \e SplitByNewLineChar.
211    */
212   enum MultilinePolicy
213   {
214     SplitByNewLineChar, ///< Text's paragraphs will wrap in lines when '\\n' character is found.
215     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.
216     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.
217   };
218
219   /**
220    * @brief Define how to display the lines when they doesn't fit inside the TextView after the text's paragraphs are wrapped in lines.
221    *
222    * The default value is \e Original.
223    */
224   enum ExceedPolicy
225   {
226     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.
227     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.
228     Split,            ///< Will split the lines in a new line(s).
229     ShrinkToFit,      ///< Will shrink the lines to fit the TextView boundary.
230     EllipsizeEnd      ///< Will ellipsize the lines by the end.
231   };
232
233   /**
234    * @brief Define how to justify lines inside the text's boundary.
235    *
236    * The default value is \e Left.
237    */
238   enum LineJustification
239   {
240     Left,     ///< Justify to the left.
241     Center,   ///< Centered.
242     Right,    ///< Justify to the right.
243     Justified ///< Line justified.
244   };
245
246 public:
247   /**
248    * @brief Create a TextView handle; this can be initialised with TextView::New().
249    *
250    * Calling member functions with an uninitialised Dali::Object handle is not allowed.
251    */
252   TextView();
253
254   /**
255    * @brief Copy constructor.
256    *
257    * Creates another handle that points to the same real object
258    * @param[in] handle The handle to copy from
259    */
260   TextView( const TextView& handle );
261
262   /**
263    * @brief Assignment operator.
264    *
265    * Changes this handle to point to another real object
266    * @param[in] handle The handle to copy from
267    * @return a reference to this
268    */
269   TextView& operator=( const TextView& handle );
270
271   /**
272    * @brief Create a TextView control with no text.
273    *
274    * @return A handle the TextView control.
275    */
276   static TextView New();
277
278   /**
279    * @brief Create a TextView control.
280    *
281    * @param[in] text to display.
282    * @return A handle the TextView control.
283    */
284   static TextView New( const std::string& text );
285
286   /**
287    * @brief Create a TextView control with styled text.
288    *
289    * @param[in] text The text with style to display.
290    * @return A handle the TextView control.
291    */
292   static TextView New( const MarkupProcessor::StyledTextArray& text );
293
294   /**
295    * @brief Downcast an Object handle to TextView.
296    *
297    * If handle points to a TextView the
298    * downcast produces valid handle. If not the returned handle is left uninitialized.
299    * @param[in] handle Handle to an object
300    * @return handle to a TextView or an uninitialized handle
301    */
302   static TextView DownCast( BaseHandle handle );
303
304   /**
305    * @brief Destructor
306    *
307    * This is non-virtual since derived Handle types must not contain data or virtual methods.
308    */
309   ~TextView();
310
311   /**
312    * @brief Replace the current text with a new text string.
313    *
314    * @param[in] text to display. The string may contain style tags.
315    */
316   void SetText( const std::string& text );
317
318   /**
319    * @brief Replace the current text with a new text string with style.
320    *
321    * @param[in] text The text with style to display.
322    */
323   void SetText( const MarkupProcessor::StyledTextArray& text );
324
325   /**
326    * @brief Inserts the given text in the specified position.
327    *
328    * @param[in] position Where the given text is going to be added.
329    * @param[in] text The text to be added.
330    */
331   void InsertTextAt( std::size_t position, const std::string& text );
332
333   /**
334    * @brief Inserts the given text with style in the specified position.
335    *
336    * @param[in] position Where the given text is going to be added.
337    * @param[in] text The text with style to be added.
338    */
339   void InsertTextAt( std::size_t position, const MarkupProcessor::StyledTextArray& text );
340
341   /**
342    * @brief Replaces part of the text.
343    *
344    * It removes the specified number of characters from the given position and inserts the given text in the same specified position.
345    *
346    * @param[in] position of the first character to be removed and Where the given text is going to be added.
347    * @param[in] numberOfCharacters number of characters to be removed.
348    * @param[in] text The text to be added.
349    */
350   void ReplaceTextFromTo( std::size_t position, std::size_t numberOfCharacters, const std::string& text );
351
352   /**
353    * @brief Replaces part of the text.
354    *
355    * It removes the specified number of characters from the given position and inserts the given text with style in the same specified position.
356    *
357    * @param[in] position of the first character to be removed and Where the given text is going to be added.
358    * @param[in] numberOfCharacters number of characters to be removed.
359    * @param[in] text The text with style to be added.
360    */
361   void ReplaceTextFromTo( std::size_t position, std::size_t numberOfCharacters, const MarkupProcessor::StyledTextArray& text );
362
363   /**
364    * @brief Removes the specified number of characters from the given position.
365    *
366    * @param[in] position of the first character to be removed.
367    * @param[in] numberOfCharacters number of characters to be removed.
368    */
369   void RemoveTextFrom( std::size_t position, std::size_t numberOfCharacters );
370
371   /**
372    * @brief Get the currently displayed text.
373    *
374    * @return The currently displayed text.
375    */
376   std::string GetText() const;
377
378   /**
379    * @brief Sets a line height offset.
380    *
381    * The line height offset will be added to the font line height.
382    * @param [in] offset The height offset in PointSize units.
383    */
384   void SetLineHeightOffset( PointSize offset );
385
386   /**
387    * @brief Retrieves the line height offset.
388    *
389    * @return The line height offset in PointSize units.
390    */
391   PointSize GetLineHeightOffset() const;
392
393   /**
394    * @brief Sets the given style to the current text.
395    *
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.
401    */
402   void SetStyleToCurrentText( const TextStyle& style, TextStyle::Mask mask = TextStyle::ALL );
403
404   /**
405    * @brief Set the current text alignment.
406    *
407    * Default alignment is (HorizontalCenter | VerticalCenter)
408    * @param[in] align The new alignment option.
409    */
410   void SetTextAlignment( Alignment::Type align );
411
412   /**
413    * @brief Get the current text alignment combined into a single value.
414    *
415    * The values can be tested by using the & operator
416    * and the desired flag. e.g. if (GetTextAlignment() & HorizontalCentre) ...
417    * @return the combined alignment
418    */
419   Alignment::Type GetTextAlignment() const;
420
421   /**
422    * @brief Sets how to split the paragraphs into lines.
423    *
424    * @param policy The multi-line policy. \e SplitByNewLineChar is set by default.
425    */
426   void SetMultilinePolicy( MultilinePolicy policy );
427
428   /**
429    * @brief Gets the wrap in lines policy.
430    *
431    * @return The multi-line policy.
432    */
433   MultilinePolicy GetMultilinePolicy() const;
434
435   /**
436    * @brief Sets how to display the text inside the TextView when it exceeds the text-view's width.
437    *
438    * @param policy The exceed policy. Original is set by default.
439    */
440   void SetWidthExceedPolicy( ExceedPolicy policy );
441
442   /**
443    * @brief Gets the width exceed policy.
444    *
445    * @return The exceed policy.
446    */
447   ExceedPolicy GetWidthExceedPolicy() const;
448
449   /**
450    * @brief Sets how to display the text inside the TextView when it exceeds the text-view's height.
451    *
452    * @param policy The exceed policy. Original is set by default.
453    */
454   void SetHeightExceedPolicy( ExceedPolicy policy );
455
456   /**
457    * @brief Gets the height exceed policy.
458    *
459    * @return The exceed policy.
460    */
461   ExceedPolicy GetHeightExceedPolicy() const;
462
463   /**
464    * @brief Sets how to justify lines inside the text's boundary.
465    *
466    * @param justification The line justification. Left is set by default.
467    */
468   void SetLineJustification( LineJustification justification );
469
470   /**
471    * @brief Gets the line justification.
472    *
473    * @return The line justification.
474    */
475   LineJustification GetLineJustification() const;
476
477   /**
478    * @brief Sets a fade boundary.
479    *
480    * @see FadeBoundary.
481    *
482    * @param[in] fadeBoundary The given fade boundary.
483    */
484   void SetFadeBoundary( const FadeBoundary& fadeBoundary );
485
486   /**
487    * @brief Retrieves the fade boundary.
488    *
489    * @see FadeBoundary.
490    *
491    * @return The fade boundary.
492    */
493   const FadeBoundary& GetFadeBoundary() const;
494
495   /**
496    * @brief Sets the ellipsize text.
497    *
498    * @param[in] ellipsizeText The new text. The string may contain style tags. By default the ellipsize text is '...'
499    */
500   void SetEllipsizeText( const std::string& ellipsizeText );
501
502   /**
503    * @brief Sets the ellipsize text with style.
504    *
505    * @param[in] ellipsizeText The new text with its style.
506    */
507   void SetEllipsizeText( const MarkupProcessor::StyledTextArray& ellipsizeText );
508
509   /**
510    * @brief Retrieves the ellipsize text.
511    *
512    * @return The ellipsize text.
513    */
514   std::string GetEllipsizeText() const;
515
516   /**
517    * @brief A mechanism to retrieve layout information from the TextView.
518    *
519    * It produces a vector of CharcterLayoutInfo structures which describe the size and position of each character,
520    * two vectors which maps the logical and visual positions of the characters in a bidirectional text, the size
521    * of the whole laid-out text and the scroll offset value.
522    *
523    * @see TextLayoutInfo.
524    *
525    * @param[out] textLayoutInfo A structure with text layout information.
526    */
527   void GetTextLayoutInfo( TextLayoutInfo& textLayoutInfo );
528
529   /**
530    * @brief Allows modification of text-actor's position in the depth sort algorithm.
531    *
532    * @see Dali::RenderableActor::SetSortModifier()
533    * @param [in] depthOffset the offset to be given to the internal text-actors. Positive values pushing it further back.
534    */
535   void SetSortModifier( float depthOffset );
536
537   /**
538    * @brief Sets whether text-view renders text using a previously generated snapshot.
539    *
540    * Rendering long text using a snapshot may increase performance. The default value is \e false (render without using a snapshot).
541    *
542    * @param[in] enable Whether text-view is using a snapshot to render text.
543    */
544   void SetSnapshotModeEnabled( bool enable );
545
546   /**
547    * @brief Retrieves whether text-view is using a snapshot to render text.
548    *
549    * @return \e true if text-view is using a snapshot to render text, otherwhise it returns \e false.
550    */
551   bool IsSnapshotModeEnabled() const;
552
553   /**
554    * @brief Sets whether markup processing should be carried out.
555    *
556    * To use markup, applications need to SetMarkupProcessingEnabled first, then SetText().
557    *
558    * @see SetText()
559    * @param[in] enable whether markup processing is carried out or not.
560    */
561   void SetMarkupProcessingEnabled( bool enable );
562
563   /**
564    * @brief Retrieves whether text-view is processing markup text
565    *
566    * @return \e true if text-view markup processing is enabled, otherwhise it returns \e false.
567    */
568   bool IsMarkupProcessingEnabled() const;
569
570   /**
571    * @brief Enables or disables the text scroll.
572    *
573    * When scroll is enabled, snapshot mode will be enabled automatically. Equally, if scroll is disabled
574    * the snapshot mode is restored to the previous value.
575    *
576    * @param[in] enable Whether to enable the text scroll.
577    */
578   void SetScrollEnabled( bool enable );
579
580   /**
581    * @brief Retrieves whether the text scroll is enabled.
582    *
583    * @return \e true if the scroll is enabled.
584    */
585   bool IsScrollEnabled() const;
586
587   /**
588    * @brief Sets a new scroll position.
589    *
590    * The new scroll position set could be trimmed if the text doesn't cover the whole text-view.
591    * i.e. If a text-view is 100x100 and a text is 200x100 a scroll position beyond 50x0 will be trimmed to 50x0.
592    *
593    * Call IsScrollPositionTrimmed() to know if the last scroll position set has been trimmed.
594    *
595    * A signal is emitted. @see ScrolledSignal().
596    *
597    * @param[in] position The new scroll position.
598    */
599   void SetScrollPosition( const Vector2& position );
600
601   /**
602    * @brief Recrieves current scroll position.
603    *
604    * @return The scroll position.
605    */
606   const Vector2& GetScrollPosition() const;
607
608   /**
609    * @brief Whether the last scroll position set was trimmed.
610    *
611    * @return \e true if the last scroll position set was trimmed, otherwise \e false.
612    */
613   bool IsScrollPositionTrimmed() const;
614
615 public:
616   /// @brief Signal types
617   typedef SignalV2< void ( TextView textView, Vector2 scrollDelta ) > ScrolledSignalV2;
618
619   /**
620    * @brief Signal emitted when the text is scrolled inside the text-view.
621    *
622    * A callback with the following prototype can be connected to this signal.
623    *
624    * Callback(TextView textView, Vector2 scrollDelta)
625    *
626    * \e textView is the handle of the text-view emitting the signal.
627    * \e scrollDelta is the differente of the current scroll position with the previous one.
628    * @return The signal to connect to
629    */
630   ScrolledSignalV2& ScrolledSignal();
631
632 public: // Not intended for application developers
633
634   /**
635    * @brief Creates a handle using the Toolkit::Internal implementation.
636    * @note Not intended for application developers
637    *
638    * @param[in]  implementation  The Control implementation.
639    */
640   DALI_INTERNAL TextView( Internal::TextView& implementation );
641
642   /**
643    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
644    * @note Not intended for application developers
645    *
646    * @param[in]  internal  A pointer to the internal CustomActor.
647    */
648   explicit DALI_INTERNAL TextView( Dali::Internal::CustomActor* internal );
649 };
650
651 } // namespace Toolkit
652
653 } // namespace Dali
654
655 #endif // __DALI_TOOLKIT_ITEM_VIEW_H__