src/com/googlecode/lanterna/gui2/TextGUIThread.java

   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 }