| 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 | } |