KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > ui > internal > commands > CommandImageManager


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.commands;
12
13 import java.net.URL JavaDoc;
14 import java.util.HashMap JavaDoc;
15 import java.util.HashSet JavaDoc;
16 import java.util.Map JavaDoc;
17 import java.util.Set JavaDoc;
18
19 import org.eclipse.core.commands.common.EventManager;
20 import org.eclipse.jface.resource.ImageDescriptor;
21
22 /**
23  * <p>
24  * A central lookup facility for images for commands. Images can be associated
25  * with commands using this manager.
26  * </p>
27  * <p>
28  * Clients may instantiate, but must not extend.
29  * </p>
30  * <p>
31  * <strong>PROVISIONAL</strong>. This class or interface has been added as
32  * part of a work in progress. There is a guarantee neither that this API will
33  * work nor that it will remain the same. Please do not use this API without
34  * consulting with the Platform/UI team.
35  * </p>
36  * <p>
37  * This class is eventually intended to exist in
38  * <code>org.eclipse.jface.commands</code>.
39  * </p>
40  *
41  * @since 3.2
42  */

43 public final class CommandImageManager extends EventManager {
44
45     /**
46      * The type of image to display in the default case.
47      */

48     public static final int TYPE_DEFAULT = 0;
49
50     /**
51      * The type of image to display if the corresponding command is disabled.
52      */

53     public static final int TYPE_DISABLED = 1;
54
55     /**
56      * The type of image to display if the mouse is hovering over the command
57      * and the command is enabled.
58      */

59     public static final int TYPE_HOVER = 2;
60
61     /**
62      * The map of command identifiers (<code>String</code>) to images. The
63      * images are an array indexed by type. The values in the array are either
64      * an <code>ImageDescriptor</code> or a <code>Map</code> of style (<code>String</code>)
65      * to <code>ImageDescriptor</code>.
66      */

67     private final Map JavaDoc imagesById = new HashMap JavaDoc();
68
69     /**
70      * Adds a listener to this command image manager. The listener will be
71      * notified when the set of image bindings changes. This can be used to
72      * track the global appearance and disappearance of image bindings.
73      *
74      * @param listener
75      * The listener to attach; must not be <code>null</code>.
76      */

77     public final void addCommandImageManagerListener(
78             final ICommandImageManagerListener listener) {
79         addListenerObject(listener);
80     }
81
82     /**
83      * Binds a particular image path to a command id, type and style triple
84      *
85      * @param commandId
86      * The identifier of the command to which the image should be
87      * bound; must not be <code>null</code>.
88      * @param type
89      * The type of image to retrieve. This value must be one of the
90      * <code>TYPE</code> constants defined in this class.
91      * @param style
92      * The style of the image; may be <code>null</code>.
93      * @param url
94      * The URL to the image. Should not be <code>null</code>.
95      */

96     public final void bind(final String JavaDoc commandId, final int type,
97             final String JavaDoc style, final URL JavaDoc url) {
98         final ImageDescriptor descriptor = ImageDescriptor.createFromURL(url);
99         bind(commandId, type, style, descriptor);
100     }
101
102     /**
103      * Binds a particular image path to a command id, type and style triple
104      *
105      * @param commandId
106      * The identifier of the command to which the image should be
107      * bound; must not be <code>null</code>.
108      * @param type
109      * The type of image to retrieve. This value must be one of the
110      * <code>TYPE</code> constants defined in this class.
111      * @param style
112      * The style of the image; may be <code>null</code>.
113      * @param descriptor
114      * The image descriptor. Should not be <code>null</code>.
115      */

116     public final void bind(final String JavaDoc commandId, final int type,
117             final String JavaDoc style, final ImageDescriptor descriptor) {
118         Object JavaDoc[] images = (Object JavaDoc[]) imagesById.get(commandId);
119         if (images == null) {
120             images = new Object JavaDoc[3];
121             imagesById.put(commandId, images);
122         }
123
124         if ((type < 0) || (type >= images.length)) {
125             throw new IllegalArgumentException JavaDoc(
126                     "The type must be one of TYPE_DEFAULT, TYPE_DISABLED and TYPE_HOVER."); //$NON-NLS-1$
127
}
128
129         final Object JavaDoc typedImage = images[type];
130         if (style == null) {
131             if ((typedImage == null) || (typedImage instanceof ImageDescriptor)) {
132                 images[type] = descriptor;
133             } else if (typedImage instanceof Map JavaDoc) {
134                 final Map JavaDoc styleMap = (Map JavaDoc) typedImage;
135                 styleMap.put(style, descriptor);
136             }
137         } else {
138             if (typedImage instanceof Map JavaDoc) {
139                 final Map JavaDoc styleMap = (Map JavaDoc) typedImage;
140                 styleMap.put(style, descriptor);
141             } else if (typedImage instanceof ImageDescriptor) {
142                 final Map JavaDoc styleMap = new HashMap JavaDoc();
143                 styleMap.put(null, typedImage);
144                 styleMap.put(style, descriptor);
145                 images[type] = descriptor;
146             }
147         }
148
149         fireManagerChanged(new CommandImageManagerEvent(this,
150                 new String JavaDoc[] { commandId }, type, style));
151     }
152
153     /**
154      * Removes all of the images from this manager.
155      */

156     public final void clear() {
157         imagesById.clear();
158         if (isListenerAttached()) {
159             final String JavaDoc[] commandIds = (String JavaDoc[]) imagesById.keySet().toArray(
160                     new String JavaDoc[imagesById.size()]);
161             fireManagerChanged(new CommandImageManagerEvent(this, commandIds,
162                     TYPE_DEFAULT, null));
163         }
164     }
165
166     /**
167      * Notifies all of the listeners to this manager that the image bindings
168      * have changed.
169      *
170      * @param event
171      * The event to send to all of the listeners; must not be
172      * <code>null</code>.
173      */

174     private final void fireManagerChanged(final CommandImageManagerEvent event) {
175         if (event == null) {
176             throw new NullPointerException JavaDoc();
177         }
178
179         final Object JavaDoc[] listeners = getListeners();
180         for (int i = 0; i < listeners.length; i++) {
181             final ICommandImageManagerListener listener = (ICommandImageManagerListener) listeners[i];
182             listener.commandImageManagerChanged(event);
183         }
184     }
185
186     /**
187      * Generates a style tag that is not currently used for the given command.
188      * This can be used by applications trying to create a unique style for a
189      * new set of images.
190      *
191      * @param commandId
192      * The identifier of the command for which a unique style is
193      * required; must not be <code>null</code>.
194      * @return A style tag that is not currently used; may be <code>null</code>.
195      */

196     public final String JavaDoc generateUnusedStyle(final String JavaDoc commandId) {
197         final Object JavaDoc[] existingImages = (Object JavaDoc[]) imagesById.get(commandId);
198         if (existingImages == null) {
199             return null;
200         }
201
202         final Set JavaDoc existingStyles = new HashSet JavaDoc(3);
203         for (int type = 0; type < existingImages.length; type++) {
204             final Object JavaDoc styledImages = existingImages[type];
205             if (styledImages instanceof ImageDescriptor) {
206                 existingStyles.add(null);
207             } else if (styledImages instanceof Map JavaDoc) {
208                 final Map JavaDoc styleMap = (Map JavaDoc) styledImages;
209                 existingStyles.addAll(styleMap.keySet());
210             }
211         }
212
213         if (!existingStyles.contains(null)) {
214             return null;
215         }
216
217         String JavaDoc generatedStyle = "AUTOGEN:::"; //$NON-NLS-1$
218
int index = 0;
219         while (existingStyles.contains(generatedStyle)) {
220             generatedStyle += (index++ % 10);
221         }
222
223         return generatedStyle;
224     }
225
226     /**
227      * Retrieves the default image associated with the given command in the
228      * default style.
229      *
230      * @param commandId
231      * The identifier to find; must not be <code>null</code>.
232      * @return An image appropriate for the given command; never
233      * <code>null</code>.
234      */

235     public final ImageDescriptor getImageDescriptor(final String JavaDoc commandId) {
236         return getImageDescriptor(commandId, TYPE_DEFAULT, null);
237     }
238
239     /**
240      * Retrieves the image of the given type associated with the given command
241      * in the default style.
242      *
243      * @param commandId
244      * The identifier to find; must not be <code>null</code>.
245      * @param type
246      * The type of image to retrieve. This value must be one of the
247      * <code>TYPE</code> constants defined in this class.
248      * @return An image appropriate for the given command; <code>null</code>
249      * if the given image type cannot be found.
250      */

251     public final ImageDescriptor getImageDescriptor(final String JavaDoc commandId,
252             final int type) {
253         return getImageDescriptor(commandId, type, null);
254     }
255
256     /**
257      * Retrieves the image of the given type associated with the given command
258      * in the given style.
259      *
260      * @param commandId
261      * The identifier to find; must not be <code>null</code>.
262      * @param type
263      * The type of image to retrieve. This value must be one of the
264      * <code>TYPE</code> constants defined in this class.
265      * @param style
266      * The style of the image to retrieve; may be <code>null</code>.
267      * @return An image appropriate for the given command; <code>null</code>
268      * if the given image style and type cannot be found.
269      */

270     public final ImageDescriptor getImageDescriptor(final String JavaDoc commandId,
271             final int type, final String JavaDoc style) {
272         if (commandId == null) {
273             throw new NullPointerException JavaDoc();
274         }
275
276         final Object JavaDoc[] images = (Object JavaDoc[]) imagesById.get(commandId);
277         if (images == null) {
278             return null;
279         }
280
281         if ((type < 0) || (type >= images.length)) {
282             throw new IllegalArgumentException JavaDoc(
283                     "The type must be one of TYPE_DEFAULT, TYPE_DISABLED and TYPE_HOVER."); //$NON-NLS-1$
284
}
285
286         Object JavaDoc typedImage = images[type];
287
288         if (typedImage == null) {
289             typedImage = images[TYPE_DEFAULT];
290         }
291
292         if (typedImage instanceof ImageDescriptor) {
293             return (ImageDescriptor) typedImage;
294         }
295
296         if (typedImage instanceof Map JavaDoc) {
297             final Map JavaDoc styleMap = (Map JavaDoc) typedImage;
298             Object JavaDoc styledImage = styleMap.get(style);
299             if (styledImage instanceof ImageDescriptor) {
300                 return (ImageDescriptor) styledImage;
301             }
302
303             if (style != null) {
304                 styledImage = styleMap.get(null);
305                 if (styledImage instanceof ImageDescriptor) {
306                     return (ImageDescriptor) styledImage;
307                 }
308             }
309         }
310
311         return null;
312     }
313
314     /**
315      * Retrieves the default image associated with the given command in the
316      * given style.
317      *
318      * @param commandId
319      * The identifier to find; must not be <code>null</code>.
320      * @param style
321      * The style of the image to retrieve; may be <code>null</code>.
322      * @return An image appropriate for the given command; <code>null</code>
323      * if the given image style cannot be found.
324      */

325     public final ImageDescriptor getImageDescriptor(final String JavaDoc commandId,
326             final String JavaDoc style) {
327         return getImageDescriptor(commandId, TYPE_DEFAULT, style);
328     }
329
330     /**
331      * Removes a listener from this command image manager.
332      *
333      * @param listener
334      * The listener to be removed; must not be <code>null</code>.
335      */

336     public final void removeCommandImageManagerListener(
337             final ICommandImageManagerListener listener) {
338         removeListenerObject(listener);
339     }
340 }
341
Popular Tags