    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}