org.eclipse.core.commands
Class CommandManager
java.lang.Object
org.eclipse.core.commands.common.EventManager
org.eclipse.core.commands.common.HandleObjectManager
org.eclipse.core.commands.CommandManager
-
All Implemented Interfaces:
-
ICategoryListener,
ICommandListener,
IParameterTypeListener
-
public final class CommandManager
- extends
HandleObjectManager
- implements
ICategoryListener,
ICommandListener,
IParameterTypeListener
A central repository for commands -- both in the defined and undefined
states. Commands can be created and retrieved using this manager. It is
possible to listen to changes in the collection of commands by attaching a
listener to the manager.
-
Since:
- 3.1
-
See Also:
-
getCommand(String)
Methods inherited from class java.lang.
Object
|
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
|
AUTOGENERATED_CATEGORY_ID
public static final
String AUTOGENERATED_CATEGORY_ID
- The identifier of the category in which all auto-generated commands will
appear. This value must never be
null
.
-
Since:
- 3.2
-
See Also:
-
Constant Field Values
CommandManager
public CommandManager()
addCommandManagerListener
public final void addCommandManagerListener(
ICommandManagerListener listener)
- Adds a listener to this command manager. The listener will be notified
when the set of defined commands changes. This can be used to track the
global appearance and disappearance of commands.
-
-
-
Parameters:
-
listener
- The listener to attach; must not be null
.
addExecutionListener
public final void addExecutionListener(
IExecutionListener listener)
- Adds an execution listener to this manager. This listener will be
notified if any of the commands controlled by this manager execute. This
can be used to support macros and instrumentation of commands.
-
-
-
Parameters:
-
listener
- The listener to attach; must not be null
.
categoryChanged
public final void categoryChanged(
CategoryEvent categoryEvent)
-
Description copied from interface:
ICategoryListener
- Notifies that one or more properties of an instance of
Category
have changed. Specific details are described in
the CategoryEvent
.
-
-
Specified by:
-
categoryChanged
in interface
ICategoryListener
-
-
Parameters:
-
categoryEvent
- the category event. Guaranteed not to be null
.
commandChanged
public final void commandChanged(
CommandEvent commandEvent)
-
Description copied from interface:
ICommandListener
- Notifies that one or more properties of an instance of
Command
have changed. Specific details are described in
the CommandEvent
.
-
-
Specified by:
-
commandChanged
in interface
ICommandListener
-
-
Parameters:
-
commandEvent
- the command event. Guaranteed not to be null
.
defineUncategorizedCategory
public final void defineUncategorizedCategory(
String name,
String description)
- Sets the name and description of the category for uncategorized commands.
This is the category that will be returned if
getCategory(String)
is called with null
.
-
-
-
Parameters:
-
name
- The name of the category for uncategorized commands; must not
be null
. -
description
- The description of the category for uncategorized commands;
may be null
. -
Since:
- 3.2
deserialize
public final
ParameterizedCommand deserialize(
String serializedParameterizedCommand)
throws
NotDefinedException,
SerializationException
-
Returns a
ParameterizedCommand
with a command and
parameterizations as specified in the provided
serializedParameterizedCommand
string. The
serializedParameterizedCommand
must use the format
returned by
ParameterizedCommand.serialize()
and described in the
Javadoc for that method.
If a parameter id encoded in the
serializedParameterizedCommand
does not exist in the
encoded command, that parameter id and value are ignored. A given
parameter id should not be used more than once in
serializedParameterizedCommand
. This will not result in
an exception, but in this case the value of the parameter when the
command is executed is unspecified.
This method will never return null
, however it may throw
an exception if there is a problem processing the serialization string or
the encoded command is undefined.
-
-
-
Parameters:
-
serializedParameterizedCommand
- a string representing a command id and parameter ids and
values; must not be null
-
Returns:
- a
ParameterizedCommand
with the command and
parameterizations encoded in the
serializedParameterizedCommand
; never
null
.
-
Throws:
-
NotDefinedException
- if the command indicated in
serializedParameterizedCommand
is not defined
-
SerializationException
- if there is an error deserializing
serializedParameterizedCommand
-
Since:
- 3.2
-
See Also:
-
ParameterizedCommand.serialize()
getAllCommands
public final
Command[] getAllCommands()
- Returns all of the commands known by this manager -- defined and
undefined.
-
-
-
Returns:
- All of the commands; may be empty, but never
null
. -
Since:
- 3.2
getCategory
public final
Category getCategory(
String categoryId)
- Gets the category with the given identifier. If no such category
currently exists, then the category will be created (but be undefined).
-
-
-
Parameters:
-
categoryId
- The identifier to find; must not be null
. If
the category is null
, then a category suitable
for uncategorized items is defined and returned.
-
Returns:
- The category with the given identifier; this value will never be
null
, but it might be undefined. -
See Also:
-
Category
getCommand
public final
Command getCommand(
String commandId)
- Gets the command with the given identifier. If no such command currently
exists, then the command will be created (but will be undefined).
-
-
-
Parameters:
-
commandId
- The identifier to find; must not be null
and
must not be zero-length.
-
Returns:
- The command with the given identifier; this value will never be
null
, but it might be undefined. -
See Also:
-
Command
getDefinedCategories
public final
Category[] getDefinedCategories()
- Returns the categories that are defined.
-
-
-
Returns:
- The defined categories; this value may be empty, but it is never
null
. -
Since:
- 3.2
getDefinedCategoryIds
public final
Set getDefinedCategoryIds()
- Returns the set of identifiers for those category that are defined.
-
-
-
Returns:
- The set of defined category identifiers; this value may be empty,
but it is never
null
.
getDefinedCommandIds
public final
Set getDefinedCommandIds()
- Returns the set of identifiers for those commands that are defined.
-
-
-
Returns:
- The set of defined command identifiers; this value may be empty,
but it is never
null
.
getDefinedCommands
public final
Command[] getDefinedCommands()
- Returns the commands that are defined.
-
-
-
Returns:
- The defined commands; this value may be empty, but it is never
null
. -
Since:
- 3.2
getDefinedParameterTypeIds
public final
Set getDefinedParameterTypeIds()
- Returns the set of identifiers for those parameter types that are
defined.
-
-
-
Returns:
- The set of defined command parameter type identifiers; this value
may be empty, but it is never
null
. -
Since:
- 3.2
getDefinedParameterTypes
public final
ParameterType[] getDefinedParameterTypes()
- Returns the command parameter types that are defined.
-
-
-
Returns:
- The defined command parameter types; this value may be empty, but
it is never
null
. -
Since:
- 3.2
getHelpContextId
public final
String getHelpContextId(
Command command)
throws
NotDefinedException
- Gets the help context identifier for a particular command. The command's
handler is first checked for a help context identifier. If the handler
does not have a help context identifier, then the help context identifier
for the command is returned. If neither has a help context identifier,
then
null
is returned.
-
-
-
Parameters:
-
command
- The command for which the help context should be retrieved;
must not be null
.
-
Returns:
- The help context identifier to use for the given command; may be
null
.
-
Throws:
-
NotDefinedException
- If the given command is not defined. -
Since:
- 3.2
getParameterType
public final
ParameterType getParameterType(
String parameterTypeId)
- Gets the command
ParameterType
with the given identifier. If no
such command parameter type currently exists, then the command parameter
type will be created (but will be undefined).
-
-
-
Parameters:
-
parameterTypeId
- The identifier to find; must not be null
and
must not be zero-length.
-
Returns:
- The
ParameterType
with the given identifier; this value
will never be null
, but it might be undefined. -
Since:
- 3.2
parameterTypeChanged
public final void parameterTypeChanged(
ParameterTypeEvent parameterTypeEvent)
- Notifies that one or more properties of an instance of
ParameterType
have changed. Specific details are described in the
ParameterTypeEvent
.
-
-
Specified by:
-
parameterTypeChanged
in interface
IParameterTypeListener
-
-
Parameters:
-
parameterTypeEvent
- the event. Guaranteed not to be null
. -
Since:
- 3.2
removeCommandManagerListener
public final void removeCommandManagerListener(
ICommandManagerListener listener)
- Removes a listener from this command manager.
-
-
-
Parameters:
-
listener
- The listener to be removed; must not be null
.
removeExecutionListener
public final void removeExecutionListener(
IExecutionListener listener)
- Removes an execution listener from this command manager.
-
-
-
Parameters:
-
listener
- The listener to be removed; must not be null
.
setHandlersByCommandId
public final void setHandlersByCommandId(
Map handlersByCommandId)
- Block updates all of the handlers for all of the commands. If the handler
is
null
or the command id does not exist in the map, then
the command becomes unhandled. Otherwise, the handler is set to the
corresponding value in the map.
-
-
-
Parameters:
-
handlersByCommandId
- A map of command identifiers (String
) to
handlers (IHandler
). This map may be
null
if all handlers should be cleared.
Similarly, if the map is empty, then all commands will become
unhandled.
setHelpContextId
public final 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
fireNotEnabled
public void fireNotEnabled(
String commandId,
NotEnabledException exception)
- Fires the
notEnabled
event for
executionListeners
.
Note: This supports bridging actions to the command framework,
and should not be used outside the framework.
-
-
-
Parameters:
-
commandId
- The command id of the command about to execute, never
null
. -
exception
- The exception, never null
. -
Since:
- 3.4
fireNotDefined
public void fireNotDefined(
String commandId,
NotDefinedException exception)
- Fires the
notDefined
event for
executionListeners
.
Note: This supports bridging actions to the command framework,
and should not be used outside the framework.
-
-
-
Parameters:
-
commandId
- The command id of the command about to execute, never
null
. -
exception
- The exception, never null
. -
Since:
- 3.4
firePreExecute
public void firePreExecute(
String commandId,
ExecutionEvent event)
- Fires the
preExecute
event for
executionListeners
.
Note: This supports bridging actions to the command framework,
and should not be used outside the framework.
-
-
-
Parameters:
-
commandId
- The command id of the command about to execute, never
null
. -
event
- The event that triggered the command, may be null
. -
Since:
- 3.4
firePostExecuteSuccess
public void firePostExecuteSuccess(
String commandId,
Object returnValue)
- Fires the
postExecuteSuccess
event for
executionListeners
.
Note: This supports bridging actions to the command framework,
and should not be used outside the framework.
-
-
-
Parameters:
-
commandId
- The command id of the command executed, never
null
. -
returnValue
- The value returned from the command, may be null
. -
Since:
- 3.4
firePostExecuteFailure
public void firePostExecuteFailure(
String commandId,
ExecutionException exception)
- Fires the
postExecuteFailure
event for
executionListeners
.
Note: This supports bridging actions to the command framework,
and should not be used outside the framework.
-
-
-
Parameters:
-
commandId
- The command id of the command executed, never
null
. -
exception
- The exception, never null
. -
Since:
- 3.4
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.