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