org.eclipse.ui.workbench
org.eclipse.ui.commands
visit times 222
/*******************************************************************************
 * Copyright (c) 2005, 2008 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.commands;

import java.util.Collection;
import java.util.Map;
import org.eclipse.core.commands.Category;
import org.eclipse.core.commands.Command;
import org.eclipse.core.commands.CommandManager;
import org.eclipse.core.commands.IExecutionListener;
import org.eclipse.core.commands.IHandler;
import org.eclipse.core.commands.ParameterType;
import org.eclipse.core.commands.ParameterizedCommand;
import org.eclipse.core.commands.SerializationException;
import org.eclipse.core.commands.common.NotDefinedException;
import org.eclipse.ui.menus.UIElement;
import org.eclipse.ui.services.IDisposable;
/**
 * 
<p>
 * Provides services related to the command architecture within the workbench.
 * This service can be used to access the set of commands and command
 * categories.
 * 
</p>
 * 
<p>
 * This service can be acquired from your service locator:
 * 
<pre>
 *     ICommandService service = (ICommandService) getSite().getService(ICommandService.class);
 * 
</pre>
 * 
<ul>
 * 
<li>This service is available globally.</li>
 * 
</ul>
 * 
</p>
 * 
@noimplement This interface is not intended to be implemented by clients.
 * 
@noextend This interface is not intended to be extended by clients.
 * 
 * 
@since 3.1
 */

