| 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 | } |