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) 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 // 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 The enumerations used to specify whether to position the ellipsis at the END, START or MIDDLE of the text.
 160   * @details Name "EllipsisPosition", type [Type](@ref Dali::Toolkit::DevelText::EllipsisPosition::Type) (Property::INTEGER), or Property::STRING. Read/Write
 161   * @note Default is EllipsisPosition::END.
 162   * @see DevelText::EllipsisPosition
 163   */
 164   ELLIPSIS_POSITION,
 165
 166   /**
 167    * @brief The default strikethrough parameters.
 168    * @details Name "strikethrough", type Property::MAP.
 169    *
 170    * The strikethrough map contains the following keys:
 171    *
 172    * | %Property Name       | Type     | Required | Description                                                                                                        |
 173    * |----------------------|----------|----------|--------------------------------------------------------------------------------------------------------------------|
 174    * | enable               | BOOLEAN  | No       | True to enable the strikethrough or false to disable (the default value is false)                                  |
 175    * | color                | VECTOR4  | No       | The color of the strikethrough (the default value is Color::BLACK)                                                 |
 176    * | height               | FLOAT    | No       | The height of the strikethrough (the default value is 0)                                                               |
 177    *
 178    */
 179   STRIKETHROUGH,
 180 };
 181
 182 } // namespace Property
 183
 184 /**
 185  * @brief Get the rendered size of a specific text range.
 186  * if the requested text is at multilines, multiple sizes will be returned for each text located in a separate line.
 187  * if a line contains characters with different directions, multiple sizes will be returned for each block of contiguous characters with the same direction.
 188  *
 189  * @param[in] textLabel The instance of TextLabel.
 190  * @param[in] startIndex start index of the text requested to calculate size for.
 191  * @param[in] endIndex end index(included) of the text requested to calculate size for.
 192  * @return list of sizes of the reuested text.
 193  */
 194 DALI_TOOLKIT_API Vector<Vector2> GetTextSize(TextLabel textLabel, const uint32_t startIndex, const uint32_t endIndex);
 195
 196 /**
 197  * @brief Get the top/left rendered position of a specific text range.
 198  * if the requested text is at multilines, multiple positions will be returned for each text located in a separate line.
 199  * if a line contains characters with different directions, multiple positions will be returned for each block of contiguous characters with the same direction.
 200  *
 201  * @param[in] textLabel The instance of TextLabel.
 202  * @param[in] startIndex start index of the text requested to get position to.
 203  * @param[in] endIndex end index(included) of the text requested to get position to.
 204  * @return list of positions of the requested text.
 205  */
 206 DALI_TOOLKIT_API Vector<Vector2> GetTextPosition(TextLabel textLabel, const uint32_t startIndex, const uint32_t endIndex);
 207
 208 /**
 209  * @brief Anchor clicked signal type.
 210  *
 211  * @note Signal
 212  *  - const char* : href of clicked anchor.
 213  *  - uint32_t    : length of href.
 214  */
 215 using AnchorClickedSignalType = Signal<void(TextLabel, const char*, uint32_t)>;
 216
 217 /**
 218  * @brief TextFit property changed signal type.
 219  */
 220 using TextFitChangedSignalType = Signal<void(TextLabel)>;
 221
 222 /**
 223  * @brief This signal is emitted when the anchor is clicked.
 224  *
 225  * A callback of the following type may be connected:
 226  * @code
 227  *   void YourCallbackName(TextLabel textLabel, const char* href, uint32_t hrefLength);
 228  * @endcode
 229  * @param[in] textLabel The instance of TextLabel.
 230  * @return The signal to connect to.
 231  */
 232 DALI_TOOLKIT_API AnchorClickedSignalType& AnchorClickedSignal(TextLabel textLabel);
 233
 234 /**
 235  * @brief This signal is emitted when the textfit property is changed.
 236  *
 237  * A callback of the following type may be connected:
 238  * @code
 239  *   void YourCallbackName(TextLabel textLabel);
 240  * @endcode
 241  * @param[in] textLabel The instance of TextLabel.
 242  * @return The signal to connect to.
 243  */
 244 DALI_TOOLKIT_API TextFitChangedSignalType& TextFitChangedSignal(TextLabel textLabel);
 245
 246 } // namespace DevelTextLabel
 247
 248 } // namespace Toolkit
 249
 250 } // namespace Dali
 251
 252 #endif // DALI_TOOLKIT_TEXT_LABEL_DEVEL_H