org.eclipse.ui.handlers.IHandlerService Maven / Gradle / Ivy
Show all versions of workbench Show documentation
/*******************************************************************************
* Copyright (c) 2005, 2006 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.handlers;
import java.util.Collection;
import org.eclipse.core.commands.Command;
import org.eclipse.core.commands.ExecutionEvent;
import org.eclipse.core.commands.ExecutionException;
import org.eclipse.core.commands.IHandler;
import org.eclipse.core.commands.NotEnabledException;
import org.eclipse.core.commands.NotHandledException;
import org.eclipse.core.commands.ParameterizedCommand;
import org.eclipse.core.commands.common.NotDefinedException;
import org.eclipse.core.expressions.Expression;
import org.eclipse.core.expressions.IEvaluationContext;
import org.eclipse.swt.widgets.Event;
import org.eclipse.ui.services.IServiceWithSources;
/**
*
* Provides services related to activating and deactivating handlers within the
* workbench.
*
*
* This interface is not intended to be implemented or extended by clients.
*
*
* @since 3.1
*/
public interface IHandlerService extends IServiceWithSources {
/**
*
* Activates the given handler from a child service. This is used by slave
* and nested services to promote handler activations up to the root. By
* using this method, it is possible for handlers coming from a more nested
* component to override the nested component.
*
*
* @param activation
* The activation that is local to the child service; must not be
* null.
* @return A token which can be used to later cancel the activation. Only
* someone with access to this token can cancel the activation. The
* activation will automatically be cancelled if the context from
* which this service was retrieved is destroyed. This activation is
* local to this service (i.e., it is not the activation that is
* passed as a parameter).
* @since 3.2
*/
public IHandlerActivation activateHandler(IHandlerActivation activation);
/**
*
* Activates the given handler within the context of this service. If this
* service was retrieved from the workbench, then this handler will be
* active globally. If the service was retrieved from a nested component,
* then the handler will only be active within that component.
*
*
* Also, it is guaranteed that the handlers submitted through a particular
* service will be cleaned up when that services is destroyed. So, for
* example, a service retrieved from a IWorkbenchPartSite
* would deactivate all of its handlers when the site is destroyed.
*
*
* @param commandId
* The identifier for the command which this handler handles;
* must not be null.
* @param handler
* The handler to activate; must not be null.
* @return A token which can be used to later cancel the activation. Only
* someone with access to this token can cancel the activation. The
* activation will automatically be cancelled if the context from
* which this service was retrieved is destroyed.
*/
public IHandlerActivation activateHandler(String commandId, IHandler handler);
/**
*
* Activates the given handler within the context of this service. The
* handler becomes active when expression evaluates to
* true. This is the same as calling
* {@link #activateHandler(String, IHandler, Expression, boolean)} with
* global==false.
*
*
* Also, it is guaranteed that the handlers submitted through a particular
* service will be cleaned up when that services is destroyed. So, for
* example, a service retrieved from a IWorkbenchPartSite
* would deactivate all of its handlers when the site is destroyed.
*
*
* @param commandId
* The identifier for the command which this handler handles;
* must not be null.
* @param handler
* The handler to activate; must not be null.
* @param expression
* This expression must evaluate to true before
* this handler will really become active. The expression may be
* null if the handler should always be active.
* @return A token which can be used to later cancel the activation. Only
* someone with access to this token can cancel the activation. The
* activation will automatically be cancelled if the context from
* which this service was retrieved is destroyed.
*
* @see org.eclipse.ui.ISources
* @since 3.2
*/
public IHandlerActivation activateHandler(String commandId,
IHandler handler, Expression expression);
/**
*
* Activates the given handler within the context of this service. The
* handler becomes active when expression evaluates to
* true. if global==false, then this
* handler service must also be the active service to active the handler.
* For example, the handler service on a part is active when that part is
* active.
*
*
* Also, it is guaranteed that the handlers submitted through a particular
* service will be cleaned up when that services is destroyed. So, for
* example, a service retrieved from a IWorkbenchPartSite
* would deactivate all of its handlers when the site is destroyed.
*
*
* @param commandId
* The identifier for the command which this handler handles;
* must not be null.
* @param handler
* The handler to activate; must not be null.
* @param expression
* This expression must evaluate to true before
* this handler will really become active. The expression may be
* null if the handler should always be active.
* @param global
* Indicates that the handler should be activated irrespectively
* of whether the corresponding workbench component (e.g.,
* window, part, etc.) is active.
* @return A token which can be used to later cancel the activation. Only
* someone with access to this token can cancel the activation. The
* activation will automatically be cancelled if the context from
* which this service was retrieved is destroyed.
*
* @see org.eclipse.ui.ISources
* @since 3.2
*/
public IHandlerActivation activateHandler(String commandId,
IHandler handler, Expression expression, boolean global);
/**
*
* Activates the given handler within the context of this service. The
* handler becomes active when expression evaluates to
* true.
*
*
* Also, it is guaranteed that the handlers submitted through a particular
* service will be cleaned up when that services is destroyed. So, for
* example, a service retrieved from a IWorkbenchPartSite
* would deactivate all of its handlers when the site is destroyed.
*
*
* @param commandId
* The identifier for the command which this handler handles;
* must not be null.
* @param handler
* The handler to activate; must not be null.
* @param expression
* This expression must evaluate to true before
* this handler will really become active. The expression may be
* null if the handler should always be active.
* @param sourcePriorities
* The source priorities for the expression.
* @return A token which can be used to later cancel the activation. Only
* someone with access to this token can cancel the activation. The
* activation will automatically be cancelled if the context from
* which this service was retrieved is destroyed.
*
* @see org.eclipse.ui.ISources
* @deprecated Use
* {@link IHandlerService#activateHandler(String, IHandler, Expression)}
* instead.
*/
public IHandlerActivation activateHandler(String commandId,
IHandler handler, Expression expression, int sourcePriorities);
/**
* Creates an execution event based on an SWT event. This execution event
* can then be passed to a command for execution.
*
* @param command
* The command for which an execution event should be created;
* must not be null.
* @param event
* The SWT event triggering the command execution; may be
* null.
* @return An execution event suitable for calling
* {@link Command#executeWithChecks(ExecutionEvent)}.
* @since 3.2
* @see Command#executeWithChecks(ExecutionEvent)
*/
public ExecutionEvent createExecutionEvent(Command command, Event event);
/**
* Creates a parameterized execution event based on an SWT event and a
* parameterized command. This execution event can then be passed to a
* command for execution.
*
* @param command
* The parameterized command for which an execution event should
* be created; must not be null.
* @param event
* The SWT event triggering the command execution; may be
* null.
* @return An execution event suitable for calling
* {@link Command#executeWithChecks(ExecutionEvent)}.
* @since 3.2
* @see ParameterizedCommand#getCommand()
* @see Command#executeWithChecks(ExecutionEvent)
*/
public ExecutionEvent createExecutionEvent(ParameterizedCommand command,
Event event);
/**
* Deactivates the given handler within the context of this service. If the
* handler was activated with a different service, then it must be
* deactivated from that service instead. It is only possible to retract a
* handler activation with this method. That is, you must have the same
* IHandlerActivation used to activate the handler.
*
* @param activation
* The token that was returned from a call to
* activateHandler; must not be null.
*/
public void deactivateHandler(IHandlerActivation activation);
/**
* Deactivates the given handlers within the context of this service. If the
* handler was activated with a different service, then it must be
* deactivated from that service instead. It is only possible to retract a
* handler activation with this method. That is, you must have the same
* IHandlerActivation used to activate the handler.
*
* @param activations
* The tokens that were returned from a call to
* activateHandler. This collection must only
* contain instances of IHandlerActivation. The
* collection must not be null.
*/
public void deactivateHandlers(Collection activations);
/**
* Executes the command with the given identifier and no parameters.
*
* @param commandId
* The identifier of the command to execute; must not be
* null.
* @param event
* The SWT event triggering the command execution; may be
* null.
* @return The return value from the execution; may be null.
* @throws ExecutionException
* If the handler has problems executing this command.
* @throws NotDefinedException
* If the command you are trying to execute is not defined.
* @throws NotEnabledException
* If the command you are trying to execute is not enabled.
* @throws NotHandledException
* If there is no handler.
* @since 3.2
* @see Command#executeWithChecks(ExecutionEvent)
*/
public Object executeCommand(String commandId, Event event)
throws ExecutionException, NotDefinedException,
NotEnabledException, NotHandledException;
/**
* Executes the given parameterized command.
*
* @param command
* The parameterized command to be executed; must not be
* null.
* @param event
* The SWT event triggering the command execution; may be
* null.
* @return The return value from the execution; may be null.
* @throws ExecutionException
* If the handler has problems executing this command.
* @throws NotDefinedException
* If the command you are trying to execute is not defined.
* @throws NotEnabledException
* If the command you are trying to execute is not enabled.
* @throws NotHandledException
* If there is no handler.
* @since 3.2
* @see Command#executeWithChecks(ExecutionEvent)
*/
public Object executeCommand(ParameterizedCommand command, Event event)
throws ExecutionException, NotDefinedException,
NotEnabledException, NotHandledException;
/**
* Returns an evaluation context representing the current state of the
* world. This is equivalent to the application context required by
* {@link ExecutionEvent}.
*
* @return the current state of the application; never null.
* @see ParameterizedCommand#executeWithChecks(Object, Object)
* @see ExecutionEvent#ExecutionEvent(Command, java.util.Map, Object,
* Object)
*/
public IEvaluationContext getCurrentState();
/**
*
* Reads the handler information from the registry. This will overwrite any
* of the existing information in the handler service. This method is
* intended to be called during start-up. When this method completes, this
* handler service will reflect the current state of the registry.
*
*/
public void readRegistry();
/**
* 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 null.
* @param helpContextId
* The help context identifier to register; may be
* null if the help context identifier should be
* removed.
* @since 3.2
*/
public void setHelpContextId(IHandler handler, String helpContextId);
}