KickJava   Java API By Example, From Geeks To Geeks.

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


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