- 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
All Methods Instance Methods Concrete Methods 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 managersvoid
disableSGR(SGR sgr)
Deactivates anSGR
(Selected Graphic Rendition) code which has previously been activated throughenableSGR(..)
.void
enableSGR(SGR sgr)
Activates anSGR
(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 aTerminalSize
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 spaceKeyStroke
pollInput()
Returns the nextKey
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 nextKey
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 callingsetCursorPosition(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 maximizedprivate 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
-
-
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 aTerminalSize
object. Please bear in mind that depending on theTerminal
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 interfaceTerminal
- 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 interfaceExtendedTerminal
- 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 interfaceExtendedTerminal
- 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 interfaceTerminal
- 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 interfaceTerminal
- 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 anSGR
(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 interfaceTerminal
- 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 anSGR
(Selected Graphic Rendition) code which has previously been activated throughenableSGR(..)
.- Specified by:
disableSGR
in interfaceTerminal
- 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 interfaceTerminal
- 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 callmoveCursor
next. Some terminal implementations doesn't reset color and modifier state so it's also good practise to callresetColorAndSGR()
after this.- Specified by:
clearScreen
in interfaceTerminal
- 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 interfaceTerminal
- 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 interfaceTerminal
- 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 interfacejava.lang.AutoCloseable
- Specified by:
close
in interfacejava.io.Closeable
- Specified by:
close
in interfaceTerminal
- Overrides:
close
in classStreamBasedTerminal
- 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 interfaceTerminal
- Parameters:
x
- The 0-indexed column to place the cursor aty
- 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 callingsetCursorPosition(position.getColumn(), position.getRow())
- Specified by:
setCursorPosition
in interfaceTerminal
- 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 interfaceTerminal
- 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 interfaceTerminal
- Parameters:
visible
- Hides the text cursor iffalse
and shows it iftrue
- 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 nextKey
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 callpollInput()
for the non-blocking version.- Specified by:
readInput
in interfaceInputProvider
- Overrides:
readInput
in classStreamBasedTerminal
- 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 nextKey
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 interfaceInputProvider
- Overrides:
pollInput
in classStreamBasedTerminal
- 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
-
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 interfaceExtendedTerminal
-
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 interfaceExtendedTerminal
-
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 interfaceExtendedTerminal
- 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 interfaceExtendedTerminal
- 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 interfaceExtendedTerminal
- 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 interfaceExtendedTerminal
- 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 interfaceExtendedTerminal
- Parameters:
mouseCaptureMode
- Which mouse events to capture, pass innull
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 interfaceScrollable
- Parameters:
firstLine
- first line of the range to be scrolled (top line is 0)lastLine
- last (inclusive) line of the range to be scrolleddistance
- 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
-
-