2 * This file is part of lanterna (http://code.google.com/p/lanterna/).
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.
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.
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/>.
17 * Copyright (C) 2010-2015 Martin
19 package com
.googlecode
.lanterna
.gui2
;
21 import com
.googlecode
.lanterna
.TerminalPosition
;
22 import com
.googlecode
.lanterna
.input
.KeyStroke
;
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.
36 public interface BasePane
extends Composite
{
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
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
50 void draw(TextGUIGraphics graphics
);
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
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.
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
72 boolean handleInput(KeyStroke key
);
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
80 Component
getComponent();
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
86 * @param component Component which this BasePane is using as it's content
89 void setComponent(Component component
);
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
96 Interactable
getFocusedInteractable();
99 * Sets the component currently in focus within this root container, or sets no component in focus if {@code null}
101 * @param interactable Interactable to focus, or {@code null} to clear focus
103 void setFocusedInteractable(Interactable interactable
);
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
112 TerminalPosition
getCursorPosition();
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
119 TerminalPosition
toGlobal(TerminalPosition localPosition
);
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
128 TerminalPosition
fromGlobal(TerminalPosition position
);
131 * If set to true, up/down array keys will not translate to next/previous if there are no more components
133 * @param strictFocusChange Will not allow relaxed navigation if set to {@code true}
135 void setStrictFocusChange(boolean strictFocusChange
);
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.
143 * In Lanterna 2, direction based movements were not available.
144 * @param enableDirectionBasedMovements Should direction based focus movements be enabled?
146 void setEnableDirectionBasedMovements(boolean enableDirectionBasedMovements
);