Module com.googlecode.lanterna

Package com.googlecode.lanterna.terminal.ansi

Class ANSITerminal

java.lang.Object

com.googlecode.lanterna.terminal.AbstractTerminal

com.googlecode.lanterna.terminal.ansi.StreamBasedTerminal

com.googlecode.lanterna.terminal.ansi.ANSITerminal

All Implemented Interfaces:

Scrollable, InputProvider, ExtendedTerminal, Terminal, java.io.Closeable, java.lang.AutoCloseable

Direct Known Subclasses:

TelnetTerminal, UnixLikeTerminal

public abstract class ANSITerminal
extends StreamBasedTerminal
implements ExtendedTerminal

Class containing graphics code for ANSI compliant text terminals and terminal emulators. All the methods inside of this class uses ANSI escape codes written to the underlying output stream.

See Also:

Wikipedia

Field Summary

Fields

Modifier and Type	Field	Description
private boolean	inPrivateMode
private MouseCaptureMode	mouseCaptureMode
private MouseCaptureMode	requestedMouseCaptureMode

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	ANSITerminal(java.io.InputStream terminalInput, java.io.OutputStream terminalOutput, java.nio.charset.Charset terminalCharset)

Method Summary

Modifier and Type	Method	Description
void	clearScreen()	Removes all the characters, colors and graphics from the screen and leaves you with a big empty space.
void	close()	Closes the terminal, if applicable.
void	deiconify()	De-iconifies the terminal, which likely means restoring it from minimized state with most window managers
void	disableSGR(SGR sgr)	Deactivates an SGR (Selected Graphic Rendition) code which has previously been activated through enableSGR(..).
void	enableSGR(SGR sgr)	Activates an SGR (Selected Graphic Rendition) code.
void	enterPrivateMode()	Calling this method will, where supported, give your terminal a private area to use, separate from what was there before.
void	exitPrivateMode()	If you have previously entered private mode, this method will exit this and, depending on implementation, maybe restore what the terminal looked like before private mode was entered.
private KeyStroke	filterMouseEvents(KeyStroke keyStroke)
protected TerminalSize	findTerminalSize()
TerminalPosition	getCursorPosition()	Returns the position of the cursor, as reported by the terminal.
protected KeyDecodingProfile	getDefaultKeyDecodingProfile()	This method can be overridden in a custom terminal implementation to change the default key decoders.
TerminalSize	getTerminalSize()	Returns the size of the terminal, expressed as a TerminalSize object.
void	iconify()	Iconifies the terminal, this likely means minimizing the window with most window managers
(package private) boolean	isInPrivateMode()	Method to test if the terminal (as far as the library knows) is in private mode.
void	maximize()	Maximizes the terminal, so that it takes up all available space
KeyStroke	pollInput()	Returns the next Key off the input queue or null if there is no more input events available.
void	popTitle()	Replaces the terminal title with the top element from the title stack managed by the terminal (the element is removed from the stack as expected)
void	pushTitle()	Saves the current window title on a stack managed internally by the terminal.
KeyStroke	readInput()	Returns the next Key off the input queue or blocks until one is available.
(package private) void	reportPosition()
void	resetColorAndSGR()	Removes all currently active SGR codes and sets foreground and background colors back to default.
(package private) void	restoreCursorPosition()
(package private) void	saveCursorPosition()
void	scrollLines(int firstLine, int lastLine, int distance)	Scroll a range of lines of this Scrollable according to given distance.
void	setBackgroundColor(TextColor color)	Changes the background color for all the following characters put to the terminal.
void	setCursorPosition(int x, int y)	Moves the text cursor to a new location on the terminal.
void	setCursorPosition(TerminalPosition position)	Same as calling setCursorPosition(position.getColumn(), position.getRow())
void	setCursorVisible(boolean visible)	Hides or shows the text cursor, but not all terminal (-emulators) supports this.
void	setForegroundColor(TextColor color)	Changes the foreground color for all the following characters put to the terminal.
void	setMouseCaptureMode(MouseCaptureMode mouseCaptureMode)	Enabled or disables capturing of mouse event.
void	setTerminalSize(int columns, int rows)	Attempts to resize the terminal through dtterm extensions "CSI 8 ; rows ; columns ; t".
void	setTitle(java.lang.String title)	This methods sets the title of the terminal, which is normally only visible if you are running the application in a terminal emulator in a graphical environment.
void	unmaximize()	Restores the terminal back to its previous size, after having been maximized
private void	updateMouseCaptureMode(MouseCaptureMode mouseCaptureMode, char l_or_h)
private void	writeCSISequenceToTerminal(byte... tail)
private void	writeOSCSequenceToTerminal(byte... tail)
private void	writeSGRSequenceToTerminal(byte... sgrParameters)

