SMenu


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.util.PropertyChangeEvent;
15  import org.eclipse.jface.util.Util;
16  
17  /**
18   * <p>
19   * A menu in a menu bar, a context menu or a pulldown menu attached to a tool
20   * item.
21   * </p>
22   * <p>
23   * Clients may instantiate this class, but must not extend.
24   * </p>
25   * <p>
26   * <strong>PROVISIONAL</strong>. This class or interface has been added as
27   * part of a work in progress. There is a guarantee neither that this API will
28   * work nor that it will remain the same. Please do not use this API without
29   * consulting with the Platform/UI team.
30   * </p>
31   * <p>
32   * This class will eventually exist in <code>org.eclipse.jface.menus</code>.
33   * </p>
34   * 
35   * @since 3.2
36   */
37  public final class SMenu extends MenuContainer {
38  
39      /**
40       * The property for a property change event indicating that whether the
41       * label for this menu has changed.
42       */
43      public static final String   PROPERTY_LABEL = "LABEL"; //$NON-NLS-1$
44  
45      /**
46       * The label for this menu. This label is displayed to the user. It may be
47       * <code>null</code>, if it appears only as an icon.
48       */
49      private String   label;
50  
51      /**
52       * Constructs a new instance of <code>SMenu</code>.
53       * 
54       * @param id
55       *            The identifier of the menu to create; must not be
56       *            <code>null</code>
57       */
58      SMenu(final String   id) {
59          super(id);
60      }
61  
62      /**
63       * <p>
64       * Defines this menu by indicating the label. The location is optional. The
65       * defined property automatically becomes <code>true</code>.
66       * </p>
67       * 
68       * @param label
69       *            The label for this menu; may be <code>null</code>.
70       * @param location
71       *            The location in which this menu will appear; may be
72       *            <code>null</code>.
73       */
74      public final void define(final String   label, SLocation location) {
75          define(label, location, null);
76      }
77  
78      /**
79       * <p>
80       * Defines this menu by indicating the label. The locations and dynamic menu
81       * are optional. The defined property automatically becomes
82       * <code>true</code>.
83       * </p>
84       * 
85       * @param label
86       *            The label for this menu; may be <code>null</code>.
87       * @param location
88       *            The location in which this menu will appear; may be
89       *            <code>null</code>.
90       * @param dynamic
91       *            The class providing dynamic menu elements to this group; may
92       *            be <code>null</code>.
93       */
94      public final void define(final String   label, SLocation location,
95              final IDynamicMenu dynamic) {
96          final SLocation[] locations;
97          if (location == null) {
98              locations = null;
99          } else {
100             locations = new SLocation[] { location };
101         }
102         define(label, locations, dynamic);
103     }
104 
105     /**
106      * <p>
107      * Defines this menu by indicating the label. The locations and dynamic menu
108      * are optional. The defined property automatically becomes
109      * <code>true</code>.
110      * </p>
111      * 
112      * @param label
113      *            The label for this menu; may be <code>null</code>.
114      * @param locations
115      *            The locations in which this menu will appear; may be
116      *            <code>null</code> or empty.
117      * @param dynamic
118      *            The class providing dynamic menu elements to this group; may
119      *            be <code>null</code>.
120      */
121     public final void define(final String   label, SLocation[] locations,
122             final IDynamicMenu dynamic) {
123         if ((locations != null) && (locations.length == 0)) {
124             locations = null;
125         }
126 
127         setDefined(true);
128         setLocations(locations);
129         setDynamic(dynamic);
130         setLabel(label);
131     }
132 
133     /**
134      * Returns the label for this menu. A menu does not need a label if its is
135      * simply a pulldown menu on a tool item.
136      * 
137      * @return The label for this menu; may be <code>null</code>.
138      * @throws NotDefinedException
139      *             If the handle is not currently defined.
140      */
141     public final String   getLabel() throws NotDefinedException {
142         if (!isDefined()) {
143             throw new NotDefinedException(
144                     "Cannot get the label from an undefined menu"); //$NON-NLS-1$
145         }
146 
147         return label;
148     }
149 
150     /**
151      * Sets the label that should be displayed for this menu. This will fire a
152      * property change event if anyone cares.
153      * 
154      * @param label
155      *            The new label for this menu; may be <code>null</code>.
156      */
157     protected final void setLabel(final String   label) {
158         if (!Util.equals(this.label, label)) {
159             PropertyChangeEvent event = null;
160             if (isListenerAttached()) {
161                 event = new PropertyChangeEvent(this, PROPERTY_LABEL,
162                         this.label, label);
163             }
164             this.label = label;
165             firePropertyChangeEvent(event);
166         }
167     }
168 
169     /**
170      * The string representation of this menu -- for debugging purposes only.
171      * This string should not be shown to an end user.
172      * 
173      * @return The string representation; never <code>null</code>.
174      */
175     public final String   toString() {
176         if (string == null) {
177             final StringBuffer   stringBuffer = new StringBuffer  ();
178             stringBuffer.append("SMenu("); //$NON-NLS-1$
179             stringBuffer.append(id);
180             stringBuffer.append(',');
181             stringBuffer.append(label);
182             stringBuffer.append(',');
183             try {
184                 stringBuffer.append(dynamic);
185             } catch (final Exception   e) {
186                 // A bogus toString() in third-party code. Ignore.
187                 stringBuffer.append(e.getClass().getName());
188             }
189             stringBuffer.append(',');
190             stringBuffer.append(defined);
191             stringBuffer.append(')');
192             string = stringBuffer.toString();
193         }
194         return string;
195     }
196 
197     /**
198      * Makes this menu become undefined. This has the side effect of changing
199      * the label, locations and dynamic class to <code>null</code>.
200      * Notification is sent to all listeners.
201      */
202     public final void undefine() {
203         string = null;
204 
205         setLabel(null);
206         setDynamic(null);
207         setLocations(null);
208         setDefined(false);
209     }
210 }
211
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags