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 the type of line wrap.
  44  */
  45 enum HorizontalWrapType
  46 {
  47   WrapByCharacter,    ///< Wrap a line per character (It may split a word in two).
  48   WrapByWord,         ///< Wrap a line by word.
  49   WrapByWordAndSplit, ///< Wrap the line by word and split a word if it doesn't fit.
  50   WrapByLine,         ///< Wrap the line when a \n is found.
  51   WrapByLineAndSplit  ///< Wrap the line 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                               mLineSize;                 ///< Current line's size.
  88   Size                               mWordSize;                 ///< Current word's size.
  89   Size                               mCharacterSize;            ///< Current character's size.
  90   TextViewProcessor::TextInfoIndices mIndices;                  ///< Current indices to line, group of words, 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                               mIsNewLineCharacter:1;     ///< Whether the current character is a new line 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 laid out 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 laid out line.
 166   std::size_t mLastIndex;                      ///< Global index within the whole text of the last character of the laid out 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 laid out 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 laid out 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 the piece of a line.
 228  */
 229 struct SubLineLayoutInfo
 230 {
 231   /**
 232    * Default constructor.
 233    *
 234    * Initializes each member to its default.
 235    */
 236   SubLineLayoutInfo();
 237
 238   /**
 239    * Empty destructor.
 240    *
 241    * @note Added to increase coverage.
 242    */
 243   ~SubLineLayoutInfo();
 244
 245   float mLineLength;    ///< The length of the portion of the line which fits on the text-view width.
 246   float mMaxCharHeight; ///< The maximum height of all characters of the portion of line which fits on the text-view width.
 247   float mMaxAscender;   ///< The maximum ascender of all characters of the portion of line which fits on the text-view width.
 248 };
 249
 250 /**
 251  * Calculates the layout info of the portion of the line which fits on the text-view width.
 252  *
 253  * @param[in] parentWidth Text-view width
 254  * @param[in] indices Indices to the word group, word and character.
 255  * @param[in] lineLayoutInfo Layout info for the line.
 256  * @param[in] splitPolicy Whether a line 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 line which fits in the text-view width.
 259  */
 260 void CalculateSubLineLayout( float parentWidth,
 261                              const TextViewProcessor::TextInfoIndices& indices,
 262                              const TextViewProcessor::LineLayoutInfo& lineLayoutInfo,
 263                              HorizontalWrapType splitPolicy,
 264                              float shrinkFactor,
 265                              SubLineLayoutInfo& 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] characterLayoutInfo Character layout info.
 346  * @param[in,out] relayoutData The text-view's data structures.
 347  */
 348 void UpdateLayoutInfoTable( Vector4& minMaxXY,
 349                             TextViewProcessor::WordGroupLayoutInfo& wordGroupLayoutInfo,
 350                             TextViewProcessor::WordLayoutInfo& wordLayoutInfo,
 351                             TextViewProcessor::CharacterLayoutInfo& characterGroupLayoutInfo,
 352                             RelayoutParameters& relayoutParameters,
 353                             TextView::RelayoutData& relayoutData );
 354
 355 /**
 356  * Calculates the text-actor visibility and fade parameters.
 357  *
 358  * @param[in] layoutParameters The layout parameters.
 359  * @param[in] characterLayoutInfo Character layout info.
 360  * @param[in,out] relayoutParameters Temporary layout parameters.
 361  * @param[in,out] fadeParameters Temporary fade parameters.
 362  * @param[in,out] relayoutData The text-view's data structures.
 363  */
 364 void CalculateVisibilityForFade( const Internal::TextView::LayoutParameters& layoutParameters,
 365                                  TextViewProcessor::CharacterLayoutInfo& characterLayoutInfo,
 366                                  RelayoutParameters& relayoutParameters,
 367                                  FadeParameters& fadeParameters,
 368                                  TextView::RelayoutData& relayoutData );
 369
 370 /**
 371  * Calculates the text-actor visibility and creates eliipsize text-actors.
 372  *
 373  * @param[in] layoutParameters The layout parameters.
 374  * @param[in] characterLayoutInfo Character layout info.
 375  * @param[in,out] ellipsizeParameters Temporary ellipsize parameters.
 376  * @param[in,out] relayoutData The text-view's data structures.
 377  */
 378 void CalculateVisibilityForEllipsize( const Internal::TextView::LayoutParameters& layoutParameters,
 379                                       TextViewProcessor::CharacterLayoutInfo& characterLayoutInfo,
 380                                       EllipsizeParameters& ellipsizeParameters,
 381                                       TextView::RelayoutData& relayoutData );
 382
 383 /**
 384  * Creates the actors needed for the ellipsized text.
 385  *
 386  * @param[in,out] ellipsizeParameters Temporary ellipsize parameters.
 387  * @param[in,out] relayoutData The text-view's data structures.
 388  */
 389 void CreateEllipsizeTextActor( const EllipsizeParameters& ellipsizeParameters,
 390                                TextView::RelayoutData& relayoutData );
 391
 392 /**
 393  *
 394  */
 395 void EllipsizeLine( const TextView::LayoutParameters& layoutParameters,
 396                     EllipsizeParameters& ellipsizeParameters,
 397                     TextView::RelayoutData& relayoutData );
 398
 399 /**
 400  * Traverse all text data structure setting its visibility to true.
 401  *
 402  * @param[in,out] relayoutData The text-view's data structures.
 403  */
 404 void SetTextVisible( TextView::RelayoutData& relayoutData );
 405
 406 /**
 407  * Calculates the visibility and fade parameters.
 408  *
 409  * @param[in] layoutParameters The layout parameters.
 410  * @param[in] visualParameters Some visual parameters (fade, sort modifier and blending).
 411  * @param[in,out] relayoutData The text-view's data structures.
 412  */
 413 void UpdateVisibilityForFade( const TextView::LayoutParameters& layoutParameters,
 414                               const TextView::VisualParameters& visualParameters,
 415                               TextView::RelayoutData& relayoutData );
 416 /**
 417  * Calculates the visibility for text ellipsize.
 418  *
 419  * @param[in] layoutParameters The layout parameters.
 420  * @param[in] visualParameters Some visual parameters (fade, sort modifier and blending).
 421  * @param[in,out] relayoutData The text-view's data structures.
 422  */
 423 void UpdateVisibilityForEllipsize( const TextView::LayoutParameters& layoutParameters,
 424                                    const TextView::VisualParameters& visualParameters,
 425                                    TextView::RelayoutData& relayoutData );
 426 /**
 427  * Calculates the visibility and fade parameters.
 428  *
 429  * @param[in] layoutParameters The layout parameters.
 430  * @param[in] visualParameters Some visual parameters (fade, sort modifier and blending).
 431  * @param[in,out] relayoutData The text-view's data structures.
 432  */
 433 void UpdateVisibility( const TextView::LayoutParameters& layoutParameters,
 434                        const TextView::VisualParameters& visualParameters,
 435                        TextView::RelayoutData& relayoutData );
 436
 437 /**
 438  * Traverse all text updating text-actor handles with new size, position, ...
 439  *
 440  * @param[in] visualParameters Some visual parameters (fade, sort modifier and blending).
 441  * @param[in,out] relayoutData Natural size (metrics), layout, text-actor info.
 442  */
 443 void UpdateTextActorInfo( const TextView::VisualParameters& visualParameters,
 444                           TextView::RelayoutData& relayoutData );
 445
 446 /**
 447  * Traverses the whole text and for each piece of underlined text,
 448  * it calculates the maximum thickness and the position of that particular piece of underlined text.
 449  *
 450  * @param[in,out] relayoutData Natural size (metrics), layout, text-actor info and conversion from visual to logical order and vice versa (for RTL text).
 451  */
 452 void CalculateUnderlineInfo( TextView::RelayoutData& relayoutData );
 453
 454 /**
 455  * Traverses the whole text and for each piece of underlined text,
 456  * it sets the previously calculated maximum thickness and the position of that particular piece of underlined text.
 457  *
 458  * @param[in,out] relayoutData Natural size (metrics), layout, text-actor info and conversion from visual to logical order and vice versa (for RTL text).
 459  */
 460 void SetUnderlineInfo( TextView::RelayoutData& relayoutData );
 461
 462 /**
 463  * Remove renderable-actor from the text-view.
 464  *
 465  * @param[in,out] textView The text-view.
 466  * @param[in] glyphActors renderable-actors to be removed from the text-view.
 467  */
 468 void RemoveGlyphActors( Actor textView,
 469                         const std::vector<RenderableActor>& glyphActors );
 470
 471 /**
 472  * Inserts the text-actors into the text-view and/or the text-actor's list.
 473  *
 474  * @param[in] relayoutOperationMask Whether the text-actors should be added into the text-view, the list of text-actors or in both.
 475  * @param[in,out] textView The text-view.
 476  * @param[in,out] relayoutData The text-view's data structures.
 477  */
 478 void InsertToTextView( TextView::RelayoutOperationMask relayoutOperationMask,
 479                        Actor textView,
 480                        TextView::RelayoutData& relayoutData );
 481
 482 /**
 483  * Retrieves a new glyph-actor from the cache of text-actors or creating a new one if it's empty.
 484  *
 485  * @param[in] text The text-actor's text.
 486  * @param[in] style The text-actor's style.
 487  * @param[in] cache The cache of text-actors.
 488  *
 489  * @return a RenderableActor with the text's glyph.
 490  */
 491 RenderableActor CreateGlyphActor( const Text& text, const TextStyle& style, TextActorCache& cache );
 492
 493 } // namespace TextViewRelayout
 494
 495 } // namespace Internal
 496
 497 } // namespace Toolkit
 498
 499 } // namespace Dali
 500
 501 #endif // __DALI_TOOLKIT_INTERNAL_RELAYOUT_UTILITIES_H__