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}