Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Programming
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Databases
Mail Systems
openSolaris
Eclipse Documentation
Techotopia.com
Virtuatopia.com

How To Guides
Virtualization
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Windows
Problem Solutions
Privacy Policy

  




 

 


Eclipse Platform
Release 3.5

org.eclipse.ui.handlers
Interface IHandlerService

All Superinterfaces:
IDisposable, IServiceWithSources

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);
 
  • This service is available globally.

Since:
3.1
Restriction:
This interface is not intended to be implemented by clients.
Restriction:
This interface is not intended to be extended by clients.

Method Summary
  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.
 
Methods inherited from interface org.eclipse.ui.services. IServiceWithSources
addSourceProvider, removeSourceProvider
 
Methods inherited from interface org.eclipse.ui.services. IDisposable
dispose
 

Method Detail

activateHandler

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.

Parameters:
activation - The activation that is local to the child service; 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 service locator 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

activateHandler

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

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.

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

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.

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.
global - Indicates that the handler should be activated irrespectively of whether the corresponding workbench component (e.g., window, part, etc.) is 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

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

createExecutionEvent

ExecutionEvent createExecutionEvent(
Command command,
                                    
Event event)
Creates an execution event based on an SWT event. This execution event can then be passed to a command for execution.

Parameters:
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.
Returns:
An execution event suitable for calling Command.executeWithChecks(ExecutionEvent).
Since:
3.2
See Also:
Command.executeWithChecks(ExecutionEvent)

createExecutionEvent

ExecutionEvent createExecutionEvent(
ParameterizedCommand 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.

Parameters:
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.
Returns:
An execution event suitable for calling Command.executeWithChecks(ExecutionEvent).
Since:
3.2
See Also:
ParameterizedCommand.getCommand(), Command.executeWithChecks(ExecutionEvent)

deactivateHandler

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

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.

executeCommand

Object executeCommand(
String commandId,
                      
Event event)
                      throws 
ExecutionException,
                             
NotDefinedException,
                             
NotEnabledException,
                             
NotHandledException
Executes the command with the given identifier and no parameters.

Parameters:
commandId - The identifier of the command to execute; must not be null.
event - The SWT event triggering the command execution; may be null.
Returns:
The return value from the execution; may be null.
Throws:
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.
Since:
3.2
See Also:
Command.executeWithChecks(ExecutionEvent)

executeCommand

Object executeCommand(
ParameterizedCommand command,
                      
Event event)
                      throws 
ExecutionException,
                             
NotDefinedException,
                             
NotEnabledException,
                             
NotHandledException
Executes the given parameterized command.

Parameters:
command - The parameterized command to be executed; must not be null.
event - The SWT event triggering the command execution; may be null.
Returns:
The return value from the execution; may be null.
Throws:
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.
Since:
3.2
See Also:
Command.executeWithChecks(ExecutionEvent)

executeCommandInContext

Object executeCommandInContext(
ParameterizedCommand command,
                               
Event event,
                               
IEvaluationContext context)
                               throws 
ExecutionException,
                                      
NotDefinedException,
                                      
NotEnabledException,
                                      
NotHandledException
Executes the given parameterized command in the provided context. It takes care of finding the correct active handler given the context, calls IHandler2.setEnabled(Object) to update the enabled state if supported, and executes with that handler.

Parameters:
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
Returns:
The return value from the execution; may be null.
Throws:
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.
Since:
3.4
See Also:
Command.executeWithChecks(ExecutionEvent), createContextSnapshot(boolean)

createContextSnapshot

IEvaluationContext createContextSnapshot(boolean includeSelection)
This method creates a copy of the application context returned by getCurrentState().

Parameters:
includeSelection - if true, include the default variable and selection variables
Returns:
an context filled with the current set of variables. If selection is not included, the default variable is an empty collection
Since:
3.4

getCurrentState

IEvaluationContext getCurrentState()
Returns an evaluation context representing the current state of the world. This is equivalent to the application context required by ExecutionEvent.

Returns:
the current state of the application; never null.
See Also:
ParameterizedCommand.executeWithChecks(Object, Object), ExecutionEvent.ExecutionEvent(Command, java.util.Map, Object, Object), IEvaluationService

readRegistry

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.


setHelpContextId

void setHelpContextId(
IHandler handler,
                      
String helpContextId)
Sets the help context identifier to associate with a particular handler.

Parameters:
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.
Since:
3.2

Eclipse Platform
Release 3.5

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.


 
 
  Published under the terms of the Eclipse Public License Version 1.0 ("EPL") Design by Interspire