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