| /******************************************************************************* |
| * Copyright (c) 2005 IBM Corporation and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Contributors: |
| * IBM Corporation - initial API and implementation |
| *******************************************************************************/ |
| package org.eclipse.ui.internal.commands; |
| |
| import java.net.URL; |
| |
| import org.eclipse.jface.resource.ImageDescriptor; |
| import org.eclipse.ui.services.IDisposable; |
| |
| /** |
| * <p> |
| * Provides a look-up facility for images associated with commands. |
| * </p> |
| * <p> |
| * The <em>type</em> of an image indicates the state of the associated command |
| * within the user interface. The supported types are: <code>TYPE_DEFAULT</code> |
| * (to be used for an enabled command), <code>TYPE_DISABLED</code> (to be used |
| * for a disabled command) and <code>TYPE_HOVER</code> (to be used for an |
| * enabled command over which the mouse is hovering). |
| * </p> |
| * <p> |
| * The <em>style</em> of an image is an arbitrary string used to distinguish |
| * between sets of images associated with a command. For example, a command may |
| * appear in the menus as the default style. However, in the toolbar, the |
| * command is simply the default action for a toolbar drop down item. As such, |
| * perhaps a different image style is appropriate. The classic case is the "Run |
| * Last Launched" command, which appears in the menu and the toolbar, but with |
| * different icons in each location. |
| * </p> |
| * <p> |
| * This interface should not be implemented or extended by clients. |
| * </p> |
| * <p> |
| * <strong>PROVISIONAL</strong>. This class or interface has been added as |
| * part of a work in progress. There is a guarantee neither that this API will |
| * work nor that it will remain the same. Please do not use this API without |
| * consulting with the Platform/UI team. |
| * </p> |
| * <p> |
| * This class is eventually intended to exist in |
| * <code>org.eclipse.ui.commands</code>. |
| * </p> |
| * |
| * @since 3.2 |
| */ |
| public interface ICommandImageService extends IDisposable { |
| |
| /** |
| * The type of image to display in the default case. |
| */ |
| public static final int TYPE_DEFAULT = ICommandImageService.TYPE_DEFAULT; |
| |
| /** |
| * The type of image to display if the corresponding command is disabled. |
| */ |
| public static final int TYPE_DISABLED = ICommandImageService.TYPE_DISABLED; |
| |
| /** |
| * The type of image to display if the mouse is hovering over the command |
| * and the command is enabled. |
| */ |
| public static final int TYPE_HOVER = ICommandImageService.TYPE_HOVER; |
| |
| /** |
| * Binds a particular image descriptor to a command id, type and style |
| * triple |
| * |
| * @param commandId |
| * The identifier of the command to which the image should be |
| * bound; must not be <code>null</code>. |
| * @param type |
| * The type of image to retrieve. This value must be one of the |
| * <code>TYPE</code> constants defined in this class. |
| * @param style |
| * The style of the image; may be <code>null</code>. |
| * @param descriptor |
| * The image descriptor. Should not be <code>null</code>. |
| */ |
| public void bind(String commandId, int type, String style, |
| ImageDescriptor descriptor); |
| |
| /** |
| * Binds a particular image path to a command id, type and style triple |
| * |
| * @param commandId |
| * The identifier of the command to which the image should be |
| * bound; must not be <code>null</code>. |
| * @param type |
| * The type of image to retrieve. This value must be one of the |
| * <code>TYPE</code> constants defined in this class. |
| * @param style |
| * The style of the image; may be <code>null</code>. |
| * @param url |
| * The URL to the image. Should not be <code>null</code>. |
| */ |
| public void bind(String commandId, int type, String style, URL url); |
| |
| /** |
| * Generates a style tag that is not currently used for the given command. |
| * This can be used by applications trying to create a unique style for a |
| * new set of images. |
| * |
| * @param commandId |
| * The identifier of the command for which a unique style is |
| * required; must not be <code>null</code>. |
| * @return A style tag that is not currently used; may be <code>null</code>. |
| */ |
| public String generateUnusedStyle(String commandId); |
| |
| /** |
| * Retrieves the default image associated with the given command in the |
| * default style. |
| * |
| * @param commandId |
| * The identifier to find; must not be <code>null</code>. |
| * @return An image appropriate for the given command; may be |
| * <code>null</code>. |
| */ |
| public ImageDescriptor getImageDescriptor(String commandId); |
| |
| /** |
| * Retrieves the image of the given type associated with the given command |
| * in the default style. |
| * |
| * @param commandId |
| * The identifier to find; must not be <code>null</code>. |
| * |
| * @param type |
| * The type of image to retrieve. This value must be one of the |
| * <code>TYPE</code> constants defined in this interface. |
| * @return An image appropriate for the given command; <code>null</code> |
| * if the given image type cannot be found. |
| */ |
| public ImageDescriptor getImageDescriptor(String commandId, int type); |
| |
| /** |
| * Retrieves the image of the given type associated with the given command |
| * in the given style. |
| * |
| * @param commandId |
| * The identifier to find; must not be <code>null</code>. |
| * @param type |
| * The type of image to retrieve. This value must be one of the |
| * <code>TYPE</code> constants defined in this interface. |
| * @param style |
| * The style of the image to retrieve; may be <code>null</code>. |
| * @return An image appropriate for the given command; <code>null</code> |
| * if the given image style and type cannot be found. |
| */ |
| public ImageDescriptor getImageDescriptor(String commandId, int type, |
| String style); |
| |
| /** |
| * Retrieves the default image associated with the given command in the |
| * given style. |
| * |
| * @param commandId |
| * The identifier to find; must not be <code>null</code>. |
| * @param style |
| * The style of the image to retrieve; may be <code>null</code>. |
| * @return An image appropriate for the given command; <code>null</code> |
| * if the given image style cannot be found. |
| */ |
| public ImageDescriptor getImageDescriptor(String commandId, String style); |
| |
| /** |
| * <p> |
| * Reads the command image information from the registry. This will |
| * overwrite any of the existing information in the command image service. |
| * This method is intended to be called during start-up. When this method |
| * completes, this command image service will reflect the current state of |
| * the registry. |
| * </p> |
| */ |
| public void readRegistry(); |
| } |