org.vishia.gral.base

## Class GralTextField

- java.lang.Object
- - org.vishia.gral.base.GralWidget
  - - org.vishia.gral.base.GralTextField

- All Implemented Interfaces:
    GetGralWidget_ifc, GralSetValue_ifc, GralTextField_ifc, GralWidget_ifc, Removeable
  Direct Known Subclasses:
    GralTextBox

      public class GralTextField
      extends GralWidget
      implements GralTextField_ifc

  This is the base class for all widgets which represents a simple text.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `private static class` | `GralTextField.CalculatorAngle16`
    `private static class` | `GralTextField.CalculatorAngle32`
    `class` | `GralTextField.GraphicImplAccess`
    `static class` | `GralTextField.Type`

    - ### Nested classes/interfaces inherited from class org.vishia.gral.base.GralWidget

      `GralWidget.ActionChangeSelect, GralWidget.ConfigData, GralWidget.DynamicData, GralWidget.ImplAccess`

    - ### Nested classes/interfaces inherited from interface org.vishia.gral.ifc.GralWidget_ifc

      `GralWidget_ifc.ActionChange, GralWidget_ifc.ActionChangeWhen`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected int` | `borderwidth` The width of an extra border arround the text field to mark it. 0: initially, no border.
    `(package private) boolean` | `bPassword`
    `private CalculatorExpr` | `calculator` A calculator to show calculated float values.
    `protected int` | `caretPos`
    `protected GralKeyListener` | `gralKeyListener`
    `private java.lang.String` | `sFormat2`
    `protected java.lang.String` | `sPrompt` The prompt to the text field.
    `protected java.lang.String` | `sPromptStylePosition` The prompt to the text field.
    `protected GralTextFieldUser_ifc` | `user`
    `static java.lang.String` | `version` Version, history and license .
    `protected GralGraphicThread` | `windowMng` It is used for some operations.

    - ### Fields inherited from class org.vishia.gral.base.GralWidget

      `_wdgImpl, bEditable, bHasFocus, bShouldInitialize, buildMng, bVisibleState, cfg, contextMenu, dateUser, dyda, htmlHelp, itsMng, lastTimeSetVisible, name, repaintDelay, repaintDelayMax, sCmd, sFormat, sToolTip, sVersion, whatIs`

    - ### Fields inherited from interface org.vishia.gral.ifc.GralWidget_ifc

      `sVersion`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GralTextField(java.lang.String name, char whatis, GralMng mng)` Deprecated.
    `GralTextField(java.lang.String posName, GralTextField.Type... property)` Constructs a text field with given properties
    `GralTextField(java.lang.String pos, java.lang.String name, GralTextField.Type... property)` Deprecated. since 2016-09,use `GralTextField(String, Type...)` with "@pos=name"

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `getCursorPos()`
    `java.lang.String` | `getPromptLabelImpl()` Returns the Label for a prompt or null if there isn't used a prompt
    `java.lang.String` | `getValue()` Gets the current value of the text field thread-independent.
    `int` | `setBorderWidth(int width)` Sets a new border width and returns the old one.
    `int` | `setCursorPos(int pos)`
    `void` | `setFormat(java.lang.String sFormat)`
    `void` | `setLongValue(long valueP)` Sets a long value into a text field.
    `void` | `setPrompt(java.lang.String sPrompt)`
    `void` | `setPrompt(java.lang.String sPrompt, java.lang.String sPromptPos)`
    `void` | `setText(java.lang.CharSequence arg)` Set the text of the widget.
    `void` | `setText(java.lang.CharSequence arg, int caretPos)` Sets the textual content.
    `void` | `setTextStyle(GralColor color, GralFont font)` Sets the style of all new set and added texts.
    `void` | `setUser(GralTextFieldUser_ifc user)`
    `void` | `setValue(double valueP)` Sets a float value into a text field.
    `void` | `setValue(float valueP)` Sets a float value into a text field.
    `void` | `setValue(java.lang.Object[] value)` Sets some value to show any content.

    - ### Methods inherited from class org.vishia.gral.base.GralWidget

      `chgPos, clearShowParam, createImplWidget_Gthread, getActionChange, getActionChangeStrict, getActionDrag, getActionDrop, getActionFocused, getActionShow, getBackColor, getCfgElement, getCmd, getCmd, getContentIdent, getContentInfo, getContextMenu, getData, getDataIx, getDataPath, getDataPath, getFloatValue, getFormat, getGralWidget, getHtmlHelp, getImpl, getItsPanel, getLongValue, getName, getShowMethod, getShowParam, getsToolTip, getText, getVariable, getVariableFromContentInfo, gralMng, isChanged, isEditable, isGraphicDisposed, isInFocus, isNotEditableOrShouldInitialize, isVisible, pos, refreshFromVariable, refreshFromVariable, registerWidget, remove, repaint, repaint, requestNewValueForVariable, setActionChange, setActionFocused, setActionMouse, setActionShow, setBackColor, setBackgroundColor, setBoundsPixel, setCfgElement, setCmd, setContentIdent, setContentInfo, setData, setDataIx, setDataPath, setDragEnable, setDropEnable, setEditable, setFocus, setFocus, setForegroundColor, setHtmlHelp, setLineColor, setMinMax, setPanelMng, setPrimaryWidgetOfPanel, setTextColor, setToolTip, setToPanel, setValue, setValue, setVisible, setVisibleState, setVisibleStateWidget, specifyActionChange, specifyContextMenu, stop, toString, XXXgetPixelPositionSize, XXXgetWidgetImplementation, XXXremoveWidgetImplementation, XXXrepaintGthread, XXXsetFocusGThread, XXXsetVisibleGThread`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface org.vishia.gral.ifc.GralTextField_ifc

      `getText`

    - ### Methods inherited from interface org.vishia.gral.ifc.GralWidget_ifc

      `createImplWidget_Gthread, getActionChange, getBackColor, getCmd, getContentIdent, getContentInfo, getData, getDataPath, getName, gralMng, isChanged, isEditable, isGraphicDisposed, isInFocus, isNotEditableOrShouldInitialize, isVisible, refreshFromVariable, refreshFromVariable, repaint, repaint, setBackColor, setBackgroundColor, setBoundsPixel, setCmd, setContentIdent, setData, setDataPath, setEditable, setFocus, setFocus, setForegroundColor, setHtmlHelp, setLineColor, setTextColor, setToPanel, setVisible`

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

      `remove`

