Class AbstractScreen

  • All Implemented Interfaces:
    Scrollable, InputProvider, Screen, java.io.Closeable, java.lang.AutoCloseable
    Direct Known Subclasses:
    TerminalScreen, VirtualScreen

    public abstract class AbstractScreen
    extends java.lang.Object
    implements Screen
    This class implements some of the Screen logic that is not directly tied to the actual implementation of how the Screen translate to the terminal. It keeps data structures for the front- and back buffers, the cursor location and some other simpler states.
    • Constructor Detail

      • AbstractScreen

        public AbstractScreen​(TerminalSize initialSize)
      • AbstractScreen

        public AbstractScreen​(TerminalSize initialSize,
                              TextCharacter defaultCharacter)
        Creates a new Screen on top of a supplied terminal, will query the terminal for its size. The screen is initially blank. You can specify which character you wish to be used to fill the screen initially; this will also be the character used if the terminal is enlarged and you don't set anything on the new areas.
        Parameters:
        initialSize - Size to initially create the Screen with (can be resized later)
        defaultCharacter - What character to use for the initial state of the screen and expanded areas
    • Method Detail

      • getCursorPosition

        public TerminalPosition getCursorPosition()
        Description copied from interface: Screen
        A screen implementation typically keeps a location on the screen where the cursor will be placed after drawing and refreshing the buffers, this method returns that location. If it returns null, it means that the terminal will attempt to hide the cursor (if supported by the terminal).
        Specified by:
        getCursorPosition in interface Screen
        Returns:
        Position where the cursor will be located after the screen has been refreshed or null if the cursor is not visible
      • setCursorPosition

        public void setCursorPosition​(TerminalPosition position)
        Moves the current cursor position or hides it. If the cursor is hidden and given a new position, it will be visible after this method call.
        Specified by:
        setCursorPosition in interface Screen
        Parameters:
        position - 0-indexed column and row numbers of the new position, or if null, hides the cursor
      • setTabBehaviour

        public void setTabBehaviour​(TabBehaviour tabBehaviour)
        Description copied from interface: Screen
        Sets the behaviour for what to do about tab characters. If a tab character is written to the Screen, it would cause issues because we don't know how the terminal emulator would render it and we wouldn't know what state the front-buffer is in. Because of this, we convert tabs to a determined number of spaces depending on different rules that are available.
        Specified by:
        setTabBehaviour in interface Screen
        Parameters:
        tabBehaviour - Tab behaviour to use when converting a \t character to a spaces
        See Also:
        TabBehaviour
      • getTabBehaviour

        public TabBehaviour getTabBehaviour()
        Description copied from interface: Screen
        Gets the behaviour for what to do about tab characters. If a tab character is written to the Screen, it would cause issues because we don't know how the terminal emulator would render it and we wouldn't know what state the front-buffer is in. Because of this, we convert tabs to a determined number of spaces depending on different rules that are available.
        Specified by:
        getTabBehaviour in interface Screen
        Returns:
        Tab behaviour that is used currently
        See Also:
        TabBehaviour
      • setCharacter

        public void setCharacter​(TerminalPosition position,
                                 TextCharacter screenCharacter)
        Description copied from interface: Screen
        Sets a character in the back-buffer to a specified value with specified colors and modifiers.
        Specified by:
        setCharacter in interface Screen
        Parameters:
        position - Which position in the terminal to modify
        screenCharacter - New data to put at the specified position
      • newTextGraphics

        public TextGraphics newTextGraphics()
        Description copied from interface: Screen
        Creates a new TextGraphics objects that is targeting this Screen for writing to. Any operations done on this TextGraphics will be affecting this screen. Remember to call refresh() on the screen to see your changes.
        Specified by:
        newTextGraphics in interface Screen
        Returns:
        New TextGraphic object targeting this Screen
      • setCharacter

        public void setCharacter​(int column,
                                 int row,
                                 TextCharacter screenCharacter)
        Description copied from interface: Screen
        Sets a character in the back-buffer to a specified value with specified colors and modifiers.
        Specified by:
        setCharacter in interface Screen
        Parameters:
        column - Column of the character to modify (x coordinate)
        row - Row of the character to modify (y coordinate)
        screenCharacter - New data to put at the specified position
      • getFrontCharacter

        public TextCharacter getFrontCharacter​(TerminalPosition position)
        Description copied from interface: Screen
        Reads a character and its associated meta-data from the front-buffer and returns it encapsulated as a ScreenCharacter.
        Specified by:
        getFrontCharacter in interface Screen
        Parameters:
        position - What position to read the character from
        Returns:
        A ScreenCharacter representation of the character in the front-buffer at the specified location
      • getFrontCharacter

        public TextCharacter getFrontCharacter​(int column,
                                               int row)
        Description copied from interface: Screen
        Reads a character and its associated meta-data from the front-buffer and returns it encapsulated as a ScreenCharacter.
        Specified by:
        getFrontCharacter in interface Screen
        Parameters:
        column - Which column to get the character from
        row - Which row to get the character from
        Returns:
        A ScreenCharacter representation of the character in the front-buffer at the specified location
      • getBackCharacter

        public TextCharacter getBackCharacter​(TerminalPosition position)
        Description copied from interface: Screen
        Reads a character and its associated meta-data from the back-buffer and returns it encapsulated as a ScreenCharacter.
        Specified by:
        getBackCharacter in interface Screen
        Parameters:
        position - What position to read the character from
        Returns:
        A ScreenCharacter representation of the character in the back-buffer at the specified location
      • getBackCharacter

        public TextCharacter getBackCharacter​(int column,
                                              int row)
        Description copied from interface: Screen
        Reads a character and its associated meta-data from the back-buffer and returns it encapsulated as a ScreenCharacter.
        Specified by:
        getBackCharacter in interface Screen
        Parameters:
        column - Which column to get the character from
        row - Which row to get the character from
        Returns:
        A ScreenCharacter representation of the character in the back-buffer at the specified location
      • refresh

        public void refresh()
                     throws java.io.IOException
        Description copied from interface: Screen
        This method will take the content from the back-buffer and move it into the front-buffer, making the changes visible to the terminal in the process. The graphics workflow with Screen would involve drawing text and text-like graphics on the back buffer and then finally calling refresh(..) to make it visible to the user.
        Specified by:
        refresh in interface Screen
        Throws:
        java.io.IOException - If there was an underlying I/O error
        See Also:
        Screen.RefreshType
      • close

        public void close()
                   throws java.io.IOException
        Description copied from interface: Screen
        Same as calling Screen.stopScreen()
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Specified by:
        close in interface Screen
        Throws:
        java.io.IOException - if there was an underlying IO error when exiting from private mode
      • clear

        public void clear()
        Description copied from interface: Screen
        Erases all the characters on the screen, effectively giving you a blank area. The default background color will be used. This is effectively the same as calling
        fill(TerminalPosition.TOP_LEFT_CORNER, getSize(), TextColor.ANSI.Default)
        .

        Please note that calling this method will only affect the back buffer, you need to call refresh to make the change visible.

        Specified by:
        clear in interface Screen
      • doResizeIfNecessary

        public TerminalSize doResizeIfNecessary()
        Description copied from interface: Screen
        One problem working with Screens is that whenever the terminal is resized, the front and back buffers needs to be adjusted accordingly and the program should have a chance to figure out what to do with this extra space (or less space). The solution is to call, at the start of your rendering code, this method, which will check if the terminal has been resized and in that case update the internals of the Screen. After this call finishes, the screen's internal buffers will match the most recent size report from the underlying terminal.
        Specified by:
        doResizeIfNecessary in interface Screen
        Returns:
        If the terminal has been resized since this method was last called, it will return the new size of the terminal. If not, it will return null.
      • getTerminalSize

        public TerminalSize getTerminalSize()
        Description copied from interface: Screen
        Returns the size of the screen. This call is not blocking but should return the size of the screen as it is represented by the buffer at the time this method is called.
        Specified by:
        getTerminalSize in interface Screen
        Returns:
        Size of the screen, in columns and rows
      • getFrontBuffer

        protected ScreenBuffer getFrontBuffer()
        Returns the front buffer connected to this screen, don't use this unless you know what you are doing!
        Returns:
        This Screen's front buffer
      • getBackBuffer

        protected ScreenBuffer getBackBuffer()
        Returns the back buffer connected to this screen, don't use this unless you know what you are doing!
        Returns:
        This Screen's back buffer
      • getAndClearPendingResize

        private TerminalSize getAndClearPendingResize()
      • addResizeRequest

        protected void addResizeRequest​(TerminalSize newSize)
        Tells this screen that the size has changed and it should, at next opportunity, resize itself and its buffers
        Parameters:
        newSize - New size the 'real' terminal now has
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • scrollLines

        public void scrollLines​(int firstLine,
                                int lastLine,
                                int distance)
        Performs the scrolling on its back-buffer.
        Specified by:
        scrollLines in interface Screen
        Specified by:
        scrollLines in interface Scrollable
        Parameters:
        firstLine - first line of the range to be scrolled (top line is 0)
        lastLine - last (inclusive) line of the range to be scrolled
        distance - if > 0: move lines up, else if < 0: move lines down.