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.graphics; | |
20 | ||
21 | import com.googlecode.lanterna.*; | |
22 | import com.googlecode.lanterna.screen.TabBehaviour; | |
23 | ||
24 | import java.util.Collection; | |
25 | import java.util.EnumSet; | |
26 | ||
27 | /** | |
28 | * This interface exposes functionality to 'draw' text graphics on a section of the terminal. It has several | |
29 | * implementation for the different levels, including one for Terminal, one for Screen and one which is used by the | |
30 | * TextGUI system to draw components. They are all very similar and has a lot of graphics functionality in | |
31 | * AbstractTextGraphics. | |
32 | * <p> | |
33 | * The basic concept behind a TextGraphics implementation is that it keeps a state on four things: | |
34 | * <ul> | |
35 | * <li>Foreground color</li> | |
36 | * <li>Background color</li> | |
37 | * <li>Modifiers</li> | |
38 | * <li>Tab-expanding behaviour</li> | |
39 | * </ul> | |
40 | * These call all be altered through ordinary set* methods, but some will be altered as the result of performing one of | |
41 | * the 'drawing' operations. See the documentation to each method for further information (for example, putString). | |
42 | * <p> | |
43 | * Don't hold on to your TextGraphics objects for too long; ideally create them and let them be GC:ed when you are done | |
44 | * with them. The reason is that not all implementations will handle the underlying terminal changing size. | |
45 | * @author Martin | |
46 | */ | |
47 | public interface TextGraphics { | |
48 | /** | |
49 | * Returns the size of the area that this text graphic can write to. Any attempts of placing characters outside of | |
50 | * this area will be silently ignored. | |
51 | * @return Size of the writable area that this TextGraphics can write too | |
52 | */ | |
53 | TerminalSize getSize(); | |
54 | ||
55 | /** | |
56 | * Creates a new TextGraphics of the same type as this one, using the same underlying subsystem. Using this method, | |
57 | * you need to specify a section of the current TextGraphics valid area that this new TextGraphic shall be | |
58 | * restricted to. If you call <code>newTextGraphics(TerminalPosition.TOP_LEFT_CORNER, textGraphics.getSize())</code> | |
59 | * then the resulting object will be identical to this one, but having a separated state for colors, position and | |
60 | * modifiers. | |
61 | * @param topLeftCorner Position of this TextGraphics's writable area that is to become the top-left corner (0x0) of | |
62 | * the new TextGraphics | |
63 | * @param size How large area, counted from the topLeftCorner, the new TextGraphics can write to. This cannot be | |
64 | * larger than the current TextGraphics's writable area (adjusted by topLeftCorner) | |
65 | * @return A new TextGraphics with the same underlying subsystem, that can write to only the specified area | |
66 | * @throws java.lang.IllegalArgumentException If the size the of new TextGraphics exceeds the dimensions of this | |
67 | * TextGraphics in any way. | |
68 | */ | |
69 | TextGraphics newTextGraphics(TerminalPosition topLeftCorner, TerminalSize size) throws IllegalArgumentException; | |
70 | ||
71 | /** | |
72 | * Returns the current background color | |
73 | * @return Current background color | |
74 | */ | |
75 | TextColor getBackgroundColor(); | |
76 | ||
77 | /** | |
78 | * Updates the current background color | |
79 | * @param backgroundColor New background color | |
80 | * @return Itself | |
81 | */ | |
82 | TextGraphics setBackgroundColor(TextColor backgroundColor); | |
83 | ||
84 | /** | |
85 | * Returns the current foreground color | |
86 | * @return Current foreground color | |
87 | */ | |
88 | TextColor getForegroundColor(); | |
89 | ||
90 | /** | |
91 | * Updates the current foreground color | |
92 | * @param foregroundColor New foreground color | |
93 | * @return Itself | |
94 | */ | |
95 | TextGraphics setForegroundColor(TextColor foregroundColor); | |
96 | ||
97 | /** | |
98 | * Adds zero or more modifiers to the set of currently active modifiers | |
99 | * @param modifiers Modifiers to add to the set of currently active modifiers | |
100 | * @return Itself | |
101 | */ | |
102 | TextGraphics enableModifiers(SGR... modifiers); | |
103 | ||
104 | /** | |
105 | * Removes zero or more modifiers from the set of currently active modifiers | |
106 | * @param modifiers Modifiers to remove from the set of currently active modifiers | |
107 | * @return Itself | |
108 | */ | |
109 | TextGraphics disableModifiers(SGR... modifiers); | |
110 | ||
111 | /** | |
112 | * Sets the active modifiers to exactly the set passed in to this method. Any previous state of which modifiers are | |
113 | * enabled doesn't matter. | |
114 | * @param modifiers Modifiers to set as active | |
115 | * @return Itself | |
116 | */ | |
117 | TextGraphics setModifiers(EnumSet<SGR> modifiers); | |
118 | ||
119 | /** | |
120 | * Removes all active modifiers | |
121 | * @return Itself | |
122 | */ | |
123 | TextGraphics clearModifiers(); | |
124 | ||
125 | /** | |
126 | * Returns all the SGR codes that are currently active in the TextGraphic | |
127 | * @return Currently active SGR modifiers | |
128 | */ | |
129 | EnumSet<SGR> getActiveModifiers(); | |
130 | ||
131 | /** | |
132 | * Retrieves the current tab behaviour, which is what the TextGraphics will use when expanding \t characters to | |
133 | * spaces. | |
134 | * @return Current behaviour in use for expanding tab to spaces | |
135 | */ | |
136 | TabBehaviour getTabBehaviour(); | |
137 | ||
138 | /** | |
139 | * Sets the behaviour to use when expanding tab characters (\t) to spaces | |
140 | * @param tabBehaviour Behaviour to use when expanding tabs to spaces | |
141 | */ | |
142 | TextGraphics setTabBehaviour(TabBehaviour tabBehaviour); | |
143 | ||
144 | /** | |
145 | * Fills the entire writable area with a single character, using current foreground color, background color and modifiers. | |
146 | * @param c Character to fill the writable area with | |
147 | */ | |
148 | TextGraphics fill(char c); | |
149 | ||
150 | /** | |
151 | * Sets the character at the current position to the specified value | |
152 | * @param column column of the location to set the character | |
153 | * @param row row of the location to set the character | |
154 | * @param character Character to set at the current position | |
155 | * @return Itself | |
156 | */ | |
157 | TextGraphics setCharacter(int column, int row, char character); | |
158 | ||
159 | /** | |
160 | * Sets the character at the current position to the specified value, without using the current colors and modifiers | |
161 | * of this TextGraphics. | |
162 | * @param column column of the location to set the character | |
163 | * @param row row of the location to set the character | |
164 | * @param character Character data to set at the current position | |
165 | * @return Itself | |
166 | */ | |
167 | TextGraphics setCharacter(int column, int row, TextCharacter character); | |
168 | ||
169 | /** | |
170 | * Sets the character at the current position to the specified value | |
171 | * @param position position of the location to set the character | |
172 | * @param character Character to set at the current position | |
173 | * @return Itself | |
174 | */ | |
175 | TextGraphics setCharacter(TerminalPosition position, char character); | |
176 | ||
177 | /** | |
178 | * Sets the character at the current position to the specified value, without using the current colors and modifiers | |
179 | * of this TextGraphics. | |
180 | * @param position position of the location to set the character | |
181 | * @param character Character data to set at the current position | |
182 | * @return Itself | |
183 | */ | |
184 | TextGraphics setCharacter(TerminalPosition position, TextCharacter character); | |
185 | ||
186 | /** | |
187 | * Draws a line from a specified position to a specified position, using a supplied character. The current | |
188 | * foreground color, background color and modifiers will be applied. | |
189 | * @param fromPoint From where to draw the line | |
190 | * @param toPoint Where to draw the line | |
191 | * @param character Character to use for the line | |
192 | * @return Itself | |
193 | */ | |
194 | TextGraphics drawLine(TerminalPosition fromPoint, TerminalPosition toPoint, char character); | |
195 | ||
196 | /** | |
197 | * Draws a line from a specified position to a specified position, using a supplied TextCharacter. The current | |
198 | * foreground color, background color and modifiers of this TextGraphics will not be used and will not be modified | |
199 | * by this call. | |
200 | * @param fromPoint From where to draw the line | |
201 | * @param toPoint Where to draw the line | |
202 | * @param character Character data to use for the line, including character, colors and modifiers | |
203 | * @return Itself | |
204 | */ | |
205 | TextGraphics drawLine(TerminalPosition fromPoint, TerminalPosition toPoint, TextCharacter character); | |
206 | ||
207 | /** | |
208 | * Draws a line from a specified position to a specified position, using a supplied character. The current | |
209 | * foreground color, background color and modifiers will be applied. | |
210 | * @param fromX Column of the starting position to draw the line from (inclusive) | |
211 | * @param fromY Row of the starting position to draw the line from (inclusive) | |
212 | * @param toX Column of the end position to draw the line to (inclusive) | |
213 | * @param toY Row of the end position to draw the line to (inclusive) | |
214 | * @param character Character to use for the line | |
215 | * @return Itself | |
216 | */ | |
217 | TextGraphics drawLine(int fromX, int fromY, int toX, int toY, char character); | |
218 | ||
219 | /** | |
220 | * Draws a line from a specified position to a specified position, using a supplied character. The current | |
221 | * foreground color, background color and modifiers of this TextGraphics will not be used and will not be modified | |
222 | * by this call. | |
223 | * @param fromX Column of the starting position to draw the line from (inclusive) | |
224 | * @param fromY Row of the starting position to draw the line from (inclusive) | |
225 | * @param toX Column of the end position to draw the line to (inclusive) | |
226 | * @param toY Row of the end position to draw the line to (inclusive) | |
227 | * @param character Character data to use for the line, including character, colors and modifiers | |
228 | * @return Itself | |
229 | */ | |
230 | TextGraphics drawLine(int fromX, int fromY, int toX, int toY, TextCharacter character); | |
231 | ||
232 | /** | |
233 | * Draws the outline of a triangle on the screen, using a supplied character. The triangle will begin at p1, go | |
234 | * through p2 and then p3 and then back to p1. The current foreground color, background color and modifiers will be | |
235 | * applied. | |
236 | * @param p1 First point on the screen of the triangle | |
237 | * @param p2 Second point on the screen of the triangle | |
238 | * @param p3 Third point on the screen of the triangle | |
239 | * @param character What character to use when drawing the lines of the triangle | |
240 | */ | |
241 | TextGraphics drawTriangle(TerminalPosition p1, TerminalPosition p2, TerminalPosition p3, char character); | |
242 | ||
243 | /** | |
244 | * Draws the outline of a triangle on the screen, using a supplied character. The triangle will begin at p1, go | |
245 | * through p2 and then p3 and then back to p1. The current foreground color, background color and modifiers of this | |
246 | * TextGraphics will not be used and will not be modified by this call. | |
247 | * @param p1 First point on the screen of the triangle | |
248 | * @param p2 Second point on the screen of the triangle | |
249 | * @param p3 Third point on the screen of the triangle | |
250 | * @param character What character data to use when drawing the lines of the triangle | |
251 | */ | |
252 | TextGraphics drawTriangle(TerminalPosition p1, TerminalPosition p2, TerminalPosition p3, TextCharacter character); | |
253 | ||
254 | /** | |
255 | * Draws a filled triangle, using a supplied character. The triangle will begin at p1, go | |
256 | * through p2 and then p3 and then back to p1. The current foreground color, background color and modifiers will be | |
257 | * applied. | |
258 | * @param p1 First point on the screen of the triangle | |
259 | * @param p2 Second point on the screen of the triangle | |
260 | * @param p3 Third point on the screen of the triangle | |
261 | * @param character What character to use when drawing the triangle | |
262 | */ | |
263 | TextGraphics fillTriangle(TerminalPosition p1, TerminalPosition p2, TerminalPosition p3, char character); | |
264 | ||
265 | /** | |
266 | * Draws a filled triangle, using a supplied character. The triangle will begin at p1, go | |
267 | * through p2 and then p3 and then back to p1. The current foreground color, background color and modifiers of this | |
268 | * TextGraphics will not be used and will not be modified by this call. | |
269 | * @param p1 First point on the screen of the triangle | |
270 | * @param p2 Second point on the screen of the triangle | |
271 | * @param p3 Third point on the screen of the triangle | |
272 | * @param character What character data to use when drawing the triangle | |
273 | */ | |
274 | TextGraphics fillTriangle(TerminalPosition p1, TerminalPosition p2, TerminalPosition p3, TextCharacter character); | |
275 | ||
276 | /** | |
277 | * Draws the outline of a rectangle with a particular character (and the currently active colors and | |
278 | * modifiers). The topLeft coordinate is inclusive. | |
279 | * <p> | |
280 | * For example, calling drawRectangle with size being the size of the terminal and top-left value being the terminal's | |
281 | * top-left (0x0) corner will draw a border around the terminal. | |
282 | * <p> | |
283 | * The current foreground color, background color and modifiers will be applied. | |
284 | * @param topLeft Coordinates of the top-left position of the rectangle | |
285 | * @param size Size (in columns and rows) of the area to draw | |
286 | * @param character What character to use when drawing the outline of the rectangle | |
287 | */ | |
288 | TextGraphics drawRectangle(TerminalPosition topLeft, TerminalSize size, char character); | |
289 | ||
290 | /** | |
291 | * Draws the outline of a rectangle with a particular TextCharacter, ignoring the current colors and modifiers of | |
292 | * this TextGraphics. | |
293 | * <p> | |
294 | * For example, calling drawRectangle with size being the size of the terminal and top-left value being the terminal's | |
295 | * top-left (0x0) corner will draw a border around the terminal. | |
296 | * <p> | |
297 | * The current foreground color, background color and modifiers will not be modified by this call. | |
298 | * @param topLeft Coordinates of the top-left position of the rectangle | |
299 | * @param size Size (in columns and rows) of the area to draw | |
300 | * @param character What character data to use when drawing the outline of the rectangle | |
301 | */ | |
302 | TextGraphics drawRectangle(TerminalPosition topLeft, TerminalSize size, TextCharacter character); | |
303 | ||
304 | /** | |
305 | * Takes a rectangle and fills it with a particular character (and the currently active colors and | |
306 | * modifiers). The topLeft coordinate is inclusive. | |
307 | * <p> | |
308 | * For example, calling fillRectangle with size being the size of the terminal and top-left value being the terminal's | |
309 | * top-left (0x0) corner will fill the entire terminal with this character. | |
310 | * <p> | |
311 | * The current foreground color, background color and modifiers will be applied. | |
312 | * @param topLeft Coordinates of the top-left position of the rectangle | |
313 | * @param size Size (in columns and rows) of the area to draw | |
314 | * @param character What character to use when filling the rectangle | |
315 | */ | |
316 | TextGraphics fillRectangle(TerminalPosition topLeft, TerminalSize size, char character); | |
317 | ||
318 | /** | |
319 | * Takes a rectangle and fills it using a particular TextCharacter, ignoring the current colors and modifiers of | |
320 | * this TextGraphics. The topLeft coordinate is inclusive. | |
321 | * <p> | |
322 | * For example, calling fillRectangle with size being the size of the terminal and top-left value being the terminal's | |
323 | * top-left (0x0) corner will fill the entire terminal with this character. | |
324 | * <p> | |
325 | * The current foreground color, background color and modifiers will not be modified by this call. | |
326 | * @param topLeft Coordinates of the top-left position of the rectangle | |
327 | * @param size Size (in columns and rows) of the area to draw | |
328 | * @param character What character data to use when filling the rectangle | |
329 | */ | |
330 | TextGraphics fillRectangle(TerminalPosition topLeft, TerminalSize size, TextCharacter character); | |
331 | ||
332 | /** | |
333 | * Takes a TextImage and draws it on the surface this TextGraphics is targeting, given the coordinates on the target | |
334 | * that is specifying where the top-left corner of the image should be drawn. This is equivalent of calling | |
335 | * {@code drawImage(topLeft, image, TerminalPosition.TOP_LEFT_CORNER, image.getSize()}. | |
336 | * @param topLeft Position of the top-left corner of the image on the target | |
337 | * @param image Image to draw | |
338 | * @return Itself | |
339 | */ | |
340 | TextGraphics drawImage(TerminalPosition topLeft, TextImage image); | |
341 | ||
342 | /** | |
343 | * Takes a TextImage and draws it on the surface this TextGraphics is targeting, given the coordinates on the target | |
344 | * that is specifying where the top-left corner of the image should be drawn. This overload will only draw a portion | |
345 | * of the image to the target, as specified by the two last parameters. | |
346 | * @param topLeft Position of the top-left corner of the image on the target | |
347 | * @param image Image to draw | |
348 | * @param sourceImageTopLeft Position of the top-left corner in the source image to draw at the topLeft position on | |
349 | * the target | |
350 | * @param sourceImageSize How much of the source image to draw on the target, counted from the sourceImageTopLeft | |
351 | * position | |
352 | * @return Itself | |
353 | */ | |
354 | TextGraphics drawImage(TerminalPosition topLeft, TextImage image, TerminalPosition sourceImageTopLeft, TerminalSize sourceImageSize); | |
355 | ||
356 | /** | |
357 | * Puts a string on the screen at the specified position with the current colors and modifiers. If the string | |
358 | * contains newlines (\r and/or \n), the method will stop at the character before that; you have to manage | |
359 | * multi-line strings yourself! The current foreground color, background color and modifiers will be applied. | |
360 | * @param column What column to put the string at | |
361 | * @param row What row to put the string at | |
362 | * @param string String to put on the screen | |
363 | * @return Itself | |
364 | */ | |
365 | TextGraphics putString(int column, int row, String string); | |
366 | ||
367 | /** | |
368 | * Shortcut to calling: | |
369 | * <pre> | |
370 | * putString(position.getColumn(), position.getRow(), string); | |
371 | * </pre> | |
372 | * @param position Position to put the string at | |
373 | * @param string String to put on the screen | |
374 | * @return Itself | |
375 | */ | |
376 | TextGraphics putString(TerminalPosition position, String string); | |
377 | ||
378 | /** | |
379 | * Puts a string on the screen at the specified position with the current colors and modifiers. If the string | |
380 | * contains newlines (\r and/or \n), the method will stop at the character before that; you have to manage | |
381 | * multi-line strings yourself! If you supplied any extra modifiers, they will be applied when writing the string | |
382 | * as well but not recorded into the state of the TextGraphics object. | |
383 | * @param column What column to put the string at | |
384 | * @param row What row to put the string at | |
385 | * @param string String to put on the screen | |
386 | * @param extraModifier Modifier to apply to the string | |
387 | * @param optionalExtraModifiers Optional extra modifiers to apply to the string | |
388 | * @return Itself | |
389 | */ | |
390 | TextGraphics putString(int column, int row, String string, SGR extraModifier, SGR... optionalExtraModifiers); | |
391 | ||
392 | /** | |
393 | * Shortcut to calling: | |
394 | * <pre> | |
395 | * putString(position.getColumn(), position.getRow(), string, modifiers, optionalExtraModifiers); | |
396 | * </pre> | |
397 | * @param position Position to put the string at | |
398 | * @param string String to put on the screen | |
399 | * @param extraModifier Modifier to apply to the string | |
400 | * @param optionalExtraModifiers Optional extra modifiers to apply to the string | |
401 | * @return Itself | |
402 | */ | |
403 | TextGraphics putString(TerminalPosition position, String string, SGR extraModifier, SGR... optionalExtraModifiers); | |
404 | ||
405 | /** | |
406 | * Puts a string on the screen at the specified position with the current colors and modifiers. If the string | |
407 | * contains newlines (\r and/or \n), the method will stop at the character before that; you have to manage | |
408 | * multi-line strings yourself! If you supplied any extra modifiers, they will be applied when writing the string | |
409 | * as well but not recorded into the state of the TextGraphics object. | |
410 | * @param column What column to put the string at | |
411 | * @param row What row to put the string at | |
412 | * @param string String to put on the screen | |
413 | * @param extraModifiers Modifier to apply to the string | |
414 | * @return Itself | |
415 | */ | |
416 | TextGraphics putString(int column, int row, String string, Collection<SGR> extraModifiers); | |
417 | ||
418 | /** | |
419 | * Returns the character at the specific position in the terminal. May return {@code null} if the TextGraphics | |
420 | * implementation doesn't support it or doesn't know what the character is. | |
421 | * @param position Position to return the character for | |
422 | * @return The text character at the specified position or {@code null} if not available | |
423 | */ | |
424 | TextCharacter getCharacter(TerminalPosition position); | |
425 | ||
426 | /** | |
427 | * Returns the character at the specific position in the terminal. May return {@code null} if the TextGraphics | |
428 | * implementation doesn't support it or doesn't know what the character is. | |
429 | * @param column Column to return the character for | |
430 | * @param row Row to return the character for | |
431 | * @return The text character at the specified position or {@code null} if not available | |
432 | */ | |
433 | TextCharacter getCharacter(int column, int row); | |
434 | } |