KickJava   Java API By Example, From Geeks To Geeks.

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


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.Command;
14 import org.eclipse.core.commands.ParameterizedCommand;
15 import org.eclipse.core.commands.common.NotDefinedException;
16 import org.eclipse.jface.util.PropertyChangeEvent;
17 import org.eclipse.jface.util.Util;
18
19 /**
20  * <p>
21  * An item in a menu, tool bar or status line. An item is characterized as a
22  * button of some kind, that executes a command when clicked. An item can
23  * optionally
24  * </p>
25  * <p>
26  * Clients may instantiate this class, but must not extend.
27  * </p>
28  * <p>
29  * <strong>PROVISIONAL</strong>. This class or interface has been added as
30  * part of a work in progress. There is a guarantee neither that this API will
31  * work nor that it will remain the same. Please do not use this API without
32  * consulting with the Platform/UI team.
33  * </p>
34  * <p>
35  * This class will eventually exist in <code>org.eclipse.jface.menus</code>.
36  * </p>
37  *
38  * @since 3.2
39  */
40 public final class SItem extends MenuElement {
41
42     /**
43      * The property for a property change event indicating that whether the
44      * command for this item has changed.
45      */
46     public static final String JavaDoc PROPERTY_COMMAND = "COMMAND"; //$NON-NLS-1$
47
48     /**
49      * The property for a property change event indicating that whether the menu
50      * id for this item has changed.
51      */
52     public static final String JavaDoc PROPERTY_MENU_ID = "MENU_ID"; //$NON-NLS-1$
53
54     /**
55      * The command that should be executed when this item is clicked. This value
56      * must not be <code>null</code>.
57      */
58     private ParameterizedCommand command;
59
60     /**
61      * The identifier of the menu attached to this item. This menu will be shown
62      * when the user performs some action. This member variable may be
63      * <code>null</code> if there is no menu associated.
64      */
65     private String JavaDoc menuId;
66
67     /**
68      * Constructs a new instance of <code>SItem</code>.
69      *
70      * @param id
71      * The identifier of the item to create; must not be
72      * <code>null</code>
73      */
74     SItem(final String JavaDoc id) {
75         super(id);
76     }
77
78     /**
79      * <p>
80      * Defines this item by providing a command with no parameters. The location
81      * is optional. The defined property automatically becomes <code>true</code>.
82      * </p>
83      *
84      * @param command
85      * The fully-parameterized command to execute when this item is
86      * triggered; must not be <code>null</code>.
87      * @param location
88      * The location in which this item will appear; may be
89      * <code>null</code>.
90      */
91     public final void define(final Command command, final SLocation location) {
92         final ParameterizedCommand parameterizedCommand = new ParameterizedCommand(
93                 command, null);
94         define(parameterizedCommand, null, location);
95     }
96
97     /**
98      * <p>
99      * Defines this item by providing the fully-parameterized command. The
100      * location is optional. The defined property automatically becomes
101      * <code>true</code>.
102      * </p>
103      *
104      * @param command
105      * The fully-parameterized command to execute when this item is
106      * triggered; must not be <code>null</code>.
107      * @param location
108      * The location in which this item will appear; may be
109      * <code>null</code>.
110      */
111     public final void define(final ParameterizedCommand command,
112             final SLocation location) {
113         define(command, null, location);
114     }
115
116     /**
117      * <p>
118      * Defines this item by providing the fully-parameterized command. The
119      * location and menu identifier are optional. The defined property
120      * automatically becomes <code>true</code>.
121      * </p>
122      *
123      * @param command
124      * The fully-parameterized command to execute when this item is
125      * triggered; must not be <code>null</code>.
126      * @param menuId
127      * The identifier of the menu to display along with this item;
128      * may be <code>null</code> if there is no such menu.
129      * @param location
130      * The location in which this item will appear; may be
131      * <code>null</code>.
132      */
133     public final void define(final ParameterizedCommand command,
134             final String JavaDoc menuId, final SLocation location) {
135         final SLocation[] locations;
136         if (location == null) {
137             locations = null;
138         } else {
139             locations = new SLocation[] { location };
140         }
141         define(command, menuId, locations);
142     }
143
144     /**
145      * <p>
146      * Defines this item by providing the fully-parameterized command. The
147      * locations and menu identifier are optional. The defined property
148      * automatically becomes <code>true</code>.
149      * </p>
150      *
151      * @param command
152      * The fully-parameterized command to execute when this item is
153      * triggered; must not be <code>null</code>.
154      * @param menuId
155      * The identifier of the menu to display along with this item;
156      * may be <code>null</code> if there is no such menu.
157      * @param locations
158      * The locations in which this item will appear; may be
159      * <code>null</code> or empty.
160      */
161     public final void define(final ParameterizedCommand command,
162             final String JavaDoc menuId, final SLocation[] locations) {
163         if (command == null) {
164             throw new NullPointerException JavaDoc("An item needs a command"); //$NON-NLS-1$
165 }
166
167         setCommand(command);
168         setMenuId(menuId);
169         setLocations(locations);
170         setDefined(true);
171     }
172
173     /**
174      * Returns the fully-parameterized command that is triggered by this item.
175      *
176      * @return The command for this item; never <code>null</code>.
177      * @throws NotDefinedException
178      * If the handle is not currently defined.
179      */
180     public final ParameterizedCommand getCommand() throws NotDefinedException {
181         if (!isDefined()) {
182             throw new NotDefinedException(
183                     "Cannot get the command from an undefined item"); //$NON-NLS-1$
184 }
185
186         return command;
187     }
188
189     /**
190      * Returns the identifier of the menu that is associated with this item.
191      *
192      * @return The menu for this item; never <code>null</code>.
193      * @throws NotDefinedException
194      * If the handle is not currently defined.
195      */
196     public final String JavaDoc getMenuId() throws NotDefinedException {
197         if (!isDefined()) {
198             throw new NotDefinedException(
199                     "Cannot get the menu from an undefined item"); //$NON-NLS-1$
200 }
201
202         return menuId;
203     }
204
205     /**
206      * Sets the command for this item. This will fire a property change event if
207      * anyone cares.
208      *
209      * @param command
210      * The new command for this item; may be <code>null</code>.
211      */
212     protected final void setCommand(final ParameterizedCommand command) {
213         if (!Util.equals(this.command, command)) {
214             PropertyChangeEvent event = null;
215             if (isListenerAttached()) {
216                 event = new PropertyChangeEvent(this, PROPERTY_COMMAND,
217                         this.command, command);
218             }
219             this.command = command;
220             firePropertyChangeEvent(event);
221         }
222     }
223
224     /**
225      * Sets the menu id for this item. This will fire a property change event if
226      * anyone cares.
227      *
228      * @param menuId
229      * The new menu id for this item; may be <code>null</code>.
230      */
231     protected final void setMenuId(final String JavaDoc menuId) {
232         if (!Util.equals(this.menuId, menuId)) {
233             PropertyChangeEvent event = null;
234             if (isListenerAttached()) {
235                 event = new PropertyChangeEvent(this, PROPERTY_MENU_ID,
236                         this.menuId, menuId);
237             }
238             this.menuId = menuId;
239             firePropertyChangeEvent(event);
240         }
241     }
242
243     /**
244      * The string representation of this item -- for debugging purposes only.
245      * This string should not be shown to an end user.
246      *
247      * @return The string representation; never <code>null</code>.
248      */
249     public final String JavaDoc toString() {
250         if (string == null) {
251             final StringBuffer JavaDoc stringBuffer = new StringBuffer JavaDoc();
252             stringBuffer.append("SItem("); //$NON-NLS-1$
253 stringBuffer.append(id);
254             stringBuffer.append(',');
255             stringBuffer.append(command);
256             stringBuffer.append(',');
257             stringBuffer.append(menuId);
258             stringBuffer.append(',');
259             stringBuffer.append(locations);
260             stringBuffer.append(',');
261             stringBuffer.append(defined);
262             stringBuffer.append(')');
263             string = stringBuffer.toString();
264         }
265         return string;
266     }
267
268     /**
269      * Makes this item become undefined. This has the side effect of changing
270      * the command, menu id and locations to <code>null</code>. Notification
271      * is sent to all listeners.
272      */
273     public final void undefine() {
274         string = null;
275
276         setCommand(null);
277         setMenuId(null);
278         setLocations(null);
279         setDefined(false);
280     }
281
282 }
283
Popular Tags