Methods inherited from class com.googlecode.lanterna.terminal.ansi.StreamBasedTerminal

bell, enquireTerminal, flush, getCharset, getInputDecoder, putCharacter, putString, resetMemorizedCursorPosition, translateCharacter, waitForCursorPositionReport, writeToTerminal

Methods inherited from class com.googlecode.lanterna.terminal.AbstractTerminal

addResizeListener, newTextGraphics, onResized, onResized, removeResizeListener

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.googlecode.lanterna.terminal.Terminal

addResizeListener, bell, enquireTerminal, flush, newTextGraphics, putCharacter, putString, removeResizeListener

Field Detail

requestedMouseCaptureMode

private MouseCaptureMode requestedMouseCaptureMode

mouseCaptureMode

private MouseCaptureMode mouseCaptureMode

inPrivateMode

private boolean inPrivateMode

Constructor Detail

ANSITerminal

protected ANSITerminal(java.io.InputStream terminalInput,
                       java.io.OutputStream terminalOutput,
                       java.nio.charset.Charset terminalCharset)

Method Detail

getDefaultKeyDecodingProfile

protected KeyDecodingProfile getDefaultKeyDecodingProfile()

This method can be overridden in a custom terminal implementation to change the default key decoders.

Returns:

The KeyDecodingProfile used by the terminal when translating character sequences to keystrokes

writeCSISequenceToTerminal

private void writeCSISequenceToTerminal(byte... tail)
                                 throws java.io.IOException

Throws:

java.io.IOException

writeSGRSequenceToTerminal

private void writeSGRSequenceToTerminal(byte... sgrParameters)
                                 throws java.io.IOException

Throws:

java.io.IOException

writeOSCSequenceToTerminal

private void writeOSCSequenceToTerminal(byte... tail)
                                 throws java.io.IOException

Throws:

java.io.IOException

getTerminalSize

public final TerminalSize getTerminalSize()
                                   throws java.io.IOException

Description copied from interface: Terminal

Returns the size of the terminal, expressed as a TerminalSize object. Please bear in mind that depending on the Terminal implementation, this may or may not be accurate. See the implementing classes for more information. Most commonly, calling getTerminalSize() will involve some kind of hack to retrieve the size of the terminal, like moving the cursor to position 5000x5000 and then read back the location, unless the terminal implementation has a more smooth way of getting this data. Keep this in mind and see if you can avoid calling this method too often. There is a helper class, SimpleTerminalResizeListener, that you can use to cache the size and update it only when resize events are received (which depends on if a resize is detectable, which they are not on all platforms).

Specified by:

getTerminalSize in interface Terminal

Returns:

Size of the terminal

Throws:

java.io.IOException - if there was an I/O error trying to retrieve the size of the terminal

findTerminalSize

protected TerminalSize findTerminalSize()
                                 throws java.io.IOException

Throws:

java.io.IOException

setTerminalSize

public void setTerminalSize(int columns,
                            int rows)
                     throws java.io.IOException

Description copied from interface: ExtendedTerminal

Attempts to resize the terminal through dtterm extensions "CSI 8 ; rows ; columns ; t". This isn't widely supported, which is why the method is not exposed through the common Terminal interface.

Specified by:

setTerminalSize in interface ExtendedTerminal

Parameters:

