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