A single-line text field.
Functionality
A TextField provides a way to get single-line text input from a user. It supports scrolling based on the cursor position, selection via holding down the shift-key (desktop-only), and copy & paste (desktop only).
Copy & Paste
The TextField will copy the currently selected text when ctrl + c is pressed, and paste any text in the clipboard when ctrl + v is pressed. Clipboard functionality is provided via the {@link Clipboard} interface. Currently thereare two standard implementations, one for the desktop and one for Android. The later is a stub, as copy & pasting on Android is not supported yet. To set your own Clipboard implementation use the {@link #setClipboard(Clipboard)} method.
On-Screen Keyboard
The TextField allows you to specify an {@link OnscreenKeyboard} implementation responsible fordisplaying a softkeyboard and piping all key events generated by the keyboard to the TextField. There are two standard implementations, one for the desktop and one for Android. The former is a stub, as a softkeyboard is not needed on the desktop. The Android {@link OnscreenKeyboard} implementation will bring up the default IME. If you want to set your own{@link OnscreenKeyboard} for a TextField use the {@link #setOnscreenKeyboard(OnscreenKeyboard)} method. The OnscreenKeyboardallows you to dynamically show and hide it, e.g. based on a key event for the return key.
Listening to Key Events To listen to TextField events one can register a {@link TextFieldListener}. This listener will be invoked after a new character was added or removed to and from the TextField. This allows you to perform input checks or dynamically hide the OnscreenKeyboard. Layout
The (preferred) width and height of a TextField are derrived from the width given at construction time as well as the combination of the used font's height and the top and bottom border patches. Use {@link Button#setPrefSize(int,int)} toprogrammatically change the size to your liking. In case the width and height you set are to small for the contained text, the TextField will clip the characters based on the current cursor position. Style
A TextField is a {@link Widget} displaying a background {@link NinePatch}, the current text via a {@link BitmapFont} and{@link Color}, a cursor via a {@link NinePatch} as well as the current selection via a {@link TextureRegion} that is stretchedover the entire selection. The style is defined via an instance of {@link TextFieldStyle}, which can be either done programmatically or via a {@link Skin}. A TextField's style definition in a skin XML file should look like this: {@code } - The
name attribute defines the name of the style which you can later use with {@link Skin#newTextField(String,float,String)}. - The
font attribute references a {@link BitmapFont} by name, to be used to render the text in the text field - The
fontColor attribute references a {@link Color} by name, to be used to render the text on the text field - The
cursorPatch attribute references a {@link NinePatch} by name, to be used to render the text field's cursor - The
selectionRegion attribute references a {@link TextureRegion} by name, to be used to highlight the textfield's selection - The
backgroundPatch attribute references a {@link NinePatch} by name, to be used as the text field'sbackground
@author mzechner