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 username could initially show "Unknown Name", and then show "Enter Name." when the cursor is shown.
  15
  16 ~~~{.cpp}
  17 // C++
  18
  19 TextField field = TextField::New();
  20 field.SetProperty( TextField::Property::PLACEHOLDER_TEXT, "Unnamed Name" );
  21 field.SetProperty( TextField::Property::PLACEHOLDER_TEXT_FOCUSED, "Enter Name." );
  22
  23 Stage::GetCurrent().Add( field );
  24 ~~~
  25
  26 ~~~{.js}
  27 // JavaScript
  28
  29 var field = new dali.TextField();
  30 field.placeholderText = "Unnamed Name";
  31 field.placeholderTextFocused = "Enter Name.";
  32
  33 dali.stage.add( field );
  34 ~~~
  35
  36 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.
  37 After text has been entered, it can be retrieved from the TEXT property.
  38
  39 ~~~{.cpp}
  40 // C++
  41
  42 Property::Value fieldText = field.GetProperty( TextField::Property::TEXT );
  43 std::cout << "Received text: " << fieldText.Get< std::string >() << std::endl;
  44 ~~~
  45
  46 ~~~{.js}
  47 // JavaScript
  48
  49 console.log( field.text );
  50 ~~~
  51
  52 ### Font Selection
  53
  54 TextField will automatically select a suitable fonts, in the same was as TextLabel.
  55 The preferred font can also be selected from a JSON stylesheet:
  56
  57 ~~~{.json}
  58 {
  59   "styles":
  60   {
  61     "textfield":
  62     {
  63       "font-family":"Arial",
  64       "font-style":"Regular",
  65       "point-size":8
  66     }
  67   }
  68 }
  69 ~~~
  70
  71 ### Text Alignment
  72
  73 TextField displays a single-line of text, which will scroll if there is not enough room for the text displayed.
  74 If there is enough room, then the text can be aligned horizontally to the beginning, end, or center of the available area:
  75
  76 ~~~{.cpp}
  77 // C++
  78
  79 field.SetProperty( TextField::Property::HORIZONTAL_ALIGNMENT, "BEGIN" ); // "CENTER" or "END"
  80 ~~~
  81
  82 ~~~{.js}
  83 // JavaScript
  84
  85 field.HorizontalAlignment = "BEGIN"; // "CENTER" or "END"
  86 ~~~
  87
  88 ### TextField Decorations
  89
  90 #### Color
  91
  92 To change the color of the text, the recommended way is to use the TEXT_COLOR property.
  93 An alternative color can be used for placeholder text by setting PLACEHOLDER_TEXT_COLOR.
  94 Note that unlike the Actor::COLOR property, these properties will not affect child Actors added to the TextField.
  95
  96 ~~~{.cpp}
  97 // C++
  98 field.SetProperty( TextField::Property::TEXT_COLOR, Color::CYAN );
  99 field.SetProperty( TextField::Property::PLACEHOLDER_TEXT_COLOR, Color::BLACK );
 100 ~~~
 101
 102 ~~~{.js}
 103 // JavaScript
 104
 105 field.textColor = dali.COLOR_CYAN;
 106 field.placeholderTextColor = dali.COLOR_BLACK;
 107 ~~~
 108
 109 ### Text Field Properties
 110
 111  Name (JavaScript)                 |  Name (C++)                          |  Type        | Writable     | Animatable
 112 -----------------------------------|--------------------------------------|--------------|--------------|-----------
 113  renderingBackend                  | RENDERING_BACKEND                    |  INTEGER     | O            | X
 114  text                              | TEXT                                 |  STRING      | O            | X
 115  placeholderText                   | PLACEHOLDER_TEXT                     |  STRING      | O            | X
 116  placeholderTextFocused            | PLACEHOLDER_TEXT_FOCUSED             |  STRING      | O            | X
 117  fontFamily                        | FONT_FAMILY                          |  STRING      | O            | X
 118  fontStyle                         | FONT_STYLE                           |  STRING      | O            | X
 119  pointSize                         | POINT_SIZE                           |  FLOAT       | O            | X
 120  maxLength                         | MAX_LENGTH                           |  INTEGER     | O            | X
 121  exceedPolicy                      | EXCEED_POLICY                        |  INTEGER     | O            | X
 122  horizontalAlignment               | HORIZONTAL_ALIGNMENT                 |  STRING      | O            | X
 123  verticalAlignment                 | VERTICAL_ALIGNMENT                   |  STRING      | O            | X
 124  textColor                         | TEXT_COLOR                           |  VECTOR4     | O            | X
 125  shadowOffset                      | SHADOW_OFFSET                        |  VECTOR2     | O            | X
 126  shadowColor                       | SHADOW_COLOR                         |  VECTOR4     | O            | X
 127  primaryCursorColor                | PRIMARY_CURSOR_COLOR                 |  VECTOR4     | O            | X
 128  secondaryCursorColor              | SECONDARY_CURSOR_COLOR               |  VECTOR4     | O            | X
 129  enableCursorBlink                 | ENABLE_CURSOR_BLINK                  |  BOOLEAN     | O            | X
 130  cursorBlinkInterval               | CURSOR_BLINK_INTERVAL                |  FLOAT       | O            | X
 131  cursorBlinkDuration               | CURSOR_BLINK_DURATION                |  FLOAT       | O            | X
 132  grabHandleImage                   | GRAB_HANDLE_IMAGE                    |  STRING      | O            | X
 133  grabHandlePressedImage            | GRAB_HANDLE_PRESSED_IMAGE            |  STRING      | O            | X
 134  scrollThreshold                   | SCROLL_THRESHOLD                     |  FLOAT       | O            | X
 135  scrollSpreed                      | SCROLL_SPEED                         |  FLOAT       | O            | X
 136  selectionHandleImageLeft          | SELECTION_HANDLE_IMAGE_LEFT          |  STRING      | O            | X
 137  selectionHandleImageRight         | SELECTION_HANDLE_IMAGE_RIGHT         |  STRING      | O            | X
 138  selectionHandlePressedImageLeft   | SELECTION_HANDLE_PRESSED_IMAGE_LEFT  |  STRING      | O            | X
 139  selectionHandlePressedImageRight  | SELECTION_HANDLE_PRESSED_IMAGE_RIGHT |  STRING      | O            | X
 140  selectionHighlightColor           | SELECTION_HIGHLIGHT_COLOR            |  VECTOR4     | O            | X
 141  decorationBoundingBox             | DECORATION_BOUNDING_BOX              |  RECTANGLE   | O            | X
 142  inputMethodSettings               | INPUT_METHOD_SETTINGS                |  MAP         | O            | X
 143
 144 @class TextField
 145
 146 */