001    /*
002      Copyright (C) 2001-2002 Renaud Pawlak. <renaud@aopsys.com>
003    
004      This program is free software; you can redistribute it and/or modify
005      it under the terms of the GNU Lesser General Public License as
006      published by the Free Software Foundation; either version 2 of the
007      License, or (at your option) any later version.
008    
009      This program is distributed in the hope that it will be useful,
010      but WITHOUT ANY WARRANTY; without even the implied warranty of
011      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
012      GNU Lesser General Public License for more details.
013    
014      You should have received a copy of the GNU Lesser General Public
015      License along with this program; if not, write to the Free Software
016      Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
017      USA */
018    
019    package org.objectweb.jac.core;
020    
021    import org.objectweb.jac.core.rtti.*;
022    import java.util.Map;
023    
024    /**
025     * This interface is an abstract description of how a display is
026     * defined in org.objectweb.jac.
027     *
028     * <p>In JAC, a GUI that needs to allow aspects to interfere with
029     * itself (with output and input data) must implement this
030     * interface. When the GUI invokes a non-gui object, it must then
031     * define the "Gui.display" attribute to be itself so that internal
032     * component know what display to use. If this display attribute is
033     * not defined by the GUI, then the objects that need display
034     * operations can use the default textual display (that uses
035     * <code>System.out</code> and <code>System.in</code> for output and
036     * input).
037     *
038     * @see org.objectweb.jac.core.Collaboration#get()
039     * @see org.objectweb.jac.core.Collaboration
040     */
041    
042    public interface Display {
043    
044        /**
045         * Gets the ID (a unique string identifier) of the current
046         * display.
047         *
048         * @return a string 
049         */
050        String getDisplayID();
051    
052        /**
053         * Sets the ID (a unique string identifier) of the current
054         * display.
055         *
056         * @param displayID a string (should be unique) 
057         */
058        void setDisplayID(String displayID);
059    
060        /**
061         * Shows the given object on the display.
062         *
063         * <p>The showed object is considered as a result.
064         *
065         * <p>On contrary to <code>showModal</code>, this method does not
066         * stop the client thread execution.
067         *
068         * @param object the object to show 
069         */
070        void show(Object object);
071    
072        /**
073         * Shows a view of an object.
074         *
075         * <p>The showed object is considered as a result.
076         *
077         * <p>On contrary to <code>showModal</code>, this method does not
078         * stop the client thread execution.
079         *
080         * @param object the object to show 
081         * @param viewType the type of the view to display
082         * @param viewParams parameters to give the view constructor
083         */
084        void show(Object object,
085                  String viewType, Object[] viewParams);
086    
087        /**
088         * Shows the given object on the display by opening a new core
089         * view.
090         *
091         * <p>On contrary to <code>showModal</code>, this method does not
092         * stop the client thread execution.
093         *
094         * @param object the object to show 
095         */
096        void openView(Object object);
097    
098        /**
099         * Shows the given object on the display and waits for a user
100         * input.
101         *
102         * <p>On contrary to <code>show</code>, this method stops the
103         * client thread execution and waits for a user input to continue
104         * (as an OK button click or a key pressing).
105         *
106         * @param object the object to show
107         * @param title the window title if a window is opened
108         * @param header a header message
109         * @param parent the parent window 
110         * @param canValidate if true, a validation button is added
111         * @param canCancel if true, a cancellation button is added
112         * @param canClose if true, a closing button is added
113         * @return false if the user canceled 
114         *
115         * @see #showModal(Object,String,Object[],String,String,Object,boolean,boolean,boolean)
116         */
117        boolean showModal(Object object, String title, String header,  
118                          Object parent,
119                          boolean canValidate, boolean canCancel, 
120                          boolean canClose);
121    
122        /**
123         * Shows the given object on the display and waits for a user
124         * input.
125         *
126         * @param object the object to show
127         * @param viewType the type of view to build or the object
128         * @param viewParams parameters to give the view constructor
129         * @param title the window title if a window is opened
130         * @param header a header message
131         * @param parent the parent window 
132         * @param okButton if true, a validation button is added
133         * @param cancelButton if true, a cancellation button is added
134         * @param closeButton if true, a closing button is added
135         * @return false if the user canceled 
136         *
137         * @see #showModal(Object,String,String,Object,boolean,boolean,boolean)
138         */
139        boolean showModal(Object object, 
140                          String viewType, Object[] viewParams,
141                          String title, String header, 
142                          Object parent,
143                          boolean okButton, boolean cancelButton, 
144                          boolean closeButton);
145    
146        /**
147         * Show a customized Gui.
148         *
149         * @param id the id of the customized GUI to show
150         * @param customized the CustomizedGUI to show
151         *
152         * @see org.objectweb.jac.aspects.gui.CustomizedGUI
153         */
154        void showCustomized(String id, Object customized);
155    
156        /**
157         * Show a customized Gui.
158         *
159         * @param id the id of the customized GUI to show
160         * @param customized the CustomizedGUI to show
161         * @param panels contents of panels ( panelID -> object)
162         *
163         * @see org.objectweb.jac.aspects.gui.CustomizedGUI
164         */
165        void showCustomized(String id, Object customized, Map panels);
166    
167        /**
168         * Rebuilds all customized GUI windows.
169         */
170        void fullRefresh();
171    
172        /**
173         * Asks the user to fill the parameters to prepare the invocation
174         * of the given method.
175         *
176         * <p>This operation stops the client thread.
177         *
178         * @param object the object that contains the method (null if a
179         * constructor)
180         * @param method the method to fill the parameters o
181         * @param parameters the parameters values; as an input, they can
182         * be set by the client to fill default values for these
183         * parameters; as an output, they must be used by the client as the
184         * actual parameter values to call the given method
185         * @return false if the user canceled 
186         */
187        boolean showInput(Object object, AbstractMethodItem method, 
188                          Object[] parameters);
189    
190        /**
191         * Refresh the display.
192         *
193         * <p>This method is useful for some kind of displays when the
194         * refresh operation cannot be done automatically when the
195         * displayed objects states change (e.g. a web display).
196         *
197         * @see org.objectweb.jac.aspects.gui.web.WebDisplay 
198         */
199        void refresh();
200    
201        /**
202         * Displays a message to the user.
203         *
204         * @param title the window title if a window is opened
205         * @param message a header message
206         * @param canValidate if true, a validation button is added
207         * @param canCancel if true, a cancellation button is added
208         * @param canClose if true, a closing button is added
209         * @return false if the user canceled 
210         */
211        boolean showMessage(String message, String title,
212                            boolean canValidate, boolean canCancel, 
213                            boolean canClose);
214    
215        /**
216         * Shows a message to the user.
217         *
218         * @param title the title of the window
219         * @param message the message
220         *
221         * @see #showError(String,String)
222         */
223        void showMessage(String title, String message);
224    
225        /**
226         * Shows a message to the user.
227         *
228         * @param title the title of the window
229         * @param message the message
230         * @return the auto-refreshed window
231         *
232         * @see #showError(String,String)
233         */
234         Object showRefreshMessage(String title, String message);
235    
236        /**
237         * Show an error message to the user.
238         *
239         * @param title the title of the window
240         * @param message the error message
241         *
242         * @see #showMessage(String,String)
243         */
244        void showError(String title, String message);
245    
246        /**
247         * Notifies the display that a new application has just started.
248         *
249         * <p>At this step, all the root objects of the application have
250         * been created and it is time to open the main view if any. */
251       
252        void applicationStarted();
253    
254        /**
255         * Closes this display. 
256         */
257        void close();
258    
259        /**
260         * Called before interactively calling a method with parameters,
261         * so that the display can set some of them.
262         * @return false if there some parameters are still unassigned 
263         */
264        boolean fillParameters(AbstractMethodItem method, Object[] parameters);
265    
266        /**
267         * Called after interactively calling a method with parameters.
268         */
269        void onInvocationReturn(Object substance, AbstractMethodItem method);
270    }
271    
272    
273