dali-toolkit/devel-api/controls/text-controls/text-label-devel.h

   1 #ifndef DALI_TOOLKIT_TEXT_LABEL_DEVEL_H
   2 #define DALI_TOOLKIT_TEXT_LABEL_DEVEL_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/vector-wrapper.h>
  23
  24 // INTERNAL INCLUDES
  25 #include <dali-toolkit/public-api/controls/text-controls/text-label.h>
  26
  27 namespace Dali
  28 {
  29 namespace Toolkit
  30 {
  31 namespace DevelTextLabel
  32 {
  33 namespace Property
  34 {
  35 enum Type
  36 {
  37   TEXT                   = Dali::Toolkit::TextLabel::Property::TEXT,
  38   FONT_FAMILY            = Dali::Toolkit::TextLabel::Property::FONT_FAMILY,
  39   FONT_STYLE             = Dali::Toolkit::TextLabel::Property::FONT_STYLE,
  40   POINT_SIZE             = Dali::Toolkit::TextLabel::Property::POINT_SIZE,
  41   MULTI_LINE             = Dali::Toolkit::TextLabel::Property::MULTI_LINE,
  42   HORIZONTAL_ALIGNMENT   = Dali::Toolkit::TextLabel::Property::HORIZONTAL_ALIGNMENT,
  43   VERTICAL_ALIGNMENT     = Dali::Toolkit::TextLabel::Property::VERTICAL_ALIGNMENT,
  44   ENABLE_MARKUP          = Dali::Toolkit::TextLabel::Property::ENABLE_MARKUP,
  45   ENABLE_AUTO_SCROLL     = Dali::Toolkit::TextLabel::Property::ENABLE_AUTO_SCROLL,
  46   AUTO_SCROLL_SPEED      = Dali::Toolkit::TextLabel::Property::AUTO_SCROLL_SPEED,
  47   AUTO_SCROLL_LOOP_COUNT = Dali::Toolkit::TextLabel::Property::AUTO_SCROLL_LOOP_COUNT,
  48   AUTO_SCROLL_GAP        = Dali::Toolkit::TextLabel::Property::AUTO_SCROLL_GAP,
  49   LINE_SPACING           = Dali::Toolkit::TextLabel::Property::LINE_SPACING,
  50   UNDERLINE              = Dali::Toolkit::TextLabel::Property::UNDERLINE,
  51   SHADOW                 = Dali::Toolkit::TextLabel::Property::SHADOW,
  52   EMBOSS                 = Dali::Toolkit::TextLabel::Property::EMBOSS,
  53   OUTLINE                = Dali::Toolkit::TextLabel::Property::OUTLINE,
  54   PIXEL_SIZE             = Dali::Toolkit::TextLabel::Property::PIXEL_SIZE,
  55   ELLIPSIS               = Dali::Toolkit::TextLabel::Property::ELLIPSIS,
  56   AUTO_SCROLL_LOOP_DELAY = Dali::Toolkit::TextLabel::Property::AUTO_SCROLL_LOOP_DELAY,
  57   AUTO_SCROLL_STOP_MODE  = Dali::Toolkit::TextLabel::Property::AUTO_SCROLL_STOP_MODE,
  58   LINE_COUNT             = Dali::Toolkit::TextLabel::Property::LINE_COUNT,
  59   LINE_WRAP_MODE         = Dali::Toolkit::TextLabel::Property::LINE_WRAP_MODE,
  60
  61   /**
  62      * @brief The direction of the layout.
  63      * @details Name "textDirection", type [Type](@ref Dali::Toolkit::DevelText::TextDirection::Type) (Property::INTEGER), Read/Write
  64      * @note The text direction can be changed only by replacing the text itself.
  65      * @see TextDirection::Type for supported values.
  66      */
  67   TEXT_DIRECTION,
  68
  69   /**
  70      * @brief Alignment of text within area of single line
  71      * @details Name "verticalLineAlignment", type [Type](@ref Dali::Toolkit::DevelText::VerticalLineAlignment::Type) (Property::INTEGER), Read/Write
  72      * @note The default value is TOP
  73      * @see VerticalLineAlignment::Type for supported values
  74      */
  75   VERTICAL_LINE_ALIGNMENT,
  76
  77   /**
  78      * @brief The default text background parameters.
  79      * @details Name "textBackground", type Property::MAP.
  80      * @note Use "textBackground" as property name to avoid conflict with Control's "background" property
  81      *
  82      * The background map contains the following keys:
  83      *
  84      * | %Property Name       | Type     | Required | Description                                                                                                        |
  85      * |----------------------|----------|----------|--------------------------------------------------------------------------------------------------------------------|
  86      * | enable               | BOOLEAN  | No       | True to enable the background or false to disable (the default value is false)                                     |
  87      * | color                | VECTOR4  | No       | The color of the background (the default value is Color::CYAN)                                                     |
  88      */
  89   BACKGROUND,
  90
  91   /**
  92      * @brief Ignore spaces after text.
  93      * @details Name "ignoreSpacesAfterText", type (Property::BOLEAN), Read/Write
  94      * @note The default value is true
  95      */
  96   IGNORE_SPACES_AFTER_TEXT,
  97
  98   /**
  99      * @brief Modifies the default text alignment to match the direction of the system language.
 100      * @details Name "matchSystemLanguageDirection", type (Property::BOLEAN), Read/Write
 101      * @note The default value is true
 102      *
 103      * If MATCH_SYSTEM_LANGUAGE_DIRECTION property set true, the default text alignment to match the direction of the system language.
 104      *
 105      * ex) Current system language direction LTR.
 106      *     TextLabel::New("Hello world \n  ﻡﺮﺤﺑﺍ. ");
 107      *     TextLabel::Property::HORIZONTAL_ALIGNMENT, "END"
 108      *
 109      * | TextLabel::Property::MATCH_SYSTEM_LANGUAGE_DIRECTION                 |
 110      * |-----------------------------------------------------------------------
 111      * |               false               |          true (default)          |
 112      * |-----------------------------------|----------------------------------|
 113      * |                     Hello world   |                  Hello world     |
 114      * |   ﻡﺮﺤﺑﺍ.                     |                          ﻡﺮﺤﺑﺍ.      |
 115      *
 116      */
 117   MATCH_SYSTEM_LANGUAGE_DIRECTION,
 118
 119   /**
 120      * @brief The text fit parameters.
 121      * @details Name "textFit", type Property::MAP.
 122      * @note The default value is false
 123      *
 124      * The textFit map contains the following keys:
 125      *
 126      * | %Property Name       | Type     | Required | Description                                                                                                        |
 127      * |----------------------|----------|----------|--------------------------------------------------------------------------------------------------------------------|
 128      * | enable               | BOOLEAN  | No       | True to enable the text fit or false to disable (the default value is false)                                     |
 129      * | minSize              | FLOAT    | No       | Minimum Size for text fit (the default value is 10.f)                                                     |
 130      * | maxSize              | FLOAT    | No       | Maximum Size for text fit (the default value is 100.f)                                                     |
 131      * | stepSize             | FLOAT    | No       | Step Size for font increase (the default value is 1.f)                                                     |
 132      * | fontSizeType         | STRING   | No       | The size type of font, You can choose between "pointSize" or "pixelSize". (the default value is "pointSize")                                                     |
 133      */
 134   TEXT_FIT,
 135
 136   /**
 137      * @brief Sets the height of the line in points.
 138      * @details Name "lineSize", type Property::FLOAT.
 139      * @note If the font size is larger than the line size, it works with the font size.
 140      */
 141   MIN_LINE_SIZE,
 142
 143   /**
 144      * @brief The type of rendering e.g. bitmap-based.
 145      * @details Name "renderingBackend", type Property::INT.
 146      */
 147   RENDERING_BACKEND,
 148
 149   /**
 150    * @brief The font size scale for scaling the specified font size up or down.
 151    * @details name "fontSizeScale", type Property::FLOAT.
 152    * @note The default value is 1.0 which does nothing.
 153    * The given font size scale value is used for multiplying the specified font size before querying fonts.
 154    *
 155    * e.g. The rendering results of both cases are same.
 156    *  - fontSize: 15pt, fontSizeScale: 1.0
 157    *  - fontSize: 10pt, fontSizeScale: 1.5
 158    */
 159   FONT_SIZE_SCALE,
 160
 161   /**
 162    * @brief True to enable the font size scale or false to disable.
 163    * @details Name "enableFontSizeScale", type Property::BOOLEAN.
 164    * @note The default value is true.
 165    * If false, font size scale is not apppied.
 166    */
 167   ENABLE_FONT_SIZE_SCALE,
 168
 169   /**
 170   * @brief The enumerations used to specify whether to position the ellipsis at the END, START or MIDDLE of the text.
 171   * @details Name "EllipsisPosition", type [Type](@ref Dali::Toolkit::DevelText::EllipsisPosition::Type) (Property::INTEGER), or Property::STRING. Read/Write
 172   * @note Default is EllipsisPosition::END.
 173   * @see DevelText::EllipsisPosition
 174   */
 175   ELLIPSIS_POSITION,
 176
 177   /**
 178    * @brief The default strikethrough parameters.
 179    * @details Name "strikethrough", type Property::MAP.
 180    *
 181    * The strikethrough map contains the following keys:
 182    *
 183    * | %Property Name       | Type     | Required | Description                                                                                                        |
 184    * |----------------------|----------|----------|--------------------------------------------------------------------------------------------------------------------|
 185    * | enable               | BOOLEAN  | No       | True to enable the strikethrough or false to disable (the default value is false)                                  |
 186    * | color                | VECTOR4  | No       | The color of the strikethrough (the default value is Color::BLACK)                                                 |
 187    * | height               | FLOAT    | No       | The height of the strikethrough (the default value is 0)                                                               |
 188    *
 189    */
 190   STRIKETHROUGH,
 191
 192   /**
 193   * @brief The spaces between characters in Pixels.
 194   * @details Name "characterSpacing", type Property::FLOAT.
 195   * @note
 196   *   A positive value will make the characters far apart (expanded) and a negative value will bring them closer (condensed).
 197   *   The default value is 0.f which does nothing.
 198   */
 199   CHARACTER_SPACING,
 200
 201   /**
 202    * @brief the relative height of the line (a factor that will be multiplied by text height).
 203    * @details Name "relativeLineSize", type Property::FLOAT.
 204    * @note If the value is less than 1, the lines could to be overlapped.
 205    */
 206   RELATIVE_LINE_SIZE,
 207
 208   /**
 209    * @brief The anchor color that will be used by default in markup processing.
 210    * @details Name "anchorColor", type Property::VECTOR4.
 211    * @note If there is a color attribute in the anchor tag, the markup attribute takes precedence.
 212    */
 213   ANCHOR_COLOR,
 214
 215   /**
 216    * @brief The anchor clicked color that will be used by default in markup processing.
 217    * @details Name "anchorClickedColor", type Property::VECTOR4.
 218    * @note If there is a color attribute in the anchor tag, the markup attribute takes precedence.
 219    */
 220   ANCHOR_CLICKED_COLOR,
 221
 222   /**
 223    * @brief Whether to trim the xBearing of first glyph of the text.
 224    * @details Name "removeFrontInset", type Property::BOOLEAN.
 225    */
 226   REMOVE_FRONT_INSET,
 227
 228   /**
 229    * @brief Whether to trim the advance of last glyph of the text.
 230    * @details Name "removeBackInset", type Property::BOOLEAN.
 231    */
 232   REMOVE_BACK_INSET,
 233 };
 234
 235 } // namespace Property
 236
 237 struct FitOption
 238 {
 239   FitOption(float pointSize = 0.0f, float minLineSize = 0.0f)
 240   : mPointSize(pointSize), mMinLineSize(minLineSize) {}
 241
 242   float GetPointSize() const
 243   {
 244     return mPointSize;
 245   }
 246   float GetMinLineSize() const
 247   {
 248     return mMinLineSize;
 249   }
 250   void SetPointSize(float pointSize)
 251   {
 252     mPointSize = pointSize;
 253   }
 254   void SetMinLineSize(float minLineSize)
 255   {
 256     mMinLineSize = minLineSize;
 257   }
 258
 259 private:
 260   float mPointSize   = 0.0f;
 261   float mMinLineSize = 0.0f;
 262 };
 263
 264 /**
 265  * @brief Get the rendered size of a specific text range.
 266  * if the requested text is at multilines, multiple sizes will be returned for each text located in a separate line.
 267  * if a line contains characters with different directions, multiple sizes will be returned for each block of contiguous characters with the same direction.
 268  *
 269  * @param[in] textLabel The instance of TextLabel.
 270  * @param[in] startIndex start index of the text requested to calculate size for.
 271  * @param[in] endIndex end index(included) of the text requested to calculate size for.
 272  * @return list of sizes of the reuested text.
 273  */
 274 DALI_TOOLKIT_API Vector<Vector2> GetTextSize(TextLabel textLabel, const uint32_t startIndex, const uint32_t endIndex);
 275
 276 /**
 277  * @brief Get the top/left rendered position of a specific text range.
 278  * if the requested text is at multilines, multiple positions will be returned for each text located in a separate line.
 279  * if a line contains characters with different directions, multiple positions will be returned for each block of contiguous characters with the same direction.
 280  *
 281  * @param[in] textLabel The instance of TextLabel.
 282  * @param[in] startIndex start index of the text requested to get position to.
 283  * @param[in] endIndex end index(included) of the text requested to get position to.
 284  * @return list of positions of the requested text.
 285  */
 286 DALI_TOOLKIT_API Vector<Vector2> GetTextPosition(TextLabel textLabel, const uint32_t startIndex, const uint32_t endIndex);
 287
 288 /**
 289  * @brief Gets the bounding box of a specific text range.
 290  *
 291  * @param[in] textLabel The instance of TextLabel.
 292  * @param[in] startIndex start index of the text requested to get bounding box to.
 293  * @param[in] endIndex end index(included) of the text requested to get bounding box to.
 294  * @return bounding box of the requested text.
 295  */
 296 DALI_TOOLKIT_API Rect<> GetTextBoundingRectangle(TextLabel textLabel, uint32_t startIndex, uint32_t endIndex);
 297
 298 /**
 299  * @brief Set text fit array to text label.
 300  *
 301  * @param[in] textLabel The instance of TextLabel.
 302  * @param[in] enable Whether the text fit array is enabled or not.
 303  * @param[in] fitOptions list of the fit options.
 304  */
 305 DALI_TOOLKIT_API void SetTextFitArray(TextLabel textLabel, const bool enable, std::vector<FitOption>& fitOptions);
 306
 307 /**
 308  * @brief Get the text fit array of text label.
 309  *
 310  * @param[in] textLabel The instance of TextLabel.
 311  * @return list of the fit options.
 312  */
 313 DALI_TOOLKIT_API std::vector<FitOption>& GetTextFitArray(TextLabel textLabel);
 314
 315 /**
 316  * @brief Whether the text fit array is enabled or not.
 317  *
 318  * @return True if the text fit array is enabled.
 319  */
 320 DALI_TOOLKIT_API bool IsTextFitArrayEnabled(TextLabel textLabel);
 321
 322 /**
 323  * @brief Set removing front inset to text label.
 324  *
 325  * @param[in] textLabel The instance of TextLabel.
 326  * @param[in] remove Whether front inset of text label has to be removed or not.
 327  */
 328 DALI_TOOLKIT_API void SetRemoveFrontInset(TextLabel textLabel, const bool remove);
 329
 330 /**
 331  * @brief Whether front inset of text label is removed or not.
 332  *
 333  * @param[in] textLabel The instance of TextLabel.
 334  * @return True if the front inset of text label is removed.
 335  */
 336 DALI_TOOLKIT_API bool IsRemoveFrontInset(TextLabel textLabel);
 337
 338 /**
 339  * @brief Set removing back inset to text label.
 340  *
 341  * @param[in] textLabel The instance of TextLabel.
 342  * @param[in] remove Whether back inset of text label has to be removed or not.
 343  */
 344 DALI_TOOLKIT_API void SetRemoveBackInset(TextLabel textLabel, const bool remove);
 345
 346 /**
 347  * @brief Whether back inset of text label is removed or not.
 348  *
 349  * @param[in] textLabel The instance of TextLabel.
 350  * @return True if the back inset of text label is removed.
 351  */
 352 DALI_TOOLKIT_API bool IsRemoveBackInset(TextLabel textLabel);
 353
 354 /**
 355  * @brief Anchor clicked signal type.
 356  *
 357  * @note Signal
 358  *  - const char* : href of clicked anchor.
 359  *  - uint32_t    : length of href.
 360  */
 361 using AnchorClickedSignalType = Signal<void(TextLabel, const char*, uint32_t)>;
 362
 363 /**
 364  * @brief TextFit property changed signal type.
 365  */
 366 using TextFitChangedSignalType = Signal<void(TextLabel)>;
 367
 368 /**
 369  * @brief This signal is emitted when the anchor is clicked.
 370  *
 371  * A callback of the following type may be connected:
 372  * @code
 373  *   void YourCallbackName(TextLabel textLabel, const char* href, uint32_t hrefLength);
 374  * @endcode
 375  * @param[in] textLabel The instance of TextLabel.
 376  * @return The signal to connect to.
 377  */
 378 DALI_TOOLKIT_API AnchorClickedSignalType& AnchorClickedSignal(TextLabel textLabel);
 379
 380 /**
 381  * @brief This signal is emitted when the textfit property is changed.
 382  *
 383  * A callback of the following type may be connected:
 384  * @code
 385  *   void YourCallbackName(TextLabel textLabel);
 386  * @endcode
 387  * @param[in] textLabel The instance of TextLabel.
 388  * @return The signal to connect to.
 389  */
 390 DALI_TOOLKIT_API TextFitChangedSignalType& TextFitChangedSignal(TextLabel textLabel);
 391
 392 } // namespace DevelTextLabel
 393
 394 } // namespace Toolkit
 395
 396 } // namespace Dali
 397
 398 #endif // DALI_TOOLKIT_TEXT_LABEL_DEVEL_H