Module com.googlecode.lanterna
Package com.googlecode.lanterna.gui2

Class 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.

    Note: This class used to always wrap the Screen object with a VirtualScreen to ensure that the UI always fits. As of 3.1.0, we don't do this anymore so when you create the MultiWindowTextGUI you can wrap the screen parameter yourself if you want to keep this behavior.

    • Field Detail

      • backgroundPane

        private final BasePane backgroundPane

      • windowRenderBufferCache

        private final java.util.IdentityHashMap<Window,​TextImage> windowRenderBufferCache

      • eofWhenNoWindows

        private boolean eofWhenNoWindows

      • titleBarDragWindow

        private Window titleBarDragWindow

    • Constructor Detail

      • MultiWindowTextGUI

        public MultiWindowTextGUI​(Screen screen)
        Creates a new MultiWindowTextGUI that uses the specified Screen as the backend for all drawing operations. The background area of the GUI will be a solid color, depending on theme (default is blue). The current thread will be used as the GUI thread for all Lanterna library operations.
        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 background area of the GUI will be a solid color, depending on theme (default is blue). This constructor allows you control the threading model for the UI.
        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. The background area of the GUI will be a solid color, depending on theme (default is blue). This constructor allows you control the threading model for the UI and set a custom WindowManager.
        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 you should change the theme. Using this constructor won't work well with theming.
        Creates a new MultiWindowTextGUI that uses the specified Screen as the backend for all drawing operations. 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 background area of the GUI will be the component supplied instead of the usual backdrop. This constructor allows you to set a custom WindowManager instead of DefaultWindowManager.
        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 background area of the GUI will be the component supplied instead of the usual backdrop. This constructor allows you to set a custom WindowManager instead of DefaultWindowManager as well as a custom WindowPostRenderer that can be used to tweak the appearance of any window.
        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 background area of the GUI will be the component supplied instead of the usual backdrop. This constructor allows you to set a custom WindowManager instead of DefaultWindowManager as well as a custom WindowPostRenderer that can be used to tweak the appearance of any window. This constructor also allows you to control the threading model for the UI.
        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 java.io.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:
        java.io.IOException - In case there was an underlying I/O error

      • readKeyStroke

        protected KeyStroke readKeyStroke()
                           throws java.io.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:
        java.io.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

      • drawBackgroundPane

        private void drawBackgroundPane​(TextGUIGraphics graphics)

      • 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

        @Deprecated
public void setVirtualScreenEnabled​(boolean virtualScreenEnabled)
        Deprecated.
        This method don't do anything anymore (as of 3.1.0)
        This method used to exist to control if the virtual screen should by bypassed or not. Since 3.1.0 calling this has no effect since we don't force a VirtualScreen anymore and you control it yourself when you create the GUI.
        Specified by:
        setVirtualScreenEnabled in interface TextGUI
        Parameters:
        virtualScreenEnabled - Not used anymore

      • 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

      • ifMouseDownPossiblyChangeActiveWindow

        protected void ifMouseDownPossiblyChangeActiveWindow​(KeyStroke keyStroke)

      • ifMouseDownPossiblyStartTitleDrag

        protected void ifMouseDownPossiblyStartTitleDrag​(KeyStroke keyStroke)

      • ifMouseDragPossiblyMoveWindow

        protected void ifMouseDragPossiblyMoveWindow​(KeyStroke keyStroke)

      • changeWindowHintsForDragged

        protected void changeWindowHintsForDragged​(Window window)
        In order for window to be draggable, it would no longer be CENTERED. Removes Hint.CENTERED, adds Hint.FIXED_POSITION to the window hints.

      • 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

      • getWindows

        public java.util.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

      • 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