001package org.vishia.gral.ifc;
002
003import org.vishia.byteData.VariableContainer_ifc;
004import org.vishia.curves.WriteCurve_ifc;
005import org.vishia.gral.base.GetGralWidget_ifc;
006
007/**This interface describes the capabilities of a curve view as application interface.
008 * @author Hartmut Schorrig
009 *
010 */
011public interface GralCurveView_ifc extends GralWidget_ifc, GralSetValue_ifc, GetGralWidget_ifc
012{
013  
014  /**Version, history and license.
015   * <ul>
016   * <li>2012-06-08 Hartmut new: {@link #applySettings(String)} and {@link #writeSettings(Appendable)} for saving
017   *   and getting the configuration of curve view from a file or another text.
018   * <li>2012-04-26 Hartmut new extends GralWidget_ifc etc: A reference to a GralCurveView_ifc is a
019   *   reference to a widget too.
020   * <li>2012-04-26 Hartmut new capability for curve view: Set active or non active. It is a state
021   *   whether values are stored, independent of their visualization.
022   * <li>2012-03-25 Hartmut created as interface to {@link org.vishia.gral.base.GralCurveView}.
023   *   Approach: The capabilities should be described by an interface. Yet only 1 method.
024   * </ul>
025   * <br><br>
026   * <b>Copyright/Copyleft</b>:
027   * For this source the LGPL Lesser General Public License,
028   * published by the Free Software Foundation is valid.
029   * It means:
030   * <ol>
031   * <li> You can use this source without any restriction for any desired purpose.
032   * <li> You can redistribute copies of this source to everybody.
033   * <li> Every user of this source, also the user of redistribute copies
034   *    with or without payment, must accept this license for further using.
035   * <li> But the LPGL is not appropriate for a whole software product,
036   *    if this source is only a part of them. It means, the user
037   *    must publish this part of source,
038   *    but doesn't need to publish the whole source of the own product.
039   * <li> You can study and modify (improve) this source
040   *    for own using or for redistribution, but you have to license the
041   *    modified sources likewise under this LGPL Lesser General Public License.
042   *    You mustn't delete this Copyright/Copyleft inscription in this source file.
043   * </ol>
044   * If you intent to use this source without publishing its usage, you can get
045   * a second license subscribing a special contract with the author. 
046   * 
047   * @author Hartmut Schorrig = hartmut.schorrig@vishia.de
048   * 
049   */
050  public static final int version = 20120608;
051  
052  enum ModeWrite {currentView, autoSave};
053  
054  /**Adds a sampling value set.
055   * <br><br> 
056   * This method can be called in any thread. It updates only data,
057   * a GUI-call isn't done. But the method is not thread-safe. 
058   * If more as one threads writes data, an external synchronization should be done
059   * which may encapsulate more as only this call.
060   * <br><br> 
061   * The caller should force repaint to show the data in the graphic thread. 
062   * It is possible and sensitive to force repaint after writing some done one after another
063   * if the data are given faster than the users view eye.
064   * 
065   * @param values The values.
066   * @param timeshort relative time-stamp as currently wrapping time in milliseconds.
067   * 
068   * @see #setTimePoint(long, int, float)
069   */
070  void setSample(float[] values, int timeshort);
071
072  
073  
074  /**Sets a point of absolute time. This routine should be called at least 2 times in an wrapping area of timeshort.
075   * If timeshort are milliseconds, this is about 2000000 seconds. It means, it isn't often. You should call this routine 
076   * cyclically in an slower cycle. Then the graphic can showt the
077   * 
078   * @param date The absolute time appropriate to the timeshort value.
079   * @param timeshort The wrapping short time at this moment of data.
080   * @param millisecPerTimeshort Number of milliseconds per step of timeshort.
081   */
082  void setTimePoint(long date, int timeshort, float millisecPerTimeshort);
083  
084  
085  
086  /**Activates or deactivates. Only if the curve view is activated, it writes in time. If it is not active,
087   * than the curve can be watched, zoomed etc. 
088   * @param activate true to activate, false to deactivate.
089   */
090  void activate(boolean activate);
091  
092  /**Returns true if the curve view is active. See {@link #activate(boolean)}. */
093  boolean isActiv();
094  
095  /**Returns true if the curve view is active but freezed in presentation. */
096  boolean isFreezed();
097  
098  
099  /**Initializes an auto-save data write process. The time range will be set from the last autosave
100   * or from the start of recording to the actual last value of curve yet written.
101   * After them some invocations of {@link #writeCurve(WriteCurve_ifc, org.vishia.gral.ifc.GralCurveView_ifc.ModeWrite)}
102   * with {@link GralCurveView_ifc.ModeWrite#autoSave} can be done with this current time range.
103   * @return The absolute time of start of curve.
104   */
105  CharSequence timeInitAutoSave();
106  
107  
108  /**Writes the curve to the given interface, it is an exporter class.
109   * @param out exporter class reference
110   * @param mode autosave: Then the data range from {@link #timeInitAutoSave()} is used. 
111   *   currentView: Then the data range visible in window will be used.
112   */
113  void writeCurve(WriteCurve_ifc out, ModeWrite mode);
114  
115  
116  /**The ZBNF-syntax of a setting for curve view. */
117  static String syntaxSettings = "curveSettings::= [ timeVariable = <* ;?timeDatapath> ; ] { <Track> } \\e."
118    + "Track::= track <*:?name> : { datapath = <* ,;?datapath> | color = <* ,;?color> | "
119    + "scale = <#f?scale> | offset = <#f?offset> | 0-line-percent = <#?nullLine> "
120    + "? , } ; .";
121
122  
123  /**Applies the settings from the given String (maybe read from a file)
124   * and sets all tracks newly.
125   * @param in Input, syntax see {@link #syntaxSettings}
126   * @return true on success.
127   */
128  boolean applySettings(String in);
129
130  /**Writes the settings of the curve view in an output, maybe a file. 
131   * The syntax is matching to {@link #applySettings(String)}.
132   * 
133   * @param out any output stream.
134   */
135  void writeSettings(Appendable out);
136
137  
138}