org.vishia.gral.ifc

## Interface GralWidget_ifc

- All Superinterfaces:
    Removeable
  All Known Subinterfaces:
    GralCurveView_ifc, GralTable_ifc<UserData>, GralTableLine_ifc<UserData>, GralTextBox_ifc, GralTextField_ifc, GralWindow_ifc
  All Known Implementing Classes:
    AwtPanel, FcmdFileCard, GralButton, GralCurveView, GralFileSelector, GralHorizontalSelector, GralHtmlBox, GralInfoBox, GralLabel, GralLed, GralPanelContent, GralPlotArea, GralSlider, GralTabbedPanel, GralTable, GralTable.TableLineData, GralTextBox, GralTextField, GralValueBar, GralWidget, GralWindow

      public interface GralWidget_ifc
      extends Removeable

  This is the basic interface for all widgets of the Graphic Adaption Layer (gral).
  Strategy of changing the graphical content of a widget:
  2013-09-30
  The SWT graphical implementation prohibits changing the graphical appearance, for example setText(newText), in another thread. Other graphical implementations are not thread-safe. Often a graphic application runs in only one thread, so that isn't a problem. But applications with complex data gathering processes needs to run in several threads. It may be fine to set the widgets in that threads immediately, seen from the programmers perspective. For multithread usage see `GralGraphicThread`.
  The solution of setting any content in a Widget in any thread in Gral is:
  - The thread invokes methods of this `GralWidget_ifc` or methods of an derived `GralWidget` such as `GralTable`, for example `setText(CharSequence)`, `setTextColor(GralColor)` or `org.vishia.gral.base.GralTable#setColorCurrLine(GralColor)`.
  - That methods store the given data either in the common `GralWidget.DynamicData` `GralWidget.dyda` of the widget or in specific data of a GralWidget implementation.
  - That method calls `repaint(int, int)` with a proper millisecond delay (usual 100). The graphic implementation widget is not touched in this time. Usual it is not necessary to show information in a faster time than 100 ms if it is not a high speed animated graphic. The delayed repaint request saves calculation time if more as one property is changed on the same widget.
  - The delayed repaint request queues the instance `GralWidget.repaintRequ` (only private visible) of `GralGraphicTimeOrder` in the central queue of requests using `GralGraphicThread.addDispatchOrder(org.vishia.gral.base.GralGraphicTimeOrder)`. The `GralGraphicThread` is known by `GralWidget.itsMng`.
  - If for example 20 widgets are changed in maybe 40 properties, that queue contains the 20 instances of `GralGraphicTimeOrder`. Any of them may have a specific delay. The graphic thread organizes it in a proper kind of time.
  - If a `GralGraphicTimeOrder` is dequeued in the graphic thread, its method `org.vishia.gral.base.GralGraphicTimeOrder#executeOrder(boolean)` is invoked. This method calls `GralWidgImpl_ifc.repaintGthread()` via the association `GralWidget._wdgImpl`.
  - The `rerepaintGthread()` method is overridden in the implementation layer with the necessary statements to transfer the non-graphic data of this `GralWidget` especially stored in `GralWidget.dyda` to the special implementation widget method invocations such as `Text.setText(String)` which touches the graphic widget. Then a `Control.update()` and `Control.redraw()` is invoked to show the content.
  It is a complex approach. But it is simple for usage. The user can change the content in any thread. The user does not need to organize a queue for the graphic thread by itself. The queue is a part of Gral.
  Strategy to create widgets and positioning: see `GralMngBuild_ifc`.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `GralWidget_ifc.ActionChange`
    `static class` | `GralWidget_ifc.ActionChangeWhen`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `sVersion` Version, history and license.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `createImplWidget_Gthread()` Sets this widget to the current panel at the current given position.
    `GralWidget_ifc.ActionChange` | `getActionChange(GralWidget_ifc.ActionChangeWhen when)`
    `GralColor` | `getBackColor(int ix)` Gets the background color for the widget.
    `java.lang.String` | `getCmd()` Any widget can have a command String, which can be quest for example in an action.
    `long` | `getContentIdent()` Gets the content identification of the users data which are set with `setContentIdent(long)`.
    `java.lang.Object` | `getContentInfo()`
    `java.lang.Object` | `getData()` Gets the application specific info.
    `java.lang.String` | `getDataPath()`
    `java.lang.String` | `getName()`
    `GralMng` | `gralMng()` Returns the associated singleton GralMng.
    `boolean` | `isChanged(boolean setUnchanged)` Returns true if the content is changed from a user action on GUI.
    `boolean` | `isEditable()` Query whether this widget is able to change from user handling.
    `boolean` | `isGraphicDisposed()` Returns true if the graphic implementatin widget was initialized, and then it was disposed.
    `boolean` | `isInFocus()` Returns true if this widget is the focused one.
    `boolean` | `isNotEditableOrShouldInitialize()` Query whether this field should be written from any initial or actual data.
    `boolean` | `isVisible()` Returns whether the widget is visible or not.
    `void` | `refreshFromVariable(VariableContainer_ifc container)` Capability for any widget to update its content from its associated variables described in its sDataPath.
    `void` | `refreshFromVariable(VariableContainer_ifc container, long timeAtleast, GralColor colorRefreshed, GralColor colorOld)`
    `void` | `repaint()` repaint request.
    `void` | `repaint(int delay, int latest)` Possible delayed repaint, can be called in any thread.
    `void` | `setBackColor(GralColor color, int ix)` Sets the background color for the widget.
    `GralColor` | `setBackgroundColor(GralColor color)` Deprecated. use `setBackColor(GralColor, int)`
    `void` | `setBoundsPixel(int x, int y, int dx, int dy)`
    `void` | `setCmd(java.lang.String cmd)` Any widget can have a command String, which can be quest for example in an action.
    `long` | `setContentIdent(long ident)` Sets a identification for the shown data.
    `void` | `setData(java.lang.Object data)` Sets a application specific data.
    `void` | `setDataPath(java.lang.String sDataPath)` Sets the data path.
    `void` | `setEditable(boolean editable)` Sets whether it is able to edit the content of the text field or text box.
    `void` | `setFocus()` Sets the focus to the widget. .
    `void` | `setFocus(int delay, int latest)` Sets the focus to the widget. .
    `GralColor` | `setForegroundColor(GralColor color)` Deprecated. use `setLineColor(GralColor, int)`
    `void` | `setHtmlHelp(java.lang.String url)` Sets the html help url for this widget.
    `void` | `setLineColor(GralColor color, int ix)` Sets the line color for the widget.
    `void` | `setText(java.lang.CharSequence text)` Set the text of the widget.
    `void` | `setTextColor(GralColor color)` Sets the text color for the widget.
    `void` | `setToPanel(GralMngBuild_ifc mng)` Deprecated.
    `boolean` | `setVisible(boolean visible)` Sets this widget visible on graphic or invisible.

    - ### Methods inherited from interface org.vishia.util.Removeable

      `remove`