columns - New size (columns)

rows - New size (rows)

Throws:

java.io.IOException - If the was an underlying I/O error

setTitle

public void setTitle(java.lang.String title)
              throws java.io.IOException

Description copied from interface: ExtendedTerminal

This methods sets the title of the terminal, which is normally only visible if you are running the application in a terminal emulator in a graphical environment.

Specified by:

setTitle in interface ExtendedTerminal

Parameters:

title - Title to set on the terminal

Throws:

java.io.IOException - If the was an underlying I/O error

setForegroundColor

public void setForegroundColor(TextColor color)
                        throws java.io.IOException

Description copied from interface: Terminal

Changes the foreground color for all the following characters put to the terminal. The foreground color is what color to draw the text in, as opposed to the background color which is the color surrounding the characters.

This overload is using the TextColor class to define a color, which is a layer of abstraction above the three different color formats supported (ANSI, indexed and RGB). The other setForegroundColor(..) overloads gives you direct access to set one of those three.

Note to implementers of this interface, just make this method call color.applyAsForeground(this);

Specified by:

setForegroundColor in interface Terminal

Parameters:

color - Color to use for foreground

Throws:

java.io.IOException - If there was an underlying I/O error

setBackgroundColor

public void setBackgroundColor(TextColor color)
                        throws java.io.IOException

Description copied from interface: Terminal

Changes the background color for all the following characters put to the terminal. The background color is the color surrounding the text being printed.

This overload is using the TextColor class to define a color, which is a layer of abstraction above the three different color formats supported (ANSI, indexed and RGB). The other setBackgroundColor(..) overloads gives you direct access to set one of those three.

Note to implementers of this interface, just make this method call color.applyAsBackground(this);

Specified by:

setBackgroundColor in interface Terminal

Parameters:

color - Color to use for the background

Throws:

java.io.IOException - If there was an underlying I/O error

enableSGR

public void enableSGR(SGR sgr)
               throws java.io.IOException

Description copied from interface: Terminal

Activates an SGR (Selected Graphic Rendition) code. This code modifies a state inside the terminal that will apply to all characters written afterwards, such as bold, italic, blinking code and so on.

Specified by:

enableSGR in interface Terminal

Parameters:

sgr - SGR code to apply

Throws:

java.io.IOException - If there was an underlying I/O error

See Also:

SGR, http://www.vt100.net/docs/vt510-rm/SGR

disableSGR

public void disableSGR(SGR sgr)
                throws java.io.IOException

Description copied from interface: Terminal

Deactivates an SGR (Selected Graphic Rendition) code which has previously been activated through enableSGR(..).

Specified by:

disableSGR in interface Terminal

Parameters:

sgr - SGR code to apply

Throws:

java.io.IOException - If there was an underlying I/O error

See Also:

SGR, http://www.vt100.net/docs/vt510-rm/SGR

resetColorAndSGR

public void resetColorAndSGR()
                      throws java.io.IOException

Description copied from interface: Terminal

Removes all currently active SGR codes and sets foreground and background colors back to default.

Specified by:

resetColorAndSGR in interface Terminal

Throws:

java.io.IOException - If there was an underlying I/O error

See Also:

SGR, http://www.vt100.net/docs/vt510-rm/SGR

clearScreen

public void clearScreen()
                 throws java.io.IOException

Description copied from interface: Terminal

Removes all the characters, colors and graphics from the screen and leaves you with a big empty space. Text cursor position is undefined after this call (depends on platform and terminal) so you should always call moveCursor next. Some terminal implementations doesn't reset color and modifier state so it's also good practise to call resetColorAndSGR() after this.

Specified by:

clearScreen in interface Terminal

Throws:

java.io.IOException - If there was an underlying I/O error

enterPrivateMode

public void enterPrivateMode()
                      throws java.io.IOException

Description copied from interface: Terminal

