dali-toolkit/internal/controls/text-view/relayout-utilities.h

   1 #ifndef __DALI_TOOLKIT_INTERNAL_RELAYOUT_UTILITIES_H__
   2 #define __DALI_TOOLKIT_INTERNAL_RELAYOUT_UTILITIES_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 // INTERNAL INCLUDES
  22 #include <dali-toolkit/public-api/controls/alignment/alignment.h>
  23 #include <dali-toolkit/public-api/controls/text-view/text-view.h>
  24 #include <dali-toolkit/internal/controls/text-view/text-view-impl.h>
  25
  26 namespace Dali
  27 {
  28
  29 namespace Toolkit
  30 {
  31
  32 namespace Internal
  33 {
  34
  35 //Forward declarations.
  36 class TextActorCache;
  37
  38 namespace TextViewRelayout
  39 {
  40
  41 extern const float MINIMUM_FADE_BOUNDARY; // When the fade boundary is the same as the text-view boundary, this constant reduces it in order to avoid a zero division.
  42
  43 /**
  44  * Define how to wrap a paragraph in lines.
  45  */
  46 enum HorizontalWrapType
  47 {
  48   WrapByCharacter,                  ///< Wrap the paragraph per character (It may split a word in two).
  49   WrapByWord,                       ///< Wrap the paragraph by word.
  50   WrapByWordAndSplit,               ///< Wrap the paragraph by word and split a word if it doesn't fit.
  51   WrapByParagraphCharacter,         ///< Wrap the paragraph when a '\n' is found.
  52   WrapByParagraphCharacterAndSplit  ///< Wrap the paragraph when a '\n' is found and split if it doesn't fit.
  53 };
  54
  55 /**
  56  * Different types of visibility tests (text-actor - text-view).
  57  */
  58 enum VisibilityTestType
  59 {
  60   FULLY_VISIBLE,           ///< The text-actor is completely inside the text-view.
  61   FULLY_VISIBLE_WIDTH,     ///< The text-actor is completely between the right and the left boundaries of the text-view.
  62   FULLY_VISIBLE_HEIGHT,    ///< The text-actor is completely between the top and the bottom boundaries of the text-view.
  63   PARTIALLY_VISIBLE,       ///< The text-actor is partially inside the text-view.
  64   PARTIALLY_VISIBLE_WIDTH, ///< The text-actor is partially inside the width of the text-view. It may be completely above and bellow the top and bottom boundaries of the text-view.
  65   PARTIALLY_VISIBLE_HEIGHT ///< The text-actor is partially inside the height of the text-view. It may be completely on the left and on the right the left and right boundaries of the text-view.
  66 };
  67
  68 /**
  69  * Temporary parameters used in the relayout process.
  70  */
  71 struct RelayoutParameters
  72 {
  73   /**
  74    * Default constructor.
  75    *
  76    * Initializes all members to their defaults.
  77    */
  78   RelayoutParameters();
  79
  80   /**
  81    * Empty destructor.
  82    *
  83    * @note Added to increase coverage.
  84    */
  85   ~RelayoutParameters();
  86
  87   Vector3                            mPositionOffset;            ///< Offset (position.x + size.width, position.y, position.z) of the previous text-actor.
  88   Size                               mParagraphSize;             ///< Current paragraphs's size.
  89   Size                               mWordSize;                  ///< Current word's size.
  90   Size                               mCharacterSize;             ///< Current character's size.
  91   TextViewProcessor::TextInfoIndices mIndices;                   ///< Current indices to paragraph, word and character.
  92   std::size_t                        mCharacterGlobalIndex;      ///< Index to a single character within the whole text.
  93   bool                               mIsFirstCharacter:1;        ///< Whether is the first character of the whole text.
  94   bool                               mIsFirstCharacterOfWord:1;  ///< Whether is the first character of the word.
  95   bool                               mIsNewLine:1;               ///< Whether the current character is the first character of a new line.
  96   bool                               mIsNewParagraphCharacter:1; ///< Whether the current character is a new paragraph character.
  97   bool                               mIsWhiteSpace:1;            ///< Whether the current character is a white space.
  98   bool                               mIsVisible:1;               ///< Whether the current character is visible.
  99 };
 100
 101 /**
 102  * Parameters used to calculate the gradient of text-actors when fading is enabled.
 103  */
 104 struct FadeParameters
 105 {
 106   /**
 107    * Default constructor.
 108    *
 109    * Initializes all members to their defaults.
 110    */
 111   FadeParameters();
 112
 113   /**
 114    * Empty destructor.
 115    *
 116    * @note Added to increase coverage.
 117    */
 118   ~FadeParameters();
 119
 120   float   mRightFadeBoundary;         ///< Distance from the right edge of the text-view to the right edge of the fade boundary.
 121   float   mRightFadeThreshold;        ///< Point from where fade out starts (by right edge).
 122   float   mRightFadeBoundaryOffset;   ///< Same as above plus an offset if the value is zero. Used to avoid a zero division.
 123   float   mRightFadeThresholdOffset;  ///< Same as above plus an offset if the value is zero. Used to avoid a zero division.
 124   Vector2 mRightAlphaCoeficients;     ///< The fade out rect coeficients for the right side of the text-view.
 125   float   mLeftFadeBoundary;          ///< Distance from the left edge of the text-view to the left edge of the fade boundary.
 126   float   mLeftFadeThreshold;         ///< Point from where fade out starts (by left edge).
 127   float   mLeftFadeBoundaryOffset;    ///< Same as above plus an offset if the value is zero. Used to avoid a zero division.
 128   float   mLeftFadeThresholdOffset;   ///< Same as above plus an offset if the value is zero. Used to avoid a zero division.
 129   Vector2 mLeftAlphaCoeficients;      ///< The fade out rect coeficients for the left side of the text-view.
 130   float   mTopFadeBoundary;           ///< Distance from the top edge of the text-view to the top edge of the fade boundary.
 131   float   mTopFadeThreshold;          ///< Point from where fade out starts (by top edge).
 132   float   mTopFadeBoundaryOffset;     ///< Same as above plus an offset if the value is zero. Used to avoid a zero division.
 133   float   mTopFadeThresholdOffset;    ///< Same as above plus an offset if the value is zero. Used to avoid a zero division.
 134   Vector2 mTopAlphaCoeficients;       ///< The fade out rect coeficients for the top side of the text-view.
 135   float   mBottomFadeBoundary;        ///< Distance from the bottom edge of the text-view to the bottom edge of the fade boundary.
 136   float   mBottomFadeThreshold;       ///< Point from where fade out starts (by bottom edge).
 137   float   mBottomFadeBoundaryOffset;  ///< Same as above plus an offset if the value is zero. Used to avoid a zero division.
 138   float   mBottomFadeThresholdOffset; ///< Same as above plus an offset if the value is zero. Used to avoid a zero division.
 139   Vector2 mBottomAlphaCoeficients;    ///< The fade out rect coeficients for the bottom side of the text-view.
 140   bool    mIsPartiallyVisible:1;      ///< Whether the current character is partially visible.
 141 };
 142
 143 /**
 144  * Parameters used to calculate the ellipsize.
 145  */
 146 struct EllipsizeParameters
 147 {
 148   /**
 149    * Default constructor.
 150    *
 151    * Initializes all members to their defaults.
 152    */
 153   EllipsizeParameters();
 154
 155   /**
 156    * Empty destructor.
 157    *
 158    * @note Added to increase coverage.
 159    */
 160   ~EllipsizeParameters();
 161
 162   Vector3     mPosition;                       ///< Position of the first character of the ellipsize text.
 163   float       mLineDescender;                  ///< Distance from the base line to the bottom.
 164   float       mLineWidth;                      ///< Current line's width.
 165   Size        mEllipsizeBoundary;              ///< Where to start to ellipsize a line.
 166   std::size_t mFirstIndex;                     ///< Global index within the whole text of the first character of the line.
 167   std::size_t mLastIndex;                      ///< Global index within the whole text of the last character of the line.
 168   bool        mEllipsizeLine:1;                ///< Whether current line must be ellipsized.
 169   bool        mIsLineWidthFullyVisible:1;      ///< Whether current line fits in text-view's width.
 170   bool        mIsLineHeightFullyVisible:1;     ///< Whether current line fits in text-view's height.
 171   bool        mIsNextLineFullyVisibleHeight:1; ///< Whether next line fits in text-view's height.
 172   bool        mCreateEllipsizedTextActors:1;   ///< Whether to create text-actors for the ellipsized text.
 173   bool        mLineFits:1;                     ///< Whether the current line fits in the boundary of the text-view.
 174   bool        mWordFits:1;                     ///< Whether the current word fits in the boundary of the text-view.
 175 };
 176
 177 /**
 178  * Stores underline info for a group of consecutive characters in the same line.
 179  */
 180 struct UnderlineInfo
 181 {
 182   /**
 183    * Default constructor.
 184    *
 185    * Initializes all members to their defaults.
 186    */
 187   UnderlineInfo();
 188
 189   /**
 190    * Empty destructor.
 191    *
 192    * @note Added to increase coverage.
 193    */
 194   ~UnderlineInfo();
 195
 196   float mMaxHeight;    ///< The maximum height.
 197   float mMaxThickness; ///< The maximum underline's thickness.
 198   float mPosition;     ///< The underline's position of the character with the maximum underline's thickness.
 199 };
 200
 201 /**
 202  * Stores underline info for each group of consecutive underlined characters.
 203  * It also stores some status used when traversing the whole text.
 204  */
 205 struct TextUnderlineStatus
 206 {
 207   /**
 208    * Default constructor.
 209    *
 210    * Initializes each member to its default.
 211    */
 212   TextUnderlineStatus();
 213
 214   /**
 215    * Empty destructor.
 216    *
 217    * @note Added to increase coverage.
 218    */
 219   ~TextUnderlineStatus();
 220
 221   std::vector<UnderlineInfo> mUnderlineInfo;            ///< Underline info for each group of consecutive underlined characters.
 222   std::size_t                mCharacterGlobalIndex;     ///< Global index (within the whole text) to current character.
 223   std::size_t                mLineGlobalIndex;          ///< Index to current line. It takes into account the current layout configuration (is not the number of \n)
 224   bool                       mCurrentUnderlineStatus:1; ///< Whether current character is underlined.
 225 };
 226
 227 /**
 228  * Stores layout information of a line.
 229  */
 230 struct LineLayoutInfo
 231 {
 232   /**
 233    * Default constructor.
 234    *
 235    * Initializes each member to its default.
 236    */
 237   LineLayoutInfo();
 238
 239   /**
 240    * Empty destructor.
 241    *
 242    * @note Added to increase coverage.
 243    */
 244   ~LineLayoutInfo();
 245
 246   float mLineLength;    ///< The length of the portion of the paragraph which fits on the text-view width.
 247   float mMaxCharHeight; ///< The maximum height of all characters of the portion of the paragraph which fits on the text-view width.
 248   float mMaxAscender;   ///< The maximum ascender of all characters of the portion of the paragraph which fits on the text-view width.
 249 };
 250
 251 /**
 252  * Calculates the layout info of the portion of the paragraph which fits on the text-view width.
 253  *
 254  * @param[in] parentWidth Text-view width
 255  * @param[in] indices Indices to the word and character.
 256  * @param[in] paragraphLayoutInfo Layout info for the paragraph.
 257  * @param[in] splitPolicy Whether a paragraph is wraped by word, by character or by word and character.
 258  * @param[in] shrinkFactor Shrink factor used.
 259  * @param[out] layoutInfo Layout information of the part of the paragraph which fits in the text-view width.
 260  */
 261 void CalculateLineLayout( float parentWidth,
 262                           const TextViewProcessor::TextInfoIndices& indices,
 263                           const TextViewProcessor::ParagraphLayoutInfo& paragraphLayoutInfo,
 264                           HorizontalWrapType splitPolicy,
 265                           float shrinkFactor,
 266                           LineLayoutInfo& layoutInfo );
 267
 268 /**
 269  * Reorders the text layout of each line of each paragraph of the text.
 270  *
 271  * @param[in,out] relayoutData The text-view's data structures.
 272  */
 273 void ReorderRightToLeftLayout( TextView::RelayoutData& relayoutData );
 274
 275 /**
 276  * Calculates the \e x offset position for the whole text.
 277  *
 278  * @param[in] horizontalTextAlignment The horizontal alignment type.
 279  * @param[in] parentWidth The parent's width.
 280  * @param[in] wholeTextWidth The whole text's width.
 281  * @return The \e x position offset.
 282  */
 283 float CalculateXoffset( Toolkit::Alignment::Type horizontalTextAlignment, float parentWidth, float wholeTextWidth );
 284
 285 /**
 286  * Calculates the \e y offset position for the whole text.
 287  *
 288  * @param[in] verticalTextAlignment The vertical alignment type.
 289  * @param[in] parentHeight The parent's height.
 290  * @param[in] wholeTextHeight The whole text's height.
 291  * @return The \e y position offset.
 292  */
 293 float CalculateYoffset( Toolkit::Alignment::Type verticalTextAlignment, float parentHeight, float wholeTextHeight );
 294
 295 /**
 296  * Calculates the \e x offset position for one line.
 297  *
 298  * @param[in] justification The line justification type.
 299  * @param[in] wholeTextWidth The whole text's width.
 300  * @param[in] lineLength The line's length.
 301  * @return The \e x position offset.
 302  *
 303  */
 304 float CalculateJustificationOffset( Toolkit::TextView::LineJustification justification, float wholeTextWidth, float lineLength );
 305
 306 /**
 307  * Whether text-actor is visible for Fade and Ellipsize exceed policies.
 308  *
 309  * It does different visibility tests according the given parameter \e type. @see VisibilityTestType.
 310  *
 311  * @param[in] position Position of the character.
 312  * @param[in] size Size of the character.
 313  * @param[in] parentSize Parent's size.
 314  * @param[in] type One of FULLY_VISIBLE, PARTIALLY_VISIBLE, PARTIALLY_VISIBLE_WIDTH or PARTIALLI_VISIBLE_HEIGHT.
 315  * @return \e true if is visible.
 316  */
 317 bool IsVisible( const Vector3& position, const Size& size, const Size& parentSize, VisibilityTestType type );
 318
 319 /**
 320  * Calculates the coeficients of the rect equation for the two given points.
 321  *
 322  * @param[in] p0 A point of the rect.
 323  * @param[in] p1 Another point of the rect.
 324  *
 325  * @return The \e gradient is returned in the \e x member and the \e constant \e term is returned in the \e y value.
 326  */
 327 Vector2 CalculateRectParameters( const Vector2& p0, const Vector2& p1 );
 328
 329 /**
 330  * Aligns the whole text within the text-view.
 331  *
 332  * @param[in] layoutParameters The layout parameters.
 333  * @param[in,out] relayoutData The text-view's data structures.
 334  */
 335 void UpdateAlignment( const TextView::LayoutParameters& layoutParameters,
 336                       TextView::RelayoutData& relayoutData );
 337
 338 /**
 339  * Calculates the bearing for the given character.
 340  *
 341  * @param[in,out] characterLayoutInfo Character layout info.
 342  * @param[in,out] relayoutData The text-view's data structures.
 343  */
 344 void CalculateBearing( TextViewProcessor::CharacterLayoutInfo& characterLayoutInfo,
 345                        TextView::RelayoutData& relayoutData );
 346
 347 /**
 348  * Updates the character's layout info table.
 349  *
 350  * This table is used to pass the size, the position and other layout info to other controls/actors.
 351  *
 352  * @param[in,out] minMaxXY The boundary box of the whole text.
 353  * @param[in,out] wordLayoutInfo Word layout info.
 354  * @param[in,out] characterLayoutInfo Character layout info.
 355  * @param[in,out] relayoutParameters Temporary layout parameters.
 356  * @param[in,out] relayoutData The text-view's data structures.
 357  */
 358 void UpdateLayoutInfoTable( Vector4& minMaxXY,
 359                             TextViewProcessor::WordLayoutInfo& wordLayoutInfo,
 360                             TextViewProcessor::CharacterLayoutInfo& characterLayoutInfo,
 361                             RelayoutParameters& relayoutParameters,
 362                             TextView::RelayoutData& relayoutData );
 363
 364 /**
 365  * Calculates the text-actor visibility and fade parameters.
 366  *
 367  * @param[in] layoutParameters The layout parameters.
 368  * @param[in] characterLayoutInfo Character layout info.
 369  * @param[in] style The style of the character. Used to get the color (and alpha) of the character.
 370  * @param[in,out] relayoutParameters Temporary layout parameters.
 371  * @param[in,out] fadeParameters Temporary fade parameters.
 372  * @param[in,out] relayoutData The text-view's data structures.
 373  */
 374 void CalculateVisibilityForFade( const Internal::TextView::LayoutParameters& layoutParameters,
 375                                  TextViewProcessor::CharacterLayoutInfo& characterLayoutInfo,
 376                                  const TextStyle& style,
 377                                  RelayoutParameters& relayoutParameters,
 378                                  FadeParameters& fadeParameters,
 379                                  TextView::RelayoutData& relayoutData );
 380
 381 /**
 382  * Calculates the text-actor visibility and creates eliipsize text-actors.
 383  *
 384  * @param[in] layoutParameters The layout parameters.
 385  * @param[in] characterLayoutInfo Character layout info.
 386  * @param[in,out] ellipsizeParameters Temporary ellipsize parameters.
 387  * @param[in,out] relayoutData The text-view's data structures.
 388  */
 389 void CalculateVisibilityForEllipsize( const Internal::TextView::LayoutParameters& layoutParameters,
 390                                       TextViewProcessor::CharacterLayoutInfo& characterLayoutInfo,
 391                                       EllipsizeParameters& ellipsizeParameters,
 392                                       TextView::RelayoutData& relayoutData );
 393
 394 /**
 395  * Creates the actors needed for the ellipsized text.
 396  *
 397  * @param[in,out] ellipsizeParameters Temporary ellipsize parameters.
 398  * @param[in,out] relayoutData The text-view's data structures.
 399  */
 400 void CreateEllipsizeTextActor( const EllipsizeParameters& ellipsizeParameters,
 401                                TextView::RelayoutData& relayoutData );
 402
 403 /**
 404  * Replace the text which exceeds the boundary by the ellipsis text.
 405  *
 406  * @param[in] layoutParameters The layout parameters.
 407  * @param[in,out] ellipsisParameters Temporary ellipsis parameters.
 408  * @param[in,out] relayoutData The text-view's data structures.
 409  */
 410 void EllipsizeLine( const TextView::LayoutParameters& layoutParameters,
 411                     EllipsizeParameters& ellipsizeParameters,
 412                     TextView::RelayoutData& relayoutData );
 413
 414 /**
 415  * Traverse all text data structure setting its visibility to true.
 416  *
 417  * @param[in,out] relayoutData The text-view's data structures.
 418  */
 419 void SetTextVisible( TextView::RelayoutData& relayoutData );
 420
 421 /**
 422  * Calculates the visibility and fade parameters.
 423  *
 424  * @param[in] layoutParameters The layout parameters.
 425  * @param[in] visualParameters Some visual parameters (fade, sort modifier and blending).
 426  * @param[in,out] relayoutData The text-view's data structures.
 427  */
 428 void UpdateVisibilityForFade( const TextView::LayoutParameters& layoutParameters,
 429                               const TextView::VisualParameters& visualParameters,
 430                               TextView::RelayoutData& relayoutData );
 431 /**
 432  * Calculates the visibility for text ellipsize.
 433  *
 434  * @param[in] layoutParameters The layout parameters.
 435  * @param[in] visualParameters Some visual parameters (fade, sort modifier and blending).
 436  * @param[in,out] relayoutData The text-view's data structures.
 437  */
 438 void UpdateVisibilityForEllipsize( const TextView::LayoutParameters& layoutParameters,
 439                                    const TextView::VisualParameters& visualParameters,
 440                                    TextView::RelayoutData& relayoutData );
 441 /**
 442  * Calculates the visibility and fade parameters.
 443  *
 444  * @param[in] layoutParameters The layout parameters.
 445  * @param[in] visualParameters Some visual parameters (fade, sort modifier and blending).
 446  * @param[in,out] relayoutData The text-view's data structures.
 447  */
 448 void UpdateVisibility( const TextView::LayoutParameters& layoutParameters,
 449                        const TextView::VisualParameters& visualParameters,
 450                        TextView::RelayoutData& relayoutData );
 451
 452 /**
 453  * Traverse all text initializing all non initialized text-actor handles
 454  * and updating text-actor handles with new size, position, ...
 455  *
 456  * @param[in] visualParameters Some visual parameters (fade, sort modifier and blending).
 457  * @param[in,out] relayoutData Natural size (metrics), layout, text-actor info.
 458  * @param[in] createGlyphActors Whether to create RenderableActor for text-actors or emojis.
 459  */
 460 void UpdateTextActorInfo( const TextView::VisualParameters& visualParameters,
 461                           TextView::RelayoutData& relayoutData,
 462                           bool createGlyphActors );
 463
 464 /**
 465  * Traverses the whole text and for each piece of underlined text,
 466  * it calculates the maximum thickness and the position of that particular piece of underlined text.
 467  *
 468  * @param[in,out] relayoutData Natural size (metrics), layout, text-actor info and conversion from visual to logical order and vice versa (for RTL text).
 469  */
 470 void CalculateUnderlineInfo( TextView::RelayoutData& relayoutData );
 471
 472 /**
 473  * Traverses the whole text and for each piece of underlined text,
 474  * it sets the previously calculated maximum thickness and the position of that particular piece of underlined text.
 475  *
 476  * @param[in,out] relayoutData Natural size (metrics), layout, text-actor info and conversion from visual to logical order and vice versa (for RTL text).
 477  */
 478 void SetUnderlineInfo( TextView::RelayoutData& relayoutData );
 479
 480 /**
 481  * Remove renderable-actor from the text-view.
 482  *
 483  * @param[in,out] textView The text-view.
 484  * @param[in] glyphActors renderable-actors to be removed from the text-view.
 485  */
 486 void RemoveGlyphActors( Actor textView,
 487                         const std::vector<RenderableActor>& glyphActors );
 488
 489 /**
 490  * Inserts the text-actors into the text-view and the text-actor's list.
 491  *
 492  * @param[in,out] textView The text-view.
 493  * @param[in,out] relayoutData The text-view's data structures.
 494  */
 495 void InsertToTextView( Actor textView,
 496                        TextView::RelayoutData& relayoutData );
 497
 498 /**
 499  * Retrieves a new glyph-actor from the cache of text-actors or creating a new one if it's empty.
 500  *
 501  * @param[in] text The text-actor's text.
 502  * @param[in] style The text-actor's style.
 503  * @param[in] cache The cache of text-actors.
 504  *
 505  * @return a RenderableActor with the text's glyph.
 506  */
 507 RenderableActor CreateGlyphActor( const Text& text, const TextStyle& style, TextActorCache& cache );
 508
 509 } // namespace TextViewRelayout
 510
 511 } // namespace Internal
 512
 513 } // namespace Toolkit
 514
 515 } // namespace Dali
 516
 517 #endif // __DALI_TOOLKIT_INTERNAL_RELAYOUT_UTILITIES_H__