- - ### Field Detail

    - #### sVersion

          static final java.lang.String sVersion

      Version, history and license.
      - 2016-08-31 Hartmut new: `isGraphicDisposed()` especially used for GralWindow-dispose detection.
      - 2016-07-20 Hartmut chg: instead setToPanel now `createImplWidget_Gthread()`. It is a better name.
      - 2015-10-11 Hartmut new: `createImplWidget_Gthread()` without mng as parameter.
      - 2015-09-12 Hartmut new: `getData()`, `setData(Object)` was existent as `GralWidget.setContentInfo(Object)`, now explicit property of any widget.
      - 2015-07-12 Hartmut new: `setCmd(String)` and `getCmd()` is present in `GralWidget` since 2010 but it was not accepted as core property. But it is a core property.
      - 2013-03-13 Hartmut new `getContentIdent()`, `setContentIdent(long)`
      - 2013-03-13 Hartmut new `isNotEditableOrShouldInitialize()` to support edit fields.
      - 2012-08-21 The method `setBackColor(GralColor, int)`, `setLineColor(GralColor, int)` and `setTextColor(GralColor)` are declared here. What methods are deprecated? I thing `setBackgroundColor(GralColor)`.
      - 2012-07-29 Hartmut chg: `setFocus()` and `setFocus(int, int)` can be called in any thread yet.
      - 2012-07-13 Hartmut new. `#getWidgetMultiImplementations()`. This method is not used in any widget yet, but it may be necessary for complex widgets.
      - 2012-04-25 Hartmut new: `refreshFromVariable(VariableContainer_ifc)`: Capability for any widget to update its content from its associated variables described in its sDataPath.
      - 2012-03-31 Hartmut new: `isVisible()`
      - 2012-01-16 Hartmut new: Concept `repaint()`, can be invoked in any thread. With delay possible.
      - 2011-06-00 Hartmut created
      Copyright/Copyleft:
      For this source the LGPL Lesser General Public License, published by the Free Software Foundation is valid. It means:
      1. You can use this source without any restriction for any desired purpose.
      2. You can redistribute copies of this source to everybody.
      3. Every user of this source, also the user of redistribute copies with or without payment, must accept this license for further using.
      4. But the LPGL is not appropriate for a whole software product, if this source is only a part of them. It means, the user must publish this part of source, but doesn't need to publish the whole source of the own product.
      5. You can study and modify (improve) this source for own using or for redistribution, but you have to license the modified sources likewise under this LGPL Lesser General Public License. You mustn't delete this Copyright/Copyleft inscription in this source file.
      If you intent to use this source without publishing its usage, you can get a second license subscribing a special contract with the author.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getName

          java.lang.String getName()

    - #### getDataPath

          java.lang.String getDataPath()

    - #### setCmd

          void setCmd(java.lang.String cmd)

      Any widget can have a command String, which can be quest for example in an action. The widget can be identified by its `getCmd()` independent of its name which can be set on runtime with this method.

    - #### getCmd

          java.lang.String getCmd()

      Any widget can have a command String, which can be quest for example in an action. The widget can be identified by this method independent of its name. See `setCmd(String)`.

    - #### setData

          void setData(java.lang.Object data)

      Sets a application specific data. It should help to present user data which are associated to this widget. This info can be set and changed anytime.

    - #### getData

          java.lang.Object getData()

      Gets the application specific info. See `#setContentInfo(Object)`.

    - #### getActionChange

          GralWidget_ifc.ActionChange getActionChange(GralWidget_ifc.ActionChangeWhen when)

    - #### createImplWidget_Gthread

          void createImplWidget_Gthread()

      Sets this widget to the current panel at the current given position. This routine should be called only one time after the Gral widget was created. It creates the graphical appearance using the capabilities of the derived GralMng for the systems graphic level. This method invokes `GralMng.createImplWidget_Gthread(GralWidget)` which tests the type of the derived GralWidget to create the correct graphical widget. That method calls the implementing specific `GralMng.ImplAccess#createImplWidget_Gthread(GralWidget)` which knows the implementation graphic.
      Instance structure
      The implementation of a widget is firstly a class which is inherit from `ImplAccess`. With them the `GralWidget` is references because it is the environment class. The core graphical widget is an aggregation in this instance. It is possible that more as one implementation widget is used for a Gral Widget implementation. For example a text field with a prompt consists of two implementation widgets, the text field and a label for the prompt.
      Positioning and Registering the widget: The registering of a widget is done in `GralWidget#initPosAndRegisterWidget(GralPos)` which is called either on construction of a widget with a String-given position, before it appears on graphic, or on construction of the graphic widget. It calls the package private `GralWidget#initPosAndRegisterWidget(GralPos)`, which takes the given position, stores it in the `GralWidget.pos()` and adds the widget both to its panel which is given with the pos and registers the widget in the GralMng for simple global access. If the name of the widget starts with "@" its name in the panel is the part after "@" whereby the global name is the "panelname.widgetname". If a widget's position is given from left and from right or with percent, it is resized on resizing the window and the panel.
      Throws:
        `java.lang.IllegalStateException` - This routine can be called only if the graphic implementation widget is not existing. It is one time after startup or more as one time if `#removeWidgetImplementation()` was called.

    - #### setToPanel

          void setToPanel(GralMngBuild_ifc mng)

      Deprecated. Use `createImplWidget_Gthread()`.
      Parameters:
        `mng` - not used. It is known as singleton. Use null as argument.

    - #### gralMng

          GralMng gralMng()

      Returns the associated singleton GralMng. The GralMng is associated only if the widget is setToPanel, see `setToPanel(GralMngBuild_ifc)`.
      Returns:
        null if the Widget is created yet without connection to the graphical implementation layer

    - #### setFocus

          void setFocus()

      Sets the focus to the widget. . It can be called in any thread. If it is called in the graphic thread, the repaint action is executed immediately in the thread. Elsewhere the graphic thread will be woken up.

    - #### setFocus

          void setFocus(int delay,
                        int latest)

      Sets the focus to the widget. . It can be called in any thread. If it is called in the graphic thread, the repaint action is executed immediately in the thread. Elsewhere the graphic thread will be woken up.
      Parameters:
        `delay` -
        `latest` -

    - #### isInFocus

          boolean isInFocus()

      Returns true if this widget is the focused one.

    - #### isGraphicDisposed

          boolean isGraphicDisposed()

      Returns true if the graphic implementatin widget was initialized, and then it was disposed. It is able to use especially to detect whether a sub window is closed or if the primary window was closed, to finish any other (waiting) thread. It may be used on any disposed widget.
      Returns:
        true if the Widget was created and after them disposed again.

    - #### setVisible

          boolean setVisible(boolean visible)

      Sets this widget visible on graphic or invisible. Any widget can be visible or not. More as one widgets can use the same position, only one of them may set visible. For a `GralWindow`, its the visibility of the whole window. Note that a window which is invisible is not shown in the task bar of the operation system. Note that an application can have more as one window. Note that a dialog window can be set to invisible if it is not need yet instead destroy and build newly.
      Parameters:
        `visible` -
      Returns:

    - #### isVisible

          boolean isVisible()

      Returns whether the widget is visible or not. This method can be invoked in any thread. It is an estimation because the state of the widget may be changed in the last time or a window can be covered by another one. The widget is not visible if it is a member of a card in a tabbed panel and that tab is not the selected one.
      Returns:
        true if the widget seams to be visible.

    - #### setEditable

          void setEditable(boolean editable)

      Sets whether it is able to edit the content of the text field or text box. If a content is not able to edit, it is a showing field or box. The user can't change the content. But the user can set the cursor, select any text and copy to the systems clipboard. If the content is able to edit, the change should be notified and the content should be gotten. To do that TODO
      Parameters:
        `editable` - true then the content is going to be able to change. False then the edit functionality is disabled.

    - #### isEditable

          boolean isEditable()

      Query whether this widget is able to change from user handling.

    - #### isNotEditableOrShouldInitialize

          boolean isNotEditableOrShouldInitialize()

      Query whether this field should be written from any initial or actual data.

    - #### setBackgroundColor

          @Deprecated
          GralColor setBackgroundColor(GralColor color)

      Deprecated. use `setBackColor(GralColor, int)`

    - #### setForegroundColor

          @Deprecated
          GralColor setForegroundColor(GralColor color)

      Deprecated. use `setLineColor(GralColor, int)`

    - #### setBackColor

          void setBackColor(GralColor color,
                            int ix)

      Sets the background color for the widget. It supports widgets with more as one background color by an index. The usage of the index is widget-specific. An index -1 should mean: All backgrounds. ix=0 means the first background.
      Parameters:
        `color` - Any color
        `ix` - -1 for non-specific, 0 for the first color or if only one color is supported, 1, ... if the widget has more as one background.

    - #### getBackColor

          GralColor getBackColor(int ix)

      Gets the background color for the widget.
      Parameters:
        `ix` - 0 if only one color is supported, 1, ... if the widget has more as one background.
      Returns:
        color Any color

    - #### setLineColor

          void setLineColor(GralColor color,
                            int ix)

      Sets the line color for the widget.
      Parameters:
        `color` - Any color
        `ix` - 0 if only one color is supported, 1, ... if the widget has more as one line.

    - #### setTextColor

          void setTextColor(GralColor color)

      Sets the text color for the widget.
      Parameters:
        `color` - Any color

    - #### setText

          void setText(java.lang.CharSequence text)

      Set the text of the widget. If the widget is a button, the standard button text is changed. If it is a window, its title is changed.
      Concept of changing a widget from application:
      Here the generally approach is described, appropriate for this method, but in the same kind for all methods to set something like `setBackColor(GralColor, int)` etc.
      With the set methods the user stores the text, color etc. in graphic-independent attributes. Then the method `repaint(int, int)` is invoked with the standard delay of `#repaintDelay` and `#repaintDelayMax`. With that the widget-specific private instance of `#repaintRequ` is added to the queue of requests in the `GralGraphicThread#addTimeOrder(GralGraphicTimeOrder)`. In the requested time that dispatch order is executed in the graphic thread. It calls `GralWidgImpl_ifc.repaintGthread()`. That method is implemented in the graphic implementation layer of the widget. It sets the appropriate values from the independent Gral attributes to the implementation specifics and invoke a redraw of the graphic layer.
      If more as one attribute is changed one after another, only one instance of the `GralGraphicTimeOrder` is queued. All changed attributes are stored in `DynamicData#whatIsChanged` and the `GralWidgImpl_ifc.repaintGthread()` quests all changes one after another. It means that a thread switch is invoked only one time per widget for more as one change.
      See `DynamicData`. That composite part of a widget stores all standard dynamic data of a widget.

    - #### setHtmlHelp

          void setHtmlHelp(java.lang.String url)

      Sets the html help url for this widget. That information will be used if the widget is focused to control the help window output.
      Parameters:
        `url` - String given url, maybe a local file too with #internalLabel.

    - #### repaint

          void repaint()

      repaint request. It can be called in any thread. If it is called in the graphic thread, the repaint action is executed immediately in the thread. Elsewhere the graphic thread will be waken up in the standard repaint time (about 100 ms). If this routine is invoked more as one time before the standard repaint time expires and not in the graphic thread, then the repaint is executed only one time after the given delay with the last set data. See `repaint(int, int)`

    - #### repaint

          void repaint(int delay,
                       int latest)

      Possible delayed repaint, can be called in any thread. If this method is re-called in the time where the delay is not elapsed then the delay will be set newly, the timer is winding up again. But the latest time on first call will be used.
      Parameters:
        `delay` - in milliseconds. If 0 or less 0, then it is executed immediately if the calling thread is the graphic thread.
        `latest` - The latest draw time in milliseconds. If it is less 0, then it is unused. If it is 0 or less delay if a delay is given, then the delay isn't wound up on re-call.

    - #### setBoundsPixel

          void setBoundsPixel(int x,
                              int y,
                              int dx,
                              int dy)

    - #### setDataPath

          void setDataPath(java.lang.String sDataPath)

      Sets the data path. It is a String in application context. If variables are used, it is the path of one or more variables, see `refreshFromVariable(VariableContainer_ifc)`.
      Parameters:
        `sDataPath` -

    - #### isChanged

          boolean isChanged(boolean setUnchanged)

      Returns true if the content is changed from a user action on GUI.
      Parameters:
        `setUnchanged` - If true then set to unchanged with this call.
      Returns:
        true if the content was changed since last setUnchanged.

    - #### setContentIdent

          long setContentIdent(long ident)

      Sets a identification for the shown data. A widget may not need to refresh if the contentIdent is not changed. A refresh of a widget's content may have side effects in user handling such as selection of text etc. See `getContentIdent()`.
      Parameters:
        `ident` - any number which identifies the value of content.
      Returns:
        the last stored ident.

    - #### getContentIdent

          long getContentIdent()

      Gets the content identification of the users data which are set with `setContentIdent(long)`.

    - #### getContentInfo

          java.lang.Object getContentInfo()

    - #### refreshFromVariable

          void refreshFromVariable(VariableContainer_ifc container)

      Capability for any widget to update its content from its associated variables described in its sDataPath.
      Parameters:
        `container` - The container is used only if the variable is not known by direct reference in the private `GralWidget.variable` or `GralWidget.variables`. If the variable(s) is/are not known, they are searched by there data path set by `setDataPath(String)`. More as one variables are possible separated by "," in the setDataPath("variable1, variable2"). The variables are searched in the container calling `VariableContainer_ifc.getVariable(String)`.

    - #### refreshFromVariable

          void refreshFromVariable(VariableContainer_ifc container,
                                   long timeAtleast,
                                   GralColor colorRefreshed,
                                   GralColor colorOld)