Package org.jline.utils

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 Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    MAX_SIZE
     
    static final 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

    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.
    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)
     
    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.
    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()
     
    String
    pipe(String d)
     
    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.
    String
    toString()
     
    void
    waitDirty()
     
    boolean
    waitDirty(long timeout)
    Waits for the screen to become dirty, up to the given timeout.
    boolean
    write(CharSequence d)
     

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • 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

    • 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()

    • 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