docs/content/programming-guide/text-field.md

   1 <!--
   2 /**-->
   3
   4 # Text Field {#text-field}
   5
   6 ## Overview
   7
   8 The Dali::Toolkit::TextField is a control which provides a single-line editable text field.
   9
  10 ### Basic usage
  11
  12 Before any text has been entered, the TextField can display some placeholder text.
  13 An alternative placeholder can be displayed when the TextField has keyboard focus.
  14 For example a TextField used to enter a user name could initially show "Unknown Name", and then show "Enter Name." when the cursor is shown.
  15
  16 Note *CR+LF* new line characters are replaced by a *LF* one.
  17
  18 ~~~{.cpp}
  19 // C++
  20
  21 TextField field = TextField::New();
  22 field.SetProperty( TextField::Property::PLACEHOLDER_TEXT, "Unnamed Name" );
  23 field.SetProperty( TextField::Property::PLACEHOLDER_TEXT_FOCUSED, "Enter Name." );
  24
  25 Stage::GetCurrent().Add( field );
  26 ~~~
  27
  28 When the TextField is tapped, it will automatically gain the keyboard focus. Key events will then result in text being inserted, and the placeholder text will be removed.
  29 After text has been entered, it can be retrieved from the TEXT property.
  30
  31 ~~~{.cpp}
  32 // C++
  33
  34 Property::Value fieldText = field.GetProperty( TextField::Property::TEXT );
  35 std::cout << "Received text: " << fieldText.Get< std::string >() << std::endl;
  36 ~~~
  37
  38 ### Font Selection
  39
  40 By default TextField will automatically select a suitable font from the platform. However, a different font could be selected. See the [Font Selection](@ref font-selection) section for more details.
  41
  42 ### Mark-up Style
  43
  44 Mark-up tags can be used to change the style of the text. See the [Mark-up Style](@ref markup-style) section for more details.
  45
  46 ### Input Style
  47
  48 The input style can be changed through the control properties. See the [Input Style](@ref input-style) section for more details.
  49
  50 ### Text Alignment
  51
  52 TextField displays a single-line of text, which will scroll if there is not enough room for the text displayed.
  53 If there is enough room, then the text can be aligned horizontally to the beginning, end, or center of the available area:
  54
  55 ~~~{.cpp}
  56 // C++
  57
  58 field.SetProperty( TextField::Property::HORIZONTAL_ALIGNMENT, "BEGIN" ); // "CENTER" or "END"
  59 ~~~
  60
  61 ### Copy and Paste  (Selection)
  62
  63 Text can be selected by a long press or double tapping it. See the [Copy and Paste](@ref copy-n-paste) section for more details.
  64
  65 ### TextField Decorations
  66
  67 #### Color
  68
  69 To change the color of the text, the recommended way is to use the TEXT_COLOR property.
  70 An alternative color can be used for placeholder text by setting PLACEHOLDER_TEXT_COLOR.
  71 Note that unlike the Actor::COLOR property, these properties will not affect child Actors added to the TextField.
  72
  73 ~~~{.cpp}
  74 // C++
  75 field.SetProperty( TextField::Property::TEXT_COLOR, Color::CYAN );
  76 field.SetProperty( TextField::Property::PLACEHOLDER_TEXT_COLOR, Color::BLACK );
  77 ~~~
  78
  79 ### Text Field Properties
  80
  81  Name (JSON)                       |  Name (C++)                          |  Type        | Writable     | Animatable
  82 -----------------------------------|--------------------------------------|--------------|--------------|-----------
  83  renderingBackend                  | RENDERING_BACKEND                    |  INTEGER     | O            | X
  84  text                              | TEXT                                 |  STRING      | O            | X
  85  placeholderText                   | PLACEHOLDER_TEXT                     |  STRING      | O            | X
  86  placeholderTextFocused            | PLACEHOLDER_TEXT_FOCUSED             |  STRING      | O            | X
  87  fontFamily                        | FONT_FAMILY                          |  STRING      | O            | X
  88  fontStyle                         | FONT_STYLE                           |  STRING      | O            | X
  89  pointSize                         | POINT_SIZE                           |  FLOAT       | O            | X
  90  maxLength                         | MAX_LENGTH                           |  INTEGER     | O            | X
  91  exceedPolicy                      | EXCEED_POLICY                        |  INTEGER     | O            | X
  92  horizontalAlignment               | HORIZONTAL_ALIGNMENT                 |  STRING      | O            | X
  93  verticalAlignment                 | VERTICAL_ALIGNMENT                   |  STRING      | O            | X
  94  textColor                         | TEXT_COLOR                           |  VECTOR4     | O            | X
  95  placeholderTextColor              | PLACEHOLDER_TEXT_COLOR               |  VECTOR4     | O            | X
  96  primaryCursorColor                | PRIMARY_CURSOR_COLOR                 |  VECTOR4     | O            | X
  97  secondaryCursorColor              | SECONDARY_CURSOR_COLOR               |  VECTOR4     | O            | X
  98  enableCursorBlink                 | ENABLE_CURSOR_BLINK                  |  BOOLEAN     | O            | X
  99  cursorBlinkInterval               | CURSOR_BLINK_INTERVAL                |  FLOAT       | O            | X
 100  cursorBlinkDuration               | CURSOR_BLINK_DURATION                |  FLOAT       | O            | X
 101  cursorWidth                       | CURSOR_WIDTH                         |  INTEGER     | O            | X
 102  grabHandleImage                   | GRAB_HANDLE_IMAGE                    |  STRING      | O            | X
 103  grabHandlePressedImage            | GRAB_HANDLE_PRESSED_IMAGE            |  STRING      | O            | X
 104  scrollThreshold                   | SCROLL_THRESHOLD                     |  FLOAT       | O            | X
 105  scrollSpeed                       | SCROLL_SPEED                         |  FLOAT       | O            | X
 106  selectionHandleImageLeft          | SELECTION_HANDLE_IMAGE_LEFT          |  STRING      | O            | X
 107  selectionHandleImageRight         | SELECTION_HANDLE_IMAGE_RIGHT         |  STRING      | O            | X
 108  selectionHandlePressedImageLeft   | SELECTION_HANDLE_PRESSED_IMAGE_LEFT  |  STRING      | O            | X
 109  selectionHandlePressedImageRight  | SELECTION_HANDLE_PRESSED_IMAGE_RIGHT |  STRING      | O            | X
 110  selectionHandleMarkerImageLeft    | SELECTION_HANDLE_MARKER_IMAGE_LEFT   |  MAP         | O            | X
 111  selectionHandleMarkerImageRight   | SELECTION_HANDLE_MARKER_IMAGE_RIGHT  |  MAP         | O            | X
 112  selectionHighlightColor           | SELECTION_HIGHLIGHT_COLOR            |  VECTOR4     | O            | X
 113  decorationBoundingBox             | DECORATION_BOUNDING_BOX              |  RECTANGLE   | O            | X
 114  inputMethodSettings               | INPUT_METHOD_SETTINGS                |  MAP         | O            | X
 115  inputColor                        | INPUT_COLOR                          |  VECTOR4     | O            | X
 116  enableMarkup                      | ENABLE_MARKUP                        |  BOOLEAN     | O            | X
 117  inputFontFamily                   | INPUT_FONT_FAMILY                    |  STRING      | O            | X
 118  inputFontStyle                    | INPUT_FONT_STYLE                     |  STRING      | O            | X
 119  inputPointSize                    | INPUT_POINT_SIZE                     |  FLOAT       | O            | X
 120  underline                         | UNDERLINE                            |  STRING      | O            | X
 121  inputUnderline                    | INPUT_UNDERLINE                      |  STRING      | O            | X
 122  shadow                            | SHADOW                               |  STRING      | O            | X
 123  inputShadow                       | INPUT_SHADOW                         |  STRING      | O            | X
 124  emboss                            | EMBOSS                               |  STRING      | O            | X
 125  inputEmboss                       | INPUT_EMBOSS                         |  STRING      | O            | X
 126  outline                           | OUTLINE                              |  STRING      | O            | X
 127  inputOutline                      | INPUT_OUTLINE                        |  STRING      | O            | X
 128
 129 */