001package org.vishia.gral.ifc;
002
003import org.vishia.gral.base.GralGraphicTimeOrder;
004
005/**This interface supports to deal with the graphical implementation, especially the graphic thread.
006 * The graphic thread is associated with a graphic device usually. The graphic device handles
007 * all window appearances and events.
008 * <br><br>
009 * Events usual calls methods from the user because the methods are registered to the events. 
010 * Therefore some actions in user space are done in the graphic thread. If there are not additional actions,
011 * all operations with a GUI like Button press, mouse move, input in fields act in the graphic thread.
012 * This actions may block the execution of the application. Therefore actions which waits for something etc
013 * should run in extra threads. The adaption of a graphic device supports a queue mechanism
014 * to send events to the graphic from any other thread.
015 * <br><br>
016 * In the eclipse.SWT graphic the actions with SWT-widgets tests the thread and causes an exception on error.
017 * In the Swing graphic some actions are possible to call in another thread, but they are not threadsafe.
018 * The gral adaption helps to handle that problems.
019 * 
020 * @author Hartmut Schorrig
021 *
022 */
023public interface GralWindowMng_ifc
024{
025  /**Version, history and license.
026   * <ul>
027   * <li>2011-06-00 Hartmut created
028   * </ul>
029   * 
030   * <b>Copyright/Copyleft</b>:<br>
031   * For this source the LGPL Lesser General Public License,
032   * published by the Free Software Foundation is valid.
033   * It means:
034   * <ol>
035   * <li> You can use this source without any restriction for any desired purpose.
036   * <li> You can redistribute copies of this source to everybody.
037   * <li> Every user of this source, also the user of redistribute copies
038   *    with or without payment, must accept this license for further using.
039   * <li> But the LPGL is not appropriate for a whole software product,
040   *    if this source is only a part of them. It means, the user
041   *    must publish this part of source,
042   *    but doesn't need to publish the whole source of the own product.
043   * <li> You can study and modify (improve) this source
044   *    for own using or for redistribution, but you have to license the
045   *    modified sources likewise under this LGPL Lesser General Public License.
046   *    You mustn't delete this Copyright/Copyleft inscription in this source file.
047   * </ol>
048   * If you intent to use this source without publishing its usage, you can get
049   * a second license subscribing a special contract with the author. 
050   * 
051   * @author Hartmut Schorrig = hartmut.schorrig@vishia.de
052   */
053  public static final int version = 20120303;
054
055  /**Starts the execution of the graphic initializing and handling in a own thread.
056   * The following sets should be called already:
057   * <pre>
058   * setTitleAndSize("Title bar text", 800, 600);  //This instruction should be written first to output syntax errors.
059     setStandardMenus(new File("."));
060     setOutputArea("A3C3");        //whole area from mid to bottom
061     setFrameAreaBorders(20, 80, 75, 80);
062     </pre>
063   * They sets only some values, no initializing of the graphic is executed till now.
064   * <br><br>
065   * The graphic thread inside this class {@link #guiThread} initializes the graphic.
066   * All other GUI-actions should be done only in the graphic-thread. 
067   * The method {@link #addDispatchListener(Runnable)} is to be used therefore.
068   * <br><br>
069   * The method to use an own thread for the GUI is not prescribed. The initialization
070   * and all actions can be done in the users thread too. But then, the user thread
071   * have to be called {@link #dispatch()} to dispatch the graphic events. It is busy with it than.   
072   * @return true if started
073   */
074  //boolean buildMainWindow(String sTitle, int x, int y, int dx, int dy);
075
076  
077  /**Returns the identification number of the already started graphic thread. This number can be compared
078   * with the own thread id (java.lang.Thread.getId()). If there are equal, the current thread is the graphic thread.
079   * 
080   * @return The id of the graphic thread or 0 if it isn't started.
081   */
082  long getThreadIdGui();
083  
084  /**Returns true if the graphical application runs. 
085   * @return
086   */
087  boolean isRunning();
088  
089  void exit();
090  
091  /**Adds a order for building the gui. The order will be execute one time after intializing the Graphic
092   * and before entry in the dispatch loop. After usage the orders will be removed,
093   * to force garbage collection for the orders.
094   * @param order
095   */
096  //public void addGuiBuildOrder(Runnable order);
097
098  
099  /**Adds a listener, which will be called in the dispatch loop.
100   * @param listener
101   */
102  void addDispatchListener(GralGraphicTimeOrder listener);
103  
104  
105  /**Removes a listener, which was called in the dispatch loop.
106   * @param listener
107   */
108  public void removeDispatchListener(GralGraphicTimeOrder listener);
109  
110  
111}