/*
 * 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.gui2;

import com.googlecode.lanterna.TerminalPosition;
import com.googlecode.lanterna.graphics.Theme;
import com.googlecode.lanterna.input.KeyStroke;

BasePane is the base container in a Text GUI. A text gui may have several base panes, although they are always independent. One common example of this is a multi-window system where each window is a base pane. Think of the base pane as a root container, the ultimate parent of all components added to a GUI. When you use MultiWindowTextGUI, the background space behind the windows is a BasePane too, just like each of the windows. They are all drawn separately and composited together. Every BasePane has a single component that is drawn over the entire area the BasePane is occupying, it's very likely you want to set this component to be a container of some sort, probably a Panel, that can host multiple child components. 
Author:
Martin
See Also:
Panel/**
 * BasePane is the base container in a Text GUI. A text gui may have several base panes, although they are
 * always independent. One common example of this is a multi-window system where each window is a base pane. Think of
 * the base pane as a root container, the ultimate parent of all components added to a GUI. When you use
 * {@code MultiWindowTextGUI}, the background space behind the windows is a {@code BasePane} too, just like each of the
 * windows. They are all drawn separately and composited together. Every {@code BasePane} has a single component that
 * is drawn over the entire area the {@code BasePane} is occupying, it's very likely you want to set this component to
 * be a container of some sort, probably a {@code Panel}, that can host multiple child components.
 *
 * @see Panel
 * @author Martin
 */
