src/com/googlecode/lanterna/screen/Screen.java

   1 /*
   2  * This file is part of lanterna (http://code.google.com/p/lanterna/).
   3  *
   4  * lanterna is free software: you can redistribute it and/or modify
   5  * it under the terms of the GNU Lesser General Public License as published by
   6  * the Free Software Foundation, either version 3 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public License
  15  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  16  *
  17  * Copyright (C) 2010-2015 Martin
  18  */
  19 package com.googlecode.lanterna.screen;
  20
  21 import com.googlecode.lanterna.TextCharacter;
  22 import com.googlecode.lanterna.graphics.Scrollable;
  23 import com.googlecode.lanterna.graphics.TextGraphics;
  24 import com.googlecode.lanterna.input.InputProvider;
  25 import com.googlecode.lanterna.TerminalPosition;
  26 import com.googlecode.lanterna.TerminalSize;
  27 import java.io.IOException;
  28
  29 /**
  30  * Screen is a fundamental layer in Lanterna, presenting the terminal as a bitmap-like surface where you can perform
  31  * smaller in-memory operations to a back-buffer, effectively painting out the terminal as you'd like it, and then call
  32  * {@code refresh} to have the screen automatically apply the changes in the back-buffer to the real terminal. The
  33  * screen tracks what's visible through a front-buffer, but this is completely managed internally and cannot be expected
  34  * to know what the terminal looks like if it's being modified externally.
  35  * <p>
  36  * If you want to do more complicated drawing operations, please see the class {@code DefaultScreenWriter} which has many
  37  * utility methods that works on Screens.
  38  *
  39  * @author Martin
  40  */
  41 public interface Screen extends InputProvider, Scrollable {
  42     /**
  43      * This is the character Screen implementations should use as a filler is there are areas not set to any particular
  44      * character.
  45      */
  46     TextCharacter DEFAULT_CHARACTER = new TextCharacter(' ');
  47
  48     /**
  49      * Before you can use a Screen, you need to start it. By starting the screen, Lanterna will make sure the terminal
  50      * is in private mode (Screen only supports private mode), clears it (so that is can set the front and back buffers
  51      * to a known value) and places the cursor in the top left corner. After calling startScreen(), you can begin using
  52      * the other methods on this interface. When you want to exit from the screen and return to what you had before,
  53      * you can call {@code stopScreen()}.
  54      *
  55      * @throws IOException if there was an underlying IO error when exiting from private mode
  56      */
  57     void startScreen() throws IOException;
  58
  59     /**
  60      * Calling this method will make the underlying terminal leave private mode, effectively going back to whatever
  61      * state the terminal was in before calling {@code startScreen()}. Once a screen has been stopped, you can start it
  62      * again with {@code startScreen()} which will restore the screens content to the terminal.
  63      *
  64      * @throws IOException if there was an underlying IO error when exiting from private mode
  65      */
  66     void stopScreen() throws IOException;
  67
  68     /**
  69      * Erases all the characters on the screen, effectively giving you a blank area. The default background color will
  70      * be used. This is effectively the same as calling
  71      * <pre>fill(TerminalPosition.TOP_LEFT_CORNER, getSize(), TextColor.ANSI.Default)</pre>.
  72      * <p>
  73      * Please note that calling this method will only affect the back buffer, you need to call refresh to make the
  74      * change visible.
  75      */
  76     void clear();
  77
  78     /**
  79      * A screen implementation typically keeps a location on the screen where the cursor will be placed after drawing
  80      * and refreshing the buffers, this method returns that location. If it returns null, it means that the terminal
  81      * will attempt to hide the cursor (if supported by the terminal).
  82      *
  83      * @return Position where the cursor will be located after the screen has been refreshed or {@code null} if the
  84      * cursor is not visible
  85      */
  86     TerminalPosition getCursorPosition();
  87
  88     /**
  89      * A screen implementation typically keeps a location on the screen where the cursor will be placed after drawing
  90      * and refreshing the buffers, this method controls that location. If you pass null, it means that the terminal
  91      * will attempt to hide the cursor (if supported by the terminal).
  92      *
  93      * @param position TerminalPosition of the new position where the cursor should be placed after refresh(), or if
  94      * {@code null}, hides the cursor
  95      */
  96     void setCursorPosition(TerminalPosition position);
  97
  98     /**
  99      * Gets the behaviour for what to do about tab characters. If a tab character is written to the Screen, it would
 100      * cause issues because we don't know how the terminal emulator would render it and we wouldn't know what state the
 101      * front-buffer is in. Because of this, we convert tabs to a determined number of spaces depending on different
 102      * rules that are available.
 103      *
 104      * @return Tab behaviour that is used currently
 105      * @see TabBehaviour
 106      */
 107     TabBehaviour getTabBehaviour();
 108
 109     /**
 110      * Sets the behaviour for what to do about tab characters. If a tab character is written to the Screen, it would
 111      * cause issues because we don't know how the terminal emulator would render it and we wouldn't know what state the
 112      * front-buffer is in. Because of this, we convert tabs to a determined number of spaces depending on different
 113      * rules that are available.
 114      *
 115      * @param tabBehaviour Tab behaviour to use when converting a \t character to a spaces
 116      * @see TabBehaviour
 117      */
 118     void setTabBehaviour(TabBehaviour tabBehaviour);
 119
 120     /**
 121      * Returns the size of the screen. This call is not blocking but should return the size of the screen as it is
 122      * represented by the buffer at the time this method is called.
 123      *
 124      * @return Size of the screen, in columns and rows
 125      */
 126     TerminalSize getTerminalSize();
 127
 128     /**
 129      * Sets a character in the back-buffer to a specified value with specified colors and modifiers.
 130      * @param column Column of the character to modify (x coordinate)
 131      * @param row Row of the character to modify (y coordinate)
 132      * @param screenCharacter New data to put at the specified position
 133      */
 134     void setCharacter(int column, int row, TextCharacter screenCharacter);
 135
 136     /**
 137      * Sets a character in the back-buffer to a specified value with specified colors and modifiers.
 138      * @param position Which position in the terminal to modify
 139      * @param screenCharacter New data to put at the specified position
 140      */
 141     void setCharacter(TerminalPosition position, TextCharacter screenCharacter);
 142
 143     /**
 144      * Creates a new TextGraphics objects that is targeting this Screen for writing to. Any operations done on this
 145      * TextGraphics will be affecting this screen. Remember to call {@code refresh()} on the screen to see your changes.
 146      *
 147      * @return New TextGraphic object targeting this Screen
 148      */
 149     TextGraphics newTextGraphics();
 150
 151     /**
 152      * Reads a character and its associated meta-data from the front-buffer and returns it encapsulated as a
 153      * ScreenCharacter.
 154      * @param column Which column to get the character from
 155      * @param row Which row to get the character from
 156      * @return A {@code ScreenCharacter} representation of the character in the front-buffer at the specified location
 157      */
 158     TextCharacter getFrontCharacter(int column, int row);
 159
 160     /**
 161      * Reads a character and its associated meta-data from the front-buffer and returns it encapsulated as a
 162      * ScreenCharacter.
 163      * @param position What position to read the character from
 164      * @return A {@code ScreenCharacter} representation of the character in the front-buffer at the specified location
 165      */
 166     TextCharacter getFrontCharacter(TerminalPosition position);
 167
 168     /**
 169      * Reads a character and its associated meta-data from the back-buffer and returns it encapsulated as a
 170      * ScreenCharacter.
 171      * @param column Which column to get the character from
 172      * @param row Which row to get the character from
 173      * @return A {@code ScreenCharacter} representation of the character in the back-buffer at the specified location
 174      */
 175     TextCharacter getBackCharacter(int column, int row);
 176
 177     /**
 178      * Reads a character and its associated meta-data from the back-buffer and returns it encapsulated as a
 179      * ScreenCharacter.
 180      * @param position What position to read the character from
 181      * @return A {@code ScreenCharacter} representation of the character in the back-buffer at the specified location
 182      */
 183     TextCharacter getBackCharacter(TerminalPosition position);
 184
 185     /**
 186      * This method will take the content from the back-buffer and move it into the front-buffer, making the changes
 187      * visible to the terminal in the process. The graphics workflow with Screen would involve drawing text and text-like
 188      * graphics on the back buffer and then finally calling refresh(..) to make it visible to the user.
 189      * @throws java.io.IOException If there was an underlying I/O error
 190      * @see RefreshType
 191      */
 192     void refresh() throws IOException;
 193
 194     /**
 195      * This method will take the content from the back-buffer and move it into the front-buffer, making the changes
 196      * visible to the terminal in the process. The graphics workflow with Screen would involve drawing text and text-like
 197      * graphics on the back buffer and then finally calling refresh(..) to make it visible to the user.
 198      * <p>
 199      * Using this method call instead of {@code refresh()} gives you a little bit more control over how the screen will
 200      * be refreshed.
 201      * @param refreshType What type of refresh to do
 202      * @throws java.io.IOException If there was an underlying I/O error
 203      * @see RefreshType
 204      */
 205     void refresh(RefreshType refreshType) throws IOException;
 206
 207     /**
 208      * One problem working with Screens is that whenever the terminal is resized, the front and back buffers needs to be
 209      * adjusted accordingly and the program should have a chance to figure out what to do with this extra space (or less
 210      * space). The solution is to call, at the start of your rendering code, this method, which will check if the
 211      * terminal has been resized and in that case update the internals of the Screen. After this call finishes, the
 212      * screen's internal buffers will match the most recent size report from the underlying terminal.
 213      *
 214      * @return If the terminal has been resized since this method was last called, it will return the new size of the
 215      * terminal. If not, it will return null.
 216      */
 217     TerminalSize doResizeIfNecessary();
 218
 219     /**
 220      * Scroll a range of lines of this Screen according to given distance.
 221      *
 222      * Screen implementations of this method do <b>not</b> throw IOException.
 223      */
 224     @Override
 225     void scrollLines(int firstLine, int lastLine, int distance);
 226
 227     /**
 228      * This enum represents the different ways a Screen can refresh the screen, moving the back-buffer data into the
 229      * front-buffer that is being displayed.
 230      */
 231     enum RefreshType {
 232         /**
 233          * Using automatic mode, the Screen will make a guess at which refresh type would be the fastest and use this one.
 234          */
 235         AUTOMATIC,
 236         /**
 237          * In {@code RefreshType.DELTA} mode, the Screen will calculate a diff between the back-buffer and the
 238          * front-buffer, then figure out the set of terminal commands that is required to make the front-buffer exactly
 239          * like the back-buffer. This normally works well when you have modified only parts of the screen, but if you
 240          * have modified almost everything it will cause a lot of overhead and you should use
 241          * {@code RefreshType.COMPLETE} instead.
 242          */
 243         DELTA,
 244         /**
 245          * In {@code RefreshType.COMPLETE} mode, the screen will send a clear command to the terminal, then redraw the
 246          * whole back-buffer line by line. This is more expensive than {@code RefreshType.COMPLETE}, especially when you
 247          * have only touched smaller parts of the screen, but can be faster if you have modified most of the content,
 248          * as well as if you suspect the screen's internal front buffer is out-of-sync with what's really showing on the
 249          * terminal (you didn't go and call methods on the underlying Terminal while in screen mode, did you?)
 250          */
 251         COMPLETE,
 252         ;
 253     }
 254 }