Class ANSITerminal

    • Field Detail

      • inPrivateMode

        private boolean inPrivateMode
    • Constructor Detail

      • ANSITerminal

        protected ANSITerminal​(java.io.InputStream terminalInput,
                               java.io.OutputStream terminalOutput,
                               java.nio.charset.Charset terminalCharset)
    • Method Detail

      • 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 java.io.IOException
        Throws:
        java.io.IOException
      • writeSGRSequenceToTerminal

        private void writeSGRSequenceToTerminal​(byte... sgrParameters)
                                         throws java.io.IOException
        Throws:
        java.io.IOException
      • writeOSCSequenceToTerminal

        private void writeOSCSequenceToTerminal​(byte... tail)
                                         throws java.io.IOException
        Throws:
        java.io.IOException
      • getTerminalSize

        public final TerminalSize getTerminalSize()
                                           throws java.io.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:
        java.io.IOException - if there was an I/O error trying to retrieve the size of the terminal
      • findTerminalSize

        protected TerminalSize findTerminalSize()
                                         throws java.io.IOException
        Throws:
        java.io.IOException
      • setTerminalSize

        public void setTerminalSize​(int columns,
                                    int rows)
                             throws java.io.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:
        java.io.IOException - If the was an underlying I/O error
      • setTitle

        public void setTitle​(java.lang.String title)
                      throws java.io.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:
        java.io.IOException - If the was an underlying I/O error
      • setForegroundColor

        public void setForegroundColor​(TextColor color)
                                throws java.io.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:
        java.io.IOException - If there was an underlying I/O error
      • setBackgroundColor

        public void setBackgroundColor​(TextColor color)
                                throws java.io.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:
        java.io.IOException - If there was an underlying I/O error
      • enableSGR

        public void enableSGR​(SGR sgr)
                       throws java.io.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:
        java.io.IOException - If there was an underlying I/O error
        See Also:
        SGR, http://www.vt100.net/docs/vt510-rm/SGR
      • disableSGR

        public void disableSGR​(SGR sgr)
                        throws java.io.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:
        java.io.IOException - If there was an underlying I/O error
        See Also:
        SGR, http://www.vt100.net/docs/vt510-rm/SGR
      • resetColorAndSGR

        public void resetColorAndSGR()
                              throws java.io.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:
        java.io.IOException - If there was an underlying I/O error
        See Also:
        SGR, http://www.vt100.net/docs/vt510-rm/SGR
      • clearScreen

        public void clearScreen()
                         throws java.io.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:
        java.io.IOException - If there was an underlying I/O error
      • enterPrivateMode

        public void enterPrivateMode()
                              throws java.io.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:
        java.io.IOException - If there was an underlying I/O error
      • exitPrivateMode

        public void exitPrivateMode()
                             throws java.io.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:
        java.io.IOException - If there was an underlying I/O error
      • close

        public void close()
                   throws java.io.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 java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Specified by:
        close in interface Terminal
        Overrides:
        close in class StreamBasedTerminal
        Throws:
        java.io.IOException - If there was an underlying I/O error
      • setCursorPosition

        public void setCursorPosition​(int x,
                                      int y)
                               throws java.io.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:
        java.io.IOException - If there was an underlying I/O error
      • setCursorPosition

        public void setCursorPosition​(TerminalPosition position)
                               throws java.io.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:
        java.io.IOException - If there was an underlying I/O error
      • getCursorPosition

        public TerminalPosition getCursorPosition()
                                           throws java.io.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:
        java.io.IOException - In there was an underlying I/O error
      • setCursorVisible

        public void setCursorVisible​(boolean visible)
                              throws java.io.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:
        java.io.IOException - If there was an underlying I/O error
      • readInput

        public KeyStroke readInput()
                            throws java.io.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:
        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 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:
        java.io.IOException - Propagated error if the underlying stream gave errors
      • 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 java.io.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:
        java.io.IOException - If the was an underlying I/O error
      • deiconify

        public void deiconify()
                       throws java.io.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:
        java.io.IOException - If the was an underlying I/O error
      • maximize

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

        public void unmaximize()
                        throws java.io.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:
        java.io.IOException - If the was an underlying I/O error
      • updateMouseCaptureMode

        private void updateMouseCaptureMode​(MouseCaptureMode mouseCaptureMode,
                                            char l_or_h)
                                     throws java.io.IOException
        Throws:
        java.io.IOException
      • setMouseCaptureMode

        public void setMouseCaptureMode​(MouseCaptureMode mouseCaptureMode)
                                 throws java.io.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:
        java.io.IOException - If the was an underlying I/O error
      • scrollLines

        public void scrollLines​(int firstLine,
                                int lastLine,
                                int distance)
                         throws java.io.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:
        java.io.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 java.io.IOException
        Throws:
        java.io.IOException
      • restoreCursorPosition

        void restoreCursorPosition()
                            throws java.io.IOException
        Throws:
        java.io.IOException
      • saveCursorPosition

        void saveCursorPosition()
                         throws java.io.IOException
        Throws:
        java.io.IOException