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
;
23 import com
.googlecode
.lanterna
.TerminalSize
;
25 import java
.util
.Collection
;
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.
34 public interface Window
extends BasePane
{
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.
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.
45 public static final Hint NO_DECORATIONS
= new Hint();
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.
51 public static final Hint NO_POST_RENDERING
= new Hint();
54 * With this hint, the window should never receive focus by the window manager
56 public static final Hint NO_FOCUS
= new Hint();
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.
62 public static final Hint CENTERED
= new Hint();
65 * Windows with this hint should not be positioned by the window manager, rather they should use whatever
66 * position is pre-set.
68 public static final Hint FIXED_POSITION
= new Hint();
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(..)}.
75 public static final Hint FIXED_SIZE
= new Hint();
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.
81 public static final Hint FIT_TERMINAL_WINDOW
= new Hint();
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
89 public static final Hint MODAL
= new Hint();
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.
95 public static final Hint FULL_SCREEN
= new Hint();
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.
102 public static final Hint EXPANDED
= new Hint();
109 WindowBasedTextGUI
getTextGUI();
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
117 void setTextGUI(WindowBasedTextGUI textGUI
);
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
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.
131 * @return Whether the window wants to be visible or not
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.
140 * @param visible whether the window should be visible or not
142 void setVisible(boolean visible
);
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
153 * Invalidates the whole window (including all of its child components) which will cause it to be recalculated
160 * Returns the size this window would like to be
161 * @return Desired size of this window
163 TerminalSize
getPreferredSize();
166 * Closes the window, which will remove it from the GUI
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
175 void setHints(Collection
<Hint
> hints
);
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
182 Set
<Hint
> getHints();
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
189 TerminalPosition
getPosition();
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
196 void setPosition(TerminalPosition topLeft
);
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
203 TerminalSize
getSize();
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
211 * @param size New size of the window
213 void setSize(TerminalSize size
);
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
220 TerminalSize
getDecoratedSize();
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
226 * @param decoratedSize Size of the window, including window decorations
228 void setDecoratedSize(TerminalSize decoratedSize
);
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
237 void setContentOffset(TerminalPosition offset
);
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
244 void waitUntilClosed();
246 ///////////////////////////////////////////////////////////////
247 //// Below here are methods from BasePane ////
248 //// We duplicate them here to make the JavaDoc more clear ////
249 ///////////////////////////////////////////////////////////////
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
256 void draw(TextGUIGraphics graphics
);
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
267 boolean handleInput(KeyStroke key
);
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
275 void setComponent(Component component
);
278 * Returns the component which is the top-level in the component hierarchy inside this window.
279 * @return Top-level component in the window
282 Component
getComponent();
285 * Returns the component in the window that currently has input focus. There can only be one component at a time
287 * @return Interactable component that is currently in receiving input focus
290 Interactable
getFocusedInteractable();
293 * Sets the component currently in focus within this window, or sets no component in focus if {@code null}
295 * @param interactable Interactable to focus, or {@code null} to clear focus
298 void setFocusedInteractable(Interactable interactable
);
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
308 TerminalPosition
getCursorPosition();
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
316 TerminalPosition
toGlobal(TerminalPosition localPosition
);
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
325 TerminalPosition
fromGlobal(TerminalPosition position
);