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