Package com.googlecode.lanterna.gui2

Class MultiWindowTextGUI

java.lang.Object

com.googlecode.lanterna.gui2.AbstractTextGUI

com.googlecode.lanterna.gui2.MultiWindowTextGUI

All Implemented Interfaces:

TextGUI, WindowBasedTextGUI

public class MultiWindowTextGUI
extends AbstractTextGUI
implements WindowBasedTextGUI

This is the main Text GUI implementation built into Lanterna, supporting multiple tiled windows and a dynamic background area that can be fully customized. If you want to create a text-based GUI with windows and controls, it's very likely this is what you want to use.

Author:

Martin

Nested Class Summary

Nested classes/interfaces inherited from interface com.googlecode.lanterna.gui2.TextGUI

TextGUI.Listener

Constructor Summary

Constructors

Constructor	Description
MultiWindowTextGUI(TextGUIThreadFactory guiThreadFactory, Screen screen)	Creates a new MultiWindowTextGUI that uses the specified Screen as the backend for all drawing operations.
MultiWindowTextGUI(TextGUIThreadFactory guiThreadFactory, Screen screen, WindowManager windowManager)	Creates a new MultiWindowTextGUI that uses the specified Screen as the backend for all drawing operations and a custom WindowManager.
MultiWindowTextGUI(TextGUIThreadFactory guiThreadFactory, Screen screen, WindowManager windowManager, WindowPostRenderer postRenderer, Component background)	Creates a new MultiWindowTextGUI that uses the specified Screen as the backend for all drawing operations.
MultiWindowTextGUI(Screen screen)	Creates a new MultiWindowTextGUI that uses the specified Screen as the backend for all drawing operations.
MultiWindowTextGUI(Screen screen, WindowManager windowManager, Component background)	Creates a new MultiWindowTextGUI that uses the specified Screen as the backend for all drawing operations.
MultiWindowTextGUI(Screen screen, WindowManager windowManager, WindowPostRenderer postRenderer, Component background)	Creates a new MultiWindowTextGUI that uses the specified Screen as the backend for all drawing operations.
MultiWindowTextGUI(Screen screen, TextColor backgroundColor)	Deprecated. It's preferred to use a custom background component if you want to customize the background color, or change the theme

Method Summary

Modifier and Type	Method	Description
WindowBasedTextGUI	addWindow(Window window)	Adds a window to the TextGUI system, depending on the window manager this window may or may not be immediately visible.
WindowBasedTextGUI	addWindowAndWait(Window window)	Adds a window to the TextGUI system, depending on the window manager this window may or may not be immediately visible.
WindowBasedTextGUI	cycleActiveWindow(boolean reverse)	Switches the active window by cyclically shuffling the window list.
protected void	drawGUI(TextGUIGraphics graphics)	Draws the entire GUI using a TextGUIGraphics object
Window	getActiveWindow()	Returns the window which the TextGUI considers the active one at the time of the method call.
BasePane	getBackgroundPane()	Returns the container for the background, which works as a single large component that takes up the whole terminal area and is always behind all windows.
TerminalPosition	getCursorPosition()	Top-level method for drilling in to the GUI and figuring out, in global coordinates, where to place the text cursor on the screen at this time.
Interactable	getFocusedInteractable()	Returns the interactable component currently in focus
WindowManager	getWindowManager()	Returns the window manager that is currently controlling this TextGUI.
WindowPostRenderer	getWindowPostRenderer()	Returns the WindowPostRenderer for this WindowBasedTextGUI
Collection<Window>	getWindows()	Returns a list of all windows currently in the TextGUI.
boolean	handleInput(KeyStroke keyStroke)	This method should take the user input and feed it to the focused component for handling.
boolean	isEOFWhenNoWindows()	Returns whether the TextGUI should return EOF when you try to read input while there are no windows in the window manager.
boolean	isPendingUpdate()	This method can be used to determine if any component has requested a redraw.
WindowBasedTextGUI	moveToTop(Window window)	Windows are internally stored as a stack and newer windows are added at the top of the stack.
protected KeyStroke	readKeyStroke()	Reads one key from the input queue, blocking or non-blocking depending on if blocking I/O has been enabled.
WindowBasedTextGUI	removeWindow(Window window)	Removes a window from the TextGUI.
MultiWindowTextGUI	setActiveWindow(Window activeWindow)	Selects a particular window to be considered 'active' and receive all input events
void	setEOFWhenNoWindows(boolean eofWhenNoWindows)	Sets whether the TextGUI should return EOF when you try to read input while there are no windows in the window manager.
void	setVirtualScreenEnabled(boolean virtualScreenEnabled)	This method controls whether or not the virtual screen should be used.
void	updateScreen()	Updates the screen, to make any changes visible to the user.
void	waitForWindowToClose(Window window)	Waits for the specified window to be closed

