src/com/googlecode/lanterna/graphics/TextImage.java

   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.TerminalPosition;
  22 import com.googlecode.lanterna.TerminalSize;
  23 import com.googlecode.lanterna.TextCharacter;
  24
  25 /**
  26  * An 'image' build up of text characters with color and style information. These are completely in memory and not
  27  * visible anyway, but can be used when drawing with a TextGraphics objects.
  28  * @author martin
  29  */
  30 public interface TextImage extends Scrollable {
  31     /**
  32      * Returns the dimensions of this TextImage, in columns and rows
  33      * @return Size of this TextImage
  34      */
  35     TerminalSize getSize();
  36
  37     /**
  38      * Returns the character stored at a particular position in this image
  39      * @param position Coordinates of the character
  40      * @return TextCharacter stored at the specified position
  41      */
  42     TextCharacter getCharacterAt(TerminalPosition position);
  43
  44     /**
  45      * Returns the character stored at a particular position in this image
  46      * @param column Column coordinate of the character
  47      * @param row Row coordinate of the character
  48      * @return TextCharacter stored at the specified position
  49      */
  50     TextCharacter getCharacterAt(int column, int row);
  51
  52     /**
  53      * Sets the character at a specific position in the image to a particular TextCharacter. If the position is outside
  54      * of the image's size, this method does nothing.
  55      * @param position Coordinates of the character
  56      * @param character What TextCharacter to assign at the specified position
  57      */
  58     void setCharacterAt(TerminalPosition position, TextCharacter character);
  59
  60     /**
  61      * Sets the character at a specific position in the image to a particular TextCharacter. If the position is outside
  62      * of the image's size, this method does nothing.
  63      * @param column Column coordinate of the character
  64      * @param row Row coordinate of the character
  65      * @param character What TextCharacter to assign at the specified position
  66      */
  67     void setCharacterAt(int column, int row, TextCharacter character);
  68
  69     /**
  70      * Sets the text image content to one specified character (including color and style)
  71      * @param character The character to fill the image with
  72      */
  73     void setAll(TextCharacter character);
  74
  75     /**
  76      * Creates a TextGraphics object that targets this TextImage for all its drawing operations.
  77      * @return TextGraphics object for this TextImage
  78      */
  79     TextGraphics newTextGraphics();
  80
  81     /**
  82      * Returns a copy of this image resized to a new size and using a specified filler character if the new size is
  83      * larger than the old and we need to fill in empty areas. The copy will be independent from the one this method is
  84      * invoked on, so modifying one will not affect the other.
  85      * @param newSize Size of the new image
  86      * @param filler Filler character to use on the new areas when enlarging the image (is not used when shrinking)
  87      * @return Copy of this image, but resized
  88      */
  89     TextImage resize(TerminalSize newSize, TextCharacter filler);
  90
  91
  92     /**
  93      * Copies this TextImage's content to another TextImage. If the destination TextImage is larger than this
  94      * ScreenBuffer, the areas outside of the area that is written to will be untouched.
  95      * @param destination TextImage to copy to
  96      */
  97     void copyTo(TextImage destination);
  98
  99     /**
 100      * Copies this TextImage's content to another TextImage. If the destination TextImage is larger than this
 101      * TextImage, the areas outside of the area that is written to will be untouched.
 102      * @param destination TextImage to copy to
 103      * @param startRowIndex Which row in this image to copy from
 104      * @param rows How many rows to copy
 105      * @param startColumnIndex Which column in this image to copy from
 106      * @param columns How many columns to copy
 107      * @param destinationRowOffset Offset (in number of rows) in the target image where we want to first copied row to be
 108      * @param destinationColumnOffset Offset (in number of columns) in the target image where we want to first copied column to be
 109      */
 110     void copyTo(
 111             TextImage destination,
 112             int startRowIndex,
 113             int rows,
 114             int startColumnIndex,
 115             int columns,
 116             int destinationRowOffset,
 117             int destinationColumnOffset);
 118
 119     /**
 120      * Scroll a range of lines of this TextImage according to given distance.
 121      *
 122      * TextImage implementations of this method do <b>not</b> throw IOException.
 123      */
 124     @Override
 125     void scrollLines(int firstLine, int lastLine, int distance);
 126 }