/*
 * This file is part of lanterna (http://code.google.com/p/lanterna/).
 *
 * lanterna is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 * Copyright (C) 2010-2020 Martin Berglund
 */
package com.googlecode.lanterna.graphics;

import com.googlecode.lanterna.*;
import com.googlecode.lanterna.screen.TabBehaviour;

import java.util.Collection;

This interface exposes functionality to 'draw' text graphics on a section of the terminal. It has several
implementation for the different levels, including one for Terminal, one for Screen and one which is used by the
TextGUI system to draw components. They are all very similar and has a lot of graphics functionality in
AbstractTextGraphics.

The basic concept behind a TextGraphics implementation is that it keeps a state on four things:

    
Foreground color
    
Background color
    
Modifiers
    
Tab-expanding behaviour

These call all be altered through ordinary set* methods, but some will be altered as the result of performing one of
the 'drawing' operations. See the documentation to each method for further information (for example, putString).

Don't hold on to your TextGraphics objects for too long; ideally create them and let them be GC:ed when you are done
with them. The reason is that not all implementations will handle the underlying terminal changing size.
Author:
Martin/**
 * This interface exposes functionality to 'draw' text graphics on a section of the terminal. It has several
 * implementation for the different levels, including one for Terminal, one for Screen and one which is used by the
 * TextGUI system to draw components. They are all very similar and has a lot of graphics functionality in
 * AbstractTextGraphics.
 * <p>
 * The basic concept behind a TextGraphics implementation is that it keeps a state on four things:
 * <ul>
 *     <li>Foreground color</li>
 *     <li>Background color</li>
 *     <li>Modifiers</li>
 *     <li>Tab-expanding behaviour</li>
 * </ul>
 * These call all be altered through ordinary set* methods, but some will be altered as the result of performing one of
 * the 'drawing' operations. See the documentation to each method for further information (for example, putString).
 * <p>
 * Don't hold on to your TextGraphics objects for too long; ideally create them and let them be GC:ed when you are done
 * with them. The reason is that not all implementations will handle the underlying terminal changing size.
 * @author Martin
 */
