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

   1 #ifndef __DALI_TOOLKIT_TEXT_LABEL_H__
   2 #define __DALI_TOOLKIT_TEXT_LABEL_H__
   3
   4 /*
   5  * Copyright (c) 2015 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/control.h>
  23
  24 namespace Dali
  25 {
  26
  27 namespace Toolkit
  28 {
  29
  30 namespace Internal DALI_INTERNAL
  31 {
  32 class TextLabel;
  33 }
  34 /**
  35  * @addtogroup dali_toolkit_controls_text_controls
  36  * @{
  37  */
  38
  39 /**
  40  * @brief A control which renders a short text string.
  41  *
  42  * Text labels are lightweight, non-editable and do not respond to user input.
  43  *
  44  * @section TextLabelProperties Properties
  45  * |%Property enum                    |String name          |Type          |Writable|Animatable|
  46  * |----------------------------------|---------------------|--------------|--------|----------|
  47  * | Property::RENDERING_BACKEND      | renderingBackend    |  INTEGER     | O      | X        |
  48  * | Property::TEXT                   | text                |  STRING      | O      | X        |
  49  * | Property::FONT_FAMILY            | fontFamily          |  STRING      | O      | X        |
  50  * | Property::FONT_STYLE             | fontStyle           |  STRING      | O      | X        |
  51  * | Property::POINT_SIZE             | pointSize           |  FLOAT       | O      | X        |
  52  * | Property::MULTI_LINE             | multiLine           |  BOOLEAN     | O      | X        |
  53  * | Property::HORIZONTAL_ALIGNMENT   | horizontalAlignment |  STRING      | O      | X        |
  54  * | Property::VERTICAL_ALIGNMENT     | verticalAlignment   |  STRING      | O      | X        |
  55  * | Property::TEXT_COLOR             | textColor           |  VECTOR4     | O      | X        |
  56  * | Property::SHADOW_OFFSET          | shadowOffset        |  VECTOR2     | O      | X        |
  57  * | Property::SHADOW_COLOR           | shadowColor         |  VECTOR4     | O      | X        |
  58  * | Property::UNDERLINE_ENABLED      | underlineEnabled    |  BOOLEAN     | O      | X        |
  59  * | Property::UNDERLINE_COLOR        | underlineColor      |  VECTOR4     | O      | X        |
  60  * | Property::UNDERLINE_HEIGHT       | underlineHeight     |  FLOAT       | O      | X        |
  61  * | Property::ENABLE_MARKUP          | enableMarkup        |  BOOLEAN     | O      | X        |
  62  * | Property::ENABLE_AUTO_SCROLL     | enableAutoScroll    |  BOOLEAN     | O      | X        |
  63  * | Property::AUTO_SCROLL_SPEED      | autoScrollSpeed     |  INTEGER     | O      | X        |
  64  * | Property::AUTO_SCROLL_LOOP_COUNT | autoScrollLoopCount |  INTEGER     | O      | X        |
  65  * | Property::AUTO_SCROLL_GAP        | autoScrollGap       |  INTEGER     | O      | X        |
  66  *
  67  * @SINCE_1_0.0
  68  */
  69 class DALI_IMPORT_API TextLabel : public Control
  70 {
  71 public:
  72
  73   /**
  74    * @brief The start and end property ranges for this control.
  75    * @SINCE_1_0.0
  76    */
  77   enum PropertyRange
  78   {
  79     PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1, ///< @SINCE_1_0.0
  80     PROPERTY_END_INDEX =   PROPERTY_START_INDEX + 1000              ///< Reserve property indices @SINCE_1_0.0
  81   };
  82
  83   /**
  84    * @brief An enumeration of properties belonging to the TextLabel class.
  85    * @SINCE_1_0.0
  86    */
  87   struct Property
  88   {
  89     enum
  90     {
  91       /**
  92        * @brief The type of rendering e.g. bitmap-based
  93        * @details name "renderingBackend", type INT, default RENDERING_SHARED_ATLAS
  94        * @SINCE_1_0.0
  95        */
  96       RENDERING_BACKEND = PROPERTY_START_INDEX,
  97
  98       /**
  99        * @brief The text to display in UTF-8 format,
 100        * @details name "text", type STRING
 101        * @SINCE_1_0.0
 102        */
 103       TEXT,
 104
 105       /**
 106        * @brief The requested font family to use,
 107        * @details name "fontFamily", type STRING
 108        * @SINCE_1_0.0
 109        */
 110       FONT_FAMILY,
 111
 112       /**
 113        * @brief The requested font style to use,
 114        * @details name "fontStyle", type STRING
 115        * @SINCE_1_0.0
 116        */
 117       FONT_STYLE,
 118
 119       /**
 120        * @brief The size of font in points
 121        * @details name "pointSize", type FLOAT
 122        * @SINCE_1_0.0
 123        */
 124       POINT_SIZE,
 125
 126       /**
 127        * @brief The single-line or multi-line layout option
 128        * @details name "multiLine", type FLOAT, default SINGLE_LINE_BOX
 129        * @SINCE_1_0.0
 130        */
 131       MULTI_LINE,
 132
 133       /**
 134        * @brief The line horizontal alignment
 135        * @details name "horizontalAlignment", type STRING,  values "BEGIN", "CENTER", "END", default BEGIN
 136        * @SINCE_1_0.0
 137        */
 138       HORIZONTAL_ALIGNMENT,
 139
 140       /**
 141        * @brief The line vertical alignment
 142        * @details name "verticalAlignment", type STRING,  values "TOP",   "CENTER", "BOTTOM" @SINCE_1_0.0, default TOP
 143        * @SINCE_1_0.0
 144        */
 145       VERTICAL_ALIGNMENT,
 146
 147       /**
 148        * @brief The color of the text
 149        * @details name "textColor", type VECTOR4
 150        * @SINCE_1_0.0
 151        */
 152       TEXT_COLOR,
 153
 154       /**
 155        * @brief The drop shadow offset 0 indicates no shadow
 156        * @details name "shadowOffset", type VECTOR4
 157        * @SINCE_1_0.0
 158        */
 159       SHADOW_OFFSET,
 160
 161       /**
 162        * @brief The color of a drop shadow
 163        * @details name "shadowColor", type VECTOR4
 164        * @SINCE_1_0.0
 165        */
 166       SHADOW_COLOR,
 167
 168       /**
 169        * @brief The underline enabled flag
 170        * @details name "underlineEnabled", type BOOLEAN
 171        * @SINCE_1_0.0
 172        */
 173       UNDERLINE_ENABLED,
 174
 175       /**
 176        * @brief The color of the underline
 177        * @details name "underlineColor", type VECTOR4
 178        * @SINCE_1_0.0
 179        */
 180       UNDERLINE_COLOR,
 181
 182       /**
 183        * @brief Overrides the underline height from font metrics
 184        * @details name "underlineHeight", type FLOAT
 185        * @SINCE_1_0.0
 186        */
 187       UNDERLINE_HEIGHT,
 188
 189       /**
 190        * @brief  Whether the mark-up processing is enabled
 191        * @details name "enableMarkup", type BOOLEAN
 192        * @SINCE_1_0.0
 193        */
 194       ENABLE_MARKUP,
 195
 196       /**
 197        * @brief  Start or stop auto scrolling,
 198        * @details name "enableMarkup", type BOOLEAN, default is false
 199        * @SINCE_1_1.35
 200        */
 201       ENABLE_AUTO_SCROLL,
 202
 203       /**
 204        * @brief  Start or stop auto scrolling,
 205        * @details name "autoScrollSpeed", type INT, default in style sheet
 206        * @SINCE_1_1.35
 207        */
 208       AUTO_SCROLL_SPEED,
 209
 210       /**
 211        * @brief  Number of complete loops when scrolling enabled
 212        * @details name "autoScrollLoopCount", type INT, default in style sheet
 213        * @SINCE_1_1.35
 214        */
 215       AUTO_SCROLL_LOOP_COUNT,
 216
 217       /**
 218        * @brief  Gap before before scrolling wraps
 219        * @details name "autoScrollGap", type INT, default in style sheet but can be overridden to prevent same text being show at start and end.
 220        * @SINCE_1_1.35
 221        */
 222       AUTO_SCROLL_GAP
 223     };
 224   };
 225
 226   /**
 227    * @brief Create the TextLabel control.
 228    *
 229    * @SINCE_1_0.0
 230    * @return A handle to the TextLabel control.
 231    */
 232   static TextLabel New();
 233
 234   /**
 235    * @brief Create the TextLabel control.
 236    *
 237    * @SINCE_1_0.0
 238    * @param[in] text The text to display.
 239    * @return A handle to the TextLabel control.
 240    */
 241   static TextLabel New( const std::string& text );
 242
 243   /**
 244    * @brief Creates an empty handle.
 245    * @SINCE_1_0.0
 246    */
 247   TextLabel();
 248
 249   /**
 250    * @brief Copy constructor.
 251    *
 252    * @SINCE_1_0.0
 253    * @param[in] handle The handle to copy from.
 254    */
 255   TextLabel( const TextLabel& handle );
 256
 257   /**
 258    * @brief Assignment operator.
 259    *
 260    * @SINCE_1_0.0
 261    * @param[in] handle The handle to copy from.
 262    * @return A reference to this.
 263    */
 264   TextLabel& operator=( const TextLabel& handle );
 265
 266   /**
 267    * @brief Destructor
 268    *
 269    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 270    * @SINCE_1_0.0
 271    */
 272   ~TextLabel();
 273
 274   /**
 275    * @brief Downcast a handle to TextLabel.
 276    *
 277    * If the BaseHandle points is a TextLabel the downcast returns a valid handle.
 278    * If not the returned handle is left empty.
 279    *
 280    * @SINCE_1_0.0
 281    * @param[in] handle Handle to an object
 282    * @return handle to a TextLabel or an empty handle
 283    */
 284   static TextLabel DownCast( BaseHandle handle );
 285
 286 public: // Not intended for application developers
 287
 288   /**
 289    * @brief Creates a handle using the Toolkit::Internal implementation.
 290    *
 291    * @SINCE_1_0.0
 292    * @param[in] implementation The Control implementation.
 293    */
 294   DALI_INTERNAL TextLabel( Internal::TextLabel& implementation );
 295
 296   /**
 297    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 298    *
 299    * @SINCE_1_0.0
 300    * @param[in]  internal  A pointer to the internal CustomActor.
 301    */
 302   explicit DALI_INTERNAL TextLabel( Dali::Internal::CustomActor* internal );
 303 };
 304
 305 /**
 306  * @}
 307  */
 308 } // namespace Toolkit
 309
 310 } // namespace Dali
 311
 312 #endif // __DALI_TOOLKIT_TEXT_LABEL_H__