    001package org.vishia.gral.ifc;
    002
    003import java.util.List;
    004import java.util.Queue;
    005import java.util.concurrent.ConcurrentLinkedQueue;
    006
    007import org.vishia.byteData.VariableContainer_ifc;
    008import org.vishia.gral.base.GralGraphicThread;
    009import org.vishia.gral.base.GralGridProperties;
    010import org.vishia.gral.base.GralPos;
    011import org.vishia.gral.base.GralWidget;
    012import org.vishia.msgDispatch.LogMessage;
    013
    014
    015
    016/**This is a unique interface for the GUI-panel-manager to work with it.
    017 * To build the graphical application see {@link org.vishia.gral.ifc.GralMngBuild_ifc}.
    018 * This interface supports handling with all widgets in a GUI.
    019 * The widgets were selected by identifier or with their {@link GralWidget} instance
    020 * whereby the implementation environment of a widget may be known. That implementation environment
    021 * is a implementor of this interface.
    022 *
    023 * @author Hartmut Schorrig
    024 *
    025 */
    026public interface GralMng_ifc
    027{
    028
    029  /**The version history of this interface:
    030   * <ul>
    031   * <li>2012-08-20 Hartmut new: {@link #getWidgetsPermanentlyUpdating()} created but not used yet because
    032   *   {@link #refreshCurvesFromVariable(VariableContainer_ifc)} has the necessary functionality.
    033   * <li>2012-01-07 Hartmut new: {@link #setInfoDelayed(GralWidgetChangeRequ, int)}
    034   * <li>2011-05-08 Hartmut new; {@link #cmdClear} used to clear a whole swt.Table, commonly using: clear a content of widget.
    035   * <li>2011-05-01 Hartmut new: {@link #cmdInsert} etc now here.
    036   * <li>2011-05-01 Hartmut new: {@link #setInfo(GralWidget, int, int, Object)} as adequate method
    037   *     to {@link #insertInfo(String, int, String) but without symbolic addressing of the widget.
    038   *     It calls the internal method to insert an information in a queue for the graphical thread.
    039   *     It is thread-safe.
    040   * <li>All other changes in 2010
    041   * </ul>
    042   *
    043   * <b>Copyright/Copyleft</b>:<br>
    044   * For this source the LGPL Lesser General Public License,
    045   * published by the Free Software Foundation is valid.
    046   * It means:
    047   * <ol>
    048   * <li> You can use this source without any restriction for any desired purpose.
    049   * <li> You can redistribute copies of this source to everybody.
    050   * <li> Every user of this source, also the user of redistribute copies
    051   *    with or without payment, must accept this license for further using.
    052   * <li> But the LPGL is not appropriate for a whole software product,
    053   *    if this source is only a part of them. It means, the user
    054   *    must publish this part of source,
    055   *    but doesn't need to publish the whole source of the own product.
    056   * <li> You can study and modify (improve) this source
    057   *    for own using or for redistribution, but you have to license the
    058   *    modified sources likewise under this LGPL Lesser General Public License.
    059   *    You mustn't delete this Copyright/Copyleft inscription in this source file.
    060   * </ol>
    061   * If you intent to use this source without publishing its usage, you can get
    062   * a second license subscribing a special contract with the author.
    063   *
    064   * @author Hartmut Schorrig = hartmut.schorrig@vishia.de
    065   */
    066  public static final int version = 20120303;
    067
    068  final static int cmdInsert = 0xadd;     //add
    069
    070  final static int cmdSet = 0x5ed;     //add
    071
    072  final static int cmdClear = 0xc1ea3;     //add
    073
    074  final static int cmdBackColor = 0xbacc0103;     //add
    075
    076  final static int cmdLineColor = 0x111c0103;
    077
    078  final static int cmdTextColor = 0x1e8c0103;     //add
    079
    080  final static int cmdColor = 0xc0103;
    081
    082  final static int cmdRedraw = 0x3ed3a2;  //redraw
    083
    084  //final static int cmdRedrawPart = 0x3ed3a201;  //redraw
    085
    086  final static int cmdRemove = 0xde1e7e;  //delete
    087
    088  final static int cmdSelect = 0x5e1ecd;
    089
    090  final static int cmdSetWindowVisible = 0x10001;
    091
    092  final static int cmdCloseWindow = 0x10002;
    093
    094  //final static int cmdSetData = 0x5e1da1a;  //setdata
    095
    096
    097  GralGridProperties propertiesGui();
    098
    099  GralGraphicThread gralDevice();
    100
    101  LogMessage log();
    102
    103  /**Searches a widget by name.
    104   * @param name The name which is assigned on build.
    105   * @return null if the widget is not found.
    106   */
    107  GralWidget getWidget(String name);
    108
    109        /**Returns the list of all widgets with its informations.
    110         * The graphical representation of the widgets is unknown here.
    111         * If it should be used, the graphic implementation should be known
    112         * and a adequate instanceof-test and cast is necessary.
    113         */
    114        @Deprecated List<GralWidget> getListCurrWidgets();
    115
    116
    117
    118  /**Sets the color of background of the widget, if possible.
    119   * @param name The name of the widget, which was given by the add...()-Operation
    120   * @ix may be a line number of table or an position identifier. 0 if unused for the kind of widget.
    121   * @param colorValue blue, green and red in the bits 23..16, 15..8 and 7..0.
    122   *        opaque in bits 31..24 if possible.
    123   */
    124  void setBackColor(String name, int ix, int colorValue);
    125
    126
    127
    128  /**Sets the text into a named widget.
    129   * @param widget
    130   * @param text The text is not stored by reference, it can be changed after them.
    131   */
    132  void setText(String widget, CharSequence text);
    133
    134  /**Sets the text into a named widget.
    135   * @param widget
    136   * @param text The text is not stored by reference, it can be changed after them.
    137   */
    138  void setValue(String widget, Object visibleInfo, Object userData);
    139
    140  /**Appends the text into a named widget. The widget can be especially a text area.
    141   * @param widget
    142   * @param text The text is not stored by reference, it can be changed after them.
    143   */
    144  void addText(String widget, CharSequence text);
    145
    146
    147  /**Sets the color of background of the widget, if possible.
    148   * @param name The name of the widget, which was given by the add...()-Operation
    149   * @ix may be a line number of table or an position identifier. 0 if unused for the kind of widget.
    150   * @param colorValue blue, green and red in the bits 23..16, 15..8 and 7..0.
    151   *        opaque in bits 31..24 if possible.
    152   * @deprecated use {@link GralWidget#setBackColor(GralColor, int)
    153   */
    154  @Deprecated
    155  void setBackColor(GralWidget widgetDescr, int ix, int colorValue);
    156
    157
    158  /**Sets the color of line of the widget, if possible.
    159   * @param name The name of the widget, which was given by the add...()-Operation
    160   * @ix may be a line number of table or an position identifier. 0 if unused for the kind of widget.
    161   * @param colorValue blue, green and red in the bits 23..16, 15..8 and 7..0.
    162   *        opaque in bits 31..24 if possible.
    163   * @deprecated use {@link GralWidget#setLineColor(GralColor, int)
    164   */
    165  @Deprecated
    166  void setLineColor(GralWidget widgetDescr, int ix, int colorValue);
    167
    168
    169  /**Sets the color of text of the widget, if possible.
    170   * @param name The name of the widget, which was given by the add...()-Operation
    171   * @ix may be a line number of table or an position identifier. 0 if unused for the kind of widget.
    172   * @param colorValue blue, green and red in the bits 23..16, 15..8 and 7..0.
    173   *        opaque in bits 31..24 if possible.
    174   * @deprecated use {@link GralWidget#setTextColor(GralColor)
    175   */
    176  @Deprecated
    177  void setTextColor(GralWidget widgetDescr, int ix, int colorValue);
    178
    179
    180  /**
    181   * @param widgetDescr
    182   * @param colorBorder
    183   * @param colorInner
    184   * @deprecated use {@link org.vishia.gral.base.GralLed#setColor(GralColor, GralColor)}.
    185   */
    186  @Deprecated
    187  void setLed(GralWidget widgetDescr, int colorBorder, int colorInner);
    188
    189  /**Adds a sampling value set.
    190   * @param sName The registered name
    191   * @param values The values.
    192   */
    193  void setSampleCurveViewY(String sName, float[] values);
    194
    195  /**Forces the redrawing for all set samples. It should be called after { @link #setSampleCurveViewY(String, float[])}.
    196   * @param sName The name of the widget.
    197   */
    198  void redrawWidget(String sName);
    199
    200
    201
    202  /**Forces the resizing of the given widged.
    203   * @param widgd the widget
    204   */
    205  void resizeWidget(GralWidget widgd, int xSizeParent, int ySizeParent);
    206
    207
    208  /**Sets a given and registered window visible at the given position and size or set it invisible.
    209   * <br>
    210   * A window can be created by invoking {@link org.vishia.gral.ifc.GralMngBuild_ifc#createWindow(String, boolean)}
    211   * in the build phase of the gui. It can be hidden because it is not necessary to show and operate with them.
    212   * In a adequate phase of operate it can be shown and focused.
    213   * <br>
    214   * The position is given relative to that panel,
    215   * which is stored in {@link GralPos#panel}. To get a position instance,
    216   * you can set a position invoking
    217   * <ul>
    218   * <li>{@link org.vishia.gral.ifc.GralMngBuild_ifc#selectPanel(String)}
    219   * <li>{@link org.vishia.gral.ifc.GralMngBuild_ifc#setPosition(float, float, float, float, int, char)}
    220   * <li>GralGridPos pos = {@link org.vishia.gral.ifc.GralMngBuild_ifc#getPositionInPanel()}.
    221   * </ul>
    222   * That can be done in the build phase of the graphic. The position can be stored. It is possible to adjust
    223   * the position relative to the unchanged panel by changing the values of {@link GralPos#x} etc.
    224   * It is possible too to change the Panel which relates to the position. Then the grid managing instance
    225   * have to be known via the {@link org.vishia.gral.ifc.GralMngBuild_ifc} to select a panel.
    226   * The panels may be moved or resized. With the knowledge of the relative position of the window in respect to a panel
    227   * of the parent window, the window can be placed onto a proper position of the whole display.
    228   *
    229   * @param window the instance of the window wrapper.
    230   * @param atPos If null then hide the window. If not null then show the window.
    231   *        The position and size of the window is given related to any panel of any other window.
    232   *
    233   * @return true if it is visible.
    234   * @deprecated
    235   */
    236  @Deprecated
    237  boolean XXXsetWindowsVisible(GralWindow_ifc window, GralPos atPos);
    238
    239
    240        /**Gets the value to the named color. It is a method of the graphic.
    241         * @param sName supported: red, green, blue, yellow
    242         * @return 3 bytes intensity: bit23..16 blue, bit15..8: green, bit 7..0 red.
    243         */
    244        int getColorValue(String sName);
    245
    246  /**Gets the value from a widget.
    247   * @param sName The name of the widget. The widget will be searched per name.
    248   * @return null if the named widget isn't found or the widget is not able to input.
    249   */
    250  String getValue(String sName);
    251
    252        /**Gets the String value from a widget with given descriptor
    253         * <ul>
    254         * <li>Text field: The content written into, with all spaces.
    255         * <li>Table: content of the selected line, all cells separated with tabulator char.
    256         * </ul>
    257         * @param widgetDescr The widget.
    258         * @return The content.
    259         */
    260        String getValueFromWidget(GralWidget widgetDescr);
    261
    262
    263        /**Sets the focus to the designated widget.
    264         * @param widgd
    265         * @return true if the focus is set. False if it isn't able to set the focus.
    266         */
    267        void setFocus(GralWidget widgd);
    268
    269        /**Notifies that this widget has the focus gotten.
    270         * Note: not all widgets notifies this. The focus can be used to detect which widget is active
    271         * while a menu command or any button is pressed.
    272         * @param widgd The widget descriptor
    273         */
    274        void notifyFocus(GralWidget widgd);
    275
    276
    277  GralWidget getWidgetInFocus();
    278
    279  /**Returns a list of the last widgets in focus in there focus order.
    280   * On access to the list, usual with an iterator, the returned list should be used
    281   * with mutex. Use 'synchronized(focusList){....}'. But don't block the access for a longer time!
    282   * The graphical thread will be wait on mutex if any other widget will be focused.
    283   *
    284   * @return The list.
    285   */
    286  List<GralWidget> getWidgetsInFocus();
    287
    288
    289  /**Gets the list of all panels which are visible yet and should be updated with values therefore.
    290   * @return The list of widget list.
    291   */
    292  ConcurrentLinkedQueue<GralVisibleWidgets_ifc> getVisiblePanels();
    293
    294
    295  /**refresh all curve views. */
    296  void refreshCurvesFromVariable(VariableContainer_ifc container);
    297
    298  /**Gets a list of widgets which should be updated permanently because they store data in any time.
    299   * @return List of widgets which are permanently to update
    300   */
    301  GralVisibleWidgets_ifc getWidgetsPermanentlyUpdating();
    302
    303
    304  /**Returns true if the current thread is the graphical thread.
    305   * This routine is used internally firstly. The graphical thread is that thread, which dispatches
    306   * all orders for the graphic, see {@link org.vishia.gral.base.GralGraphicThread#run()}.
    307   * @return true if this routine is called from the same thread as the graphical thread.
    308   */
    309  boolean currThreadIsGraphic();
    310
    311  /**Writes a log message instead throwing an exception or writing on standard output.
    312   * The log message contains a timestamp and can be dispatched to any destination.
    313   * All internal methods of gral writes exceptions to that logging system instead abort the execution of the application.
    314   * @param msgId The ident number for dispatching and evaluation.
    315   * @param exc The catched exception.
    316   */
    317  void writeLog(int msgId, Exception exc);
    318
    319}