- java.lang.Object
-
- com.googlecode.lanterna.screen.AbstractScreen
-
- com.googlecode.lanterna.screen.VirtualScreen
-
- All Implemented Interfaces:
Scrollable
,InputProvider
,Screen
,java.io.Closeable
,java.lang.AutoCloseable
public class VirtualScreen extends AbstractScreen
VirtualScreen wraps a normal screen and presents it as a screen that has a configurable minimum size; if the real screen is smaller than this size, the presented screen will add scrolling to get around it. To anyone using this class, it will appear and behave just as a normal screen. Scrolling is done by using CTRL + arrow keys.The use case for this class is to allow you to set a minimum size that you can count on be honored, no matter how small the user makes the terminal. This should make programming GUIs easier.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
VirtualScreen.DefaultFrameRenderer
static interface
VirtualScreen.FrameRenderer
Interface for rendering the virtual screen's frame when the real terminal is too small for the virtual screen-
Nested classes/interfaces inherited from interface com.googlecode.lanterna.screen.Screen
Screen.RefreshType
-
-
Field Summary
Fields Modifier and Type Field Description private VirtualScreen.FrameRenderer
frameRenderer
private TerminalSize
minimumSize
private Screen
realScreen
private TerminalSize
viewportSize
private TerminalPosition
viewportTopLeft
-
Fields inherited from interface com.googlecode.lanterna.screen.Screen
DEFAULT_CHARACTER
-
-
Constructor Summary
Constructors Constructor Description VirtualScreen(Screen screen)
Creates a new VirtualScreen that wraps a supplied Screen.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description private TerminalSize
calculateViewport(TerminalSize realTerminalSize)
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).private KeyStroke
filter(KeyStroke keyStroke)
TextCharacter
getFrontCharacter(TerminalPosition position)
Reads a character and its associated meta-data from the front-buffer and returns it encapsulated as a ScreenCharacter.TerminalSize
getMinimumSize()
Returns the minimum size this virtual screen can have.TerminalSize
getViewportSize()
Returns the current size of the viewport.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.void
scrollLines(int firstLine, int lastLine, int distance)
Performs the scrolling on its back-buffer.void
setCursorPosition(TerminalPosition position)
Moves the current cursor position or hides it.void
setMinimumSize(TerminalSize minimumSize)
Sets the minimum size we want the virtual screen to have.void
setViewportTopLeft(TerminalPosition position)
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()
.-
Methods inherited from class com.googlecode.lanterna.screen.AbstractScreen
addResizeRequest, clear, close, getBackBuffer, getBackCharacter, getBackCharacter, getCursorPosition, getFrontBuffer, getFrontCharacter, getTabBehaviour, getTerminalSize, newTextGraphics, refresh, setCharacter, setCharacter, setTabBehaviour, toString
-
-
-
-
Field Detail
-
realScreen
private final Screen realScreen
-
frameRenderer
private final VirtualScreen.FrameRenderer frameRenderer
-
minimumSize
private TerminalSize minimumSize
-
viewportTopLeft
private TerminalPosition viewportTopLeft
-
viewportSize
private TerminalSize viewportSize
-
-
Constructor Detail
-
VirtualScreen
public VirtualScreen(Screen screen)
Creates a new VirtualScreen that wraps a supplied Screen. The screen passed in here should be the real screen that is created on top of the realTerminal
, it will have the correct size and content for what's actually displayed to the user, but this class will present everything as one view with a fixed minimum size, no matter what size the real terminal has.The initial minimum size will be the current size of the screen.
- Parameters:
screen
- Real screen that will be used when drawing the whole or partial virtual screen
-
-
Method Detail
-
setMinimumSize
public void setMinimumSize(TerminalSize minimumSize)
Sets the minimum size we want the virtual screen to have. If the user resizes the real terminal to something smaller than this, the virtual screen will refuse to make it smaller and add scrollbars to the view.- Parameters:
minimumSize
- Minimum size we want the screen to have
-
getMinimumSize
public TerminalSize getMinimumSize()
Returns the minimum size this virtual screen can have. If the real terminal is made smaller than this, the virtual screen will draw scrollbars and implement scrolling- Returns:
- Minimum size configured for this virtual screen
-
getViewportSize
public TerminalSize getViewportSize()
Returns the current size of the viewport. This will generally match the dimensions of the underlying terminal.- Returns:
- Viewport size for this
VirtualScreen
-
setViewportTopLeft
public void setViewportTopLeft(TerminalPosition position)
-
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
-
getFrontCharacter
public TextCharacter getFrontCharacter(TerminalPosition position)
Description copied from interface:Screen
Reads a character and its associated meta-data from the front-buffer and returns it encapsulated as a ScreenCharacter.- Specified by:
getFrontCharacter
in interfaceScreen
- Overrides:
getFrontCharacter
in classAbstractScreen
- Parameters:
position
- What position to read the character from- Returns:
- A
ScreenCharacter
representation of the character in the front-buffer at the specified location
-
setCursorPosition
public void setCursorPosition(TerminalPosition position)
Description copied from class:AbstractScreen
Moves the current cursor position or hides it. If the cursor is hidden and given a new position, it will be visible after this method call.- Specified by:
setCursorPosition
in interfaceScreen
- Overrides:
setCursorPosition
in classAbstractScreen
- Parameters:
position
- 0-indexed column and row numbers of the new position, or ifnull
, hides the cursor
-
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.
-
calculateViewport
private TerminalSize calculateViewport(TerminalSize realTerminalSize)
-
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
-
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
-
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
-
filter
private KeyStroke filter(KeyStroke keyStroke) throws java.io.IOException
- Throws:
java.io.IOException
-
scrollLines
public void scrollLines(int firstLine, int lastLine, int distance)
Description copied from class:AbstractScreen
Performs the scrolling on its back-buffer.- 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.
-
-