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.graphics.Theme; | |
22 | import com.googlecode.lanterna.input.KeyStroke; | |
23 | ||
24 | import java.io.IOException; | |
25 | ||
26 | /** | |
27 | * This is the base interface for advanced text GUIs supported in Lanterna. You may want to use this in combination with | |
28 | * a TextGUIThread, that can be created/retrieved by using {@code getGUIThread()}. | |
29 | * @author Martin | |
30 | */ | |
31 | public interface TextGUI { | |
32 | /** | |
33 | * Sets the global theme to be used by this TextGUI. This value will be set on every TextGUIGraphics object created | |
34 | * for drawing the GUI, but individual components can override this if they want. If you don't call this method | |
35 | * you should assume that a default theme is assigned by the library. | |
36 | * @param theme Theme to use as the default theme for this TextGUI | |
37 | */ | |
38 | void setTheme(Theme theme); | |
39 | ||
40 | /** | |
41 | * Drains the input queue and passes the key strokes to the GUI system for processing. For window-based system, it | |
42 | * will send each key stroke to the active window for processing. If the input read gives an EOF, it will throw | |
43 | * EOFException and this is normally the signal to shut down the GUI (any command coming in before the EOF will be | |
44 | * processed as usual before this). | |
45 | * @return {@code true} if at least one key stroke was read and processed, {@code false} if there was nothing on the | |
46 | * input queue (only for non-blocking IO) | |
47 | * @throws java.io.IOException In case there was an underlying I/O error | |
48 | * @throws java.io.EOFException In the input stream received an EOF marker | |
49 | */ | |
50 | boolean processInput() throws IOException; | |
51 | ||
52 | /** | |
53 | * Updates the screen, to make any changes visible to the user. | |
54 | * @throws java.io.IOException In case there was an underlying I/O error | |
55 | */ | |
56 | void updateScreen() throws IOException; | |
57 | ||
58 | /** | |
59 | * This method can be used to determine if any component has requested a redraw. If this method returns | |
60 | * {@code true}, you may want to call {@code updateScreen()}. | |
61 | * @return {@code true} if this TextGUI has a change and is waiting for someone to call {@code updateScreen()} | |
62 | */ | |
63 | boolean isPendingUpdate(); | |
64 | ||
65 | /** | |
66 | * The first time this method is called, it will create a new TextGUIThread object that you can use to automatically | |
67 | * manage this TextGUI instead of manually calling {@code processInput()} and {@code updateScreen()}. After the | |
68 | * initial call, it will return the same object as it was originally returning. | |
69 | * @return A {@code TextGUIThread} implementation that can be used to asynchronously manage the GUI | |
70 | */ | |
71 | TextGUIThread getGUIThread(); | |
72 | ||
73 | /** | |
74 | * Returns the interactable component currently in focus | |
75 | * @return Component that is currently in input focus | |
76 | */ | |
77 | Interactable getFocusedInteractable(); | |
78 | ||
79 | /** | |
80 | * Adds a listener to this TextGUI to fire events on. | |
81 | * @param listener Listener to add | |
82 | */ | |
83 | void addListener(Listener listener); | |
84 | ||
85 | /** | |
86 | * Removes a listener from this TextGUI so that it will no longer receive events | |
87 | * @param listener Listener to remove | |
88 | */ | |
89 | void removeListener(Listener listener); | |
90 | ||
91 | /** | |
92 | * Listener interface for TextGUI, firing on events related to the overall GUI | |
93 | */ | |
94 | interface Listener { | |
95 | /** | |
96 | * Fired either when no component was in focus during a keystroke or if the focused component and all its parent | |
97 | * containers chose not to handle the event. This event listener should also return {@code true} if the event | |
98 | * was processed in any way that requires the TextGUI to update itself, otherwise {@code false}. | |
99 | * @param textGUI TextGUI that had the event | |
100 | * @param keyStroke Keystroke that was unhandled | |
101 | * @return If the outcome of this KeyStroke processed by the implementer requires the TextGUI to re-draw, return | |
102 | * {@code true} here, otherwise {@code false} | |
103 | */ | |
104 | boolean onUnhandledKeyStroke(TextGUI textGUI, KeyStroke keyStroke); | |
105 | } | |
106 | } |