001    package sale;
002    
003    import java.io.*;
004    import sale.events.*;
005    import java.awt.Rectangle;
006    
007    /**
008     * An abstract display that can display Form- and MenuSheets.
009     *
010     * <p>Displays are used to hide concrete user interface implementation details from the application
011     * developer. Together with {@link FormSheet FormSheets} and {@link MenuSheet MenuSheets}
012     * they provide a complete abstraction from concrete user interfaces. Whatever the concrete user
013     * interface looks like, Displays, Form- and MenuSheets will always be handled in the same way by the
014     * application.</p>
015     *
016     * <p>At any given point of time there may be up to one FormSheet and up to one MenuSheet set on a
017     * given Display. The Display interface offers methods to set and close these Form- and MenuSheets.
018     * as well as a restricted set of events that can be used to keep up to date with the current
019     * state of the display.</p>
020     *
021     * @author Steffen Zschaler
022     * @version 2.0 27/05/1999
023     * @since v2.0
024     */
025    public interface Display {
026    
027        /**
028         * Sets and displays a FormSheet.
029         *
030         * <p>This method should attach a FormSheetContainer as the FormSheet's display,
031         * get the FormSheet's caption, component and button bar and render them. The entire
032         * peer creation should be synchronized using {@link FormSheet#getComponentLock}
033         * and {@link FormSheet#getButtonsLock}, so as not to loose any events.</p>
034         *
035         * <p>If {@link FormSheet#waitResponse fs.waitResponse()} returns true,
036         * <code>setFormSheet()</code> should block, until the FormSheet is closed by a matching
037         * call to a <code>closeFormSheet()</code> method.</p>
038         *
039         * <p>If a FormSheet is already being displayed, <code>setFormSheet()</code> should cancel this
040         * FormSheet prior to setting the new FormSheet.</p>
041         *
042         * @override Always
043         *
044         * @param fs the FormSheet to be displayed.
045         *
046         * @exception InterruptedException if an interrupt occured while waiting for the
047         * FormSheet to be closed.
048         */
049        public void setFormSheet(FormSheet fs) throws InterruptedException;
050    
051        /**
052         * Returns the {@link FormSheet} that is currently attached to the display.
053         */
054        public FormSheet getFormSheet();
055    
056        /**
057         * Closes the current FormSheet. It is up to the display whether the FormSheet will be cancelled or
058         * just closed normally.
059         *
060         * @override Always
061         */
062        public void closeFormSheet();
063    
064        /**
065         * Shows a FormSheet, but do not close the current FormSheet. This method will
066         * normally pop up an extra {@link JDisplayDialog} that has the FormSheet set.
067         *
068         * <p>This method should attach a FormSheetContainer as the FormSheet's display,
069         * get the FormSheet's caption, component and button bar and render them. The entire
070         * peer creation should be synchronized using {@link FormSheet#getComponentLock}
071         * and {@link FormSheet#getButtonsLock}, so as not to loose any events.</p>
072         *
073         * <p>If {@link FormSheet#waitResponse fs.waitResponse()} returns true,
074         * <code>popUpFormSheet()</code> should block, until the FormSheet is closed by a matching
075         * call to a <code>closeFormSheet()</code> method.</p>
076         *
077         * <p>If a FormSheet is already being displayed, <code>popUpFormSheet()</code> must not close this
078         * FormSheet prior to setting the new FormSheet.</p>
079         *
080         * @override Always
081         *
082         * @param fs the FormSheet to be displayed.
083         *
084         * @exception InterruptedException if an interrupt occured while waiting for the
085         * FormSheet to be closed.
086         */
087        public void popUpFormSheet(FormSheet fs) throws InterruptedException;
088    
089        /**
090         * Sets and displays a MenuSheet.
091         *
092         * <p>If a MenuSheet is already being displayed, <code>setMenuSheet()</code> should remove this
093         * MenuSheet prior to setting the new MenuSheet.</p>
094         *
095         * @override Always
096         *
097         * @param ms the MenuSheet to be displayed. <code>null</code> is a valid value and should result in the
098         * current MenuSheet being closed.
099         */
100        public void setMenuSheet(MenuSheet ms);
101    
102        /**
103         * Returns the {@link MenuSheet} that is currently attached to the display.
104         */
105        public MenuSheet getMenuSheet();
106    
107        /**
108         * Returns true to indicate that this is a display that can be used normally. The only subclass that
109         * is actually allowed to return false is {@link NullDisplay}.
110         *
111         * @override Always
112         */
113        public boolean isUseableDisplay();
114    
115        /**
116         * Sets size an position of the display.
117         *
118         * @param r the Rectangle that contains the size and position information.
119         *
120         * @override Always
121         */
122        public void setBounds(Rectangle r);
123    
124        /**
125         * Returns currently set size and position of the display
126         */
127        public Rectangle getBounds();
128    
129        /**
130         * Registers a FormSheetListener to be informed when a FormSheet is set or closed.
131         *
132         * @override Always
133         *
134         * @param fsl the FormSheetListener to be registered.
135         */
136        public void addFormSheetListener(FormSheetListener fsl);
137    
138        /**
139         * Unregisters a FormSheetListener to be informed when a FormSheet is set or closed.
140         *
141         * @override Always
142         *
143         * @param fsl the FormSheetListener to be unregistered.
144         */
145        public void removeFormSheetListener(FormSheetListener fsl);
146    
147        /**
148         * Brings the display to front, i.e. activates it.
149         *
150         * @override Always
151         */
152        public void toFront();
153    
154        /**
155         * Restores the display from a stream.
156         *
157         * <p>As displays should not be serialized when making the Shop persistent, they cannot be normally
158         * deserialized. Instead they should individually read the attributes they previously {@link #save saved}.
159         * The attributes must be read in the same order they have previously been writtn.</p>
160         *
161         * <p><strong>Attention:</strong> The current class that has been written by the <code>save()</code> method
162         * must not be read here!</p>
163         *
164         * Example:
165         * <pre>
166         * FormSheet fsCurrent = (FormSheet)ois.readObject();
167         * MenuSheet msCurrent = (MenuSheet)ois.readObject();
168         * ...
169         * </pre>
170         * @override Always
171         *
172         * @param ois the stream to read attributes from
173         * @throws IOException
174         * @throws ClassNotFoundException
175         */
176        public void load(ObjectInputStream ois) throws IOException, ClassNotFoundException;
177    
178        /**
179         * Writes the display to a stream.
180         *
181         * <p>Displays should not be serialized as a whole. Instead use this method to individually write
182         * all attributes of the display to the stream.</p>
183         *
184         * <p><strong>Attention:</strong> The very first attribute to be written must be the display's class!</p>
185         *
186         *
187         * Example:
188         * <pre>
189         * oos.writeObject(getClass());
190         * oos.writeObject(fsCurrent); //current FormSheet
191         * oos.writeObject(msCurrent); //current MenuSheet
192         * ...
193         * </pre>
194         * @override Always
195         *
196         * @param oos the stream to write attributes to
197         * @throws IOException
198         * @throws ClassNotFoundException
199         */
200        public void save(ObjectOutputStream oos) throws IOException;
201    }