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