libgdx API

com.badlogic.gdx.scenes.scene2d.ui
Class TextField

java.lang.Object
  extended by com.badlogic.gdx.scenes.scene2d.Actor
      extended by com.badlogic.gdx.scenes.scene2d.ui.Widget
          extended by com.badlogic.gdx.scenes.scene2d.ui.TextField
All Implemented Interfaces:
Layout

public class TextField
extends Widget

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 Clipboard interface. Currently there are 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 setClipboard(Clipboard) method.

On-Screen Keyboard

The TextField allows you to specify an TextField.OnscreenKeyboard implementation responsible for displaying 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 TextField.OnscreenKeyboard implementation will bring up the default IME. If you want to set your own TextField.OnscreenKeyboard for a TextField use the setOnscreenKeyboard(OnscreenKeyboard) method. The OnscreenKeyboard allows 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 TextField.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 Button#setPrefSize(int, int) to programmatically 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 Widget displaying a background NinePatch, the current text via a BitmapFont and Color, a cursor via a NinePatch as well as the current selection via a TextureRegion that is stretched over the entire selection. The style is defined via an instance of TextField.TextFieldStyle, which can be either done programmatically or via a Skin.

A TextField's style definition in a skin XML file should look like this:
 <textfield name="name" 
            font="fontName" 
            fontColor="fontColor" 
            cursor="cursorPatch" 
            selection="selectionRegion" 
            background="backgroundPatch"/>
 
 

Author:
mzechner

Nested Class Summary
static class TextField.DefaultOnscreenKeyboard
          The default TextField.OnscreenKeyboard used by all TextField instances.
static interface TextField.OnscreenKeyboard
          An interface for onscreen keyboards.
static interface TextField.TextFieldListener
          Interface for listening to typed characters.
static class TextField.TextFieldStyle
          Defines a text field's style, see TextField
 
Field Summary
 
Fields inherited from class com.badlogic.gdx.scenes.scene2d.ui.Widget
invalidated
 
Fields inherited from class com.badlogic.gdx.scenes.scene2d.Actor
actions, color, height, name, originX, originY, parent, rotation, scaleX, scaleY, touchable, visible, width, x, y
 
Constructor Summary
TextField(Skin skin)
           
TextField(java.lang.String text, Skin skin)
           
TextField(java.lang.String text, TextField.TextFieldStyle style)
           
TextField(java.lang.String text, TextField.TextFieldStyle style, java.lang.String name)
          Creates a new Textfield.
TextField(TextField.TextFieldStyle style)
           
 
Method Summary
 void draw(SpriteBatch batch, float parentAlpha)
          Draws the Actor.
 TextField.OnscreenKeyboard getOnscreenKeyboard()
          Returns the currently used TextField.OnscreenKeyboard.
 float getPrefHeight()
           
 float getPrefWidth()
           
 java.lang.String getText()
           
 Actor hit(float x, float y)
           
 boolean keyDown(int keycode)
           
 boolean keyTyped(char character)
           
 void layout()
          Positions and sizes each child of this actor.
 void setClipboard(Clipboard clipboard)
          Sets the Clipboard implementation this TextField uses.
 void setOnscreenKeyboard(TextField.OnscreenKeyboard keyboard)
          Sets the TextField.OnscreenKeyboard to be used by this textfield
 void setStyle(TextField.TextFieldStyle style)
          Sets the style of this widget.
 void setText(java.lang.String text)
          Sets the text of this text field.
 void setTextFieldListener(TextField.TextFieldListener listener)
          Sets the TextField.TextFieldListener
 boolean touchDown(float x, float y, int pointer)
           
 void touchDragged(float x, float y, int pointer)
           
 void touchUp(float x, float y, int pointer)
           
 
Methods inherited from class com.badlogic.gdx.scenes.scene2d.ui.Widget
getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, invalidate, invalidateHierarchy
 
Methods inherited from class com.badlogic.gdx.scenes.scene2d.Actor
act, action, clearActions, isMarkedToRemove, keyUp, markToRemove, remove, scrolled, toLocalCoordinates, toString, touchMoved
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

TextField

public TextField(Skin skin)

TextField

public TextField(java.lang.String text,
                 Skin skin)

TextField

public TextField(TextField.TextFieldStyle style)

TextField

public TextField(java.lang.String text,
                 TextField.TextFieldStyle style)

TextField

public TextField(java.lang.String text,
                 TextField.TextFieldStyle style,
                 java.lang.String name)
Creates a new Textfield. The width is determined by the prefWidth parameter, the height is determined by the font's height as well as the top and bottom border patches of the text fields background.

Parameters:
style - the TextField.TextFieldStyle
prefWidth - the (preferred) width
name - the name
Method Detail

setStyle

public void setStyle(TextField.TextFieldStyle style)
Sets the style of this widget.

Parameters:
style -

layout

public void layout()
Description copied from interface: Layout
Positions and sizes each child of this actor. Subsequent calls will not have any affect unless Layout.invalidate() is called.


draw

public void draw(SpriteBatch batch,
                 float parentAlpha)
Description copied from class: Actor
Draws the Actor. The spriteBatch is configured so that the Actor can draw in its parents coordinate system. The parent's alpha is passed to the method in order for the Actor to multiply it with its own alpha. This will allow FadeIn and other Actions to have an effect even if they are only set on the parent of the Actor.

Specified by:
draw in class Actor
Parameters:
batch - the spritebatch to render with
parentAlpha - the parent's alpha value.

touchDown

public boolean touchDown(float x,
                         float y,
                         int pointer)
Specified by:
touchDown in class Actor

touchUp

public void touchUp(float x,
                    float y,
                    int pointer)
Specified by:
touchUp in class Actor

touchDragged

public void touchDragged(float x,
                         float y,
                         int pointer)
Specified by:
touchDragged in class Actor

keyDown

public boolean keyDown(int keycode)
Overrides:
keyDown in class Actor

keyTyped

public boolean keyTyped(char character)
Overrides:
keyTyped in class Actor

hit

public Actor hit(float x,
                 float y)
Overrides:
hit in class Widget

setTextFieldListener

public void setTextFieldListener(TextField.TextFieldListener listener)
Sets the TextField.TextFieldListener

Parameters:
listener - the listener or null

setText

public void setText(java.lang.String text)
Sets the text of this text field.

Parameters:
text - the text

getText

public java.lang.String getText()
Returns:
the text of this text field. Never null, might be an empty string.

getPrefWidth

public float getPrefWidth()

getPrefHeight

public float getPrefHeight()

getOnscreenKeyboard

public TextField.OnscreenKeyboard getOnscreenKeyboard()
Returns the currently used TextField.OnscreenKeyboard. TextField instances use the TextField.DefaultOnscreenKeyboard by default.

Returns:
the OnscreenKeyboard.

setOnscreenKeyboard

public void setOnscreenKeyboard(TextField.OnscreenKeyboard keyboard)
Sets the TextField.OnscreenKeyboard to be used by this textfield

Parameters:
keyboard - the OnscreenKeyboard

setClipboard

public void setClipboard(Clipboard clipboard)
Sets the Clipboard implementation this TextField uses.

Parameters:
clipboard - the Clipboard

libgdx API

Copyright 2010 Mario Zechner (contact@badlogicgames.com), Nathan Sweet (admin@esotericsoftware.com)