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 configuration interface of the Gui aspect defines all the
025     * methods that handle some behavioral configurations of the widgets.
026     *
027     * @see GuiAC
028     * @see View
029     *
030     * @author <a href="mailto:renaud@cnam.fr">Renaud Pawlak</a>
031     * @author <a href="mailto:laurent@aopsys.com">Laurent Martelli</a> */
032    
033    public interface BehaviorGuiConf {
034    
035       /**
036        * This configuration method tells the GUI to automatically create
037        * a new instance of the field type when a setter or an adder is
038        * invoke on the object that owns this field.
039        *
040        * <p>This features makes the GUI more usable in many cases
041        * (otherwhise, a intermediate step is asked to the user for
042        * creating or picking an existing instance).
043        *
044        * @param field the field to be auto-created */  
045    
046       void setAutoCreate(FieldItem field);
047    
048       /**
049        * Defines a method to initialize new objects created by the auto-create behaviour.
050        *
051        * @param field the field whose autocreate behaviour is considered
052        * @param initializer method used to initialize new objects. It
053        * must be a method of the field's owning class that takes an
054        * instance of the auto created object as parameter.
055        *
056        * @see #setAutoCreate(FieldItem) */
057       void setAutoCreateInitializer(FieldItem field, MethodItem initializer);
058    
059       /**
060        * This configuration method tells that all the class methods must
061        * be in auto-creation mode.
062        * @param cl the class
063        */
064       void setAutoCreateAll(ClassItem cl);
065    
066       /**
067        * This configuration method tells which parameters of the given
068        * method should be autocreated.
069        *
070        * <p>It does not use the constructor view but the actual modal
071        * view on an empty created object that needs to be filled by the
072        * user.
073        *
074        * @param method the method 
075        */
076       void setAutoCreateParameters(AbstractMethodItem method);
077    
078       /**
079        * This configuration method tells that all the class methods must
080        * be in auto-creation mode except the excluded ones.
081        *
082        * @param cl the class
083        * @param excludedMethods the excluded methods names
084        */
085       void setAutoCreateParametersEx(ClassItem cl, String[] excludedMethods);
086    
087       /**
088        * This configuration method tells which fields of the given class
089        * should be auto-created.
090        *
091        * <p>When a wrappee of the given class is auto-created using the
092        * <code>setAutoCreateParameters</code> method, all the fields
093        * mentioned here are also autocreated afterwards and a modal view
094        * is shown to the user so that he can fill the values. The given
095        * fields should be references (on other wrappees).
096        *
097        * @param cl the class
098        * @param fields the fields to autocreate
099        * @see #setAutoCreateParameters(AbstractMethodItem) */
100    
101       void setAutoCreateState(ClassItem cl, String[] fields);
102    
103       /**
104        * This configuration method allows the programmer to specify that
105        * the result of a given method (should be a wrappe) opens a new
106        * view on this result instead of treating it as a simple result.
107        *
108        * @param cl the class
109        * @param methodName the method name
110        * @see org.objectweb.jac.core.Display#openView(Object) */
111    
112       void setOpenViewMethod(ClassItem cl, String methodName);
113    
114       /**
115        * This configuration method allows the programmer to specify that
116        * the view on an object contained in a collection will be
117        * automatically opened by the GUI when the user selects it.
118        *
119        * @param collection the collection
120        *
121        * @see #setOnSelection(CollectionItem,MethodItem)
122        * @see #setSelectionTarget(CollectionItem,ClassItem,String)
123        */
124    
125       void setViewOnSelection(CollectionItem collection);
126    
127       /**
128        * Sets the event handler to be called when an item of the
129        * collection is selected.
130        *
131        * @param collection the collection
132        * @param eventHandler the event handler method. It must be static
133        * method. It will be called with the following parameters : the
134        * CustomizedGUI, the CollectionItem and the selected Object. If
135        * the handler returns an object, it will be used as the selected
136        * object.
137        */
138       void setOnSelection(CollectionItem collection, MethodItem eventHandler);
139    
140       /**
141        * Sets the field to be displayed when an item of the collection is
142        * selected, instead of the item itself.
143        *
144        * <p>If the user selects an object o, o.<targetField> will be
145        * displayed instead of o.</p>
146        *
147        * @param collection the collection
148        * @param targetClass the class owning the target field
149        * @param targetField the field to display
150        *
151        * @see #setViewOnSelection(CollectionItem) */
152       void setSelectionTarget(CollectionItem collection, 
153                               ClassItem targetClass, String targetField);
154    
155       /**
156        * Specify that the object views of instances of a class depend on
157        * the value of a field. That is, these views must be refreshed
158        * whenever the value of that field changes.
159        *
160        * @param cl the class
161        * @param fieldName the field name
162        */
163       void addViewFieldDependency(ClassItem cl, String fieldName);
164    
165       /**
166        * Tells if the default values of an item can be editable from the
167        * GUI. */
168       void setEditableDefaultValues(CollectionItem collection,boolean editable);
169       
170       /**
171        * Sets the given method to be closing (ie, when the user press the
172        * corresponding button, it performs the call and closes the
173        * current object view).
174        *
175        * @param cl the class the contains the method
176        * @param methodName the method item name. It can be of the form
177        * "methodName" or "methodName(<types>)". The first syntax will use
178        * the method with that name. The second syntax allow you to
179        * specify parameter types (separated by commas, with no spaces). */
180    
181       void setClosingMethod(ClassItem cl, String methodName);
182    
183       /**
184        * Set the commit method to use when attibutes are edited. 
185        *
186        * @param value If true, attribute changes are committed when the
187        * widget loses focus. Otherwise, a commit and a cancel button are
188        * displayed in each object view.  */
189    
190       void setCommitOnFocusLost(boolean value);
191    
192       /**
193        * Tells the swing administration gui to capture System.out so that
194        * it appears in a tab.  */
195    
196       void captureSystemOut();
197    
198       /**
199        * Tells the swing administration gui to capture System.err so that
200        * it appears in a tab.  */
201    
202       void captureSystemErr();
203    
204       /**
205        * Sets a method to be used to handler user interaction when a
206        * method is called, instead of the standard "ask for parameters
207        * stuffs".
208        * @param method
209        * @param handler It should be a static method taking as arguments
210        * (Interaction,DisplayContext)
211        */
212       void setInteractionHandler(MethodItem method, MethodItem handler);
213    
214       /**
215        * Defines a method to be called when an object referred to by it's
216        * indexed field is not found.
217        *
218        * @param cl the class of which the instance is not found
219        * @param handler the method to be called. It must be a static
220        * method taking 2 parameters: a ClassItem, which is the class of
221        * the object which could not be found, and an Object which is the
222        * value of the indexed field. And it should return an Object,
223        * which if not null will used as the found object.
224        *
225        * @see ClassAppearenceGuiConf#selectWithIndexedField(ClassItem,CollectionItem,String) 
226        */
227       void setIndexNotFoundHandler(ClassItem cl, 
228                                    MethodItem handler);
229    
230    }