Module org.jline.terminal
Package org.jline.utils

Class Display

java.lang.Object
org.jline.utils.Display
All Implemented Interfaces:
Sized
public class Display extends Object implements Sized
Manages terminal display and efficient screen updates with cursor positioning.

The Display class provides functionality for managing the display of content on the terminal screen. It handles the complexities of cursor positioning, line wrapping, and efficient screen updates to minimize the amount of data sent to the terminal.

This class supports two main modes of operation:

  • Full-screen mode - Takes over the entire terminal screen
  • Partial-screen mode - Updates only a portion of the screen, preserving content above

Key features include:

  • Efficient screen updates using cursor positioning
  • Support for multi-line content with proper wrapping
  • Handling of ANSI-styled text (colors, attributes)
  • Size-aware rendering that adapts to terminal dimensions
  • Cursor positioning relative to the display area

This class is used by various JLine components, such as LineReader, to provide efficient terminal display management for features like command-line editing, completion menus, and status messages.

Thread Safety

This class is NOT thread-safe and must be accessed from a single thread or with external synchronization. The Display class maintains mutable state including cursor position, screen content, and terminal dimensions that can be corrupted by concurrent access.

Components that use Display in multi-threaded environments (such as signal handlers for window resize events) must provide their own synchronization. For example, the LineReader uses a ReentrantLock to coordinate access between the main thread and signal handlers.

