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 ois the stream to write attributes to
197 * @throws IOException
198 * @throws ClassNotFoundException
199 */
200 public void save(ObjectOutputStream oos) throws IOException;
201 }