2 * This file is part of lanterna (http://code.google.com/p/lanterna/).
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.
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.
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/>.
17 * Copyright (C) 2010-2015 Martin
19 package com
.googlecode
.lanterna
.graphics
;
21 import com
.googlecode
.lanterna
.*;
22 import com
.googlecode
.lanterna
.screen
.TabBehaviour
;
24 import java
.util
.Collection
;
25 import java
.util
.EnumSet
;
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.
33 * The basic concept behind a TextGraphics implementation is that it keeps a state on four things:
35 * <li>Foreground color</li>
36 * <li>Background color</li>
38 * <li>Tab-expanding behaviour</li>
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).
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.
47 public interface TextGraphics
{
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
53 TerminalSize
getSize();
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
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.
69 TextGraphics
newTextGraphics(TerminalPosition topLeftCorner
, TerminalSize size
) throws IllegalArgumentException
;
72 * Returns the current background color
73 * @return Current background color
75 TextColor
getBackgroundColor();
78 * Updates the current background color
79 * @param backgroundColor New background color
82 TextGraphics
setBackgroundColor(TextColor backgroundColor
);
85 * Returns the current foreground color
86 * @return Current foreground color
88 TextColor
getForegroundColor();
91 * Updates the current foreground color
92 * @param foregroundColor New foreground color
95 TextGraphics
setForegroundColor(TextColor foregroundColor
);
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
102 TextGraphics
enableModifiers(SGR
... modifiers
);
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
109 TextGraphics
disableModifiers(SGR
... modifiers
);
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
117 TextGraphics
setModifiers(EnumSet
<SGR
> modifiers
);
120 * Removes all active modifiers
123 TextGraphics
clearModifiers();
126 * Returns all the SGR codes that are currently active in the TextGraphic
127 * @return Currently active SGR modifiers
129 EnumSet
<SGR
> getActiveModifiers();
132 * Retrieves the current tab behaviour, which is what the TextGraphics will use when expanding \t characters to
134 * @return Current behaviour in use for expanding tab to spaces
136 TabBehaviour
getTabBehaviour();
139 * Sets the behaviour to use when expanding tab characters (\t) to spaces
140 * @param tabBehaviour Behaviour to use when expanding tabs to spaces
142 TextGraphics
setTabBehaviour(TabBehaviour tabBehaviour
);
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
148 TextGraphics
fill(char c
);
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
157 TextGraphics
setCharacter(int column
, int row
, char character
);
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
167 TextGraphics
setCharacter(int column
, int row
, TextCharacter character
);
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
175 TextGraphics
setCharacter(TerminalPosition position
, char character
);
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
184 TextGraphics
setCharacter(TerminalPosition position
, TextCharacter character
);
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
194 TextGraphics
drawLine(TerminalPosition fromPoint
, TerminalPosition toPoint
, char character
);
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
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
205 TextGraphics
drawLine(TerminalPosition fromPoint
, TerminalPosition toPoint
, TextCharacter character
);
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
217 TextGraphics
drawLine(int fromX
, int fromY
, int toX
, int toY
, char character
);
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
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
230 TextGraphics
drawLine(int fromX
, int fromY
, int toX
, int toY
, TextCharacter character
);
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
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
241 TextGraphics
drawTriangle(TerminalPosition p1
, TerminalPosition p2
, TerminalPosition p3
, char character
);
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
252 TextGraphics
drawTriangle(TerminalPosition p1
, TerminalPosition p2
, TerminalPosition p3
, TextCharacter character
);
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
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
263 TextGraphics
fillTriangle(TerminalPosition p1
, TerminalPosition p2
, TerminalPosition p3
, char character
);
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
274 TextGraphics
fillTriangle(TerminalPosition p1
, TerminalPosition p2
, TerminalPosition p3
, TextCharacter character
);
277 * Draws the outline of a rectangle with a particular character (and the currently active colors and
278 * modifiers). The topLeft coordinate is inclusive.
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.
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
288 TextGraphics
drawRectangle(TerminalPosition topLeft
, TerminalSize size
, char character
);
291 * Draws the outline of a rectangle with a particular TextCharacter, ignoring the current colors and modifiers of
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.
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
302 TextGraphics
drawRectangle(TerminalPosition topLeft
, TerminalSize size
, TextCharacter character
);
305 * Takes a rectangle and fills it with a particular character (and the currently active colors and
306 * modifiers). The topLeft coordinate is inclusive.
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.
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
316 TextGraphics
fillRectangle(TerminalPosition topLeft
, TerminalSize size
, char character
);
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.
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.
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
330 TextGraphics
fillRectangle(TerminalPosition topLeft
, TerminalSize size
, TextCharacter character
);
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
340 TextGraphics
drawImage(TerminalPosition topLeft
, TextImage image
);
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
350 * @param sourceImageSize How much of the source image to draw on the target, counted from the sourceImageTopLeft
354 TextGraphics
drawImage(TerminalPosition topLeft
, TextImage image
, TerminalPosition sourceImageTopLeft
, TerminalSize sourceImageSize
);
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
365 TextGraphics
putString(int column
, int row
, String string
);
368 * Shortcut to calling:
370 * putString(position.getColumn(), position.getRow(), string);
372 * @param position Position to put the string at
373 * @param string String to put on the screen
376 TextGraphics
putString(TerminalPosition position
, String string
);
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
390 TextGraphics
putString(int column
, int row
, String string
, SGR extraModifier
, SGR
... optionalExtraModifiers
);
393 * Shortcut to calling:
395 * putString(position.getColumn(), position.getRow(), string, modifiers, optionalExtraModifiers);
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
403 TextGraphics
putString(TerminalPosition position
, String string
, SGR extraModifier
, SGR
... optionalExtraModifiers
);
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
416 TextGraphics
putString(int column
, int row
, String string
, Collection
<SGR
> extraModifiers
);
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
424 TextCharacter
getCharacter(TerminalPosition position
);
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
433 TextCharacter
getCharacter(int column
, int row
);