View source for Platform Command Framework

= Architecture Overview =

http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/platform-ui-home/R3_1/contributions-proposal/requestForComments_html_m41374bdb.png

<center>Figure 1: High Level Architecture</center>

= Commands =

Commands are managed by the <b>org.eclipse.ui.commands</b> extension point and the ICommandService.

An example of using the extension point to create a command:

 <extension
       point="org.eclipse.ui.commands">
    <category
          description="Actions take at lunch time."
          id="z.ex.view.keybindings.category"
          name="Lunch">
    </category>
    <command
          categoryId="z.ex.view.keybindings.category"
          description="Go for the taco."
          id="z.ex.view.keybindings.eatTaco"
          name="Eat That Taco">
    </command>
 </extension>

You can programmatically create commands as well.  From within a view:

 ICommandService cmdService = (ICommandService) getSite().getService(
     ICommandService.class);
 Category lunch = cmdService
     .getCategory("z.ex.view.keybindings.category");
 if (!lunch.isDefined()) {
   lunch.define("Lunch", "Actions take at lunch time.");
 }
 Command eatTaco = cmdService
     .getCommand("z.ex.view.keybindings.eatTaco");
 if (!eatTaco.isDefined()) {
   eatTaco.define("Eat That Taco", "Go for the taco.", lunch);
 }

Note, however, that a plugin that programmatically defines commands is responsible for cleaning them up if the plugin is ever unloaded.

Also, like IAction you can execute a command directly ... but to get the proper environment it's better to execute it through the IHandlerService.  See [[#Handlers]].

== Executing a command with parameters ==

When a Command specifies its parameters, it can also specify a parameter type and/or some valid values.  For example, the showView command.

  <command
      name="%command.showView.name"
      description="%command.showView.description"
      categoryId="org.eclipse.ui.category.views"
      id="org.eclipse.ui.views.showView"
      defaultHandler="org.eclipse.ui.handlers.ShowViewHandler">
    <commandParameter
        id="org.eclipse.ui.views.showView.viewId"
        name="%command.showView.viewIdParameter"
        values="org.eclipse.ui.internal.registry.ViewParameterValues" />
  </command>

To execute this command, you need to create a ParameterizedCommand with a Parameterization (an instance of a parameter and its value).

 		ICommandService commandService = ...;
 		IHandlerService handlerService = ...;
 		Command showView = commandService
 				.getCommand("org.eclipse.ui.views.showView");
 		IParameter viewIdParm = showView
 				.getParameter("org.eclipse.ui.views.showView.viewId");
 
 		// the viewId parameter provides a list of valid values ... if you
 		// knew the id of the problem view, you could skip this step.
 		// This method is supposed to be used in places like the keys
 		// preference page, to allow the user to select values
 		IParameterValues parmValues = viewIdParm.getValues();
 		String viewId = null;
 		Iterator i = parmValues.getParameterValues().values().iterator();
 		while (i.hasNext()) {
 			String id = (String) i.next();
 			if (id.indexOf("ProblemView") != -1) {
 				viewId = id;
 				break;
 			}
 		}
 
 		Parameterization parm = new Parameterization(viewIdParm, viewId);
 		ParameterizedCommand parmCommand = new ParameterizedCommand(
 				showView, new Parameterization[] { parm });
 
 		handlerService.executeCommand(parmCommand, null);


This executes the showView command with the problem view id.  This is done for us when declaratively specifying a keybinding.

  <key
      sequence="M2+M3+Q X"
      contextId="org.eclipse.ui.contexts.window"
      commandId="org.eclipse.ui.views.showView"
      schemeId="org.eclipse.ui.defaultAcceleratorConfiguration">
    <parameter 
        id="org.eclipse.ui.views.showView.viewId"
        value="org.eclipse.ui.views.ProblemView" />
  </key>

= Handlers =

Handlers are managed by the <b>org.eclipse.ui.handlers</b> extension point and the IHandlerService.  Many Handlers can register for a command.  At any give time, either 0 or 1 handlers will be active for the command.  A handler's active state and enabled state can be controlled declaratively.

 <extension
       point="org.eclipse.ui.handlers">
    <handler
          class="z.ex.view.keybindings.handlers.TacoHandler"
          commandId="z.ex.view.keybindings.eatTaco">
       <activeWhen>
          <with
                variable="activeContexts">
             <iterate
                   operator="or">
                <equals
                      value="z.ex.view.keybindings.contexts.taco"/>
             </iterate>
          </with>
       </activeWhen>
    </handler>
 </extension>