public interface ICommandService extends IDisposable {

    
/**
     * The identifier of the category in which all auto
-generated commands will
     * appear. This value must never be 
<code>null</code>.
     * 
     * 
@since 3.2
     */

    
public static final String AUTOGENERATED_CATEGORY_ID = CommandManager.AUTOGENERATED_CATEGORY_ID;

    
/**
     * Adds an execution listener to the command service. This listener will be
     * notified as commands are executed.
     * 
<p>
     * 
<b>Note:</b> listeners should be removed when no longer necessary. If
     * not, they will be removed when the IServiceLocator used to acquire this
     * service is disposed.
     * 
</p>
     * 
     * 
@param listener
     *            The listener to add; must not be 
<code>null</code>.
     * 
@see #removeExecutionListener(IExecutionListener)
     */

    
public void addExecutionListener(IExecutionListener listener);

    
/**
     * Sets the name and description of the category for uncategorized commands.
     * This is the category that will be returned if
     * 
{@link #getCategory(String)} is called with <code>null</code>.
     * 
     * 
@param name
     *            The name of the category for uncategorized commands; must not
     *            be 
<code>null</code>.
     * 
@param description
     *            The description of the category for uncategorized commands;
     *            may be 
<code>null</code>.
     * 
@since 3.2
     */

    
public void defineUncategorizedCategory(String name, String description);

    
/**
     * 
<p>
     * Returns a 
{@link ParameterizedCommand} with a command and
     * parameterizations as specified in the provided
     * 
<code>serializedParameterizedCommand</code> string. The
     * 
<code>serializedParameterizedCommand</code> must use the format
     * returned by 
{@link ParameterizedCommand#serialize()} and described in the
     * Javadoc for that method.
     * 
</p>
     * 
<p>
     * If a parameter id encoded in the
     * 
<code>serializedParameterizedCommand</code> does not exist in the
     * encoded command, that parameter id and value are ignored. A given
     * parameter id should not be used more than once in
     * 
<code>serializedParameterizedCommand</code>. This will not result in
     * an exception, but the value of the parameter when the command is executed
     * cannot be specified here.
     * 
</p>
     * 
<p>
     * This method will never return 
<code>null</code>, however it may throw
     * an exception if there is a problem processing the serialization string or
     * the encoded command is undefined.
     * 
</p>
     * 
     * 
@param serializedParameterizedCommand
     *            a 
<code>String</code> representing a command id and
     *            parameter ids and values
     * 
@return a <code>ParameterizedCommand</code> with the command and
     *         parameterizations encoded in the
     *         
<code>serializedParameterizedCommand</code>
     * 
@throws NotDefinedException
     *             if the command indicated in
     *             
<code>serializedParameterizedCommand</code> is not defined
     * 
@throws SerializationException
     *             if there is an error deserializing
     *             
<code>serializedParameterizedCommand</code>
     * 
@see ParameterizedCommand#serialize()
     * 
@see CommandManager#deserialize(String)
     * 
@since 3.2
     */

    
public ParameterizedCommand deserialize(
            String serializedParameterizedCommand
) throws NotDefinedException,
            SerializationException;

    
/**
     * Retrieves the category with the given identifier. If no such category
     * exists, then an undefined category with the given id is created.
     * 
     * 
@param categoryId
     *            The identifier to find. If the category is 
<code>null</code>,
     *            then a category suitable for uncategorized items is defined
     *            and returned.
     * 
@return A category with the given identifier, either defined or
     *         undefined.
     */

    
public Category getCategory(String categoryId);

    
/**
     * Retrieves the command with the given identifier. If no such command
     * exists, then an undefined command with the given id is created.
     * 
     * 
@param commandId
     *            The identifier to find; must not be 
<code>null</code>.
     * 
@return A command with the given identifier, either defined or undefined.
     */

    
public Command getCommand(String commandId);

    
/**
     * Returns the collection of all of the defined categories in the workbench.
     * 
     * 
@return The collection of categories (<code>Category</code>) that are
     *         defined; never 
<code>null</code>, but may be empty.
     * 
@since 3.2
     */

    
public Category[] getDefinedCategories();

    
/**
     * Returns the collection of the identifiers for all of the defined
     * categories in the workbench.
     * 
     * 
@return The collection of category identifiers (<code>String</code>)
     *         that are defined; never 
<code>null</code>, but may be empty.
     */

    
public Collection getDefinedCategoryIds();

    
/**
     * Returns the collection of the identifiers for all of the defined commands
     * in the workbench.
     * 
     * 
@return The collection of command identifiers (<code>String</code>)
     *         that are defined; never 
<code>null</code>, but may be empty.
     */

    
public Collection getDefinedCommandIds();

    
/**
     * Returns the collection of all of the defined commands in the workbench.
     * 
     * 
@return The collection of commands (<code>Command</code>) that are
     *         defined; never 
<code>null</code>, but may be empty.
     * 
@since 3.2
     */

    
public Command[] getDefinedCommands();

    
/**
     * Returns the collection of the identifiers for all of the defined command
     * parameter types in the workbench.
     * 
     * 
@return The collection of command parameter type identifiers (<code>String</code>)
     *         that are defined; never 
<code>null</code>, but may be empty.
     * 
@since 3.2
     */

    
public Collection getDefinedParameterTypeIds();

    
/**
     * Returns the collection of all of the defined command parameter types in
     * the workbench.
     * 
     * 
@return The collection of command parameter types (<code>ParameterType</code>)
     *         that are defined; never 
<code>null</code>, but may be empty.
     * 
@since 3.2
     */

    
public ParameterType[] getDefinedParameterTypes();

    
/**
     * Gets the help context identifier for a particular command. The command's
     * handler is first checked for a help context identifier. If the handler
     * does not have a help context identifier, then the help context identifier
     * for the command is returned. If neither has a help context identifier,
     * then 
<code>null</code> is returned.
     * 
     * 
@param command
     *            The command for which the help context should be retrieved;
     *            must not be 
<code>null</code>.
     * 
@return The help context identifier to use for the given command; may be
     *         
<code>null</code>.
     * 
@throws NotDefinedException
     *             If the given command is not defined.
     * 
@since 3.2
     */

    
public String getHelpContextId(Command command) throws NotDefinedException;

    
/**
     * Gets the help context identifier for a particular command. The command's
     * handler is first checked for a help context identifier. If the handler
     * does not have a help context identifier, then the help context identifier
     * for the command is returned. If neither has a help context identifier,
     * then 
<code>null</code> is returned.
     * 
     * 
@param commandId
     *            The identifier of the command for which the help context
     *            should be retrieved; must not be 
<code>null</code>.
     * 
@return The help context identifier to use for the given command; may be
     *         
<code>null</code>.
     * 
@throws NotDefinedException
     *             If the command with the given identifier is not defined.
     * 
@since 3.2
     */

    
public String getHelpContextId(String commandId) throws NotDefinedException;

    
/**
     * Retrieves the command parameter type with the given identifier. If no
     * such parameter type exists, then an undefined parameter type with the
     * given id is created.
     * 
     * 
@param parameterTypeId
     *            The identifier to find; must not be 
<code>null</code>.
     * 
@return A command parameter type with the given identifier, either
     *         defined or undefined.
     * 
@since 3.2
     */

    
public ParameterType getParameterType(String parameterTypeId);

    
/**
     * 
<p>
     * Reads the command information from the registry and the preferences. This
     * will overwrite any of the existing information in the command service.
     * This method is intended to be called during start
-up. When this method
     * completes, this command service will reflect the current state of the
     * registry and preference store.
     * 
</p>
     */

    
public void readRegistry();

    
/**
     * Removes an execution listener from the command service.
     * 
     * 
@param listener
     *            The listener to remove; must not be 
<code>null</code>.
     */

    
public void removeExecutionListener(IExecutionListener listener);

    
/**
     * Sets the help context identifier to associate with a particular handler.
     * 
     * 
@param handler
     *            The handler with which to register a help context identifier;
     *            must not be 
<code>null</code>.
     * 
@param helpContextId
     *            The help context identifier to register; may be
     *            
<code>null</code> if the help context identifier should be
     *            removed.
     * 
@since 3.2
     */

    
public void setHelpContextId(IHandler handler, String helpContextId);

    
/**
     * Register that this element accepts callbacks for this parameterized
     * command.
     * 
<p>
     * 
<b>Note:</b> elements should be removed when no longer necessary. If
     * not, they will be removed when the IServiceLocator used to acquire this
     * service is disposed.
     * 
</p>
     * 
     * 
@param command
     *            The parameterized command that is already specialized. Must
     *            not be 
<code>null</code>.
     * 
@param element
     *            The callback to register for this specialized command
     *            instance. Must not be 
<code>null</code>.
     * 
@return A reference for the registered element that can be used to
     *         unregister it.
     * 
@throws NotDefinedException
     *             If the command included in the ParameterizedCommand is not
     *             defined, or the element is 
<code>null</code>.
     * 
@since 3.3
     * 
@see #unregisterElement(IElementReference)
     */

    
public IElementReference registerElementForCommand(
            ParameterizedCommand command, UIElement element
)
            
throws NotDefinedException;

    
/**
     * Re
-register a callback element provided by the ICommandService. This
     * element reference must not currently be held by the ICommandService. i.e.
     * it must have been removed using
     * 
{@link #unregisterElement(IElementReference)}.
     * 
<p>
     * 
<b>Note:</b> elements should be removed when no longer necessary. If
     * not, they will be removed when the IServiceLocator used to acquire this
     * service is disposed.
     * 
</p>
     * 
     * 
@param elementReference
     *            The reference to re
-register. Must not be <code>null</code>.
     * 
@since 3.3
     * 
@see #unregisterElement(IElementReference)
     */

    
public void registerElement(IElementReference elementReference);

    
/**
     * Unregister an element callback. It will be removed from the
     * ICommandService. The same service that is used to register an element for
     * a command 
<b>must</b> be used to unregister the element.
     * 
     * 
@param elementReference
     *            The callback reference that was provided by the command
     *            service on registration. Must not be 
<code>null</code>.
     * 
@since 3.3
     */

    
public void unregisterElement(IElementReference elementReference);

    
/**
     * Refresh any elements registered against the command with the given id.
     * It allows the active handler the opportunity to provide user feedback. If
     * the command is parameterized, some of the parameters can be specified to
     * help narrow down which elements to refresh.
     * 
<p>
     * The service locator used in registering the element can also be used to
     * scope the search. For example: if you wanted all elements for your
     * command but only within the part's workbench window, you could use:
     * 
     * 
<pre>
     * Map filter = new HashMap();
     * filter.put(IServiceScopes.WINDOW_SCOPE, getSite().getPage()
     *         .getWorkbenchWindow());
     * commandService.refreshElements(commandId, filter);
     * 
</pre>
     * 
     * 
</p>
     * 
     * 
@param commandId
     *            The command id to refresh if it has registered eleemnts.
     * 
@param filter
     *            key
-value pairs that can narrow down the callbacks to return.
     *            The parameters are 
<b>AND</b>ed together. This may be
     *            
<code>null</code>.
     * 
@since 3.3
     */

    
public void refreshElements(String commandId, Map filter);
}