Class StreamBasedTerminal
- All Implemented Interfaces:
InputProvider
,Terminal
,Closeable
,AutoCloseable
- Direct Known Subclasses:
ANSITerminal
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final InputDecoder
private TerminalPosition
private final Lock
private final Charset
private final InputStream
private final OutputStream
private static final Charset
-
Constructor Summary
ConstructorsConstructorDescriptionStreamBasedTerminal
(InputStream terminalInput, OutputStream terminalOutput, Charset terminalCharset) -
Method Summary
Modifier and TypeMethodDescriptionvoid
bell()
Prints 0x7 to the terminal, which will make the terminal (emulator) ring a bell (or more likely beep).void
close()
Closes the terminal, if applicable.private byte[]
convertToCharset
(char input) private byte[]
convertToVT100
(char code) byte[]
enquireTerminal
(int timeout, TimeUnit timeoutTimeUnit) Retrieves optional information from the terminal by printing the ENQ (\u005) character.void
flush()
Callsflush()
on the underlyingOutputStream
object, or whatever other implementation this terminal is built around.protected Charset
Returns theInputDecoder
attached to thisStreamBasedTerminal
.Returns the nextKey
off the input queue or null if there is no more input events available.void
putCharacter
(char c) Prints one character to the terminal at the current cursor location.void
Prints a string to the terminal at the current cursor location.Returns the nextKey
off the input queue or blocks until one is available.private KeyStroke
readInput
(boolean blocking, boolean useKeyQueue) (package private) void
Used by the cursor reporting methods to reset any previous position memorized, so we're guaranteed to return the next reported positionprotected byte[]
translateCharacter
(char input) (package private) TerminalPosition
Waits for up to 5 seconds for a terminal cursor position report to appear in the input stream.protected void
writeToTerminal
(byte... bytes) This method will write a list of bytes directly to the output stream of the terminal.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
clearScreen, disableSGR, enableSGR, enterPrivateMode, exitPrivateMode, getCursorPosition, getTerminalSize, resetColorAndSGR, setBackgroundColor, setCursorPosition, setCursorPosition, setCursorVisible, setForegroundColor
-
Field Details
-
UTF8_REFERENCE
-
terminalInput
-
terminalOutput
-
terminalCharset
-
inputDecoder
-
keyQueue
-
readLock
-
lastReportedCursorPosition
-
-
Constructor Details
-
StreamBasedTerminal
public StreamBasedTerminal(InputStream terminalInput, OutputStream terminalOutput, Charset terminalCharset)
-
-
Method Details
-
putCharacter
Prints one character to the terminal at the current cursor location. Please note that the cursor will then move one column to the right, so multiple calls toputCharacter
will print out a text string without the need to reposition the text cursor. If you reach the end of the line while putting characters using this method, you can expect the text cursor to move to the beginning of the next line.You can output CJK (Chinese, Japanese, Korean) characters (as well as other regional scripts) but remember that the terminal that the user is using might not have the required font to render it. Also worth noticing is that CJK (and some others) characters tend to take up 2 columns per character, simply because they are a square in their construction as opposed to the somewhat rectangular shape we fit latin characters in. As it's very difficult to create a monospace font for CJK with a 2:1 height-width proportion, it seems like the implementers back in the days simply gave up and made each character take 2 column. It causes issues for the random terminal programmer because you can't really trust 1 character = 1 column, but I suppose it's "しょうがない". If you try to print non-printable control characters, the terminal is likely to ignore them (all
Terminal
implementations bundled with Lanterna will). TheStreamBasedTerminal
class will attempt to translate some unicode characters to VT100 if the encoding attached to thisTerminal
isn't UTF-8.- Parameters:
c
- Character to place on the terminal- Throws:
IOException
- If there was an underlying I/O error
-
putString
Prints a string to the terminal at the current cursor location. Please note that the cursor will then move one column to the right, so multiple calls toputString
will print out a text string without the need to reposition the text cursor. If you reach the end of the line while putting characters using this method, you can expect the text cursor to move to the beginning of the next line.You can output CJK (Chinese, Japanese, Korean) characters (as well as other regional scripts) but remember that the terminal that the user is using might not have the required font to render it. Also worth noticing is that CJK (and some others) characters tend to take up 2 columns per character, simply because they are a square in their construction as opposed to the somewhat rectangular shape we fit latin characters in. As it's very difficult to create a monospace font for CJK with a 2:1 height-width proportion, it seems like the implementers back in the days simply gave up and made each character take 2 column. It causes issues for the random terminal programmer because you can't really trust 1 character = 1 column, but I suppose it's "しょうがない".
If you try to print non-printable control characters, the terminal is likely to ignore them (all
Terminal
implementations bundled with Lanterna will).You can use this method to place emoji characters on the terminal, since they take up more than one char with Java's built-in UTF16 encoding. The
StreamBasedTerminal
class will attempt to translate some unicode characters to VT100 if the encoding attached to thisTerminal
isn't UTF-8.- Parameters:
string
- String to place on the terminal- Throws:
IOException
- If there was an underlying I/O error
-
writeToTerminal
This method will write a list of bytes directly to the output stream of the terminal.- Parameters:
bytes
- Bytes to write to the terminal (synchronized)- Throws:
IOException
- If there was an underlying I/O error
-
enquireTerminal
Description copied from interface:Terminal
Retrieves optional information from the terminal by printing the ENQ (\u005) character. Terminals and terminal emulators may or may not respond to this command, sometimes it's configurable.- Parameters:
timeout
- How long to wait for the talk-back message, if there's nothing immediately available on the input stream, you should probably set this to a somewhat small value to prevent unnecessary blockage on the input stream but large enough to accommodate a round-trip to the user's terminal (~300 ms if you are connection across the globe).timeoutTimeUnit
- What unit to use when interpreting thetimeout
parameter- Returns:
- Answer-back message from the terminal or empty if there was nothing
- Throws:
IOException
- If there was an I/O error while trying to read the enquiry reply
-
bell
Description copied from interface:Terminal
Prints 0x7 to the terminal, which will make the terminal (emulator) ring a bell (or more likely beep). Not all terminals implements this. Wikipedia has more details.- Throws:
IOException
- If there was an underlying I/O error
-
getInputDecoder
Returns theInputDecoder
attached to thisStreamBasedTerminal
. Can be used to add additional character patterns to recognize and tune the way input is turned inKeyStroke
:s.- Returns:
InputDecoder
attached to thisStreamBasedTerminal
-
resetMemorizedCursorPosition
void resetMemorizedCursorPosition()Used by the cursor reporting methods to reset any previous position memorized, so we're guaranteed to return the next reported position -
waitForCursorPositionReport
Waits for up to 5 seconds for a terminal cursor position report to appear in the input stream. If the timeout expires, it will return null. You should have sent the cursor position query already before calling this method.- Returns:
- Current position of the cursor, or null if the terminal didn't report it in time.
- Throws:
IOException
- If there was an I/O error
-
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.- Returns:
- Key object which represents a keystroke coming in through the input stream
- Throws:
IOException
- Propagated error if the underlying stream gave errors
-
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.- Returns:
- Key object which represents a keystroke coming in through the input stream
- Throws:
IOException
- Propagated error if the underlying stream gave errors
-
readInput
- Throws:
IOException
-
flush
Description copied from interface:Terminal
Callsflush()
on the underlyingOutputStream
object, or whatever other implementation this terminal is built around. Some implementing classes of this interface (like SwingTerminal) doesn't do anything as it doesn't really apply to them.- 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.- Throws:
IOException
- If there was an underlying I/O error
-
getCharset
-
translateCharacter
protected byte[] translateCharacter(char input) -
convertToVT100
private byte[] convertToVT100(char code) -
convertToCharset
private byte[] convertToCharset(char input)
-