Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Programming
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Databases
Mail Systems
openSolaris
Eclipse Documentation
Techotopia.com
Virtuatopia.com

How To Guides
Virtualization
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Windows
Problem Solutions
Privacy Policy

  




 

 

Eclipse Plug-in Developer Guide
Previous Page Home Next Page


Eclipse Platform
Release 3.5

Package org.eclipse.core.commands

Application programming interfaces for commands and handlers.

See:
           Description

Interface Summary
ICategoryListener An instance of this interface can be used by clients to receive notification of changes to one or more instances of Category.
ICommandListener An instance of this interface can be used by clients to receive notification of changes to one or more instances of Command.
ICommandManagerListener An instance of this interface can be used by clients to receive notification of changes to one or more instances of ICommandManager.
IExecutionListener A listener to the execution of commands.
IExecutionListenerWithChecks A listener to the execution of commands.
IHandler A handler is the pluggable piece of a command that handles execution.
IHandler2 Extend the IHandler interface to provide some context for isEnabled() requests.
IHandlerAttributes Attribute constants that have special meanings within this package.
IHandlerListener An instance of this interface can be used by clients to receive notification of changes to one or more instances of IHandler.
INamedHandleStateIds State identifiers that are understood by named handle objects that implement IObjectWithState.
IObjectWithState An object that holds zero or more state objects.
IParameter A parameter for a command.
IParameterTypeListener An instance of this interface can be used by clients to receive notification of changes to one or more instances of ParameterType.
IParameterValues The parameters for a command.
IStateListener A listener to changes in some state.
ITypedParameter A command parameter that has a declared type.
 

Class Summary
AbstractHandler This class is a partial implementation of IHandler.
AbstractHandlerWithState An abstract implementation of IObjectWithState.
AbstractParameterValueConverter Supports conversion between objects and strings for command parameter values.
Category A logical group for a set of commands.
CategoryEvent An instance of this class describes changes to an instance of Category.
Command A command is an abstract representation for some semantic behaviour.
CommandEvent An instance of this class describes changes to an instance of Command.
CommandManager A central repository for commands -- both in the defined and undefined states.
CommandManagerEvent An event indicating that the set of defined command identifiers has changed.
ExecutionEvent The data object to pass to the command (and its handler) as it executes.
HandlerEvent An instance of this class describes changes to an instance of IHandler.
Parameterization A parameter with a specific value.
ParameterizedCommand A command that has had one or more of its parameters specified.
ParameterType Provides information about the type of a command parameter.
ParameterTypeEvent An instance of this class describes changes to an instance of ParameterType.
State A piece of state information that can be shared between objects, and might be persisted between sessions.
 

Exception Summary
ExecutionException Signals that an exception occured during the execution of a command.
NotEnabledException Signals that an attempt was made to execute a command that is not enabled.
NotHandledException Signals that an attempt was made to access the properties of an unhandled object.
ParameterValueConversionException Signals that a problem occurred while converting a command parameter value from string to object, or object to string.
ParameterValuesException Signals that a problem has occurred while trying to create an instance of IParameterValues.
SerializationException Signals that an exception occured while serializing a ParameterizedCommand to a string or deserializing a String to a ParameterizedCommand.
 

Package org.eclipse.core.commands Description

Application programming interfaces for commands and handlers.

Package Specification

This package provides API and implementation classes to define abstract pieces of functionality. These pieces of functionality are intended to provide a common way for plug-ins and the user interface to communicate potential behaviour.

This package is designed so that its elements can be public and dynamic. That is, elements in this package can appear and disappear over the life of the application.

Command

A command is an abstract representation for some semantic behaviour. For example, there might be a "copy" command. How this command actually behaves might be dependent on what state your application is in. It is not the actual implementation of that behaviour, and it is not the visual representation of that behaviour.

Commands are managed by an instance of CommandManager. In fact, a command cannot be constructed directly. Commands are constructed using the method CommandManager.getCommand(String). This ensures that there is only ever one command with a given identifier ever associated with a command. manager.

