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