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 classes in the GUI.
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 ClassAppearenceGuiConf {
034    
035        /**
036         * Defines the string representation of the instances of the class.
037         *
038         * @param classItem the class
039         * @param formatExpression a string that contains field references
040         * of the form <code>%field_name%</code>. All the field references
041         * are replaced by their value when a string representation of the
042         * instance is needed. When you need to print out a <code>%</code>,
043         * then you must double it (<code>%%</code>). 
044         *
045         * @see #setToString(ClassItem,MemberItem,String)
046         * @see #setToolTipText(ClassItem,MemberItem,String)
047         * @see #setToolTipText(ClassItem,ClassItem,String)
048         */
049        void setToString(ClassItem classItem, String formatExpression);
050    
051        /**
052         * Defines a contextual string representation of the instances of
053         * the class that will override the default one in some cases,
054         * depending on the selector parameter.
055         *
056         * @param classItem the class
057         * @param selector tells when the formatExpression should be
058         * applied. 
059         * @param formatExpression a string that contains field references
060         * of the form <code>%field_name%</code>. All the field references
061         * are replaced by their value when a string representation of the
062         * instance is needed. When you need to print out a <code>%</code>,
063         * then you must double it (<code>%%</code>).  
064         *
065         * @see #setToString(ClassItem,String)
066         * @see #setToString(ClassItem,MemberItem,String)
067         * @see #setToolTipText(ClassItem,MemberItem,String)
068         * @see #setToolTipText(ClassItem,ClassItem,String)
069         */
070        void setToString(ClassItem classItem, MemberItem selector,
071                         String formatExpression);
072    
073        /**
074         * Defines a contextual string representation of the instances of
075         * the class that will override the default one in some cases,
076         * depending on the selector parameter.
077         *
078         * @param classItem the class
079         * @param selector tells when the formatExpression should be
080         * applied. 
081         * @param formatExpression a string that contains field references
082         * of the form <code>%field_name%</code>. All the field references
083         * are replaced by their value when a string representation of the
084         * instance is needed. When you need to print out a <code>%</code>,
085         * then you must double it (<code>%%</code>).  
086         *
087         * @see #setToString(ClassItem,String)
088         * @see #setToString(ClassItem,MemberItem,String)
089         * @see #setToolTipText(ClassItem,MemberItem,String)
090         * @see #setToolTipText(ClassItem,ClassItem,String)
091         */
092        void setToString(ClassItem classItem, ClassItem selector,
093                         String formatExpression);
094    
095        /**
096         * This configuration method attaches an icon to a given class so
097         * that the iconized instances of this class will be represented by
098         * this icon (for instance in a treeview).
099         *
100         * @param cli the class
101         * @param name the icon's resource name 
102         *
103         * @see #setIcon(ClassItem,MethodItem)
104         */   
105        void setIcon(ClassItem cli, String name);
106    
107        /**
108         * Defines a method to dynamically compute the icon for a class.
109         *
110         * @param cli a class
111         * @param iconMethod a static method which must take an object as
112         * parameter and return a String or null. It will be invoked with
113         * the object for which an icon must be determined.
114         *
115         * @see #setIcon(ClassItem,String) 
116         */
117        void setDynamicIcon(ClassItem cli, MethodItem iconMethod);
118    
119        /**
120         * Defines a contextual string tooltip for the instances of a class.
121         *    
122         * @param classItem the class
123         * @param formatExpression a string that contains field references
124         * of the form <code>%field_name%</code>. All the field references
125         * are replaced by their value when a string representation of the
126         * instance is needed. When you need to print out a <code>%</code>,
127         * then you must double it (<code>%%</code>).  
128         *
129         * @see #setToolTipText(ClassItem,ClassItem,String)
130         * @see #setToolTipText(ClassItem,MemberItem,String)
131         */
132        void setToolTipText(ClassItem classItem, String formatExpression);
133    
134        /**
135         * Defines a contextual string tooltip for the instances of the
136         * class that will override the default one in some cases,
137         * depending on the selector parameter.
138         *
139         * @param classItem the class
140         * @param selector tells when the formatExpression should be
141         * applied. 
142         * @param formatExpression a string that contains field references
143         * of the form <code>%field_name%</code>. All the field references
144         * are replaced by their value when a string representation of the
145         * instance is needed. When you need to print out a <code>%</code>,
146         * then you must double it (<code>%%</code>).  
147         *
148         * @see #setToolTipText(ClassItem,String) 
149         * @see #setToolTipText(ClassItem,ClassItem,String) 
150         */
151        void setToolTipText(ClassItem classItem, MemberItem selector, 
152                            String formatExpression);
153    
154    
155        /**
156         * Defines a contextual string tooltip for the instances of the
157         * class that will override the default one in some cases,
158         * depending on the selector parameter.
159         *
160         * @param classItem the class
161         * @param selector tells when the formatExpression should be
162         * applied. 
163         * @param formatExpression a string that contains field references
164         * of the form <code>%field_name%</code>. All the field references
165         * are replaced by their value when a string representation of the
166         * instance is needed. When you need to print out a <code>%</code>,
167         * then you must double it (<code>%%</code>).  
168         *
169         * @see #setToolTipText(ClassItem,String) 
170         * @see #setToolTipText(ClassItem,MemberItem,String) 
171         */
172        void setToolTipText(ClassItem classItem, ClassItem selector, 
173                            String formatExpression);
174    
175        /**
176         * This configuration method attaches a contextual menu to a given
177         * class so that the instances of this class will show the menu
178         * when the user performs a right click on it (by default the menu
179         * shows all the methods).
180         *
181         * @param classItem the class
182         * @param menu an array containing the names of the methods that
183         * form the menu (must be declared in the class item), if an
184         * element is an empty string, then a menu item separator is added
185         */   
186        void setMenu(ClassItem classItem, String[] menu);
187    
188        /**
189         * This configuration method sets some categories for a class.
190         *
191         * <p>The GUI will interpret this categories to split the views
192         * of this class instances to be separated into several subviews.
193         * For instance, the Swing GUI will show the object in
194         * several parts placed into several tabs.
195         *
196         * <p>When this method has been called, each meta-item of the class
197         * must be categorized with one of the categories by using the
198         * <code>setCategory</code> method.
199         *
200         * @param cl the class item
201         * @param categories the categories for this class
202         * @see FieldAppearenceGuiConf#setCategory(MemberItem,String) 
203         */
204        void setCategories(ClassItem cl, String[] categories);
205    
206    
207        /**
208         * This configuration method sets categories icons for a class.
209         *
210         * Each icon is associated with a category, so there must be
211         * the right number of icons (one by category)
212         *
213         * @param cli the class
214         * @param icons the icons for the categories
215         * @see ClassAppearenceGuiConf#setCategories(ClassItem,String[]) 
216         */
217        void setCategoriesIcons(ClassItem cli, String[] icons);
218    
219        /**
220         * This configuration method sets categories labels for a class.
221         *
222         * Each label is associated with a category, so there must be
223         * the right number of labels (one by category)
224         *
225         * @param cli the class 
226         * @param labels the labels for the categories
227         * @see ClassAppearenceGuiConf#setCategories(ClassItem,String[]) 
228         */
229        void setCategoriesLabels(ClassItem cli, String[] labels);
230    
231        /**
232         * This configuration method allows the programmer to tell that the
233         * given class should be viewed with a given customized view when
234         * it is opened in a desktop panel.
235         *
236         * @param classItem the class of the viewed objects
237         * @param type the class of the view component 
238         */
239        void setDesktopCustomizedView(ClassItem classItem, ClassItem type);
240    
241        /**
242         * Sets the order in which the attributes of a class are to be
243         * rendered.
244         *
245         * <p>Attributes not listed here will not be rendered. This order
246         * is also used for tableView rendered collections if the
247         * <code>setTableMembersOrder</code> method is not used.
248         *
249         * @param cl the class 
250         * @param attributeNames the name of the attributes in the
251         * rendering order
252         *
253         * @see #setAttributesOrder(ClassItem,String,String[])
254         * @see #setTableMembersOrder(ClassItem,String[]) 
255         * @see #setMethodsOrder(ClassItem,String[]) 
256         * @see FieldAppearenceGuiConf#setMembersOrder(CollectionItem,ClassItem,String[])
257         */
258        void setAttributesOrder(ClassItem cl, String[] attributeNames);
259    
260        /**
261         * Sets the order in which the attributes of a class are to be
262         * rendered for a given view.
263         *
264         * <p>Attributes not listed here will not be rendered. This order
265         * is also used for tableView rendered collections if the
266         * <code>setTableMembersOrder</code> method is not used.
267         *
268         * @param cl the class 
269         * @param viewName the name of the view
270         * @param attributeNames the name of the attributes in the
271         * rendering order
272         *
273         * @see #setAttributesOrder(ClassItem,String[])
274         * @see #setTableMembersOrder(ClassItem,String[]) 
275         * @see FieldAppearenceGuiConf#setMembersOrder(CollectionItem,ClassItem,String[])
276         */
277        void setAttributesOrder(ClassItem cl, String viewName, String[] attributeNames);
278    
279        /**
280         * Sets the attributes to be displayed for editable default values in tables
281         *
282         * @param cl the class
283         * @param attributeNames the name of the attributes
284         * @see BehaviorGuiConf#setEditableDefaultValues(CollectionItem,boolean)
285         */
286        void setDefaultsAttributesOrder(ClassItem cl, String[] attributeNames);
287    
288        /**
289         * Defines which fields should start on a new line. By default,
290         * every fields start on a new line.
291         *
292         * @param cli the class
293         * @param fields the names fields which should start on a
294         * new line.  
295         */
296        void setLineBreaks(ClassItem cli, String[] fields);
297    
298        /**
299         * Sets the order in which the methods of a class are to be
300         * rendered for the default view.
301         *
302         * <p>Methods not listed here will not be rendered.
303         *
304         * @param cl the class name 
305         * @param methodNames the name of the methods in the
306         * rendering order 
307         * 
308         * @see #setMethodsOrder(ClassItem,String,String[])
309         */
310        void setMethodsOrder(ClassItem cl, String[] methodNames);
311    
312        /**
313         * Sets the order in which the methods of a class are to be
314         * rendered for a view.
315         *
316         * <p>Methods not listed here will not be rendered.
317         *
318         * @param cl the class name 
319         * @param viewName the view for which to set the methods order
320         * @param methodNames the name of the methods in the
321         * rendering order 
322         * 
323         * @see #setMethodsOrder(ClassItem,String[])
324         * @see #setAttributesOrder(ClassItem,String,String[])
325         */
326        void setMethodsOrder(ClassItem cl, String viewName, String[] methodNames);
327    
328        /**
329         * Sets the order in which the attributes of a class are to be
330         * rendered when an instance is created.
331         *
332         * @param cl the class name 
333         * @param attributeNames the name of the attributes in the
334         * rendering order
335         * @see #setAttributesOrder(ClassItem,String[]) */
336    
337        void setCreationAttributesOrder(ClassItem cl, String[] attributeNames);
338    
339        /**
340         * Sets the order in which the attributes of a class are to be
341         * rendered when their instance are placed within a table of the a
342         * default view.
343         *
344         * <p>Attributes not listed here will not be rendered.
345         *
346         * @param cl the class name
347         * @param memberNames the name of the member in the
348         * rendering order
349         *
350         * @see #setTableMembersOrder(ClassItem,String,String[])
351         * @see #setAttributesOrder(ClassItem,String[])
352         * @see FieldAppearenceGuiConf#setMembersOrder(CollectionItem,ClassItem,String[]) 
353         */
354        void setTableMembersOrder(ClassItem cl, String[] memberNames);
355    
356        /**
357         * Sets the order in which the attributes of a class are to be
358         * rendered when their instance are placed within a table of a
359         * given view.
360         *
361         * <p>Attributes not listed here will not be rendered.
362         *
363         * @param cl the class name
364         * @param viewName the name of the view
365         * @param memberNames the name of the member in the
366         * rendering order
367         *
368         * @see #setTableMembersOrder(ClassItem,String[])
369         * @see FieldAppearenceGuiConf#setMembersOrder(CollectionItem,ClassItem,String[]) 
370         */
371        void setTableMembersOrder(ClassItem cl, String viewName, String[] memberNames);
372    
373        /**
374         * Sets the order in which the attributes of a class are to be
375         * rendered when their instance are placed within a tree.
376         *
377         * <p>Attributes not listed here will not be rendered.
378         *
379         * @param cl the class name 
380         * @param attributeNames the name of the attributes in the
381         * rendering order
382         * @see #setAttributesOrder(ClassItem,String[])
383         * @see FieldAppearenceGuiConf#setMembersOrder(CollectionItem,ClassItem,String[])
384         */
385        void setTreeAttributesOrder(ClassItem cl, String[] attributeNames);
386    
387        /**
388         * Sets a default sorted column for a class.
389         *
390         * @param cl the class
391         * @param column the column used to sort (it is a fieldItem, watch
392         * out for case). You may preprend a '-' to use the reverse order
393         * of that column.
394         */
395        void setDefaultSortedColumn(ClassItem cl, String column);
396    
397        /**
398         * Sets the description of a class.
399         * @param cl the class
400         * @param description the description of the class
401         */
402        void setDescription(ClassItem cl, String description);
403    
404        /**
405         * Sets the label of a class.
406         * @param cl the class
407         * @param label the label of the class
408         */
409        void setLabel(ClassItem cl, String label);
410    
411        /**
412         * Wether to display a label containing the name of the field in views.
413         *
414         * @param virtualClass the name of the class
415         * @param value boolean indicating wether to display the label or not
416         */
417        void setDisplayLabel(String virtualClass, boolean value);
418    
419        /**
420         * Sets the display format of a class.
421         */
422        void setFormat(String className, String format);
423    
424        /**
425         * Tells the gui to use a primary key field to select instances of
426         * a class, instead of a combobox. This is usefull when there are
427         * two many instances of the class.
428         *
429         * @param cl the class whose instance to select
430         * @param collection the collection whose indexed field to use 
431         * @param repositoryName name of the object holding the collection
432         *
433         * @see org.objectweb.jac.core.rtti.RttiAC#setIndexedField(CollectionItem,FieldItem) 
434         */
435        void selectWithIndexedField(ClassItem cl, CollectionItem collection, String repositoryName);
436    
437        /**
438         * Set the style for a class
439         *
440         * @param cli the class
441         * @param style the CSS style
442         *
443         * @see FieldAppearenceGuiConf#setStyle(FieldItem,String)
444         * @see GuiConf#addStyleSheetURL(String)
445         * @see GuiConf#addStyleSheetURL(String,String)
446         */
447        void setStyle(ClassItem cli, String style);
448    
449        void setReadOnly(ClassItem cli, String viewName, boolean readOnly);
450    
451        /**
452         * Defines a method that returns instances of a class that should
453         * be displayed in comboboxes.
454         *
455         * @param className the class to configure (ClassItem or VirtualClassItem)
456         * @param targetMethod the static method that returns instances of
457         * the class. It should take a ClassItem as a parameter and return
458         * a Collection
459         *
460         * @see FieldAppearenceGuiConf#setDynamicFieldChoice(FieldItem,Boolean,MethodItem) 
461         */
462        void setDynamicClassChoice(String className, MethodItem targetMethod);
463    
464        /**
465         * Defines preferred mnemonics for class.
466         * @param cli
467         * @param mnemonics the mnemonics
468         */
469        void setMnemonics(ClassItem cli, String mnemonics);
470    }