When a command is first constructed, it is undefined. An undefined command is one that is carrying no information except for an id. Attempts to interact with a command that is undefined will result in a NotDefinedException. Through this mechanism, it is possible for clients to hold references to commands, and still have those commands "disappear" (i.e., become undefined). This is particularly useful in a system built around dynamic components (e.g., plug-ins).

Commands can be grouped into categories. These categories are arbitrary groupings, and have no defined behaviour. These categories might be used in a user interface for breaking up a large list of commands into semantically similar commands -- making the list easier to navigate.

It is also possible to attach listeners to both commands and command managers. A listener on a command manager will be notified if the list of defined commands or categories changes.

Examples


        CommandManager manager = new CommandManager();
        Category category = manager.getCategory("categoryId");
        category.define("name", "description");
        Command command = manager.getCommand("commandId");
        command.define("name", "description", category);

This example shows how to create a command from scratch -- with no existing manager or categories.


        command.undefine();
        command = null;
        category.undefine();
        category = null;

If you wish to get rid of the command, then you simply undefine it. This will send notification to the appropriate listeners, and future attempts to access it will fail. If you are the only one holding on to the command, then it will be garbage collected. However, if other people still have a reference to the command, then the stub will remain until they respond to the change.


        String name;
        try {
                name = command.getName();
        } catch (NotDefinedException e) {
                // Clean-up my reference to the command.
                command = null;
                return;
        }

This shows one way of dealing with commands. Instead of listening for changes to the command, you can simply listen for the exceptions to be thrown. When a NotDefinedException is thrown, you can clean up your own code. How you clean up is application dependent. In this case, the reference is cleared and we return from the method.


        try {
                String name = command.getName();
                
                // Do all your work in the block.
                
        } catch (NotDefinedException e) {
                // Ignore, or possibly throw an error
        }
        
        ...
        
        public commandChanged(CommandEvent e) {
                if (e.hasDefinedChanged()) {
                        command.removeListener(this);
                        command = null;
                }
        }

Another way is to attach a listener, and then simply ignore the exceptions. When the command becomes undefined, you will be notified. This gives your the opportunity to unhook your listener and release your reference.

Handler

A handler is the behaviour of a command at a particular point in time. This is the piece that will actually interact with your application model. For every command, there can be zero or more possible handlers. However, at any one time, there is either one handler (i.e., handled) or no handler (i.e., unhandled).

Handlers must implement IHandler. However, there is a convenient abstract class, AbstractHandler which provides default behaviour for some of the methods in the interface. It is recommended that developers subclass AbstractHandler.

Beside functional behaviour, a handler carries with it a map of attribute values. This is a completely optionaly way of carrying extra data. In the case of the AbstractHandler, this map is empty. Some attributes have well defined meanings. These attributes are defined in IHandlerAttributes.

Like commands, handlers can have listeners attached to them. Listeners will be notified when the attributes of the handler change.

When a handler executes, it is passed an event object (ExecutionEvent) that carries with it some pieces of information. First of all, it contains the parameters for execution. Parameters are simple key-value pairs that are intended to modify the execution in some way. The event also carries with it a collection of contexts that were active at the time of execution. The event also carries two untyped objects: the triggering event and the current application state. In the case of a graphical tool, the triggering event is likely to be the underlying widget toolkit event. The application state might contain information like widget focus information. In your own application, feel free to use whichever of these event attributes that fit your application.

Examples


        IHandler myHandler = createHandler();
        command.setHandler(myHandler);
        
        ExecutionEvent e = new ExecutionEvent(parameters,contexts,trigger,state);
        try {
                command.execute(e);
        } catch (ExecutionException ex) {
                // Notify the user, log the problem, etc.
        }


Eclipse Platform
Release 3.5

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.


 
 
  Published under the terms of the Eclipse Public License Version 1.0 ("EPL") Design by Interspire