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