Commit | Line | Data |
---|---|---|
a3b510ab NR |
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 | } |