Class CommandManager
- All Implemented Interfaces:
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:
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final StringThe identifier of the category in which all auto-generated commands will appear.Fields inherited from class org.eclipse.core.commands.common.HandleObjectManager
definedHandleObjects, handleObjectsById -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoidAdds a listener to this command manager.voidaddExecutionListener(IExecutionListener listener) Adds an execution listener to this manager.voidcategoryChanged(CategoryEvent categoryEvent) Notifies that one or more properties of an instance ofCategoryhave changed.voidcommandChanged(CommandEvent commandEvent) Notifies that one or more properties of an instance ofCommandhave changed.voiddefineUncategorizedCategory(String name, String description) Sets the name and description of the category for uncategorized commands.deserialize(String serializedParameterizedCommand) Returns aParameterizedCommandwith a command and parameterizations as specified in the providedserializedParameterizedCommandstring.voidfireNotDefined(String commandId, NotDefinedException exception) Fires thenotDefinedevent forexecutionListeners.voidfireNotEnabled(String commandId, NotEnabledException exception) Fires thenotEnabledevent forexecutionListeners.voidfirePostExecuteFailure(String commandId, ExecutionException exception) Fires thepostExecuteFailureevent forexecutionListeners.voidfirePostExecuteSuccess(String commandId, Object returnValue) Fires thepostExecuteSuccessevent forexecutionListeners.voidfirePreExecute(String commandId, ExecutionEvent event) Fires thepreExecuteevent forexecutionListeners.Command[]Returns all of the commands known by this manager -- defined and undefined.getCategory(String categoryId) Gets the category with the given identifier.getCommand(String commandId) Gets the command with the given identifier.Category[]Returns the categories that are defined.Returns the set of identifiers for those category that are defined.Returns the set of identifiers for those commands that are defined.Command[]Returns the commands that are defined.Returns the set of identifiers for those parameter types that are defined.Returns the command parameter types that are defined.getHelpContextId(Command command) Gets the help context identifier for a particular command.getParameterType(String parameterTypeId) Gets the commandParameterTypewith the given identifier.voidparameterTypeChanged(ParameterTypeEvent parameterTypeEvent) Notifies that one or more properties of an instance ofParameterTypehave changed.voidRemoves a listener from this command manager.voidremoveExecutionListener(IExecutionListener listener) Removes an execution listener from this command manager.voidsetHandlersByCommandId(Map handlersByCommandId) Block updates all of the handlers for all of the commands.voidsetHelpContextId(IHandler handler, String helpContextId) Sets the help context identifier to associate with a particular handler.Methods inherited from class org.eclipse.core.commands.common.HandleObjectManager
checkId, getDefinedHandleObjectIdsMethods inherited from class org.eclipse.core.commands.common.EventManager
addListenerObject, clearListeners, getListeners, isListenerAttached, removeListenerObject
-
Field Details
-
AUTOGENERATED_CATEGORY_ID
The identifier of the category in which all auto-generated commands will appear. This value must never benull.- Since:
- 3.2
- See Also:
-
-
Constructor Details
-
CommandManager
public CommandManager()
-
-
Method Details
-
addCommandManagerListener
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 benull.
-
addExecutionListener
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 benull.
-
categoryChanged
Description copied from interface:ICategoryListenerNotifies that one or more properties of an instance ofCategoryhave changed. Specific details are described in theCategoryEvent.- Specified by:
categoryChangedin interfaceICategoryListener- Parameters:
categoryEvent- the category event. Guaranteed not to benull.
-
commandChanged
Description copied from interface:ICommandListenerNotifies that one or more properties of an instance ofCommandhave changed. Specific details are described in theCommandEvent.- Specified by:
commandChangedin interfaceICommandListener- Parameters:
commandEvent- the command event. Guaranteed not to benull.
-
defineUncategorizedCategory
Sets the name and description of the category for uncategorized commands. This is the category that will be returned ifgetCategory(String)is called withnull.- Parameters:
name- The name of the category for uncategorized commands; must not benull.description- The description of the category for uncategorized commands; may benull.- Since:
- 3.2
-
deserialize
public ParameterizedCommand deserialize(String serializedParameterizedCommand) throws NotDefinedException, SerializationException Returns a
ParameterizedCommandwith a command and parameterizations as specified in the providedserializedParameterizedCommandstring. TheserializedParameterizedCommandmust use the format returned byParameterizedCommand.serialize()and described in the Javadoc for that method.If a parameter id encoded in the
serializedParameterizedCommanddoes not exist in the encoded command, that parameter id and value are ignored. A given parameter id should not be used more than once inserializedParameterizedCommand. 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 benull- Returns:
- a
ParameterizedCommandwith the command and parameterizations encoded in theserializedParameterizedCommand; nevernull. - Throws:
NotDefinedException- if the command indicated inserializedParameterizedCommandis not definedSerializationException- if there is an error deserializingserializedParameterizedCommand- Since:
- 3.2
- See Also:
-
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
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 benull. If the category isnull, 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:
-
getCommand
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 benulland 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:
-
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
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
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
Returns the commands that are defined.- Returns:
- The defined commands; this value may be empty, but it is never
null. - Since:
- 3.2
-
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
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
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, thennullis returned.- Parameters:
command- The command for which the help context should be retrieved; must not benull.- 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
Gets the commandParameterTypewith 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 benulland must not be zero-length.- Returns:
- The
ParameterTypewith the given identifier; this value will never benull, but it might be undefined. - Since:
- 3.2
-
parameterTypeChanged
Notifies that one or more properties of an instance ofParameterTypehave changed. Specific details are described in theParameterTypeEvent.- Specified by:
parameterTypeChangedin interfaceIParameterTypeListener- Parameters:
parameterTypeEvent- the event. Guaranteed not to benull.- Since:
- 3.2
-
removeCommandManagerListener
Removes a listener from this command manager.- Parameters:
listener- The listener to be removed; must not benull.
-
removeExecutionListener
Removes an execution listener from this command manager.- Parameters:
listener- The listener to be removed; must not benull.
-
setHandlersByCommandId
Block updates all of the handlers for all of the commands. If the handler isnullor 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 benullif all handlers should be cleared. Similarly, if the map is empty, then all commands will become unhandled.
-
setHelpContextId
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 benull.helpContextId- The help context identifier to register; may benullif the help context identifier should be removed.- Since:
- 3.2
-
fireNotEnabled
Fires thenotEnabledevent forexecutionListeners.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, nevernull.exception- The exception, nevernull.- Since:
- 3.4
-
fireNotDefined
Fires thenotDefinedevent forexecutionListeners.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, nevernull.exception- The exception, nevernull.- Since:
- 3.4
-
firePreExecute
Fires thepreExecuteevent forexecutionListeners.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, nevernull.event- The event that triggered the command, may benull.- Since:
- 3.4
-
firePostExecuteSuccess
Fires thepostExecuteSuccessevent forexecutionListeners.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, nevernull.returnValue- The value returned from the command, may benull.- Since:
- 3.4
-
firePostExecuteFailure
Fires thepostExecuteFailureevent forexecutionListeners.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, nevernull.exception- The exception, nevernull.- Since:
- 3.4
-