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.

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 Details

  • Constructor Details

    • 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 Details

    • 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
    • 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
    • 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
      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
    • moveToBottom

      public WindowBasedTextGUI moveToBottom(Window window)
    • 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