|
Eclipse Platform Release 3.1 |
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.eclipse.core.commands.common.HandleObject
org.eclipse.core.commands.common.NamedHandleObject
org.eclipse.core.commands.Command
A command is an abstract representation for some semantic behaviour. It is not the actual implementation of this behaviour, nor is it the visual appearance of this behaviour in the user interface. Instead, it is a bridge between the two.
The concept of a command is based on the command design pattern. The notable
difference is how the command delegates responsibility for execution. Rather
than allowing concrete subclasses, it uses a handler mechanism (see the
handlers
extension point). This provides another level of
indirection.
A command will exist in two states: defined and undefined. A command is
defined if it is declared in the XML of a resolved plug-in. If the plug-in is
unloaded or the command is simply not declared, then it is undefined. Trying
to reference an undefined command will succeed, but trying to access any of
its functionality will fail with a NotDefinedException
. If
you need to know when a command changes from defined to undefined (or vice
versa), then attach a command listener.
Commands are mutable and will change as their definition changes.
Field Summary | |
---|---|
static boolean |
DEBUG_COMMAND_EXECUTION
This flag can be set to true if commands should print
information to System.out when executing. |
static boolean |
DEBUG_HANDLERS
This flag can be set to true if commands should print
information to System.out when changing handlers. |
static String |
DEBUG_HANDLERS_COMMAND_ID
This flag can be set to a particular command identifier if only that command should print information to System.out when
changing handlers. |
Fields inherited from class org.eclipse.core.commands.common.NamedHandleObject |
---|
description, name |
Fields inherited from class org.eclipse.core.commands.common.HandleObject |
---|
defined, id, string |
Method Summary | |
---|---|
void |
addCommandListener(ICommandListener commandListener)
Adds a listener to this command that will be notified when this command's state changes. |
void |
addExecutionListener(IExecutionListener executionListener)
Adds a listener to this command that will be notified when this command is about to execute. |
int |
compareTo(Object object)
Compares this command with another command by comparing each of its non-transient attributes. |
void |
define(String name,
String description,
Category category,
IParameter[] parameters)
Defines this command by giving it a name, and possibly a description as well. |
boolean |
equals(Object object)
Tests whether this command is equal to another object. |
Object |
execute(ExecutionEvent event)
Executes this command by delegating to the current handler, if any. |
Category |
getCategory()
Returns the category for this command. |
IParameter[] |
getParameters()
Returns the parameters for this command. |
boolean |
isEnabled()
Returns whether this command has a handler, and whether this handler is also handled. |
boolean |
isHandled()
Returns whether this command has a handler, and whether this handler is also enabled. |
void |
removeCommandListener(ICommandListener commandListener)
Removes a listener from this command. |
void |
removeExecutionListener(IExecutionListener executionListener)
Removes a listener from this command. |
boolean |
setHandler(IHandler handler)
Changes the handler for this command. |
String |
toString()
The string representation of this command -- for debugging purposes only. |
void |
undefine()
Makes this scheme become undefined. |
Methods inherited from class org.eclipse.core.commands.common.NamedHandleObject |
---|
getDescription, getName |
Methods inherited from class org.eclipse.core.commands.common.HandleObject |
---|
getId, hashCode, isDefined |
Methods inherited from class java.lang.Object |
---|
clone, finalize, getClass, notify, notifyAll, wait, wait, wait |
Field Detail |
public static boolean DEBUG_COMMAND_EXECUTION
true
if commands should print
information to System.out
when executing.
public static boolean DEBUG_HANDLERS
true
if commands should print
information to System.out
when changing handlers.
public static String DEBUG_HANDLERS_COMMAND_ID
System.out
when
changing handlers.
Method Detail |
public final void addCommandListener(ICommandListener commandListener)
commandListener
- The listener to be added; must not be null
.public final void addExecutionListener(IExecutionListener executionListener)
executionListener
- The listener to be added; must not be null
.public final int compareTo(Object object)
compareTo
in interface Comparable
object
- The object with which to compare; must be an instance of
Command
.
public final void define(String name, String description, Category category, IParameter[] parameters)
Defines this command by giving it a name, and possibly a description as
well. The defined property automatically becomes true
.
Notification is sent to all listeners that something has changed.
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; may be null
.parameters
- The parameters understood by this command. This value may be
either null
or empty if the command does not
accept parameters.public final boolean equals(Object object)
equals
in class HandleObject
object
- The object with which to compare; may be null
.
true
if the commands are equal; false
otherwise.public final Object execute(ExecutionEvent event) throws ExecutionException, NotHandledException
event
- An event containing all the information about the current
state of the application; must not be null
.
null
. This
result will be available to the client executing the command, and
execution listeners.
ExecutionException
- If the handler has problems executing this command.
NotHandledException
- If there is no handler.public final Category getCategory() throws NotDefinedException
null
.
NotDefinedException
- If the handle is not currently defined.public final IParameter[] getParameters() throws NotDefinedException
null
, if the command has no parameters.
NotDefinedException
- If the handle is not currently defined.public final boolean isEnabled()
true
if the command is handled; false
otherwise.public final boolean isHandled()
true
if the command is handled; false
otherwise.public final void removeCommandListener(ICommandListener commandListener)
commandListener
- The listener to be removed; must not be null
.public final void removeExecutionListener(IExecutionListener executionListener)
executionListener
- The listener to be removed; must not be null
.public final boolean setHandler(IHandler handler)
System.out
.
handler
- The new handler; may be null
if none.
true
if the handler changed; false
otherwise.public final String toString()
toString
in class HandleObject
null
.public final void undefine()
null
. Notification is sent to
all listeners.
undefine
in class HandleObject
|
Eclipse Platform Release 3.1 |
|||||||||||
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, 2005. All rights reserved.