KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > ui > internal > menus > SWidget


1 /*******************************************************************************
2  * Copyright (c) 2005, 2006 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/

11 package org.eclipse.ui.internal.menus;
12
13 import org.eclipse.core.commands.common.NotDefinedException;
14 import org.eclipse.jface.menus.IWidget;
15 import org.eclipse.jface.util.PropertyChangeEvent;
16
17 /**
18  * <p>
19  * A menu element that represents some arbitrary control. This arbitrary control
20  * has an id, zero or more locations, and a class providing the callback methods
21  * necessary to create the arbitrary control.
22  * </p>
23  * <p>
24  * <strong>PROVISIONAL</strong>. This class or interface has been added as part
25  * of a work in progress. There is a guarantee neither that this API will work
26  * nor that it will remain the same. Please do not use this API without
27  * consulting with the Platform/UI team.
28  * </p>
29  * <p>
30  * This class will eventually exist in <code>org.eclipse.jface.menus</code>.
31  * </p>
32  *
33  * @since 3.2
34  */

35 public final class SWidget extends MenuElement {
36
37     /**
38      * The property for a property change event indicating that whether the
39      * widget class has changed.
40      */

41     public static final String JavaDoc PROPERTY_WIDGET = "WIDGET"; //$NON-NLS-1$
42

43     /**
44      * The layout information to associate with this widget; never
45      * <code>null</code>.
46      */

47     private SLayout layout;
48
49     /**
50      * The class that will contribute widgets to the menu; never
51      * <code>null</code>.
52      */

53     private IWidget thirdPartyCode;
54
55     /**
56      * Constructs a new instance of <code>SWidget</code>.
57      *
58      * @param id
59      * The identifier of the widget to create; must not be
60      * <code>null</code>
61      */

62     SWidget(final String JavaDoc id) {
63         super(id);
64     }
65
66     /**
67      * <p>
68      * Defines this widget by providing the class defining the widget. The
69      * location is optional. The defined property automatically becomes
70      * <code>true</code>.
71      * </p>
72      *
73      * @param widget
74      * The class that is called to contribute widgets to the given
75      * locations; must not be <code>null</code>.
76      * @param location
77      * The location in which this item will appear; may be
78      * <code>null</code>.
79      */

80     public final void define(final IWidget widget, final SLocation location) {
81         final SLocation[] locations;
82         if (location == null) {
83             locations = null;
84         } else {
85             locations = new SLocation[] { location };
86         }
87         define(widget, locations);
88     }
89
90     /**
91      * <p>
92      * Defines this widget by providing the class defining the widget. The
93      * locations are optional. The defined property automatically becomes
94      * <code>true</code>.
95      * </p>
96      *
97      * @param widget
98      * The class that is called to contribute widgets to the given
99      * locations; must not be <code>null</code>.
100      * @param locations
101      * The locations in which this item will appear; may be
102      * <code>null</code> or empty.
103      */

104     public final void define(final IWidget widget, final SLocation[] locations) {
105         define(widget, locations, new SLayout());
106     }
107
108     /**
109      * <p>
110      * Defines this widget by providing the class defining the widget. The
111      * locations are optional. The defined property automatically becomes
112      * <code>true</code>.
113      * </p>
114      *
115      * @param widget
116      * The class that is called to contribute widgets to the given
117      * locations; must not be <code>null</code>.
118      * @param locations
119      * The locations in which this item will appear; may be
120      * <code>null</code> or empty.
121      * @param layout
122      * The layout information to use for this widget
123      */

124     public final void define(final IWidget widget, final SLocation[] locations,
125             SLayout layout) {
126         if (widget == null) {
127             throw new NullPointerException JavaDoc(
128                     "A widget needs a class to contribute the widgets"); //$NON-NLS-1$
129
}
130
131         setDefined(true);
132         setLocations(locations);
133         setLayout(layout);
134         setWidget(widget);
135     }
136
137     /**
138      * Returns the layout information associated with this widget
139      *
140      * @return the layout information; never <code>null</code>.
141      * @throws NotDefinedException
142      */

143     public final SLayout getLayout() throws NotDefinedException {
144         if (!isDefined()) {
145             throw new NotDefinedException(
146                     "Cannot get the layout from an undefined widget"); //$NON-NLS-1$
147
}
148
149         return layout;
150     }
151
152     /**
153      * Returns the class providing the widgets for this menu element.
154      *
155      * @return The widget for this menu element; never <code>null</code>.
156      * @throws NotDefinedException
157      * If the handle is not currently defined.
158      */

159     public final IWidget getWidget() throws NotDefinedException {
160         if (!isDefined()) {
161             throw new NotDefinedException(
162                     "Cannot get the widget class from an undefined widget"); //$NON-NLS-1$
163
}
164
165         return thirdPartyCode;
166     }
167
168     /**
169      * Sets the layout information associated with this widget. This will fire a
170      * property change event if anyone cares.
171      *
172      * @param layout
173      * The layout information to associate with this widget; may be
174      * <code>null</code>.
175      */

176     private final void setLayout(final SLayout layout) {
177         this.layout = layout;
178     }
179
180     /**
181      * Sets widget class backing this widget. This will fire a property change
182      * event if anyone cares.
183      *
184      * @param widget
185      * The widget class; may be <code>null</code>.
186      */

187     protected final void setWidget(final IWidget widget) {
188         PropertyChangeEvent event = null;
189         if (isListenerAttached()) {
190             event = new PropertyChangeEvent(this, PROPERTY_WIDGET,
191                     this.thirdPartyCode, widget);
192         }
193         this.thirdPartyCode = widget;
194         firePropertyChangeEvent(event);
195     }
196
197     /**
198      * The string representation of this widget -- for debugging purposes only.
199      * This string should not be shown to an end user.
200      *
201      * @return The string representation; never <code>null</code>.
202      */

203     public final String JavaDoc toString() {
204         if (string == null) {
205             final StringBuffer JavaDoc stringBuffer = new StringBuffer JavaDoc();
206             stringBuffer.append("SWidget("); //$NON-NLS-1$
207
stringBuffer.append(id);
208             stringBuffer.append(',');
209             stringBuffer.append(locations);
210             stringBuffer.append(',');
211             try {
212                 stringBuffer.append(thirdPartyCode);
213             } catch (final Exception JavaDoc e) {
214                 // A bogus toString() in third-party code. Ignore.
215
stringBuffer.append(e.getClass().getName());
216             }
217             stringBuffer.append(',');
218             stringBuffer.append(defined);
219             stringBuffer.append(')');
220             string = stringBuffer.toString();
221         }
222         return string;
223     }
224
225     /**
226      * Makes this widget become undefined. This has the side effect of changing
227      * the locations and widget to <code>null</code>. Notification is sent to
228      * all listeners.
229      */

230     public final void undefine() {
231         string = null;
232
233         setWidget(null);
234         setLocations(null);
235         setLayout(null);
236         setDefined(false);
237     }
238 }
239
Popular Tags