ICommandImageService


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  
15  import org.eclipse.jface.resource.ImageDescriptor;
16  import org.eclipse.ui.services.IDisposable;
17  
18  /**
19   * <p>
20   * Provides a look-up facility for images associated with commands.
21   * </p>
22   * <p>
23   * The <em>type</em> of an image indicates the state of the associated command
24   * within the user interface. The supported types are: <code>TYPE_DEFAULT</code>
25   * (to be used for an enabled command), <code>TYPE_DISABLED</code> (to be used
26   * for a disabled command) and <code>TYPE_HOVER</code> (to be used for an
27   * enabled command over which the mouse is hovering).
28   * </p>
29   * <p>
30   * The <em>style</em> of an image is an arbitrary string used to distinguish
31   * between sets of images associated with a command. For example, a command may
32   * appear in the menus as the default style. However, in the toolbar, the
33   * command is simply the default action for a toolbar drop down item. As such,
34   * perhaps a different image style is appropriate. The classic case is the "Run
35   * Last Launched" command, which appears in the menu and the toolbar, but with
36   * different icons in each location.
37   * </p>
38   * <p>
39   * This interface should not be implemented or extended by clients.
40   * </p>
41   * <p>
42   * <strong>PROVISIONAL</strong>. This class or interface has been added as
43   * part of a work in progress. There is a guarantee neither that this API will
44   * work nor that it will remain the same. Please do not use this API without
45   * consulting with the Platform/UI team.
46   * </p>
47   * <p>
48   * This class is eventually intended to exist in
49   * <code>org.eclipse.ui.commands</code>.
50   * </p>
51   * 
52   * @since 3.2
53   */
54  public interface ICommandImageService extends IDisposable {
55  
56      /**
57       * The type of image to display in the default case.
58       */
59      public static final int TYPE_DEFAULT = ICommandImageService.TYPE_DEFAULT;
60  
61      /**
62       * The type of image to display if the corresponding command is disabled.
63       */
64      public static final int TYPE_DISABLED = ICommandImageService.TYPE_DISABLED;
65  
66      /**
67       * The type of image to display if the mouse is hovering over the command
68       * and the command is enabled.
69       */
70      public static final int TYPE_HOVER = ICommandImageService.TYPE_HOVER;
71  
72      /**
73       * Binds a particular image descriptor to a command id, type and style
74       * triple
75       * 
76       * @param commandId
77       *            The identifier of the command to which the image should be
78       *            bound; must not be <code>null</code>.
79       * @param type
80       *            The type of image to retrieve. This value must be one of the
81       *            <code>TYPE</code> constants defined in this class.
82       * @param style
83       *            The style of the image; may be <code>null</code>.
84       * @param descriptor
85       *            The image descriptor. Should not be <code>null</code>.
86       */
87      public void bind(String   commandId, int type, String   style,
88              ImageDescriptor descriptor);
89  
90      /**
91       * Binds a particular image path to a command id, type and style triple
92       * 
93       * @param commandId
94       *            The identifier of the command to which the image should be
95       *            bound; must not be <code>null</code>.
96       * @param type
97       *            The type of image to retrieve. This value must be one of the
98       *            <code>TYPE</code> constants defined in this class.
99       * @param style
100      *            The style of the image; may be <code>null</code>.
101      * @param url
102      *            The URL to the image. Should not be <code>null</code>.
103      */
104     public void bind(String   commandId, int type, String   style, URL   url);
105 
106     /**
107      * Generates a style tag that is not currently used for the given command.
108      * This can be used by applications trying to create a unique style for a
109      * new set of images.
110      * 
111      * @param commandId
112      *            The identifier of the command for which a unique style is
113      *            required; must not be <code>null</code>.
114      * @return A style tag that is not currently used; may be <code>null</code>.
115      */
116     public String   generateUnusedStyle(String   commandId);
117 
118     /**
119      * Retrieves the default image associated with the given command in the
120      * default style.
121      * 
122      * @param commandId
123      *            The identifier to find; must not be <code>null</code>.
124      * @return An image appropriate for the given command; may be
125      *         <code>null</code>.
126      */
127     public ImageDescriptor getImageDescriptor(String   commandId);
128 
129     /**
130      * Retrieves the image of the given type associated with the given command
131      * in the default style.
132      * 
133      * @param commandId
134      *            The identifier to find; must not be <code>null</code>.
135      * 
136      * @param type
137      *            The type of image to retrieve. This value must be one of the
138      *            <code>TYPE</code> constants defined in this interface.
139      * @return An image appropriate for the given command; <code>null</code>
140      *         if the given image type cannot be found.
141      */
142     public ImageDescriptor getImageDescriptor(String   commandId, int type);
143 
144     /**
145      * Retrieves the image of the given type associated with the given command
146      * in the given style.
147      * 
148      * @param commandId
149      *            The identifier to find; must not be <code>null</code>.
150      * @param type
151      *            The type of image to retrieve. This value must be one of the
152      *            <code>TYPE</code> constants defined in this interface.
153      * @param style
154      *            The style of the image to retrieve; may be <code>null</code>.
155      * @return An image appropriate for the given command; <code>null</code>
156      *         if the given image style and type cannot be found.
157      */
158     public ImageDescriptor getImageDescriptor(String   commandId, int type,
159             String   style);
160 
161     /**
162      * Retrieves the default image associated with the given command in the
163      * given style.
164      * 
165      * @param commandId
166      *            The identifier to find; must not be <code>null</code>.
167      * @param style
168      *            The style of the image to retrieve; may be <code>null</code>.
169      * @return An image appropriate for the given command; <code>null</code>
170      *         if the given image style cannot be found.
171      */
172     public ImageDescriptor getImageDescriptor(String   commandId, String   style);
173 
174     /**
175      * <p>
176      * Reads the command image information from the registry. This will
177      * overwrite any of the existing information in the command image service.
178      * This method is intended to be called during start-up. When this method
179      * completes, this command image service will reflect the current state of
180      * the registry.
181      * </p>
182      */
183     public void readRegistry();
184 }
185
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags