001 /* 002 Copyright (C) 2001-2003 Renaud Pawlak <renaud@aopsys.com>, 003 Laurent Martelli <laurent@aopsys.com> 004 005 This program is free software; you can redistribute it and/or modify 006 it under the terms of the GNU Lesser General Public License as 007 published by the Free Software Foundation; either version 2 of the 008 License, or (at your option) any later version. 009 010 This program is distributed in the hope that it will be useful, 011 but WITHOUT ANY WARRANTY; without even the implied warranty of 012 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 013 GNU Lesser General Public License for more details. 014 015 You should have received a copy of the GNU Lesser General Public License 016 along with this program; if not, write to the Free Software 017 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ 018 019 package org.objectweb.jac.aspects.gui; 020 021 import org.objectweb.jac.core.rtti.*; 022 023 /** 024 * This is the configuration interface of the Gui aspect. 025 * 026 * @see GuiAC 027 * @see View 028 * 029 * @author <a href="mailto:renaud@cnam.fr">Renaud Pawlak</a> 030 * @author <a href="mailto:laurent@aopsys.com">Laurent Martelli</a> 031 */ 032 033 public interface GuiConf 034 extends ClassAppearenceGuiConf, FieldAppearenceGuiConf, 035 MethodAppearenceGuiConf, BehaviorGuiConf { 036 037 /** 038 * Essential method for GUI, which weaves 039 * <code>InputWrapper.askForParameters</code> on all methods with 040 * parameters. 041 * 042 * <p>It permits to dynamically call methods, and so display 043 * something when user clicks on buttons.</p> 044 * 045 * @param classExpr the classes 046 */ 047 void askForParameters(String classExpr); 048 049 /** 050 * This configuration method allows the user to create and register 051 * a new customized GUI. 052 * 053 * <p>A configuration file should first use this method, then 054 * configure the customized GUI, and then call the 055 * <code>showCustomized</code> method when the GUI configuration is 056 * finished. 057 * 058 * @param name the new customized GUI name 059 */ 060 void registerCustomized(String name); 061 062 /** 063 * Sets the icon of the window 064 * @param gui the gui ID 065 * @param icon the name of the icon 066 */ 067 void setCustomizedIcon(String gui, String icon); 068 069 /** 070 * Set an event handler which is called when the window is closed. 071 * @param gui the customized gui ID 072 * @param eventHandler the event handler 073 */ 074 void setOnCloseHandler(String gui, AbstractMethodItem eventHandler); 075 076 /** 077 * Sets a welcome message (in a popup) when a customized GUI is 078 * started. 079 * 080 * @param gui the gui ID 081 * @param title the popup's title 082 * @param message the welcome message 083 * @param icon an icon (defined as a resource) placed before the 084 * message (can be null) */ 085 086 void setWelcomeMessage(String gui,String title, 087 String message,String icon); 088 089 /** 090 * This configuration method allows the programmer to actually show 091 * a status bar in a declared personal UI. 092 * 093 * @param gui the name of the customized GUI 094 * @param method the method that returns the text 095 * @param position UP||BOTTOM */ 096 097 void addStatusBar( String gui, MethodItem method, String position ); 098 099 /** 100 * This configuration method allows the programmer to actually show 101 * an empty status bar in a declared personal UI. The text should 102 * be set with the <code>showStatus</code> method. 103 * 104 * @param gui the name of the customized GUI 105 * @param position UP||BOTTOM 106 * 107 * @see #addStatusBar(String,MethodItem,String) 108 */ 109 void addStatusBar( String gui, String position ); 110 111 /** 112 * This configuration method delegates to 113 * <code>setSubPanesGeometry(int,int,String[])</code> with all the 114 * panes scrollable. 115 * 116 * <p>The GUI must have been declared. 117 * 118 * @param gui the GUI name 119 * @param subPanesCount the number of subpanes in the window 120 * @param geometry the geometry = <code>VERTICAL || HORIZONTAL || 121 * VERTICAL_LEFT || VERTICAL_RIGHT || HORIZONTAL_UP || 122 * HORIZONTAL_DOWN || NONE</code> 123 * 124 * @see #registerCustomized(String) 125 * @see #setSubPanesGeometry(String,int,String,boolean[]) 126 * @see #setPaneContent(String,String,String,String[]) 127 */ 128 void setSubPanesGeometry(String gui, int subPanesCount, String geometry); 129 130 /** 131 * This configuration method delegates to the corresponding 132 * customized GUI. 133 * 134 * <p>The GUI must have been declared. 135 * 136 * @param gui the GUI name 137 * @param subPanesCount the number of subpanes in the window 138 * @param geometry the geometry = <code>VERTICAL || HORIZONTAL || 139 * VERTICAL_LEFT || VERTICAL_RIGHT || HORIZONTAL_UP || 140 * HORIZONTAL_DOWN</code> 141 * @param scrollings a set of string that tells if the sub-panes 142 * must be srollable or not (use setSubPanesGeometry(String,int,String) to 143 * make all the sub-panes scrollable 144 * 145 * @see #registerCustomized(String) 146 * @see #setSubPanesGeometry(String,int,String) 147 * @see #setPaneContent(String,String,String,String[]) 148 */ 149 void setSubPanesGeometry(String gui, int subPanesCount, 150 String geometry, 151 boolean[] scrollings); 152 153 /** 154 * Defines the initial content of a pane. 155 * 156 * <p>The GUI must have been declared. 157 * 158 * @param gui the GUI name 159 * @param paneId the panel id (see the geometry to know its placement) 160 * @param type the type of the view 161 * @param args arguments to pass to the constructor of the view 162 * 163 * @see #registerCustomized(String) 164 * @see #setViewConstructor(String,String,AbstractMethodItem) 165 * @see #setSubPanesGeometry(String,int,String) 166 * @see #setSubPanesGeometry(String,int,String,boolean[]) 167 */ 168 void setPaneContent(String gui, String paneId, String type, String[] args); 169 170 /** 171 * Set the container type to use for a pane. The default is 172 * "SingleSlotContainer". 173 * 174 * @param gui the GUI name 175 * @param paneId the panel id (see the geometry to know its 176 * placement) 177 * @param type the type of the container 178 * 179 * @see #registerCustomized(String) 180 * @see #setViewConstructor(String,String,AbstractMethodItem) 181 */ 182 void setPaneContainer(String gui, String paneId, String type); 183 184 /** 185 * Set a pane to be invalidated (reload) when a given pane content 186 * changes. 187 * 188 * @param gui the GUI name 189 * @param changedPane the pane to watch 190 * @param invalidPane the pane to invalidate when the watched 191 * pane's content changes */ 192 193 void setInvalidPane(String gui, String changedPane, String invalidPane); 194 195 /** 196 * Specify in which pane to open the view of a reference, 197 * collection, or a method's result. The default view for an object 198 * will be used. 199 * 200 * <p>Note that, for a method member, a displayabe object should be 201 * returned by the method. Otherwise, a runtime error will happen. 202 * 203 * @param gui the GUI name 204 * @param member the member (reference, collection, or method) 205 * @param paneId the ID of the pane where the view must be opened 206 * 207 * @see #registerCustomized(String) 208 * @see #addReferenceToPane(String,MemberItem,,String,String[],Boolean,String) 209 */ 210 void addReferenceToPane(String gui, 211 MemberItem member, 212 String paneId); 213 214 /** 215 * This configuration method delegates to the corresponding 216 * customized GUI. 217 * 218 * <p>The GUI must have been declared. 219 * 220 * @param gui the GUI name 221 * @param field the field (reference of collection) 222 * @param viewType the type of the view to open 223 * @param small tell if the viewed object in this pane should be 224 * small 225 * @param panePath the path of the panel where the view must be 226 * opened (<customizedID>/<paneID>) 227 * 228 * @see #registerCustomized(String) 229 * @see #addReferenceToPane(String,MemberItem,String) 230 * @see CustomizedGUI#addReferenceToPane(MemberItem,String,String[],String) 231 */ 232 void addReferenceToPane(String gui, 233 MemberItem field, 234 String viewType, String[] viewParams, 235 Boolean small, 236 String panePath); 237 238 /** 239 * This configuration method delegates to the corresponding 240 * customized GUI. 241 * 242 * <p>The GUI must have been declared. 243 * 244 * @param gui the GUI name 245 * @param left left-border pixel 246 * @param up upper-border pixel 247 * @param width in percentage regarding the screen 248 * @param height in percentage regarding the screen 249 * 250 * @see #registerCustomized(String) 251 * @see CustomizedGUI#setPosition(int,int,int,int) */ 252 253 void setPosition(String gui, int left, int up, 254 int width, int height); 255 256 /** 257 * Sets the position of a menu 258 * @param gui the customized GUI 259 * @param menu the menu name 260 * @param position the position of the menu (TOP, BOTTOM, LEFT or RIGHT) 261 */ 262 void setMenuPosition(String gui, String menu, String position); 263 264 /** 265 * Add a menu item to a menu bar. 266 * 267 * @param gui the GUI name 268 * @param menu the menu name 269 * @param menuPath the path of the menu item. 270 * @param method the callback method for that menu item. It must be 271 * a static method with no arguments. 272 * 273 * @see #registerCustomized(String) 274 * @see #addMenuItem(String,String,String[],String,AbstractMethodItem) 275 * @see #addMenuItem(String,String,String[],String,AbstractMethodItem,String[]) 276 */ 277 void addMenuItem(String gui, String menu, String[] menuPath, 278 AbstractMethodItem method); 279 280 /** 281 * Add a menu item to a menu bar. 282 * 283 * @param gui the GUI name 284 * @param menu the menu name 285 * @param menuPath the path of the menu item. 286 * @param objectName the name of the object on which to invoke the method 287 * @param method the callback method for that menu item. It must be 288 * an instance method with no arguments. 289 * 290 * @see #registerCustomized(String) 291 * @see #addMenuItem(String,String,String[],AbstractMethodItem) 292 * @see #addMenuItem(String,String,String[],AbstractMethodItem,String[]) 293 */ 294 void addMenuItem(String gui, String menu, String[] menuPath, 295 String objectName, AbstractMethodItem method); 296 297 /** 298 * Add a menu item to a menu bar. 299 * 300 * @param gui the GUI name 301 * @param menu the menu name 302 * @param menuPath the path of the menu item. 303 * @param method the callback method for that menu item. It must be 304 * a static method. 305 * @param parameters the arguments to pass to the callback method 306 * when it is called 307 * 308 * @see #registerCustomized(String) 309 * @see #addMenuItem(String,String,String[],AbstractMethodItem) 310 * @see #addMenuItem(String,String,String[],String,AbstractMethodItem) 311 * @see #addMenuItem(String,String,String[],String,AbstractMethodItem,String[]) 312 */ 313 void addMenuItem(String gui, String menu, String[] menuPath, 314 AbstractMethodItem method, String[] parameters); 315 316 /** 317 * Add a menu item to a menu bar. 318 * 319 * @param gui the GUI name 320 * @param menu the menu name 321 * @param menuPath the path of the menu item. 322 * @param objectName the name of the object on which to invoke the method 323 * @param method the callback method for that menu item. It must be 324 * an instance method. 325 * @param parameters the arguments to pass to the callback method 326 * when it is called 327 * 328 * @see #registerCustomized(String) 329 * @see #addMenuItem(String,String,String[],AbstractMethodItem) 330 * @see #addMenuItem(String,String,String[],AbstractMethodItem,String[]) 331 * @see #addMenuItem(String,String,String[],String,AbstractMethodItem) 332 */ 333 void addMenuItem(String gui, String menu, String[] menuPath, 334 String objectName, AbstractMethodItem method, 335 String[] parameters); 336 337 /** 338 * Add a separator in a menu. 339 * 340 * @param gui the GUI name 341 * @param menuPath the path of the menu item separator. 342 * 343 * @see #registerCustomized(String) 344 */ 345 void addMenuSeparator(String gui, String menu, String[] menuPath); 346 347 /** 348 * Set the icon for a menu. 349 * @param gui the GUI name 350 * @param menuPath the path of the menu 351 * @param icon the name of the icon 352 * 353 * @see #registerCustomized(String) 354 */ 355 void setMenuIcon(String gui, String menu, String[] menuPath, String icon); 356 357 /** 358 * Add a button in the toolbar 359 * 360 * @param gui the GUI name 361 * @param method the callback method for that button. It must be a 362 * static method with no arguments. 363 * 364 * @see #addToolbarAction(String,String,AbstractMethodItem) 365 * @see #registerCustomized(String) 366 */ 367 368 void addToolbarAction(String gui,AbstractMethodItem method); 369 370 371 /** 372 * Add a button in the toolbar 373 * 374 * @param gui the GUI name 375 * @param objectName name of the object on which to invoke the method 376 * @param method the callback method for that button. It must be a 377 * static method with no arguments. 378 * 379 * @see #addToolbarAction(String,AbstractMethodItem) 380 * @see #registerCustomized(String) 381 */ 382 383 void addToolbarAction(String gui,String objectName,AbstractMethodItem method); 384 385 /** 386 * Add a separator in the toolbar 387 * 388 * @param gui the GUI name 389 * 390 * @see #registerCustomized(String) 391 */ 392 void addToolbarSeparator(String gui); 393 394 /** 395 * This configuration method delegates to the corresponding 396 * customized GUI. 397 * 398 * <p>The GUI must have been declared. 399 * 400 * @param gui the GUI name 401 * @param splitterId the splitter's index 402 * @param location the position as a percentage between 0 and 1, 403 * regarding to the top/left component, a negative value means that 404 * the splitter should be set at the preferred sized of the inner 405 * components 406 * @see #registerCustomized(String) 407 * @see CustomizedGUI#setSplitterLocation(int,float) */ 408 409 void setSplitterLocation( String gui, int splitterId, float location ); 410 411 /** 412 * This configuration method sets the title of the GUI main window. 413 * 414 * <p>The GUI must have been declared. 415 * 416 * @param gui the GUI name 417 * @param title the window title 418 * @see #registerCustomized(String) 419 */ 420 void setTitle(String gui, String title); 421 422 /** 423 * Sets the given methods to be logging. 424 * 425 * <p>When it is called, the argument --- that must be a string --- 426 * is written into a text area added at the end of a subpanel 427 * defined by a customized GUI. 428 * 429 * @param gui the customized gui (must be registered and 430 * configured with at least <code>setSubPanesGeometry</code>) 431 * @param objects the objects that contain the method (pointcut expression) 432 * @param classes the class the contains the method (pointcut expression) 433 * @param methods the method item names (pointcut expression) 434 * @param paneId the subpanel id 435 * @see #registerCustomized(String) 436 * @see #setSubPanesGeometry(String,int,String) 437 */ 438 void setLoggingMethod(String gui, 439 String objects, String classes, String methods, 440 int paneId); 441 442 /** 443 * This configuration method allows the user to define new 444 * resources that can be used by the GUI later-on. 445 * 446 * @param type the resource type (ICON) -- other types should be 447 * supported soon 448 * @param name the identifier of the resource (should be unique) 449 * @param path the path where the resource is located (can be 450 * classpath relative) 451 * @see #setIcon(ClassItem,String) 452 */ 453 void defineResource(String type, String name, String path ); 454 455 /** 456 * This configuration method allows the programmer to define 457 * attributes for the default font. It currently is only used by 458 * the swing display. 459 * 460 * <p>The specified font will be used by all the UI components. 461 * 462 * <p>Note: this method sets a global font that will be active for 463 * all the configured GUIs. It is not possible to have different 464 * font configurations when running several GUIs on the same 465 * container. 466 * 467 * <p>Configurable font attributes are:</p> 468 * <dl> 469 * <dt>family</dt><dd>serif,sans-serif or monospace</dd> 470 * <dt>weight</dt><dd>normal or bold</dd> 471 * <dt>style</dt><dd>normal or italic</dd> 472 * <dt>size</dt><dd>the size of the font</dd> 473 * </dl> 474 * 475 * @param attribute the name of the attribute 476 * @param value the value for the attribute 477 */ 478 void setFontAttribute( String attribute, String value ); 479 480 /** 481 * Adds a style-sheet URL for the generated html pages (for WEB 482 * GUIs). 483 * 484 * <p>By default, the style-sheets are the one defined in the 485 * org/objectweb/jac/aspects/gui/web directory but the user can override some of 486 * their characteristics by adding customized ones (last added 487 * overrides) 488 * 489 * @param gui the customized GUI the style sheets applies to 490 * @param url the URL string 491 * @see #addStyleSheetURL(String) 492 */ 493 void addStyleSheetURL(String gui, String url); 494 495 /** 496 * Adds a style-sheet URL for the generated html pages (for WEB 497 * GUIs). 498 * 499 * @param url the URL string 500 * @see #addStyleSheetURL(String,String) 501 */ 502 void addStyleSheetURL(String url); 503 504 /** 505 * Sets the delay before a dialog times out. Dialogs only time out 506 * on the web GUI, to avoid locking threads on the server for ever. 507 * @param timeout the timeout delay in milliseconds 508 */ 509 void setDialogTimeout(long timeout); 510 511 /** 512 * Set the default currency 513 * 514 * @param currencyName the name of the default currency 515 * @param precision number of decimals to display 516 */ 517 void setDefaultCurrency(String currencyName, int precision); 518 519 /** 520 * Declare a currency and it's change rate with the default currency 521 * 522 * @param currencyName the name of currency 523 * @param precision number of decimals to display for the currency 524 * @param rate the change rate for the currency 525 */ 526 void declareCurrency( String currencyName, int precision, double rate); 527 528 529 /** 530 * Set the view constructor for a given gui type. 531 * @param guiType the type of the gui ("swing","web",...) 532 * @param viewType the type of the view 533 * @param constructor the view constructor for this gui type and view type 534 */ 535 void setViewConstructor(String guiType, 536 String viewType, 537 AbstractMethodItem constructor); 538 539 540 /** 541 * Set the default date format used by date components. It must be 542 * a valid format as defined by java.text.SimpleDateFormat 543 * 544 * @param dateFormat the date format 545 * @see java.text.SimpleDateFormat 546 */ 547 void setDateFormat(String dateFormat); 548 549 /** 550 * Define an enumeration. It associates integer values with strings. 551 * 552 * @param name the name of enumeration to define 553 * @param values the labels of the values 554 * @param start the integer value of the first item. 555 * @param step 556 * 557 * @see FieldAppearenceGuiConf#setFieldEnum(FieldItem,String) 558 * @see FieldAppearenceGuiConf#setFieldChoice(FieldItem,Boolean,String[]) 559 */ 560 void defineEnum(String name, String[] values, int start, int step); 561 562 /** 563 * Enables navigation bar for a collection. <p> Navigation bar is a 564 * set of buttons (previous element, next element, remove element) 565 * used to navigate in a collection 566 * 567 * @param gui the gui 568 * @param collection the collection 569 */ 570 void setNavBar(String gui, CollectionItem collection); 571 572 void setLabelOK(String label); 573 void setLabelCancel(String label); 574 void setLabelNew(String label); 575 void setLabelAdd(String label); 576 void setLabelNone(String label); 577 void setLabelAll(String label); 578 579 /** 580 * Sets the default charset encoding to use when interaction with 581 * the user's terminal. Defaults to "UTF-8". Used by the WEB 582 * diplay. 583 * 584 * @param encoding the charset encoding 585 * 586 * @see java.nio.charset.Charset 587 */ 588 void setEncoding(String encoding); 589 } 590