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 the appearence of the methods in views.
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 MethodAppearenceGuiConf {
034    
035        /**
036         * Same as <code>setDynamicFieldChoice</code> but for method parameters
037         *
038         * <p>The values are dynamically defined at runtime by the
039         * invocation of a static target method. This target method must
040         * return an array of objects that contains the possible new values
041         * for the fields.
042         *
043         * @param method the method
044         * @param targetClasses the array of classes that contains the
045         * target method for each parameter (elements of this array may be null)
046         * @param targetMethods the static methods within the target
047         * classes that returns the values to choose from (elements of this
048         * array may be null). The prototype is
049         * <code>callback(Object)</code> where the given object is the
050         * substance.
051         * @param editable tells if the values can be edited (new values
052         * can be manually entered) 
053         *
054         * @see #setMethodDynamicParameterChoice(MethodItem,MethodItem[],boolean[])
055         */
056        void setMethodDynamicParameterChoice(MethodItem method, 
057                                             ClassItem[] targetClasses, 
058                                             String[] targetMethods,
059                                             boolean[] editable); 
060    
061        /**
062         * Same as <code>setDynamicFieldChoice</code> but for method parameters
063         *
064         * <p>The values are dynamically defined at runtime by the
065         * invocation of a static target method. This target method must
066         * return an array of objects that contains the possible new values
067         * for the fields.
068         *
069         * @param method the method
070         * @param targetMethods the static methods 
071         * that returns the values to choose from (elements of this
072         * array may be null). The prototype is
073         * <code>callback(Object)</code> where the given object is the
074         * substance.
075         * @param editable tells if the values can be edited (new values
076         * can be manually entered) 
077         *
078         * @see #setMethodDynamicParameterChoice(MethodItem,ClassItem[],String[],boolean[])
079         */
080        void setMethodDynamicParameterChoice(MethodItem method, 
081                                             MethodItem[] targetMethods, 
082                                             boolean[] editable); 
083    
084        /**
085         * Sets the argument names of a given method item so that they can
086         * be used by GUI aspect components.
087         *
088         * <p>The GUI aspect can automatically fill some default parameter
089         * names for all the setters to lighten the GUI aspect programmer
090         * work (however, these automatically generated names can be
091         * overloaded if needed).
092         *
093         * @param method the method item. It can be of the form
094         * "methodName" or "methodName(<types>)". The first syntax will use
095         * the method with that name. The second syntax allow you to
096         * specify parameter types (separated by commas, with no spaces).
097         * @param parameterNames the parameter names
098         */
099        void setParameterNames(AbstractMethodItem method,
100                               String[] parameterNames);
101    
102        /**
103         * Declares some parameters of method as enums. 
104         * @param method the method
105         * @param enumNames the name of enums, for each parameter of the
106         * method. Use null to leave a parameter unaffected.
107         */
108        void setParameterEnums(AbstractMethodItem method, 
109                               String[] enumNames) throws Exception;
110    
111        /**
112         * Declares some reference parameters (non-primitive object-typed
113         * parameters) of the method to be linked with a collection that
114         * gives the choices of the object in the GUI combobox.
115         * @param method the method
116         * @param collections the entire names of the collections that
117         * should be linked to the corresponding parameters (empty string
118         * if unlinked) */
119        void setLinkedParameters(AbstractMethodItem method, 
120                                 String[] collections) throws Exception;
121    
122        /**
123         * Tells if JAC object-typed (references) arguments of a method can be
124         * created while the method's invocation or if they should be
125         * choosen in existing instances list.
126         *
127         * @param method the method item. It can be of the form
128         * "methodName" or "methodName(<types>)". The first syntax will use
129         * the method with that name. The second syntax allow you to
130         * specify parameter types (separated by commas, with no spaces).
131         * @param create a flags arrays that tells for each parameters
132         * whether it can be created (true) or not (false). It has no
133         * effect if the parameter is not a JAC object (a reference) 
134         * 
135         * @see #setCreationAllowed(FieldItem,boolean)
136         */
137        void setCreationAllowedParameters(AbstractMethodItem method,
138                                          boolean[] create);
139    
140        /**
141         * Tells wether should be allowed to create a new instance when
142         * editing the value of a field.
143         *
144         * @param field the field
145         * @param allow wether to allow or not
146         * 
147         * @see #setCreationAllowedParameters(AbstractMethodItem,boolean[]) 
148         */
149        void setCreationAllowed(FieldItem field, boolean allow);
150    
151        /**
152         * Specify that a parameter of a method corresponds to a field
153         * within the invoked object.
154         *
155         * @param method the method 
156         * @param parameterFields an array that contains the corresponding
157         * field for each parameter of the method 
158         */
159        void setParameterFields(AbstractMethodItem method, 
160                                String[] parameterFields);
161       
162        /**
163         * Sets the width for all parameters of one method.
164         *
165         * @param method the method
166         * @param width width in pixels of all parameters
167         * @param columns width in columns of all parameters
168         */
169        void setMethodParametersWidth(AbstractMethodItem method,
170                                      int[] width, int[] columns)
171            throws Exception;
172    
173        /**
174         * Sets the height for all parameters of one method.
175         *
176         * @param method the method
177         * @param height height in pixels of all parameters
178         * @param rows height in columns of all parameters
179         */
180        void setMethodParametersHeight(AbstractMethodItem method,
181                                       int[] height, int[] rows)
182            throws Exception;
183    
184        /**
185         * Specify that a parameter of a method is a pasword method.
186         *
187         * <p>A password parameter will be rendered with stars instead of
188         * the actual characters.
189         *
190         * @param method the method 
191         * @param parameterFields an array that must contains "true" items
192         * if the corresponding parameter is a password, "false" or ""
193         * otherwhise. 
194         */
195        void setPasswordParameters(AbstractMethodItem method, String[] parameterFields);
196    
197        /**
198         * This configuration method allows the programmer to tell the GUI
199         * to add some buttons to the collection that will invoke the
200         * corresponding methods on the currently selected collection
201         * element.
202         *
203         * @param collection the collection 
204         * @param methods the names of the methods that can be invoked on
205         * the selected element 
206         */
207        void setDirectCollectionMethods(CollectionItem collection, 
208                                        String[] methods);
209    
210        /**
211         * Sets the default value for argument names of a given method item
212         * so that they can be used by GUI aspect components.
213         *
214         * @param method the method item. It can be of the form
215         * "methodName" or "methodName(<types>)". The first syntax will use
216         * the method with that name. The second syntax allow you to
217         * specify parameter types (separated by commas, with no spaces).
218         * @param values the default parameter values */
219    
220        void setDefaultValues(AbstractMethodItem method, Object[] values);
221    
222        /**
223         * Sets a condition on a method. If the condition evaluates to
224         * false, the method is diabled in the GUI.
225         *
226         * @param method the method to put a condition on
227         * @param condition the condition. It must be the name of method of
228         * the same class as method which returns a boolean.
229         */
230        void setCondition(AbstractMethodItem method, String condition);
231    
232        /**
233         * If an operation is expected to take a long time to complete,
234         * use this method to tell the GUI that it should display a
235         * message asking the user to wait for a while.
236         *
237         * @param method the method
238         * @param isSlow wether the method is slow or not
239         */
240        void setSlowOperation(AbstractMethodItem method, boolean isSlow);
241    
242        /**
243         * <p>Sets the mime-type of the file written to an OutputStream or
244         * Writer.</p>
245         *
246         * <p>If a method takes an OutputStream or Writer as a parameter,
247         * a display (such as the web display or instance) may redirect
248         * the stream, to the browser. So that the browser can correctly
249         * interpret the data, it may be necessary to specify its
250         * mime-type.</p>
251         *
252         * @param method
253         * @param type the mime-type (such as "application/pdf") 
254         */
255        void setMimeType(AbstractMethodItem method, String type);
256    
257        /**
258         * Defines a method to dynamically compute the icon for a menu's
259         * method.
260         *
261         * @param method method
262         * @param iconMethod a static method which must take 3 parameters
263         * (a MethodItem, an Object and an array of objects) and return a
264         * String or null. It will be invoked with the parameters array
265         * given to <code>addMenuItem</code>
266         *
267         * @see GuiConf#addMenuItem(String,String,String[],String,AbstractMethodItem,String[]) 
268         * @see FieldAppearenceGuiConf#setIcon((MemberItem,String)
269         */
270        void setDynamicIcon(MethodItem method, MethodItem iconMethod);
271    
272        /**
273         * Specifies a method to be invoked after a method is invoked from
274         * the GUI.
275         *
276         * @param method 
277         * @param hook the method to be invoked after "method" is
278         * invoked. It must be static and take an InvokeEvent parameter
279         * @see InvokeEvent
280         */
281        void addPostInvoke(AbstractMethodItem method, AbstractMethodItem hook);
282    }