Class AbstractTextGUI

  • All Implemented Interfaces:
    TextGUI
    Direct Known Subclasses:
    MultiWindowTextGUI

    public abstract class AbstractTextGUI
    extends java.lang.Object
    implements TextGUI
    This abstract implementation of TextGUI contains some basic management of the underlying Screen and other common code that can be shared between different implementations.
    • Field Detail

      • screen

        private final Screen screen
      • blockingIO

        private boolean blockingIO
      • dirty

        private boolean dirty
      • guiTheme

        private Theme guiTheme
    • Constructor Detail

      • AbstractTextGUI

        protected AbstractTextGUI​(TextGUIThreadFactory textGUIThreadFactory,
                                  Screen screen)
        Constructor for AbstractTextGUI that requires a Screen and a factory for creating the GUI thread
        Parameters:
        textGUIThreadFactory - Factory class to use for creating the TextGUIThread class
        screen - What underlying Screen to use for this text GUI
    • Method Detail

      • readKeyStroke

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

        protected KeyStroke pollInput()
                               throws java.io.IOException
        Polls the underlying input queue for user input, returning either a KeyStroke or null
        Returns:
        KeyStroke representing the user input or null if there was none
        Throws:
        java.io.IOException - In case of an I/O error while reading input
      • processInput

        public boolean processInput()
                             throws java.io.IOException
        Description copied from interface: TextGUI
        Drains the input queue and passes the key strokes to the GUI system for processing. For window-based system, it will send each key stroke to the active window for processing. If the input read gives an EOF, it will throw EOFException and this is normally the signal to shut down the GUI (any command coming in before the EOF will be processed as usual before this).
        Specified by:
        processInput in interface TextGUI
        Returns:
        true if at least one key stroke was read and processed, false if there was nothing on the input queue (only for non-blocking IO)
        Throws:
        java.io.IOException - In case there was an underlying I/O error
        java.io.EOFException - In the input stream received an EOF marker
      • setTheme

        public void setTheme​(Theme theme)
        Description copied from interface: TextGUI
        Sets the global theme to be used by this TextGUI. This value will be set on every TextGUIGraphics object created for drawing the GUI, but individual components can override this if they want. If you don't call this method you should assume that a default theme is assigned by the library.
        Specified by:
        setTheme in interface TextGUI
        Parameters:
        theme - Theme to use as the default theme for this TextGUI
      • getTheme

        public Theme getTheme()
        Description copied from interface: TextGUI
        Returns the theme currently assigned to this TextGUI
        Specified by:
        getTheme in interface TextGUI
        Returns:
        Currently active Theme
      • 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
        Throws:
        java.io.IOException - In case there was an underlying I/O error
      • 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
        Returns:
        true if this TextGUI has a change and is waiting for someone to call updateScreen()
      • getGUIThread

        public TextGUIThread getGUIThread()
        Description copied from interface: TextGUI
        The first time this method is called, it will create a new TextGUIThread object that you can use to automatically manage this TextGUI instead of manually calling processInput() and updateScreen(). After the initial call, it will return the same object as it was originally returning.
        Specified by:
        getGUIThread in interface TextGUI
        Returns:
        A TextGUIThread implementation that can be used to asynchronously manage the GUI
      • addListener

        public void addListener​(TextGUI.Listener listener)
        Description copied from interface: TextGUI
        Adds a listener to this TextGUI to fire events on.
        Specified by:
        addListener in interface TextGUI
        Parameters:
        listener - Listener to add
      • removeListener

        public void removeListener​(TextGUI.Listener listener)
        Description copied from interface: TextGUI
        Removes a listener from this TextGUI so that it will no longer receive events
        Specified by:
        removeListener in interface TextGUI
        Parameters:
        listener - Listener to remove
      • setBlockingIO

        public void setBlockingIO​(boolean blockingIO)
        Enables blocking I/O, causing calls to readKeyStroke() to block until there is input available. Notice that you can still poll for input using pollInput().
        Parameters:
        blockingIO - Set this to true if blocking I/O should be enabled, otherwise false
      • isBlockingIO

        public boolean isBlockingIO()
        Checks if blocking I/O is enabled or not
        Returns:
        true if blocking I/O is enabled, otherwise false
      • fireUnhandledKeyStroke

        protected final boolean fireUnhandledKeyStroke​(KeyStroke keyStroke)
        This method should be called when there was user input that wasn't handled by the GUI. It will fire the onUnhandledKeyStroke(..) method on any registered listener.
        Parameters:
        keyStroke - The KeyStroke that wasn't handled by the GUI
        Returns:
        true if at least one of the listeners handled the key stroke, this will signal to the GUI that it needs to be redrawn again.
      • invalidate

        protected void invalidate()
        Marks the whole text GUI as invalid and that it needs to be redrawn at next opportunity
      • drawGUI

        protected abstract void drawGUI​(TextGUIGraphics graphics)
        Draws the entire GUI using a TextGUIGraphics object
        Parameters:
        graphics - Graphics object to draw using
      • getCursorPosition

        protected abstract 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.
        Returns:
        Where to place the text cursor, or null if the cursor should be hidden
      • handleInput

        protected abstract boolean handleInput​(KeyStroke key)
        This method should take the user input and feed it to the focused component for handling.
        Parameters:
        key - KeyStroke representing the user input
        Returns:
        true if the input was recognized and handled by the GUI, indicating that the GUI should be redrawn