Commit | Line | Data |
---|---|---|
a3b510ab NR |
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 | } |