base/dali-toolkit/public-api/controls/text-view/text-view.h

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