001: /*******************************************************************************
002: * Copyright (c) 2005, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui.internal.commands;
011:
012: import java.net.URL;
013:
014: import org.eclipse.jface.resource.ImageDescriptor;
015: import org.eclipse.ui.services.IDisposable;
016:
017: /**
018: * <p>
019: * Provides a look-up facility for images associated with commands.
020: * </p>
021: * <p>
022: * The <em>type</em> of an image indicates the state of the associated command
023: * within the user interface. The supported types are: <code>TYPE_DEFAULT</code>
024: * (to be used for an enabled command), <code>TYPE_DISABLED</code> (to be used
025: * for a disabled command) and <code>TYPE_HOVER</code> (to be used for an
026: * enabled command over which the mouse is hovering).
027: * </p>
028: * <p>
029: * The <em>style</em> of an image is an arbitrary string used to distinguish
030: * between sets of images associated with a command. For example, a command may
031: * appear in the menus as the default style. However, in the toolbar, the
032: * command is simply the default action for a toolbar drop down item. As such,
033: * perhaps a different image style is appropriate. The classic case is the "Run
034: * Last Launched" command, which appears in the menu and the toolbar, but with
035: * different icons in each location.
036: * </p>
037: * <p>
038: * This interface should not be implemented or extended by clients.
039: * </p>
040: * <p>
041: * <strong>PROVISIONAL</strong>. This class or interface has been added as
042: * part of a work in progress. There is a guarantee neither that this API will
043: * work nor that it will remain the same. Please do not use this API without
044: * consulting with the Platform/UI team.
045: * </p>
046: * <p>
047: * This class is eventually intended to exist in
048: * <code>org.eclipse.ui.commands</code>.
049: * </p>
050: *
051: * @since 3.2
052: */
053: public interface ICommandImageService extends IDisposable {
054:
055: /**
056: * The type of image to display in the default case.
057: */
058: public static final int TYPE_DEFAULT = ICommandImageService.TYPE_DEFAULT;
059:
060: /**
061: * The type of image to display if the corresponding command is disabled.
062: */
063: public static final int TYPE_DISABLED = ICommandImageService.TYPE_DISABLED;
064:
065: /**
066: * The type of image to display if the mouse is hovering over the command
067: * and the command is enabled.
068: */
069: public static final int TYPE_HOVER = ICommandImageService.TYPE_HOVER;
070:
071: /**
072: * Binds a particular image descriptor to a command id, type and style
073: * triple
074: *
075: * @param commandId
076: * The identifier of the command to which the image should be
077: * bound; must not be <code>null</code>.
078: * @param type
079: * The type of image to retrieve. This value must be one of the
080: * <code>TYPE</code> constants defined in this class.
081: * @param style
082: * The style of the image; may be <code>null</code>.
083: * @param descriptor
084: * The image descriptor. Should not be <code>null</code>.
085: */
086: public void bind(String commandId, int type, String style,
087: ImageDescriptor descriptor);
088:
089: /**
090: * Binds a particular image path to a command id, type and style triple
091: *
092: * @param commandId
093: * The identifier of the command to which the image should be
094: * bound; must not be <code>null</code>.
095: * @param type
096: * The type of image to retrieve. This value must be one of the
097: * <code>TYPE</code> constants defined in this class.
098: * @param style
099: * The style of the image; may be <code>null</code>.
100: * @param url
101: * The URL to the image. Should not be <code>null</code>.
102: */
103: public void bind(String commandId, int type, String style, URL url);
104:
105: /**
106: * Generates a style tag that is not currently used for the given command.
107: * This can be used by applications trying to create a unique style for a
108: * new set of images.
109: *
110: * @param commandId
111: * The identifier of the command for which a unique style is
112: * required; must not be <code>null</code>.
113: * @return A style tag that is not currently used; may be <code>null</code>.
114: */
115: public String generateUnusedStyle(String commandId);
116:
117: /**
118: * Retrieves the default image associated with the given command in the
119: * default style.
120: *
121: * @param commandId
122: * The identifier to find; must not be <code>null</code>.
123: * @return An image appropriate for the given command; may be
124: * <code>null</code>.
125: */
126: public ImageDescriptor getImageDescriptor(String commandId);
127:
128: /**
129: * Retrieves the image of the given type associated with the given command
130: * in the default style.
131: *
132: * @param commandId
133: * The identifier to find; must not be <code>null</code>.
134: *
135: * @param type
136: * The type of image to retrieve. This value must be one of the
137: * <code>TYPE</code> constants defined in this interface.
138: * @return An image appropriate for the given command; <code>null</code>
139: * if the given image type cannot be found.
140: */
141: public ImageDescriptor getImageDescriptor(String commandId, int type);
142:
143: /**
144: * Retrieves the image of the given type associated with the given command
145: * in the given style.
146: *
147: * @param commandId
148: * The identifier to find; must not be <code>null</code>.
149: * @param type
150: * The type of image to retrieve. This value must be one of the
151: * <code>TYPE</code> constants defined in this interface.
152: * @param style
153: * The style of the image to retrieve; may be <code>null</code>.
154: * @return An image appropriate for the given command; <code>null</code>
155: * if the given image style and type cannot be found.
156: */
157: public ImageDescriptor getImageDescriptor(String commandId,
158: int type, String style);
159:
160: /**
161: * Retrieves the default image associated with the given command in the
162: * given style.
163: *
164: * @param commandId
165: * The identifier to find; must not be <code>null</code>.
166: * @param style
167: * The style of the image to retrieve; may be <code>null</code>.
168: * @return An image appropriate for the given command; <code>null</code>
169: * if the given image style cannot be found.
170: */
171: public ImageDescriptor getImageDescriptor(String commandId,
172: 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: }
|