Calling this method will, where supported, give your terminal a private area to use, separate from what was there before. Some terminal emulators will preserve the terminal history and restore it when you exit private mode. Some terminals will just clear the screen and put the cursor in the top-left corner. Typically, if you terminal supports scrolling, going into private mode will disable the scrolling and leave you with a fixed screen, which can be useful if you don't want to deal with what the terminal buffer will look like if the user scrolls up.

Specified by:

enterPrivateMode in interface Terminal

Throws:

java.io.IOException - If there was an underlying I/O error

exitPrivateMode

public void exitPrivateMode()
                     throws java.io.IOException

Description copied from interface: Terminal

If you have previously entered private mode, this method will exit this and, depending on implementation, maybe restore what the terminal looked like before private mode was entered. If the terminal doesn't support a secondary buffer for private mode, it will probably make a new line below the private mode and place the cursor there.

Specified by:

exitPrivateMode in interface Terminal

Throws:

java.io.IOException - If there was an underlying I/O error

close

public void close()
           throws java.io.IOException

Description copied from interface: Terminal

Closes the terminal, if applicable. If the implementation doesn't support closing the terminal, this will do nothing. The Swing/AWT emulator implementations will translate this into a dispose() call on the UI resources, the telnet implementation will hang out the connection.

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface Terminal

Overrides:

close in class StreamBasedTerminal

Throws:

java.io.IOException - If there was an underlying I/O error

setCursorPosition

public void setCursorPosition(int x,
                              int y)
                       throws java.io.IOException

Description copied from interface: Terminal

Moves the text cursor to a new location on the terminal. The top-left corner has coordinates 0 x 0 and the bottom- right corner has coordinates terminal_width-1 x terminal_height-1. You can retrieve the size of the terminal by calling getTerminalSize().

Specified by:

setCursorPosition in interface Terminal

Parameters:

x - The 0-indexed column to place the cursor at

y - The 0-indexed row to place the cursor at

Throws:

java.io.IOException - If there was an underlying I/O error

setCursorPosition

public void setCursorPosition(TerminalPosition position)
                       throws java.io.IOException

Description copied from interface: Terminal

Same as calling setCursorPosition(position.getColumn(), position.getRow())

Specified by:

setCursorPosition in interface Terminal

Parameters:

position - Position to place the cursor at

Throws:

java.io.IOException - If there was an underlying I/O error

getCursorPosition

public TerminalPosition getCursorPosition()
                                   throws java.io.IOException

Description copied from interface: Terminal

Returns the position of the cursor, as reported by the terminal. The top-left corner has coordinates 0 x 0 and the bottom-right corner has coordinates terminal_width-1 x terminal_height-1.

Specified by:

getCursorPosition in interface Terminal

Returns:

Position of the cursor

Throws:

java.io.IOException - In there was an underlying I/O error

setCursorVisible

public void setCursorVisible(boolean visible)
                      throws java.io.IOException

Description copied from interface: Terminal

Hides or shows the text cursor, but not all terminal (-emulators) supports this. The text cursor is normally a text block or an underscore, sometimes blinking, which shows the user where keyboard-entered text is supposed to show up.

Specified by:

setCursorVisible in interface Terminal

Parameters:

visible - Hides the text cursor if false and shows it if true

Throws:

java.io.IOException - If there was an underlying I/O error

readInput

public KeyStroke readInput()
                    throws java.io.IOException

Description copied from interface: InputProvider

Returns the next Key off the input queue or blocks until one is available. NOTE: In previous versions of Lanterna, this method was not blocking. From lanterna 3, it is blocking and you can call pollInput() for the non-blocking version.

Specified by:

readInput in interface InputProvider

Overrides:

readInput in class StreamBasedTerminal

Returns:

Key object which represents a keystroke coming in through the input stream

Throws:

java.io.IOException - Propagated error if the underlying stream gave errors

pollInput

public KeyStroke pollInput()
                    throws java.io.IOException

Description copied from interface: InputProvider

Returns the next Key off the input queue or null if there is no more input events available. Note, this method call is not blocking, it returns null immediately if there is nothing on the input stream.

Specified by:

pollInput in interface InputProvider

Overrides:

pollInput in class StreamBasedTerminal

