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 namespace Dali
  33 {
  34 namespace Toolkit
  35 {
  36 namespace Text
  37 {
  38 struct HyphenInfo
  39 {
  40   Vector<GlyphInfo> glyph;
  41   Vector<Vector2>   position;
  42   Vector<Length>    index;
  43 };
  44
  45 class VisualModel;
  46 typedef IntrusivePtr<VisualModel> VisualModelPtr;
  47
  48 /**
  49  * @brief A visual text model contains layout specific information.
  50  *
  51  * This includes:
  52  * - A series of glyphs in visual order i.e. after the bidirectional reordering.
  53  * - The position of each glyph within a 2D bounding box.
  54  */
  55 class VisualModel : public RefObject
  56 {
  57 public:
  58   /**
  59    * @brief Create a new instance of a VisualModel.
  60    *
  61    * @return A pointer to a new VisualModel.
  62    */
  63   static VisualModelPtr New();
  64
  65   // Glyph interface.
  66
  67   /**
  68    * @brief Creates the character to glyph conversion table.
  69    *
  70    * @pre The glyphs per character table needs to be created first.
  71    *
  72    * @param[in] startIndex The character from where the conversion table is created.
  73    * @param[in] startGlyphIndex The glyph from where the conversion table is created.
  74    * @param[in] numberOfCharacters The number of characters.
  75    */
  76   void CreateCharacterToGlyphTable(CharacterIndex startIndex,
  77                                    GlyphIndex     startGlyphIndex,
  78                                    Length         numberOfCharacters);
  79
  80   /**
  81    * @brief Creates an array containing the number of glyphs per character.
  82    *
  83    * @param[in] startIndex The character from where the table is created.
  84    * @param[in] startGlyphIndex The glyph from where the conversion table is created.
  85    * @param[in] numberOfCharacters The number of characters.
  86    */
  87   void CreateGlyphsPerCharacterTable(CharacterIndex startIndex,
  88                                      GlyphIndex     startGlyphIndex,
  89                                      Length         numberOfCharacters);
  90
  91   /**
  92    * @brief Retrieves glyphs in the given buffer.
  93    *
  94    * The size of the @p glyphs buffer needs to be big enough to copy the @p numberOfGlyphs.
  95    * @param[out] glyphs Pointer to a buffer where the glyphs are copied.
  96    * @param[in] glyphIndex Index to the first glyph.
  97    * @param[in] numberOfGlyphs Number of glyphs to be copied.
  98    */
  99   void GetGlyphs(GlyphInfo* glyphs,
 100                  GlyphIndex glyphIndex,
 101                  Length     numberOfGlyphs) const;
 102
 103   // Position interface
 104
 105   /**
 106    * @brief Retrieves the glyph positions.
 107    *
 108    * @pre The size of the @p positions buffer needs to be big enough to copy the @p numberOfGlyphs positions.
 109    * @param[out] glyphPositions Pointer to a buffer where the glyph positions are copied.
 110    * @param[in] glyphIndex Index to the first glyph position.
 111    * @param[in] numberOfGlyphs The number of positions to be copied.
 112    */
 113   void GetGlyphPositions(Vector2*   glyphPositions,
 114                          GlyphIndex glyphIndex,
 115                          Length     numberOfGlyphs) const;
 116
 117   // Line interface.
 118
 119   /**
 120    * @brief Retrieves the number of lines and the index to the first line where the given range of glyphs is laid out.
 121    *
 122    * @param[in] glyphIndex Index to the first glyph.
 123    * @param[in] numberOfGlyphs The number of glyph.
 124    * @param[out] firstLine Index to the line containing the glyph index.
 125    * @param[out] numberOfLines The number of lines.
 126    */
 127   void GetNumberOfLines(GlyphIndex glyphIndex,
 128                         Length     numberOfGlyphs,
 129                         LineIndex& firstLine,
 130                         Length&    numberOfLines) const;
 131
 132   /**
 133    * @brief Retrieves the lines where the given range of glyphs is laid out.
 134    *
 135    * The size of the @p lines buffer needs to be big enough to copy the @p numberOfLines.
 136    *
 137    * @param[out] lines Pointer to a buffer where the lines are copied.
 138    * @param[in] glyphIndex Index to the first glyphs of the range.
 139    * @param[in] numberOfGlyphs Number of glyphs in the range.
 140    */
 141   void GetLinesOfGlyphRange(LineRun*   lines,
 142                             GlyphIndex glyphIndex,
 143                             Length     numberOfGlyphs) const;
 144
 145   /**
 146    * @brief Retrieves the line index where the character is laid-out.
 147    *
 148    * @param[in] characterIndex The character's index.
 149    *
 150    * @return The line index.
 151    */
 152   LineIndex GetLineOfCharacter(CharacterIndex characterIndex);
 153
 154   // Underline runs
 155
 156   /**
 157    * @brief Retrieves the underline runs.
 158    *
 159    * @param[out] underlineRuns Pointer to a buffer where the underline runs are copied.
 160    * @param[in] index Index of the first underline run to be copied.
 161    * @param[in] numberOfRuns Number of underline runs to be copied.
 162    */
 163   void GetUnderlineRuns(GlyphRun*         underlineRuns,
 164                         UnderlineRunIndex index,
 165                         Length            numberOfRuns) const;
 166
 167   // Size interface
 168
 169   /**
 170    * @brief Sets the natural size.
 171    *
 172    * @param[in] size The text's natural size.
 173    */
 174   void SetNaturalSize(const Vector2& size);
 175
 176   /**
 177    * @brief Retrieves the natural size.
 178    *
 179    * @return The text's natural size.
 180    */
 181   const Vector2& GetNaturalSize() const;
 182
 183   /**
 184    * @brief Sets the text's layout size.
 185    *
 186    * @param[in] size The text's size.
 187    */
 188   void SetLayoutSize(const Vector2& size);
 189
 190   /**
 191    * @brief Retrieves the text's layout size.
 192    *
 193    * @return The text's size.
 194    */
 195   const Vector2& GetLayoutSize() const;
 196
 197   /**
 198    * @brief Set the text's color
 199    *
 200    * @param[in] textColor The text's color
 201    */
 202   void SetTextColor(const Vector4& textColor);
 203
 204   /**
 205    * @brief Retrieve the text's color
 206    *
 207    * @return The text's color
 208    */
 209   const Vector4& GetTextColor() const;
 210
 211   /**
 212    * @brief Sets the text's shadow offset.
 213    *
 214    * @param[in] shadowOffset The shadow offset, 0,0 indicates no shadow.
 215    */
 216   void SetShadowOffset(const Vector2& shadowOffset);
 217
 218   /**
 219    * @brief Retrieves the text's shadow offset.
 220    *
 221    * @return The text's shadow offset, 0,0 indicates no shadow.
 222    */
 223   const Vector2& GetShadowOffset() const;
 224
 225   /**
 226    * @brief Sets the text's shadow color.
 227    *
 228    * @param[in] shadowColor The shadow color.
 229    */
 230   void SetShadowColor(const Vector4& shadowColor);
 231
 232   /**
 233    * @brief Retrieves the text's shadow color.
 234    *
 235    * @return The text's shadow color.
 236    */
 237   const Vector4& GetShadowColor() const;
 238
 239   /**
 240    * @brief Set the shadow blur radius.
 241    *
 242    * @param[in] shadowBlurRadius The shadow blur radius, 0,0 indicates no blur.
 243    */
 244   void SetShadowBlurRadius(const float& shadowBlurRadius);
 245
 246   /**
 247    * @brief Retrieve the shadow blur radius.
 248    *
 249    * @return The shadow blur radius.
 250    */
 251   const float& GetShadowBlurRadius() const;
 252
 253   /**
 254    * @brief Sets the text's underline color.
 255    *
 256    * @param[in] color The text's underline color.
 257    */
 258   void SetUnderlineColor(const Vector4& color);
 259
 260   /**
 261    * @brief Retrieves the text's underline color.
 262    *
 263    * @return The text's underline color.
 264    */
 265   const Vector4& GetUnderlineColor() const;
 266
 267   /**
 268    * @brief Sets the text underline flag.
 269    *
 270    * @param[in] enabled true if underlined.
 271    */
 272   void SetUnderlineEnabled(bool enabled);
 273
 274   /**
 275    * @brief Returns whether the text is underlined or not.
 276    *
 277    * @return underline state.
 278    */
 279   bool IsUnderlineEnabled() const;
 280
 281   /**
 282    * @brief Clear the caches.
 283    */
 284   void ClearCaches();
 285
 286   /**
 287    * @brief Set the override used for underline height, 0 indicates height will be come from font metrics
 288    *
 289    * @param[in] height The height in pixels of the underline
 290    */
 291   void SetUnderlineHeight(float height);
 292
 293   /**
 294    * @brief Retrieves the underline height override
 295    *
 296    * @return Returns the override height for an underline, 0 indicates that font metrics will determine the height
 297    */
 298   float GetUnderlineHeight() const;
 299
 300   /**
 301    * @brief Retrieves the number of underline runs.
 302    *
 303    * @return The number of underline runs.
 304    */
 305   Length GetNumberOfUnderlineRuns() const;
 306
 307   /**
 308    * @brief Set the outline color.
 309    *
 310    * @param[in] color color of outline.
 311    */
 312   void SetOutlineColor(const Vector4& color);
 313
 314   /**
 315    * @brief Retrieve the outline color.
 316    *
 317    * @return The outline color.
 318    */
 319   const Vector4& GetOutlineColor() const;
 320
 321   /**
 322    * @brief Set the outline width
 323    *
 324    * @param[in] width The width in pixels of the outline, 0 indicates no outline
 325    */
 326   void SetOutlineWidth(uint16_t width);
 327
 328   /**
 329    * @brief Retrieves the width of an outline
 330    *
 331    * @return The width of the outline.
 332    */
 333   uint16_t GetOutlineWidth() const;
 334
 335   /**
 336    * @brief Sets the text's background color.
 337    *
 338    * @param[in] color The text's background color.
 339    */
 340   void SetBackgroundColor(const Vector4& color);
 341
 342   /**
 343    * @brief Retrieves the text's background color.
 344    *
 345    * @return The text's background color.
 346    */
 347   const Vector4& GetBackgroundColor() const;
 348
 349   /**
 350    * @brief Sets whether the text has a background or not.
 351    *
 352    * @param[in] enabled true if the text has a background.
 353    */
 354   void SetBackgroundEnabled(bool enabled);
 355
 356   /**
 357    * @brief Returns whether the text has a background or not.
 358    *
 359    * @return whether the text has a background or not.
 360    */
 361   bool IsBackgroundEnabled() const;
 362
 363   /**
 364    * @brief Sets whether the text has a markup-processor or not.
 365    *
 366    * @param[in] enabled true if the text has a markup-processor.
 367    */
 368   void SetMarkupProcessorEnabled(bool enabled);
 369
 370   /**
 371    * @brief Returns whether the text has a markup-processor or not.
 372    *
 373    * @return whether the text has a markup-processor or not.
 374    */
 375   bool IsMarkupProcessorEnabled() const;
 376
 377 protected:
 378   /**
 379    * @brief A reference counted object may only be deleted by calling Unreference().
 380    */
 381   virtual ~VisualModel();
 382
 383 private:
 384   /**
 385    * @brief Private constructor.
 386    */
 387   VisualModel();
 388
 389   // Undefined
 390   VisualModel(const VisualModel& handle);
 391
 392   // Undefined
 393   VisualModel& operator=(const VisualModel& handle);
 394
 395 public:
 396   Vector<GlyphInfo>      mGlyphs;                 ///< For each glyph, the font's id, glyph's index within the font and glyph's metrics.
 397   Vector<CharacterIndex> mGlyphsToCharacters;     ///< For each glyph, the index of the first character.
 398   Vector<GlyphIndex>     mCharactersToGlyph;      ///< For each character, the index of the first glyph.
 399   Vector<Length>         mCharactersPerGlyph;     ///< For each glyph, the number of characters that form the glyph.
 400   Vector<Length>         mGlyphsPerCharacter;     ///< For each character, the number of glyphs that are shaped.
 401   Vector<Vector2>        mGlyphPositions;         ///< For each glyph, the position.
 402   Vector<LineRun>        mLines;                  ///< The laid out lines.
 403   Vector<GlyphRun>       mUnderlineRuns;          ///< Runs of glyphs that are underlined.
 404   Vector<Vector4>        mColors;                 ///< Colors of the glyphs.
 405   Vector<ColorIndex>     mColorIndices;           ///< Indices to the vector of colors for each glyphs.
 406   Vector<Vector4>        mBackgroundColors;       ///< Background colors of the glyphs.
 407   Vector<ColorIndex>     mBackgroundColorIndices; ///< Indices to the vector of background colors for each glyphs.
 408
 409   Vector4  mTextColor;        ///< The text color
 410   Vector4  mShadowColor;      ///< Color of drop shadow
 411   Vector4  mUnderlineColor;   ///< Color of underline
 412   Vector4  mOutlineColor;     ///< Color of outline
 413   Vector4  mBackgroundColor;  ///< Color of text background
 414   Size     mControlSize;      ///< The size of the UI control.
 415   Vector2  mShadowOffset;     ///< Offset for drop shadow, 0 indicates no shadow
 416   float    mUnderlineHeight;  ///< Fixed height for underline to override font metrics.
 417   float    mShadowBlurRadius; ///< Blur radius of shadow, 0 indicates no blur.
 418   uint16_t mOutlineWidth;     ///< Width of outline.
 419
 420 private:
 421   Size mNaturalSize; ///< Size of the text with no line wrapping.
 422   Size mLayoutSize;  ///< Size of the laid-out text considering the layout properties set.
 423
 424   // Caches to increase performance in some consecutive operations.
 425   LineIndex mCachedLineIndex; ///< Used to increase performance in consecutive calls to GetLineOfGlyph() or GetLineOfCharacter() with consecutive glyphs or characters.
 426
 427 public:
 428   bool mUnderlineEnabled : 1;  ///< Underline enabled flag
 429   bool mUnderlineColorSet : 1; ///< Has the underline color been explicitly set?
 430   bool mBackgroundEnabled : 1; ///< Background enabled flag
 431   bool mMarkupProcessorEnabled : 1; ///< Markup-processor enabled flag
 432   HyphenInfo mHyphen; ///< Contains hyphen glyph info & the character index to draw hyphen after.
 433 };
 434
 435 } // namespace Text
 436
 437 } // namespace Toolkit
 438
 439 } // namespace Dali
 440
 441 #endif // DALI_TOOLKIT_TEXT_VISUAL_MODEL_IMPL_H