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 } // namespace Property
 224
 225 struct FitOption
 226 {
 227   FitOption(float pointSize = 0.0f, float minLineSize = 0.0f)
 228   : mPointSize(pointSize), mMinLineSize(minLineSize) {}
 229
 230   float GetPointSize() const
 231   {
 232     return mPointSize;
 233   }
 234   float GetMinLineSize() const
 235   {
 236     return mMinLineSize;
 237   }
 238   void SetPointSize(float pointSize)
 239   {
 240     mPointSize = pointSize;
 241   }
 242   void SetMinLineSize(float minLineSize)
 243   {
 244     mMinLineSize = minLineSize;
 245   }
 246
 247 private:
 248   float mPointSize   = 0.0f;
 249   float mMinLineSize = 0.0f;
 250 };
 251
 252 /**
 253  * @brief Get the rendered size of a specific text range.
 254  * if the requested text is at multilines, multiple sizes will be returned for each text located in a separate line.
 255  * if a line contains characters with different directions, multiple sizes will be returned for each block of contiguous characters with the same direction.
 256  *
 257  * @param[in] textLabel The instance of TextLabel.
 258  * @param[in] startIndex start index of the text requested to calculate size for.
 259  * @param[in] endIndex end index(included) of the text requested to calculate size for.
 260  * @return list of sizes of the reuested text.
 261  */
 262 DALI_TOOLKIT_API Vector<Vector2> GetTextSize(TextLabel textLabel, const uint32_t startIndex, const uint32_t endIndex);
 263
 264 /**
 265  * @brief Get the top/left rendered position of a specific text range.
 266  * if the requested text is at multilines, multiple positions will be returned for each text located in a separate line.
 267  * if a line contains characters with different directions, multiple positions 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 get position to.
 271  * @param[in] endIndex end index(included) of the text requested to get position to.
 272  * @return list of positions of the requested text.
 273  */
 274 DALI_TOOLKIT_API Vector<Vector2> GetTextPosition(TextLabel textLabel, const uint32_t startIndex, const uint32_t endIndex);
 275
 276 /**
 277  * @brief Gets the bounding box of a specific text range.
 278  *
 279  * @param[in] textLabel The instance of TextLabel.
 280  * @param[in] startIndex start index of the text requested to get bounding box to.
 281  * @param[in] endIndex end index(included) of the text requested to get bounding box to.
 282  * @return bounding box of the requested text.
 283  */
 284 DALI_TOOLKIT_API Rect<> GetTextBoundingRectangle(TextLabel textLabel, uint32_t startIndex, uint32_t endIndex);
 285
 286 /**
 287  * @brief Set text fit array to text label.
 288  *
 289  * @param[in] textLabel The instance of TextLabel.
 290  * @param[in] enable Whether the text fit array is enabled or not.
 291  * @param[in] fitOptions list of the fit options.
 292  */
 293 DALI_TOOLKIT_API void SetTextFitArray(TextLabel textLabel, const bool enable, std::vector<FitOption>& fitOptions);
 294
 295 /**
 296  * @brief Get the text fit array of text label.
 297  *
 298  * @param[in] textLabel The instance of TextLabel.
 299  * @return list of the fit options.
 300  */
 301 DALI_TOOLKIT_API std::vector<FitOption>& GetTextFitArray(TextLabel textLabel);
 302
 303 /**
 304  * @brief Whether the text fit array is enabled or not.
 305  *
 306  * @return True if the text fit array is enabled.
 307  */
 308 DALI_TOOLKIT_API bool IsTextFitArrayEnabled(TextLabel textLabel);
 309
 310 /**
 311  * @brief Anchor clicked signal type.
 312  *
 313  * @note Signal
 314  *  - const char* : href of clicked anchor.
 315  *  - uint32_t    : length of href.
 316  */
 317 using AnchorClickedSignalType = Signal<void(TextLabel, const char*, uint32_t)>;
 318
 319 /**
 320  * @brief TextFit property changed signal type.
 321  */
 322 using TextFitChangedSignalType = Signal<void(TextLabel)>;
 323
 324 /**
 325  * @brief This signal is emitted when the anchor is clicked.
 326  *
 327  * A callback of the following type may be connected:
 328  * @code
 329  *   void YourCallbackName(TextLabel textLabel, const char* href, uint32_t hrefLength);
 330  * @endcode
 331  * @param[in] textLabel The instance of TextLabel.
 332  * @return The signal to connect to.
 333  */
 334 DALI_TOOLKIT_API AnchorClickedSignalType& AnchorClickedSignal(TextLabel textLabel);
 335
 336 /**
 337  * @brief This signal is emitted when the textfit property is changed.
 338  *
 339  * A callback of the following type may be connected:
 340  * @code
 341  *   void YourCallbackName(TextLabel textLabel);
 342  * @endcode
 343  * @param[in] textLabel The instance of TextLabel.
 344  * @return The signal to connect to.
 345  */
 346 DALI_TOOLKIT_API TextFitChangedSignalType& TextFitChangedSignal(TextLabel textLabel);
 347
 348 } // namespace DevelTextLabel
 349
 350 } // namespace Toolkit
 351
 352 } // namespace Dali
 353
 354 #endif // DALI_TOOLKIT_TEXT_LABEL_DEVEL_H