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