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. If the caller is already on the GUI thread, the code is executed immediately
35 * @param runnable Code to run
36 * @throws java.lang.IllegalStateException If the GUI thread is not running
38 void invokeLater(Runnable runnable
) throws IllegalStateException
;
41 * Main method to call when you are managing the event/input/update loop yourself. This method will run one round
42 * through the GUI's event/input queue and update the visuals if required. If the operation did nothing (returning
43 * {@code false}) you could sleep for a millisecond and then try again. If you use {@code SameTextGUIThread} you
44 * must either call this method directly to make the GUI update or use one of the methods on
45 * {@code WindowBasedTextGUI} that blocks until a particular window has closed.
46 * @return {@code true} if there was anything to process or the GUI was updated, otherwise {@code false}
49 @SuppressWarnings("BooleanMethodIsAlwaysInverted")
50 boolean processEventsAndUpdate() throws IOException
;
53 * Schedules custom code to be executed on the GUI thread and waits until the code has been executed before
55 * @param runnable Code to run
56 * @throws IllegalStateException If the GUI thread is not running
57 * @throws InterruptedException If the caller thread was interrupted while waiting for the task to be executed
59 void invokeAndWait(Runnable runnable
) throws IllegalStateException
, InterruptedException
;
62 * Updates the exception handler used by this TextGUIThread. The exception handler will be invoked when an exception
63 * occurs in the main event loop. You can then decide how to log this exception and if you want to terminate the
65 * @param exceptionHandler Handler to inspect exceptions
67 void setExceptionHandler(ExceptionHandler exceptionHandler
);
70 * Returns the Java thread which is processing GUI events and updating the screen
71 * @return Thread which is processing events and updating the screen
76 * This interface defines an exception handler, that is used for looking at exceptions that occurs during the main
77 * event loop of the TextGUIThread. You can for example use this for logging, but also decide if you want the
78 * exception to kill the thread.
80 interface ExceptionHandler
{
82 * Will be called when an IOException has occurred in the main event thread
83 * @param e IOException that occurred
84 * @return If you return {@code true}, the event thread will be terminated
86 boolean onIOException(IOException e
);
89 * Will be called when a RuntimeException has occurred in the main event thread
90 * @param e RuntimeException that occurred
91 * @return If you return {@code true}, the event thread will be terminated
93 boolean onRuntimeException(RuntimeException e
);