001 /* 002 Copyright (C) 2001-2002 Renaud Pawlak. <renaud@aopsys.com> 003 004 This program is free software; you can redistribute it and/or modify 005 it under the terms of the GNU Lesser General Public License as 006 published by the Free Software Foundation; either version 2 of the 007 License, or (at your option) any later version. 008 009 This program is distributed in the hope that it will be useful, 010 but WITHOUT ANY WARRANTY; without even the implied warranty of 011 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 012 GNU Lesser General Public License for more details. 013 014 You should have received a copy of the GNU Lesser General Public 015 License along with this program; if not, write to the Free Software 016 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 017 USA */ 018 019 package org.objectweb.jac.core; 020 021 import org.objectweb.jac.core.rtti.*; 022 import java.util.Map; 023 024 /** 025 * This interface is an abstract description of how a display is 026 * defined in org.objectweb.jac. 027 * 028 * <p>In JAC, a GUI that needs to allow aspects to interfere with 029 * itself (with output and input data) must implement this 030 * interface. When the GUI invokes a non-gui object, it must then 031 * define the "Gui.display" attribute to be itself so that internal 032 * component know what display to use. If this display attribute is 033 * not defined by the GUI, then the objects that need display 034 * operations can use the default textual display (that uses 035 * <code>System.out</code> and <code>System.in</code> for output and 036 * input). 037 * 038 * @see org.objectweb.jac.core.Collaboration#get() 039 * @see org.objectweb.jac.core.Collaboration 040 */ 041 042 public interface Display { 043 044 /** 045 * Gets the ID (a unique string identifier) of the current 046 * display. 047 * 048 * @return a string 049 */ 050 String getDisplayID(); 051 052 /** 053 * Sets the ID (a unique string identifier) of the current 054 * display. 055 * 056 * @param displayID a string (should be unique) 057 */ 058 void setDisplayID(String displayID); 059 060 /** 061 * Shows the given object on the display. 062 * 063 * <p>The showed object is considered as a result. 064 * 065 * <p>On contrary to <code>showModal</code>, this method does not 066 * stop the client thread execution. 067 * 068 * @param object the object to show 069 */ 070 void show(Object object); 071 072 /** 073 * Shows a view of an object. 074 * 075 * <p>The showed object is considered as a result. 076 * 077 * <p>On contrary to <code>showModal</code>, this method does not 078 * stop the client thread execution. 079 * 080 * @param object the object to show 081 * @param viewType the type of the view to display 082 * @param viewParams parameters to give the view constructor 083 */ 084 void show(Object object, 085 String viewType, Object[] viewParams); 086 087 /** 088 * Shows the given object on the display by opening a new core 089 * view. 090 * 091 * <p>On contrary to <code>showModal</code>, this method does not 092 * stop the client thread execution. 093 * 094 * @param object the object to show 095 */ 096 void openView(Object object); 097 098 /** 099 * Shows the given object on the display and waits for a user 100 * input. 101 * 102 * <p>On contrary to <code>show</code>, this method stops the 103 * client thread execution and waits for a user input to continue 104 * (as an OK button click or a key pressing). 105 * 106 * @param object the object to show 107 * @param title the window title if a window is opened 108 * @param header a header message 109 * @param parent the parent window 110 * @param canValidate if true, a validation button is added 111 * @param canCancel if true, a cancellation button is added 112 * @param canClose if true, a closing button is added 113 * @return false if the user canceled 114 * 115 * @see #showModal(Object,String,Object[],String,String,Object,boolean,boolean,boolean) 116 */ 117 boolean showModal(Object object, String title, String header, 118 Object parent, 119 boolean canValidate, boolean canCancel, 120 boolean canClose); 121 122 /** 123 * Shows the given object on the display and waits for a user 124 * input. 125 * 126 * @param object the object to show 127 * @param viewType the type of view to build or the object 128 * @param viewParams parameters to give the view constructor 129 * @param title the window title if a window is opened 130 * @param header a header message 131 * @param parent the parent window 132 * @param okButton if true, a validation button is added 133 * @param cancelButton if true, a cancellation button is added 134 * @param closeButton if true, a closing button is added 135 * @return false if the user canceled 136 * 137 * @see #showModal(Object,String,String,Object,boolean,boolean,boolean) 138 */ 139 boolean showModal(Object object, 140 String viewType, Object[] viewParams, 141 String title, String header, 142 Object parent, 143 boolean okButton, boolean cancelButton, 144 boolean closeButton); 145 146 /** 147 * Show a customized Gui. 148 * 149 * @param id the id of the customized GUI to show 150 * @param customized the CustomizedGUI to show 151 * 152 * @see org.objectweb.jac.aspects.gui.CustomizedGUI 153 */ 154 void showCustomized(String id, Object customized); 155 156 /** 157 * Show a customized Gui. 158 * 159 * @param id the id of the customized GUI to show 160 * @param customized the CustomizedGUI to show 161 * @param panels contents of panels ( panelID -> object) 162 * 163 * @see org.objectweb.jac.aspects.gui.CustomizedGUI 164 */ 165 void showCustomized(String id, Object customized, Map panels); 166 167 /** 168 * Rebuilds all customized GUI windows. 169 */ 170 void fullRefresh(); 171 172 /** 173 * Asks the user to fill the parameters to prepare the invocation 174 * of the given method. 175 * 176 * <p>This operation stops the client thread. 177 * 178 * @param object the object that contains the method (null if a 179 * constructor) 180 * @param method the method to fill the parameters o 181 * @param parameters the parameters values; as an input, they can 182 * be set by the client to fill default values for these 183 * parameters; as an output, they must be used by the client as the 184 * actual parameter values to call the given method 185 * @return false if the user canceled 186 */ 187 boolean showInput(Object object, AbstractMethodItem method, 188 Object[] parameters); 189 190 /** 191 * Refresh the display. 192 * 193 * <p>This method is useful for some kind of displays when the 194 * refresh operation cannot be done automatically when the 195 * displayed objects states change (e.g. a web display). 196 * 197 * @see org.objectweb.jac.aspects.gui.web.WebDisplay 198 */ 199 void refresh(); 200 201 /** 202 * Displays a message to the user. 203 * 204 * @param title the window title if a window is opened 205 * @param message a header message 206 * @param canValidate if true, a validation button is added 207 * @param canCancel if true, a cancellation button is added 208 * @param canClose if true, a closing button is added 209 * @return false if the user canceled 210 */ 211 boolean showMessage(String message, String title, 212 boolean canValidate, boolean canCancel, 213 boolean canClose); 214 215 /** 216 * Shows a message to the user. 217 * 218 * @param title the title of the window 219 * @param message the message 220 * 221 * @see #showError(String,String) 222 */ 223 void showMessage(String title, String message); 224 225 /** 226 * Shows a message to the user. 227 * 228 * @param title the title of the window 229 * @param message the message 230 * @return the auto-refreshed window 231 * 232 * @see #showError(String,String) 233 */ 234 Object showRefreshMessage(String title, String message); 235 236 /** 237 * Show an error message to the user. 238 * 239 * @param title the title of the window 240 * @param message the error message 241 * 242 * @see #showMessage(String,String) 243 */ 244 void showError(String title, String message); 245 246 /** 247 * Notifies the display that a new application has just started. 248 * 249 * <p>At this step, all the root objects of the application have 250 * been created and it is time to open the main view if any. */ 251 252 void applicationStarted(); 253 254 /** 255 * Closes this display. 256 */ 257 void close(); 258 259 /** 260 * Called before interactively calling a method with parameters, 261 * so that the display can set some of them. 262 * @return false if there some parameters are still unassigned 263 */ 264 boolean fillParameters(AbstractMethodItem method, Object[] parameters); 265 266 /** 267 * Called after interactively calling a method with parameters. 268 */ 269 void onInvocationReturn(Object substance, AbstractMethodItem method); 270 } 271 272 273