dali-toolkit/internal/text/visual-model-impl.h

   1 #ifndef DALI_TOOLKIT_TEXT_VISUAL_MODEL_IMPL_H
   2 #define DALI_TOOLKIT_TEXT_VISUAL_MODEL_IMPL_H
   3
   4 /*
   5  * Copyright (c) 2021 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 // EXTERNAL INCLUDES
  22 #include <dali/public-api/common/dali-vector.h>
  23 #include <dali/public-api/common/intrusive-ptr.h>
  24 #include <dali/public-api/math/vector2.h>
  25 #include <dali/public-api/math/vector4.h>
  26 #include <dali/public-api/object/ref-object.h>
  27
  28 // INTERNAL INCLUDES
  29 #include <dali-toolkit/internal/text/color-run.h>
  30 #include <dali-toolkit/internal/text/line-run.h>
  31
  32 // DEVEL INCLUDES
  33 #include <dali-toolkit/devel-api/text/text-enumerations-devel.h>
  34
  35 namespace Dali
  36 {
  37 namespace Toolkit
  38 {
  39 namespace Text
  40 {
  41 struct HyphenInfo
  42 {
  43   Vector<GlyphInfo> glyph;
  44   Vector<Vector2>   position;
  45   Vector<Length>    index;
  46 };
  47
  48 class VisualModel;
  49 typedef IntrusivePtr<VisualModel> VisualModelPtr;
  50
  51 /**
  52  * @brief A visual text model contains layout specific information.
  53  *
  54  * This includes:
  55  * - A series of glyphs in visual order i.e. after the bidirectional reordering.
  56  * - The position of each glyph within a 2D bounding box.
  57  */
  58 class VisualModel : public RefObject
  59 {
  60 public:
  61   /**
  62    * @brief Create a new instance of a VisualModel.
  63    *
  64    * @return A pointer to a new VisualModel.
  65    */
  66   static VisualModelPtr New();
  67
  68   // Glyph interface.
  69
  70   /**
  71    * @brief Creates the character to glyph conversion table.
  72    *
  73    * @pre The glyphs per character table needs to be created first.
  74    *
  75    * @param[in] startIndex The character from where the conversion table is created.
  76    * @param[in] startGlyphIndex The glyph from where the conversion table is created.
  77    * @param[in] numberOfCharacters The number of characters.
  78    */
  79   void CreateCharacterToGlyphTable(CharacterIndex startIndex,
  80                                    GlyphIndex     startGlyphIndex,
  81                                    Length         numberOfCharacters);
  82
  83   /**
  84    * @brief Creates an array containing the number of glyphs per character.
  85    *
  86    * @param[in] startIndex The character from where the table is created.
  87    * @param[in] startGlyphIndex The glyph from where the conversion table is created.
  88    * @param[in] numberOfCharacters The number of characters.
  89    */
  90   void CreateGlyphsPerCharacterTable(CharacterIndex startIndex,
  91                                      GlyphIndex     startGlyphIndex,
  92                                      Length         numberOfCharacters);
  93
  94   /**
  95    * @brief Retrieves glyphs in the given buffer.
  96    *
  97    * The size of the @p glyphs buffer needs to be big enough to copy the @p numberOfGlyphs.
  98    * @param[out] glyphs Pointer to a buffer where the glyphs are copied.
  99    * @param[in] glyphIndex Index to the first glyph.
 100    * @param[in] numberOfGlyphs Number of glyphs to be copied.
 101    */
 102   void GetGlyphs(GlyphInfo* glyphs,
 103                  GlyphIndex glyphIndex,
 104                  Length     numberOfGlyphs) const;
 105
 106   // Position interface
 107
 108   /**
 109    * @brief Retrieves the glyph positions.
 110    *
 111    * @pre The size of the @p positions buffer needs to be big enough to copy the @p numberOfGlyphs positions.
 112    * @param[out] glyphPositions Pointer to a buffer where the glyph positions are copied.
 113    * @param[in] glyphIndex Index to the first glyph position.
 114    * @param[in] numberOfGlyphs The number of positions to be copied.
 115    */
 116   void GetGlyphPositions(Vector2*   glyphPositions,
 117                          GlyphIndex glyphIndex,
 118                          Length     numberOfGlyphs) const;
 119
 120   // Line interface.
 121
 122   /**
 123    * @brief Retrieves the total number of lines.
 124    *
 125    * @return The number of lines.
 126    */
 127   Length GetTotalNumberOfLines() const;
 128
 129   /**
 130    * @brief Retrieves the number of lines and the index to the first line where the given range of glyphs is laid out.
 131    *
 132    * @param[in] glyphIndex Index to the first glyph.
 133    * @param[in] numberOfGlyphs The number of glyph.
 134    * @param[out] firstLine Index to the line containing the glyph index.
 135    * @param[out] numberOfLines The number of lines.
 136    */
 137   void GetNumberOfLines(GlyphIndex glyphIndex,
 138                         Length     numberOfGlyphs,
 139                         LineIndex& firstLine,
 140                         Length&    numberOfLines) const;
 141
 142   /**
 143    * @brief Retrieves the lines where the given range of glyphs is laid out.
 144    *
 145    * The size of the @p lines buffer needs to be big enough to copy the @p numberOfLines.
 146    *
 147    * @param[out] lines Pointer to a buffer where the lines are copied.
 148    * @param[in] glyphIndex Index to the first glyphs of the range.
 149    * @param[in] numberOfGlyphs Number of glyphs in the range.
 150    */
 151   void GetLinesOfGlyphRange(LineRun*   lines,
 152                             GlyphIndex glyphIndex,
 153                             Length     numberOfGlyphs) const;
 154
 155   /**
 156    * @brief Retrieves the line index where the character is laid-out.
 157    *
 158    * @param[in] characterIndex The character's index.
 159    *
 160    * @return The line index.
 161    */
 162   LineIndex GetLineOfCharacter(CharacterIndex characterIndex);
 163
 164   // Underline runs
 165
 166   /**
 167    * @brief Retrieves the underline runs.
 168    *
 169    * @param[out] underlineRuns Pointer to a buffer where the underline runs are copied.
 170    * @param[in] index Index of the first underline run to be copied.
 171    * @param[in] numberOfRuns Number of underline runs to be copied.
 172    */
 173   void GetUnderlineRuns(GlyphRun*         underlineRuns,
 174                         UnderlineRunIndex index,
 175                         Length            numberOfRuns) const;
 176
 177   // Size interface
 178
 179   /**
 180    * @brief Sets the natural size.
 181    *
 182    * @param[in] size The text's natural size.
 183    */
 184   void SetNaturalSize(const Vector2& size);
 185
 186   /**
 187    * @brief Retrieves the natural size.
 188    *
 189    * @return The text's natural size.
 190    */
 191   const Vector2& GetNaturalSize() const;
 192
 193   /**
 194    * @brief Sets the text's layout size.
 195    *
 196    * @param[in] size The text's size.
 197    */
 198   void SetLayoutSize(const Vector2& size);
 199
 200   /**
 201    * @brief Retrieves the text's layout size.
 202    *
 203    * @return The text's size.
 204    */
 205   const Vector2& GetLayoutSize() const;
 206
 207   /**
 208    * @brief Set the text's color
 209    *
 210    * @param[in] textColor The text's color
 211    */
 212   void SetTextColor(const Vector4& textColor);
 213
 214   /**
 215    * @brief Retrieve the text's color
 216    *
 217    * @return The text's color
 218    */
 219   const Vector4& GetTextColor() const;
 220
 221   /**
 222    * @brief Sets the text's shadow offset.
 223    *
 224    * @param[in] shadowOffset The shadow offset, 0,0 indicates no shadow.
 225    */
 226   void SetShadowOffset(const Vector2& shadowOffset);
 227
 228   /**
 229    * @brief Retrieves the text's shadow offset.
 230    *
 231    * @return The text's shadow offset, 0,0 indicates no shadow.
 232    */
 233   const Vector2& GetShadowOffset() const;
 234
 235   /**
 236    * @brief Sets the text's shadow color.
 237    *
 238    * @param[in] shadowColor The shadow color.
 239    */
 240   void SetShadowColor(const Vector4& shadowColor);
 241
 242   /**
 243    * @brief Retrieves the text's shadow color.
 244    *
 245    * @return The text's shadow color.
 246    */
 247   const Vector4& GetShadowColor() const;
 248
 249   /**
 250    * @brief Set the shadow blur radius.
 251    *
 252    * @param[in] shadowBlurRadius The shadow blur radius, 0,0 indicates no blur.
 253    */
 254   void SetShadowBlurRadius(const float& shadowBlurRadius);
 255
 256   /**
 257    * @brief Retrieve the shadow blur radius.
 258    *
 259    * @return The shadow blur radius.
 260    */
 261   const float& GetShadowBlurRadius() const;
 262
 263   /**
 264    * @brief Sets the text's underline color.
 265    *
 266    * @param[in] color The text's underline color.
 267    */
 268   void SetUnderlineColor(const Vector4& color);
 269
 270   /**
 271    * @brief Retrieves the text's underline color.
 272    *
 273    * @return The text's underline color.
 274    */
 275   const Vector4& GetUnderlineColor() const;
 276
 277   /**
 278    * @brief Sets the text underline flag.
 279    *
 280    * @param[in] enabled true if underlined.
 281    */
 282   void SetUnderlineEnabled(bool enabled);
 283
 284   /**
 285    * @brief Returns whether the text is underlined or not.
 286    *
 287    * @return underline state.
 288    */
 289   bool IsUnderlineEnabled() const;
 290
 291   /**
 292    * @brief Clear the caches.
 293    */
 294   void ClearCaches();
 295
 296   /**
 297    * @brief Set the override used for underline height, 0 indicates height will be come from font metrics
 298    *
 299    * @param[in] height The height in pixels of the underline
 300    */
 301   void SetUnderlineHeight(float height);
 302
 303   /**
 304    * @brief Retrieves the underline height override
 305    *
 306    * @return Returns the override height for an underline, 0 indicates that font metrics will determine the height
 307    */
 308   float GetUnderlineHeight() const;
 309
 310   /**
 311    * @brief Retrieves the number of underline runs.
 312    *
 313    * @return The number of underline runs.
 314    */
 315   Length GetNumberOfUnderlineRuns() const;
 316
 317   /**
 318    * @brief Set the outline color.
 319    *
 320    * @param[in] color color of outline.
 321    */
 322   void SetOutlineColor(const Vector4& color);
 323
 324   /**
 325    * @brief Retrieve the outline color.
 326    *
 327    * @return The outline color.
 328    */
 329   const Vector4& GetOutlineColor() const;
 330
 331   /**
 332    * @brief Set the outline width
 333    *
 334    * @param[in] width The width in pixels of the outline, 0 indicates no outline
 335    */
 336   void SetOutlineWidth(uint16_t width);
 337
 338   /**
 339    * @brief Retrieves the width of an outline
 340    *
 341    * @return The width of the outline.
 342    */
 343   uint16_t GetOutlineWidth() const;
 344
 345   /**
 346    * @brief Sets the text's background color.
 347    *
 348    * @param[in] color The text's background color.
 349    */
 350   void SetBackgroundColor(const Vector4& color);
 351
 352   /**
 353    * @brief Retrieves the text's background color.
 354    *
 355    * @return The text's background color.
 356    */
 357   const Vector4& GetBackgroundColor() const;
 358
 359   /**
 360    * @brief Sets whether the text has a background or not.
 361    *
 362    * @param[in] enabled true if the text has a background.
 363    */
 364   void SetBackgroundEnabled(bool enabled);
 365
 366   /**
 367    * @brief Returns whether the text has a background or not.
 368    *
 369    * @return whether the text has a background or not.
 370    */
 371   bool IsBackgroundEnabled() const;
 372
 373   /**
 374    * @brief Sets whether the text has a markup-processor or not.
 375    *
 376    * @param[in] enabled true if the text has a markup-processor.
 377    */
 378   void SetMarkupProcessorEnabled(bool enabled);
 379
 380   /**
 381    * @brief Returns whether the text has a markup-processor or not.
 382    *
 383    * @return whether the text has a markup-processor or not.
 384    */
 385   bool IsMarkupProcessorEnabled() const;
 386
 387   /**
 388    * @brief Sets ellipsis position
 389    * @param[in] ellipsisPosition The ellipsis position for the text
 390    */
 391   void SetEllipsisPosition(Toolkit::DevelText::EllipsisPosition::Type ellipsisPosition);
 392
 393   /**
 394    * @brief Retrieves ellipsis position for text.
 395    *
 396    * @return The ellipsis position.
 397    */
 398   Toolkit::DevelText::EllipsisPosition::Type GetEllipsisPosition() const;
 399
 400   /**
 401    * @brief Enable or disable the text elide.
 402    *
 403    * @param[in] enabled Whether to enable the text elide.
 404    */
 405   void SetTextElideEnabled(bool enabled);
 406
 407   /**
 408    * @brief Whether the text elide property is enabled.
 409    *
 410    * @return @e true if the text elide property is enabled, @e false otherwise.
 411    */
 412   bool IsTextElideEnabled() const;
 413
 414   /**
 415    * @brief Sets the start index of laid-out glyphs.
 416    *
 417    * @param[in] startIndexOfElidedGlyphs The start index of laid-out glyphs.
 418    */
 419   void SetStartIndexOfElidedGlyphs(GlyphIndex startIndexOfElidedGlyphs);
 420
 421   /**
 422    * @brief Sets the end index of elided glyphs.
 423    *
 424    * @param[in] endIndexOfElidedGlyphs The end index of elided glyphs.
 425    */
 426   void SetEndIndexOfElidedGlyphs(GlyphIndex endIndexOfElidedGlyphs);
 427
 428   /**
 429    * @brief Sets the first middle index of elided glyphs, index before ellipsis of middle.
 430    *
 431    * @param[in] firstMiddleIndexOfElidedGlyphs The first middle index of elided glyphs, index before ellipsis of middle.
 432    */
 433   void SetFirstMiddleIndexOfElidedGlyphs(GlyphIndex firstMiddleIndexOfElidedGlyphs);
 434
 435   /**
 436    * @brief Sets the second middle index of elided glyphs, index of ellipsis of middle.
 437    *
 438    * @param[in] secondMiddleIndexOfElidedGlyphs The second middle index of elided glyphs, index of ellipsis of middle.
 439    */
 440   void SetSecondMiddleIndexOfElidedGlyphs(GlyphIndex secondMiddleIndexOfElidedGlyphs);
 441
 442   /**
 443    * @brief Retrieves the start index of laid-out glyphs.
 444    *
 445    * @return The start index of laid-out glyphs.
 446    */
 447   GlyphIndex GetStartIndexOfElidedGlyphs() const;
 448
 449   /**
 450    * @brief Retrieves the end index of laid-out glyphs.
 451    *
 452    * @return The end index of laid-out glyphs.
 453    */
 454   GlyphIndex GetEndIndexOfElidedGlyphs() const;
 455
 456   /**
 457    * @brief Retrieves the first middle index of elided glyphs, index before ellipsis of middle.
 458    *
 459    * @return The first middle index of elided glyphs, index before ellipsis of middle.
 460    */
 461   GlyphIndex GetFirstMiddleIndexOfElidedGlyphs() const;
 462
 463   /**
 464    * @brief Retrieves the second middle index of elided glyphs, index of ellipsis of middle.
 465    *
 466    * @return The second middle index of elided glyphs, index of ellipsis of middle.
 467    */
 468   GlyphIndex GetSecondMiddleIndexOfElidedGlyphs() const;
 469
 470   /**
 471    * @brief Sets the text's strikethrough color.
 472    *
 473    * @param[in] color The text's strikethrough color.
 474    */
 475   void SetStrikethroughColor(const Vector4& color);
 476
 477   /**
 478    * @brief Retrieves the text's strikethrough color.
 479    *
 480    * @return The text's strikethrough color.
 481    */
 482   const Vector4& GetStrikethroughColor() const;
 483
 484   /**
 485    * @brief Sets the text strikethrough flag.
 486    *
 487    * @param[in] enabled true if strikethrough.
 488    */
 489   void SetStrikethroughEnabled(bool enabled);
 490
 491   /**
 492    * @brief Returns whether the text is strikethrough or not.
 493    *
 494    * @return strikethrough state.
 495    */
 496   bool IsStrikethroughEnabled() const;
 497
 498   /**
 499    * @brief Set the override used for strikethrough height, 0 indicates height will be come from font metrics
 500    *
 501    * @param[in] height The height in pixels of the strikethrough
 502    */
 503   void SetStrikethroughHeight(float height);
 504
 505   /**
 506    * @brief Retrieves the strikethrough height override
 507    *
 508    * @return Returns the override height for a strikethrough, 0 indicates that font metrics will determine the height
 509    */
 510   float GetStrikethroughHeight() const;
 511
 512 protected:
 513   /**
 514    * @brief A reference counted object may only be deleted by calling Unreference().
 515    */
 516   virtual ~VisualModel();
 517
 518 private:
 519   /**
 520    * @brief Private constructor.
 521    */
 522   VisualModel();
 523
 524   // Undefined
 525   VisualModel(const VisualModel& handle);
 526
 527   // Undefined
 528   VisualModel& operator=(const VisualModel& handle);
 529
 530 public:
 531   Vector<GlyphInfo>      mGlyphs;                 ///< For each glyph, the font's id, glyph's index within the font and glyph's metrics.
 532   Vector<CharacterIndex> mGlyphsToCharacters;     ///< For each glyph, the index of the first character.
 533   Vector<GlyphIndex>     mCharactersToGlyph;      ///< For each character, the index of the first glyph.
 534   Vector<Length>         mCharactersPerGlyph;     ///< For each glyph, the number of characters that form the glyph.
 535   Vector<Length>         mGlyphsPerCharacter;     ///< For each character, the number of glyphs that are shaped.
 536   Vector<Vector2>        mGlyphPositions;         ///< For each glyph, the position.
 537   Vector<LineRun>        mLines;                  ///< The laid out lines.
 538   Vector<GlyphRun>       mUnderlineRuns;          ///< Runs of glyphs that are underlined.
 539   Vector<Vector4>        mColors;                 ///< Colors of the glyphs.
 540   Vector<ColorIndex>     mColorIndices;           ///< Indices to the vector of colors for each glyphs.
 541   Vector<Vector4>        mBackgroundColors;       ///< Background colors of the glyphs.
 542   Vector<ColorIndex>     mBackgroundColorIndices; ///< Indices to the vector of background colors for each glyphs.
 543
 544   Vector4  mTextColor;           ///< The text color
 545   Vector4  mShadowColor;         ///< Color of drop shadow
 546   Vector4  mUnderlineColor;      ///< Color of underline
 547   Vector4  mOutlineColor;        ///< Color of outline
 548   Vector4  mBackgroundColor;     ///< Color of text background
 549   Vector4  mStrikethroughColor;  ///< Color of text background
 550   Size     mControlSize;         ///< The size of the UI control.
 551   Vector2  mShadowOffset;        ///< Offset for drop shadow, 0 indicates no shadow
 552   float    mUnderlineHeight;     ///< Fixed height for underline to override font metrics.
 553   float    mStrikethroughHeight; ///< Fixed height for strikethrough to override font metrics.
 554   float    mShadowBlurRadius;    ///< Blur radius of shadow, 0 indicates no blur.
 555   uint16_t mOutlineWidth;        ///< Width of outline.
 556
 557 private:
 558   Size mNaturalSize; ///< Size of the text with no line wrapping.
 559   Size mLayoutSize;  ///< Size of the laid-out text considering the layout properties set.
 560
 561   // Caches to increase performance in some consecutive operations.
 562   LineIndex mCachedLineIndex; ///< Used to increase performance in consecutive calls to GetLineOfGlyph() or GetLineOfCharacter() with consecutive glyphs or characters.
 563
 564   DevelText::EllipsisPosition::Type mEllipsisPosition;                ///< Where is the location the text elide
 565   GlyphIndex                        mStartIndexOfElidedGlyphs;        ///< The start index of elided glyphs.
 566   GlyphIndex                        mEndIndexOfElidedGlyphs;          ///< The end index of elided glyphs.
 567   GlyphIndex                        mFirstMiddleIndexOfElidedGlyphs;  ///< The first end index of elided glyphs, index before ellipsis of middle.
 568   GlyphIndex                        mSecondMiddleIndexOfElidedGlyphs; ///< The first end index of elided glyphs, index of ellipsis of middle.
 569   bool                              mTextElideEnabled : 1;            ///< Whether the text's elide is enabled.
 570
 571 public:
 572   bool       mUnderlineEnabled : 1;       ///< Underline enabled flag
 573   bool       mUnderlineColorSet : 1;      ///< Has the underline color been explicitly set?
 574   bool       mBackgroundEnabled : 1;      ///< Background enabled flag
 575   bool       mMarkupProcessorEnabled : 1; ///< Markup-processor enabled flag
 576   HyphenInfo mHyphen;                     ///< Contains hyphen glyph info & the character index to draw hyphen after.
 577   bool       mStrikethroughEnabled : 1;   ///< Strikethrough enabled flag
 578 };
 579
 580 } // namespace Text
 581
 582 } // namespace Toolkit
 583
 584 } // namespace Dali
 585
 586 #endif // DALI_TOOLKIT_TEXT_VISUAL_MODEL_IMPL_H