Class ScreenTerminal

java.lang.Object
org.jline.utils.ScreenTerminal
All Implemented Interfaces:
Sized

public class ScreenTerminal extends 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 Details

  • Constructor Details

    • 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 Details

    • withTerminal

      public static ScreenTerminal.VirtualTerminal withTerminal(String name, String type, int width, int height) throws 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:
      IOException - if an I/O error occurs while creating the terminal
    • wireTerminal

      public static void wireTerminal(ScreenTerminal screen, LineDisciplineTerminal terminal, ScreenTerminalOutputStream.DelegateOutputStream delegate)
      Wires an existing ScreenTerminal to an existing LineDisciplineTerminal whose masterOutput is a ScreenTerminalOutputStream.DelegateOutputStream.

      After this call the delegate's real target is a ScreenTerminalOutputStream that decodes bytes into the screen and feeds VT100 responses back as terminal input through LineDisciplineTerminal.processInputByte(int) and LineDisciplineTerminal.processInputBytes(byte[], int, int).

      This is useful when the terminal or screen are subclassed (e.g. to override setDirty() or doClose()) and therefore cannot be created by withTerminal(String, String, int, int).

      Parameters:
      screen - the virtual screen
      terminal - the line-discipline terminal
      delegate - the delegate output stream passed to the terminal's constructor
    • wireTerminal

      public static void wireTerminal(ScreenTerminal screen, LineDisciplineTerminal terminal, ScreenTerminalOutputStream.DelegateOutputStream delegate, Runnable onFlush)
      Wires an existing ScreenTerminal to an existing LineDisciplineTerminal, adding a callback that is invoked every time the ScreenTerminalOutputStream is flushed.

      This overload is intended for UI terminals (e.g. Swing) that need to trigger a repaint after each flush.

      Parameters:
      screen - the virtual screen
      terminal - the line-discipline terminal
      delegate - the delegate output stream passed to the terminal's constructor
      onFlush - callback invoked after every flush() on the screen output stream
    • isDirty

      public boolean isDirty()
    • waitDirty

      public void waitDirty() throws InterruptedException
      Throws:
      InterruptedException
    • waitDirty

      public boolean waitDirty(long timeout) throws 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:
      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 String read()
    • pipe

      public String pipe(String d)
    • write

      public boolean write(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 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 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:
      InterruptedException - if interrupted
    • dump

      public boolean dump(long timeout, boolean forceDump, long[] fullscreen, int[] cursor) throws 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:
      InterruptedException - if interrupted
    • dump

      public String dump(long timeout, boolean forceDump) throws 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:
      InterruptedException - if interrupted
    • dump

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

      public String toString()
      Overrides:
      toString in class Object