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
,Closeable
,AutoCloseable
- Direct Known Subclasses:
TelnetTerminal
,UnixLikeTerminal
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:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate boolean
private MouseCaptureMode
private MouseCaptureMode
-
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
ANSITerminal
(InputStream terminalInput, OutputStream terminalOutput, Charset terminalCharset) -
Method Summary
Modifier and TypeMethodDescriptionvoid
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
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
Activates anSGR
(Selected Graphic Rendition) code.void
Calling this method will, where supported, give your terminal a private area to use, separate from what was there before.void
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
Returns the position of the cursor, as reported by the terminal.protected KeyDecodingProfile
This method can be overridden in a custom terminal implementation to change the default key decoders.final TerminalSize
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
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 spaceReturns 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
Saves the current window title on a stack managed internally by the terminal.Returns the nextKey
off the input queue or blocks until one is available.(package private) void
void
Removes all currently active SGR codes and sets foreground and background colors back to default.(package private) void
(package private) void
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
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
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 Details
-
requestedMouseCaptureMode
-
mouseCaptureMode
-
inPrivateMode
private boolean inPrivateMode
-
-
Constructor Details
-
ANSITerminal
protected ANSITerminal(InputStream terminalInput, OutputStream terminalOutput, Charset terminalCharset)
-
-
Method Details
-
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
- Throws:
IOException
-
writeSGRSequenceToTerminal
- Throws:
IOException
-
writeOSCSequenceToTerminal
- Throws:
IOException
-
getTerminalSize
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:
IOException
- if there was an I/O error trying to retrieve the size of the terminal
-
findTerminalSize
- Throws:
IOException
-
setTerminalSize
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:
IOException
- If the was an underlying I/O error
-
setTitle
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:
IOException
- If the was an underlying I/O error
-
setForegroundColor
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:
IOException
- If there was an underlying I/O error
-
setBackgroundColor
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:
IOException
- If there was an underlying I/O error
-
enableSGR
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:
IOException
- If there was an underlying I/O error- See Also:
-
disableSGR
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:
IOException
- If there was an underlying I/O error- See Also:
-
resetColorAndSGR
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:
IOException
- If there was an underlying I/O error- See Also:
-
clearScreen
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:
IOException
- If there was an underlying I/O error
-
enterPrivateMode
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:
IOException
- If there was an underlying I/O error
-
exitPrivateMode
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:
IOException
- If there was an underlying I/O error
-
close
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 interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
- Specified by:
close
in interfaceTerminal
- Overrides:
close
in classStreamBasedTerminal
- Throws:
IOException
- If there was an underlying I/O error
-
setCursorPosition
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:
IOException
- If there was an underlying I/O error
-
setCursorPosition
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:
IOException
- If there was an underlying I/O error
-
getCursorPosition
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:
IOException
- In there was an underlying I/O error
-
setCursorVisible
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:
IOException
- If there was an underlying I/O error
-
readInput
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:
IOException
- Propagated error if the underlying stream gave errors
-
pollInput
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:
IOException
- Propagated error if the underlying stream gave errors
-
filterMouseEvents
-
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
Description copied from interface:ExtendedTerminal
Iconifies the terminal, this likely means minimizing the window with most window managers- Specified by:
iconify
in interfaceExtendedTerminal
- Throws:
IOException
- If the was an underlying I/O error
-
deiconify
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:
IOException
- If the was an underlying I/O error
-
maximize
Description copied from interface:ExtendedTerminal
Maximizes the terminal, so that it takes up all available space- Specified by:
maximize
in interfaceExtendedTerminal
- Throws:
IOException
- If the was an underlying I/O error
-
unmaximize
Description copied from interface:ExtendedTerminal
Restores the terminal back to its previous size, after having been maximized- Specified by:
unmaximize
in interfaceExtendedTerminal
- Throws:
IOException
- If the was an underlying I/O error
-
updateMouseCaptureMode
private void updateMouseCaptureMode(MouseCaptureMode mouseCaptureMode, char l_or_h) throws IOException - Throws:
IOException
-
setMouseCaptureMode
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:
IOException
- If the was an underlying I/O error
-
scrollLines
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:
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
- Throws:
IOException
-
restoreCursorPosition
- Throws:
IOException
-
saveCursorPosition
- Throws:
IOException
-