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