001 package sale;
002
003 import java.io.Serializable;
004
005 import javax.swing.*;
006
007 /**
008 * A generic menu element.
009 *
010 * @see MenuSheet
011 * @see MenuSheetItem
012 * @see MenuSheetSeparator
013 *
014 * @author Steffen Zschaler
015 * @version 2.0 20/05/1999
016 * @since v2.0
017 */
018 public abstract class MenuSheetObject extends Object implements Serializable {
019
020 /**
021 * The caption of the menu element.
022 *
023 * @serial
024 */
025 private String m_sCaption;
026
027 /**
028 * Immutable tag, that can be used to identify the menu element. Never
029 * <code>null</code>!
030 *
031 * @serial
032 */
033 private String m_sTag;
034
035 /**
036 * Is this MenuSheetObject currently on display?
037 *
038 * @serial
039 */
040 private boolean m_fVisible = false;
041
042 /**
043 * The MenuSheet that contains this menu element.
044 *
045 * @serial
046 */
047 protected MenuSheet m_msParent;
048
049 /**
050 * The SalesPoint attached to this MenuSheetObject, if any.
051 *
052 * @serial
053 */
054 protected SalesPoint m_spAttached;
055
056 /**
057 * The SaleProcess attached to this MenuSheetObject, if any.
058 *
059 * @serial
060 */
061 protected SaleProcess m_pAttached;
062
063 /**
064 * Create a new MenuSheetObject with a caption and a tag.
065 *
066 * @param sCaption the caption of this MenuObject
067 * @param sTag the tag of this MenuObject. If <code>null</code>, a default, unique tag
068 * will be given.
069 */
070 public MenuSheetObject(String sCaption, String sTag) {
071 super();
072
073 m_sCaption = sCaption;
074
075 if (sTag != null) {
076 m_sTag = sTag;
077 } else {
078 m_sTag = STD_TAG_PREFIX + (s_nLastTagID++);
079 }
080 }
081
082 /**
083 * Create a new MenuSheetObject with a caption and a default tag.
084 *
085 * <p>You can find out about the tag by calling {@link #getTag}.</p>
086 *
087 * @param sCaption the caption of the MenuSheetObject.
088 */
089 public MenuSheetObject(String sCaption) {
090 this(sCaption, null);
091 }
092
093 /**
094 * Get the MenuSheetObject's caption.
095 *
096 * @override Never
097 */
098 public String getCaption() {
099 return m_sCaption;
100 }
101
102 /**
103 * Set the MenuSheetObject's caption.
104 *
105 * @override Always Override to make sure, the peer's captions gets properly updated.
106 *
107 * @param sCaption the new caption.
108 */
109 public void setCaption(String sCaption) {
110 m_sCaption = sCaption;
111 }
112
113 /**
114 * Get the MenuSheetObject's tag. The tag of a MenuSheetObject can be used to
115 * identify a MenuSheetObject in a MenuSheet. It is immutable, never <code>null</code>
116 * and should be unique in the containing MenuSheet.
117 *
118 * @override Never
119 *
120 * @see MenuSheet
121 * @see #getTaggedItem
122 */
123 public String getTag() {
124 return m_sTag;
125 }
126
127 /**
128 * Get the first MenuSheetObject with the given tag which is managed by this one.
129 *
130 * <p>The default implementation returns this MenuSheetObject if it has the given tag,
131 * and <code>null</code> otherwise.</p>
132 *
133 * @override Never
134 *
135 * @param sTag the tag that is searched for.
136 * @param fTopLevelOnly if true, only the top level items are searched.
137 */
138 public MenuSheetObject getTaggedItem(String sTag, boolean fTopLevelOnly) {
139 return ((getTag().equals(sTag)) ? (this) : (null));
140 }
141
142 /**
143 * Convenience method for in-depth search for a tagged item.
144 *
145 * <p>Equivalent to:
146 *
147 * <pre>
148 * getTaggedItem (sTag, false);
149 * </pre>
150 *
151 * @override Never
152 *
153 * @param sTag the tag to be searched for.
154 */
155 public MenuSheetObject getTaggedItem(String sTag) {
156 return getTaggedItem(sTag, false);
157 }
158
159 /**
160 * Attach a SalesPoint to this MenuSheetObject.
161 *
162 * @override Never
163 *
164 * @param sp the SalesPoint to be attached.
165 *
166 * @return the previously attached SalesPoint, if any.
167 */
168 public SalesPoint attach(SalesPoint sp) {
169 SalesPoint spOld = m_spAttached;
170
171 m_spAttached = sp;
172
173 return spOld;
174 }
175
176 /**
177 * Detach the currently attached SalesPoint.
178 *
179 * @override Never
180 *
181 * @return the SalesPoint just detached, if any.
182 */
183 public SalesPoint detachSalesPoint() {
184 return attach((SalesPoint)null);
185 }
186
187 /**
188 * Attach a SaleProcess to this MenuSheetObject.
189 *
190 * @override Never
191 *
192 * @param p the process to be attached.
193 *
194 * @return the previously attached process, if any.
195 */
196 public SaleProcess attach(SaleProcess p) {
197 SaleProcess pOld = m_pAttached;
198
199 m_pAttached = p;
200
201 return pOld;
202 }
203
204 /**
205 * Detach the currently attached SaleProcess.
206 *
207 * @override Never
208 *
209 * @return the SaleProcess just detached, if any.
210 */
211 public SaleProcess detachSaleProcess() {
212 return attach((SaleProcess)null);
213 }
214
215 /**
216 * Set the parent of the MenuSheetObject. This method is used internally only.
217 *
218 * @override Never
219 */
220 void setParent(MenuSheet msParent) {
221 m_msParent = msParent;
222 }
223
224 /**
225 * Get the parent MenuSheet of this MenuSheetObject.
226 *
227 * @override Never
228 *
229 * @return the MenuSheet containing this MenuSheetObject.
230 */
231 public MenuSheet getParent() {
232 return m_msParent;
233 }
234
235 /**
236 * Mark this MenuSheetObject visible or invisible. This does not actually show or hide
237 * the MenuSheetObject's peer, but rather helps the MenuSheetObject manage resources.
238 *
239 * <p>This method is usually not called directly.</p>
240 *
241 * @override Sometimes Override if you have some additional ressources that need visibility dependent
242 * management.
243 *
244 * @param fVisible the visibility state of the MenuSheetObject.
245 */
246 public void setVisible(boolean fVisible) {
247 m_fVisible = fVisible;
248 }
249
250 /**
251 * Get the visibility state of this MenuSheetObject.
252 *
253 * @override Never
254 */
255 public boolean isVisible() {
256 return m_fVisible;
257 }
258
259 /**
260 * Return true if this is a separator. Separators need not have peers.
261 *
262 * @override Never The default implementation returns false.
263 *
264 * @see #getPeer
265 * @see #getMenuPeer
266 */
267 public boolean isSeparator() {
268 return false;
269 }
270
271 /**
272 * Compare this MenuSheetObject to the given object and return true if they are equal.
273 *
274 * <p>For MenuSheetObjects equality of references is measured, i.e.
275 * <code>equals()</code> will only return true if <code>this == o</code>.</p>
276 *
277 * @override Never You should only override this method when there is an absolute need for a different
278 * equality measurement.
279 *
280 * @param o the object to compare to.
281 */
282 public boolean equals(Object o) {
283 return (this == o);
284 }
285
286 /**
287 * Return the JMenuItem peer for this MenuSheetObject. This can be a JMenuItem or a
288 * JMenu, just as is appropriate. You can always return the same peer.
289 *
290 * @override Always
291 */
292 public abstract JMenuItem getPeer();
293
294 /**
295 * Return the JMenu peer for this MenuSheetObject. Independently of the actual type of
296 * the MenuSheetObject this must return a JMenu object.
297 *
298 * <p>For MenuSheetItems and similar MenuSheetObjects it is recommended that you create
299 * a JMenu with the same caption and only one item, the MenuElement peer of the
300 * MenuSheetObject. Make sure, however, to create all these objects afresh for the
301 * JMenu peer, lest there should result inpredictably behaving menus. This does, of
302 * course not apply, if the MenuElement peer and the JMenu peer are entirely equal as
303 * is the case for MenuSheets.</p>
304 *
305 * <p>Although JMenuItem peer and JMenu peer should be different objects, subsequent
306 * calls to <code>getMenuPeer()</code> can still return the same object.</p>
307 *
308 * @override Always
309 */
310 public abstract JMenu getMenuPeer();
311
312 /**
313 * The default tag prefix, if no tag was given.
314 */
315 private static final String STD_TAG_PREFIX = "__TAG_";
316
317 /**
318 * The last tag id that was given to a default tag.
319 */
320 private static int s_nLastTagID = 0;
321 }