    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}