Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.eclipse.ui.commands
Interface ICommand

All Superinterfaces:
  Comparable

public interface ICommand
extends Comparable

An instance of `ICommand` is a handle representing a command as defined by the extension point `org.eclipse.ui.commands`. The identifier of the handle is identifier of the command being represented.

An instance of `ICommand` can be obtained from an instance of `ICommandManager` for any identifier, whether or not a command with that identifier defined in the plugin registry.

The handle-based nature of this API allows it to work well with runtime plugin activation and deactivation. If a command is defined, that means that its corresponding plug-in is active. If the plug-in is then deactivated, the command will still exist but it will be undefined. An attempts to use an undefined command will result in a `NotDefinedException` being thrown.

This interface is not intended to be extended or implemented by clients.

Since:
  3.0
See Also:
  `ICommandListener`, `ICommandManager`

Method Summary
`void` | `addCommandListener(ICommandListener commandListener)` Registers an instance of `ICommandListener` to listen for changes to attributes of this instance.
`Object` | `execute(Map parameterValuesByName)` Executes with the map of parameter values by name.
`Map` | `getAttributeValuesByName()` Returns the map of attribute values by name.
`String` | `getCategoryId()` Returns the identifier of the category of the command represented by this handle.
`String` | `getDescription()` Returns the description of the command represented by this handle, suitable for display to the user.
`String` | `getId()` Returns the identifier of this handle.
`List` | `getKeySequenceBindings()` Returns the list of key sequence bindings for this handle.
`String` | `getName()` Returns the name of the command represented by this handle, suitable for display to the user.
`boolean` | `isDefined()` Returns whether or not the command represented by this handle is defined.
`boolean` | `isHandled()` Returns whether or not this command is handled.
`void` | `removeCommandListener(ICommandListener commandListener)` Unregisters an instance of `ICommandListener` listening for changes to attributes of this instance.

Methods inherited from interface java.lang.Comparable
`compareTo`

Method Detail

### addCommandListener

    public void addCommandListener(ICommandListener commandListener)

  Registers an instance of `ICommandListener` to listen for changes to attributes of this instance.

  Parameters:
    `commandListener` - the instance of `ICommandListener` to register. Must not be `null`. If an attempt is made to register an instance of `ICommandListener` which is already registered with this instance, no operation is performed.

### execute

    public Object execute(Map parameterValuesByName)
                   throws ExecutionException,
                          NotHandledException

  Executes with the map of parameter values by name.

  Parameters:
    `parameterValuesByName` - the map of parameter values by name. Reserved for future use, must be `null`.
  Returns:
    the result of the execution. Reserved for future use, must be `null`.
  Throws:
    `ExecutionException` - if an exception occurred during execution.
    `NotHandledException` - if this is not handled.

### getAttributeValuesByName

    public Map getAttributeValuesByName()
                                 throws NotHandledException

  Returns the map of attribute values by name.

  Notification is sent to all registered listeners if this property changes.

  Returns:
    the map of attribute values by name. This map may be empty, but is guaranteed not to be `null`. If this map is not empty, its collection of keys is guaranteed to only contain instances of `String`.
  Throws:
    `NotHandledException` - if this is not handled.

### getCategoryId

    public String getCategoryId()
                         throws NotDefinedException

  Returns the identifier of the category of the command represented by this handle.

  Notification is sent to all registered listeners if this attribute changes.

  Returns:
    the identifier of the category of the command represented by this handle. May be `null`.
  Throws:
    `NotDefinedException` - if the command represented by this handle is not defined.

### getDescription

    public String getDescription()
                          throws NotDefinedException

  Returns the description of the command represented by this handle, suitable for display to the user.

  Notification is sent to all registered listeners if this attribute changes.

  Returns:
    the description of the command represented by this handle. Guaranteed not to be `null`.
  Throws:
    `NotDefinedException` - if the command represented by this handle is not defined.

### getId

    public String getId()

  Returns the identifier of this handle.

  Returns:
    the identifier of this handle. Guaranteed not to be `null`.

### getKeySequenceBindings

    public List getKeySequenceBindings()

  Returns the list of key sequence bindings for this handle. This method will return all key sequence bindings for this handle's identifier, whether or not the command represented by this handle is defined.

  Notification is sent to all registered listeners if this attribute changes.

  Returns:
    the list of key sequence bindings. This list may be empty, but is guaranteed not to be `null`. If this list is not empty, it is guaranteed to only contain instances of `KeySequence`.

### getName

    public String getName()
                   throws NotDefinedException

  Returns the name of the command represented by this handle, suitable for display to the user.

  Notification is sent to all registered listeners if this attribute changes.

  Returns:
    the name of the command represented by this handle. Guaranteed not to be `null`.
  Throws:
    `NotDefinedException` - if the command represented by this handle is not defined.

### isDefined

    public boolean isDefined()

  Returns whether or not the command represented by this handle is defined.

  Notification is sent to all registered listeners if this attribute changes.

  Returns:
    `true`, iff the command represented by this handle is defined.

### isHandled

    public boolean isHandled()

  Returns whether or not this command is handled. A command is handled if it currently has an `IHandler` instance associated with it. A command needs a handler to carry out the `execute(Map)` method.

  Notification is sent to all registered listeners if this attribute changes.

  Returns:
    `true`, iff this command is enabled.

### removeCommandListener

    public void removeCommandListener(ICommandListener commandListener)

  Unregisters an instance of `ICommandListener` listening for changes to attributes of this instance.

  Parameters:
    `commandListener` - the instance of `ICommandListener` to unregister. Must not be `null`. If an attempt is made to unregister an instance of `ICommandListener` which is not already registered with this instance, no operation is performed.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2004. All rights reserved.