Fix UTF8 bug, create first executable JAR file
[jvcard.git] / src / com / googlecode / lanterna / gui2 / TextGUIThread.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 java.io.IOException;
22
23/**
24 * Class that represents the thread this is expected to run the event/input/update loop for the {@code TextGUI}. There
25 * are mainly two implementations of this interface, one for having lanterna automatically spawn a new thread for doing
26 * all the processing and leaving the creator thread free to do other things, and one that assumes the creator thread
27 * will hand over control to lanterna for as long as the GUI is running.
28 * @see SameTextGUIThread
29 * @see SeparateTextGUIThread
30 * @author Martin
31 */
32public interface TextGUIThread {
33 /**
34 * Invokes custom code on the GUI thread. Even if the current thread <b>is</b> the GUI thread, the code will be
35 * executed at a later time when the event processing is done.
36 *
37 * @param runnable Code to run asynchronously
38 * @throws java.lang.IllegalStateException If the GUI thread is not running
39 */
40 void invokeLater(Runnable runnable) throws IllegalStateException;
41
42 /**
43 * Main method to call when you are managing the event/input/update loop yourself. This method will run one round
44 * through the GUI's event/input queue and update the visuals if required. If the operation did nothing (returning
45 * {@code false}) you could sleep for a millisecond and then try again. If you use {@code SameTextGUIThread} you
46 * must either call this method directly to make the GUI update or use one of the methods on
47 * {@code WindowBasedTextGUI} that blocks until a particular window has closed.
48 * @return {@code true} if there was anything to process or the GUI was updated, otherwise {@code false}
49 * @throws IOException
50 */
51 @SuppressWarnings("BooleanMethodIsAlwaysInverted")
52 boolean processEventsAndUpdate() throws IOException;
53
54 /**
55 * Schedules custom code to be executed on the GUI thread and waits until the code has been executed before
56 * returning. If this is run on the GUI thread, it will immediately run the {@code Runnable} and then return.
57 *
58 * @param runnable Code to be run and waited for completion before this method returns
59 * @throws IllegalStateException If the GUI thread is not running
60 * @throws InterruptedException If the caller thread was interrupted while waiting for the task to be executed
61 */
62 void invokeAndWait(Runnable runnable) throws IllegalStateException, InterruptedException;
63
64 /**
65 * Updates the exception handler used by this TextGUIThread. The exception handler will be invoked when an exception
66 * occurs in the main event loop. You can then decide how to log this exception and if you want to terminate the
67 * thread or not.
68 * @param exceptionHandler Handler to inspect exceptions
69 */
70 void setExceptionHandler(ExceptionHandler exceptionHandler);
71
72 /**
73 * Returns the Java thread which is processing GUI events and updating the screen
74 * @return Thread which is processing events and updating the screen
75 */
76 Thread getThread();
77
78 /**
79 * This interface defines an exception handler, that is used for looking at exceptions that occurs during the main
80 * event loop of the TextGUIThread. You can for example use this for logging, but also decide if you want the
81 * exception to kill the thread.
82 */
83 interface ExceptionHandler {
84 /**
85 * Will be called when an IOException has occurred in the main event thread
86 * @param e IOException that occurred
87 * @return If you return {@code true}, the event thread will be terminated
88 */
89 boolean onIOException(IOException e);
90
91 /**
92 * Will be called when a RuntimeException has occurred in the main event thread
93 * @param e RuntimeException that occurred
94 * @return If you return {@code true}, the event thread will be terminated
95 */
96 boolean onRuntimeException(RuntimeException e);
97 }
98}