Methods inherited from class com.googlecode.lanterna.gui2.AbstractTextGUI

addListener, fireUnhandledKeyStroke, getGUIThread, getScreen, getTheme, invalidate, isBlockingIO, pollInput, processInput, removeListener, setBlockingIO, setTheme

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.gui2.TextGUI

addListener, getGUIThread, getScreen, getTheme, processInput, removeListener, setTheme

Constructor Detail

MultiWindowTextGUI

public MultiWindowTextGUI(Screen screen)

Creates a new MultiWindowTextGUI that uses the specified Screen as the backend for all drawing operations. The screen will be automatically wrapped in a VirtualScreen in order to deal with GUIs becoming too big to fit the terminal. The background area of the GUI will be solid blue.

Parameters:

screen - Screen to use as the backend for drawing operations

MultiWindowTextGUI

public MultiWindowTextGUI(TextGUIThreadFactory guiThreadFactory,
                          Screen screen)

Creates a new MultiWindowTextGUI that uses the specified Screen as the backend for all drawing operations. The screen will be automatically wrapped in a VirtualScreen in order to deal with GUIs becoming too big to fit the terminal. The background area of the GUI will be solid blue

Parameters:

guiThreadFactory - Factory implementation to use when creating the TextGUIThread

screen - Screen to use as the backend for drawing operations

MultiWindowTextGUI

public MultiWindowTextGUI(TextGUIThreadFactory guiThreadFactory,
                          Screen screen,
                          WindowManager windowManager)

Creates a new MultiWindowTextGUI that uses the specified Screen as the backend for all drawing operations and a custom WindowManager. The screen will be automatically wrapped in a VirtualScreen in order to deal with GUIs becoming too big to fit the terminal. The background area of the GUI will use the default GUIBackdrop component.

Parameters:

guiThreadFactory - Factory implementation to use when creating the TextGUIThread

screen - Screen to use as the backend for drawing operations

windowManager - Custom window manager to use

MultiWindowTextGUI

@Deprecated
public MultiWindowTextGUI(Screen screen,
                          TextColor backgroundColor)

Deprecated. It's preferred to use a custom background component if you want to customize the background color, or change the theme

Creates a new MultiWindowTextGUI that uses the specified Screen as the backend for all drawing operations. The screen will be automatically wrapped in a VirtualScreen in order to deal with GUIs becoming too big to fit the terminal. The background area of the GUI is a solid color as decided by the backgroundColor parameter.

Parameters:

screen - Screen to use as the backend for drawing operations

backgroundColor - Color to use for the GUI background

MultiWindowTextGUI

public MultiWindowTextGUI(Screen screen,
                          WindowManager windowManager,
                          Component background)

Creates a new MultiWindowTextGUI that uses the specified Screen as the backend for all drawing operations. The screen will be automatically wrapped in a VirtualScreen in order to deal with GUIs becoming too big to fit the terminal. The background area of the GUI is the component passed in as the background parameter, forced to full size.

Parameters:

screen - Screen to use as the backend for drawing operations

windowManager - Window manager implementation to use

background - Component to use as the background of the GUI, behind all the windows

MultiWindowTextGUI

public MultiWindowTextGUI(Screen screen,
                          WindowManager windowManager,
                          WindowPostRenderer postRenderer,
                          Component background)

Creates a new MultiWindowTextGUI that uses the specified Screen as the backend for all drawing operations. The screen will be automatically wrapped in a VirtualScreen in order to deal with GUIs becoming too big to fit the terminal. The background area of the GUI is the component passed in as the background parameter, forced to full size.

Parameters:

screen - Screen to use as the backend for drawing operations

windowManager - Window manager implementation to use

postRenderer - WindowPostRenderer object to invoke after each window has been drawn

background - Component to use as the background of the GUI, behind all the windows

MultiWindowTextGUI

public MultiWindowTextGUI(TextGUIThreadFactory guiThreadFactory,
                          Screen screen,
                          WindowManager windowManager,
                          WindowPostRenderer postRenderer,
                          Component background)

Creates a new MultiWindowTextGUI that uses the specified Screen as the backend for all drawing operations. The screen will be automatically wrapped in a VirtualScreen in order to deal with GUIs becoming too big to fit the terminal. The background area of the GUI is the component passed in as the background parameter, forced to full size.

Parameters:

guiThreadFactory - Factory implementation to use when creating the TextGUIThread

screen - Screen to use as the backend for drawing operations

windowManager - Window manager implementation to use

