org.eclipse.ui.handlers
Interface IHandlerService

All Superinterfaces:

IServiceWithSources

public interface IHandlerService

extends 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

Method Summary

IHandlerActivation	activateHandler(String commandId, IHandler handler) Activates the given handler within the context of this service.
IHandlerActivation	activateHandler(String commandId, IHandler handler, Expression expression) Activates the given handler within the context of this service.
IHandlerActivation	activateHandler(String commandId, IHandler handler, Expression expression, int sourcePriorities) Deprecated. Use activateHandler(String, IHandler, Expression) instead.
void	deactivateHandler(IHandlerActivation activation) Deactivates the given handler within the context of this service.
void	deactivateHandlers(Collection activations) Deactivates the given handlers within the context of this service.
IEvaluationContext	getCurrentState() returns an evaluation context representing the current state of the world.
void	readRegistry() Reads the handler information from the registry.

Methods inherited from interface org.eclipse.ui.IServiceWithSources

addSourceProvider, removeSourceProvider

Method Detail

activateHandler

public IHandlerActivation activateHandler(String commandId,
                                          IHandler handler)

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.

Parameters:

commandId - The identifier for the command which this handler handles; must not be null.

handler - The handler to activate; must not be null.

Returns:

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.

activateHandler

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.

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.

Parameters:

commandId - The identifier for the command which this handler handles; must not be null.

handler - The handler to activate; must not be null.

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.

Returns:

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.

Since:

3.2

See Also:

ISources

activateHandler

public IHandlerActivation activateHandler(String commandId,
                                          IHandler handler,
                                          Expression expression,
                                          int sourcePriorities)

Deprecated. Use activateHandler(String, IHandler, Expression) instead.

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.

Parameters:

commandId - The identifier for the command which this handler handles; must not be null.

handler - The handler to activate; must not be null.

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.

sourcePriorities - The source priorities for the expression.

Returns:

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 Also:

ISources

deactivateHandler

public void deactivateHandler(IHandlerActivation activation)

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.

Parameters:

activation - The token that was returned from a call to activateHandler; must not be null.

deactivateHandlers

public void deactivateHandlers(Collection activations)

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.

Parameters:

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.

getCurrentState

public IEvaluationContext getCurrentState()

returns an evaluation context representing the current state of the world.

Returns:

the current state of the application; never null.

readRegistry

public void readRegistry()

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.