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 // INTERNAL INCLUDES
  22 #include <dali-toolkit/public-api/controls/text-controls/text-label.h>
  23
  24 namespace Dali
  25 {
  26 namespace Toolkit
  27 {
  28 namespace DevelTextLabel
  29 {
  30 namespace Property
  31 {
  32 enum Type
  33 {
  34   TEXT                   = Dali::Toolkit::TextLabel::Property::TEXT,
  35   FONT_FAMILY            = Dali::Toolkit::TextLabel::Property::FONT_FAMILY,
  36   FONT_STYLE             = Dali::Toolkit::TextLabel::Property::FONT_STYLE,
  37   POINT_SIZE             = Dali::Toolkit::TextLabel::Property::POINT_SIZE,
  38   MULTI_LINE             = Dali::Toolkit::TextLabel::Property::MULTI_LINE,
  39   HORIZONTAL_ALIGNMENT   = Dali::Toolkit::TextLabel::Property::HORIZONTAL_ALIGNMENT,
  40   VERTICAL_ALIGNMENT     = Dali::Toolkit::TextLabel::Property::VERTICAL_ALIGNMENT,
  41   ENABLE_MARKUP          = Dali::Toolkit::TextLabel::Property::ENABLE_MARKUP,
  42   ENABLE_AUTO_SCROLL     = Dali::Toolkit::TextLabel::Property::ENABLE_AUTO_SCROLL,
  43   AUTO_SCROLL_SPEED      = Dali::Toolkit::TextLabel::Property::AUTO_SCROLL_SPEED,
  44   AUTO_SCROLL_LOOP_COUNT = Dali::Toolkit::TextLabel::Property::AUTO_SCROLL_LOOP_COUNT,
  45   AUTO_SCROLL_GAP        = Dali::Toolkit::TextLabel::Property::AUTO_SCROLL_GAP,
  46   LINE_SPACING           = Dali::Toolkit::TextLabel::Property::LINE_SPACING,
  47   UNDERLINE              = Dali::Toolkit::TextLabel::Property::UNDERLINE,
  48   SHADOW                 = Dali::Toolkit::TextLabel::Property::SHADOW,
  49   EMBOSS                 = Dali::Toolkit::TextLabel::Property::EMBOSS,
  50   OUTLINE                = Dali::Toolkit::TextLabel::Property::OUTLINE,
  51   PIXEL_SIZE             = Dali::Toolkit::TextLabel::Property::PIXEL_SIZE,
  52   ELLIPSIS               = Dali::Toolkit::TextLabel::Property::ELLIPSIS,
  53   AUTO_SCROLL_LOOP_DELAY = Dali::Toolkit::TextLabel::Property::AUTO_SCROLL_LOOP_DELAY,
  54   AUTO_SCROLL_STOP_MODE  = Dali::Toolkit::TextLabel::Property::AUTO_SCROLL_STOP_MODE,
  55   LINE_COUNT             = Dali::Toolkit::TextLabel::Property::LINE_COUNT,
  56   LINE_WRAP_MODE         = Dali::Toolkit::TextLabel::Property::LINE_WRAP_MODE,
  57
  58   /**
  59      * @brief The direction of the layout.
  60      * @details Name "textDirection", type [Type](@ref Dali::Toolkit::DevelText::TextDirection::Type) (Property::INTEGER), Read/Write
  61      * @note The text direction can be changed only by replacing the text itself.
  62      * @see TextDirection::Type for supported values.
  63      */
  64   TEXT_DIRECTION,
  65
  66   /**
  67      * @brief Alignment of text within area of single line
  68      * @details Name "verticalLineAlignment", type [Type](@ref Dali::Toolkit::DevelText::VerticalLineAlignment::Type) (Property::INTEGER), Read/Write
  69      * @note The default value is TOP
  70      * @see VerticalLineAlignment::Type for supported values
  71      */
  72   VERTICAL_LINE_ALIGNMENT,
  73
  74   /**
  75      * @brief The default text background parameters.
  76      * @details Name "textBackground", type Property::MAP.
  77      * @note Use "textBackground" as property name to avoid conflict with Control's "background" property
  78      *
  79      * The background map contains the following keys:
  80      *
  81      * | %Property Name       | Type     | Required | Description                                                                                                        |
  82      * |----------------------|----------|----------|--------------------------------------------------------------------------------------------------------------------|
  83      * | enable               | BOOLEAN  | No       | True to enable the background or false to disable (the default value is false)                                     |
  84      * | color                | VECTOR4  | No       | The color of the background (the default value is Color::CYAN)                                                     |
  85      */
  86   BACKGROUND,
  87
  88   /**
  89      * @brief Ignore spaces after text.
  90      * @details Name "ignoreSpacesAfterText", type (Property::BOLEAN), Read/Write
  91      * @note The default value is true
  92      */
  93   IGNORE_SPACES_AFTER_TEXT,
  94
  95   /**
  96      * @brief Modifies the default text alignment to match the direction of the system language.
  97      * @details Name "matchSystemLanguageDirection", type (Property::BOLEAN), Read/Write
  98      * @note The default value is true
  99      *
 100      * If MATCH_SYSTEM_LANGUAGE_DIRECTION property set true, the default text alignment to match the direction of the system language.
 101      *
 102      * ex) Current system language direction LTR.
 103      *     TextLabel::New("Hello world \n  ﻡﺮﺤﺑﺍ. ");
 104      *     TextLabel::Property::HORIZONTAL_ALIGNMENT, "END"
 105      *
 106      * | TextLabel::Property::MATCH_SYSTEM_LANGUAGE_DIRECTION                 |
 107      * |-----------------------------------------------------------------------
 108      * |               false               |          true (default)          |
 109      * |-----------------------------------|----------------------------------|
 110      * |                     Hello world   |                  Hello world     |
 111      * |   ﻡﺮﺤﺑﺍ.                     |                          ﻡﺮﺤﺑﺍ.      |
 112      *
 113      */
 114   MATCH_SYSTEM_LANGUAGE_DIRECTION,
 115
 116   /**
 117      * @brief The text fit parameters.
 118      * @details Name "textFit", type Property::MAP.
 119      * @note The default value is false
 120      *
 121      * The textFit map contains the following keys:
 122      *
 123      * | %Property Name       | Type     | Required | Description                                                                                                        |
 124      * |----------------------|----------|----------|--------------------------------------------------------------------------------------------------------------------|
 125      * | enable               | BOOLEAN  | No       | True to enable the text fit or false to disable (the default value is false)                                     |
 126      * | minSize              | FLOAT    | No       | Minimum Size for text fit (the default value is 10.f)                                                     |
 127      * | maxSize              | FLOAT    | No       | Maximum Size for text fit (the default value is 100.f)                                                     |
 128      * | stepSize             | FLOAT    | No       | Step Size for font increase (the default value is 1.f)                                                     |
 129      * | fontSizeType         | STRING   | No       | The size type of font, You can choose between "pointSize" or "pixelSize". (the default value is "pointSize")                                                     |
 130      */
 131   TEXT_FIT,
 132
 133   /**
 134      * @brief Sets the height of the line in points.
 135      * @details Name "lineSize", type Property::FLOAT.
 136      * @note If the font size is larger than the line size, it works with the font size.
 137      */
 138   MIN_LINE_SIZE,
 139
 140   /**
 141      * @brief The type of rendering e.g. bitmap-based.
 142      * @details Name "renderingBackend", type Property::INT.
 143      */
 144   RENDERING_BACKEND,
 145
 146   /**
 147    * @brief The font size scale for scaling the specified font size up or down.
 148    * @details name "fontSizeScale", type Property::FLOAT.
 149    * @note The default value is 1.0 which does nothing.
 150    * The given font size scale value is used for multiplying the specified font size before querying fonts.
 151    *
 152    * e.g. The rendering results of both cases are same.
 153    *  - fontSize: 15pt, fontSizeScale: 1.0
 154    *  - fontSize: 10pt, fontSizeScale: 1.5
 155    */
 156   FONT_SIZE_SCALE,
 157
 158   /**
 159    * @brief True to enable the font size scale or false to disable.
 160    * @details Name "enableFontSizeScale", type Property::BOOLEAN.
 161    * @note The default value is true.
 162    * If false, font size scale is not apppied.
 163    */
 164   ENABLE_FONT_SIZE_SCALE,
 165
 166   /**
 167   * @brief The enumerations used to specify whether to position the ellipsis at the END, START or MIDDLE of the text.
 168   * @details Name "EllipsisPosition", type [Type](@ref Dali::Toolkit::DevelText::EllipsisPosition::Type) (Property::INTEGER), or Property::STRING. Read/Write
 169   * @note Default is EllipsisPosition::END.
 170   * @see DevelText::EllipsisPosition
 171   */
 172   ELLIPSIS_POSITION,
 173
 174   /**
 175    * @brief The default strikethrough parameters.
 176    * @details Name "strikethrough", type Property::MAP.
 177    *
 178    * The strikethrough map contains the following keys:
 179    *
 180    * | %Property Name       | Type     | Required | Description                                                                                                        |
 181    * |----------------------|----------|----------|--------------------------------------------------------------------------------------------------------------------|
 182    * | enable               | BOOLEAN  | No       | True to enable the strikethrough or false to disable (the default value is false)                                  |
 183    * | color                | VECTOR4  | No       | The color of the strikethrough (the default value is Color::BLACK)                                                 |
 184    * | height               | FLOAT    | No       | The height of the strikethrough (the default value is 0)                                                               |
 185    *
 186    */
 187   STRIKETHROUGH,
 188
 189   /**
 190   * @brief The spaces between characters in Pixels.
 191   * @details Name "characterSpacing", type Property::FLOAT.
 192   * @note
 193   *   A positive value will make the characters far apart (expanded) and a negative value will bring them closer (condensed).
 194   *   The default value is 0.f which does nothing.
 195   */
 196   CHARACTER_SPACING,
 197
 198   /**
 199    * @brief the relative height of the line (a factor that will be multiplied by text height).
 200    * @details Name "relativeLineSize", type Property::FLOAT.
 201    * @note If the value is less than 1, the lines could to be overlapped.
 202    */
 203   RELATIVE_LINE_SIZE,
 204 };
 205
 206 } // namespace Property
 207
 208 /**
 209  * @brief Get the rendered size of a specific text range.
 210  * if the requested text is at multilines, multiple sizes will be returned for each text located in a separate line.
 211  * if a line contains characters with different directions, multiple sizes will be returned for each block of contiguous characters with the same direction.
 212  *
 213  * @param[in] textLabel The instance of TextLabel.
 214  * @param[in] startIndex start index of the text requested to calculate size for.
 215  * @param[in] endIndex end index(included) of the text requested to calculate size for.
 216  * @return list of sizes of the reuested text.
 217  */
 218 DALI_TOOLKIT_API Vector<Vector2> GetTextSize(TextLabel textLabel, const uint32_t startIndex, const uint32_t endIndex);
 219
 220 /**
 221  * @brief Get the top/left rendered position of a specific text range.
 222  * if the requested text is at multilines, multiple positions will be returned for each text located in a separate line.
 223  * if a line contains characters with different directions, multiple positions will be returned for each block of contiguous characters with the same direction.
 224  *
 225  * @param[in] textLabel The instance of TextLabel.
 226  * @param[in] startIndex start index of the text requested to get position to.
 227  * @param[in] endIndex end index(included) of the text requested to get position to.
 228  * @return list of positions of the requested text.
 229  */
 230 DALI_TOOLKIT_API Vector<Vector2> GetTextPosition(TextLabel textLabel, const uint32_t startIndex, const uint32_t endIndex);
 231
 232 /**
 233  * @brief Anchor clicked signal type.
 234  *
 235  * @note Signal
 236  *  - const char* : href of clicked anchor.
 237  *  - uint32_t    : length of href.
 238  */
 239 using AnchorClickedSignalType = Signal<void(TextLabel, const char*, uint32_t)>;
 240
 241 /**
 242  * @brief TextFit property changed signal type.
 243  */
 244 using TextFitChangedSignalType = Signal<void(TextLabel)>;
 245
 246 /**
 247  * @brief This signal is emitted when the anchor is clicked.
 248  *
 249  * A callback of the following type may be connected:
 250  * @code
 251  *   void YourCallbackName(TextLabel textLabel, const char* href, uint32_t hrefLength);
 252  * @endcode
 253  * @param[in] textLabel The instance of TextLabel.
 254  * @return The signal to connect to.
 255  */
 256 DALI_TOOLKIT_API AnchorClickedSignalType& AnchorClickedSignal(TextLabel textLabel);
 257
 258 /**
 259  * @brief This signal is emitted when the textfit property is changed.
 260  *
 261  * A callback of the following type may be connected:
 262  * @code
 263  *   void YourCallbackName(TextLabel textLabel);
 264  * @endcode
 265  * @param[in] textLabel The instance of TextLabel.
 266  * @return The signal to connect to.
 267  */
 268 DALI_TOOLKIT_API TextFitChangedSignalType& TextFitChangedSignal(TextLabel textLabel);
 269
 270 } // namespace DevelTextLabel
 271
 272 } // namespace Toolkit
 273
 274 } // namespace Dali
 275
 276 #endif // DALI_TOOLKIT_TEXT_LABEL_DEVEL_H