TextField and TextArea

TextField is a great way to get String input from the user like any typical form. Traversing from field to field with the tab key works and it can be set to behave like a password field as well. TextArea is the multi-line sibling to TextField.

TextFieldStyle

TextFields require a font and a "fontColor" to represent the text that the user types. There is also a separate field called "messageFont". Consider this a way to show hint text in the TextField when the user hasn't entered anything into the box. Typically, you'll choose a light color for the "messageFontColor" and a darker, more vivid color for the "fontColor". For these colors to really look the way they're supposed to, make sure the font bitmap is colored white.

You should set a background to represent the box for the TextField. Users often associate white boxes with a dark outline as something you can type in. Make sure to accommodate for some padding to ensure that the text doesn't seem squished against the border in your NinePatch.

When the user clicks in your TextField, this sets the Stage's keyboard focus to the widget and activates the "focusedBackground". This can have a brighter border to make it stand out from the rest of the fields in your scene. Or you can simply not specify it and it will always show the default Drawable background. Another optional background is the "disabledBackground". This is usually a washed out, gray fill to indicate that the field can not be typed in. Don't forget to also set corresponding colors for "focusedFontColor" and "disabledFontColor".

The "cursor" field represents the insertion point that shows the user's place in the text. This works best with a single pixel width line. The height will automatically adjust to the height of the font. You can experiment with different sized cursors, though it will be challenging to get it to be placed exactly where you want it to go.

To indicate what characters the user has highlighted, you need to specify the "selection" field. This is drawn behind the text, so you can feel free to use an opaque drawable. A 1x1 pixel of a vibrant color that contrasts with the background and the text is usually enough unless you want to draw something ornate.

TextFieldStyle can be applied to both TextField and TextArea. You just have to make sure that your TextField Drawable can be stretched horizontally and vertically.

Layout

This is a TextField.

TextField textField = new TextField("", skin);
root.add(textField);

Using TextArea is nearly identical, however you can input more than single line of text. You can specify how many lines are visible by default.

TextArea textArea = new TextArea("", skin);
textArea.setPrefRows(5);
root.add(textArea);

TextFields have a default preferred width of 150. Make sure to specify a width if you want a different size.

TextField textField = new TextField("", skin);
root.add(textField).width(300);

You can select text in a TextField programatically, but you won't be able to see it unless the keyboard focus is set.

TextField textField = new TextField("Text needs to be selected in this sentence.", skin);
textField.setSelection(17, 25);
root.add(textField).growX();
stage.setKeyboardFocus(textField);

Password mode hides the text you type with a character of your choosing. This is usually the asterisk or the bullet symbol if you chose to add that to your font's supported characters.

TextField textField = new TextField("", skin);
textField.setPasswordCharacter('*');
textField.setPasswordMode(true);
root.add(textField).width(300);

TextFields are automatically programmed to traverse to the next field to the right and below. If you don't like this order, you can override this functionality.

private Array<TextField> textFields = new Array<>();
private int index;

@Override
public void create () {
    ...
    TextField one = new TextField("", skin) {
        @Override
        public void next(boolean up) {
            nextTextField(up);
        }
    };
    root.add(one);

    TextField four = new TextField("", skin) {
        @Override
        public void next(boolean up) {
            nextTextField(up);
        }
    };
    root.add(four);
    
    root.row();
    TextField two = new TextField("", skin) {
        @Override
        public void next(boolean up) {
            nextTextField(up);
        }
    };
    root.add(two);
    
    root.row();
    TextField three = new TextField("", skin) {
        @Override
        public void next(boolean up) {
            nextTextField(up);
        }
    };
    root.add(three);

    textFields.add(one);
    textFields.add(two);
    textFields.add(three);
    textFields.add(four);
}

private void nextTextField(boolean up) {
    if (up) {
        index--;
        if (index < 0) index = textFields.size - 1;
    } else {
        index++;
        if (index == textFields.size) index = 0;
    }
    stage.setKeyboardFocus(textFields.get(index));
}

You can simply disable focusTraversal if you don't need it.

TextField textField = new TextField("text", skin);
textField.setFocusTraversal(false);
root.add(textField);

Further Steps

Continuing on the focus with font based widgets, proceed learning with chapter 05 - Tree and List or return to the table of contents.