    001package org.vishia.gral.ifc;
    002
    003import org.vishia.gral.base.GralWidget;
    004import org.vishia.gral.widget.GralFileSelector;
    005import org.vishia.util.Assert;
    006import org.vishia.util.KeyCode;
    007
    008
    009/**This Interface should be implemented by any user class to receive any user actions on the graphic.
    010 * User actions are for example: A button is pressed,
    011 * a selection is done, a slider is changed or any widget is activated.
    012 * The interface is a universal one. It is possible to have only one implementation method
    013 * for some and different widgets with different actions. But it is possible too to implement one method only
    014 * for a special widget for a special action. The value {@link GralWidget#sCmd} can be used to determine
    015 * the action when this method is invoked. This value can be set in the build phase
    016 * of the GUI to some widgets to have an adequate user action. If a script is used for build, it is the
    017 * parameter 'cmd=<i>CMD</i>'.
    018 * <br><br>
    019 * If a user action should be selected by String in the GUI-Script, it should be supplied by registering
    020 * before the script runs.
    021 * This should be done with the method {@link GralMngBuild_ifc#registerUserAction(String, UserActionGui)}.
    022 * <br><br>
    023 * Some widgets can know the same implementing instance. The differencing is done with the {@link GralWidget}
    024 * as parameter while calling.
    025 * <br><br>
    026 */
    027public abstract class GralUserAction
    028{
    029  /**Version, history and license.
    030   * <ul>
    031   * <li>2012-07-15 Hartmut new: Constructor with name only for debug (it's nice to have to see anything what it is).
    032   * <li>2011-10-23 Hartmut chg: Now it is not an interface but a abstract class with the KeyCode-sensitive method.
    033   *   All implementations yet uses the anonymous class, therefore no changes in its usage.
    034   *   Typical the implementation is a simple inheritance embedded as inner class.
    035   *   Then an abstract class is able to use like a interface.
    036   *   The idea is, don't use the String determined method any more, instead the new method with KeyCode.
    037   *   All calling should call both methods, but the user can implement only one of them. The other returns false.
    038   *   So only the calling places in sources should be adapted for usage yet.
    039   * <li>2011-06-00 Hartmut created
    040   * </ul>
    041   *
    042   * <b>Copyright/Copyleft</b>:<br>
    043   * For this source the LGPL Lesser General Public License,
    044   * published by the Free Software Foundation is valid.
    045   * It means:
    046   * <ol>
    047   * <li> You can use this source without any restriction for any desired purpose.
    048   * <li> You can redistribute copies of this source to everybody.
    049   * <li> Every user of this source, also the user of redistribute copies
    050   *    with or without payment, must accept this license for further using.
    051   * <li> But the LPGL is not appropriate for a whole software product,
    052   *    if this source is only a part of them. It means, the user
    053   *    must publish this part of source,
    054   *    but doesn't need to publish the whole source of the own product.
    055   * <li> You can study and modify (improve) this source
    056   *    for own using or for redistribution, but you have to license the
    057   *    modified sources likewise under this LGPL Lesser General Public License.
    058   *    You mustn't delete this Copyright/Copyleft inscription in this source file.
    059   * </ol>
    060   * If you intent to use this source without publishing its usage, you can get
    061   * a second license subscribing a special contract with the author.
    062   *
    063   * @author Hartmut Schorrig = hartmut.schorrig@vishia.de
    064   */
    065  public static final String version = "2015-08-05";
    066
    067  /**The name of the action on construction, may be used to register, used for debug. */
    068  public final String name;
    069
    070  private boolean bCallDeprecated;
    071
    072  public GralUserAction(String ident){ name = ident; }
    073
    074  /**
    075   * @deprecated use {@link #GralUserAction(String)} with a name. The name helps while debugging.
    076   */
    077  @Deprecated
    078  public GralUserAction(){
    079    CharSequence info = Assert.stackInfo("", 2, 1);
    080    System.out.printf("GralUserAction - without name; %s;\n", info);
    081    name = "";
    082  }
    083
    084  /**Call of users method while a widget is activated.
    085   * Usual intensions:
    086   * <ul>
    087   * <li>"ok": The OK-Button or enter-key
    088   * <li>"key": A key is pressed. Then the key code is contained as Integer in params[0].
    089   *            The key code follows the convention of {@link GralKey}.
    090   * <li>"sliderValue": A slider is changed: params contains a Integer value between 0 and 99.
    091   * <li>ActionMouseButton: "Button-down", "Button-up", "Button-click"
    092   * <li>ActionFocused: "Focus-get", "Focus-release"
    093   * <li>"FileSelector-file": from {@link GralFileSelector} if a file is entered.
    094   * </ul>
    095   * @param sIntension A short string describes the intension of call, means which action is done.
    096   *        This String is generated from the calling routine.
    097   *        It isn't able to set by the user usual, expect if it is parameterized in a specific way.
    098   *        Often the sIntension should not be tested in the users implementation,
    099   *        because the interface is used only for a specific case. But the action should be checked
    100   *        then to detect software errors.
    101   *        With this information the same action method can be used for more as one action type.
    102   * @param widgd The Gral-widget is given in most cases. It depends some additional static informations
    103   *        about the widget to control the user action.
    104   * @param params Some optional values, depending on the sIntension.
    105   * @return true if the user action is done, false if the sIntension or any other parameter
    106   *        doesn't much to that implementation. It is possible to build a queue of user action invocations.
    107   *        The first invocation which returns true may finish the invocations.
    108   * @deprecated use {@link #exec(int, GralWidget, Object...)}.
    109   */
    110  @Deprecated public boolean userActionGui(String sIntension, GralWidget widgd, Object... params){ return false; }
    111
    112  /**@deprecated use {@link #exec(int, GralWidget_ifc, Object...)} instead.
    113   * The new method exec works with a {@link GralWidget_ifc} instead {@link GralWidget} as reference for parameter
    114   * and is more universal therefore. The method is deprecated to force usage of only one method type.
    115   * If any class overrides this method and does not override the non deprecated method, this method is called
    116   * if the non deprecated method is called. It is for compatibility.
    117   * @param actionCode
    118   * @param widgd
    119   * @param params
    120   * @return
    121   */
    122  @Deprecated
    123  public boolean userActionGui(int actionCode, GralWidget widgd, Object... params){
    124    if(bCallDeprecated) return false;
    125    else return exec(actionCode, widgd, params);
    126  }
    127
    128
    129
    130
    131
    132  /**This method should be override by the users class.
    133   * In the implementation the user can cast from the widgd given as interface to the known implementation widget type
    134   * because the {@link GralUserAction} is associated to a specific widget.
    135   * <br><br>
    136   * If this method is not overridden from the {@link GralUserAction} super class, it tries to call
    137   * the deprecated {@link #userActionGui(int, GralWidget, Object...)} because that method may be overridden.
    138   *
    139   * @param actionCode See {@link KeyCode}. Any special action is designated with 0.
    140   * @param widgd The Gral which calls this method in any of its implementation methods.
    141   *   This parameter designates the source of the call with some specific properties in the widget.
    142   *   For example ((GralWidget)widgd).getCmd() can be invoked.
    143   * @param params Some optional values, depending on special user designation. In most cases no parameter.
    144   *   The user may be test the type of parameter for complex usage.
    145   * @return true if execution is succeed. false if the users application can't deal with the actionCode or the widget.
    146   */
    147  public boolean exec(int actionCode, GralWidget_ifc widgd, Object... params){
    148    bCallDeprecated = true; //prevent recursively.
    149    if(widgd == null || (widgd instanceof GralWidget)){
    150      return userActionGui(actionCode, (GralWidget)widgd, params);  //call this method, it may be overridden.
    151    } else {
    152      //try to call
    153      return userActionGui(actionCode, null, params);  //call this method, it may be overridden.
    154    }
    155  }
    156
    157
    158  /**Only for debug, to see what it is.
    159   * @see java.lang.Object#toString()
    160   */
    161  @Override public String toString(){ return name; }
    162
    163}