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  ;
14  import java.util.HashMap  ;
15  import java.util.HashSet  ;
16  import java.util.Map  ;
17  import java.util.Set  ;
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   imagesById = new HashMap  ();
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   commandId, final int type,
97              final String   style, final URL   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   commandId, final int type,
117             final String   style, final ImageDescriptor descriptor) {
118         Object  [] images = (Object  []) imagesById.get(commandId);
119         if (images == null) {
120             images = new Object  [3];
121             imagesById.put(commandId, images);
122         }
123 
124         if ((type < 0) || (type >= images.length)) {
125             throw new IllegalArgumentException  (
126                     "The type must be one of TYPE_DEFAULT, TYPE_DISABLED and TYPE_HOVER."); //$NON-NLS-1$
127         }
128 
129         final Object   typedImage = images[type];
130         if (style == null) {
131             if ((typedImage == null) || (typedImage instanceof ImageDescriptor)) {
132                 images[type] = descriptor;
133             } else if (typedImage instanceof Map  ) {
134                 final Map   styleMap = (Map  ) typedImage;
135                 styleMap.put(style, descriptor);
136             }
137         } else {
138             if (typedImage instanceof Map  ) {
139                 final Map   styleMap = (Map  ) typedImage;
140                 styleMap.put(style, descriptor);
141             } else if (typedImage instanceof ImageDescriptor) {
142                 final Map   styleMap = new HashMap  ();
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  [] { 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  [] commandIds = (String  []) imagesById.keySet().toArray(
160                     new String  [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  ();
177         }
178 
179         final Object  [] 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   generateUnusedStyle(final String   commandId) {
197         final Object  [] existingImages = (Object  []) imagesById.get(commandId);
198         if (existingImages == null) {
199             return null;
200         }
201 
202         final Set   existingStyles = new HashSet  (3);
203         for (int type = 0; type < existingImages.length; type++) {
204             final Object   styledImages = existingImages[type];
205             if (styledImages instanceof ImageDescriptor) {
206                 existingStyles.add(null);
207             } else if (styledImages instanceof Map  ) {
208                 final Map   styleMap = (Map  ) styledImages;
209                 existingStyles.addAll(styleMap.keySet());
210             }
211         }
212 
213         if (!existingStyles.contains(null)) {
214             return null;
215         }
216 
217         String   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   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   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   commandId,
271             final int type, final String   style) {
272         if (commandId == null) {
273             throw new NullPointerException  ();
274         }
275 
276         final Object  [] images = (Object  []) imagesById.get(commandId);
277         if (images == null) {
278             return null;
279         }
280 
281         if ((type < 0) || (type >= images.length)) {
282             throw new IllegalArgumentException  (
283                     "The type must be one of TYPE_DEFAULT, TYPE_DISABLED and TYPE_HOVER."); //$NON-NLS-1$
284         }
285 
286         Object   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  ) {
297             final Map   styleMap = (Map  ) typedImage;
298             Object   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   commandId,
326             final String   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags