src/com/googlecode/lanterna/gui2/BasePane.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.gui2;
  20
  21 import com.googlecode.lanterna.TerminalPosition;
  22 import com.googlecode.lanterna.input.KeyStroke;
  23
  24 /**
  25  * BasePane is the base container in a Text GUI. A text gui may have several base panes, although they are
  26  * always independent. One common example of this is a multi-window system where each window is a base pane. Think of
  27  * the base pane as a root container, the ultimate parent of all components added to a GUI. When you use
  28  * {@code MultiWindowTextGUI}, the background space behind the windows is a {@code BasePane} too, just like each of the
  29  * windows. They are all drawn separately and composited together. Every {@code BasePane} has a single component that
  30  * is drawn over the entire area the {@code BasePane} is occupying, it's very likely you want to set this component to
  31  * be a container of some sort, probably a {@code Panel}, that can host multiple child components.
  32  *
  33  * @see Panel
  34  * @author Martin
  35  */
  36 public interface BasePane extends Composite {
  37
  38     /**
  39      * Returns the TextGUI this BasePane belongs to or {@code null} if none. One example of when this method returns
  40      * {@code null} is when calling it on a Window that hasn't been displayed yet.
  41      * @return The TextGUI this BasePane belongs to
  42      */
  43     TextGUI getTextGUI();
  44
  45     /**
  46      * Called by the GUI system (or something imitating the GUI system) to draw the root container. The TextGUIGraphics
  47      * object should be used to perform the drawing operations.
  48      * @param graphics TextGraphics object to draw with
  49      */
  50     void draw(TextGUIGraphics graphics);
  51
  52     /**
  53      * Checks if this root container (i.e. any of its child components) has signaled that what it's currently displaying
  54      * is out of date and needs re-drawing.
  55      * @return {@code true} if the container's content is invalid and needs redrawing, {@code false} otherwise
  56      */
  57     boolean isInvalid();
  58
  59     /**
  60      * Invalidates the whole root container (including all of its child components) which will cause them all to be
  61      * recalculated (for containers) and redrawn.
  62      */
  63     void invalidate();
  64
  65     /**
  66      * Called by the GUI system to delegate a keyboard input event. The root container will decide what to do with this
  67      * input, usually sending it to one of its sub-components, but if it isn't able to find any handler for this input
  68      * it should return {@code false} so that the GUI system can take further decisions on what to do with it.
  69      * @param key Keyboard input
  70      * @return {@code true} If the root container could handle the input, false otherwise
  71      */
  72     boolean handleInput(KeyStroke key);
  73
  74     /**
  75      * Returns the component that is the content of the BasePane. This is probably the root of a hierarchy of nested
  76      * Panels but it could also be a single component.
  77      * @return Component which is the content of this BasePane
  78      */
  79     @Override
  80     Component getComponent();
  81
  82     /**
  83      * Sets the top-level component inside this BasePane. If you want it to contain only one component, you can set it
  84      * directly, but for more complicated GUIs you probably want to create a hierarchy of panels and set the first one
  85      * here.
  86      * @param component Component which this BasePane is using as it's content
  87      */
  88     @Override
  89     void setComponent(Component component);
  90
  91     /**
  92      * Returns the component in the root container that currently has input focus. There can only be one component at a
  93      * time being in focus.
  94      * @return Interactable component that is currently in receiving input focus
  95      */
  96     Interactable getFocusedInteractable();
  97
  98     /**
  99      * Sets the component currently in focus within this root container, or sets no component in focus if {@code null}
 100      * is passed in.
 101      * @param interactable Interactable to focus, or {@code null} to clear focus
 102      */
 103     void setFocusedInteractable(Interactable interactable);
 104
 105     /**
 106      * Returns the position of where to put the terminal cursor according to this root container. This is typically
 107      * derived from which component has focus, or {@code null} if no component has focus or if the root container doesn't
 108      * want the cursor to be visible. Note that the coordinates are in local coordinate space, relative to the top-left
 109      * corner of the root container. You can use your TextGUI implementation to translate these to global coordinates.
 110      * @return Local position of where to place the cursor, or {@code null} if the cursor shouldn't be visible
 111      */
 112     TerminalPosition getCursorPosition();
 113
 114     /**
 115      * Returns a position in a root container's local coordinate space to global coordinates
 116      * @param localPosition The local position to translate
 117      * @return The local position translated to global coordinates
 118      */
 119     TerminalPosition toGlobal(TerminalPosition localPosition);
 120
 121     /**
 122      * Returns a position expressed in global coordinates, i.e. row and column offset from the top-left corner of the
 123      * terminal into a position relative to the top-left corner of the base pane. Calling
 124      * {@code fromGlobal(toGlobal(..))} should return the exact same position.
 125      * @param position Position expressed in global coordinates to translate to local coordinates of this BasePane
 126      * @return The global coordinates expressed as local coordinates
 127      */
 128     TerminalPosition fromGlobal(TerminalPosition position);
 129
 130     /**
 131      * If set to true, up/down array keys will not translate to next/previous if there are no more components
 132      * above/below.
 133      * @param strictFocusChange Will not allow relaxed navigation if set to {@code true}
 134      */
 135     void setStrictFocusChange(boolean strictFocusChange);
 136
 137     /**
 138      * If set to false, using the keyboard arrows keys will have the same effect as using the tab and reverse tab.
 139      * Lanterna will map arrow down and arrow right to tab, going to the next component, and array up and array left to
 140      * reverse tab, going to the previous component. If set to true, Lanterna will search for the next component
 141      * starting at the cursor position in the general direction of the arrow. By default this is enabled.
 142      * <p>
 143      * In Lanterna 2, direction based movements were not available.
 144      * @param enableDirectionBasedMovements Should direction based focus movements be enabled?
 145      */
 146     void setEnableDirectionBasedMovements(boolean enableDirectionBasedMovements);
 147 }