- - ### Field Detail

    - #### version

          public static final java.lang.String version

      Version, history and license .
      - 2015-05-04 Hartmut new: `setBorderWidth(int)` to show the text field with a border.
      - 2015-05-04 Hartmut chg: `setLongValue(long)` is more complexly, a calculation can result in a float value. Fixed.
      - 2015-05-02 Hartmut chg: Calculation of the `GralTextField.GraphicImplAccess.posPrompt` and ...posField is processed in this class commonly for SWT and AWT implementation.
      - 2014-02-10 Hartmut chg: Constructor with Parameter `GralTextField.Type`, supports password field.
      - 2013-12-22 Hartmut chg: Now `GralTextField` uses the new concept of instantiation: It is not the super class of the implementation class. But it provides `GralTextField.GraphicImplAccess` as the super class.
      - 2013-03-13 Hartmut new `setText(CharSequence, int)`: supports `GralWidget_ifc.isNotEditableOrShouldInitialize()` to support edit field handling.
      - 2013-03-04 Hartmut chg: The `setText(CharSequence, int)` overwriting concept is faulty. Because an accidentally change of text prevents setting the correct text. Check of `#bTextChg` removed. The preventing of overwriting an edit field should be prevented outside as condition of call of `setText(CharSequence)`.
      - 2013-02-22 GralTextField: edit field now works with GralShowMethods syncVariableOnFocus, `#bTextChg` detects whether any input is taken. `GralWidget.isChanged(boolean)` returns this information and resets `#bTextChg`. `setText(CharSequence, int)` only sets if the text is unchanged. Therefore a changed text won't be over-written by an setText().
      - 2012-09-24 Hartmut new: `setValue(double)` and `setValue(Object[])` for double values.
      - 2012-04-17 Hartmut new: `sFormat2` etc: Now format "int16AngleDegree" etc. are recognized as special format. Improved calling `calculator` in `setValue(float)`.
      - 2012-04-16 Hartmut new: `#isChanged()`, `setUser(GralTextFieldUser_ifc)`
      - 2012-04-01 Hartmut new: `setValue(float)` now supports formatting view. This algorithm was used for the `InspcGui` before.
      - 2011-11-18 Hartmut new `#setMouseAction(GralUserAction)`. This method should be an abstract method of all `GralWidget` but it is used yet only here.
      - 2011-09-00 Hartmut Creation to build a platform-indenpenden representation of text field.
      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 ist 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 don'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 are intent to use this sources without publishing its usage, you can get a second license subscribing a special contract with the author.
      See Also:
        Constant Field Values

    - #### caretPos

          protected int caretPos

    - #### borderwidth

          protected int borderwidth

      The width of an extra border arround the text field to mark it. 0: initially, no border. Note: The color of the border is the `GralWidget.DynamicData.lineColor`

    - #### sPrompt

          protected java.lang.String sPrompt

      The prompt to the text field.

    - #### sPromptStylePosition

          protected java.lang.String sPromptStylePosition

      The prompt to the text field.

    - #### calculator

          private CalculatorExpr calculator

      A calculator to show calculated float values. It is null if it isn't used.

    - #### sFormat2

          private java.lang.String sFormat2

    - #### user

          protected GralTextFieldUser_ifc user

    - #### windowMng

          protected final GralGraphicThread windowMng

      It is used for some operations.

    - #### bPassword

          final boolean bPassword

    - #### gralKeyListener

          protected GralKeyListener gralKeyListener

  - ### Constructor Detail

    - #### GralTextField

          public GralTextField(java.lang.String posName,
                               GralTextField.Type... property)

      Constructs a text field with given properties
      Parameters:
        `posName` - Position and Name of the field. Maybe null if it is not need in management by name See `GralWidget.GralWidget(String, char)`.
        `property` - password, editable, maybe left empty.

    - #### GralTextField

          public GralTextField(java.lang.String pos,
                               java.lang.String name,
                               GralTextField.Type... property)

      Deprecated. since 2016-09,use `GralTextField(String, Type...)` with "@pos=name"
      Constructs a text field with given properties
      Parameters:
        `name` - Name of the field. Maybe null if it is not need in management by name
        `property` - password, editable, maybe left empty.

    - #### GralTextField

          @Deprecated
          public GralTextField(java.lang.String name,
                                            char whatis,
                                            GralMng mng)

      Deprecated.

  - ### Method Detail

    - #### setPrompt

          public void setPrompt(java.lang.String sPrompt)

    - #### setPrompt

          public void setPrompt(java.lang.String sPrompt,
                                java.lang.String sPromptPos)

    - #### setUser

          public void setUser(GralTextFieldUser_ifc user)

    - #### setFormat

          public void setFormat(java.lang.String sFormat)

      Overrides:
        `setFormat` in class `GralWidget`

    - #### setValue

          public void setValue(float valueP)

      Sets a float value into a text field. The float value may be calculated and formatted:
      - If the `setFormat(String)` of this widget starts with '!' and contains a second '!', the String between that is used as expression to calculate the float value using `CalculatorExpr`. Therewith any calculation can be done.
      - The rest after the "!expression!" or the given format is used for String.format(sFormat, value) to determine the output appearance.
      - If no format is given, the value will be shown in proper readable appearance. That assures that the value is able to present in a short text field, using maximal 9 digits.
      - If no format is given and the absolute of the value is less 0.000001 but not 0, a "0.000001" with the correct sign will be shown. It shows, there is a less value, but not null.
      - If no format is given and the value is in range up to 1 Billion, it is shown with "k", "M" for kilo and Mega with max 3 digits before dot and 3 digits after the dot.
      - if no format is given and the value is greater than 1 Billion, it is shown with exponent.
      Specified by:
        `setValue` in interface `GralSetValue_ifc`
      Overrides:
        `setValue` in class `GralWidget`
      Parameters:
        `valueP` - This routine may be overridden by some specialized widgets.
      See Also:
        `GralWidget.setValue(float)`

    - #### setLongValue

          public void setLongValue(long valueP)

      Sets a long value into a text field. The long value may be calculated and may be formatted:
      - If the `setFormat(String)` of this widget starts with '!' and contains a second '!', the String between that is used as expression to calculate the long value using `CalculatorExpr`. Therewith any calculation can be done. The result may be a float or double.
      - The rest after the "!expression!" or the given format is used for String.format(sFormat, value) to determine the output appearance.
      - If The sFormat has the form "!16lo!expr!format" ("!16lo" as prefix), then additional to the expression the 16 lo-Bits are filtered firstly. Adequate starting with "!!16hi.." filteres the Bits 31..16 to bit 15..0 before calculate the expression. This is especially if 2 * 16 bit for different values are accessed in one 32 bit address position of an processor which can only access 32 bit.
      - As special feature a format `int32AngleDegree` and `int16AngleDegree` is supported, if that text is contained in the format string. The value should come from an integer, which contains an angle value with wrap-around-presentation: 0x7fffffff (32 bit) or 0x7fff (16 bit) and 0x80000000 which is exactly 180 degree. This format helps to calculate with angle values in range of -180...+179.99999 degree. The presentation in the text field is shown as degree angle value.
      - If no format is given, the value will be shown as normal decimal long value.
      Specified by:
        `setLongValue` in interface `GralSetValue_ifc`
      Overrides:
        `setLongValue` in class `GralWidget`
      Parameters:
        `valueP` - This routine may be overridden by some specialized widgets.
      See Also:
        `GralWidget.setValue(float)`

    - #### setValue

          public void setValue(double valueP)

      Sets a float value into a text field. The float value may be formatted:
      - If the `setFormat(String)` of this widget starts with '!' and contains a second '!', the String between that is used as expression to calculate the float value using `CalculatorExpr`. Therewith any calculation can be done.
      - The rest after the "!expression!" or the given format is used for String.format(sFormat, value) to determine the output appearance.
      - If no format is given, the value will be shown in proper readable appearance. That assures that the value is able to present in a short text field, using maximal 9 digits.
      - If no format is given and the absolute of the value is less 0.000001 but not 0, a "0.000001" with the correct sign will be shown. It shows, there is a less value, but not null.
      - If no format is given and the value is in range up to 1 Billion, it is shown with "k", "M" for kilo and Mega with max 3 digits before dot and 3 digits after the dot.
      - if no format is given and the value is greater than 1 Billion, it is shown with exponent.
      See Also:
        `GralWidget.setValue(float)`

    - #### setValue

          public void setValue(java.lang.Object[] value)

      Description copied from class: `GralWidget`
      Sets some value to show any content.
      Specified by:
        `setValue` in interface `GralSetValue_ifc`
      Overrides:
        `setValue` in class `GralWidget`
      Parameters:
        `value` - This routine may be overridden by some specialized widgets.

    - #### setText

          public void setText(java.lang.CharSequence arg)

      Description copied from interface: `GralWidget_ifc`
      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 `GralWidget_ifc.setBackColor(GralColor, int)` etc.
      With the set methods the user stores the text, color etc. in graphic-independent attributes. Then the method `GralWidget_ifc.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.
      Specified by:
        `setText` in interface `GralSetValue_ifc`
      Specified by:
        `setText` in interface `GralTextField_ifc`
      Specified by:
        `setText` in interface `GralWidget_ifc`
      Overrides:
        `setText` in class `GralWidget`
      Parameters:
        `arg` - The content

    - #### setText

          public void setText(java.lang.CharSequence arg,
                              int caretPos)

      Sets the textual content. This method sets the text and invokes a `GralWidget.repaint(int, int)` in 100 ms if the content is changed in another thread than the graphical thread. It invokes a `#repaintGthread()` if the content was changed in the graphical thread. Note: If the current content is equals with the new one, a repaint request is not forced. Therewith the cursor can be positioned inside. But if the content is changed, it is set with this given one.
      Specified by:
        `setText` in interface `GralTextField_ifc`
      Parameters:
        `arg` - The text to show in the widget.
        `caretPos` - 0 for left, -1 for right, 0 to Integer.MAXINT for a given position. If the caret position is greater then the number of chars, it is set right. That character which is left from the caret position is shown guaranteed in the text field. Especially -1 can be given to show the text right-aligned.
      See Also:
        `GralTextField_ifc.setText(java.lang.CharSequence, int)`

    - #### getValue

          public java.lang.String getValue()

      Gets the current value of the text field thread-independent. It is the value stored in the `GralWidget.DynamicData.displayedText` which is updated while typing the text or if the focus is changed (depending on implementation).
      Overrides:
        `getValue` in class `GralWidget`
      Returns:
        The value in String representation.

    - #### getCursorPos

          public int getCursorPos()

      Specified by:
        `getCursorPos` in interface `GralTextField_ifc`

    - #### setCursorPos

          public int setCursorPos(int pos)

      Specified by:
        `setCursorPos` in interface `GralTextField_ifc`

    - #### setTextStyle

          public void setTextStyle(GralColor color,
                                   GralFont font)

      Description copied from interface: `GralTextField_ifc`
      Sets the style of all new set and added texts. The content contained in the text field or box are not changed.
      Specified by:
        `setTextStyle` in interface `GralTextField_ifc`

    - #### setBorderWidth

          public int setBorderWidth(int width)

      Sets a new border width and returns the old one. If the width is the same as the old one, nothing else is done. If the widht is another, a repaint request is registered to show it in graphic. This routine can be invoked in any thread.
      Parameters:
        `width` - 0: No border, 1... number of pixel for border.
      Returns:
        last width to quest, store and restore.

    - #### getPromptLabelImpl

          public final java.lang.String getPromptLabelImpl()

      Returns the Label for a prompt or null if there isn't used a prompt