Returns:

Key object which represents a keystroke coming in through the input stream

Throws:

java.io.IOException - Propagated error if the underlying stream gave errors

filterMouseEvents

private KeyStroke filterMouseEvents(KeyStroke keyStroke)

pushTitle

public void pushTitle()

Description copied from interface: ExtendedTerminal

Saves the current window title on a stack managed internally by the terminal.

Specified by:

pushTitle in interface ExtendedTerminal

popTitle

public void popTitle()

Description copied from interface: ExtendedTerminal

Replaces the terminal title with the top element from the title stack managed by the terminal (the element is removed from the stack as expected)

Specified by:

popTitle in interface ExtendedTerminal

iconify

public void iconify()
             throws java.io.IOException

Description copied from interface: ExtendedTerminal

Iconifies the terminal, this likely means minimizing the window with most window managers

Specified by:

iconify in interface ExtendedTerminal

Throws:

java.io.IOException - If the was an underlying I/O error

deiconify

public void deiconify()
               throws java.io.IOException

Description copied from interface: ExtendedTerminal

De-iconifies the terminal, which likely means restoring it from minimized state with most window managers

Specified by:

deiconify in interface ExtendedTerminal

Throws:

java.io.IOException - If the was an underlying I/O error

maximize

public void maximize()
              throws java.io.IOException

Description copied from interface: ExtendedTerminal

Maximizes the terminal, so that it takes up all available space

Specified by:

maximize in interface ExtendedTerminal

Throws:

java.io.IOException - If the was an underlying I/O error

unmaximize

public void unmaximize()
                throws java.io.IOException

Description copied from interface: ExtendedTerminal

Restores the terminal back to its previous size, after having been maximized

Specified by:

unmaximize in interface ExtendedTerminal

Throws:

java.io.IOException - If the was an underlying I/O error

updateMouseCaptureMode

private void updateMouseCaptureMode(MouseCaptureMode mouseCaptureMode,
                                    char l_or_h)
                             throws java.io.IOException

Throws:

java.io.IOException

setMouseCaptureMode

public void setMouseCaptureMode(MouseCaptureMode mouseCaptureMode)
                         throws java.io.IOException

Description copied from interface: ExtendedTerminal

Enabled or disables capturing of mouse event. This is not recommended to use as most users are not familiar with the fact that terminal emulators allow capturing mouse input. You can decide which events you want to capture but be careful since different terminal emulators will support these modes differently. Mouse capture mode will be automatically disabled when the application exits through a shutdown hook.

Specified by:

setMouseCaptureMode in interface ExtendedTerminal

Parameters:

mouseCaptureMode - Which mouse events to capture, pass in null to disable mouse input capturing

Throws:

java.io.IOException - If the was an underlying I/O error

scrollLines

public void scrollLines(int firstLine,
                        int lastLine,
                        int distance)
                 throws java.io.IOException

Description copied from interface: Scrollable

Scroll a range of lines of this Scrollable according to given distance. If scroll-range is empty (firstLine > lastLine || distance == 0) then this method does nothing. Lines that are scrolled away from are cleared. If absolute value of distance is equal or greater than number of lines in range, then all lines within the range will be cleared.

Specified by:

scrollLines in interface Scrollable

Parameters:

firstLine - first line of the range to be scrolled (top line is 0)

lastLine - last (inclusive) line of the range to be scrolled

distance - if > 0: move lines up, else if < 0: move lines down.

Throws:

java.io.IOException - If there was an I/O error when running the operation

isInPrivateMode

boolean isInPrivateMode()

Method to test if the terminal (as far as the library knows) is in private mode.

Returns:

True if there has been a call to enterPrivateMode() but not yet exitPrivateMode()

reportPosition

void reportPosition()
             throws java.io.IOException

Throws:

java.io.IOException

restoreCursorPosition

void restoreCursorPosition()
                    throws java.io.IOException

Throws:

java.io.IOException

saveCursorPosition

void saveCursorPosition()
                 throws java.io.IOException

Throws:

java.io.IOException