docs/content/shared-javascript-and-cpp-documentation/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 ~~~{.js}
  29 // JavaScript
  30
  31 var field = new dali.TextField();
  32 field.placeholderText = "Unnamed Name";
  33 field.placeholderTextFocused = "Enter Name.";
  34
  35 dali.stage.add( field );
  36 ~~~
  37
  38 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.
  39 After text has been entered, it can be retrieved from the TEXT property.
  40
  41 ~~~{.cpp}
  42 // C++
  43
  44 Property::Value fieldText = field.GetProperty( TextField::Property::TEXT );
  45 std::cout << "Received text: " << fieldText.Get< std::string >() << std::endl;
  46 ~~~
  47
  48 ~~~{.js}
  49 // JavaScript
  50
  51 console.log( field.text );
  52 ~~~
  53
  54 ### Font Selection
  55
  56 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.
  57
  58 ### Mark-up Style
  59
  60 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.
  61
  62 ### Input Style
  63
  64 The input style can be changed through the control properties. See the [Input Style](@ref input-style) section for more details.
  65
  66 ### Text Alignment
  67
  68 TextField displays a single-line of text, which will scroll if there is not enough room for the text displayed.
  69 If there is enough room, then the text can be aligned horizontally to the beginning, end, or center of the available area:
  70
  71 ~~~{.cpp}
  72 // C++
  73
  74 field.SetProperty( TextField::Property::HORIZONTAL_ALIGNMENT, "BEGIN" ); // "CENTER" or "END"
  75 ~~~
  76
  77 ~~~{.js}
  78 // JavaScript
  79
  80 field.HorizontalAlignment = "BEGIN"; // "CENTER" or "END"
  81 ~~~
  82
  83 ### Copy and Paste  (Selection)
  84
  85 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.
  86
  87 ### TextField Decorations
  88
  89 #### Color
  90
  91 To change the color of the text, the recommended way is to use the TEXT_COLOR property.
  92 An alternative color can be used for placeholder text by setting PLACEHOLDER_TEXT_COLOR.
  93 Note that unlike the Actor::COLOR property, these properties will not affect child Actors added to the TextField.
  94
  95 ~~~{.cpp}
  96 // C++
  97 field.SetProperty( TextField::Property::TEXT_COLOR, Color::CYAN );
  98 field.SetProperty( TextField::Property::PLACEHOLDER_TEXT_COLOR, Color::BLACK );
  99 ~~~
 100
 101 ~~~{.js}
 102 // JavaScript
 103
 104 field.textColor = dali.COLOR_CYAN;
 105 field.placeholderTextColor = dali.COLOR_BLACK;
 106 ~~~
 107
 108 ### Text Field Properties
 109
 110  Name (JavaScript)                 |  Name (C++)                          |  Type        | Writable     | Animatable
 111 -----------------------------------|--------------------------------------|--------------|--------------|-----------
 112  renderingBackend                  | RENDERING_BACKEND                    |  INTEGER     | O            | X
 113  text                              | TEXT                                 |  STRING      | O            | X
 114  placeholderText                   | PLACEHOLDER_TEXT                     |  STRING      | O            | X
 115  placeholderTextFocused            | PLACEHOLDER_TEXT_FOCUSED             |  STRING      | O            | X
 116  fontFamily                        | FONT_FAMILY                          |  STRING      | O            | X
 117  fontStyle                         | FONT_STYLE                           |  STRING      | O            | X
 118  pointSize                         | POINT_SIZE                           |  FLOAT       | O            | X
 119  maxLength                         | MAX_LENGTH                           |  INTEGER     | O            | X
 120  exceedPolicy                      | EXCEED_POLICY                        |  INTEGER     | O            | X
 121  horizontalAlignment               | HORIZONTAL_ALIGNMENT                 |  STRING      | O            | X
 122  verticalAlignment                 | VERTICAL_ALIGNMENT                   |  STRING      | O            | X
 123  textColor                         | TEXT_COLOR                           |  VECTOR4     | O            | X
 124  placeholderTextColor              | PLACEHOLDER_TEXT_COLOR               |  VECTOR4     | O            | X
 125  primaryCursorColor                | PRIMARY_CURSOR_COLOR                 |  VECTOR4     | O            | X
 126  secondaryCursorColor              | SECONDARY_CURSOR_COLOR               |  VECTOR4     | O            | X
 127  enableCursorBlink                 | ENABLE_CURSOR_BLINK                  |  BOOLEAN     | O            | X
 128  cursorBlinkInterval               | CURSOR_BLINK_INTERVAL                |  FLOAT       | O            | X
 129  cursorBlinkDuration               | CURSOR_BLINK_DURATION                |  FLOAT       | O            | X
 130  cursorWidth                       | CURSOR_WIDTH                         |  INTEGER     | O            | X
 131  grabHandleImage                   | GRAB_HANDLE_IMAGE                    |  STRING      | O            | X
 132  grabHandlePressedImage            | GRAB_HANDLE_PRESSED_IMAGE            |  STRING      | O            | X
 133  scrollThreshold                   | SCROLL_THRESHOLD                     |  FLOAT       | O            | X
 134  scrollSpeed                       | SCROLL_SPEED                         |  FLOAT       | O            | X
 135  selectionHandleImageLeft          | SELECTION_HANDLE_IMAGE_LEFT          |  STRING      | O            | X
 136  selectionHandleImageRight         | SELECTION_HANDLE_IMAGE_RIGHT         |  STRING      | O            | X
 137  selectionHandlePressedImageLeft   | SELECTION_HANDLE_PRESSED_IMAGE_LEFT  |  STRING      | O            | X
 138  selectionHandlePressedImageRight  | SELECTION_HANDLE_PRESSED_IMAGE_RIGHT |  STRING      | O            | X
 139  selectionHandleMarkerImageLeft    | SELECTION_HANDLE_MARKER_IMAGE_LEFT   |  MAP         | O            | X
 140  selectionHandleMarkerImageRight   | SELECTION_HANDLE_MARKER_IMAGE_RIGHT  |  MAP         | O            | X
 141  selectionHighlightColor           | SELECTION_HIGHLIGHT_COLOR            |  VECTOR4     | O            | X
 142  decorationBoundingBox             | DECORATION_BOUNDING_BOX              |  RECTANGLE   | O            | X
 143  inputMethodSettings               | INPUT_METHOD_SETTINGS                |  MAP         | O            | X
 144  inputColor                        | INPUT_COLOR                          |  VECTOR4     | O            | X
 145  enableMarkup                      | ENABLE_MARKUP                        |  BOOLEAN     | O            | X
 146  inputFontFamily                   | INPUT_FONT_FAMILY                    |  STRING      | O            | X
 147  inputFontStyle                    | INPUT_FONT_STYLE                     |  STRING      | O            | X
 148  inputPointSize                    | INPUT_POINT_SIZE                     |  FLOAT       | O            | X
 149  underline                         | UNDERLINE                            |  STRING      | O            | X
 150  inputUnderline                    | INPUT_UNDERLINE                      |  STRING      | O            | X
 151  shadow                            | SHADOW                               |  STRING      | O            | X
 152  inputShadow                       | INPUT_SHADOW                         |  STRING      | O            | X
 153  emboss                            | EMBOSS                               |  STRING      | O            | X
 154  inputEmboss                       | INPUT_EMBOSS                         |  STRING      | O            | X
 155  outline                           | OUTLINE                              |  STRING      | O            | X
 156  inputOutline                      | INPUT_OUTLINE                        |  STRING      | O            | X
 157
 158 @class TextField
 159
 160 */