- java.lang.Object
-
- com.googlecode.lanterna.gui2.AbstractComponent<T>
-
- com.googlecode.lanterna.gui2.AbstractInteractableComponent<TextBox>
-
- com.googlecode.lanterna.gui2.TextBox
-
- All Implemented Interfaces:
Component
,Interactable
,TextGUIElement
public class TextBox extends AbstractInteractableComponent<TextBox>
This component keeps a text content that is editable by the user. A TextBox can be single line or multiline and lets the user navigate the cursor in the text area by using the arrow keys, page up, page down, home and end. For multi-lineTextBox
:es, scrollbars will be automatically displayed if needed.Size-wise, a
TextBox
should be hard-coded to a particular size, it's not good at guessing how large it should be. You can do this through the constructor.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
TextBox.DefaultTextBoxRenderer
This is the default text box renderer that is used if you don't override anything.static class
TextBox.Style
Enum value to force aTextBox
to be either single line or multi line.static interface
TextBox.TextBoxRenderer
Helper interface that doesn't add any new methods but makes coding new text box renderers a little bit more clearstatic interface
TextBox.TextChangeListener
Listener interface for when theTextBox
content has changed.-
Nested classes/interfaces inherited from interface com.googlecode.lanterna.gui2.Interactable
Interactable.FocusChangeDirection, Interactable.Result
-
-
Field Summary
Fields Modifier and Type Field Description private TerminalPosition
caretPosition
private boolean
caretWarp
private boolean
horizontalFocusSwitching
private java.util.List<java.lang.String>
lines
private int
longestRow
private java.lang.Character
mask
private int
maxLineLength
private boolean
readOnly
private TextBox.Style
style
private TextBox.TextChangeListener
textChangeListener
private java.util.regex.Pattern
validationPattern
private boolean
verticalFocusSwitching
-
Constructor Summary
Constructors Constructor Description TextBox()
Default constructor, this creates a single-lineTextBox
of size 10 which is initially emptyTextBox(TerminalSize preferredSize)
Creates a new emptyTextBox
with a specific sizeTextBox(TerminalSize preferredSize, TextBox.Style style)
Creates a new emptyTextBox
with a specific size and styleTextBox(TerminalSize preferredSize, java.lang.String initialContent)
Creates a new emptyTextBox
with a specific size and initial contentTextBox(TerminalSize preferredSize, java.lang.String initialContent, TextBox.Style style)
Main constructor of theTextBox
which decides size, initial content and styleTextBox(java.lang.String initialContent)
Constructor that creates aTextBox
with an initial content and attempting to be big enough to display the whole text at once without scrollbarsTextBox(java.lang.String initialContent, TextBox.Style style)
Creates aTextBox
that has an initial content and attempting to be big enough to display the whole text at once without scrollbars.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description TextBox
addLine(java.lang.String line)
Adds a single line to theTextBox
at the end, this only works when in multi-line modeprivate boolean
canMoveCaretDown()
private boolean
canMoveCaretUp()
protected TextBox.TextBoxRenderer
createDefaultRenderer()
When you create a custom component, you need to implement this method and return a Renderer which is responsible for taking care of sizing the component, rendering it and choosing where to place the cursor (if Interactable).private void
fireOnTextChanged(boolean initiatedByUserInteraction)
TerminalPosition
getCaretPosition()
Returns the position of the caret, as aTerminalPosition
where the row and columns equals the coordinates in a multi-lineTextBox
and for single-lineTextBox
you can ignore therow
component.java.lang.String
getLine(int index)
Returns the line on the specific row.int
getLineCount()
Returns the number of lines currently in this TextBox.java.lang.Character
getMask()
Returns the current text mask, meaning the substitute to draw instead of the text inside theTextBox
.TextBox.TextBoxRenderer
getRenderer()
Returns the renderer used to draw this component and measure its preferred size.java.lang.String
getText()
Returns the text in thisTextBox
, for multi-line mode all lines will be concatenated together with \n as separator.java.lang.String
getTextOrDefault(java.lang.String defaultValueIfEmpty)
Helper method, it will return the content of theTextBox
unless it's empty in which case it will return the supplied default valueInteractable.Result
handleKeyStroke(KeyStroke keyStroke)
This method can be overridden to handle various user input (mostly from the keyboard) when this component is in focus.private Interactable.Result
handleKeyStrokeReadOnly(KeyStroke keyStroke)
boolean
isCaretWarp()
Checks whether caret warp mode is enabled or not.boolean
isHorizontalFocusSwitching()
Iftrue
, the TextBox will switch focus to the next available component to the left if the cursor in the TextBox is at the left-most position (index 0) on the row and the user pressed the 'left' arrow key, or vice versa for pressing the 'right' arrow key when the cursor in at the right-most position of the current row.boolean
isReadOnly()
Returnstrue
if thisTextBox
is in read-only mode, meaning text input from the user through the keyboard is preventedboolean
isVerticalFocusSwitching()
Iftrue
, the component will switch to the next available component above if the cursor is at the top of the TextBox and the user presses the 'up' array key, or switch to the next available component below if the cursor is at the bottom of the TextBox and the user presses the 'down' array key.private void
performMoveCaretDown()
private void
performMoveCaretUp()
TextBox
removeLine(int lineIndex)
Removes a line from aTextBox
component.TextBox
setCaretPosition(int column)
Moves the text caret position horizontally to a new position in theTextBox
.TextBox
setCaretPosition(int line, int column)
Moves the text caret position to a new position in theTextBox
.TextBox
setCaretWarp(boolean caretWarp)
Sets if the caret should jump to the beginning of the next line if right arrow is pressed while at the end of a line.TextBox
setHorizontalFocusSwitching(boolean horizontalFocusSwitching)
If set totrue
, the TextBox will switch focus to the next available component to the left if the cursor in the TextBox is at the left-most position (index 0) on the row and the user pressed the 'left' arrow key, or vice versa for pressing the 'right' arrow key when the cursor in at the right-most position of the current row.TextBox
setMask(java.lang.Character mask)
Sets the current text mask, meaning the substitute to draw instead of the text inside theTextBox
.TextBox
setReadOnly(boolean readOnly)
Sets the read-only mode of theTextBox
, meaning text input from the user through the keyboard is prevented.TextBox
setText(java.lang.String text)
Updates the text content of theTextBox
to the supplied string.TextBox
setTextChangeListener(TextBox.TextChangeListener textChangeListener)
Assigns a change listener for when the TextBox content has changed.TextBox
setValidationPattern(java.util.regex.Pattern validationPattern)
Sets a pattern on which the content of the text box is to be validated.TextBox
setVerticalFocusSwitching(boolean verticalFocusSwitching)
If set totrue
, the component will switch to the next available component above if the cursor is at the top of the TextBox and the user presses the 'up' array key, or switch to the next available component below if the cursor is at the bottom of the TextBox and the user presses the 'down' array key.private boolean
validated(java.lang.String line)
-
Methods inherited from class com.googlecode.lanterna.gui2.AbstractInteractableComponent
afterEnterFocus, afterLeaveFocus, getCursorLocation, getInputFilter, handleInput, isActivationStroke, isEnabled, isFocusable, isFocused, isKeyboardActivationStroke, isMouseActivationStroke, isMouseDown, isMouseDrag, isMouseMove, isMouseUp, onEnterFocus, onLeaveFocus, setEnabled, setInputFilter, takeFocus
-
Methods inherited from class com.googlecode.lanterna.gui2.AbstractComponent
addTo, calculatePreferredSize, draw, getBasePane, getGlobalPosition, getLayoutData, getParent, getPosition, getPreferredSize, getSize, getTextGUI, getTheme, getThemeDefinition, hasParent, invalidate, isInside, isInvalid, isVisible, onAdded, onAfterDrawing, onBeforeDrawing, onRemoved, runOnGUIThreadIfExistsOtherwiseRunDirect, self, setLayoutData, setPosition, setPreferredSize, setRenderer, setSize, setTheme, setVisible, toBasePane, toGlobal, withBorder
-
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
-
Methods inherited from interface com.googlecode.lanterna.gui2.Component
addTo, getBasePane, getGlobalPosition, getLayoutData, getParent, getPosition, getPreferredSize, getSize, getTextGUI, getTheme, getThemeDefinition, hasParent, invalidate, isInside, isVisible, onAdded, onRemoved, setLayoutData, setPosition, setPreferredSize, setSize, setTheme, setVisible, toBasePane, toGlobal, withBorder
-
Methods inherited from interface com.googlecode.lanterna.gui2.TextGUIElement
draw, isInvalid
-
-
-
-
Field Detail
-
lines
private final java.util.List<java.lang.String> lines
-
style
private final TextBox.Style style
-
caretPosition
private TerminalPosition caretPosition
-
caretWarp
private boolean caretWarp
-
readOnly
private boolean readOnly
-
horizontalFocusSwitching
private boolean horizontalFocusSwitching
-
verticalFocusSwitching
private boolean verticalFocusSwitching
-
maxLineLength
private final int maxLineLength
-
longestRow
private int longestRow
-
mask
private java.lang.Character mask
-
validationPattern
private java.util.regex.Pattern validationPattern
-
textChangeListener
private TextBox.TextChangeListener textChangeListener
-
-
Constructor Detail
-
TextBox
public TextBox()
Default constructor, this creates a single-lineTextBox
of size 10 which is initially empty
-
TextBox
public TextBox(java.lang.String initialContent)
Constructor that creates aTextBox
with an initial content and attempting to be big enough to display the whole text at once without scrollbars- Parameters:
initialContent
- Initial content of theTextBox
-
TextBox
public TextBox(java.lang.String initialContent, TextBox.Style style)
Creates aTextBox
that has an initial content and attempting to be big enough to display the whole text at once without scrollbars.- Parameters:
initialContent
- Initial content of theTextBox
style
- Forced style instead of auto-detecting
-
TextBox
public TextBox(TerminalSize preferredSize)
Creates a new emptyTextBox
with a specific size- Parameters:
preferredSize
- Size of theTextBox
-
TextBox
public TextBox(TerminalSize preferredSize, TextBox.Style style)
Creates a new emptyTextBox
with a specific size and style- Parameters:
preferredSize
- Size of theTextBox
style
- Style to use
-
TextBox
public TextBox(TerminalSize preferredSize, java.lang.String initialContent)
Creates a new emptyTextBox
with a specific size and initial content- Parameters:
preferredSize
- Size of theTextBox
initialContent
- Initial content of theTextBox
-
TextBox
public TextBox(TerminalSize preferredSize, java.lang.String initialContent, TextBox.Style style)
Main constructor of theTextBox
which decides size, initial content and style- Parameters:
preferredSize
- Size of theTextBox
initialContent
- Initial content of theTextBox
style
- Style to use for thisTextBox
, instead of auto-detecting
-
-
Method Detail
-
setValidationPattern
public TextBox setValidationPattern(java.util.regex.Pattern validationPattern)
Sets a pattern on which the content of the text box is to be validated. For multi-line TextBox:s, the pattern is checked against each line individually, not the content as a whole. Partial matchings will not be allowed, the whole pattern must match, however, empty lines will always be allowed. When the user tried to modify the content of the TextBox in a way that does not match the pattern, the operation will be silently ignored. If you set this pattern tonull
, all validation is turned off.- Parameters:
validationPattern
- Pattern to validate the lines in this TextBox against, ornull
to disable- Returns:
- itself
-
setTextChangeListener
public TextBox setTextChangeListener(TextBox.TextChangeListener textChangeListener)
Assigns a change listener for when the TextBox content has changed. This can be either by user interactions with the component or through programmatically adding and removing lines (there is a flag set on the callback to make it possible to distinguish between the two).- Parameters:
textChangeListener
- Text change listener to invoke when the TextBox content has changed- Returns:
- Itself
-
setText
public TextBox setText(java.lang.String text)
Updates the text content of theTextBox
to the supplied string.- Parameters:
text
- New text to assign to theTextBox
- Returns:
- Itself
-
getRenderer
public TextBox.TextBoxRenderer getRenderer()
Description copied from interface:Component
Returns the renderer used to draw this component and measure its preferred size. You probably won't need to call this method unless you know exactly which ComponentRenderer implementation is used and you need to customize it.- Specified by:
getRenderer
in interfaceComponent
- Overrides:
getRenderer
in classAbstractInteractableComponent<TextBox>
- Returns:
- Renderer this component is using
-
addLine
public TextBox addLine(java.lang.String line)
Adds a single line to theTextBox
at the end, this only works when in multi-line mode- Parameters:
line
- Line to add at the end of the content in thisTextBox
- Returns:
- Itself
-
removeLine
public TextBox removeLine(int lineIndex)
Removes a line from aTextBox
component. If the component is single-line, they only valid call to this method isremoveLine(0)
which has the same effect as callingsetText("")
. For multi-line text boxes, the line at the specified index will be removed. Will throwArrayIndexOutOfBoundsException
if you specified an incorrect index.- Parameters:
lineIndex
- Index of the line to remove, has to be 0 or greater and less than the number of lines in the text box- Returns:
- Itself
-
setCaretWarp
public TextBox setCaretWarp(boolean caretWarp)
Sets if the caret should jump to the beginning of the next line if right arrow is pressed while at the end of a line. Similarly, pressing left arrow at the beginning of a line will make the caret jump to the end of the previous line. This only makes sense for multi-line TextBox:es; for single-line ones it has no effect. By default this isfalse
.- Parameters:
caretWarp
- Whether the caret will warp at the beginning/end of lines- Returns:
- Itself
-
isCaretWarp
public boolean isCaretWarp()
Checks whether caret warp mode is enabled or not. SeesetCaretWarp
for more details.- Returns:
true
if caret warp mode is enabled
-
getCaretPosition
public TerminalPosition getCaretPosition()
Returns the position of the caret, as aTerminalPosition
where the row and columns equals the coordinates in a multi-lineTextBox
and for single-lineTextBox
you can ignore therow
component.- Returns:
- Position of the text input caret
-
setCaretPosition
public TextBox setCaretPosition(int column)
-
setCaretPosition
public TextBox setCaretPosition(int line, int column)
-
getText
public java.lang.String getText()
Returns the text in thisTextBox
, for multi-line mode all lines will be concatenated together with \n as separator.- Returns:
- The text inside this
TextBox
-
getTextOrDefault
public java.lang.String getTextOrDefault(java.lang.String defaultValueIfEmpty)
Helper method, it will return the content of theTextBox
unless it's empty in which case it will return the supplied default value- Parameters:
defaultValueIfEmpty
- Value to return if theTextBox
is empty- Returns:
- Text in the
TextBox
ordefaultValueIfEmpty
is theTextBox
is empty
-
getMask
public java.lang.Character getMask()
Returns the current text mask, meaning the substitute to draw instead of the text inside theTextBox
. This is normally used for password input fields so the password isn't shown- Returns:
- Current text mask or
null
if there is no mask
-
setMask
public TextBox setMask(java.lang.Character mask)
Sets the current text mask, meaning the substitute to draw instead of the text inside theTextBox
. This is normally used for password input fields so the password isn't shown- Parameters:
mask
- New text mask ornull
if there is no mask- Returns:
- Itself
-
isReadOnly
public boolean isReadOnly()
Returnstrue
if thisTextBox
is in read-only mode, meaning text input from the user through the keyboard is prevented- Returns:
true
if thisTextBox
is in read-only mode
-
setReadOnly
public TextBox setReadOnly(boolean readOnly)
Sets the read-only mode of theTextBox
, meaning text input from the user through the keyboard is prevented. The user can still focus and scroll through the text in this mode.- Parameters:
readOnly
- Iftrue
then theTextBox
will switch to read-only mode- Returns:
- Itself
-
isVerticalFocusSwitching
public boolean isVerticalFocusSwitching()
Iftrue
, the component will switch to the next available component above if the cursor is at the top of the TextBox and the user presses the 'up' array key, or switch to the next available component below if the cursor is at the bottom of the TextBox and the user presses the 'down' array key. The means that for single-line TextBox:es, pressing up and down will always switch focus.- Returns:
true
if vertical focus switching is enabled
-
setVerticalFocusSwitching
public TextBox setVerticalFocusSwitching(boolean verticalFocusSwitching)
If set totrue
, the component will switch to the next available component above if the cursor is at the top of the TextBox and the user presses the 'up' array key, or switch to the next available component below if the cursor is at the bottom of the TextBox and the user presses the 'down' array key. The means that for single-line TextBox:es, pressing up and down will always switch focus with this mode enabled.- Parameters:
verticalFocusSwitching
- If called with true, vertical focus switching will be enabled- Returns:
- Itself
-
isHorizontalFocusSwitching
public boolean isHorizontalFocusSwitching()
Iftrue
, the TextBox will switch focus to the next available component to the left if the cursor in the TextBox is at the left-most position (index 0) on the row and the user pressed the 'left' arrow key, or vice versa for pressing the 'right' arrow key when the cursor in at the right-most position of the current row.- Returns:
true
if horizontal focus switching is enabled
-
setHorizontalFocusSwitching
public TextBox setHorizontalFocusSwitching(boolean horizontalFocusSwitching)
If set totrue
, the TextBox will switch focus to the next available component to the left if the cursor in the TextBox is at the left-most position (index 0) on the row and the user pressed the 'left' arrow key, or vice versa for pressing the 'right' arrow key when the cursor in at the right-most position of the current row.- Parameters:
horizontalFocusSwitching
- If called with true, horizontal focus switching will be enabled- Returns:
- Itself
-
getLine
public java.lang.String getLine(int index)
Returns the line on the specific row. For non-multiline TextBox:es, calling this with index set to 0 will return the same as callinggetText()
. If the row index is invalid (less than zero or equals or larger than the number of rows), this method will throw IndexOutOfBoundsException.- Parameters:
index
- Index of the row to return the contents from- Returns:
- The line at the specified index, as a String
- Throws:
java.lang.IndexOutOfBoundsException
- if the row index is less than zero or too large
-
getLineCount
public int getLineCount()
Returns the number of lines currently in this TextBox. For single-line TextBox:es, this will always return 1.- Returns:
- Number of lines of text currently in this TextBox
-
createDefaultRenderer
protected TextBox.TextBoxRenderer createDefaultRenderer()
Description copied from class:AbstractComponent
When you create a custom component, you need to implement this method and return a Renderer which is responsible for taking care of sizing the component, rendering it and choosing where to place the cursor (if Interactable). This value is intended to be overridden by custom themes.- Specified by:
createDefaultRenderer
in classAbstractInteractableComponent<TextBox>
- Returns:
- Renderer to use when sizing and drawing this component
-
handleKeyStroke
public Interactable.Result handleKeyStroke(KeyStroke keyStroke)
Description copied from class:AbstractInteractableComponent
This method can be overridden to handle various user input (mostly from the keyboard) when this component is in focus. The input method from the interface,handleInput(..)
is final inAbstractInteractableComponent
to ensure the input filter is properly handled. If the filter decides that this event should be processed, it will call this method.- Overrides:
handleKeyStroke
in classAbstractInteractableComponent<TextBox>
- Parameters:
keyStroke
- What input was entered by the user- Returns:
- Result of processing the key-stroke
-
canMoveCaretUp
private boolean canMoveCaretUp()
-
canMoveCaretDown
private boolean canMoveCaretDown()
-
performMoveCaretUp
private void performMoveCaretUp()
-
performMoveCaretDown
private void performMoveCaretDown()
-
validated
private boolean validated(java.lang.String line)
-
handleKeyStrokeReadOnly
private Interactable.Result handleKeyStrokeReadOnly(KeyStroke keyStroke)
-
fireOnTextChanged
private void fireOnTextChanged(boolean initiatedByUserInteraction)
-
-