Class ANSITerminal

java.lang.Object
com.googlecode.lanterna.terminal.AbstractTerminal
com.googlecode.lanterna.terminal.ansi.StreamBasedTerminal
com.googlecode.lanterna.terminal.ansi.ANSITerminal
All Implemented Interfaces:
Scrollable, InputProvider, ExtendedTerminal, Terminal, Closeable, AutoCloseable
Direct Known Subclasses:
TelnetTerminal, UnixLikeTerminal
public abstract class ANSITerminal extends StreamBasedTerminal implements ExtendedTerminal
Class containing graphics code for ANSI compliant text terminals and terminal emulators. All the methods inside of this class uses ANSI escape codes written to the underlying output stream.
See Also:

  • Field Details

    • requestedMouseCaptureMode

      private MouseCaptureMode requestedMouseCaptureMode

    • mouseCaptureMode

      private MouseCaptureMode mouseCaptureMode

    • inPrivateMode

      private boolean inPrivateMode

  • Constructor Details

  • Method Details

    • getDefaultKeyDecodingProfile

      protected KeyDecodingProfile getDefaultKeyDecodingProfile()
      This method can be overridden in a custom terminal implementation to change the default key decoders.
      Returns:
      The KeyDecodingProfile used by the terminal when translating character sequences to keystrokes

    • writeCSISequenceToTerminal

      private void writeCSISequenceToTerminal(byte... tail) throws IOException
      Throws:
      IOException

    • writeSGRSequenceToTerminal

      private void writeSGRSequenceToTerminal(byte... sgrParameters) throws IOException
      Throws:
      IOException

    • writeOSCSequenceToTerminal

      private void writeOSCSequenceToTerminal(byte... tail) throws IOException
      Throws:
      IOException

    • getTerminalSize

      public final TerminalSize getTerminalSize() throws IOException
      Description copied from interface: Terminal
      Returns the size of the terminal, expressed as a TerminalSize object. Please bear in mind that depending on the Terminal implementation, this may or may not be accurate. See the implementing classes for more information. Most commonly, calling getTerminalSize() will involve some kind of hack to retrieve the size of the terminal, like moving the cursor to position 5000x5000 and then read back the location, unless the terminal implementation has a more smooth way of getting this data. Keep this in mind and see if you can avoid calling this method too often. There is a helper class, SimpleTerminalResizeListener, that you can use to cache the size and update it only when resize events are received (which depends on if a resize is detectable, which they are not on all platforms).
      Specified by:
      getTerminalSize in interface Terminal
      Returns:
      Size of the terminal
      Throws:
      IOException - if there was an I/O error trying to retrieve the size of the terminal

    • findTerminalSize

      protected TerminalSize findTerminalSize() throws IOException
      Throws:
      IOException

    • setTerminalSize

      public void setTerminalSize(int columns, int rows) throws IOException
      Description copied from interface: ExtendedTerminal
      Attempts to resize the terminal through dtterm extensions "CSI 8 ; rows ; columns ; t". This isn't widely supported, which is why the method is not exposed through the common Terminal interface.
      Specified by:
      setTerminalSize in interface ExtendedTerminal
      Parameters:
      columns - New size (columns)
      rows - New size (rows)
      Throws:
      IOException - If the was an underlying I/O error

    • setTitle

      public void setTitle(String title) throws IOException
      Description copied from interface: ExtendedTerminal
      This methods sets the title of the terminal, which is normally only visible if you are running the application in a terminal emulator in a graphical environment.
      Specified by:
      setTitle in interface ExtendedTerminal
      Parameters:
      title - Title to set on the terminal
      Throws:
      IOException - If the was an underlying I/O error

    • setForegroundColor

      public void setForegroundColor(TextColor color) throws IOException
      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 Terminal
      Parameters:
      color - Color to use for foreground
      Throws:
      IOException - If there was an underlying I/O error

    • setBackgroundColor

      public void setBackgroundColor(TextColor color) throws IOException
      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 Terminal
      Parameters:
      color - Color to use for the background
      Throws:
      IOException - If there was an underlying I/O error

    • enableSGR

      public void enableSGR(SGR sgr) throws IOException
      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 Terminal
      Parameters:
      sgr - SGR code to apply
      Throws:
      IOException - If there was an underlying I/O error
      See Also:

    • disableSGR

      public void disableSGR(SGR sgr) throws IOException
      Description copied from interface: Terminal
      Deactivates an SGR (Selected Graphic Rendition) code which has previously been activated through enableSGR(..).
      Specified by:
      disableSGR in interface Terminal
      Parameters:
      sgr - SGR code to apply
      Throws:
      IOException - If there was an underlying I/O error
      See Also:

    • resetColorAndSGR

      public void resetColorAndSGR() throws IOException
      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 Terminal
      Throws:
      IOException - If there was an underlying I/O error
      See Also:

    • clearScreen

      public void clearScreen() throws IOException
      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 Terminal
      Throws:
      IOException - If there was an underlying I/O error

    • enterPrivateMode

      public void enterPrivateMode() throws IOException
      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 Terminal
      Throws:
      IOException - If there was an underlying I/O error

    • exitPrivateMode

      public void exitPrivateMode() throws IOException
      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 Terminal
      Throws:
      IOException - If there was an underlying I/O error

    • close

      public void close() throws IOException
      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 Terminal
      Overrides:
      close in class StreamBasedTerminal
      Throws:
      IOException - If there was an underlying I/O error

    • setCursorPosition

      public void setCursorPosition(int x, int y) throws IOException
      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 Terminal
      Parameters:
      x - The 0-indexed column to place the cursor at
      y - The 0-indexed row to place the cursor at
      Throws:
      IOException - If there was an underlying I/O error

    • setCursorPosition

      public void setCursorPosition(TerminalPosition position) throws IOException
      Description copied from interface: Terminal
      Same as calling setCursorPosition(position.getColumn(), position.getRow())
      Specified by:
      setCursorPosition in interface Terminal
      Parameters:
      position - Position to place the cursor at
      Throws:
      IOException - If there was an underlying I/O error

    • getCursorPosition

      public TerminalPosition getCursorPosition() throws IOException
      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 Terminal
      Returns:
      Position of the cursor
      Throws:
      IOException - In there was an underlying I/O error

    • setCursorVisible

      public void setCursorVisible(boolean visible) throws IOException
      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 Terminal
      Parameters:
      visible - Hides the text cursor if false and shows it if true
      Throws:
      IOException - If there was an underlying I/O error

    • readInput

      public KeyStroke readInput() throws IOException
      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
      Overrides:
      readInput in class StreamBasedTerminal
      Returns:
      Key object which represents a keystroke coming in through the input stream
      Throws:
      IOException - Propagated error if the underlying stream gave errors

    • pollInput

      public KeyStroke pollInput() throws IOException
      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
      Overrides:
      pollInput in class StreamBasedTerminal
      Returns:
      Key object which represents a keystroke coming in through the input stream
      Throws:
      IOException - Propagated error if the underlying stream gave errors

    • filterMouseEvents

      private KeyStroke filterMouseEvents(KeyStroke keyStroke)

    • pushTitle

      public void pushTitle()
      Description copied from interface: ExtendedTerminal
      Saves the current window title on a stack managed internally by the terminal.
      Specified by:
      pushTitle in interface ExtendedTerminal

    • popTitle

      public void popTitle()
      Description copied from interface: ExtendedTerminal
      Replaces the terminal title with the top element from the title stack managed by the terminal (the element is removed from the stack as expected)
      Specified by:
      popTitle in interface ExtendedTerminal

    • iconify

      public void iconify() throws IOException
      Description copied from interface: ExtendedTerminal
      Iconifies the terminal, this likely means minimizing the window with most window managers
      Specified by:
      iconify in interface ExtendedTerminal
      Throws:
      IOException - If the was an underlying I/O error

    • deiconify

      public void deiconify() throws IOException
      Description copied from interface: ExtendedTerminal
      De-iconifies the terminal, which likely means restoring it from minimized state with most window managers
      Specified by:
      deiconify in interface ExtendedTerminal
      Throws:
      IOException - If the was an underlying I/O error

    • maximize

      public void maximize() throws IOException
      Description copied from interface: ExtendedTerminal
      Maximizes the terminal, so that it takes up all available space
      Specified by:
      maximize in interface ExtendedTerminal
      Throws:
      IOException - If the was an underlying I/O error

    • unmaximize

      public void unmaximize() throws IOException
      Description copied from interface: ExtendedTerminal
      Restores the terminal back to its previous size, after having been maximized
      Specified by:
      unmaximize in interface ExtendedTerminal
      Throws:
      IOException - If the was an underlying I/O error

    • updateMouseCaptureMode

      private void updateMouseCaptureMode(MouseCaptureMode mouseCaptureMode, char l_or_h) throws IOException
      Throws:
      IOException

    • setMouseCaptureMode

      public void setMouseCaptureMode(MouseCaptureMode mouseCaptureMode) throws IOException
      Description copied from interface: ExtendedTerminal
      Enabled or disables capturing of mouse event. This is not recommended to use as most users are not familiar with the fact that terminal emulators allow capturing mouse input. You can decide which events you want to capture but be careful since different terminal emulators will support these modes differently. Mouse capture mode will be automatically disabled when the application exits through a shutdown hook.
      Specified by:
      setMouseCaptureMode in interface ExtendedTerminal
      Parameters:
      mouseCaptureMode - Which mouse events to capture, pass in null to disable mouse input capturing
      Throws:
      IOException - If the was an underlying I/O error

    • scrollLines

      public void scrollLines(int firstLine, int lastLine, int distance) throws IOException
      Description copied from interface: Scrollable
      Scroll a range of lines of this Scrollable according to given distance. If scroll-range is empty (firstLine > lastLine || distance == 0) then this method does nothing. Lines that are scrolled away from are cleared. If absolute value of distance is equal or greater than number of lines in range, then all lines within the range will be cleared.
      Specified by:
      scrollLines in interface Scrollable
      Parameters:
      firstLine - first line of the range to be scrolled (top line is 0)
      lastLine - last (inclusive) line of the range to be scrolled
      distance - if > 0: move lines up, else if < 0: move lines down.
      Throws:
      IOException - If there was an I/O error when running the operation

    • isInPrivateMode

      boolean isInPrivateMode()
      Method to test if the terminal (as far as the library knows) is in private mode.
      Returns:
      True if there has been a call to enterPrivateMode() but not yet exitPrivateMode()

    • reportPosition

      void reportPosition() throws IOException
      Throws:
      IOException

    • restoreCursorPosition

      void restoreCursorPosition() throws IOException
      Throws:
      IOException

    • saveCursorPosition

      void saveCursorPosition() throws IOException
      Throws:
      IOException