KickJava   Java API By Example, From Geeks To Geeks.

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


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
12 package org.eclipse.ui.internal.menus;
13
14 import org.eclipse.core.commands.common.NamedHandleObject;
15 import org.eclipse.core.commands.common.NotDefinedException;
16 import org.eclipse.jface.util.IPropertyChangeListener;
17 import org.eclipse.jface.util.PropertyChangeEvent;
18 import org.eclipse.jface.util.Util;
19
20 /**
21  * <p>
22  * A group of menu elements that can be made visible or invisible as a group.
23  * Action sets can also be associated with particular parts or perspectives. The
24  * end user is also able to enable and disable action sets for a given
25  * perspective.
26  * </p>
27  * <p>
28  * Action sets are defined using the <code>org.eclipse.ui.menus</code>
29  * extension point. They can be associated with parts using the
30  * <code>org.eclipse.ui.actionSetPartAssociations</code> extension point. They
31  * can be associated with perspectives using the
32  * <code>org.eclipse.ui.perspectiveExtensions</code> extension point.
33  * </p>
34  * <p>
35  * Clients may instantiate, but they must extend.
36  * </p>
37  * <p>
38  * <strong>PROVISIONAL</strong>. This class or interface has been added as
39  * part of a work in progress. There is a guarantee neither that this API will
40  * work nor that it will remain the same. Please do not use this API without
41  * consulting with the Platform/UI team.
42  * </p>
43  * <p>
44  * This class will eventually exist in <code>org.eclipse.jface.menus</code>.
45  * </p>
46  *
47  * @since 3.2
48  */

