Package org.eclipse.e4.core.commands

# Interface ECommandService

All Known Implementing Classes:
  `CommandServiceImpl`

public interface ECommandService
This service allows access to the command subsystem. A `command` is an abstract notion of a user action like "copy" and "paste". A handler is an object that executes the actual code when the command is activated.

Many handlers may be associated with a command (e.g. "copy") because each handler typically only handles the command when in a specific context. An example of different contexts is the use of the "copy" command in a text editor versus in a table. In each case the command is the same, but the code to handle the case in that context is very different.

You should not implement this service, an implementation is provided by Eclipse.

It is usually not needed to use this service in your programs because command creation is done by Eclipse using the application model. However, in some cases it may be needed to programmatically create commands, or activate a handler using the `EHandlerService`

Example usage:

     @inject  ECommandService cs;
     @inject  EHandlerService hs;

     Command command = cs.getCommand(commandId);
     if (command.isDefined()) {
            Map<String, Object> parameters = new HashMap<String, Object>();
            parameters.put("parm1", "hello, world");
            ParameterizedCommand parmCmd = cs.createCommand(commandId, parameters);
            if (hs.canExecute(parmCmd)) {
                    hs.executeHandler(parmCmd);
            }
            else {logger.error("Cannot execute command");}
     }
     else {logger.error("Command is not defined");}

Since:
  1.0
See Also:
  - `EHandlerService`
Restriction:
  This interface is not intended to be implemented by clients.
Restriction:
  This interface is not intended to be extended by clients.

## Method Summary

Modifier and Type
Method
Description
`ParameterizedCommand`
`createCommand(String id)`
Allows to create an instance of an existing command based on the id parameter which does not require parameters Delegates to createCommand(String,Map) passing in null as Map parameter
`ParameterizedCommand`
`createCommand(String id, Map<String,?> parameters)`
Allows to create an instance of an existing command based on the id parameter
`Category`
`defineCategory(String id, String name, String description)`
`Command`
`defineCommand(String id, String name, String description, Category category, IParameter[] parameters)`
`Command`
`defineCommand(String id, String name, String description, Category category, IParameter[] parameters, String helpContextId)`
`Category`
`getCategory(String categoryId)`
Get category for id.
`Command`
`getCommand(String commandId)`
Get command for id.

## Method Details

### createCommand

ParameterizedCommand createCommand(String id, Map<String,?> parameters)
Allows to create an instance of an existing command based on the id parameter

Parameters:
  `id` - - Command to create
  `parameters` - - Map of the parameters of the command or null
Returns:
  ParameterizedCommand - created command or null

### createCommand

ParameterizedCommand createCommand(String id)
Allows to create an instance of an existing command based on the id parameter which does not require parameters Delegates to createCommand(String,Map) passing in null as Map parameter

Parameters:
  `id` - - Command to create
Returns:
  ParameterizedCommand - created command or null

### defineCategory

Category defineCategory(String id, String name, String description)

Parameters:
  `id` - - Category to define
  `name` - - The name of this category; must not be `null`
  `description` - - The description for this category; may be `null`
Returns:
  the defined category
Restriction:

### defineCommand

Command defineCommand(String id, String name, String description, Category category, IParameter[] parameters)

Parameters:
  `id` - - Command to define
  `name` - - The name of this command; must not be `null`
  `description` - - The description for this command; may be `null`
  `category` - - The category for this command; must not be `null`
  `parameters` - - The parameters understood by this command. This value may be either `null` or empty if the command does not accept parameters
Returns:
  the defined command
Restriction:

### defineCommand

Command defineCommand(String id, String name, String description, Category category, IParameter[] parameters, String helpContextId)

Parameters:
  `id` - - Command to define
  `name` - - The name of this command; must not be `null`
  `description` - - The description for this command; may be `null`
  `category` - - The category for this command; must not be `null`
  `parameters` - - The parameters understood by this command. This value may be either `null` or empty if the command does not accept parameters
  `helpContextId` - - The identifier of the help context to associate with this command; may be `null` if this command does not have any help associated with it
Returns:
  the defined command
Restriction:

### getCategory

Category getCategory(String categoryId)
Get category for id.

Parameters:
  `categoryId` - - The category id
Returns:
  the category for id

### getCommand

Command getCommand(String commandId)
Get command for id.

Parameters:
  `commandId` - - The command id
Returns:
  the command for id