Fix UTF8 bug, create first executable JAR file
[jvcard.git] / src / com / googlecode / lanterna / gui2 / TextGUI.java
... / ...
CommitLineData
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 */
19package com.googlecode.lanterna.gui2;
20
21import com.googlecode.lanterna.graphics.Theme;
22import com.googlecode.lanterna.input.KeyStroke;
23
24import 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 */
31public 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}