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}