Class AbstractScreen

java.lang.Object
com.googlecode.lanterna.screen.AbstractScreen
All Implemented Interfaces:
Scrollable, InputProvider, Screen, Closeable, AutoCloseable
Direct Known Subclasses:
TerminalScreen, VirtualScreen

public abstract class AbstractScreen extends 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.
  • Field Details

  • Constructor Details

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

    • 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:
    • 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:
    • 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 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:
      IOException - If there was an underlying I/O error
      See Also:
    • close

      public void close() throws IOException
      Description copied from interface: Screen
      Same as calling Screen.stopScreen()
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Specified by:
      close in interface Screen
      Throws:
      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
    • getCharacterFromBuffer

      private TextCharacter getCharacterFromBuffer(ScreenBuffer buffer, int column, int row)
    • toString

      public String toString()
      Overrides:
      toString in class 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.