Class DeferredTerminal
- All Implemented Interfaces:
Closeable, Flushable, AutoCloseable, Sized, Terminal
Terminal proxy that defers construction to a background thread.
Before the real terminal is ready, this proxy returns heuristic defaults ? not the result of real terminal detection ? so callers can produce output without blocking:
writer()? buffers output, replays through the real writer on completiongetType()?TERMenv var;"dumb"whenNO_COLORis set orTERM=dumb; on Windows withoutTERM, checksWT_SESSION,ConEmuANSI=ON,ANSICON,TERM_PROGRAM=vscodefor ANSI support;"ansi"on non-Windows whenTERMis unsetgetSize()/getColumns()/getRows()?COLUMNS/LINESenv vars, defaulting to 120×40getNumericCapability(InfoCmp.Capability)formax_colors? detected fromCOLORTERM(truecolor/24bit ? 16M) andTERM(256color ? 256), defaulting to 256getPalette()? default palette (no terminal query)encoding()?Charset.defaultCharset()- Other capabilities ?
false/null
Methods that require the real terminal (signal handling, raw mode, input, cursor queries) block until construction completes.
If the process exits before the terminal is ready, close() drains buffered
output to System.out.
Obtain via TerminalBuilder.buildDeferred().
-
Nested Class Summary
Nested classes/interfaces inherited from interface Terminal
Terminal.KittyKeyboardMode, Terminal.Mode, Terminal.MouseTracking, Terminal.Signal, Terminal.SignalHandler -
Field Summary
Fields inherited from interface Terminal
TYPE_DUMB, TYPE_DUMB_COLOR -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionbooleanWhether this terminal supportsTerminal.pause()andTerminal.resume()calls.voidclose()booleanvoidbooleanecho()Returns whether the terminal is currently echoing input characters.booleanecho(boolean echo) Enables or disables echoing of input characters.encoding()Returns theCharsetthat should be used to encode characters forTerminal.input()andTerminal.output().Puts the terminal into raw mode.voidflush()Flushes any buffered output to the terminal.Returns the current terminal attributes.booleangetBooleanCapability(InfoCmp.Capability capability) Returns whether the terminal supports the specified boolean capability.Retrieve the size of the window buffer.intGet the terminal's column count.Returns the current mouse tracking mode.getCursorPosition(IntConsumer discarded) Query the terminal to report the cursor position.getName()Returns the name of this terminal.getNumericCapability(InfoCmp.Capability capability) Returns the value of the specified numeric capability for this terminal.Returns the color palette for this terminal.intgetRows()Get the terminal's visible row count.getSize()Retrieve the size of the visible windowgetStringCapability(InfoCmp.Capability capability) Returns the string value of the specified capability for this terminal.Blocks until the real terminal is ready, then returns it.getType()Returns the type of this terminal.handle(Terminal.Signal signal, Terminal.SignalHandler handler) Registers a handler for the givenTerminal.Signal.booleanReturns whether the terminal has support for focus tracking.booleanReturns whether the terminal has support for mouse tracking.input()Retrieve the input stream for this terminal.Returns theCharsetthat should be used to decode characters from the terminal input (Terminal.input()).booleanisReady()voidonComplete(Consumer<Terminal> callback) Registers a callback that runs once the real terminal is ready.output()Retrieve the output stream for this terminal.Returns theCharsetthat should be used to encode characters for the terminal output (Terminal.output()).voidpause()Temporarily stops reading the input stream.voidpause(boolean wait) Stop reading the input stream and optionally wait for the underlying threads to finish.booleanpaused()Check whether the terminal is currently reading the input stream or not.booleanputs(InfoCmp.Capability capability, Object... params) Outputs a terminal control string for the specified capability.voidraise(Terminal.Signal signal) Raises the specified signal, triggering any registered handlers.reader()Retrieve theReaderfor this terminal.Read a MouseEvent from the terminal input stream.readMouseEvent(String prefix) Reads and decodes a mouse event with a specified prefix that has already been consumed.readMouseEvent(IntSupplier reader) Reads and decodes a mouse event using the provided input supplier.readMouseEvent(IntSupplier reader, String prefix) Reads and decodes a mouse event using the provided input supplier with a specified prefix that has already been consumed.voidresume()Resumes reading the input stream after it has been paused.voidsetAttributes(Attributes attr) Sets the terminal attributes to the specified values.voidRequests that the terminal adopt the specified window dimensions.booleantrackFocus(boolean tracking) Enables or disables focus tracking mode.booleantrackMouse(Terminal.MouseTracking tracking) Enables or disables mouse tracking with the specified mode.writer()Retrieve theWriterfor this terminal.Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitMethods inherited from interface Terminal
beginSynchronizedUpdate, endSynchronizedUpdate, getDefaultBackgroundColor, getDefaultForegroundColor, getenv, getGraphemeClusterMode, getHeight, getWidth, hasInBandResizeSupport, hasKittyKeyboardSupport, isModeSupported, resetKittyKeyboardMode, setGraphemeClusterMode, setKittyKeyboardMode, setSize, supportsGraphemeClusterMode, synchronizedUpdate, trackInBandResize
-
Constructor Details
-
DeferredTerminal
public DeferredTerminal()
-
-
Method Details
-
onComplete
Registers a callback that runs once the real terminal is ready. If the terminal is already ready when this method is called, the callback is invoked immediately on the calling thread. Useful for wiring up AnsiConsole, LineReader, etc.Thread safety: the callback may be invoked from the build thread or the calling thread. Any mutable state captured by the callback must be safely published independently of this field.
-
complete
-
completeExceptionally
-
getTerminal
Blocks until the real terminal is ready, then returns it. -
isReady
public boolean isReady() -
writer
Description copied from interface:TerminalRetrieve theWriterfor this terminal. This is the standard way to write to this terminal.The returned writer is owned by this terminal and will be closed when the terminal is closed. Callers should not close it directly.
-
getType
Description copied from interface:TerminalReturns the type of this terminal.The terminal type is a string identifier that describes the terminal's capabilities and behavior. Common terminal types include "xterm", "vt100", "ansi", and "dumb". This type is often used to look up terminal capabilities in the terminfo database.
Special terminal types include:
Terminal.TYPE_DUMB- A terminal with minimal capabilities, typically not supporting cursor movement or colorsTerminal.TYPE_DUMB_COLOR- A dumb terminal that supports basic color output
-
getName
Description copied from interface:TerminalReturns the name of this terminal.The terminal name is typically a descriptive identifier that can be used for logging or debugging purposes. It may reflect the terminal type, connection method, or other distinguishing characteristics.
-
encoding
Description copied from interface:TerminalReturns theCharsetthat should be used to encode characters forTerminal.input()andTerminal.output().This method returns a general encoding that can be used for both input and output. For stream-specific encodings, use
Terminal.inputEncoding()andTerminal.outputEncoding(). -
getSize
-
getColumns
public int getColumns()Description copied from interface:TerminalGet the terminal's column count.- Specified by:
getColumnsin interfaceSized- Specified by:
getColumnsin interfaceTerminal- Returns:
- the number of columns in the terminal
- See Also:
-
getRows
-
getBooleanCapability
Description copied from interface:TerminalReturns whether the terminal supports the specified boolean capability.Boolean capabilities indicate whether the terminal supports specific features, such as color support, automatic margins, or status line support.
Example usage:
Terminal terminal = TerminalBuilder.terminal(); // Check if terminal supports colors if (terminal.getBooleanCapability(Capability.colors)) { // Use color output } else { // Use monochrome output }- Specified by:
getBooleanCapabilityin interfaceTerminal- Parameters:
capability- the boolean capability to check- Returns:
trueif the terminal supports the capability,falseotherwise
-
getNumericCapability
Description copied from interface:TerminalReturns the value of the specified numeric capability for this terminal.Numeric capabilities represent terminal properties with numeric values, such as the maximum number of colors supported, the number of function keys, or timing parameters for certain operations.
Example usage:
Terminal terminal = TerminalBuilder.terminal(); // Get the number of colors supported by the terminal Integer colors = terminal.getNumericCapability(Capability.max_colors); if (colors != null && colors >= 256) { // Terminal supports 256 colors }- Specified by:
getNumericCapabilityin interfaceTerminal- Parameters:
capability- the numeric capability to retrieve- Returns:
- the value of the capability, or
nullif the capability is not supported
-
getStringCapability
Description copied from interface:TerminalReturns the string value of the specified capability for this terminal.String capabilities represent terminal control sequences that can be used to perform various operations, such as moving the cursor, changing colors, clearing the screen, or ringing the bell. These sequences can be parameterized using the
Terminal.puts(Capability, Object...)method.Example usage:
Terminal terminal = TerminalBuilder.terminal(); // Get the control sequence for clearing the screen String clearScreen = terminal.getStringCapability(Capability.clear_screen); if (clearScreen != null) { // Use the sequence directly terminal.writer().print(clearScreen); terminal.flush(); }- Specified by:
getStringCapabilityin interfaceTerminal- Parameters:
capability- the string capability to retrieve- Returns:
- the string value of the capability, or
nullif the capability is not supported - See Also:
-
getPalette
Description copied from interface:TerminalReturns the color palette for this terminal.The color palette provides access to the terminal's color capabilities, allowing for customization and mapping of colors to terminal-specific values. This is particularly useful for terminals that support different color modes (8-color, 256-color, or true color).
The palette allows mapping between color values and their RGB representations, and provides methods for color conversion and manipulation.
Example usage:
Terminal terminal = TerminalBuilder.terminal(); ColorPalette palette = terminal.getPalette(); // Get RGB values for a specific color int[] rgb = palette.toRgb(AttributedStyle.RED);
- Specified by:
getPalettein interfaceTerminal- Returns:
- the terminal's color palette
- See Also:
-
flush
public void flush()Description copied from interface:TerminalFlushes any buffered output to the terminal.Terminal implementations may buffer output for efficiency. This method ensures that any buffered data is written to the terminal immediately. It's important to call this method when immediate display of output is required, such as when prompting for user input or updating status information.
Example usage:
Terminal terminal = TerminalBuilder.terminal(); terminal.writer().print("Enter your name: "); terminal.flush(); // Ensure the prompt is displayed before reading input String name = terminal.reader().readLine(); -
handle
Description copied from interface:TerminalRegisters a handler for the givenTerminal.Signal.This method allows the application to specify custom behavior when a particular signal is raised. The handler's
Terminal.SignalHandler.handle(Signal)method will be called whenever the specified signal is raised.Note that the JVM does not easily allow catching the
Terminal.Signal.QUITsignal (Ctrl+\), which typically causes a thread dump to be displayed. This signal handling is mainly effective when connecting through an SSH socket to a virtual terminal.Example usage:
Terminal terminal = TerminalBuilder.terminal(); // Handle window resize events terminal.handle(Signal.WINCH, signal -> { Size size = terminal.getSize(); terminal.writer().println("\nTerminal resized to " + size.getColumns() + "x" + size.getRows()); terminal.flush(); }); // Ignore interrupt signal terminal.handle(Signal.INT, SignalHandler.SIG_IGN); -
raise
Description copied from interface:TerminalRaises the specified signal, triggering any registered handlers.This method manually triggers a signal, causing any registered handler for that signal to be called. This is typically not a method that application code would call directly, but is used internally by terminal implementations.
When accessing a terminal through an SSH or Telnet connection, signals may be conveyed by the protocol and need to be raised when they reach the terminal code. Terminal implementations automatically raise signals when the input stream receives characters mapped to special control characters:
Attributes.ControlChar.VINTR(typically Ctrl+C) - RaisesTerminal.Signal.INTAttributes.ControlChar.VQUIT(typically Ctrl+\) - RaisesTerminal.Signal.QUITAttributes.ControlChar.VSUSP(typically Ctrl+Z) - RaisesTerminal.Signal.TSTP
In some cases, application code might want to programmatically raise signals to trigger specific behaviors, such as simulating a window resize event by raising
Terminal.Signal.WINCH. -
reader
Description copied from interface:TerminalRetrieve theReaderfor this terminal. This is the standard way to read input from this terminal. The reader is non blocking.The returned reader is owned by this terminal and will be closed when the terminal is closed. Callers should not close it directly.
-
inputEncoding
Description copied from interface:TerminalReturns theCharsetthat should be used to decode characters from the terminal input (Terminal.input()).This method returns the encoding specifically for terminal input. If no specific input encoding was configured, it falls back to the general encoding from
Terminal.encoding().- Specified by:
inputEncodingin interfaceTerminal- Returns:
- The terminal input encoding
- See Also:
-
outputEncoding
Description copied from interface:TerminalReturns theCharsetthat should be used to encode characters for the terminal output (Terminal.output()).This method returns the encoding specifically for terminal output. The encoding used depends on the system stream associated with this terminal: if the terminal is bound to standard error, it uses the stderr encoding; otherwise, it uses the stdout encoding. If no specific output encoding was configured, it falls back to the general encoding from
Terminal.encoding().- Specified by:
outputEncodingin interfaceTerminal- Returns:
- The terminal output encoding
- See Also:
-
input
Description copied from interface:TerminalRetrieve the input stream for this terminal. In some rare cases, there may be a need to access the terminal input stream directly. In the usual cases, use theTerminal.reader()instead.The returned stream is owned by this terminal and will be closed when the terminal is closed. Callers should not close it directly.
-
output
Description copied from interface:TerminalRetrieve the output stream for this terminal. In some rare cases, there may be a need to access the terminal output stream directly. In the usual cases, use theTerminal.writer()instead.The returned stream is owned by this terminal and will be closed when the terminal is closed. Callers should not close it directly.
-
canPauseResume
public boolean canPauseResume()Description copied from interface:TerminalWhether this terminal supportsTerminal.pause()andTerminal.resume()calls.- Specified by:
canPauseResumein interfaceTerminal- Returns:
- whether this terminal supports
Terminal.pause()andTerminal.resume()calls. - See Also:
-
pause
public void pause()Description copied from interface:TerminalTemporarily stops reading the input stream.This method pauses the terminal's input processing, which can be useful when transferring control to a subprocess or when the terminal needs to be in a specific state for certain operations. While paused, the terminal will not process input or handle signals that would normally be triggered by special characters in the input stream.
This method returns immediately without waiting for the terminal to actually pause. To wait until the terminal has fully paused, use
Terminal.pause(boolean)with a value oftrue.Example usage:
Terminal terminal = TerminalBuilder.terminal(); // Pause terminal input processing before running a subprocess terminal.pause(); // Run subprocess that takes control of the terminal Process process = new ProcessBuilder("vim").inheritIO().start(); process.waitFor(); // Resume terminal input processing terminal.resume(); -
pause
Description copied from interface:TerminalStop reading the input stream and optionally wait for the underlying threads to finish.- Specified by:
pausein interfaceTerminal- Parameters:
wait-trueto wait until the terminal is actually paused- Throws:
InterruptedException- if the call has been interrupted
-
resume
public void resume()Description copied from interface:TerminalResumes reading the input stream after it has been paused.This method restarts the terminal's input processing after it has been temporarily stopped using
Terminal.pause()orTerminal.pause(boolean). Once resumed, the terminal will continue to process input and handle signals triggered by special characters in the input stream.Calling this method when the terminal is not paused has no effect.
Example usage:
Terminal terminal = TerminalBuilder.terminal(); // Pause terminal input processing terminal.pause(); // Perform operations while terminal input is paused... // Resume terminal input processing terminal.resume();
-
paused
public boolean paused()Description copied from interface:TerminalCheck whether the terminal is currently reading the input stream or not. In order to process signal as quickly as possible, the terminal need to read the input stream and buffer it internally so that it can detect specific characters in the input stream (Ctrl+C, Ctrl+D, etc...) and raise the appropriate signals. However, there are some cases where this processing should be disabled, for example when handing the terminal control to a subprocess. -
enterRawMode
Description copied from interface:TerminalPuts the terminal into raw mode.In raw mode, input is available character by character, terminal-generated signals are disabled, and special character processing is disabled. This mode is typically used for full-screen interactive applications like text editors.
This method modifies the terminal attributes to configure raw mode and returns the original attributes, which can be used to restore the terminal to its previous state.
Example usage:
Terminal terminal = TerminalBuilder.terminal(); Attributes originalAttributes = terminal.enterRawMode(); // Use terminal in raw mode... // Restore original attributes when done terminal.setAttributes(originalAttributes);
- Specified by:
enterRawModein interfaceTerminal- Returns:
- the original terminal attributes before entering raw mode
- See Also:
-
echo
public boolean echo()Description copied from interface:TerminalReturns whether the terminal is currently echoing input characters.When echo is enabled, characters typed by the user are automatically displayed on the screen. When echo is disabled, input characters are not displayed, which is useful for password input or other sensitive information.
-
echo
public boolean echo(boolean echo) Description copied from interface:TerminalEnables or disables echoing of input characters.When echo is enabled, characters typed by the user are automatically displayed on the screen. When echo is disabled, input characters are not displayed, which is useful for password input or other sensitive information.
Example usage for password input:
Terminal terminal = TerminalBuilder.terminal(); boolean oldEcho = terminal.echo(false); // Disable echo String password = readPassword(terminal); terminal.echo(oldEcho); // Restore previous echo state
-
getAttributes
Description copied from interface:TerminalReturns the current terminal attributes.Terminal attributes control various aspects of terminal behavior, including:
- Input processing - How input characters are processed (e.g., character mapping, parity checking)
- Output processing - How output characters are processed (e.g., newline translation)
- Control settings - Hardware settings like baud rate and character size
- Local settings - Terminal behavior settings like echo, canonical mode, and signal generation
- Control characters - Special characters like EOF, interrupt, and erase
The returned
Attributesobject is a copy of the terminal's current attributes and can be safely modified without affecting the terminal until it is applied usingTerminal.setAttributes(Attributes). This allows for making multiple changes to the attributes before applying them all at once.Example usage:
Terminal terminal = TerminalBuilder.terminal(); // Get current attributes Attributes attrs = terminal.getAttributes(); // Modify attributes attrs.setLocalFlag(LocalFlag.ECHO, false); // Disable echo attrs.setInputFlag(InputFlag.ICRNL, false); // Disable CR to NL mapping attrs.setControlChar(ControlChar.VMIN, 1); // Set minimum input to 1 character attrs.setControlChar(ControlChar.VTIME, 0); // Set timeout to 0 deciseconds // Apply modified attributes terminal.setAttributes(attrs);
- Specified by:
getAttributesin interfaceTerminal- Returns:
- a copy of the terminal's current attributes
- See Also:
-
setAttributes
Description copied from interface:TerminalSets the terminal attributes to the specified values.This method applies the specified attributes to the terminal, changing its behavior according to the settings in the
Attributesobject. The terminal makes a copy of the provided attributes, so further modifications to theattrobject will not affect the terminal until this method is called again.Terminal attributes control various aspects of terminal behavior, including input and output processing, control settings, local settings, and special control characters. Changing these attributes allows for fine-grained control over how the terminal processes input and output.
Common attribute modifications include:
- Disabling echo for password input
- Enabling/disabling canonical mode for line-by-line or character-by-character input
- Disabling signal generation for custom handling of Ctrl+C and other control sequences
- Changing control characters like the interrupt character or end-of-file character
For convenience, the
Terminal.enterRawMode()method provides a pre-configured set of attributes suitable for full-screen interactive applications.Example usage:
Terminal terminal = TerminalBuilder.terminal(); // Save original attributes for later restoration Attributes originalAttrs = terminal.getAttributes(); try { // Create and configure new attributes Attributes attrs = new Attributes(originalAttrs); attrs.setLocalFlag(LocalFlag.ECHO, false); // Disable echo for password input attrs.setLocalFlag(LocalFlag.ICANON, false); // Disable canonical mode // Apply the new attributes terminal.setAttributes(attrs); // Use terminal with modified attributes... } finally { // Restore original attributes terminal.setAttributes(originalAttrs); }- Specified by:
setAttributesin interfaceTerminal- Parameters:
attr- the attributes to apply to the terminal- See Also:
-
setSize
Description copied from interface:TerminalRequests that the terminal adopt the specified window dimensions. Implementations may apply constraints or ignore the request if resizing is unsupported; callers should useTerminal.getSize()to observe the effective size after calling this method. -
getBufferSize
Description copied from interface:TerminalRetrieve the size of the window buffer. Some terminals can be configured to have a buffer size larger than the visible window size and provide scroll bars. In such cases, this method should attempt to return the size of the whole buffer. ThegetBufferSize()method can be used to avoid wrapping when using the terminal in a line editing mode, while theTerminal.getSize()method should be used when using full screen mode.- Specified by:
getBufferSizein interfaceTerminal- Returns:
- the terminal buffer size
- See Also:
-
puts
Description copied from interface:TerminalOutputs a terminal control string for the specified capability.This method formats and outputs a control sequence for the specified terminal capability, with the given parameters. It's used to perform terminal operations such as cursor movement, screen clearing, color changes, and other terminal-specific functions.
Example usage:
Terminal terminal = TerminalBuilder.terminal(); // Clear the screen terminal.puts(Capability.clear_screen); // Move cursor to position (10, 20) terminal.puts(Capability.cursor_address, 20, 10); // Set foreground color to red terminal.puts(Capability.set_a_foreground, 1);
-
getCursorPosition
Description copied from interface:TerminalQuery the terminal to report the cursor position. As the response is read from the input stream, some characters may be read before the cursor position is actually read. Those characters can be given back usingorg.jline.keymap.BindingReader#runMacro(String)- Specified by:
getCursorPositionin interfaceTerminal- Parameters:
discarded- a consumer receiving discarded characters- Returns:
nullif cursor position reporting is not supported or a valid cursor position
-
hasMouseSupport
public boolean hasMouseSupport()Description copied from interface:TerminalReturns whether the terminal has support for mouse tracking.Mouse support allows the terminal to report mouse events such as clicks, movement, and wheel scrolling. Not all terminals support mouse tracking, so this method should be called before attempting to enable mouse tracking with
Terminal.trackMouse(MouseTracking).Common terminal emulators that support mouse tracking include xterm, iTerm2, and modern versions of GNOME Terminal and Konsole. Terminal multiplexers like tmux and screen may also support mouse tracking depending on their configuration and the capabilities of the underlying terminal.
Example usage:
Terminal terminal = TerminalBuilder.terminal(); if (terminal.hasMouseSupport()) { // Enable mouse tracking terminal.trackMouse(MouseTracking.Normal); // Process mouse events // ... } else { System.out.println("Mouse tracking not supported by this terminal"); }- Specified by:
hasMouseSupportin interfaceTerminal- Returns:
trueif the terminal supports mouse tracking,falseotherwise- See Also:
-
trackMouse
Description copied from interface:TerminalEnables or disables mouse tracking with the specified mode.This method configures the terminal to report mouse events according to the specified tracking mode. When mouse tracking is enabled, the terminal will send special escape sequences to the input stream whenever mouse events occur. These sequences begin with the
InfoCmp.Capability.key_mousesequence, followed by data that describes the specific mouse event.The tracking mode determines which mouse events are reported:
Terminal.MouseTracking.Off- Disables mouse trackingTerminal.MouseTracking.Normal- Reports button press and release eventsTerminal.MouseTracking.Button- Reports button press, release, and motion events while buttons are pressedTerminal.MouseTracking.Any- Reports all mouse events, including movement without buttons pressed
To process mouse events, applications should:
- Enable mouse tracking by calling this method with the desired mode
- Monitor the input stream for the
InfoCmp.Capability.key_mousesequence - When this sequence is detected, call
Terminal.readMouseEvent()to decode the event - Process the returned
MouseEventas needed
Example usage:
Terminal terminal = TerminalBuilder.terminal(); if (terminal.hasMouseSupport()) { // Enable tracking of all mouse events boolean supported = terminal.trackMouse(MouseTracking.Any); if (supported) { System.out.println("Mouse tracking enabled"); // Set up input processing to detect and handle mouse events } }- Specified by:
trackMousein interfaceTerminal- Parameters:
tracking- the mouse tracking mode to enable, orTerminal.MouseTracking.Offto disable tracking- Returns:
trueif the requested mouse tracking mode is supported,falseotherwise- See Also:
-
getCurrentMouseTracking
Description copied from interface:TerminalReturns the current mouse tracking mode.- Specified by:
getCurrentMouseTrackingin interfaceTerminal- See Also:
-
readMouseEvent
Description copied from interface:TerminalRead a MouseEvent from the terminal input stream. Such an event must have been detected by scanning the terminal'sInfoCmp.Capability.key_mousein the stream immediately before reading the event.This method should be called after detecting the terminal's
InfoCmp.Capability.key_mousesequence in the input stream, which indicates that a mouse event has occurred. The method reads the necessary data from the input stream and decodes it into aMouseEventobject containing information about the event type, button, modifiers, and coordinates.Before calling this method, mouse tracking must be enabled using
Terminal.trackMouse(MouseTracking)with an appropriate tracking mode.The typical pattern for handling mouse events is:
- Enable mouse tracking with
Terminal.trackMouse(MouseTracking) - Read input from the terminal
- When the
InfoCmp.Capability.key_mousesequence is detected, call this method - Process the returned
MouseEvent
Example usage:
Terminal terminal = TerminalBuilder.terminal(); if (terminal.hasMouseSupport()) { terminal.trackMouse(MouseTracking.Normal); // Read input and look for mouse events String keyMouse = terminal.getStringCapability(Capability.key_mouse); // When keyMouse sequence is detected in the input: MouseEvent event = terminal.readMouseEvent(); System.out.println("Mouse event: " + event.getType() + " at " + event.getX() + "," + event.getY()); }- Specified by:
readMouseEventin interfaceTerminal- Returns:
- the decoded mouse event containing event type, button, modifiers, and coordinates
- See Also:
- Enable mouse tracking with
-
readMouseEvent
Description copied from interface:TerminalReads and decodes a mouse event using the provided input supplier.This method is similar to
Terminal.readMouseEvent(), but allows reading mouse event data from a custom input source rather than the terminal's default input stream. This can be useful in situations where input is being processed through a different channel or when implementing custom input handling.The input supplier should provide the raw bytes of the mouse event data as integers. The method will read the necessary data from the supplier and decode it into a
MouseEventobject containing information about the event type, button, modifiers, and coordinates.This method is primarily intended for advanced use cases where the standard
Terminal.readMouseEvent()method is not sufficient.Example usage:
Terminal terminal = TerminalBuilder.terminal(); // Create a custom input supplier IntSupplier customReader = new IntSupplier() { private byte[] data = ...; // Mouse event data private int index = 0; public int getAsInt() { return (index < data.length) ? data[index++] & 0xFF : -1; } }; // Read mouse event using the custom supplier MouseEvent event = terminal.readMouseEvent(customReader);- Specified by:
readMouseEventin interfaceTerminal- Parameters:
reader- the input supplier that provides the raw bytes of the mouse event data- Returns:
- the decoded mouse event containing event type, button, modifiers, and coordinates
- See Also:
-
readMouseEvent
Description copied from interface:TerminalReads and decodes a mouse event with a specified prefix that has already been consumed.This method is similar to
Terminal.readMouseEvent(), but it allows specifying a prefix that has already been consumed. This is useful when the mouse event prefix (e.g., "\033[<" or "\033[M") has been consumed by the key binding detection, and we need to continue parsing from the current position.This method is primarily intended for advanced use cases where the standard
Terminal.readMouseEvent()method is not sufficient, particularly when dealing with key binding systems that may consume part of the mouse event sequence.- Specified by:
readMouseEventin interfaceTerminal- Parameters:
prefix- the prefix that has already been consumed, or null if none- Returns:
- the decoded mouse event containing event type, button, modifiers, and coordinates
- See Also:
-
readMouseEvent
Description copied from interface:TerminalReads and decodes a mouse event using the provided input supplier with a specified prefix that has already been consumed.This method combines the functionality of
Terminal.readMouseEvent(IntSupplier)andTerminal.readMouseEvent(String), allowing both a custom input supplier and a prefix to be specified. This is useful for advanced input handling scenarios where both customization of the input source and handling of partially consumed sequences are needed.- Specified by:
readMouseEventin interfaceTerminal- Parameters:
reader- the input supplier that provides the raw bytes of the mouse event dataprefix- the prefix that has already been consumed, or null if none- Returns:
- the decoded mouse event containing event type, button, modifiers, and coordinates
- See Also:
-
hasFocusSupport
public boolean hasFocusSupport()Description copied from interface:TerminalReturns whether the terminal has support for focus tracking.Focus tracking allows the terminal to report when it gains or loses focus. This can be useful for applications that need to change their behavior or appearance based on whether they are currently in focus.
Not all terminals support focus tracking, so this method should be called before attempting to enable focus tracking with
Terminal.trackFocus(boolean).When focus tracking is enabled and supported, the terminal will send special escape sequences to the input stream when focus is gained ("\33[I") or lost ("\33[O"). Applications can detect these sequences to respond to focus changes.
Example usage:
Terminal terminal = TerminalBuilder.terminal(); if (terminal.hasFocusSupport()) { // Enable focus tracking terminal.trackFocus(true); // Now the application can detect focus changes // by looking for "\33[I" and "\33[O" in the input stream } else { System.out.println("Focus tracking not supported by this terminal"); }- Specified by:
hasFocusSupportin interfaceTerminal- Returns:
trueif the terminal supports focus tracking,falseotherwise- See Also:
-
trackFocus
public boolean trackFocus(boolean tracking) Description copied from interface:TerminalEnables or disables focus tracking mode.Focus tracking allows applications to detect when the terminal window gains or loses focus. When focus tracking is enabled, the terminal will send special escape sequences to the input stream whenever the focus state changes:
- When the terminal gains focus: "\33[I" (ESC [ I)
- When the terminal loses focus: "\33[O" (ESC [ O)
Applications can monitor the input stream for these sequences to detect focus changes and respond accordingly, such as by changing the cursor appearance, pausing animations, or adjusting the display.
Not all terminals support focus tracking. Use
Terminal.hasFocusSupport()to check whether focus tracking is supported before enabling it.Example usage:
Terminal terminal = TerminalBuilder.terminal(); if (terminal.hasFocusSupport()) { // Enable focus tracking boolean enabled = terminal.trackFocus(true); if (enabled) { System.out.println("Focus tracking enabled"); // Set up input processing to detect focus change sequences } }- Specified by:
trackFocusin interfaceTerminal- Parameters:
tracking-trueto enable focus tracking,falseto disable it- Returns:
trueif focus tracking is supported and the operation succeeded,falseotherwise- See Also:
-
close
- Specified by:
closein interfaceAutoCloseable- Specified by:
closein interfaceCloseable- Throws:
IOException
-