Warning: Concurrent access to Display methods may result in:

  • ConcurrentModificationException
  • Corrupted terminal output
  • Inconsistent cursor positioning
  • Race conditions in screen updates

  • Field Details

    • terminal

      protected final Terminal terminal

    • fullScreen

      protected final boolean fullScreen

    • cursorPos

      protected int cursorPos

    • columns

      protected int columns

    • columns1

      protected int columns1

    • rows

      protected int rows

    • reset

      protected boolean reset

    • delayLineWrap

      protected boolean delayLineWrap

    • cost

      protected final Map<InfoCmp.Capability,Integer> cost

    • canScroll

      protected final boolean canScroll

    • terminalWrapAtEol

      protected final boolean terminalWrapAtEol

    • terminalDelayedWrapAtEol

      protected final boolean terminalDelayedWrapAtEol

    • wrapAtEol

      protected boolean wrapAtEol

    • delayedWrapAtEol

      protected boolean delayedWrapAtEol

    • cursorDownIsNewLine

      protected final boolean cursorDownIsNewLine

  • Constructor Details

    • Display

      public Display(Terminal terminal, boolean fullscreen)
      Create a Display bound to the given Terminal and configured for either full-screen or inline (partial-screen) usage.

      Queries the terminal for capabilities and initializes internal flags that control scrolling, wrap-at-end-of-line behavior, and cursor movement semantics.

      Parameters:
      terminal - the target terminal used for rendering
      fullscreen - true to enable full-screen (application-takes-over) mode, false for partial-screen mode

  • Method Details

    • delayLineWrap

      public boolean delayLineWrap()
      If cursor is at right margin, don't wrap immediately. See org.jline.reader.LineReader.Option#DELAY_LINE_WRAP.
      Returns:
      true if line wrap is delayed, false otherwise

    • setDelayLineWrap

      public void setDelayLineWrap(boolean v)
      Enable or disable delayed line wrapping when the cursor reaches the right margin.
      Parameters:
      v - `true` to delay wrapping at end-of-line, `false` to disable delayed wrapping

    • scrollOptimization

      public boolean scrollOptimization()
      Returns whether the scroll optimization is enabled. When enabled, the display uses terminal insert/delete line capabilities to scroll content efficiently instead of redrawing all changed lines.
      Returns:
      true if scroll optimization is enabled (the default)

    • setScrollOptimization

      public void setScrollOptimization(boolean v)
      Enable or disable the scroll optimization.

      When enabled (the default), the display detects content shifts between frames and uses terminal insert/delete line capabilities to scroll content efficiently. This reduces the number of characters written but may cause visible flicker on terminals that render intermediate states (e.g. during high-FPS full-screen updates).

      Disabling the scroll optimization forces full per-line diff updates, which produces more output bytes but avoids flicker from insert/delete line intermediate states.

      Parameters:
      v - true to enable scroll optimization, false to disable it

    • resize

      public void resize(Sized sized)
      Resize the display to the dimensions specified by the given Size.
      Parameters:
      sized - the target display dimensions; its rows and columns are applied to the display

    • resize

      @Deprecated public void resize(int rows, int columns)
      Deprecated.
      Use resize(Sized) instead to avoid parameter order confusion.
      Resize the display to the specified number of rows and columns. This updates the display geometry, rewraps previously rendered lines to the new width, and adjusts wrap-at-EOL behavior based on the terminal's buffer width. If either dimension is zero the method treats it as a special case (sets rows to 1 and columns to a very large internal value) to avoid a zero-sized display.
      Parameters:
      rows - the number of display rows
      columns - the number of display columns

    • getColumns

      public int getColumns()
      Get the current display width in character cells.
      Specified by:
      getColumns in interface Sized
      Returns:
      the number of columns (display width)

    • getRows

      public int getRows()
      The current display height in character rows.
      Specified by:
      getRows in interface Sized
      Returns:
      the current number of rows

    • reset

      public void reset()
      Clears the cached model of previously rendered lines.

      The next update(java.util.List<org.jline.utils.AttributedString>, int) call will treat all content as new and repaint every line via the diff algorithm. This does not issue a terminal clear_screen; to also clear the physical screen, call clear() before reset().

    • clear

      public void clear()
      Clears the whole screen. Use this method only when using full-screen / application mode.

    • updateAnsi

      public void updateAnsi(List<String> newLines, int targetCursorPos)
      Update the display with lines containing ANSI escape sequences and flush the output.

      Each string in the list is parsed via AttributedString.fromAnsi(String) to convert ANSI escape codes into styled AttributedStrings, then delegated to update(List, int).

      Parameters:
      newLines - the new lines to display, with embedded ANSI escape sequences
      targetCursorPos - the desired cursor position after the update (0-based character offset from the start of the first line, or -1 to leave the cursor at the end)

    • update

      public void update(List<AttributedString> newLines, int targetCursorPos)
      Update the display according to the new lines and flushes the output.
      Parameters:
      newLines - the lines to display
      targetCursorPos - desired cursor position - see Size.cursorPos.

    • update

      public void update(List<AttributedString> newLines, int targetCursorPos, boolean flush)
      Update the display according to the new lines.
      Parameters:
      newLines - the lines to display
      targetCursorPos - desired cursor position - see Size.cursorPos.
      flush - whether the output should be flushed or not

    • deleteLines

      protected boolean deleteLines(int nb)
      Emits terminal control sequences to delete the specified number of lines.
      Parameters:
      nb - the number of lines to delete
      Returns:
      `true` if a delete-line capability was available and the operation was issued, `false` otherwise

    • insertLines

      protected boolean insertLines(int nb)

    • insertChars

      protected boolean insertChars(int nb)

    • deleteChars

      protected boolean deleteChars(int nb)

    • can

      protected boolean can(InfoCmp.Capability single, InfoCmp.Capability multi)

    • perform

      protected boolean perform(InfoCmp.Capability single, InfoCmp.Capability multi, int nb)
      Emits a terminal capability to affect a repeated action, using the parameterized (multi) form when available and preferable, otherwise repeating the single-capability.
      Parameters:
      single - the single-invocation capability to use repeatedly if a multi-parameter form is unavailable or not preferable
      multi - the multi-parameter capability that can perform the action for a specified count in one invocation
      nb - the number of times the action should be applied
      Returns:
      true if a capability sequence was emitted to perform the action, false if neither capability is available

    • moveVisualCursorTo

      protected void moveVisualCursorTo(int targetPos, List<AttributedString> newLines)

    • moveVisualCursorTo

      protected int moveVisualCursorTo(int i1)
      Move the visual cursor to the specified wrapped-line position without allowing movement to a right-margin target. Moves the terminal cursor from the current visual position (stored in cursorPos) to i1, handling line and column transitions, and updating cursorPos. If the current position is at the right margin a carriage return is emitted before further movement. The target position must not lie on a right-margin column (i.e. i1 % columns1 != columns).
      Parameters:
      i1 - the target visual cursor position in wrapped-line coordinates
      Returns:
      the updated cursor position (equal to i1)

    • wcwidth

      public int wcwidth(String str)
      Compute the number of terminal columns required to display a string, interpreting ANSI escape sequences.
      Parameters:
      str - the input string, which may contain ANSI escape sequences; if `null` it is treated as empty
      Returns:
      the displayed column width of the string (0 if `str` is `null`)