- java.lang.Object
-
- com.googlecode.lanterna.screen.AbstractScreen
-
- com.googlecode.lanterna.screen.TerminalScreen
-
- All Implemented Interfaces:
Scrollable
,InputProvider
,Screen
,java.io.Closeable
,java.lang.AutoCloseable
public class TerminalScreen extends AbstractScreen
This is the default concrete implementation of the Screen interface, a buffered layer sitting on top of a Terminal. If you want to get started with the Screen layer, this is probably the class you want to use. Remember to start the screen before you can use it and stop it when you are done with it. This will place the terminal in private mode during the screen operations and leave private mode afterwards.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
TerminalScreen.ScreenPointComparator
private static class
TerminalScreen.ScrollHint
private class
TerminalScreen.TerminalScreenResizeListener
-
Nested classes/interfaces inherited from interface com.googlecode.lanterna.screen.Screen
Screen.RefreshType
-
-
Field Summary
Fields Modifier and Type Field Description private boolean
fullRedrawHint
private boolean
isStarted
private TerminalScreen.ScrollHint
scrollHint
private Terminal
terminal
-
Fields inherited from interface com.googlecode.lanterna.screen.Screen
DEFAULT_CHARACTER
-
-
Constructor Summary
Constructors Constructor Description TerminalScreen(Terminal terminal)
Creates a new Screen on top of a supplied terminal, will query the terminal for its size.TerminalScreen(Terminal terminal, TextCharacter defaultCharacter)
Creates a new Screen on top of a supplied terminal, will query the terminal for its size.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
clear()
Erases all the characters on the screen, effectively giving you a blank area.TerminalSize
doResizeIfNecessary()
One problem working with Screens is that whenever the terminal is resized, the front and back buffers needs to be adjusted accordingly and the program should have a chance to figure out what to do with this extra space (or less space).Terminal
getTerminal()
Returns the underlyingTerminal
interface that this Screen is using.KeyStroke
pollInput()
Returns the nextKey
off the input queue or null if there is no more input events available.KeyStroke
readInput()
Returns the nextKey
off the input queue or blocks until one is available.void
refresh(Screen.RefreshType refreshType)
This method will take the content from the back-buffer and move it into the front-buffer, making the changes visible to the terminal in the process.private void
refreshByDelta()
private void
refreshFull()
void
scrollLines(int firstLine, int lastLine, int distance)
Perform the scrolling and save scroll-range and distance in order to be able to optimize Terminal-update later.void
startScreen()
Before you can use a Screen, you need to start it.void
stopScreen()
Calling this method will make the underlying terminal leave private mode, effectively going back to whatever state the terminal was in before callingstartScreen()
.void
stopScreen(boolean flushInput)
private void
useScrollHint()
-
Methods inherited from class com.googlecode.lanterna.screen.AbstractScreen
addResizeRequest, close, getBackBuffer, getBackCharacter, getBackCharacter, getCursorPosition, getFrontBuffer, getFrontCharacter, getFrontCharacter, getTabBehaviour, getTerminalSize, newTextGraphics, refresh, setCharacter, setCharacter, setCursorPosition, setTabBehaviour, toString
-
-
-
-
Field Detail
-
terminal
private final Terminal terminal
-
isStarted
private boolean isStarted
-
fullRedrawHint
private boolean fullRedrawHint
-
scrollHint
private TerminalScreen.ScrollHint scrollHint
-
-
Constructor Detail
-
TerminalScreen
public TerminalScreen(Terminal terminal) throws java.io.IOException
Creates a new Screen on top of a supplied terminal, will query the terminal for its size. The screen is initially blank. The default character used for unused space (the newly initialized state of the screen and new areas after expanding the terminal size) will be a blank space in 'default' ANSI front- and background color.Before you can display the content of this buffered screen to the real underlying terminal, you must call the
startScreen()
method. This will ask the terminal to enter private mode (which is required for Screens to work properly). Similarly, when you are done, you should callstopScreen()
which will exit private mode.- Parameters:
terminal
- Terminal object to create the DefaultScreen on top of- Throws:
java.io.IOException
- If there was an underlying I/O error when querying the size of the terminal
-
TerminalScreen
public TerminalScreen(Terminal terminal, TextCharacter defaultCharacter) throws java.io.IOException
Creates a new Screen on top of a supplied terminal, will query the terminal for its size. The screen is initially blank. The default character used for unused space (the newly initialized state of the screen and new areas after expanding the terminal size) will be a blank space in 'default' ANSI front- and background color.Before you can display the content of this buffered screen to the real underlying terminal, you must call the
startScreen()
method. This will ask the terminal to enter private mode (which is required for Screens to work properly). Similarly, when you are done, you should callstopScreen()
which will exit private mode.- Parameters:
terminal
- Terminal object to create the DefaultScreen on top of.defaultCharacter
- What character to use for the initial state of the screen and expanded areas- Throws:
java.io.IOException
- If there was an underlying I/O error when querying the size of the terminal
-
-
Method Detail
-
startScreen
public void startScreen() throws java.io.IOException
Description copied from interface:Screen
Before you can use a Screen, you need to start it. By starting the screen, Lanterna will make sure the terminal is in private mode (Screen only supports private mode), clears it (so that is can set the front and back buffers to a known value) and places the cursor in the top left corner. After calling startScreen(), you can begin using the other methods on this interface. When you want to exit from the screen and return to what you had before, you can callstopScreen()
.- Throws:
java.io.IOException
- if there was an underlying IO error when exiting from private mode
-
stopScreen
public void stopScreen() throws java.io.IOException
Description copied from interface:Screen
Calling this method will make the underlying terminal leave private mode, effectively going back to whatever state the terminal was in before callingstartScreen()
. Once a screen has been stopped, you can start it again withstartScreen()
which will restore the screens content to the terminal.- Throws:
java.io.IOException
- if there was an underlying IO error when exiting from private mode
-
stopScreen
public void stopScreen(boolean flushInput) throws java.io.IOException
- Throws:
java.io.IOException
-
refresh
public void refresh(Screen.RefreshType refreshType) throws java.io.IOException
Description copied from interface:Screen
This method will take the content from the back-buffer and move it into the front-buffer, making the changes visible to the terminal in the process. The graphics workflow with Screen would involve drawing text and text-like graphics on the back buffer and then finally calling refresh(..) to make it visible to the user.Using this method call instead of
refresh()
gives you a little bit more control over how the screen will be refreshed.- Parameters:
refreshType
- What type of refresh to do- Throws:
java.io.IOException
- If there was an underlying I/O error- See Also:
Screen.RefreshType
-
useScrollHint
private void useScrollHint() throws java.io.IOException
- Throws:
java.io.IOException
-
refreshByDelta
private void refreshByDelta() throws java.io.IOException
- Throws:
java.io.IOException
-
refreshFull
private void refreshFull() throws java.io.IOException
- Throws:
java.io.IOException
-
getTerminal
public Terminal getTerminal()
Returns the underlyingTerminal
interface that this Screen is using.Be aware: directly modifying the underlying terminal will most likely result in unexpected behaviour if you then go on and try to interact with the Screen. The Screen's back-buffer/front-buffer will not know about the operations you are going on the Terminal and won't be able to properly generate a refresh unless you enforce a
Screen.RefreshType.COMPLETE
, at which the entire terminal area will be repainted according to the back-buffer of theScreen
.- Returns:
- Underlying terminal used by the screen
-
readInput
public KeyStroke readInput() throws java.io.IOException
Description copied from interface:InputProvider
Returns the nextKey
off the input queue or blocks until one is available. NOTE: In previous versions of Lanterna, this method was not blocking. From lanterna 3, it is blocking and you can callpollInput()
for the non-blocking version.- Returns:
- Key object which represents a keystroke coming in through the input stream
- Throws:
java.io.IOException
- Propagated error if the underlying stream gave errors
-
pollInput
public KeyStroke pollInput() throws java.io.IOException
Description copied from interface:InputProvider
Returns the nextKey
off the input queue or null if there is no more input events available. Note, this method call is not blocking, it returns null immediately if there is nothing on the input stream.- Returns:
- Key object which represents a keystroke coming in through the input stream
- Throws:
java.io.IOException
- Propagated error if the underlying stream gave errors
-
clear
public void clear()
Description copied from interface:Screen
Erases all the characters on the screen, effectively giving you a blank area. The default background color will be used. This is effectively the same as callingfill(TerminalPosition.TOP_LEFT_CORNER, getSize(), TextColor.ANSI.Default)
.Please note that calling this method will only affect the back buffer, you need to call refresh to make the change visible.
- Specified by:
clear
in interfaceScreen
- Overrides:
clear
in classAbstractScreen
-
doResizeIfNecessary
public TerminalSize doResizeIfNecessary()
Description copied from interface:Screen
One problem working with Screens is that whenever the terminal is resized, the front and back buffers needs to be adjusted accordingly and the program should have a chance to figure out what to do with this extra space (or less space). The solution is to call, at the start of your rendering code, this method, which will check if the terminal has been resized and in that case update the internals of the Screen. After this call finishes, the screen's internal buffers will match the most recent size report from the underlying terminal.- Specified by:
doResizeIfNecessary
in interfaceScreen
- Overrides:
doResizeIfNecessary
in classAbstractScreen
- Returns:
- If the terminal has been resized since this method was last called, it will return the new size of the terminal. If not, it will return null.
-
scrollLines
public void scrollLines(int firstLine, int lastLine, int distance)
Perform the scrolling and save scroll-range and distance in order to be able to optimize Terminal-update later.- Specified by:
scrollLines
in interfaceScreen
- Specified by:
scrollLines
in interfaceScrollable
- Overrides:
scrollLines
in classAbstractScreen
- Parameters:
firstLine
- first line of the range to be scrolled (top line is 0)lastLine
- last (inclusive) line of the range to be scrolleddistance
- if > 0: move lines up, else if < 0: move lines down.
-
-