KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > core > commands > Category


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.core.commands;
12
13 import java.util.ArrayList JavaDoc;
14 import java.util.Collection JavaDoc;
15 import java.util.Iterator JavaDoc;
16
17 import org.eclipse.core.commands.common.NamedHandleObject;
18 import org.eclipse.core.internal.commands.util.Util;
19
20 /**
21  * <p>
22  * A logical group for a set of commands. A command belongs to exactly one
23  * category. The category has no functional effect, but may be used in graphical
24  * tools that want to group the set of commands somehow.
25  * </p>
26  *
27  * @since 3.1
28  */
29 public final class Category extends NamedHandleObject {
30
31     /**
32      * A collection of objects listening to changes to this category. This
33      * collection is <code>null</code> if there are no listeners.
34      */
35     private Collection JavaDoc categoryListeners;
36
37     /**
38      * Constructs a new instance of <code>Category</code> based on the given
39      * identifier. When a category is first constructed, it is undefined.
40      * Category should only be constructed by the <code>CommandManager</code>
41      * to ensure that identifier remain unique.
42      *
43      * @param id
44      * The identifier for the category. This value must not be
45      * <code>null</code>, and must be unique amongst all
46      * categories.
47      */
48     Category(final String JavaDoc id) {
49         super(id);
50     }
51
52     /**
53      * Adds a listener to this category that will be notified when this
54      * category's state changes.
55      *
56      * @param categoryListener
57      * The listener to be added; must not be <code>null</code>.
58      */
59     public final void addCategoryListener(
60             final ICategoryListener categoryListener) {
61         if (categoryListener == null) {
62             throw new NullPointerException JavaDoc();
63         }
64         if (categoryListeners == null) {
65             categoryListeners = new ArrayList JavaDoc();
66         }
67         if (!categoryListeners.contains(categoryListener)) {
68             categoryListeners.add(categoryListener);
69         }
70     }
71
72     /**
73      * <p>
74      * Defines this category by giving it a name, and possibly a description as
75      * well. The defined property automatically becomes <code>true</code>.
76      * </p>
77      * <p>
78      * Notification is sent to all listeners that something has changed.
79      * </p>
80      *
81      * @param name
82      * The name of this command; must not be <code>null</code>.
83      * @param description
84      * The description for this command; may be <code>null</code>.
85      */
86     public final void define(final String JavaDoc name, final String JavaDoc description) {
87         if (name == null) {
88             throw new NullPointerException JavaDoc(
89                     "The name of a command cannot be null"); //$NON-NLS-1$
90 }
91
92         final boolean definedChanged = !this.defined;
93         this.defined = true;
94
95         final boolean nameChanged = !Util.equals(this.name, name);
96         this.name = name;
97
98         final boolean descriptionChanged = !Util.equals(this.description,
99                 description);
100         this.description = description;
101
102         fireCategoryChanged(new CategoryEvent(this, definedChanged,
103                 descriptionChanged, nameChanged));
104     }
105
106     /**
107      * Notifies the listeners for this category that it has changed in some way.
108      *
109      * @param categoryEvent
110      * The event to send to all of the listener; must not be
111      * <code>null</code>.
112      */
113     private final void fireCategoryChanged(final CategoryEvent categoryEvent) {
114         if (categoryEvent == null) {
115             throw new NullPointerException JavaDoc();
116         }
117         if (categoryListeners != null) {
118             final Iterator JavaDoc listenerItr = categoryListeners.iterator();
119             while (listenerItr.hasNext()) {
120                 final ICategoryListener listener = (ICategoryListener) listenerItr
121                         .next();
122                 listener.categoryChanged(categoryEvent);
123             }
124         }
125     }
126
127     /**
128      * Removes a listener from this category.
129      *
130      * @param categoryListener
131      * The listener to be removed; must not be <code>null</code>.
132      *
133      */
134     public final void removeCategoryListener(
135             final ICategoryListener categoryListener) {
136         if (categoryListener == null) {
137             throw new NullPointerException JavaDoc();
138         }
139
140         if (categoryListeners != null) {
141             categoryListeners.remove(categoryListener);
142         }
143     }
144
145     /*
146      * (non-Javadoc)
147      *
148      * @see org.eclipse.core.commands.common.HandleObject#toString()
149      */
150     public String JavaDoc toString() {
151         if (string == null) {
152             final StringBuffer JavaDoc stringBuffer = new StringBuffer JavaDoc();
153             stringBuffer.append("Category("); //$NON-NLS-1$
154 stringBuffer.append(id);
155             stringBuffer.append(',');
156             stringBuffer.append(name);
157             stringBuffer.append(',');
158             stringBuffer.append(description);
159             stringBuffer.append(',');
160             stringBuffer.append(defined);
161             stringBuffer.append(')');
162             string = stringBuffer.toString();
163         }
164         return string;
165     }
166
167     /*
168      * (non-Javadoc)
169      *
170      * @see org.eclipse.core.commands.common.HandleObject#undefine()
171      */
172     public void undefine() {
173         string = null;
174
175         final boolean definedChanged = defined;
176         defined = false;
177
178         final boolean nameChanged = name != null;
179         name = null;
180
181         final boolean descriptionChanged = description != null;
182         description = null;
183
184         fireCategoryChanged(new CategoryEvent(this, definedChanged,
185                 descriptionChanged, nameChanged));
186     }
187
188 }
189
Popular Tags