Class ScreenTerminal

  • All Implemented Interfaces:
    Sized
    Direct Known Subclasses:
    WebTerminal.WebTerminalComponent

    public class ScreenTerminal
    extends java.lang.Object
    implements Sized
    A virtual terminal screen implementation.

    This class provides a virtual terminal screen that can process ANSI escape sequences and maintain the state of a terminal display. It supports features including:

    • Cursor positioning and movement
    • Text attributes (bold, underline, etc.)
    • Color support (including 256 colors)
    • Screen clearing and scrolling
    • Alternate screen buffer
    • Screen resizing

    This implementation is based on the Apache Karaf WebConsole Gogo plugin, with adaptations to support alternate screen, resizing, and 256 colors. It follows the ECMA-48 standard for terminal control sequences.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int MAX_SIZE  
      static int MIN_SIZE  
    • Constructor Summary

      Constructors 
      Constructor Description
      ScreenTerminal()
      Creates a ScreenTerminal using the default size of 80 columns and 24 rows.
      ScreenTerminal​(int columns, int rows)
      Creates a ScreenTerminal with the specified number of columns and rows.
      ScreenTerminal​(int columns, int rows, boolean eatNewlineGlitch)
      Creates a ScreenTerminal with the specified size and wrap behavior.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static long cellAttr​(long cell)
      Extracts the raw 32-bit attribute word from a cell value.
      static int cellBackground​(long cell)
      Extracts the background color as a 12-bit value (4 bits per r/g/b channel).
      static boolean cellBold​(long cell)
      Returns true if the cell has the bold attribute set.
      static int cellCodePoint​(long cell)
      Extracts the Unicode code point from a cell value.
      static int cellColorRgb​(int color12)
      Expands a 12-bit color (as returned by cellForeground(long) or cellBackground(long)) to a 24-bit RGB value.
      static boolean cellConceal​(long cell)
      Returns true if the cell has the conceal (hidden) attribute set.
      static boolean cellDim​(long cell)
      Returns true if the cell has the dim/faint attribute set.
      static int cellForeground​(long cell)
      Extracts the foreground color as a 12-bit value (4 bits per r/g/b channel).
      static boolean cellHasBackground​(long cell)
      Returns true if the cell has an explicit background color set.
      static boolean cellHasForeground​(long cell)
      Returns true if the cell has an explicit foreground color set.
      static boolean cellInverse​(long cell)
      Returns true if the cell has the inverse (negative) attribute set.
      static boolean cellItalic​(long cell)
      Returns true if the cell has the italic attribute set.
      static boolean cellUnderline​(long cell)
      Returns true if the cell has the underline attribute set.
      java.lang.String dump()
      Dumps the terminal content as HTML with inline RGB color styles.
      void dump​(long[] fullscreen, int[] cursor)
      Dumps the raw screen content into a flat array.
      void dump​(long[] fullscreen, int ftop, int fleft, int fheight, int fwidth, int[] cursor)  
      java.lang.String dump​(long timeout, boolean forceDump)
      Dumps the terminal content as HTML with inline RGB color styles.
      boolean dump​(long timeout, boolean forceDump, long[] fullscreen, int[] cursor)
      Waits for the screen to be dirty, then dumps the raw screen content.
      boolean dump​(long timeout, boolean forceDump, long[] fullscreen, int ftop, int fleft, int fheight, int fwidth, int[] cursor)
      Waits for the screen to be dirty, then dumps the raw screen content into a subregion.
      int getColumns()
      Provide the current number of columns in the terminal.
      int getHeight()
      Deprecated.
      Use getRows() instead.
      java.util.List<long[]> getHistory()
      Returns a snapshot of the scrollback history: the lines that have scrolled off the top of the active screen, oldest first.
      int getHistorySize()
      Returns the number of lines currently held in the scrollback history.
      int getRows()
      Gets the number of rows in the terminal.
      int getWidth()
      Deprecated.
      Use getColumns() instead.
      boolean isDirty()  
      boolean isSynchronizedOutput()
      Returns whether the terminal is currently in synchronized output mode (mode 2026).
      java.lang.String pipe​(java.lang.String d)  
      java.lang.String read()  
      protected void setDirty()  
      boolean setSize​(int columns, int rows)
      Deprecated.
      Use setSize(Sized) instead.
      boolean setSize​(Sized sized)
      Resize the terminal to the specified columns and rows.
      java.lang.String toString()  
      void waitDirty()  
      boolean waitDirty​(long timeout)
      Waits for the screen to become dirty, up to the given timeout.
      static void wireTerminal​(ScreenTerminal screen, LineDisciplineTerminal terminal, ScreenTerminalOutputStream.DelegateOutputStream delegate)
      Wires an existing ScreenTerminal to an existing LineDisciplineTerminal whose masterOutput is a ScreenTerminalOutputStream.DelegateOutputStream.
      static void wireTerminal​(ScreenTerminal screen, LineDisciplineTerminal terminal, ScreenTerminalOutputStream.DelegateOutputStream delegate, java.lang.Runnable onFlush)
      Wires an existing ScreenTerminal to an existing LineDisciplineTerminal, adding a callback that is invoked every time the ScreenTerminalOutputStream is flushed.
      static ScreenTerminal.VirtualTerminal withTerminal​(java.lang.String name, java.lang.String type, int width, int height)
      Creates a ScreenTerminal paired with a LineDisciplineTerminal and wires them together so that: Bytes written to the terminal's output are decoded and forwarded to the screen. VT100 responses generated by the screen (e.g.
      boolean write​(java.lang.CharSequence d)  
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Constructor Detail

      • ScreenTerminal

        public ScreenTerminal()
        Creates a ScreenTerminal using the default size of 80 columns and 24 rows.
      • ScreenTerminal

        public ScreenTerminal​(int columns,
                              int rows)
        Creates a ScreenTerminal with the specified number of columns and rows.
        Parameters:
        columns - the number of character columns for the terminal
        rows - the number of character rows for the terminal
      • ScreenTerminal

        public ScreenTerminal​(int columns,
                              int rows,
                              boolean eatNewlineGlitch)
        Creates a ScreenTerminal with the specified size and wrap behavior.
        Parameters:
        columns - the number of character columns for the terminal
        rows - the number of character rows for the terminal
        eatNewlineGlitch - when true, the cursor stays at the last column after writing a character there (delayed wrap / xenl behavior, like xterm). When false, writing at the last column immediately wraps the cursor to column 0 of the next line (like windows-vtp).
    • Method Detail

      • withTerminal

        public static ScreenTerminal.VirtualTerminal withTerminal​(java.lang.String name,
                                                                  java.lang.String type,
                                                                  int width,
                                                                  int height)
                                                           throws java.io.IOException
        Creates a ScreenTerminal paired with a LineDisciplineTerminal and wires them together so that:
        • Bytes written to the terminal's output are decoded and forwarded to the screen.
        • VT100 responses generated by the screen (e.g. cursor-position reports) are fed back as terminal input.

        This factory hides the circular dependency between the two objects (the terminal needs an OutputStream at construction time, but the ScreenTerminalOutputStream needs the terminal for feedback) by using a ScreenTerminalOutputStream.DelegateOutputStream internally.

        Parameters:
        name - the terminal name
        type - the terminal type (e.g. "screen-256color")
        width - the initial number of columns
        height - the initial number of rows
        Returns:
        a ScreenTerminal.VirtualTerminal holding the paired terminal and screen
        Throws:
        java.io.IOException - if an I/O error occurs while creating the terminal
      • isDirty

        public boolean isDirty()
      • waitDirty

        public void waitDirty()
                       throws java.lang.InterruptedException
        Throws:
        java.lang.InterruptedException
      • waitDirty

        public boolean waitDirty​(long timeout)
                          throws java.lang.InterruptedException
        Waits for the screen to become dirty, up to the given timeout. Uses a while loop to guard against spurious wakeups.
        Parameters:
        timeout - maximum time to wait in milliseconds; if <= 0, returns immediately
        Returns:
        true if the screen is dirty
        Throws:
        java.lang.InterruptedException - if interrupted while waiting
      • setDirty

        protected void setDirty()
      • isSynchronizedOutput

        public boolean isSynchronizedOutput()
        Returns whether the terminal is currently in synchronized output mode (mode 2026).

        When synchronized output is active, dirty notifications are deferred until the mode is turned off (ESU received), allowing consumers to see a single atomic screen update instead of per-character repaints.

        Returns:
        true if mode 2026 is currently set
      • getColumns

        public int getColumns()
        Provide the current number of columns in the terminal.
        Specified by:
        getColumns in interface Sized
        Returns:
        the current number of columns
      • getRows

        public int getRows()
        Gets the number of rows in the terminal.
        Specified by:
        getRows in interface Sized
        Returns:
        the number of rows
      • getWidth

        @Deprecated
        public int getWidth()
        Deprecated.
        Use getColumns() instead.
        Gets the terminal width in characters.
        Returns:
        the width in characters
      • getHeight

        @Deprecated
        public int getHeight()
        Deprecated.
        Use getRows() instead.
        Gets the terminal height in characters.
        Returns:
        the height in characters
      • setSize

        public boolean setSize​(Sized sized)
        Resize the terminal to the specified columns and rows.
        Parameters:
        sized - the new Size whose columns and rows will be applied
        Returns:
        true if the size was set successfully, false otherwise
      • setSize

        @Deprecated
        public boolean setSize​(int columns,
                               int rows)
        Deprecated.
        Use setSize(Sized) instead.
        Resize the terminal to the given number of columns and rows.
        Parameters:
        columns - the target number of columns (2?4096)
        rows - the target number of rows (2?4096)
        Returns:
        `true` if the size was changed; `false` if the requested dimensions are out of range
      • read

        public java.lang.String read()
      • pipe

        public java.lang.String pipe​(java.lang.String d)
      • write

        public boolean write​(java.lang.CharSequence d)
      • dump

        public void dump​(long[] fullscreen,
                         int ftop,
                         int fleft,
                         int fheight,
                         int fwidth,
                         int[] cursor)
      • dump

        public void dump​(long[] fullscreen,
                         int[] cursor)
        Dumps the raw screen content into a flat array. The array must be at least columns * rows elements long.
        Parameters:
        fullscreen - destination array
        cursor - 2-element array to receive cursor [x, y], or null
      • getHistory

        public java.util.List<long[]> getHistory()
        Returns a snapshot of the scrollback history: the lines that have scrolled off the top of the active screen, oldest first. Each row is encoded in the same cell format as dump(long[], int[]) (the low 32 bits hold the code point, the high 32 bits hold the attributes).

        The returned List is a copy, so it is safe to iterate while the terminal keeps processing output. The long[] rows it references are shared with the terminal and must be treated as read-only.

        Returns:
        a snapshot of the scrollback history rows, oldest first (never null)
      • getHistorySize

        public int getHistorySize()
        Returns the number of lines currently held in the scrollback history.

        Equivalent to getHistory().size() but without copying the history.

        Returns:
        the number of scrollback history lines
      • cellCodePoint

        public static int cellCodePoint​(long cell)
        Extracts the Unicode code point from a cell value. A return value of 0 indicates a continuation cell for a wide character.
        Parameters:
        cell - the 64-bit cell value from dump(long[], int[]) or getHistory()
        Returns:
        the Unicode code point stored in the cell
      • cellAttr

        public static long cellAttr​(long cell)
        Extracts the raw 32-bit attribute word from a cell value. Prefer the typed accessors (cellBold(long), cellForeground(long), etc.) over inspecting this value directly.
        Parameters:
        cell - the 64-bit cell value
        Returns:
        the upper 32 bits containing style and color information
      • cellBold

        public static boolean cellBold​(long cell)
        Returns true if the cell has the bold attribute set.
        Parameters:
        cell - the 64-bit cell value
        Returns:
        whether bold is enabled
      • cellDim

        public static boolean cellDim​(long cell)
        Returns true if the cell has the dim/faint attribute set.
        Parameters:
        cell - the 64-bit cell value
        Returns:
        whether dim is enabled
      • cellItalic

        public static boolean cellItalic​(long cell)
        Returns true if the cell has the italic attribute set.
        Parameters:
        cell - the 64-bit cell value
        Returns:
        whether italic is enabled
      • cellUnderline

        public static boolean cellUnderline​(long cell)
        Returns true if the cell has the underline attribute set.
        Parameters:
        cell - the 64-bit cell value
        Returns:
        whether underline is enabled
      • cellInverse

        public static boolean cellInverse​(long cell)
        Returns true if the cell has the inverse (negative) attribute set.
        Parameters:
        cell - the 64-bit cell value
        Returns:
        whether inverse is enabled
      • cellConceal

        public static boolean cellConceal​(long cell)
        Returns true if the cell has the conceal (hidden) attribute set.
        Parameters:
        cell - the 64-bit cell value
        Returns:
        whether conceal is enabled
      • cellHasForeground

        public static boolean cellHasForeground​(long cell)
        Returns true if the cell has an explicit foreground color set. When false, the terminal's default foreground should be used.
        Parameters:
        cell - the 64-bit cell value
        Returns:
        whether a foreground color is set
      • cellHasBackground

        public static boolean cellHasBackground​(long cell)
        Returns true if the cell has an explicit background color set. When false, the terminal's default background should be used.
        Parameters:
        cell - the 64-bit cell value
        Returns:
        whether a background color is set
      • cellForeground

        public static int cellForeground​(long cell)
        Extracts the foreground color as a 12-bit value (4 bits per r/g/b channel). Only meaningful when cellHasForeground(long) returns true. Use cellColorRgb(int) to expand to a 24-bit RGB value.
        Parameters:
        cell - the 64-bit cell value
        Returns:
        the 12-bit foreground color (0x000?0xFFF)
      • cellBackground

        public static int cellBackground​(long cell)
        Extracts the background color as a 12-bit value (4 bits per r/g/b channel). Only meaningful when cellHasBackground(long) returns true. Use cellColorRgb(int) to expand to a 24-bit RGB value.
        Parameters:
        cell - the 64-bit cell value
        Returns:
        the 12-bit background color (0x000?0xFFF)
      • cellColorRgb

        public static int cellColorRgb​(int color12)
        Expands a 12-bit color (as returned by cellForeground(long) or cellBackground(long)) to a 24-bit RGB value. Each 4-bit channel is expanded to 8 bits by replicating the nibble (e.g. 0xA ? 0xAA).
        Parameters:
        color12 - the 12-bit color value (0x000?0xFFF)
        Returns:
        the 24-bit RGB color (0x000000?0xFFFFFF)
      • dump

        public boolean dump​(long timeout,
                            boolean forceDump,
                            long[] fullscreen,
                            int ftop,
                            int fleft,
                            int fheight,
                            int fwidth,
                            int[] cursor)
                     throws java.lang.InterruptedException
        Waits for the screen to be dirty, then dumps the raw screen content into a subregion.
        Parameters:
        timeout - maximum time to wait in milliseconds
        forceDump - if true, dump even if the screen is not dirty
        fullscreen - destination array (must be at least fwidth * fheight)
        ftop - top row offset
        fleft - left column offset
        fheight - number of rows to dump
        fwidth - number of columns to dump
        cursor - 2-element array to receive cursor [x, y], or null
        Returns:
        true if the screen was dumped
        Throws:
        java.lang.InterruptedException - if interrupted
      • dump

        public boolean dump​(long timeout,
                            boolean forceDump,
                            long[] fullscreen,
                            int[] cursor)
                     throws java.lang.InterruptedException
        Waits for the screen to be dirty, then dumps the raw screen content.
        Parameters:
        timeout - maximum time to wait in milliseconds
        forceDump - if true, dump even if the screen is not dirty
        fullscreen - destination array (must be at least columns * rows)
        cursor - 2-element array to receive cursor [x, y], or null
        Returns:
        true if the screen was dumped
        Throws:
        java.lang.InterruptedException - if interrupted
      • dump

        public java.lang.String dump​(long timeout,
                                     boolean forceDump)
                              throws java.lang.InterruptedException
        Dumps the terminal content as HTML with inline RGB color styles.
        Parameters:
        timeout - maximum time to wait for changes in milliseconds
        forceDump - whether to force a dump even if screen is not dirty
        Returns:
        the terminal content as HTML, or null if no update
        Throws:
        java.lang.InterruptedException - if interrupted
      • dump

        public java.lang.String dump()
        Dumps the terminal content as HTML with inline RGB color styles.
        Returns:
        the terminal content as HTML.
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object