Here the handler is checking the activeContexts variable (See [http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/api/org/eclipse/ui/ISources.html org.eclipse.ui.ISources]) and if the "taco" context is active, the handler is active.

The handler itself, <b>TacoHandler</b>, must implement IHandler but would usually be derived from the abstract base class [http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/api/org/eclipse/core/commands/AbstractHandler.html org.eclipse.core.commands.AbstractHandler].

You can create and activate a handler programmatically:

 IHandlerService handlerService = (IHandlerService) getSite()
     .getService(IHandlerService.class);
 IHandler handler = new AbstractHandler() {
   public Object execute(ExecutionEvent event)
           throws ExecutionException {
     System.out.println("Eat that Taco");
     return null;
   }
 };
 handlerService
     .activateHandler("z.ex.view.keybindings.eatTaco", handler);


Apparently, to run commands we should be calling the IHandlerService, not the Command object execute method itself.

 handlerService.executeCommand("z.ex.view.keybindings.eatTaco", null);

= KeyBindings =

KeyBindings are managed by the <b>org.eclipse.ui.bindings</b> extension point and the IBindingService.  Keybindings cannot be updated programmatically.

 <extension
       point="org.eclipse.ui.bindings">
    <key
          commandId="z.ex.view.keybindings.eatTaco"
          contextId="z.ex.view.keybindings.contexts.taco"
          schemeId="org.eclipse.ui.defaultAcceleratorConfiguration"
          sequence="CTRL+3">
    </key>
 </extension>

A key binding is active when the context is active.

= Contexts =

Contexts are managed by the <b>org.eclipse.ui.contexts</b> extension point and the IContextService.

Most contexts are created by the extension point, and activated programmatically when appropriate.  But you can create contexts programmatically as well.  The active contexts usually form a tree, although in the case of keybindings this tree is narrowed down to a branch.

 <extension
       point="org.eclipse.ui.contexts">
    <context
          description="To allow the consumption of Tacos"
          id="z.ex.view.keybindings.contexts.taco"
          name="Mexican Food"
          parentId="org.eclipse.ui.contexts.window">
    </context>
 </extension>

For a context that was attached to a view, it would normally be activated in the view's createPartControl(*) method.

 IContextService contextService = (IContextService) getSite()
   .getService(IContextService.class);
 IContextActivation contextActivation = contextService.activateContext("z.ex.view.keybindings.contexts.taco");

You can only de-activate a context that you are responsible for activating.

Programmatically, you can create contexts:

 Context tacos = contextService
     .getContext("z.ex.view.keybindings.contexts.taco");
 if (!tacos.isDefined()) {
   tacos.define("Mexican Food", "To allow the consumption of Tacos",
       "org.eclipse.ui.contexts.window");
 }

Note, however, that a plugin that programmatically defines contexts is responsible for cleaning them up if the plugin is ever unloaded.

= Tracing Option =

There are a couple of reasons why keybindings and commands might not work.

#Keybindings are in a context that is not active
#There is a keybinding conflict
#No handler is currently active for the command
#There is a handler conflict

To help track down the problem, you can run with debug tracing options.  For example:

 org.eclipse.ui/debug=true
 org.eclipse.ui/trace/keyBindings=true
 org.eclipse.ui/trace/keyBindings.verbose=true
 org.eclipse.ui/trace/sources=true
 org.eclipse.ui/trace/handlers=true
 org.eclipse.ui/trace/handlers.verbose=true
 #org.eclipse.ui/trace/handlers.verbose.commandId=org.eclipse.ui.edit.copy
 org.eclipse.ui/trace/handlers.verbose.commandId=org.eclipse.jdt.ui.navigate.open.type
 org.eclipse.ui/trace/contexts=true
 org.eclipse.ui/trace/contexts.verbose=true


I put these options in a <b>debug.options</b> file and run eclipse using:

 bash$ eclipse -debug debug.options -data /opt/local/pw_workspace >debug.log 2>&1

This logs the debug output to the debug.log file.  This works on windows as well:

 C:\development> eclipse32\eclipse.exe -debug debug.options -data workspaces\pw_workspace >debug.log 2>&1

<b>handlers.verbose.commandId</b> allows you to track the information about a specific command that isn't working.  org.eclipse.jdt.ui.navigate.open.type is the open type dialog (normally CTRL+SHIFT+T) and org.eclipse.ui.edit.copy (commented out) is COPY (normally CTRL+C)