Package com.github.tommyettinger.textra

Class TextraField

java.lang.Object
com.badlogic.gdx.scenes.scene2d.Actor
com.badlogic.gdx.scenes.scene2d.ui.Widget
com.github.tommyettinger.textra.TextraField
All Implemented Interfaces:
com.badlogic.gdx.scenes.scene2d.utils.Disableable, com.badlogic.gdx.scenes.scene2d.utils.Layout
public class TextraField
extends com.badlogic.gdx.scenes.scene2d.ui.Widget
implements com.badlogic.gdx.scenes.scene2d.utils.Disableable
A single-line text input field.
This class is alpha-quality at best right now! You should try alternatives instead of using TextraField:
When you want text entry, you should use a TextField with a BitmapFont that has its BitmapFont.BitmapFontData.markupEnabled set to false.
If you just want a span of read-only text that can be selected and copied, then use a TypingLabel with selectable set to true, use a TypingListener that checks for the event "*SELECTED", and call TypingLabel.copySelectedText() when the user requests.
NONE OF THE REST OF THIS IS ACCURATE YET.
The preferred height of a text field is the height of the TextField.TextFieldStyle.font and TextField.TextFieldStyle.background. The preferred width of a text field is 150, a relatively arbitrary size.

The text field 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 Android clipboard is a stub, as copy & pasting on Android is not supported yet.

