| 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 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 | */ |
| 32 | public interface TextGUIThread { |
| 33 | /** |
| 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 |
| 37 | */ |
| 38 | void invokeLater(Runnable runnable) throws IllegalStateException; |
| 39 | |
| 40 | /** |
| 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} |
| 47 | * @throws IOException |
| 48 | */ |
| 49 | @SuppressWarnings("BooleanMethodIsAlwaysInverted") |
| 50 | boolean processEventsAndUpdate() throws IOException; |
| 51 | |
| 52 | /** |
| 53 | * Schedules custom code to be executed on the GUI thread and waits until the code has been executed before |
| 54 | * returning. |
| 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 |
| 58 | */ |
| 59 | void invokeAndWait(Runnable runnable) throws IllegalStateException, InterruptedException; |
| 60 | |
| 61 | /** |
| 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 |
| 64 | * thread or not. |
| 65 | * @param exceptionHandler Handler to inspect exceptions |
| 66 | */ |
| 67 | void setExceptionHandler(ExceptionHandler exceptionHandler); |
| 68 | |
| 69 | /** |
| 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 |
| 72 | */ |
| 73 | Thread getThread(); |
| 74 | |
| 75 | /** |
| 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. |
| 79 | */ |
| 80 | interface ExceptionHandler { |
| 81 | /** |
| 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 |
| 85 | */ |
| 86 | boolean onIOException(IOException e); |
| 87 | |
| 88 | /** |
| 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 |
| 92 | */ |
| 93 | boolean onRuntimeException(RuntimeException e); |
| 94 | } |
| 95 | } |