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}