The text field allows you to specify an TextraField.OnscreenKeyboard for displaying a softkeyboard and piping all key events generated by the keyboard to the text field. There are two standard implementations, one for the desktop and one for Android. The desktop keyboard is a stub, as a softkeyboard is not needed on the desktop. The Android TextraField.OnscreenKeyboard implementation will bring up the default IME.

  • Nested Class Summary

    Nested Classes
    Modifier and Type Class Description
    static class  TextraField.DefaultOnscreenKeyboard
    The default TextraField.OnscreenKeyboard used by all TextraField instances.
    static interface  TextraField.OnscreenKeyboard
    An interface for onscreen keyboards.
    class  TextraField.TextFieldClickListener
    Basic input listener for the text field
    static interface  TextraField.TextFieldFilter
    Interface for filtering characters entered into the text field.
    static interface  TextraField.TextFieldListener
    Interface for listening to typed characters.

  • Field Summary

    Fields
    Modifier and Type Field Description
    protected static char BACKSPACE  
    static char BULLET
    Used as the default char to replace content when passwordMode is on.
    protected static char CARRIAGE_RETURN  
    protected int cursor  
    protected static char DELETE  
    protected java.lang.String displayText  
    protected float fontOffset  
    protected com.badlogic.gdx.utils.FloatArray glyphPositions  
    protected boolean hasSelection  
    static float keyRepeatInitialTime  
    static float keyRepeatTime  
    protected TypingLabel label  
    protected static char NEWLINE  
    protected int selectionStart  
    protected static char TAB  
    protected java.lang.String text  
    protected float textOffset  
    protected int visibleTextEnd  
    protected int visibleTextStart  
    protected boolean writeEnters  

  • Constructor Summary

    Constructors
    Constructor Description
    TextraField​(java.lang.String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin)  
    TextraField​(java.lang.String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, java.lang.String styleName)  
    TextraField​(java.lang.String text, com.badlogic.gdx.scenes.scene2d.ui.TextField.TextFieldStyle style)  
    TextraField​(java.lang.String text, com.badlogic.gdx.scenes.scene2d.ui.TextField.TextFieldStyle style, Font replacementFont)  

  • Method Summary

    Modifier and Type Method Description
    void act​(float delta)  
    void appendText​(java.lang.String str)  
    protected void calculateOffsets()  
    void clearSelection()  
    protected boolean continueCursor​(int index, int offset)  
    void copy()
    Copies the contents of this TextraField to the Clipboard implementation set on this TextraField.
    protected com.badlogic.gdx.scenes.scene2d.InputListener createInputListener()  
    void cut()
    Copies the selected contents of this TextraField to the Clipboard implementation set on this TextraField, then removes it.
    void draw​(com.badlogic.gdx.graphics.g2d.Batch batch, float parentAlpha)  
    protected void drawCursor​(com.badlogic.gdx.scenes.scene2d.utils.Drawable cursorPatch, com.badlogic.gdx.graphics.g2d.Batch batch, Font font, float x, float y)  
    protected void drawSelection​(com.badlogic.gdx.scenes.scene2d.utils.Drawable selection, com.badlogic.gdx.graphics.g2d.Batch batch, Font font, float x, float y)
    Draws selection rectangle
    int getAlignment()  
    protected com.badlogic.gdx.scenes.scene2d.utils.Drawable getBackgroundDrawable()  
    int getCursorPosition()  
    com.badlogic.gdx.scenes.scene2d.InputListener getDefaultInputListener()  
    int getMaxLength()  
    java.lang.String getMessageText()  
    TextraField.OnscreenKeyboard getOnscreenKeyboard()
    Default is an instance of TextraField.DefaultOnscreenKeyboard.
    float getPrefHeight()  
    float getPrefWidth()  
    boolean getProgrammaticChangeEvents()  
    java.lang.String getSelection()  
    int getSelectionStart()  
    com.badlogic.gdx.scenes.scene2d.ui.TextField.TextFieldStyle getStyle()
    Returns the text field's style.
    java.lang.String getText()  
    TextraField.TextFieldFilter getTextFieldFilter()  
    protected float getTextY​(Font font, com.badlogic.gdx.scenes.scene2d.utils.Drawable background)  
    protected void initialize()  
    boolean isDisabled()  
    boolean isPasswordMode()  
    protected boolean isWordCharacter​(char c)  
    protected boolean isWordCharacter​(long glyph)  
    protected void moveCursor​(boolean forward, boolean jump)  
    void next​(boolean up)
    Sets the keyboard focus to the next TextraField.
    protected void positionChanged()  
    void selectAll()  
    void setAlignment​(int alignment)
    Sets text horizontal alignment (left, center or right).
    void setBlinkTime​(float blinkTime)  
    void setClipboard​(com.badlogic.gdx.utils.Clipboard clipboard)  
    void setCursorPosition​(int cursorPosition)
    Sets the cursor position and clears any selection.
    void setDisabled​(boolean disabled)  
    void setFocusTraversal​(boolean focusTraversal)
    If true (the default), tab/shift+tab will move to the next text field.
    void setMaxLength​(int maxLength)  
    void setMessageText​(java.lang.String messageText)
    Sets the text that will be drawn in the text field if no text has been entered.
    void setOnlyFontChars​(boolean onlyFontChars)
    When false, text set by setText(String) may contain characters not in the font, a space will be displayed instead.
    void setOnscreenKeyboard​(TextraField.OnscreenKeyboard keyboard)  
    void setPasswordCharacter​(char passwordCharacter)
    Sets the password character for the text field.
    void setPasswordMode​(boolean passwordMode)
    If true, the text in this text field will be shown as bullet characters.
    void setProgrammaticChangeEvents​(boolean programmaticChangeEvents)
    If false, methods that change the text will not fire ChangeListener.ChangeEvent, the event will be fired only when the user changes the text.
    void setSelection​(int selectionStart, int selectionEnd)
    Sets the selected text.
    void setStyle​(com.badlogic.gdx.scenes.scene2d.ui.TextField.TextFieldStyle style)  
    void setText​(java.lang.String str)  
    void setTextFieldFilter​(TextraField.TextFieldFilter filter)  
    void setTextFieldListener​(TextraField.TextFieldListener listener)  
    protected void sizeChanged()  
    protected long wordUnderCursor()  

    Methods inherited from class com.badlogic.gdx.scenes.scene2d.ui.Widget

    getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, invalidate, invalidateHierarchy, layout, needsLayout, pack, setFillParent, setLayoutEnabled, validate

    Methods inherited from class com.badlogic.gdx.scenes.scene2d.Actor

    addAction, addCaptureListener, addListener, ancestorsVisible, ascendantsVisible, clear, clearActions, clearListeners, clipBegin, clipBegin, clipEnd, debug, drawDebug, drawDebugBounds, fire, firstAscendant, getActions, getCaptureListeners, getColor, getDebug, getHeight, getListeners, getName, getOriginX, getOriginY, getParent, getRight, getRotation, getScaleX, getScaleY, getStage, getTop, getTouchable, getUserObject, getWidth, getX, getX, getY, getY, getZIndex, hasActions, hasKeyboardFocus, hasParent, hasScrollFocus, hit, isAscendantOf, isDescendantOf, isTouchable, isTouchFocusListener, isTouchFocusTarget, isVisible, localToActorCoordinates, localToAscendantCoordinates, localToParentCoordinates, localToScreenCoordinates, localToStageCoordinates, moveBy, notify, parentToLocalCoordinates, remove, removeAction, removeCaptureListener, removeListener, rotateBy, rotationChanged, scaleBy, scaleBy, scaleChanged, screenToLocalCoordinates, setBounds, setColor, setColor, setDebug, setHeight, setName, setOrigin, setOrigin, setOriginX, setOriginY, setParent, setPosition, setPosition, setRotation, setScale, setScale, setScaleX, setScaleY, setSize, setStage, setTouchable, setUserObject, setVisible, setWidth, setX, setX, setY, setY, setZIndex, sizeBy, sizeBy, stageToLocalCoordinates, toBack, toFront, toString

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

    • BACKSPACE

      protected static final char BACKSPACE
      See Also:
      Constant Field Values

    • CARRIAGE_RETURN

      protected static final char CARRIAGE_RETURN
      See Also:
      Constant Field Values

    • NEWLINE

      protected static final char NEWLINE
      See Also:
      Constant Field Values

    • TAB

      protected static final char TAB
      See Also:
      Constant Field Values

    • DELETE

      protected static final char DELETE
      See Also:
      Constant Field Values

    • BULLET

      public static final char BULLET
      Used as the default char to replace content when passwordMode is on.
      See Also:
      Constant Field Values

    • keyRepeatInitialTime

      public static float keyRepeatInitialTime

    • keyRepeatTime

      public static float keyRepeatTime

    • text

      protected java.lang.String text

    • cursor

      protected int cursor

    • selectionStart

      protected int selectionStart

    • hasSelection

      protected boolean hasSelection

    • writeEnters

      protected boolean writeEnters

    • label

      protected final TypingLabel label

    • glyphPositions

      protected final com.badlogic.gdx.utils.FloatArray glyphPositions

    • displayText

      protected java.lang.String displayText

    • fontOffset

      protected float fontOffset

    • textOffset

      protected float textOffset

    • visibleTextStart

      protected int visibleTextStart

    • visibleTextEnd

      protected int visibleTextEnd

  • Constructor Details

    • TextraField

      public TextraField​(@Null java.lang.String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin)

    • TextraField

      public TextraField​(@Null java.lang.String text, com.badlogic.gdx.scenes.scene2d.ui.Skin skin, java.lang.String styleName)

    • TextraField

      public TextraField​(@Null java.lang.String text, com.badlogic.gdx.scenes.scene2d.ui.TextField.TextFieldStyle style)

    • TextraField

      public TextraField​(@Null java.lang.String text, com.badlogic.gdx.scenes.scene2d.ui.TextField.TextFieldStyle style, Font replacementFont)

  • Method Details

    • initialize

      protected void initialize()

    • createInputListener

      protected com.badlogic.gdx.scenes.scene2d.InputListener createInputListener()

    • isWordCharacter

      protected boolean isWordCharacter​(char c)

    • isWordCharacter

      protected boolean isWordCharacter​(long glyph)

    • wordUnderCursor

      protected long wordUnderCursor()

    • setMaxLength

      public void setMaxLength​(int maxLength)

    • getMaxLength

      public int getMaxLength()

    • setOnlyFontChars

      public void setOnlyFontChars​(boolean onlyFontChars)
      When false, text set by setText(String) may contain characters not in the font, a space will be displayed instead. When true (the default), characters not in the font are stripped by setText. Characters not in the font are always stripped when typed or pasted.

    • setStyle

      public void setStyle​(com.badlogic.gdx.scenes.scene2d.ui.TextField.TextFieldStyle style)

    • getStyle

      public com.badlogic.gdx.scenes.scene2d.ui.TextField.TextFieldStyle getStyle()
      Returns the text field's style. Modifying the returned style may not have an effect until setStyle(TextFieldStyle) is called.

    • calculateOffsets

      protected void calculateOffsets()

    • getBackgroundDrawable

      @Null protected com.badlogic.gdx.scenes.scene2d.utils.Drawable getBackgroundDrawable()

    • draw

      public void draw​(com.badlogic.gdx.graphics.g2d.Batch batch, float parentAlpha)
      Overrides:
      draw in class com.badlogic.gdx.scenes.scene2d.ui.Widget

    • getTextY

      protected float getTextY​(Font font, @Null com.badlogic.gdx.scenes.scene2d.utils.Drawable background)

    • drawSelection

      protected void drawSelection​(com.badlogic.gdx.scenes.scene2d.utils.Drawable selection, com.badlogic.gdx.graphics.g2d.Batch batch, Font font, float x, float y)
      Draws selection rectangle

    • drawCursor

      protected void drawCursor​(com.badlogic.gdx.scenes.scene2d.utils.Drawable cursorPatch, com.badlogic.gdx.graphics.g2d.Batch batch, Font font, float x, float y)

    • copy

      public void copy()
      Copies the contents of this TextraField to the Clipboard implementation set on this TextraField.

    • cut

      public void cut()
      Copies the selected contents of this TextraField to the Clipboard implementation set on this TextraField, then removes it.

    • next

      public void next​(boolean up)
      Sets the keyboard focus to the next TextraField. If no next text field is found, the onscreen keyboard is hidden. Does nothing if the text field is not in a stage.
      Parameters:
      up - If true, the text field with the same or next smallest y coordinate is found, else the next highest.

    • getDefaultInputListener

      public com.badlogic.gdx.scenes.scene2d.InputListener getDefaultInputListener()

    • setTextFieldListener

      public void setTextFieldListener​(@Null TextraField.TextFieldListener listener)
      Parameters:
      listener - May be null.

    • setTextFieldFilter

      public void setTextFieldFilter​(@Null TextraField.TextFieldFilter filter)
      Parameters:
      filter - May be null.

    • getTextFieldFilter

      @Null public TextraField.TextFieldFilter getTextFieldFilter()

    • setFocusTraversal

      public void setFocusTraversal​(boolean focusTraversal)
      If true (the default), tab/shift+tab will move to the next text field.

    • getMessageText

      @Null public java.lang.String getMessageText()
      Returns:
      May be null.

    • setMessageText

      public void setMessageText​(@Null java.lang.String messageText)
      Sets the text that will be drawn in the text field if no text has been entered.
      Parameters:
      messageText - may be null.

    • appendText

      public void appendText​(@Null java.lang.String str)
      Parameters:
      str - If null, "" is used.

    • setText

      public void setText​(@Null java.lang.String str)
      Parameters:
      str - If null, "" is used.

    • getText

      public java.lang.String getText()
      Returns:
      Never null, might be an empty string.

    • setProgrammaticChangeEvents

      public void setProgrammaticChangeEvents​(boolean programmaticChangeEvents)
      If false, methods that change the text will not fire ChangeListener.ChangeEvent, the event will be fired only when the user changes the text.

    • getProgrammaticChangeEvents

      public boolean getProgrammaticChangeEvents()

    • getSelectionStart

      public int getSelectionStart()

    • getSelection

      public java.lang.String getSelection()

    • setSelection

      public void setSelection​(int selectionStart, int selectionEnd)
      Sets the selected text.

    • selectAll

      public void selectAll()

    • clearSelection

      public void clearSelection()

    • setCursorPosition

      public void setCursorPosition​(int cursorPosition)
      Sets the cursor position and clears any selection.

    • getCursorPosition

      public int getCursorPosition()

    • getOnscreenKeyboard

      public TextraField.OnscreenKeyboard getOnscreenKeyboard()
      Default is an instance of TextraField.DefaultOnscreenKeyboard.

    • setOnscreenKeyboard

      public void setOnscreenKeyboard​(TextraField.OnscreenKeyboard keyboard)

    • setClipboard

      public void setClipboard​(com.badlogic.gdx.utils.Clipboard clipboard)

    • getPrefWidth

      public float getPrefWidth()
      Specified by:
      getPrefWidth in interface com.badlogic.gdx.scenes.scene2d.utils.Layout
      Overrides:
      getPrefWidth in class com.badlogic.gdx.scenes.scene2d.ui.Widget

    • getPrefHeight

      public float getPrefHeight()
      Specified by:
      getPrefHeight in interface com.badlogic.gdx.scenes.scene2d.utils.Layout
      Overrides:
      getPrefHeight in class com.badlogic.gdx.scenes.scene2d.ui.Widget

    • setAlignment

      public void setAlignment​(int alignment)
      Sets text horizontal alignment (left, center or right).
      See Also:
      Align

    • getAlignment

      public int getAlignment()

    • positionChanged

      protected void positionChanged()
      Overrides:
      positionChanged in class com.badlogic.gdx.scenes.scene2d.Actor

    • sizeChanged

      protected void sizeChanged()
      Overrides:
      sizeChanged in class com.badlogic.gdx.scenes.scene2d.ui.Widget

    • act

      public void act​(float delta)
      Overrides:
      act in class com.badlogic.gdx.scenes.scene2d.Actor

    • setPasswordMode

      public void setPasswordMode​(boolean passwordMode)
      If true, the text in this text field will be shown as bullet characters.
      See Also:
      setPasswordCharacter(char)

    • isPasswordMode

      public boolean isPasswordMode()

    • setPasswordCharacter

      public void setPasswordCharacter​(char passwordCharacter)
      Sets the password character for the text field. If the character is not present in the Font, this does nothing. Default is 8226 (the bullet char • , Unicode 0x2022).

    • setBlinkTime

      public void setBlinkTime​(float blinkTime)

    • setDisabled

      public void setDisabled​(boolean disabled)
      Specified by:
      setDisabled in interface com.badlogic.gdx.scenes.scene2d.utils.Disableable

    • isDisabled

      public boolean isDisabled()
      Specified by:
      isDisabled in interface com.badlogic.gdx.scenes.scene2d.utils.Disableable

    • moveCursor

      protected void moveCursor​(boolean forward, boolean jump)

    • continueCursor

      protected boolean continueCursor​(int index, int offset)