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   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   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   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   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   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   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   name, final String   description,
137             final boolean visible, final SReference[] references) {
138         if (name == null) {
139             throw new NullPointerException  ("An action set needs a name"); //$NON-NLS-1$
140         }
141 
142         if (references == null) {
143             throw new NullPointerException  (
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  (
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  [] 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   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   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   toString() {
328         if (string == null) {
329             final StringBuffer   stringBuffer = new StringBuffer  ();
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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags