Interface Screen

  • All Superinterfaces:
    java.lang.AutoCloseable, java.io.Closeable, InputProvider, Scrollable
    All Known Implementing Classes:
    AbstractScreen, TerminalScreen, VirtualScreen

    public interface Screen
    extends InputProvider, Scrollable, java.io.Closeable
    Screen is a fundamental layer in Lanterna, presenting the terminal as a bitmap-like surface where you can perform smaller in-memory operations to a back-buffer, effectively painting out the terminal as you'd like it, and then call refresh to have the screen automatically apply the changes in the back-buffer to the real terminal. The screen tracks what's visible through a front-buffer, but this is completely managed internally and cannot be expected to know what the terminal looks like if it's being modified externally.

    If you want to do more complicated drawing operations, please see the class DefaultScreenWriter which has many utility methods that works on Screens.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Interface Description
      static class  Screen.RefreshType
      This enum represents the different ways a Screen can refresh the screen, moving the back-buffer data into the front-buffer that is being displayed.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static TextCharacter DEFAULT_CHARACTER
      This is the character Screen implementations should use as a filler is there are areas not set to any particular character.
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void clear()
      Erases all the characters on the screen, effectively giving you a blank area.
      void close()
      Same as calling stopScreen()
      TerminalSize doResizeIfNecessary()
      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).
      TextCharacter getBackCharacter​(int column, int row)
      Reads a character and its associated meta-data from the back-buffer and returns it encapsulated as a ScreenCharacter.
      TextCharacter getBackCharacter​(TerminalPosition position)
      Reads a character and its associated meta-data from the back-buffer and returns it encapsulated as a ScreenCharacter.
      TerminalPosition getCursorPosition()
      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.
      TextCharacter getFrontCharacter​(int column, int row)
      Reads a character and its associated meta-data from the front-buffer and returns it encapsulated as a ScreenCharacter.
      TextCharacter getFrontCharacter​(TerminalPosition position)
      Reads a character and its associated meta-data from the front-buffer and returns it encapsulated as a ScreenCharacter.
      TabBehaviour getTabBehaviour()
      Gets the behaviour for what to do about tab characters.
      TerminalSize getTerminalSize()
      Returns the size of the screen.
      TextGraphics newTextGraphics()
      Creates a new TextGraphics objects that is targeting this Screen for writing to.
      void refresh()
      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.
      void refresh​(Screen.RefreshType refreshType)
      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.
      void scrollLines​(int firstLine, int lastLine, int distance)
      Scroll a range of lines of this Screen according to given distance.
      void setCharacter​(int column, int row, TextCharacter screenCharacter)
      Sets a character in the back-buffer to a specified value with specified colors and modifiers.
      void setCharacter​(TerminalPosition position, TextCharacter screenCharacter)
      Sets a character in the back-buffer to a specified value with specified colors and modifiers.
      void setCursorPosition​(TerminalPosition position)
      A screen implementation typically keeps a location on the screen where the cursor will be placed after drawing and refreshing the buffers, this method controls that location.
      void setTabBehaviour​(TabBehaviour tabBehaviour)
      Sets the behaviour for what to do about tab characters.
      void startScreen()
      Before you can use a Screen, you need to start it.
      void stopScreen()
      Calling this method will make the underlying terminal leave private mode, effectively going back to whatever state the terminal was in before calling startScreen().
    • Field Detail

      • DEFAULT_CHARACTER

        static final TextCharacter DEFAULT_CHARACTER
        This is the character Screen implementations should use as a filler is there are areas not set to any particular character.
    • Method Detail

      • startScreen

        void startScreen()
                  throws java.io.IOException
        Before you can use a Screen, you need to start it. By starting the screen, Lanterna will make sure the terminal is in private mode (Screen only supports private mode), clears it (so that is can set the front and back buffers to a known value) and places the cursor in the top left corner. After calling startScreen(), you can begin using the other methods on this interface. When you want to exit from the screen and return to what you had before, you can call stopScreen().
        Throws:
        java.io.IOException - if there was an underlying IO error when exiting from private mode
      • close

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

        void stopScreen()
                 throws java.io.IOException
        Calling this method will make the underlying terminal leave private mode, effectively going back to whatever state the terminal was in before calling startScreen(). Once a screen has been stopped, you can start it again with startScreen() which will restore the screens content to the terminal.
        Throws:
        java.io.IOException - if there was an underlying IO error when exiting from private mode
      • clear

        void clear()
        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.

      • getCursorPosition

        TerminalPosition getCursorPosition()
        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).
        Returns:
        Position where the cursor will be located after the screen has been refreshed or null if the cursor is not visible
      • setCursorPosition

        void setCursorPosition​(TerminalPosition position)
        A screen implementation typically keeps a location on the screen where the cursor will be placed after drawing and refreshing the buffers, this method controls that location. If you pass null, it means that the terminal will attempt to hide the cursor (if supported by the terminal).
        Parameters:
        position - TerminalPosition of the new position where the cursor should be placed after refresh(), or if null, hides the cursor
      • getTabBehaviour

        TabBehaviour getTabBehaviour()
        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.
        Returns:
        Tab behaviour that is used currently
        See Also:
        TabBehaviour
      • setTabBehaviour

        void setTabBehaviour​(TabBehaviour tabBehaviour)
        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.
        Parameters:
        tabBehaviour - Tab behaviour to use when converting a \t character to a spaces
        See Also:
        TabBehaviour
      • getTerminalSize

        TerminalSize getTerminalSize()
        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.
        Returns:
        Size of the screen, in columns and rows
      • setCharacter

        void setCharacter​(int column,
                          int row,
                          TextCharacter screenCharacter)
        Sets a character in the back-buffer to a specified value with specified colors and modifiers.
        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
      • setCharacter

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

        TextGraphics newTextGraphics()
        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.
        Returns:
        New TextGraphic object targeting this Screen
      • getFrontCharacter

        TextCharacter getFrontCharacter​(int column,
                                        int row)
        Reads a character and its associated meta-data from the front-buffer and returns it encapsulated as a ScreenCharacter.
        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
      • getFrontCharacter

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

        TextCharacter getBackCharacter​(int column,
                                       int row)
        Reads a character and its associated meta-data from the back-buffer and returns it encapsulated as a ScreenCharacter.
        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
      • getBackCharacter

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

        void refresh()
              throws java.io.IOException
        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.
        Throws:
        java.io.IOException - If there was an underlying I/O error
        See Also:
        Screen.RefreshType
      • refresh

        void refresh​(Screen.RefreshType refreshType)
              throws java.io.IOException
        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.

        Using this method call instead of refresh() gives you a little bit more control over how the screen will be refreshed.

        Parameters:
        refreshType - What type of refresh to do
        Throws:
        java.io.IOException - If there was an underlying I/O error
        See Also:
        Screen.RefreshType
      • doResizeIfNecessary

        TerminalSize doResizeIfNecessary()
        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.
        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.
      • scrollLines

        void scrollLines​(int firstLine,
                         int lastLine,
                         int distance)
        Scroll a range of lines of this Screen according to given distance. Screen implementations of this method do not throw IOException.
        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.