/*
 * This file is part of lanterna (https://github.com/mabe02/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.terminal.virtual;

import com.googlecode.lanterna.TerminalPosition;
import com.googlecode.lanterna.TerminalSize;
import com.googlecode.lanterna.TextCharacter;
import com.googlecode.lanterna.input.KeyStroke;
import com.googlecode.lanterna.terminal.IOSafeTerminal;

A virtual terminal is a kind of terminal emulator implemented inside of Lanterna that exposes the Terminal interface and maintains its state completely internally. The VirtualTerminal interface extends this interface and allows you to query and modify its internals in a way you can not do with a regular terminal. The AWT and Swing terminal implementations in Lanterna uses the DefaultVirtualTerminal class internally for keeping its state and doing most of the terminal operations. /**
 * A virtual terminal is a kind of terminal emulator implemented inside of Lanterna that exposes the Terminal interface
 * and maintains its state completely internally. The {@link VirtualTerminal} interface extends this interface and
 * allows you to query and modify its internals in a way you can not do with a regular terminal. The AWT and Swing
 * terminal implementations in Lanterna uses the {@link DefaultVirtualTerminal} class internally for keeping its state
 * and doing most of the terminal operations.
 */
public interface VirtualTerminal extends IOSafeTerminal {
    
Changes the "visible size" of the virtual terminal. This is the area at the bottom of the text buffer that is
considered the workable area since the cursor is restricted to this space. If you call this method with a size
that is different from the current size of the virtual terminal, the resize event will be fired on all listeners.
Params:
newSize – New size of the virtual terminal/**
     * Changes the "visible size" of the virtual terminal. This is the area at the bottom of the text buffer that is
     * considered the workable area since the cursor is restricted to this space. If you call this method with a size
     * that is different from the current size of the virtual terminal, the resize event will be fired on all listeners.
     * @param newSize New size of the virtual terminal
     */
    void setTerminalSize(TerminalSize newSize);

    
Adds a listener to receive notifications when certain events happens on the virtual terminal. Notice that this is not the same as the list of TerminalResizeListener, but as the VirtualTerminalListener also allows you to listen on size changes, it can be used for the same purpose. 
Params:
listener – Listener to receive events from this virtual terminal/**
     * Adds a listener to receive notifications when certain events happens on the virtual terminal. Notice that this is
     * not the same as the list of {@link com.googlecode.lanterna.terminal.TerminalResizeListener}, but as the
     * {@link VirtualTerminalListener} also allows you to listen on size changes, it can be used for the same purpose.
     * @param listener Listener to receive events from this virtual terminal
     */
    void addVirtualTerminalListener(VirtualTerminalListener listener);

    
Removes a listener from this virtual terminal so it will no longer receive events. Notice that this is not the same as the list of TerminalResizeListener. 
Params:
listener – Listener to remove from this virtual terminal/**
     * Removes a listener from this virtual terminal so it will no longer receive events. Notice that this is not the
     * same as the list of {@link com.googlecode.lanterna.terminal.TerminalResizeListener}.
     * @param listener Listener to remove from this virtual terminal
     */
    void removeVirtualTerminalListener(VirtualTerminalListener listener);

    
Sets the number of rows to allow in the non-private buffer above the viewport. The total size of the text buffer will be backlogSize + terminalSize.getRows(). If set to 0, there is no scrollback. Please note that private mode is unaffected by this and will always have no backlog. 
Params:
backlogSize – Number of rows of backlog/**
     * Sets the number of rows to allow in the non-private buffer above the viewport. The total size of the text buffer
     * will be {@code backlogSize + terminalSize.getRows()}. If set to 0, there is no scrollback. Please note that
     * private mode is unaffected by this and will always have no backlog.
     * @param backlogSize Number of rows of backlog
     */
    void setBacklogSize(int backlogSize);

    
Checks if the terminal cursor is visible or not
Returns:
true if the terminal cursor is visible, false otherwise/**
     * Checks if the terminal cursor is visible or not
     * @return {@code true} if the terminal cursor is visible, {@code false} otherwise
     */
    boolean isCursorVisible();

    
Adds a KeyStroke to the input queue of this virtual terminal. This even will be read the next time either IOSafeTerminal.pollInput() or IOSafeTerminal.readInput() is called, assuming there are no other events before it in the queue. 
Params:
keyStroke – KeyStroke to add to the input queue of this virtual terminal/**
     * Adds a {@link KeyStroke} to the input queue of this virtual terminal. This even will be read the next time either
     * {@link #pollInput()} or {@link #readInput()} is called, assuming there are no other events before it in the queue.
     * @param keyStroke {@link KeyStroke} to add to the input queue of this virtual terminal
     */
    void addInput(KeyStroke keyStroke);

    
Returns the position of the terminal cursor where the row index is counted from the top of the text buffer, including all backlog. This means, if there is 500 lines of backlog but the cursor position is set to 0x0, this method will return 0x500. If you want to get the cursor's position in the viewport, please use IOSafeTerminal.getCursorPosition() instead. 
Returns:
Cursor position as an offset from the top-left position of the text buffer including any backlog/**
     * Returns the position of the terminal cursor where the row index is counted from the top of the text buffer,
     * including all backlog. This means, if there is 500 lines of backlog but the cursor position is set to 0x0, this
     * method will return 0x500. If you want to get the cursor's position in the viewport, please use
     * {@link #getCursorPosition()} instead.
     * @return Cursor position as an offset from the top-left position of the text buffer including any backlog
     */
    TerminalPosition getCursorBufferPosition();

    
Returns a character from this virtual terminal, relative to the top-left position of the text buffer including any backlog. If you want to get a character from the bottom viewport, please use getCharacter(TerminalPosition) instead. 
Params:
position – Position to get the character from
Returns:
Text character at the specific position in the text buffer/**
     * Returns a character from this virtual terminal, relative to the top-left position of the text buffer including
     * any backlog. If you want to get a character from the bottom viewport, please use
     * {@link #getCharacter(TerminalPosition)} instead.
     *
     * @param position Position to get the character from
     * @return Text character at the specific position in the text buffer
     */
    TextCharacter getBufferCharacter(TerminalPosition position);


    
Returns a character from this virtual terminal, relative to the top-left position of the text buffer including any backlog. If you want to get a character from the bottom viewport, please use getCharacter(int, int) instead. 
Params:
column – Column to get the character from
row – Row, counting from the first line in the backlog, to get the character from
Returns:
Text character at the specific position in the text buffer/**
     * Returns a character from this virtual terminal, relative to the top-left position of the text buffer including
     * any backlog. If you want to get a character from the bottom viewport, please use
     * {@link #getCharacter(int, int)} instead.
     *
     * @param column Column to get the character from
     * @param row Row, counting from the first line in the backlog, to get the character from
     * @return Text character at the specific position in the text buffer
     */
    TextCharacter getBufferCharacter(int column, int row);

    
Returns a character from the viewport at the specified coordinates. This method cannot access the backlog, if you want to fetch a character potentially from the backlog, please use getBufferCharacter(TerminalPosition) instead. 
Params:
position – Position of the character to return
Returns:
Text character at the specific position in the viewport/**
     * Returns a character from the viewport at the specified coordinates. This method cannot access the backlog, if you
     * want to fetch a character potentially from the backlog, please use {@link #getBufferCharacter(TerminalPosition)}
     * instead.
     * @param position Position of the character to return
     * @return Text character at the specific position in the viewport
     */
    TextCharacter getCharacter(TerminalPosition position);

    
Returns a character from the viewport at the specified coordinates. This method cannot access the backlog, if you want to fetch a character potentially from the backlog, please use getBufferCharacter(int, int) instead. 
Params:
column – Column in the viewport to get the character from
row – Row in the viewport to get the character form
Returns:
Text character at the specific position in the viewport/**
     * Returns a character from the viewport at the specified coordinates. This method cannot access the backlog, if you
     * want to fetch a character potentially from the backlog, please use {@link #getBufferCharacter(int,int)}
     * instead.
     * @param column Column in the viewport to get the character from
     * @param row Row in the viewport to get the character form
     * @return Text character at the specific position in the viewport
     */
    TextCharacter getCharacter(int column, int row);

    
Returns the number of lines in the entire text buffer, including any backlog
Returns:
Number of lines in the buffer/**
     * Returns the number of lines in the entire text buffer, including any backlog
     * @return Number of lines in the buffer
     */
    int getBufferLineCount();

    
Iterates over a range of lines in the text buffer
Params:
startRow – Index of the first row of the iteration, counting 0 as the first row in the backlog
endRow – Index of the last row of the iteration (inclusive), counting 0 as the first row in the backlog
bufferWalker – Callback to invoke on each row in the iteration/**
     * Iterates over a range of lines in the text buffer
     * @param startRow Index of the first row of the iteration, counting 0 as the first row in the backlog
     * @param endRow Index of the last row of the iteration (inclusive), counting 0 as the first row in the backlog
     * @param bufferWalker Callback to invoke on each row in the iteration
     */
    void forEachLine(int startRow, int endRow, BufferWalker bufferWalker);

    
Interface used by BufferWalker to repressent a line in the text buffer when iterating over a range of lines /**
     * Interface used by {@link BufferWalker} to repressent a line in the text buffer when iterating over a range of
     * lines
     */
    interface BufferLine {
        
Returns a text character from this line in the specific column
Params:
column – Column to return the text character from
Returns:
Text character in the column of this line/**
         * Returns a text character from this line in the specific column
         * @param column Column to return the text character from
         * @return Text character in the column of this line
         */
        TextCharacter getCharacterAt(int column);
    }

    
Callback interface that is used by VirtualTerminal.forEachLine(int, int, BufferWalker) as a way to iterate over a range of lines in the text buffer /**
     * Callback interface that is used by {@link #forEachLine(int, int, BufferWalker)} as a way to iterate over a range
     * of lines in the text buffer
     */
    interface BufferWalker {
        
Invoked separately on each line inside the specified range when calling VirtualTerminal.forEachLine(int, int, BufferWalker) 
Params:
rowNumber – The row number of this invocation, where 0 means the first line of the backlog
bufferLine – Object the repressents the line and its content on this row/**
         * Invoked separately on each line inside the specified range when calling
         * {@link #forEachLine(int, int, BufferWalker)}
         * @param rowNumber The row number of this invocation, where 0 means the first line of the backlog
         * @param bufferLine Object the repressents the line and its content on this row
         */
        void onLine(int rowNumber, BufferLine bufferLine);
    }
}