org.vishia.gral.ifc

## Class GralUserAction

- java.lang.Object
- - org.vishia.gral.ifc.GralUserAction

- Direct Known Subclasses:
    ButtonInspcCmd, GralActionJztc.Action, GralActionJztc.ActionRereadScript, GralArea9Window.GralActionFileOpen, GralColorShow.ActionEnterHLS, GralColorShow.ActionEnterHSB, GralWindow.ActionResizeOnePanel

      public abstract class GralUserAction
      extends java.lang.Object

  This Interface should be implemented by any user class to receive any user actions on the graphic. User actions are for example: A button is pressed, a selection is done, a slider is changed or any widget is activated. The interface is a universal one. It is possible to have only one implementation method for some and different widgets with different actions. But it is possible too to implement one method only for a special widget for a special action. The value `GralWidget.sCmd` can be used to determine the action when this method is invoked. This value can be set in the build phase of the GUI to some widgets to have an adequate user action. If a script is used for build, it is the parameter 'cmd=CMD'.
  If a user action should be selected by String in the GUI-Script, it should be supplied by registering before the script runs. This should be done with the method `GralMngBuild_ifc#registerUserAction(String, UserActionGui)`.
  Some widgets can know the same implementing instance. The differencing is done with the `GralWidget` as parameter while calling.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private boolean` | `bCallDeprecated`
    `java.lang.String` | `name` The name of the action on construction, may be used to register, used for debug.
    `static java.lang.String` | `version` Version, history and license.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GralUserAction()` Deprecated. use `GralUserAction(String)` with a name. The name helps while debugging.
    `GralUserAction(java.lang.String ident)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `exec(int actionCode, GralWidget_ifc widgd, java.lang.Object... params)` This method should be override by the users class.
    `java.lang.String` | `toString()` Only for debug, to see what it is.
    `boolean` | `userActionGui(int actionCode, GralWidget widgd, java.lang.Object... params)` Deprecated. use `exec(int, GralWidget_ifc, Object...)` instead. The new method exec works with a `GralWidget_ifc` instead `GralWidget` as reference for parameter and is more universal therefore. The method is deprecated to force usage of only one method type. If any class overrides this method and does not override the non deprecated method, this method is called if the non deprecated method is called. It is for compatibility.
    `boolean` | `userActionGui(java.lang.String sIntension, GralWidget widgd, java.lang.Object... params)` Deprecated. use `#exec(int, GralWidget, Object...)`.

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

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

- - ### Field Detail

    - #### version

          public static final java.lang.String version

      Version, history and license.
      - 2012-07-15 Hartmut new: Constructor with name only for debug (it's nice to have to see anything what it is).
      - 2011-10-23 Hartmut chg: Now it is not an interface but a abstract class with the KeyCode-sensitive method. All implementations yet uses the anonymous class, therefore no changes in its usage. Typical the implementation is a simple inheritance embedded as inner class. Then an abstract class is able to use like a interface. The idea is, don't use the String determined method any more, instead the new method with KeyCode. All calling should call both methods, but the user can implement only one of them. The other returns false. So only the calling places in sources should be adapted for usage yet.
      - 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

    - #### name

          public final java.lang.String name

      The name of the action on construction, may be used to register, used for debug.

    - #### bCallDeprecated

          private boolean bCallDeprecated

  - ### Constructor Detail

    - #### GralUserAction

          public GralUserAction(java.lang.String ident)

    - #### GralUserAction

          @Deprecated
          public GralUserAction()

      Deprecated. use `GralUserAction(String)` with a name. The name helps while debugging.

  - ### Method Detail

    - #### userActionGui

          @Deprecated
          public boolean userActionGui(java.lang.String sIntension,
                                                    GralWidget widgd,
                                                    java.lang.Object... params)

      Deprecated. use `#exec(int, GralWidget, Object...)`.
      Call of users method while a widget is activated. Usual intensions:
      - "ok": The OK-Button or enter-key
      - "key": A key is pressed. Then the key code is contained as Integer in params[0]. The key code follows the convention of `GralKey`.
      - "sliderValue": A slider is changed: params contains a Integer value between 0 and 99.
      - ActionMouseButton: "Button-down", "Button-up", "Button-click"
      - ActionFocused: "Focus-get", "Focus-release"
      - "FileSelector-file": from `GralFileSelector` if a file is entered.
      Parameters:
        `sIntension` - A short string describes the intension of call, means which action is done. This String is generated from the calling routine. It isn't able to set by the user usual, expect if it is parameterized in a specific way. Often the sIntension should not be tested in the users implementation, because the interface is used only for a specific case. But the action should be checked then to detect software errors. With this information the same action method can be used for more as one action type.
        `widgd` - The Gral-widget is given in most cases. It depends some additional static informations about the widget to control the user action.
        `params` - Some optional values, depending on the sIntension.
      Returns:
        true if the user action is done, false if the sIntension or any other parameter doesn't much to that implementation. It is possible to build a queue of user action invocations. The first invocation which returns true may finish the invocations.

    - #### userActionGui

          @Deprecated
          public boolean userActionGui(int actionCode,
                                                    GralWidget widgd,
                                                    java.lang.Object... params)

      Deprecated. use `exec(int, GralWidget_ifc, Object...)` instead. The new method exec works with a `GralWidget_ifc` instead `GralWidget` as reference for parameter and is more universal therefore. The method is deprecated to force usage of only one method type. If any class overrides this method and does not override the non deprecated method, this method is called if the non deprecated method is called. It is for compatibility.
      Parameters:
        `actionCode` -
        `widgd` -
        `params` -
      Returns:

    - #### exec

          public boolean exec(int actionCode,
                              GralWidget_ifc widgd,
                              java.lang.Object... params)

      This method should be override by the users class. In the implementation the user can cast from the widgd given as interface to the known implementation widget type because the `GralUserAction` is associated to a specific widget.
      If this method is not overridden from the `GralUserAction` super class, it tries to call the deprecated `userActionGui(int, GralWidget, Object...)` because that method may be overridden.
      Parameters:
        `actionCode` - See `KeyCode`. Any special action is designated with 0.
        `widgd` - The Gral which calls this method in any of its implementation methods. This parameter designates the source of the call with some specific properties in the widget. For example ((GralWidget)widgd).getCmd() can be invoked.
        `params` - Some optional values, depending on special user designation. In most cases no parameter. The user may be test the type of parameter for complex usage.
      Returns:
        true if execution is succeed. false if the users application can't deal with the actionCode or the widget.

    - #### toString

          public java.lang.String toString()

      Only for debug, to see what it is.
      Overrides:
        `toString` in class `java.lang.Object`
      See Also:
        `Object.toString()`