001package org.vishia.gral.base;
002
003import java.util.EventObject;
004
005import org.vishia.event.EventConsumer;
006import org.vishia.event.TimeOrder;
007
008
009/**This is the base class for user classes, which contains code, that should be executed in the graphic thread.
010 * The method {@link #executeOrder()} should be overridden with the functionality which should be executed
011 * in the graphic thread before the system's dispatching routine starts.
012 *   
013 * @author Hartmut Schorrig.
014 *
015 */
016public abstract class GralGraphicTimeOrder extends TimeOrder
017{
018  
019  /**Version and history.
020   * <ul>
021   * <li>2015-01-10 Hartmut renamed from <code>GralDispatchCallbackWorker</code>
022   * <li>2012-02-14 Hartmut corr: {@link #addToGraphicThread(GralGraphicThread, int)}:
023   *   For time saving: If an instance is added already and its new execution time
024   *   is up to 5 ms later, nothing is done. It saves time for more as one call of this routine
025   *   in a fast loop.
026   * <li>2012-02-14 Hartmut corr: It was happen that an instance was designated with {@link #bAdded}==true
027   *   but it wasn't added, Therefore on {@link #addToGraphicThread(GralGraphicThread, int)} it is removed
028   *   from list and added newly. It is more save. 
029   * <li>2012-01-26 Hartmut chg: rename removeFromGraphicThread(GralGraphicThread) 
030   *   to {@link #removeFromQueue(GralGraphicThread)}. It is a better naming because it is removed from the queue
031   *   in the graphic thread. This class is only used in that queue. 
032   * <li>2012-01-15 Hartmut new: {@link #name} to identify, proper for debugging
033   * <li>2012-01-08 Hartmut new: {@link #addToGraphicThread(GralGraphicThread, int)} and 
034   *   {@link #removeFromQueue(GralGraphicThread)} as thread-safe functions which 
035   *   marks the instance as added (for delayed execution, for re-using).
036   * <li>2011-02-21 Hartmut created.
037   * </ul> 
038   * 
039   * <b>Copyright/Copyleft</b>:
040   * For this source the LGPL Lesser General Public License,
041   * published by the Free Software Foundation is valid.
042   * It means:
043   * <ol>
044   * <li> You can use this source without any restriction for any desired purpose.
045   * <li> You can redistribute copies of this source to everybody.
046   * <li> Every user of this source, also the user of redistribute copies
047   *    with or without payment, must accept this license for further using.
048   * <li> But the LPGL is not appropriate for a whole software product,
049   *    if this source is only a part of them. It means, the user
050   *    must publish this part of source,
051   *    but don't need to publish the whole source of the own product.
052   * <li> You can study and modify (improve) this source
053   *    for own using or for redistribution, but you have to license the
054   *    modified sources likewise under this LGPL Lesser General Public License.
055   *    You mustn't delete this Copyright/Copyleft inscription in this source file.
056   * </ol>
057   * If you are indent to use this sources without publishing its usage, you can get
058   * a second license subscribing a special contract with the author. 
059   * 
060   * @author Hartmut Schorrig = hartmut.schorrig@vishia.de
061   * 
062   * 
063   */
064  public final static String version = "2015-01-17";
065
066  
067  private static final long serialVersionUID = 1L;
068
069  /**To create the instance for the EventConsumer to enqueue time orders in the graphic thread queue.
070   * NOTE: class is need, not an anonymous instance, because initialization in super(..., new Enqueu...)
071   */
072  private static class EnqueueInGraphicThread implements EventConsumer {
073    @Override public int processEvent(EventObject ev)
074    { //the manager is known application global
075      GralMng mng = GralMng.get();  //the singleton.
076      if(mng !=null) {
077        mng.gralDevice().storeEvent(ev);
078      }
079      return mEventConsumed;
080    }
081
082  };
083  
084  
085
086  /**Super constructor for all graphic time orders.
087   * Usual a anonymous class is used for the instance: <pre>
088  private final GralGraphicTimeOrder repaintRequ = new GralGraphicTimeOrder("GralWidget.repaintRequ"){
089    QOverride public void executeOrder() {
090      repaintGthread();
091    }
092    QOverride public String toString(){ return name + ":" + GralWidget.this.name; }
093  };
094   * </pre>  
095   * @param name The name is only used for showing in debugging.
096   */
097  protected GralGraphicTimeOrder(String name)
098  { super(name, new EnqueueInGraphicThread(), GralMng.get().gralDevice.orderList);
099  }
100  
101
102  
103  /**Activates the graphic order to execute immediately as next call in the graphic thread. */
104  public void activate(){
105    GralMng mng = GralMng.get();  //the singleton.
106    mng.gralDevice().storeEvent(this);
107  }
108  
109}