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