postRenderer - WindowPostRenderer object to invoke after each window has been drawn

background - Component to use as the background of the GUI, behind all the windows

Method Detail

isPendingUpdate

public boolean isPendingUpdate()

Description copied from interface: TextGUI

This method can be used to determine if any component has requested a redraw. If this method returns true, you may want to call updateScreen().

Specified by:

isPendingUpdate in interface TextGUI

Overrides:

isPendingUpdate in class AbstractTextGUI

Returns:

true if this TextGUI has a change and is waiting for someone to call updateScreen()

updateScreen

public void updateScreen()
                  throws IOException

Description copied from interface: TextGUI

Updates the screen, to make any changes visible to the user.

Specified by:

updateScreen in interface TextGUI

Overrides:

updateScreen in class AbstractTextGUI

Throws:

IOException - In case there was an underlying I/O error

readKeyStroke

protected KeyStroke readKeyStroke()
                           throws IOException

Description copied from class: AbstractTextGUI

Reads one key from the input queue, blocking or non-blocking depending on if blocking I/O has been enabled. To enable blocking I/O (disabled by default), use setBlockingIO(true).

Overrides:

readKeyStroke in class AbstractTextGUI

Returns:

One piece of user input as a KeyStroke or null if blocking I/O is disabled and there was no input waiting

Throws:

IOException - In case of an I/O error while reading input

drawGUI

protected void drawGUI(TextGUIGraphics graphics)

Description copied from class: AbstractTextGUI

Draws the entire GUI using a TextGUIGraphics object

Specified by:

drawGUI in class AbstractTextGUI

Parameters:

graphics - Graphics object to draw using

getCursorPosition

public TerminalPosition getCursorPosition()

Description copied from class: AbstractTextGUI

Top-level method for drilling in to the GUI and figuring out, in global coordinates, where to place the text cursor on the screen at this time.

Specified by:

getCursorPosition in class AbstractTextGUI

Returns:

Where to place the text cursor, or null if the cursor should be hidden

setEOFWhenNoWindows

public void setEOFWhenNoWindows(boolean eofWhenNoWindows)

Sets whether the TextGUI should return EOF when you try to read input while there are no windows in the window manager. Setting this to true (off by default) will make the GUI automatically exit when the last window has been closed.

Parameters:

eofWhenNoWindows - Should the GUI return EOF when there are no windows left

isEOFWhenNoWindows

public boolean isEOFWhenNoWindows()

Returns whether the TextGUI should return EOF when you try to read input while there are no windows in the window manager. When this is true (true by default) will make the GUI automatically exit when the last window has been closed.

Returns:

Should the GUI return EOF when there are no windows left

setVirtualScreenEnabled

public void setVirtualScreenEnabled(boolean virtualScreenEnabled)

This method controls whether or not the virtual screen should be used. This is what enabled you to make your UI larger than what fits the terminal, as it will expand the virtual area and put in scrollbars. If set to false, the virtual screen will be bypassed and any content outside of the screen will be cropped. This property is true by default.

Specified by:

setVirtualScreenEnabled in interface TextGUI

Parameters:

virtualScreenEnabled - If true, then virtual screen will be used, otherwise it is bypassed

getFocusedInteractable

public Interactable getFocusedInteractable()

Description copied from interface: TextGUI

Returns the interactable component currently in focus

Specified by:

getFocusedInteractable in interface TextGUI

Returns:

Component that is currently in input focus

handleInput

public boolean handleInput(KeyStroke keyStroke)

Description copied from class: AbstractTextGUI

This method should take the user input and feed it to the focused component for handling.

Specified by:

handleInput in class AbstractTextGUI

Parameters:

keyStroke - KeyStroke representing the user input

Returns:

true if the input was recognized and handled by the GUI, indicating that the GUI should be redrawn

getWindowManager

public WindowManager getWindowManager()

Description copied from interface: WindowBasedTextGUI

Returns the window manager that is currently controlling this TextGUI. The window manager is in charge of placing the windows on the surface and also deciding how they behave and move around.

Specified by:

getWindowManager in interface WindowBasedTextGUI

Returns:

Window manager that is currently controlling the windows in the terminal

addWindow

public WindowBasedTextGUI addWindow(Window window)

Description copied from interface: WindowBasedTextGUI

Adds a window to the TextGUI system, depending on the window manager this window may or may not be immediately visible. By adding a window to the GUI, it will be associated with this GUI and can receive focus and events from it. This method call will return immediately, if you want the call to block until the window is closed, please use addWindowAndWait(..). Windows are internally stored as a stack and newer windows are added at the top of the stack. The GUI system will render windows in a predictable order from bottom to top. You can modify the stack by using moveToTop(..) to move a Window from its current position in the stack to the top.

