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 java
.io
.IOException
;
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
32 public interface TextGUIThread
{
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.
37 * @param runnable Code to run asynchronously
38 * @throws java.lang.IllegalStateException If the GUI thread is not running
40 void invokeLater(Runnable runnable
) throws IllegalStateException
;
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}
51 @SuppressWarnings("BooleanMethodIsAlwaysInverted")
52 boolean processEventsAndUpdate() throws IOException
;
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.
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
62 void invokeAndWait(Runnable runnable
) throws IllegalStateException
, InterruptedException
;
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
68 * @param exceptionHandler Handler to inspect exceptions
70 void setExceptionHandler(ExceptionHandler exceptionHandler
);
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
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.
83 interface ExceptionHandler
{
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
89 boolean onIOException(IOException e
);
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
96 boolean onRuntimeException(RuntimeException e
);