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 Summary

Fields

Modifier and Type	Field	Description
protected final boolean	canScroll
protected int	columns
protected int	columns1
protected final Map<InfoCmp.Capability,Integer>	cost
protected final boolean	cursorDownIsNewLine
protected int	cursorPos
protected boolean	delayedWrapAtEol
protected boolean	delayLineWrap
protected final boolean	fullScreen
protected final List<AttributedString>	oldLines
protected boolean	reset
protected int	rows
protected final Terminal	terminal
protected final boolean	terminalDelayedWrapAtEol
protected final boolean	terminalWrapAtEol
protected boolean	wrapAtEol

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
protected boolean	can(InfoCmp.Capability single, InfoCmp.Capability multi)
void	clear()	Clears the whole screen.
boolean	delayLineWrap()	If cursor is at right margin, don't wrap immediately.
protected boolean	deleteChars(int nb)
protected boolean	deleteLines(int nb)	Emits terminal control sequences to delete the specified number of lines.
int	getColumns()	Get the current display width in character cells.
int	getRows()	The current display height in character rows.
protected boolean	insertChars(int nb)
protected boolean	insertLines(int nb)
protected int	moveVisualCursorTo(int i1)	Move the visual cursor to the specified wrapped-line position without allowing movement to a right-margin target.
protected void	moveVisualCursorTo(int targetPos, List<AttributedString> newLines)
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.
void	reset()	Clears the cached model of previously rendered lines.
void	resize(int rows, int columns)	Deprecated. Use resize(Sized) instead to avoid parameter order confusion.
void	resize(Sized sized)	Resize the display to the dimensions specified by the given Size.
void	setDelayLineWrap(boolean v)	Enable or disable delayed line wrapping when the cursor reaches the right margin.
void	update(List<AttributedString> newLines, int targetCursorPos)	Update the display according to the new lines and flushes the output.
void	update(List<AttributedString> newLines, int targetCursorPos, boolean flush)	Update the display according to the new lines.
void	updateAnsi(List<String> newLines, int targetCursorPos)	Update the display with lines containing ANSI escape sequences and flush the output.
int	wcwidth(String str)	Compute the number of terminal columns required to display a string, interpreting ANSI escape sequences.

Methods inherited from class java.lang.Object

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

Field Details

terminal

protected final Terminal terminal

fullScreen

protected final boolean fullScreen

oldLines

protected final List<AttributedString> oldLines

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

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`)