Class DefaultVirtualTerminal

java.lang.Object
com.googlecode.lanterna.terminal.AbstractTerminal
com.googlecode.lanterna.terminal.virtual.DefaultVirtualTerminal
All Implemented Interfaces:
InputProvider, IOSafeTerminal, Terminal, VirtualTerminal, Closeable, AutoCloseable
public class DefaultVirtualTerminal extends AbstractTerminal implements VirtualTerminal

  • Field Details

    • regularTextBuffer

      private final TextBuffer regularTextBuffer

    • privateModeTextBuffer

      private final TextBuffer privateModeTextBuffer

    • dirtyTerminalCells

      private final TreeSet<TerminalPosition> dirtyTerminalCells

    • listeners

      private final List<VirtualTerminalListener> listeners

    • currentTextBuffer

      private TextBuffer currentTextBuffer

    • wholeBufferDirty

      private boolean wholeBufferDirty

    • terminalSize

      private TerminalSize terminalSize

    • cursorVisible

      private boolean cursorVisible

    • backlogSize

      private int backlogSize

    • inputQueue

      private final BlockingQueue<KeyStroke> inputQueue

    • activeModifiers

      private final EnumSet<SGR> activeModifiers

    • activeForegroundColor

      private TextColor activeForegroundColor

    • activeBackgroundColor

      private TextColor activeBackgroundColor

    • cursorPosition

      private TerminalPosition cursorPosition

    • savedCursorPosition

      private TerminalPosition savedCursorPosition

  • Constructor Details

    • DefaultVirtualTerminal

      public DefaultVirtualTerminal()
      Creates a new virtual terminal with an initial size set

    • DefaultVirtualTerminal

      public DefaultVirtualTerminal(TerminalSize initialTerminalSize)
      Creates a new virtual terminal with an initial size set
      Parameters:
      initialTerminalSize - Starting size of the virtual terminal

  • Method Details

    • getTerminalSize

      public TerminalSize getTerminalSize()
      /////////////////////////////////////////////////////////////////////////////////////////////////////////////////
      Specified by:
      getTerminalSize in interface IOSafeTerminal
      Specified by:
      getTerminalSize in interface Terminal
      Returns:
      Size of the terminal

    • setTerminalSize

      public void setTerminalSize(TerminalSize newSize)
      Description copied from interface: VirtualTerminal
      Changes the "visible size" of the virtual terminal. This is the area at the bottom of the text buffer that is considered the workable area since the cursor is restricted to this space. If you call this method with a size that is different from the current size of the virtual terminal, the resize event will be fired on all listeners.
      Specified by:
      setTerminalSize in interface VirtualTerminal
      Parameters:
      newSize - New size of the virtual terminal

    • enterPrivateMode

      public void enterPrivateMode()
      Description copied from interface: Terminal
      Calling this method will, where supported, give your terminal a private area to use, separate from what was there before. Some terminal emulators will preserve the terminal history and restore it when you exit private mode. Some terminals will just clear the screen and put the cursor in the top-left corner. Typically, if you terminal supports scrolling, going into private mode will disable the scrolling and leave you with a fixed screen, which can be useful if you don't want to deal with what the terminal buffer will look like if the user scrolls up.
      Specified by:
      enterPrivateMode in interface IOSafeTerminal
      Specified by:
      enterPrivateMode in interface Terminal

    • exitPrivateMode

      public void exitPrivateMode()
      Description copied from interface: Terminal
      If you have previously entered private mode, this method will exit this and, depending on implementation, maybe restore what the terminal looked like before private mode was entered. If the terminal doesn't support a secondary buffer for private mode, it will probably make a new line below the private mode and place the cursor there.
      Specified by:
      exitPrivateMode in interface IOSafeTerminal
      Specified by:
      exitPrivateMode in interface Terminal

    • clearScreen

      public void clearScreen()
      Description copied from interface: Terminal
      Removes all the characters, colors and graphics from the screen and leaves you with a big empty space. Text cursor position is undefined after this call (depends on platform and terminal) so you should always call moveCursor next. Some terminal implementations doesn't reset color and modifier state so it's also good practise to call resetColorAndSGR() after this.
      Specified by:
      clearScreen in interface IOSafeTerminal
      Specified by:
      clearScreen in interface Terminal

    • setCursorPosition

      public void setCursorPosition(int x, int y)
      Description copied from interface: Terminal
      Moves the text cursor to a new location on the terminal. The top-left corner has coordinates 0 x 0 and the bottom- right corner has coordinates terminal_width-1 x terminal_height-1. You can retrieve the size of the terminal by calling getTerminalSize().
      Specified by:
      setCursorPosition in interface IOSafeTerminal
      Specified by:
      setCursorPosition in interface Terminal
      Parameters:
      x - The 0-indexed column to place the cursor at
      y - The 0-indexed row to place the cursor at

    • setCursorPosition

      public void setCursorPosition(TerminalPosition cursorPosition)
      Description copied from interface: Terminal
      Same as calling setCursorPosition(position.getColumn(), position.getRow())
      Specified by:
      setCursorPosition in interface IOSafeTerminal
      Specified by:
      setCursorPosition in interface Terminal
      Parameters:
      cursorPosition - Position to place the cursor at

    • getCursorPosition

      public TerminalPosition getCursorPosition()
      Description copied from interface: Terminal
      Returns the position of the cursor, as reported by the terminal. The top-left corner has coordinates 0 x 0 and the bottom-right corner has coordinates terminal_width-1 x terminal_height-1.
      Specified by:
      getCursorPosition in interface IOSafeTerminal
      Specified by:
      getCursorPosition in interface Terminal
      Returns:
      Position of the cursor

    • getCursorBufferPosition

      public TerminalPosition getCursorBufferPosition()
      Description copied from interface: VirtualTerminal
      Returns the position of the terminal cursor where the row index is counted from the top of the text buffer, including all backlog. This means, if there is 500 lines of backlog but the cursor position is set to 0x0, this method will return 0x500. If you want to get the cursor's position in the viewport, please use IOSafeTerminal.getCursorPosition() instead.
      Specified by:
      getCursorBufferPosition in interface VirtualTerminal
      Returns:
      Cursor position as an offset from the top-left position of the text buffer including any backlog

    • setCursorVisible

      public void setCursorVisible(boolean visible)
      Description copied from interface: Terminal
      Hides or shows the text cursor, but not all terminal (-emulators) supports this. The text cursor is normally a text block or an underscore, sometimes blinking, which shows the user where keyboard-entered text is supposed to show up.
      Specified by:
      setCursorVisible in interface IOSafeTerminal
      Specified by:
      setCursorVisible in interface Terminal
      Parameters:
      visible - Hides the text cursor if false and shows it if true

    • putCharacter

      public void putCharacter(char c)
      Description copied from interface: Terminal
      Prints one character to the terminal at the current cursor location. Please note that the cursor will then move one column to the right, so multiple calls to putCharacter will print out a text string without the need to reposition the text cursor. If you reach the end of the line while putting characters using this method, you can expect the text cursor to move to the beginning of the next line.

      You can output CJK (Chinese, Japanese, Korean) characters (as well as other regional scripts) but remember that the terminal that the user is using might not have the required font to render it. Also worth noticing is that CJK (and some others) characters tend to take up 2 columns per character, simply because they are a square in their construction as opposed to the somewhat rectangular shape we fit latin characters in. As it's very difficult to create a monospace font for CJK with a 2:1 height-width proportion, it seems like the implementers back in the days simply gave up and made each character take 2 column. It causes issues for the random terminal programmer because you can't really trust 1 character = 1 column, but I suppose it's "しょうがない". If you try to print non-printable control characters, the terminal is likely to ignore them (all Terminal implementations bundled with Lanterna will).

      Specified by:
      putCharacter in interface IOSafeTerminal
      Specified by:
      putCharacter in interface Terminal
      Parameters:
      c - Character to place on the terminal

    • putString

      public void putString(String string)
      Description copied from interface: Terminal
      Prints a string to the terminal at the current cursor location. Please note that the cursor will then move one column to the right, so multiple calls to putString will print out a text string without the need to reposition the text cursor. If you reach the end of the line while putting characters using this method, you can expect the text cursor to move to the beginning of the next line.

      You can output CJK (Chinese, Japanese, Korean) characters (as well as other regional scripts) but remember that the terminal that the user is using might not have the required font to render it. Also worth noticing is that CJK (and some others) characters tend to take up 2 columns per character, simply because they are a square in their construction as opposed to the somewhat rectangular shape we fit latin characters in. As it's very difficult to create a monospace font for CJK with a 2:1 height-width proportion, it seems like the implementers back in the days simply gave up and made each character take 2 column. It causes issues for the random terminal programmer because you can't really trust 1 character = 1 column, but I suppose it's "しょうがない".

      If you try to print non-printable control characters, the terminal is likely to ignore them (all Terminal implementations bundled with Lanterna will).

      You can use this method to place emoji characters on the terminal, since they take up more than one char with Java's built-in UTF16 encoding.

      Specified by:
      putString in interface IOSafeTerminal
      Specified by:
      putString in interface Terminal
      Parameters:
      string - String to place on the terminal

    • enableSGR

      public void enableSGR(SGR sgr)
      Description copied from interface: Terminal
      Activates an SGR (Selected Graphic Rendition) code. This code modifies a state inside the terminal that will apply to all characters written afterwards, such as bold, italic, blinking code and so on.
      Specified by:
      enableSGR in interface IOSafeTerminal
      Specified by:
      enableSGR in interface Terminal
      Parameters:
      sgr - SGR code to apply
      See Also:

    • disableSGR

      public void disableSGR(SGR sgr)
      Description copied from interface: Terminal
      Deactivates an SGR (Selected Graphic Rendition) code which has previously been activated through enableSGR(..).
      Specified by:
      disableSGR in interface IOSafeTerminal
      Specified by:
      disableSGR in interface Terminal
      Parameters:
      sgr - SGR code to apply
      See Also:

    • resetColorAndSGR

      public void resetColorAndSGR()
      Description copied from interface: Terminal
      Removes all currently active SGR codes and sets foreground and background colors back to default.
      Specified by:
      resetColorAndSGR in interface IOSafeTerminal
      Specified by:
      resetColorAndSGR in interface Terminal
      See Also:

    • setForegroundColor

      public void setForegroundColor(TextColor color)
      Description copied from interface: Terminal
      Changes the foreground color for all the following characters put to the terminal. The foreground color is what color to draw the text in, as opposed to the background color which is the color surrounding the characters.

      This overload is using the TextColor class to define a color, which is a layer of abstraction above the three different color formats supported (ANSI, indexed and RGB). The other setForegroundColor(..) overloads gives you direct access to set one of those three.

      Note to implementers of this interface, just make this method call color.applyAsForeground(this);

      Specified by:
      setForegroundColor in interface IOSafeTerminal
      Specified by:
      setForegroundColor in interface Terminal
      Parameters:
      color - Color to use for foreground

    • setBackgroundColor

      public void setBackgroundColor(TextColor color)
      Description copied from interface: Terminal
      Changes the background color for all the following characters put to the terminal. The background color is the color surrounding the text being printed.

      This overload is using the TextColor class to define a color, which is a layer of abstraction above the three different color formats supported (ANSI, indexed and RGB). The other setBackgroundColor(..) overloads gives you direct access to set one of those three.

      Note to implementers of this interface, just make this method call color.applyAsBackground(this);

      Specified by:
      setBackgroundColor in interface IOSafeTerminal
      Specified by:
      setBackgroundColor in interface Terminal
      Parameters:
      color - Color to use for the background

    • enquireTerminal

      public byte[] enquireTerminal(int timeout, TimeUnit timeoutUnit)
      Description copied from interface: Terminal
      Retrieves optional information from the terminal by printing the ENQ (\u005) character. Terminals and terminal emulators may or may not respond to this command, sometimes it's configurable.
      Specified by:
      enquireTerminal in interface IOSafeTerminal
      Specified by:
      enquireTerminal in interface Terminal
      Parameters:
      timeout - How long to wait for the talk-back message, if there's nothing immediately available on the input stream, you should probably set this to a somewhat small value to prevent unnecessary blockage on the input stream but large enough to accommodate a round-trip to the user's terminal (~300 ms if you are connection across the globe).
      timeoutUnit - What unit to use when interpreting the timeout parameter
      Returns:
      Answer-back message from the terminal or empty if there was nothing

    • bell

      public void bell()
      Description copied from interface: Terminal
      Prints 0x7 to the terminal, which will make the terminal (emulator) ring a bell (or more likely beep). Not all terminals implements this. Wikipedia has more details.
      Specified by:
      bell in interface IOSafeTerminal
      Specified by:
      bell in interface Terminal

    • flush

      public void flush()
      Description copied from interface: Terminal
      Calls flush() on the underlying OutputStream object, or whatever other implementation this terminal is built around. Some implementing classes of this interface (like SwingTerminal) doesn't do anything as it doesn't really apply to them.
      Specified by:
      flush in interface IOSafeTerminal
      Specified by:
      flush in interface Terminal

    • close

      public void close()
      Description copied from interface: Terminal
      Closes the terminal, if applicable. If the implementation doesn't support closing the terminal, this will do nothing. The Swing/AWT emulator implementations will translate this into a dispose() call on the UI resources, the telnet implementation will hang out the connection.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Specified by:
      close in interface IOSafeTerminal
      Specified by:
      close in interface Terminal

    • pollInput

      public KeyStroke pollInput()
      Description copied from interface: InputProvider
      Returns the next Key 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.
      Specified by:
      pollInput in interface InputProvider
      Specified by:
      pollInput in interface IOSafeTerminal
      Returns:
      Key object which represents a keystroke coming in through the input stream

    • readInput

      public KeyStroke readInput()
      Description copied from interface: InputProvider
      Returns the next Key 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 call pollInput() for the non-blocking version.
      Specified by:
      readInput in interface InputProvider
      Specified by:
      readInput in interface IOSafeTerminal
      Returns:
      Key object which represents a keystroke coming in through the input stream

    • newTextGraphics

      public TextGraphics newTextGraphics()
      Description copied from interface: Terminal
      Creates a new TextGraphics object that uses this Terminal directly when outputting. Keep in mind that you are probably better off to switch to a Screen to make advanced text graphics more efficient. Also, this TextGraphics implementation will not call .flush() after any operation, so you'll need to do that on your own.
      Specified by:
      newTextGraphics in interface Terminal
      Overrides:
      newTextGraphics in class AbstractTerminal
      Returns:
      TextGraphics implementation that draws directly using this Terminal interface

    • addVirtualTerminalListener

      public void addVirtualTerminalListener(VirtualTerminalListener listener)
      /////////////////////////////////////////////////////////////////////////////////////////////////////////////////
      Specified by:
      addVirtualTerminalListener in interface VirtualTerminal
      Parameters:
      listener - Listener to receive events from this virtual terminal

    • removeVirtualTerminalListener

      public void removeVirtualTerminalListener(VirtualTerminalListener listener)
      Description copied from interface: VirtualTerminal
      Removes a listener from this virtual terminal so it will no longer receive events. Notice that this is not the same as the list of TerminalResizeListener.
      Specified by:
      removeVirtualTerminalListener in interface VirtualTerminal
      Parameters:
      listener - Listener to remove from this virtual terminal

    • setBacklogSize

      public void setBacklogSize(int backlogSize)
      Description copied from interface: VirtualTerminal
      Sets the number of rows to allow in the non-private buffer above the viewport. The total size of the text buffer will be backlogSize + terminalSize.getRows(). If set to 0, there is no scrollback. Please note that private mode is unaffected by this and will always have no backlog.
      Specified by:
      setBacklogSize in interface VirtualTerminal
      Parameters:
      backlogSize - Number of rows of backlog

    • isCursorVisible

      public boolean isCursorVisible()
      Description copied from interface: VirtualTerminal
      Checks if the terminal cursor is visible or not
      Specified by:
      isCursorVisible in interface VirtualTerminal
      Returns:
      true if the terminal cursor is visible, false otherwise

    • addInput

      public void addInput(KeyStroke keyStroke)
      Description copied from interface: VirtualTerminal
      Adds a KeyStroke to the input queue of this virtual terminal. This even will be read the next time either IOSafeTerminal.pollInput() or IOSafeTerminal.readInput() is called, assuming there are no other events before it in the queue.
      Specified by:
      addInput in interface VirtualTerminal
      Parameters:
      keyStroke - KeyStroke to add to the input queue of this virtual terminal

    • getDirtyCells

      public TreeSet<TerminalPosition> getDirtyCells()

    • getAndResetDirtyCells

      public TreeSet<TerminalPosition> getAndResetDirtyCells()

    • isWholeBufferDirtyThenReset

      public boolean isWholeBufferDirtyThenReset()

    • getCharacter

      public TextCharacter getCharacter(TerminalPosition position)
      Description copied from interface: VirtualTerminal
      Returns a character from the viewport at the specified coordinates. This method cannot access the backlog, if you want to fetch a character potentially from the backlog, please use VirtualTerminal.getBufferCharacter(TerminalPosition) instead.
      Specified by:
      getCharacter in interface VirtualTerminal
      Parameters:
      position - Position of the character to return
      Returns:
      Text character at the specific position in the viewport

    • getCharacter

      public TextCharacter getCharacter(int column, int row)
      Description copied from interface: VirtualTerminal
      Returns a character from the viewport at the specified coordinates. This method cannot access the backlog, if you want to fetch a character potentially from the backlog, please use VirtualTerminal.getBufferCharacter(int,int) instead.
      Specified by:
      getCharacter in interface VirtualTerminal
      Parameters:
      column - Column in the viewport to get the character from
      row - Row in the viewport to get the character form
      Returns:
      Text character at the specific position in the viewport

    • getBufferCharacter

      public TextCharacter getBufferCharacter(int column, int row)
      Description copied from interface: VirtualTerminal
      Returns a character from this virtual terminal, relative to the top-left position of the text buffer including any backlog. If you want to get a character from the bottom viewport, please use VirtualTerminal.getCharacter(int, int) instead.
      Specified by:
      getBufferCharacter in interface VirtualTerminal
      Parameters:
      column - Column to get the character from
      row - Row, counting from the first line in the backlog, to get the character from
      Returns:
      Text character at the specific position in the text buffer

    • getBufferCharacter

      public TextCharacter getBufferCharacter(TerminalPosition position)
      Description copied from interface: VirtualTerminal
      Returns a character from this virtual terminal, relative to the top-left position of the text buffer including any backlog. If you want to get a character from the bottom viewport, please use VirtualTerminal.getCharacter(TerminalPosition) instead.
      Specified by:
      getBufferCharacter in interface VirtualTerminal
      Parameters:
      position - Position to get the character from
      Returns:
      Text character at the specific position in the text buffer

    • getBufferLineCount

      public int getBufferLineCount()
      Description copied from interface: VirtualTerminal
      Returns the number of lines in the entire text buffer, including any backlog
      Specified by:
      getBufferLineCount in interface VirtualTerminal
      Returns:
      Number of lines in the buffer

    • forEachLine

      public void forEachLine(int startRow, int endRow, VirtualTerminal.BufferWalker bufferWalker)
      Description copied from interface: VirtualTerminal
      Iterates over a range of lines in the text buffer
      Specified by:
      forEachLine in interface VirtualTerminal
      Parameters:
      startRow - Index of the first row of the iteration, counting 0 as the first row in the backlog
      endRow - Index of the last row of the iteration (inclusive), counting 0 as the first row in the backlog
      bufferWalker - Callback to invoke on each row in the iteration

    • putCharacter

      void putCharacter(TextCharacter terminalCharacter)

    • moveCursorToNextLine

      private void moveCursorToNextLine()
      Moves the text cursor to the first column of the next line and trims the backlog of necessary

    • setWholeBufferDirty

      private void setWholeBufferDirty()
      Marks the whole buffer as dirty so every cell is considered in need to repainting. This is used by methods such as clear and bell that will affect all content at once.

    • trimBufferBacklog

      private void trimBufferBacklog()

    • correctCursor

      private void correctCursor()

    • toString

      public String toString()
      Overrides:
      toString in class Object