java.lang.Object
com.googlecode.lanterna.gui2.AbstractComponent<TextBox>
com.googlecode.lanterna.gui2.AbstractInteractableComponent<TextBox>
com.googlecode.lanterna.gui2.TextBox
- All Implemented Interfaces:
Component
,Interactable
,TextGUIElement
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-line
TextBox
: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 ClassesModifier and TypeClassDescriptionstatic class
This is the default text box renderer that is used if you don't override anything.static enum
Enum value to force aTextBox
to be either single line or multi line.static interface
Helper interface that doesn't add any new methods but makes coding new text box renderers a little bit more clearstatic interface
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
FieldsModifier and TypeFieldDescriptionprivate TerminalPosition
private boolean
private boolean
private int
private Character
private final int
private boolean
private final TextBox.Style
private TextBox.TextChangeListener
private Pattern
private boolean
-
Constructor Summary
ConstructorsConstructorDescriptionTextBox()
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, String initialContent) Creates a new emptyTextBox
with a specific size and initial contentTextBox
(TerminalSize preferredSize, String initialContent, TextBox.Style style) Main constructor of theTextBox
which decides size, initial content and styleConstructor that creates aTextBox
with an initial content and attempting to be big enough to display the whole text at once without scrollbarsTextBox
(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
Modifier and TypeMethodDescriptionAdds a single line to theTextBox
at the end, this only works when in multi-line modeprivate boolean
private boolean
protected TextBox.TextBoxRenderer
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) 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.getLine
(int index) Returns the line on the specific row.int
Returns the number of lines currently in this TextBox.getMask()
Returns the current text mask, meaning the substitute to draw instead of the text inside theTextBox
.Returns the renderer used to draw this component and measure its preferred size.getText()
Returns the text in thisTextBox
, for multi-line mode all lines will be concatenated together with \n as separator.getTextOrDefault
(String defaultValueIfEmpty) Helper method, it will return the content of theTextBox
unless it's empty in which case it will return the supplied default valuehandleKeyStroke
(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
Checks whether caret warp mode is enabled or not.boolean
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
Returnstrue
if thisTextBox
is in read-only mode, meaning text input from the user through the keyboard is preventedboolean
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
private void
removeLine
(int lineIndex) Removes a line from aTextBox
component.setCaretPosition
(int column) Moves the text caret position horizontally to a new position in theTextBox
.setCaretPosition
(int line, int column) Moves the text caret position to a new position in theTextBox
.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.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.Sets the current text mask, meaning the substitute to draw instead of the text inside theTextBox
.setReadOnly
(boolean readOnly) Sets the read-only mode of theTextBox
, meaning text input from the user through the keyboard is prevented.Updates the text content of theTextBox
to the supplied string.setTextChangeListener
(TextBox.TextChangeListener textChangeListener) Assigns a change listener for when the TextBox content has changed.setValidationPattern
(Pattern validationPattern) Sets a pattern on which the content of the text box is to be validated.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
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 Details
-
lines
-
style
-
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
-
validationPattern
-
textChangeListener
-
-
Constructor Details
-
TextBox
public TextBox()Default constructor, this creates a single-lineTextBox
of size 10 which is initially empty -
TextBox
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
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
Creates a new emptyTextBox
with a specific size- Parameters:
preferredSize
- Size of theTextBox
-
TextBox
Creates a new emptyTextBox
with a specific size and style- Parameters:
preferredSize
- Size of theTextBox
style
- Style to use
-
TextBox
Creates a new emptyTextBox
with a specific size and initial content- Parameters:
preferredSize
- Size of theTextBox
initialContent
- Initial content of theTextBox
-
TextBox
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 Details
-
setValidationPattern
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
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
Updates the text content of theTextBox
to the supplied string.- Parameters:
text
- New text to assign to theTextBox
- Returns:
- Itself
-
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
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
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
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
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
-
setCaretPosition
-
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
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
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
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
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
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
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
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:
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
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
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
-
handleKeyStrokeReadOnly
-
fireOnTextChanged
private void fireOnTextChanged(boolean initiatedByUserInteraction)
-