public interface IHandlerService extends IServiceWithSources
Provides services related to activating and deactivating handlers within the workbench.
This service can be acquired from your service locator:
IHandlerService service = (IHandlerService) getSite().getService(IHandlerService.class);
Modifier and Type | Method and Description |
---|---|
IHandlerActivation |
activateHandler(IHandlerActivation activation)
Activates the given handler from a child service.
|
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,
boolean global)
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. |
IEvaluationContext |
createContextSnapshot(boolean includeSelection)
This method creates a copy of the application context returned by
getCurrentState() . |
ExecutionEvent |
createExecutionEvent(Command command,
Event event)
Creates an execution event based on an SWT event.
|
ExecutionEvent |
createExecutionEvent(ParameterizedCommand command,
Event event)
Creates a parameterized execution event based on an SWT event and a
parameterized command.
|
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.
|
Object |
executeCommand(ParameterizedCommand command,
Event event)
Executes the given parameterized command.
|
Object |
executeCommand(String commandId,
Event event)
Executes the command with the given identifier and no parameters.
|
Object |
executeCommandInContext(ParameterizedCommand command,
Event event,
IEvaluationContext context)
Executes the given parameterized command in the provided context.
|
IEvaluationContext |
getCurrentState()
Returns an evaluation context representing the current state of the
world.
|
void |
readRegistry()
Reads the handler information from the registry.
|
void |
setHelpContextId(IHandler handler,
String helpContextId)
Sets the help context identifier to associate with a particular handler.
|
addSourceProvider, removeSourceProvider
dispose
IHandlerActivation activateHandler(IHandlerActivation activation)
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.
activation
- The activation that is local to the child service; must not be
null
.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.
commandId
- The identifier for the command which this handler handles;
must not be null
.handler
- The handler to activate; must not be null
.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
. This is the same as calling
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 service is destroyed. So, for
example, a service retrieved from a IWorkbenchPartSite
would deactivate all of its handlers when the site is destroyed.
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.ISources
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
. 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.
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.global
- Indicates that the handler should be activated irrespectively
of whether the corresponding workbench component (e.g.,
window, part, etc.) is active.ISources
@Deprecated IHandlerActivation activateHandler(String commandId, IHandler handler, Expression expression, int sourcePriorities)
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.
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.ISources
ExecutionEvent createExecutionEvent(Command command, Event event)
command
- The command for which an execution event should be created;
must not be null
.event
- The SWT event triggering the command execution; may be
null
.Command.executeWithChecks(ExecutionEvent)
.Command.executeWithChecks(ExecutionEvent)
ExecutionEvent createExecutionEvent(ParameterizedCommand command, Event event)
command
- The parameterized command for which an execution event should
be created; must not be null
.event
- The SWT event triggering the command execution; may be
null
.Command.executeWithChecks(ExecutionEvent)
.ParameterizedCommand.getCommand()
,
Command.executeWithChecks(ExecutionEvent)
void deactivateHandler(IHandlerActivation activation)
IHandlerActivation
used to activate the handler.activation
- The token that was returned from a call to
activateHandler
; must not be null
.void deactivateHandlers(Collection activations)
IHandlerActivation
used to activate the handler.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
.Object executeCommand(String commandId, Event event) throws ExecutionException, NotDefinedException, NotEnabledException, NotHandledException
commandId
- The identifier of the command to execute; must not be
null
.event
- The SWT event triggering the command execution; may be
null
.null
.ExecutionException
- If the handler has problems executing this command.NotDefinedException
- If the command you are trying to execute is not defined.NotEnabledException
- If the command you are trying to execute is not enabled.NotHandledException
- If there is no handler.Command.executeWithChecks(ExecutionEvent)
Object executeCommand(ParameterizedCommand command, Event event) throws ExecutionException, NotDefinedException, NotEnabledException, NotHandledException
command
- The parameterized command to be executed; must not be
null
.event
- The SWT event triggering the command execution; may be
null
.null
.ExecutionException
- If the handler has problems executing this command.NotDefinedException
- If the command you are trying to execute is not defined.NotEnabledException
- If the command you are trying to execute is not enabled.NotHandledException
- If there is no handler.Command.executeWithChecks(ExecutionEvent)
Object executeCommandInContext(ParameterizedCommand command, Event event, IEvaluationContext context) throws ExecutionException, NotDefinedException, NotEnabledException, NotHandledException
IHandler2.setEnabled(Object)
to update the enabled state if
supported, and executes with that handler.command
- The parameterized command to be executed; must not be
null
.event
- The SWT event triggering the command execution; may be
null
.context
- the evaluation context to run against. Must not be
null
null
.ExecutionException
- If the handler has problems executing this command.NotDefinedException
- If the command you are trying to execute is not defined.NotEnabledException
- If the command you are trying to execute is not enabled.NotHandledException
- If there is no handler.Command.executeWithChecks(ExecutionEvent)
,
createContextSnapshot(boolean)
IEvaluationContext createContextSnapshot(boolean includeSelection)
getCurrentState()
.includeSelection
- if true
, include the default variable and
selection variablesIEvaluationContext getCurrentState()
ExecutionEvent
.null
.ParameterizedCommand.executeWithChecks(Object, Object)
,
ExecutionEvent.ExecutionEvent(Command, java.util.Map, Object,
Object)
,
IEvaluationService
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.
void setHelpContextId(IHandler handler, String helpContextId)
handler
- The handler with which to register a help context identifier;
must not be null
.helpContextId
- The help context identifier to register; may be
null
if the help context identifier should be
removed.
Copyright (c) 2000, 2014 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.