Specified by:

addWindow in interface WindowBasedTextGUI

Parameters:

window - Window to add to the GUI

Returns:

The WindowBasedTextGUI Itself

addWindowAndWait

public WindowBasedTextGUI addWindowAndWait(Window window)

Description copied from interface: WindowBasedTextGUI

Adds a window to the TextGUI system, depending on the window manager this window may or may not be immediately visible. By adding a window to the GUI, it will be associated with this GUI and can receive focus and events from it. This method block until the added window is removed or closed, if you want the call to return immediately, please use addWindow(..). This method call is useful for modal dialogs that requires a certain user input before the application can continue. Windows are internally stored as a stack and newer windows are added at the top of the stack. The GUI system will render windows in a predictable order from bottom to top. You can modify the stack by using moveToTop(..) to move a Window from its current position in the stack to the top.

Specified by:

addWindowAndWait in interface WindowBasedTextGUI

Parameters:

window - Window to add to the GUI

Returns:

The WindowBasedTextGUI Itself

removeWindow

public WindowBasedTextGUI removeWindow(Window window)

Description copied from interface: WindowBasedTextGUI

Removes a window from the TextGUI. This is effectively the same as closing the window. The window will be unassociated from this TextGUI and will no longer receive any events for it. Any threads waiting on the window to close will be resumed.

Specified by:

removeWindow in interface WindowBasedTextGUI

Parameters:

window - Window to close

Returns:

The WindowBasedTextGUI itself

waitForWindowToClose

public void waitForWindowToClose(Window window)

Description copied from interface: WindowBasedTextGUI

Waits for the specified window to be closed

Specified by:

waitForWindowToClose in interface WindowBasedTextGUI

Parameters:

window - Window to wait for

getWindows

public Collection<Window> getWindows()

Description copied from interface: WindowBasedTextGUI

Returns a list of all windows currently in the TextGUI. The list is unmodifiable and just a snapshot of what the state was when the method was invoked. If windows are added/removed after the method call, the list will not reflect this.

Specified by:

getWindows in interface WindowBasedTextGUI

Returns:

Unmodifiable list of all windows in the TextGUI at the time of the call

setActiveWindow

public MultiWindowTextGUI setActiveWindow(Window activeWindow)

Description copied from interface: WindowBasedTextGUI

Selects a particular window to be considered 'active' and receive all input events

Specified by:

setActiveWindow in interface WindowBasedTextGUI

Parameters:

activeWindow - Window to become active and receive input events

Returns:

The WindowBasedTextGUI itself

getActiveWindow

public Window getActiveWindow()

Description copied from interface: WindowBasedTextGUI

Returns the window which the TextGUI considers the active one at the time of the method call. The active window is generally the one which relieves all keyboard input.

Specified by:

getActiveWindow in interface WindowBasedTextGUI

Returns:

Active window in the TextGUI or null

getBackgroundPane

public BasePane getBackgroundPane()

Description copied from interface: WindowBasedTextGUI

Returns the container for the background, which works as a single large component that takes up the whole terminal area and is always behind all windows.

Specified by:

getBackgroundPane in interface WindowBasedTextGUI

Returns:

The BasePane used by this WindowBasedTextGUI

getWindowPostRenderer

public WindowPostRenderer getWindowPostRenderer()

Description copied from interface: WindowBasedTextGUI

Returns the WindowPostRenderer for this WindowBasedTextGUI

Specified by:

getWindowPostRenderer in interface WindowBasedTextGUI

Returns:

the WindowPostRenderer for this WindowBasedTextGUI

moveToTop

public WindowBasedTextGUI moveToTop(Window window)

Description copied from interface: WindowBasedTextGUI

Windows are internally stored as a stack and newer windows are added at the top of the stack. The GUI system will render windows in a predictable order from bottom to top. This method allows you to move a Window from its current position in the stack to the top, meaning it will be rendered last. This mean it will overlap all other windows and because of this visually appear on top.

Specified by:

moveToTop in interface WindowBasedTextGUI

Parameters:

window - Window in the stack to move to the top position

Returns:

The WindowBasedTextGUI Itself

cycleActiveWindow

public WindowBasedTextGUI cycleActiveWindow(boolean reverse)

Switches the active window by cyclically shuffling the window list. If reverse parameter is false then the current top window is placed at the bottom of the stack and the window immediately behind it is the new top. If reverse is set to true then the window at the bottom of the stack is moved up to the front and the previous top window will be immediately below it

Specified by:

cycleActiveWindow in interface WindowBasedTextGUI

Parameters:

reverse - Direction to cycle through the windows

Returns:

Itself