public interface TextGraphics extends StyleSet<TextGraphics> {
    
Returns the size of the area that this text graphic can write to. Any attempts of placing characters outside of
this area will be silently ignored.
Returns:
Size of the writable area that this TextGraphics can write too/**
     * Returns the size of the area that this text graphic can write to. Any attempts of placing characters outside of
     * this area will be silently ignored.
     * @return Size of the writable area that this TextGraphics can write too
     */
    TerminalSize getSize();

    
Creates a new TextGraphics of the same type as this one, using the same underlying subsystem. Using this method,
you need to specify a section of the current TextGraphics valid area that this new TextGraphic shall be
restricted to. If you call newTextGraphics(TerminalPosition.TOP_LEFT_CORNER, textGraphics.getSize())
then the resulting object will be identical to this one, but having a separated state for colors, position and
modifiers.
Params:
topLeftCorner – Position of this TextGraphics's writable area that is to become the top-left corner (0x0) of
                     the new TextGraphics
size – How large area, counted from the topLeftCorner, the new TextGraphics can write to. This cannot be
            larger than the current TextGraphics's writable area (adjusted by topLeftCorner)
Throws:
IllegalArgumentException – If the size the of new TextGraphics exceeds the dimensions of this
TextGraphics in any way.
Returns:
A new TextGraphics with the same underlying subsystem, that can write to only the specified area/**
     * Creates a new TextGraphics of the same type as this one, using the same underlying subsystem. Using this method,
     * you need to specify a section of the current TextGraphics valid area that this new TextGraphic shall be
     * restricted to. If you call <code>newTextGraphics(TerminalPosition.TOP_LEFT_CORNER, textGraphics.getSize())</code>
     * then the resulting object will be identical to this one, but having a separated state for colors, position and
     * modifiers.
     * @param topLeftCorner Position of this TextGraphics's writable area that is to become the top-left corner (0x0) of
     *                      the new TextGraphics
     * @param size How large area, counted from the topLeftCorner, the new TextGraphics can write to. This cannot be
     *             larger than the current TextGraphics's writable area (adjusted by topLeftCorner)
     * @return A new TextGraphics with the same underlying subsystem, that can write to only the specified area
     * @throws java.lang.IllegalArgumentException If the size the of new TextGraphics exceeds the dimensions of this
     * TextGraphics in any way.
     */
    TextGraphics newTextGraphics(TerminalPosition topLeftCorner, TerminalSize size) throws IllegalArgumentException;

    
Retrieves the current tab behaviour, which is what the TextGraphics will use when expanding \t characters to
spaces.
Returns:
Current behaviour in use for expanding tab to spaces/**
     * Retrieves the current tab behaviour, which is what the TextGraphics will use when expanding \t characters to
     * spaces.
     * @return Current behaviour in use for expanding tab to spaces
     */
    TabBehaviour getTabBehaviour();

    
Sets the behaviour to use when expanding tab characters (\t) to spaces
Params:
tabBehaviour – Behaviour to use when expanding tabs to spaces
Returns:
Itself/**
     * Sets the behaviour to use when expanding tab characters (\t) to spaces
     * @param tabBehaviour Behaviour to use when expanding tabs to spaces
     * @return Itself
     */
    TextGraphics setTabBehaviour(TabBehaviour tabBehaviour);

    
Fills the entire writable area with a single character, using current foreground color, background color and modifiers.
Params:
c – Character to fill the writable area with
Returns:
Itself/**
     * Fills the entire writable area with a single character, using current foreground color, background color and modifiers.
     * @param c Character to fill the writable area with
     * @return Itself
     */
    TextGraphics fill(char c);

    
Sets the character at the current position to the specified value
Params:
column – column of the location to set the character
row – row of the location to set the character
character – Character to set at the current position
Returns:
Itself/**
     * Sets the character at the current position to the specified value
     * @param column column of the location to set the character
     * @param row row of the location to set the character
     * @param character Character to set at the current position
     * @return Itself
     */
    TextGraphics setCharacter(int column, int row, char character);

    
Sets the character at the current position to the specified value, without using the current colors and modifiers
of this TextGraphics.
Params:
column – column of the location to set the character
row – row of the location to set the character
character – Character data to set at the current position
Returns:
Itself/**
     * Sets the character at the current position to the specified value, without using the current colors and modifiers
     * of this TextGraphics.
     * @param column column of the location to set the character
     * @param row row of the location to set the character
     * @param character Character data to set at the current position
     * @return Itself
     */
    TextGraphics setCharacter(int column, int row, TextCharacter character);

    
Sets the character at the current position to the specified value
Params:
position – position of the location to set the character
character – Character to set at the current position
Returns:
Itself/**
     * Sets the character at the current position to the specified value
     * @param position position of the location to set the character
     * @param character Character to set at the current position
     * @return Itself
     */
    TextGraphics setCharacter(TerminalPosition position, char character);

    
Sets the character at the current position to the specified value, without using the current colors and modifiers
of this TextGraphics.
Params:
position – position of the location to set the character
character – Character data to set at the current position
Returns:
Itself/**
     * Sets the character at the current position to the specified value, without using the current colors and modifiers
     * of this TextGraphics.
     * @param position position of the location to set the character
     * @param character Character data to set at the current position
     * @return Itself
     */
    TextGraphics setCharacter(TerminalPosition position, TextCharacter character);

    
Draws a line from a specified position to a specified position, using a supplied character. The current
foreground color, background color and modifiers will be applied.
Params:
fromPoint – From where to draw the line
toPoint – Where to draw the line
character – Character to use for the line
Returns:
Itself/**
     * Draws a line from a specified position to a specified position, using a supplied character. The current
     * foreground color, background color and modifiers will be applied.
     * @param fromPoint From where to draw the line
     * @param toPoint Where to draw the line
     * @param character Character to use for the line
     * @return Itself
     */
    TextGraphics drawLine(TerminalPosition fromPoint, TerminalPosition toPoint, char character);

    
Draws a line from a specified position to a specified position, using a supplied TextCharacter. The current
foreground color, background color and modifiers of this TextGraphics will not be used and will not be modified
by this call.
Params:
fromPoint – From where to draw the line
toPoint – Where to draw the line
character – Character data to use for the line, including character, colors and modifiers
Returns:
Itself/**
     * Draws a line from a specified position to a specified position, using a supplied TextCharacter. The current
     * foreground color, background color and modifiers of this TextGraphics will not be used and will not be modified
     * by this call.
     * @param fromPoint From where to draw the line
     * @param toPoint Where to draw the line
     * @param character Character data to use for the line, including character, colors and modifiers
     * @return Itself
     */
    TextGraphics drawLine(TerminalPosition fromPoint, TerminalPosition toPoint, TextCharacter character);
    
    
Draws a line from a specified position to a specified position, using a supplied character. The current
foreground color, background color and modifiers will be applied.
Params:
fromX – Column of the starting position to draw the line from (inclusive)
fromY – Row of the starting position to draw the line from (inclusive)
toX – Column of the end position to draw the line to (inclusive)
toY – Row of the end position to draw the line to (inclusive)
character – Character to use for the line
Returns:
Itself/**
     * Draws a line from a specified position to a specified position, using a supplied character. The current
     * foreground color, background color and modifiers will be applied.
     * @param fromX Column of the starting position to draw the line from (inclusive)
     * @param fromY Row of the starting position to draw the line from (inclusive)
     * @param toX Column of the end position to draw the line to (inclusive)
     * @param toY Row of the end position to draw the line to (inclusive)
     * @param character Character to use for the line
     * @return Itself
     */
    TextGraphics drawLine(int fromX, int fromY, int toX, int toY, char character);

    
Draws a line from a specified position to a specified position, using a supplied character. The current
foreground color, background color and modifiers of this TextGraphics will not be used and will not be modified
by this call.
Params:
fromX – Column of the starting position to draw the line from (inclusive)
fromY – Row of the starting position to draw the line from (inclusive)
toX – Column of the end position to draw the line to (inclusive)
toY – Row of the end position to draw the line to (inclusive)
character – Character data to use for the line, including character, colors and modifiers
Returns:
Itself/**
     * Draws a line from a specified position to a specified position, using a supplied character. The current
     * foreground color, background color and modifiers of this TextGraphics will not be used and will not be modified
     * by this call.
     * @param fromX Column of the starting position to draw the line from (inclusive)
     * @param fromY Row of the starting position to draw the line from (inclusive)
     * @param toX Column of the end position to draw the line to (inclusive)
     * @param toY Row of the end position to draw the line to (inclusive)
     * @param character Character data to use for the line, including character, colors and modifiers
     * @return Itself
     */
    TextGraphics drawLine(int fromX, int fromY, int toX, int toY, TextCharacter character);
    
    
Draws the outline of a triangle on the screen, using a supplied character. The triangle will begin at p1, go
through p2 and then p3 and then back to p1. The current foreground color, background color and modifiers will be
applied.
Params:
p1 – First point on the screen of the triangle
p2 – Second point on the screen of the triangle
p3 – Third point on the screen of the triangle
character – What character to use when drawing the lines of the triangle
Returns:
Itself/**
     * Draws the outline of a triangle on the screen, using a supplied character. The triangle will begin at p1, go
     * through p2 and then p3 and then back to p1. The current foreground color, background color and modifiers will be
     * applied.
     * @param p1 First point on the screen of the triangle
     * @param p2 Second point on the screen of the triangle
     * @param p3 Third point on the screen of the triangle
     * @param character What character to use when drawing the lines of the triangle
     * @return Itself
     */
    TextGraphics drawTriangle(TerminalPosition p1, TerminalPosition p2, TerminalPosition p3, char character);

    
Draws the outline of a triangle on the screen, using a supplied character. The triangle will begin at p1, go
through p2 and then p3 and then back to p1. The current foreground color, background color and modifiers of this
TextGraphics will not be used and will not be modified by this call.
Params:
p1 – First point on the screen of the triangle
p2 – Second point on the screen of the triangle
p3 – Third point on the screen of the triangle
character – What character data to use when drawing the lines of the triangle
Returns:
Itself/**
     * Draws the outline of a triangle on the screen, using a supplied character. The triangle will begin at p1, go
     * through p2 and then p3 and then back to p1. The current foreground color, background color and modifiers of this
     * TextGraphics will not be used and will not be modified by this call.
     * @param p1 First point on the screen of the triangle
     * @param p2 Second point on the screen of the triangle
     * @param p3 Third point on the screen of the triangle
     * @param character What character data to use when drawing the lines of the triangle
     * @return Itself
     */
    TextGraphics drawTriangle(TerminalPosition p1, TerminalPosition p2, TerminalPosition p3, TextCharacter character);

    
Draws a filled triangle, using a supplied character. The triangle will begin at p1, go
through p2 and then p3 and then back to p1. The current foreground color, background color and modifiers will be
applied.
Params:
p1 – First point on the screen of the triangle
p2 – Second point on the screen of the triangle
p3 – Third point on the screen of the triangle
character – What character to use when drawing the triangle
Returns:
Itself/**
     * Draws a filled triangle, using a supplied character. The triangle will begin at p1, go
     * through p2 and then p3 and then back to p1. The current foreground color, background color and modifiers will be
     * applied.
     * @param p1 First point on the screen of the triangle
     * @param p2 Second point on the screen of the triangle
     * @param p3 Third point on the screen of the triangle
     * @param character What character to use when drawing the triangle
     * @return Itself
     */
    TextGraphics fillTriangle(TerminalPosition p1, TerminalPosition p2, TerminalPosition p3, char character);

    
Draws a filled triangle, using a supplied character. The triangle will begin at p1, go
through p2 and then p3 and then back to p1. The current foreground color, background color and modifiers of this
TextGraphics will not be used and will not be modified by this call.
Params:
p1 – First point on the screen of the triangle
p2 – Second point on the screen of the triangle
p3 – Third point on the screen of the triangle
character – What character data to use when drawing the triangle
Returns:
Itself/**
     * Draws a filled triangle, using a supplied character. The triangle will begin at p1, go
     * through p2 and then p3 and then back to p1. The current foreground color, background color and modifiers of this
     * TextGraphics will not be used and will not be modified by this call.
     * @param p1 First point on the screen of the triangle
     * @param p2 Second point on the screen of the triangle
     * @param p3 Third point on the screen of the triangle
     * @param character What character data to use when drawing the triangle
     * @return Itself
     */
    TextGraphics fillTriangle(TerminalPosition p1, TerminalPosition p2, TerminalPosition p3, TextCharacter character);

    
Draws the outline of a rectangle with a particular character (and the currently active colors and
modifiers). The topLeft coordinate is inclusive.

For example, calling drawRectangle with size being the size of the terminal and top-left value being the terminal's
top-left (0x0) corner will draw a border around the terminal.

The current foreground color, background color and modifiers will be applied.
Params:
topLeft – Coordinates of the top-left position of the rectangle
size – Size (in columns and rows) of the area to draw
character – What character to use when drawing the outline of the rectangle
Returns:
Itself/**
     * Draws the outline of a rectangle with a particular character (and the currently active colors and
     * modifiers). The topLeft coordinate is inclusive.
     * <p>
     * For example, calling drawRectangle with size being the size of the terminal and top-left value being the terminal's
     * top-left (0x0) corner will draw a border around the terminal.
     * <p>
     * The current foreground color, background color and modifiers will be applied.
     * @param topLeft Coordinates of the top-left position of the rectangle
     * @param size Size (in columns and rows) of the area to draw
     * @param character What character to use when drawing the outline of the rectangle
     * @return Itself
     */
    TextGraphics drawRectangle(TerminalPosition topLeft, TerminalSize size, char character);

    
Draws the outline of a rectangle with a particular TextCharacter, ignoring the current colors and modifiers of
this TextGraphics.

For example, calling drawRectangle with size being the size of the terminal and top-left value being the terminal's
top-left (0x0) corner will draw a border around the terminal.

The current foreground color, background color and modifiers will not be modified by this call.
Params:
topLeft – Coordinates of the top-left position of the rectangle
size – Size (in columns and rows) of the area to draw
character – What character data to use when drawing the outline of the rectangle
Returns:
Itself/**
     * Draws the outline of a rectangle with a particular TextCharacter, ignoring the current colors and modifiers of
     * this TextGraphics.
     * <p>
     * For example, calling drawRectangle with size being the size of the terminal and top-left value being the terminal's
     * top-left (0x0) corner will draw a border around the terminal.
     * <p>
     * The current foreground color, background color and modifiers will not be modified by this call.
     * @param topLeft Coordinates of the top-left position of the rectangle
     * @param size Size (in columns and rows) of the area to draw
     * @param character What character data to use when drawing the outline of the rectangle
     * @return Itself
     */
    TextGraphics drawRectangle(TerminalPosition topLeft, TerminalSize size, TextCharacter character);

    
Takes a rectangle and fills it with a particular character (and the currently active colors and
modifiers). The topLeft coordinate is inclusive.

For example, calling fillRectangle with size being the size of the terminal and top-left value being the terminal's
top-left (0x0) corner will fill the entire terminal with this character.

The current foreground color, background color and modifiers will be applied.
Params:
topLeft – Coordinates of the top-left position of the rectangle
size – Size (in columns and rows) of the area to draw
character – What character to use when filling the rectangle
Returns:
Itself/**
     * Takes a rectangle and fills it with a particular character (and the currently active colors and
     * modifiers). The topLeft coordinate is inclusive.
     * <p>
     * For example, calling fillRectangle with size being the size of the terminal and top-left value being the terminal's
     * top-left (0x0) corner will fill the entire terminal with this character.
     * <p>
     * The current foreground color, background color and modifiers will be applied.
     * @param topLeft Coordinates of the top-left position of the rectangle
     * @param size Size (in columns and rows) of the area to draw
     * @param character What character to use when filling the rectangle
     * @return Itself
     */
    TextGraphics fillRectangle(TerminalPosition topLeft, TerminalSize size, char character);

    
Takes a rectangle and fills it using a particular TextCharacter, ignoring the current colors and modifiers of
this TextGraphics. The topLeft coordinate is inclusive.

For example, calling fillRectangle with size being the size of the terminal and top-left value being the terminal's
top-left (0x0) corner will fill the entire terminal with this character.

The current foreground color, background color and modifiers will not be modified by this call.
Params:
topLeft – Coordinates of the top-left position of the rectangle
size – Size (in columns and rows) of the area to draw
character – What character data to use when filling the rectangle
Returns:
Itself/**
     * Takes a rectangle and fills it using a particular TextCharacter, ignoring the current colors and modifiers of
     * this TextGraphics. The topLeft coordinate is inclusive.
     * <p>
     * For example, calling fillRectangle with size being the size of the terminal and top-left value being the terminal's
     * top-left (0x0) corner will fill the entire terminal with this character.
     * <p>
     * The current foreground color, background color and modifiers will not be modified by this call.
     * @param topLeft Coordinates of the top-left position of the rectangle
     * @param size Size (in columns and rows) of the area to draw
     * @param character What character data to use when filling the rectangle
     * @return Itself
     */
    TextGraphics fillRectangle(TerminalPosition topLeft, TerminalSize size, TextCharacter character);
    
    
Takes a TextImage and draws it on the surface this TextGraphics is targeting, given the coordinates on the target that is specifying where the top-left corner of the image should be drawn. This is equivalent of calling drawImage(topLeft, image, TerminalPosition.TOP_LEFT_CORNER, image.getSize(). 
Params:
topLeft – Position of the top-left corner of the image on the target
image – Image to draw
Returns:
Itself/**
     * Takes a TextImage and draws it on the surface this TextGraphics is targeting, given the coordinates on the target
     * that is specifying where the top-left corner of the image should be drawn. This is equivalent of calling
     * {@code drawImage(topLeft, image, TerminalPosition.TOP_LEFT_CORNER, image.getSize()}.
     * @param topLeft Position of the top-left corner of the image on the target
     * @param image Image to draw
     * @return Itself
     */
    TextGraphics drawImage(TerminalPosition topLeft, TextImage image);

    
Takes a TextImage and draws it on the surface this TextGraphics is targeting, given the coordinates on the target
that is specifying where the top-left corner of the image should be drawn. This overload will only draw a portion
of the image to the target, as specified by the two last parameters.
Params:
topLeft – Position of the top-left corner of the image on the target
image – Image to draw
sourceImageTopLeft – Position of the top-left corner in the source image to draw at the topLeft position on
                         the target
sourceImageSize – How much of the source image to draw on the target, counted from the sourceImageTopLeft
                       position
Returns:
Itself/**
     * Takes a TextImage and draws it on the surface this TextGraphics is targeting, given the coordinates on the target
     * that is specifying where the top-left corner of the image should be drawn. This overload will only draw a portion
     * of the image to the target, as specified by the two last parameters.
     * @param topLeft Position of the top-left corner of the image on the target
     * @param image Image to draw
     * @param sourceImageTopLeft Position of the top-left corner in the source image to draw at the topLeft position on
     *                          the target
     * @param sourceImageSize How much of the source image to draw on the target, counted from the sourceImageTopLeft
     *                        position
     * @return Itself
     */
    TextGraphics drawImage(TerminalPosition topLeft, TextImage image, TerminalPosition sourceImageTopLeft, TerminalSize sourceImageSize);

    
Puts a string on the screen at the specified position with the current colors and modifiers. If the string
contains newlines (\r and/or \n), the method will stop at the character before that; you have to manage
multi-line strings yourself! The current foreground color, background color and modifiers will be applied.
Params:
column – What column to put the string at
row – What row to put the string at
string – String to put on the screen
Returns:
Itself/**
     * Puts a string on the screen at the specified position with the current colors and modifiers. If the string
     * contains newlines (\r and/or \n), the method will stop at the character before that; you have to manage
     * multi-line strings yourself! The current foreground color, background color and modifiers will be applied.
     * @param column What column to put the string at
     * @param row What row to put the string at
     * @param string String to put on the screen
     * @return Itself
     */
    TextGraphics putString(int column, int row, String string);

    
Shortcut to calling:
 putString(position.getColumn(), position.getRow(), string);

Params:
position – Position to put the string at
string – String to put on the screen
Returns:
Itself/**
     * Shortcut to calling:
     * <pre>
     *  putString(position.getColumn(), position.getRow(), string);
     * </pre>
     * @param position Position to put the string at
     * @param string String to put on the screen
     * @return Itself
     */
    TextGraphics putString(TerminalPosition position, String string);

    
Puts a string on the screen at the specified position with the current colors and modifiers. If the string
contains newlines (\r and/or \n), the method will stop at the character before that; you have to manage
multi-line strings yourself! If you supplied any extra modifiers, they will be applied when writing the string
as well but not recorded into the state of the TextGraphics object.
Params:
column – What column to put the string at
row – What row to put the string at
string – String to put on the screen
extraModifier – Modifier to apply to the string
optionalExtraModifiers – Optional extra modifiers to apply to the string
Returns:
Itself/**
     * Puts a string on the screen at the specified position with the current colors and modifiers. If the string
     * contains newlines (\r and/or \n), the method will stop at the character before that; you have to manage
     * multi-line strings yourself! If you supplied any extra modifiers, they will be applied when writing the string
     * as well but not recorded into the state of the TextGraphics object.
     * @param column What column to put the string at
     * @param row What row to put the string at
     * @param string String to put on the screen
     * @param extraModifier Modifier to apply to the string
     * @param optionalExtraModifiers Optional extra modifiers to apply to the string
     * @return Itself
     */
    TextGraphics putString(int column, int row, String string, SGR extraModifier, SGR... optionalExtraModifiers);

    
Shortcut to calling:
 putString(position.getColumn(), position.getRow(), string, modifiers, optionalExtraModifiers);

Params:
position – Position to put the string at
string – String to put on the screen
extraModifier – Modifier to apply to the string
optionalExtraModifiers – Optional extra modifiers to apply to the string
Returns:
Itself/**
     * Shortcut to calling:
     * <pre>
     *  putString(position.getColumn(), position.getRow(), string, modifiers, optionalExtraModifiers);
     * </pre>
     * @param position Position to put the string at
     * @param string String to put on the screen
     * @param extraModifier Modifier to apply to the string
     * @param optionalExtraModifiers Optional extra modifiers to apply to the string
     * @return Itself
     */
    TextGraphics putString(TerminalPosition position, String string, SGR extraModifier, SGR... optionalExtraModifiers);

    
Puts a string on the screen at the specified position with the current colors and modifiers. If the string
contains newlines (\r and/or \n), the method will stop at the character before that; you have to manage
multi-line strings yourself! If you supplied any extra modifiers, they will be applied when writing the string
as well but not recorded into the state of the TextGraphics object.
Params:
column – What column to put the string at
row – What row to put the string at
string – String to put on the screen
extraModifiers – Modifier to apply to the string
Returns:
Itself/**
     * Puts a string on the screen at the specified position with the current colors and modifiers. If the string
     * contains newlines (\r and/or \n), the method will stop at the character before that; you have to manage
     * multi-line strings yourself! If you supplied any extra modifiers, they will be applied when writing the string
     * as well but not recorded into the state of the TextGraphics object.
     * @param column What column to put the string at
     * @param row What row to put the string at
     * @param string String to put on the screen
     * @param extraModifiers Modifier to apply to the string
     * @return Itself
     */
    TextGraphics putString(int column, int row, String string, Collection<SGR> extraModifiers);

    
Puts a string on the screen at the specified position with the current colors and modifiers. If the string
contains newlines (\r and/or \n), the method will stop at the character before that; you have to manage
multi-line strings yourself!
 This method has an additional functionality to the regular putString(int, int, String); if you embed ANSI CSI-style control sequences (like modifying text color or controlling SGR status), they will be interpreted as the string is printed and mutates the TextGraphics object. In this version of Lanterna, the following sequences are supported: 

    
Set foreground color
    
Set background color
    
Set/Clear bold style
    
Set/Clear underline style
    
Set/Clear blink style
    
Set/Clear reverse style
    
Clear all styles and colors (notice that this will return the state to what it was at the start of the method)
 When the call is complete, the TextGraphics object will return to the color/style state it was in at the start of the call. 
Params:
column – What column to put the string at
row – What row to put the string at
string – String to put on the screen
Returns:
Itself/**
     * Puts a string on the screen at the specified position with the current colors and modifiers. If the string
     * contains newlines (\r and/or \n), the method will stop at the character before that; you have to manage
     * multi-line strings yourself!
     * <p>
     * This method has an additional functionality to the regular {@link TextGraphics#putString(int, int, String)};
     * if you embed ANSI CSI-style control sequences (like modifying text color or controlling SGR status), they will be
     * interpreted as the string is printed and mutates the {@link TextGraphics} object. In this version of Lanterna,
     * the following sequences are supported:
     * <ul>
     *     <li>Set foreground color</li>
     *     <li>Set background color</li>
     *     <li>Set/Clear bold style</li>
     *     <li>Set/Clear underline style</li>
     *     <li>Set/Clear blink style</li>
     *     <li>Set/Clear reverse style</li>
     *     <li>Clear all styles and colors (notice that this will return the state to what it was at the start of the method)</li>
     * </ul>
     * When the call is complete, the {@link TextGraphics} object will return to the color/style state it was in at the
     * start of the call.
     * @param column What column to put the string at
     * @param row What row to put the string at
     * @param string String to put on the screen
     * @return Itself
     */
    TextGraphics putCSIStyledString(int column, int row, String string);

    
Puts a string on the screen at the specified position with the current colors and modifiers. If the string
contains newlines (\r and/or \n), the method will stop at the character before that; you have to manage
multi-line strings yourself!
 This method has an additional functionality to the regular putString(int, int, String); if you embed ANSI CSI-style control sequences (like modifying text color or controlling SGR status), they will be interpreted as the string is printed and mutates the TextGraphics object. In this version of Lanterna, the following sequences are supported: 

    
Set foreground color
    
Set background color
    
Set/Clear bold style
    
Set/Clear underline style
    
Set/Clear blink style
    
Set/Clear reverse style
    
Clear all styles and colors (notice that this will return the state to what it was at the start of the method)
 When the call is complete, the TextGraphics object will return to the color/style state it was in at the start of the call. 
Params:
position – Position to put the string at
string – String to put on the screen
Returns:
Itself/**
     * Puts a string on the screen at the specified position with the current colors and modifiers. If the string
     * contains newlines (\r and/or \n), the method will stop at the character before that; you have to manage
     * multi-line strings yourself!
     * <p>
     * This method has an additional functionality to the regular {@link TextGraphics#putString(int, int, String)};
     * if you embed ANSI CSI-style control sequences (like modifying text color or controlling SGR status), they will be
     * interpreted as the string is printed and mutates the {@link TextGraphics} object. In this version of Lanterna,
     * the following sequences are supported:
     * <ul>
     *     <li>Set foreground color</li>
     *     <li>Set background color</li>
     *     <li>Set/Clear bold style</li>
     *     <li>Set/Clear underline style</li>
     *     <li>Set/Clear blink style</li>
     *     <li>Set/Clear reverse style</li>
     *     <li>Clear all styles and colors (notice that this will return the state to what it was at the start of the method)</li>
     * </ul>
     * When the call is complete, the {@link TextGraphics} object will return to the color/style state it was in at the
     * start of the call.
     * @param position Position to put the string at
     * @param string String to put on the screen
     * @return Itself
     */
    TextGraphics putCSIStyledString(TerminalPosition position, String string);

    
Returns the character at the specific position in the terminal. May return null if the TextGraphics implementation doesn't support it or doesn't know what the character is. 
Params:
position – Position to return the character for
Returns:
The text character at the specified position or null if not available/**
     * Returns the character at the specific position in the terminal. May return {@code null} if the TextGraphics
     * implementation doesn't support it or doesn't know what the character is.
     * @param position Position to return the character for
     * @return The text character at the specified position or {@code null} if not available
     */
    TextCharacter getCharacter(TerminalPosition position);

    
Returns the character at the specific position in the terminal. May return null if the TextGraphics implementation doesn't support it or doesn't know what the character is. 
Params:
column – Column to return the character for
row – Row to return the character for
Returns:
The text character at the specified position or null if not available/**
     * Returns the character at the specific position in the terminal. May return {@code null} if the TextGraphics
     * implementation doesn't support it or doesn't know what the character is.
     * @param column Column to return the character for
     * @param row Row to return the character for
     * @return The text character at the specified position or {@code null} if not available
     */
    TextCharacter getCharacter(int column, int row);
}