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 | import com.googlecode.lanterna.TerminalSize; | |
24 | ||
25 | import java.util.Collection; | |
26 | import java.util.Set; | |
27 | ||
28 | /** | |
29 | * Window is a base unit in the TextGUI system, it represents a collection of components grouped together, usually | |
30 | * surrounded by a border and a title. Modern computer system GUIs are normally based around the metaphor of windows, | |
31 | * so I don't think you should have any problems understanding what this means. | |
32 | * @author Martin | |
33 | */ | |
34 | public interface Window extends BasePane { | |
35 | /** | |
36 | * Window hints are meta-data stored along with the window that can be used to give the GUI system some ideas of how | |
37 | * this window wants to be treated. There are no guarantees that the hints will be honoured though. You can declare | |
38 | * your own window hints by sub-classing this class. | |
39 | */ | |
40 | class Hint { | |
41 | /** | |
42 | * With this hint, the TextGUI system should not draw any decorations around the window. Decorated size will be | |
43 | * the same as the window size. | |
44 | */ | |
45 | public static final Hint NO_DECORATIONS = new Hint(); | |
46 | ||
47 | /** | |
48 | * With this hint, the TextGUI system should skip running any post renderers for the window. By default this | |
49 | * means the window won't have any shadow. | |
50 | */ | |
51 | public static final Hint NO_POST_RENDERING = new Hint(); | |
52 | ||
53 | /** | |
54 | * With this hint, the window should never receive focus by the window manager | |
55 | */ | |
56 | public static final Hint NO_FOCUS = new Hint(); | |
57 | ||
58 | /** | |
59 | * With this hint, the window wants to be at the center of the terminal instead of using the cascading layout | |
60 | * which is the standard. | |
61 | */ | |
62 | public static final Hint CENTERED = new Hint(); | |
63 | ||
64 | /** | |
65 | * Windows with this hint should not be positioned by the window manager, rather they should use whatever | |
66 | * position is pre-set. | |
67 | */ | |
68 | public static final Hint FIXED_POSITION = new Hint(); | |
69 | ||
70 | /** | |
71 | * Windows with this hint should not be automatically sized by the window manager (using | |
72 | * {@code getPreferredSize()}), rather should rely on the code manually setting the size of the window using | |
73 | * {@code setSize(..)}. | |
74 | */ | |
75 | public static final Hint FIXED_SIZE = new Hint(); | |
76 | ||
77 | /** | |
78 | * With this hint, don't let the window grow larger than the terminal screen, rather set components to a smaller | |
79 | * size than they prefer. | |
80 | */ | |
81 | public static final Hint FIT_TERMINAL_WINDOW = new Hint(); | |
82 | ||
83 | /** | |
84 | * This hint tells the window manager that this window should have exclusive access to the keyboard input until | |
85 | * it is closed. For window managers that allows the user to switch between open windows, putting a window on | |
86 | * the screen with this hint should make the window manager temporarily disable that function until the window | |
87 | * is closed. | |
88 | */ | |
89 | public static final Hint MODAL = new Hint(); | |
90 | ||
91 | /** | |
92 | * A window with this hint would like to be placed covering the entire screen. Use this in combination with | |
93 | * NO_DECORATIONS if you want the content area to take up the entire terminal. | |
94 | */ | |
95 | public static final Hint FULL_SCREEN = new Hint(); | |
96 | ||
97 | /** | |
98 | * This window hint tells the window manager that the window should be taking up almost the entire screen, | |
99 | * leaving only a small space around it. This is different from {@code FULL_SCREEN} which takes all available | |
100 | * space and completely hide the background and any other window behind it. | |
101 | */ | |
102 | public static final Hint EXPANDED = new Hint(); | |
103 | ||
104 | protected Hint() { | |
105 | } | |
106 | } | |
107 | ||
108 | @Override | |
109 | WindowBasedTextGUI getTextGUI(); | |
110 | ||
111 | /** | |
112 | * DON'T CALL THIS METHOD YOURSELF, it is called automatically by the TextGUI system when you add a window. If you | |
113 | * call it with the intention of adding the window to the specified TextGUI, you need to read the documentation | |
114 | * on how to use windows. | |
115 | * @param textGUI TextGUI this window belongs to from now on | |
116 | */ | |
117 | void setTextGUI(WindowBasedTextGUI textGUI); | |
118 | ||
119 | /** | |
120 | * This method returns the title of the window, which is normally drawn at the top-left corder of the window | |
121 | * decoration, but depending on the {@code WindowDecorationRenderer} used by the {@code TextGUI} | |
122 | * @return title of the window | |
123 | */ | |
124 | String getTitle(); | |
125 | ||
126 | /** | |
127 | * This values is optionally used by the window manager to decide if the windows should be drawn or not. In an | |
128 | * invisible state, the window is still considered active in the TextGUI but just not drawn and not receiving any | |
129 | * input events. Please note that window managers may choose not to implement this. | |
130 | * | |
131 | * @return Whether the window wants to be visible or not | |
132 | */ | |
133 | boolean isVisible(); | |
134 | ||
135 | /** | |
136 | * This values is optionally used by the window manager to decide if the windows should be drawn or not. In an | |
137 | * invisible state, the window is still considered active in the TextGUI but just not drawn and not receiving any | |
138 | * input events. Please note that window managers may choose not to implement this. | |
139 | * | |
140 | * @param visible whether the window should be visible or not | |
141 | */ | |
142 | void setVisible(boolean visible); | |
143 | ||
144 | /** | |
145 | * This method is used to determine if the window requires re-drawing. The most common cause for this is the some | |
146 | * of its components has changed and we need a re-draw to make these changes visible. | |
147 | * @return {@code true} if the window would like to be re-drawn, {@code false} if the window doesn't need | |
148 | */ | |
149 | @Override | |
150 | boolean isInvalid(); | |
151 | ||
152 | /** | |
153 | * Invalidates the whole window (including all of its child components) which will cause it to be recalculated | |
154 | * and redrawn. | |
155 | */ | |
156 | @Override | |
157 | void invalidate(); | |
158 | ||
159 | /** | |
160 | * Returns the size this window would like to be | |
161 | * @return Desired size of this window | |
162 | */ | |
163 | TerminalSize getPreferredSize(); | |
164 | ||
165 | /** | |
166 | * Closes the window, which will remove it from the GUI | |
167 | */ | |
168 | void close(); | |
169 | ||
170 | /** | |
171 | * Updates the set of active hints for this window. Please note that it's up to the window manager if these hints | |
172 | * will be honored or not. | |
173 | * @param hints Set of hints to be active for this window | |
174 | */ | |
175 | void setHints(Collection<Hint> hints); | |
176 | ||
177 | /** | |
178 | * Returns a set of window hints that can be used by the text gui system, the window manager or any other part that | |
179 | * is interacting with windows. | |
180 | * @return Set of hints defined for this window | |
181 | */ | |
182 | Set<Hint> getHints(); | |
183 | ||
184 | /** | |
185 | * Returns the position of the window, as last specified by the window manager. This position does not include | |
186 | * window decorations but is the top-left position of the first usable space of the window. | |
187 | * @return Position, relative to the top-left corner of the terminal, of the top-left corner of the window | |
188 | */ | |
189 | TerminalPosition getPosition(); | |
190 | ||
191 | /** | |
192 | * This method is called by the GUI system to update the window on where the window manager placed it. Calling this | |
193 | * yourself will have no effect other than making the {@code getPosition()} call incorrect until the next redraw. | |
194 | * @param topLeft Global coordinates of the top-left corner of the window | |
195 | */ | |
196 | void setPosition(TerminalPosition topLeft); | |
197 | ||
198 | /** | |
199 | * Returns the last known size of the window. This is in general derived from the last drawing operation, how large | |
200 | * area the window was allowed to draw on. This size does not include window decorations. | |
201 | * @return Size of the window | |
202 | */ | |
203 | TerminalSize getSize(); | |
204 | ||
205 | /** | |
206 | * This method is called by the GUI system to update the window on how large it is, excluding window decorations. | |
207 | * Calling this yourself will generally make no difference in the size of the window, since it will be reset on the | |
208 | * next redraw based on how large area the TextGraphics given is covering. However, if you add the FIXED_SIZE | |
209 | * window hint, the auto-size calculation will be turned off and you can use this method to set how large you want | |
210 | * the window to be. | |
211 | * @param size New size of the window | |
212 | */ | |
213 | void setSize(TerminalSize size); | |
214 | ||
215 | /** | |
216 | * Returns the last known size of the window including window decorations put on by the window manager. The value | |
217 | * returned here is passed in during drawing by the TextGUI through {@code setDecoratedSize(..)}. | |
218 | * @return Size of the window, including window decorations | |
219 | */ | |
220 | TerminalSize getDecoratedSize(); | |
221 | ||
222 | /** | |
223 | * This method is called by the GUI system to update the window on how large it is, counting window decorations too. | |
224 | * Calling this yourself will have no effect other than making the {@code getDecoratedSize()} call incorrect until | |
225 | * the next redraw. | |
226 | * @param decoratedSize Size of the window, including window decorations | |
227 | */ | |
228 | void setDecoratedSize(TerminalSize decoratedSize); | |
229 | ||
230 | /** | |
231 | * This method is called by the GUI system to update the window on, as of the last drawing operation, the distance | |
232 | * from the top-left position of the window including decorations to the top-left position of the actual content | |
233 | * area. If this window has no decorations, it will be always 0x0. Do not call this method yourself. | |
234 | * @param offset Offset from the top-left corner of the window (including decorations) to the top-left corner of | |
235 | * the content area. | |
236 | */ | |
237 | void setContentOffset(TerminalPosition offset); | |
238 | ||
239 | /** | |
240 | * Waits for the window to close. Please note that this can cause deadlocks if care is not taken. Also, this method | |
241 | * will swallow any interrupts, if you need a wait method that throws InterruptedException, you'll have to implement | |
242 | * this yourself. | |
243 | */ | |
244 | void waitUntilClosed(); | |
245 | ||
246 | /////////////////////////////////////////////////////////////// | |
247 | //// Below here are methods from BasePane //// | |
248 | //// We duplicate them here to make the JavaDoc more clear //// | |
249 | /////////////////////////////////////////////////////////////// | |
250 | /** | |
251 | * Called by the GUI system (or something imitating the GUI system) to draw the window. The TextGUIGraphics object | |
252 | * should be used to perform the drawing operations. | |
253 | * @param graphics TextGraphics object to draw with | |
254 | */ | |
255 | @Override | |
256 | void draw(TextGUIGraphics graphics); | |
257 | ||
258 | /** | |
259 | * Called by the GUI system's window manager when it has decided that this window should receive the keyboard input. | |
260 | * The window will decide what to do with this input, usually sending it to one of its sub-components, but if it | |
261 | * isn't able to find any handler for this input it should return {@code false} so that the window manager can take | |
262 | * further decisions on what to do with it. | |
263 | * @param key Keyboard input | |
264 | * @return {@code true} If the window could handle the input, false otherwise | |
265 | */ | |
266 | @Override | |
267 | boolean handleInput(KeyStroke key); | |
268 | ||
269 | /** | |
270 | * Sets the top-level component in the window, this will be the only component unless it's a container of some kind | |
271 | * that you add child-components to. | |
272 | * @param component Component to use as the top-level object in the Window | |
273 | */ | |
274 | @Override | |
275 | void setComponent(Component component); | |
276 | ||
277 | /** | |
278 | * Returns the component which is the top-level in the component hierarchy inside this window. | |
279 | * @return Top-level component in the window | |
280 | */ | |
281 | @Override | |
282 | Component getComponent(); | |
283 | ||
284 | /** | |
285 | * Returns the component in the window that currently has input focus. There can only be one component at a time | |
286 | * being in focus. | |
287 | * @return Interactable component that is currently in receiving input focus | |
288 | */ | |
289 | @Override | |
290 | Interactable getFocusedInteractable(); | |
291 | ||
292 | /** | |
293 | * Sets the component currently in focus within this window, or sets no component in focus if {@code null} | |
294 | * is passed in. | |
295 | * @param interactable Interactable to focus, or {@code null} to clear focus | |
296 | */ | |
297 | @Override | |
298 | void setFocusedInteractable(Interactable interactable); | |
299 | ||
300 | /** | |
301 | * Returns the position of where to put the terminal cursor according to this window. This is typically | |
302 | * derived from which component has focus, or {@code null} if no component has focus or if the window doesn't | |
303 | * want the cursor to be visible. Note that the coordinates are in local coordinate space, relative to the top-left | |
304 | * corner of the window. You can use your TextGUI implementation to translate these to global coordinates. | |
305 | * @return Local position of where to place the cursor, or {@code null} if the cursor shouldn't be visible | |
306 | */ | |
307 | @Override | |
308 | TerminalPosition getCursorPosition(); | |
309 | ||
310 | /** | |
311 | * Returns a position in the window's local coordinate space to global coordinates | |
312 | * @param localPosition The local position to translate | |
313 | * @return The local position translated to global coordinates | |
314 | */ | |
315 | @Override | |
316 | TerminalPosition toGlobal(TerminalPosition localPosition); | |
317 | ||
318 | /** | |
319 | * Returns a position expressed in global coordinates, i.e. row and column offset from the top-left corner of the | |
320 | * terminal into a position relative to the top-left corner of the window. Calling | |
321 | * {@code fromGlobal(toGlobal(..))} should return the exact same position. | |
322 | * @param position Position expressed in global coordinates to translate to local coordinates of this Window | |
323 | * @return The global coordinates expressed as local coordinates | |
324 | */ | |
325 | TerminalPosition fromGlobal(TerminalPosition position); | |
326 | } |