public interface BasePane extends Composite {
    
    
Returns the TextGUI this BasePane belongs to or null if none. One example of when this method returns null is when calling it on a Window that hasn't been displayed yet. 
Returns:
The TextGUI this BasePane belongs to/**
     * Returns the TextGUI this BasePane belongs to or {@code null} if none. One example of when this method returns
     * {@code null} is when calling it on a Window that hasn't been displayed yet.
     * @return The TextGUI this BasePane belongs to
     */
    TextGUI getTextGUI();
    
    
Called by the GUI system (or something imitating the GUI system) to draw the root container. The TextGUIGraphics
object should be used to perform the drawing operations.
Params:
graphics – TextGraphics object to draw with/**
     * Called by the GUI system (or something imitating the GUI system) to draw the root container. The TextGUIGraphics
     * object should be used to perform the drawing operations.
     * @param graphics TextGraphics object to draw with
     */
    void draw(TextGUIGraphics graphics);

    
Checks if this root container (i.e. any of its child components) has signaled that what it's currently displaying
is out of date and needs re-drawing.
Returns:
true if the container's content is invalid and needs redrawing, false otherwise/**
     * Checks if this root container (i.e. any of its child components) has signaled that what it's currently displaying
     * is out of date and needs re-drawing.
     * @return {@code true} if the container's content is invalid and needs redrawing, {@code false} otherwise
     */
    boolean isInvalid();

    
Invalidates the whole root container (including all of its child components) which will cause them all to be
recalculated (for containers) and redrawn.
/**
     * Invalidates the whole root container (including all of its child components) which will cause them all to be
     * recalculated (for containers) and redrawn.
     */
    void invalidate();

    
Called by the GUI system to delegate a keyboard input event. The root container will decide what to do with this input, usually sending it to one of its sub-components, but if it isn't able to find any handler for this input it should return false so that the GUI system can take further decisions on what to do with it. 
Params:
key – Keyboard input
Returns:
true If the root container could handle the input, false otherwise/**
     * Called by the GUI system to delegate a keyboard input event. The root container will decide what to do with this
     * input, usually sending it to one of its sub-components, but if it isn't able to find any handler for this input
     * it should return {@code false} so that the GUI system can take further decisions on what to do with it.
     * @param key Keyboard input
     * @return {@code true} If the root container could handle the input, false otherwise
     */
    boolean handleInput(KeyStroke key);

    
Returns the component that is the content of the BasePane. This is probably the root of a hierarchy of nested
Panels but it could also be a single component.
Returns:
Component which is the content of this BasePane/**
     * Returns the component that is the content of the BasePane. This is probably the root of a hierarchy of nested
     * Panels but it could also be a single component.
     * @return Component which is the content of this BasePane
     */
    @Override
    Component getComponent();

    
Sets the top-level component inside this BasePane. If you want it to contain only one component, you can set it
directly, but for more complicated GUIs you probably want to create a hierarchy of panels and set the first one
here.
Params:
component – Component which this BasePane is using as it's content/**
     * Sets the top-level component inside this BasePane. If you want it to contain only one component, you can set it
     * directly, but for more complicated GUIs you probably want to create a hierarchy of panels and set the first one
     * here.
     * @param component Component which this BasePane is using as it's content
     */
    @Override
    void setComponent(Component component);

    
Returns the component in the root container that currently has input focus. There can only be one component at a
time being in focus.
Returns:
Interactable component that is currently in receiving input focus/**
     * Returns the component in the root container that currently has input focus. There can only be one component at a
     * time being in focus.
     * @return Interactable component that is currently in receiving input focus
     */
    Interactable getFocusedInteractable();

    
Sets the component currently in focus within this root container, or sets no component in focus if null is passed in. 
Params:
interactable – Interactable to focus, or null to clear focus/**
     * Sets the component currently in focus within this root container, or sets no component in focus if {@code null}
     * is passed in.
     * @param interactable Interactable to focus, or {@code null} to clear focus
     */
    void setFocusedInteractable(Interactable interactable);

    
Returns the position of where to put the terminal cursor according to this root container. This is typically derived from which component has focus, or null if no component has focus or if the root container doesn't want the cursor to be visible. Note that the coordinates are in local coordinate space, relative to the top-left corner of the root container. You can use your TextGUI implementation to translate these to global coordinates. 
Returns:
Local position of where to place the cursor, or null if the cursor shouldn't be visible/**
     * Returns the position of where to put the terminal cursor according to this root container. This is typically
     * derived from which component has focus, or {@code null} if no component has focus or if the root container doesn't
     * want the cursor to be visible. Note that the coordinates are in local coordinate space, relative to the top-left
     * corner of the root container. You can use your TextGUI implementation to translate these to global coordinates.
     * @return Local position of where to place the cursor, or {@code null} if the cursor shouldn't be visible
     */
    TerminalPosition getCursorPosition();

    
Returns a position in a root container's local coordinate space to global coordinates
Params:
localPosition – The local position to translate
Returns:
The local position translated to global coordinates/**
     * Returns a position in a root container's local coordinate space to global coordinates
     * @param localPosition The local position to translate
     * @return The local position translated to global coordinates
     */
    TerminalPosition toGlobal(TerminalPosition localPosition);

    
Returns a position expressed in global coordinates, i.e. row and column offset from the top-left corner of the terminal into a position relative to the top-left corner of the base pane. Calling fromGlobal(toGlobal(..)) should return the exact same position. 
Params:
position – Position expressed in global coordinates to translate to local coordinates of this BasePane
Returns:
The global coordinates expressed as local coordinates/**
     * Returns a position expressed in global coordinates, i.e. row and column offset from the top-left corner of the
     * terminal into a position relative to the top-left corner of the base pane. Calling
     * {@code fromGlobal(toGlobal(..))} should return the exact same position.
     * @param position Position expressed in global coordinates to translate to local coordinates of this BasePane
     * @return The global coordinates expressed as local coordinates
     */
    TerminalPosition fromGlobal(TerminalPosition position);

    
If set to true, up/down array keys will not translate to next/previous if there are no more components
above/below.
Params:
strictFocusChange – Will not allow relaxed navigation if set to true/**
     * If set to true, up/down array keys will not translate to next/previous if there are no more components
     * above/below.
     * @param strictFocusChange Will not allow relaxed navigation if set to {@code true}
     */
    void setStrictFocusChange(boolean strictFocusChange);

    
If set to false, using the keyboard arrows keys will have the same effect as using the tab and reverse tab.
Lanterna will map arrow down and arrow right to tab, going to the next component, and array up and array left to
reverse tab, going to the previous component. If set to true, Lanterna will search for the next component
starting at the cursor position in the general direction of the arrow. By default this is enabled.

In Lanterna 2, direction based movements were not available.
Params:
enableDirectionBasedMovements – Should direction based focus movements be enabled?/**
     * If set to false, using the keyboard arrows keys will have the same effect as using the tab and reverse tab.
     * Lanterna will map arrow down and arrow right to tab, going to the next component, and array up and array left to
     * reverse tab, going to the previous component. If set to true, Lanterna will search for the next component
     * starting at the cursor position in the general direction of the arrow. By default this is enabled.
     * <p>
     * In Lanterna 2, direction based movements were not available.
     * @param enableDirectionBasedMovements Should direction based focus movements be enabled?
     */
    void setEnableDirectionBasedMovements(boolean enableDirectionBasedMovements);

    
Returns the text GUI Theme associated with this base pane/window. This is either coming from the TextGUI this object is associated with, the theme set as the override through setTheme(Theme) or null if this base pane/window isn't added to any TextGUI and doesn't have any override. 
Returns:
The Theme this base pane/window is expected to use when drawing the contents/**
     * Returns the text GUI {@link Theme} associated with this base pane/window. This is either coming from the
     * {@link TextGUI} this object is associated with, the theme set as the override through {@link #setTheme(Theme)}
     * or {@code null} if this base pane/window isn't added to any {@link TextGUI} and doesn't have any override.
     * @return The {@link Theme} this base pane/window is expected to use when drawing the contents
     */
    Theme getTheme();

    
Sets the override Theme to use for this base pane/window, rather than the default Theme associated with the TextGUI it is attached to. If called with null, it will clear the override and use the default value instead. 
Params:
theme – Theme to assign to this base pane/window, or null to reset/**
     * Sets the override {@link Theme} to use for this base pane/window, rather than the default {@link Theme}
     * associated with the {@link TextGUI} it is attached to. If called with {@code null}, it will clear the override
     * and use the default value instead.
     * @param theme {@link Theme} to assign to this base pane/window, or {@code null} to reset
     */
    void setTheme(Theme theme);
}