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