Class ScrollingAWTTerminal
- All Implemented Interfaces:
InputProvider, IOSafeTerminal, Terminal, ImageObserver, MenuContainer, Closeable, Serializable, AutoCloseable
AWTTerminal with a scrollbar, effectively implementing a
pseudo-terminal with scrollback history. You can choose the same parameters are for AWTTerminal, they are
forwarded, this class mostly deals with linking the AWTTerminal with the scrollbar and having them update
each other.- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate classprivate classNested classes/interfaces inherited from class Container
Container.AccessibleAWTContainerNested classes/interfaces inherited from class Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final AWTTerminalprivate final Scrollbarprivate booleanFields inherited from class Component
accessibleContext, BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENTFields inherited from interface ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH -
Constructor Summary
ConstructorsConstructorDescriptionCreates a newScrollingAWTTerminalwith all default optionsScrollingAWTTerminal(TerminalEmulatorDeviceConfiguration deviceConfiguration, SwingTerminalFontConfiguration fontConfiguration, TerminalEmulatorColorConfiguration colorConfiguration) Creates a newScrollingAWTTerminalwith customizable settings. -
Method Summary
Modifier and TypeMethodDescriptionvoidTakes a KeyStroke and puts it on the input queue of the terminal emulator.voidaddResizeListener(TerminalResizeListener listener) Adds aTerminalResizeListenerto be called when the terminal has changed size.voidbell()Prints 0x7 to the terminal, which will make the terminal (emulator) ring a bell (or more likely beep).voidRemoves all the characters, colors and graphics from the screen and leaves you with a big empty space.voidclose()Closes the terminal, if applicable.voiddisableSGR(SGR sgr) Deactivates anSGR(Selected Graphic Rendition) code which has previously been activated throughenableSGR(..).voidActivates anSGR(Selected Graphic Rendition) code.byte[]enquireTerminal(int timeout, TimeUnit timeoutUnit) Retrieves optional information from the terminal by printing the ENQ (\u005) character.voidCalling this method will, where supported, give your terminal a private area to use, separate from what was there before.voidIf 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.voidflush()Callsflush()on the underlyingOutputStreamobject, or whatever other implementation this terminal is built around.Returns the position of the cursor, as reported by the terminal.Returns the size of the terminal, expressed as aTerminalSizeobject.Creates a new TextGraphics object that uses this Terminal directly when outputting.////////voidputCharacter(char c) Prints one character to the terminal at the current cursor location.voidPrints a string to the terminal at the current cursor location.Returns the nextKeyoff the input queue or blocks until one is available.voidremoveResizeListener(TerminalResizeListener listener) Removes aTerminalResizeListenerfrom the list of listeners to be notified when the terminal has changed sizevoidRemoves all currently active SGR codes and sets foreground and background colors back to default.voidsetBackgroundColor(TextColor color) Changes the background color for all the following characters put to the terminal.voidsetCursorPosition(int x, int y) Moves the text cursor to a new location on the terminal.voidsetCursorPosition(TerminalPosition position) Same as callingsetCursorPosition(position.getColumn(), position.getRow())voidsetCursorVisible(boolean visible) Hides or shows the text cursor, but not all terminal (-emulators) supports this.voidsetForegroundColor(TextColor color) Changes the foreground color for all the following characters put to the terminal.Methods inherited from class Container
add, add, add, add, add, addContainerListener, addImpl, addNotify, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getInsets, getLayout, getListeners, getMaximumSize, getMinimumSize, getMousePosition, getPreferredSize, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, isValidateRoot, layout, list, list, locate, minimumSize, paint, paintComponents, paramString, preferredSize, print, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, removeNotify, setComponentZOrder, setFocusCycleRoot, setFocusTraversalKeys, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setFont, setLayout, transferFocusDownCycle, update, validate, validateTreeMethods inherited from class Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getAccessibleContext, getBackground, getBaseline, getBaselineResizeBehavior, getBounds, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getGraphicsConfiguration, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, requestFocusInWindow, reshape, resize, resize, revalidate, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeysEnabled, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setMixingCutoutShape, setName, setPreferredSize, setSize, setSize, setVisible, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle
-
Field Details
-
awtTerminal
-
scrollBar
-
scrollModelUpdateBySystem
private volatile boolean scrollModelUpdateBySystem
-
-
Constructor Details
-
ScrollingAWTTerminal
public ScrollingAWTTerminal()Creates a newScrollingAWTTerminalwith all default options -
ScrollingAWTTerminal
public ScrollingAWTTerminal(TerminalEmulatorDeviceConfiguration deviceConfiguration, SwingTerminalFontConfiguration fontConfiguration, TerminalEmulatorColorConfiguration colorConfiguration) Creates a newScrollingAWTTerminalwith customizable settings.- Parameters:
deviceConfiguration- How to configure the terminal virtual devicefontConfiguration- What kind of fonts to usecolorConfiguration- Which color schema to use for ANSI colors
-
-
Method Details
-
addInput
Takes a KeyStroke and puts it on the input queue of the terminal emulator. This way you can insert synthetic input events to be processed as if they came from the user typing on the keyboard.- Parameters:
keyStroke- Key stroke input event to put on the queue
-
pollInput
////////- Specified by:
pollInputin interfaceInputProvider- Specified by:
pollInputin interfaceIOSafeTerminal- Returns:
- Key object which represents a keystroke coming in through the input stream
-
readInput
Description copied from interface:InputProviderReturns the nextKeyoff 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:
readInputin interfaceInputProvider- Specified by:
readInputin interfaceIOSafeTerminal- Returns:
- Key object which represents a keystroke coming in through the input stream
-
enterPrivateMode
public void enterPrivateMode()Description copied from interface:TerminalCalling 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:
enterPrivateModein interfaceIOSafeTerminal- Specified by:
enterPrivateModein interfaceTerminal
-
exitPrivateMode
public void exitPrivateMode()Description copied from interface:TerminalIf 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:
exitPrivateModein interfaceIOSafeTerminal- Specified by:
exitPrivateModein interfaceTerminal
-
clearScreen
public void clearScreen()Description copied from interface:TerminalRemoves 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 callmoveCursornext. Some terminal implementations doesn't reset color and modifier state so it's also good practise to callresetColorAndSGR()after this.- Specified by:
clearScreenin interfaceIOSafeTerminal- Specified by:
clearScreenin interfaceTerminal
-
setCursorPosition
public void setCursorPosition(int x, int y) Description copied from interface:TerminalMoves 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:
setCursorPositionin interfaceIOSafeTerminal- Specified by:
setCursorPositionin interfaceTerminal- Parameters:
x- The 0-indexed column to place the cursor aty- The 0-indexed row to place the cursor at
-
setCursorPosition
Description copied from interface:TerminalSame as callingsetCursorPosition(position.getColumn(), position.getRow())- Specified by:
setCursorPositionin interfaceIOSafeTerminal- Specified by:
setCursorPositionin interfaceTerminal- Parameters:
position- Position to place the cursor at
-
getCursorPosition
Description copied from interface:TerminalReturns 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:
getCursorPositionin interfaceIOSafeTerminal- Specified by:
getCursorPositionin interfaceTerminal- Returns:
- Position of the cursor
-
setCursorVisible
public void setCursorVisible(boolean visible) Description copied from interface:TerminalHides 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:
setCursorVisiblein interfaceIOSafeTerminal- Specified by:
setCursorVisiblein interfaceTerminal- Parameters:
visible- Hides the text cursor iffalseand shows it iftrue
-
putCharacter
public void putCharacter(char c) Description copied from interface:TerminalPrints 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 toputCharacterwill 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
Terminalimplementations bundled with Lanterna will).- Specified by:
putCharacterin interfaceIOSafeTerminal- Specified by:
putCharacterin interfaceTerminal- Parameters:
c- Character to place on the terminal
-
putString
Description copied from interface:TerminalPrints 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 toputStringwill 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
Terminalimplementations 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.
- Specified by:
putStringin interfaceIOSafeTerminal- Specified by:
putStringin interfaceTerminal- Parameters:
string- String to place on the terminal
-
newTextGraphics
Description copied from interface:TerminalCreates a new TextGraphics object that uses this Terminal directly when outputting. Keep in mind that you are probably better off to switch to a Screen to make advanced text graphics more efficient. Also, this TextGraphics implementation will not call.flush()after any operation, so you'll need to do that on your own.- Specified by:
newTextGraphicsin interfaceTerminal- Returns:
- TextGraphics implementation that draws directly using this Terminal interface
-
enableSGR
Description copied from interface:TerminalActivates 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:
enableSGRin interfaceIOSafeTerminal- Specified by:
enableSGRin interfaceTerminal- Parameters:
sgr- SGR code to apply- See Also:
-
disableSGR
Description copied from interface:TerminalDeactivates anSGR(Selected Graphic Rendition) code which has previously been activated throughenableSGR(..).- Specified by:
disableSGRin interfaceIOSafeTerminal- Specified by:
disableSGRin interfaceTerminal- Parameters:
sgr- SGR code to apply- See Also:
-
resetColorAndSGR
public void resetColorAndSGR()Description copied from interface:TerminalRemoves all currently active SGR codes and sets foreground and background colors back to default.- Specified by:
resetColorAndSGRin interfaceIOSafeTerminal- Specified by:
resetColorAndSGRin interfaceTerminal- See Also:
-
setForegroundColor
Description copied from interface:TerminalChanges 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:
setForegroundColorin interfaceIOSafeTerminal- Specified by:
setForegroundColorin interfaceTerminal- Parameters:
color- Color to use for foreground
-
setBackgroundColor
Description copied from interface:TerminalChanges 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:
setBackgroundColorin interfaceIOSafeTerminal- Specified by:
setBackgroundColorin interfaceTerminal- Parameters:
color- Color to use for the background
-
getTerminalSize
Description copied from interface:TerminalReturns the size of the terminal, expressed as aTerminalSizeobject. Please bear in mind that depending on theTerminalimplementation, 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:
getTerminalSizein interfaceIOSafeTerminal- Specified by:
getTerminalSizein interfaceTerminal- Returns:
- Size of the terminal
-
enquireTerminal
Description copied from interface:TerminalRetrieves 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.- Specified by:
enquireTerminalin interfaceIOSafeTerminal- Specified by:
enquireTerminalin interfaceTerminal- 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).timeoutUnit- What unit to use when interpreting thetimeoutparameter- Returns:
- Answer-back message from the terminal or empty if there was nothing
-
bell
public void bell()Description copied from interface:TerminalPrints 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.- Specified by:
bellin interfaceIOSafeTerminal- Specified by:
bellin interfaceTerminal
-
flush
public void flush()Description copied from interface:TerminalCallsflush()on the underlyingOutputStreamobject, 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.- Specified by:
flushin interfaceIOSafeTerminal- Specified by:
flushin interfaceTerminal
-
close
public void close()Description copied from interface:TerminalCloses 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:
closein interfaceAutoCloseable- Specified by:
closein interfaceCloseable- Specified by:
closein interfaceIOSafeTerminal- Specified by:
closein interfaceTerminal
-
addResizeListener
Description copied from interface:TerminalAdds aTerminalResizeListenerto be called when the terminal has changed size. There is no guarantee that this listener will really be invoked when the terminal has changed size, at all depends on the terminal emulator implementation. Normally on Unix systems the WINCH signal will be sent to the process and lanterna can intercept this.There are no guarantees on what thread the call will be made on, so please be careful with what kind of operation you perform in this callback. You should probably not take too long to return.
- Specified by:
addResizeListenerin interfaceTerminal- Parameters:
listener- Listener object to be called when the terminal has been changed- See Also:
-
removeResizeListener
Description copied from interface:TerminalRemoves aTerminalResizeListenerfrom the list of listeners to be notified when the terminal has changed size- Specified by:
removeResizeListenerin interfaceTerminal- Parameters:
listener- Listener object to remove- See Also:
-