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}