49 public final class SActionSet extends NamedHandleObject {
50
51     /**
52      * The property for a property change event indicating that the defined
53      * state for this action set has changed.
54      */

55     public static final String JavaDoc PROPERTY_DEFINED = "DEFINED"; //$NON-NLS-1$
56

57     /**
58      * The property for a property change event indicating that the description
59      * for this action set has changed.
60      */

61     public static final String JavaDoc PROPERTY_DESCRIPTION = "DESCRIPTION"; //$NON-NLS-1$
62

63     /**
64      * The property for a property change event indicating that the name for
65      * this action set has changed.
66      */

67     public static final String JavaDoc PROPERTY_NAME = "NAME"; //$NON-NLS-1$
68

69     /**
70      * The property for a property change event indicating that the references
71      * for this action set have changed.
72      */

73     public static final String JavaDoc PROPERTY_REFERENCES = "REFERENCES"; //$NON-NLS-1$
74

75     /**
76      * The property for a property change event indicating that the visible
77      * state for this action set has changed.
78      */

79     public static final String JavaDoc PROPERTY_VISIBLE = "VISIBLE"; //$NON-NLS-1$
80

81     /**
82      * References to menu elements in the workbench. These are the menu elements
83      * that are in this action set.
84      */

85     private SReference[] references;
86
87     /**
88      * Whether this action set should be visible in all perspectives by default.
89      */

90     private boolean visible = false;
91
92     /**
93      * Constructs a new instance of <code>SActionSet</code>
94      *
95      * @param id
96      * The identifier of the action set to create; must not be
97      * <code>null</code>.
98      */

99     public SActionSet(final String JavaDoc id) {
100         super(id);
101     }
102
103     /**
104      * Adds a listener to this action set that will be notified when this action
105      * set's state changes.
106      *
107      * @param listener
108      * The listener to be added; must not be <code>null</code>.
109      */

110     public final void addListener(final IPropertyChangeListener listener) {
111         addListenerObject(listener);
112     }
113
114     /**
115      * <p>
116      * Defines this command by giving it a name, visibility and a collection of
117      * references. The description is optional. The defined property
118      * automatically becomes <code>true</code>.
119      * </p>
120      *
121      * @param name
122      * The name of the action set; must not be <code>null</code>.
123      * This name should short (one or two words) and human-readable.
124      * @param description
125      * The description for the action set; may be <code>null</code>
126      * if there is no description. The description can be longer: one
127      * or two sentences.
128      * @param visible
129      * Whether the action set should be visible in all perspective by
130      * default.
131      * @param references
132      * References to the menu elements that are included in this
133      * action set. This value must not be <code>null</code> and it
134      * must not be empty.
135      */

136     public final void define(final String JavaDoc name, final String JavaDoc description,
137             final boolean visible, final SReference[] references) {
138         if (name == null) {
139             throw new NullPointerException JavaDoc("An action set needs a name"); //$NON-NLS-1$
140
}
141
142         if (references == null) {
143             throw new NullPointerException JavaDoc(
144                     "The action set must reference at least one menu element"); //$NON-NLS-1$
145
}
146
147         if (references.length == 0) {
148             throw new IllegalArgumentException JavaDoc(
149                     "The action set must reference at least one menu element"); //$NON-NLS-1$
150
}
151
152         setDefined(true);
153         setName(name);
154         setDescription(description);
155         setVisible(visible);
156         setReferences(references);
157     }
158
159     /**
160      * Notifies listeners to this action set that it has changed in some way.
161      *
162      * @param event
163      * The event to fire; may be <code>null</code>.
164      */

165     protected final void firePropertyChangeEvent(final PropertyChangeEvent event) {
166         if (event == null) {
167             return;
168         }
169
170         final Object JavaDoc[] listeners = getListeners();
171         for (int i = 0; i < listeners.length; i++) {
172             final IPropertyChangeListener listener = (IPropertyChangeListener) listeners[i];
173             listener.propertyChange(event);
174         }
175     }
176
177     /**
178      * Returns the references for this action set. This performs a copy of the
179      * internal data structure.
180      *
181      * @return The references for this action set; never <code>null</code>.
182      * @throws NotDefinedException
183      * If the handle is not currently defined.
184      */

185     public final SReference[] getReferences() throws NotDefinedException {
186         if (!isDefined()) {
187             throw new NotDefinedException(
188                     "Cannot get the references from an undefined action set"); //$NON-NLS-1$
189
}
190
191         final SReference[] result = new SReference[references.length];
192         System.arraycopy(references, 0, result, 0, references.length);
193         return result;
194     }
195
196     /**
197      * Whether the action set should be visible in every perspective by default.
198      *
199      * @return <code>true</code> if the action set is visible in every
200      * perspective; <code>false</code> otherwise.
201      * @throws NotDefinedException
202      * If the handle is not currently defined.
203      */

204     public final boolean isVisible() throws NotDefinedException {
205         if (!isDefined()) {
206             throw new NotDefinedException(
207                     "Cannot get the visibility from an undefined action set"); //$NON-NLS-1$
208
}
209
210         return visible;
211     }
212
213     /**
214      * Removes a listener from this action set.
215      *
216      * @param listener
217      * The listener to be removed; must not be <code>null</code>.
218      */

219     public final void removeListener(final IPropertyChangeListener listener) {
220         addListenerObject(listener);
221     }
222
223     /**
224      * Sets whether this menu element is defined. This will fire a property
225      * change event if anyone cares.
226      *
227      * @param defined
228      * Whether the menu element is defined.
229      */

230     protected final void setDefined(final boolean defined) {
231         if (this.defined != defined) {
232             PropertyChangeEvent event = null;
233             if (isListenerAttached()) {
234                 event = new PropertyChangeEvent(this, PROPERTY_DEFINED,
235                         (this.defined ? Boolean.TRUE : Boolean.FALSE),
236                         (defined ? Boolean.TRUE : Boolean.FALSE));
237             }
238             this.defined = defined;
239             firePropertyChangeEvent(event);
240         }
241     }
242
243     /**
244      * Sets the description that should be displayed for this action set. This
245      * will fire a property change event if anyone cares.
246      *
247      * @param description
248      * The new description for this action set; may be
249      * <code>null</code>.
250      */

251     protected final void setDescription(final String JavaDoc description) {
252         if (!Util.equals(this.description, description)) {
253             PropertyChangeEvent event = null;
254             if (isListenerAttached()) {
255                 event = new PropertyChangeEvent(this, PROPERTY_DESCRIPTION,
256                         this.description, description);
257             }
258             this.description = description;
259             firePropertyChangeEvent(event);
260         }
261     }
262
263     /**
264      * Sets the name that should be displayed for this action set. This will
265      * fire a property change event if anyone cares.
266      *
267      * @param name
268      * The new name for this action set; may be <code>null</code>.
269      */

270     protected final void setName(final String JavaDoc name) {
271         if (!Util.equals(this.name, name)) {
272             PropertyChangeEvent event = null;
273             if (isListenerAttached()) {
274                 event = new PropertyChangeEvent(this, PROPERTY_NAME, this.name,
275                         name);
276             }
277             this.name = name;
278             firePropertyChangeEvent(event);
279         }
280     }
281
282     /**
283      * Sets the references associated with this action set. This will fire a
284      * property change event if anyone cares.
285      *
286      * @param references
287      * The references for this action set; may be <code>null</code>.
288      */

289     protected final void setReferences(final SReference[] references) {
290         if (!Util.equals(this.references, references)) {
291             PropertyChangeEvent event = null;
292             if (isListenerAttached()) {
293                 event = new PropertyChangeEvent(this, PROPERTY_REFERENCES,
294                         this.references, references);
295             }
296             this.references = references;
297             firePropertyChangeEvent(event);
298         }
299     }
300
301     /**
302      * Sets whether this action set should be visible. This will fire a property
303      * change event if anyone cares.
304      *
305      * @param visible
306      * Whether the action set should be visible
307      */

308     protected final void setVisible(final boolean visible) {
309         if (this.visible != visible) {
310             PropertyChangeEvent event = null;
311             if (isListenerAttached()) {
312                 event = new PropertyChangeEvent(this, PROPERTY_VISIBLE,
313                         (this.visible ? Boolean.TRUE : Boolean.FALSE),
314                         (visible ? Boolean.TRUE : Boolean.FALSE));
315             }
316             this.visible = visible;
317             firePropertyChangeEvent(event);
318         }
319     }
320
321     /**
322      * The string representation of this action set -- for debugging purposes
323      * only. This string should not be shown to an end user.
324      *
325      * @return The string representation; never <code>null</code>.
326      */

327     public final String JavaDoc toString() {
328         if (string == null) {
329             final StringBuffer JavaDoc stringBuffer = new StringBuffer JavaDoc();
330             stringBuffer.append("SGroup("); //$NON-NLS-1$
331
stringBuffer.append(id);
332             stringBuffer.append(',');
333             stringBuffer.append(name);
334             stringBuffer.append(',');
335             stringBuffer.append(description);
336             stringBuffer.append(',');
337             stringBuffer.append(visible);
338             stringBuffer.append(',');
339             stringBuffer.append(references);
340             stringBuffer.append(',');
341             stringBuffer.append(defined);
342             stringBuffer.append(')');
343             string = stringBuffer.toString();
344         }
345         return string;
346     }
347
348     /**
349      * Makes this action set become undefined. This has the side effect of
350      * changing the name, description and references to <code>null</code>.
351      * Notification is sent to all listeners.
352      */

353     public final void undefine() {
354         string = null;
355
356         setReferences(references);
357         setVisible(visible);
358         setDescription(description);
359         setName(name);
360         setDefined(false);
361     }
362 }
363
Popular Tags