Eclipse Search

Loading

Jan 7, 2009

Commands Part 3: Parameters for Commands

Think of a command which opens a file in an editor. You can't possibly create an extensive list of "Open File - somefile.txt", "Open File - someotherfile.txt", etc. Rather you want a generic command like "Open File" with the actual file as a parameter. In this tip, lets see how to create such a command.
The extension point for the command and the parameter:
<command name="Open File"
      defaultHandler="com.eclipse_tips.commads.OpenFileHandler"
      id="com.eclipse-tips.commands.openFileCommand">
   <commandParameter
         id="com.eclipse-tips.commands.filePathParameter"
         name="File Path">
   </commandParameter>
</command>

The handler code looks like:
public Object execute(ExecutionEvent event) throws ExecutionException {   
    String filePathParam = event.getParameter("com.eclipse-tips.commands.filePathParameter");
    IPath filePath = new Path(filePathParam);
    IFile file = ResourcesPlugin.getWorkspace().getRoot().getFile(filePath);
    IWorkbenchPage activePage = ...// get the activePage
    try {
        IDE.openEditor(activePage, file);
    } catch (PartInitException e) {
        ;// display error message
    }
    return null;
}

As you can see, the ExecutionEvent will have all the parameters, which can be accessed thru their ids. Once you get the parameter string, you can use it in your own way. But exactly do we pass different parameters to that command? When you put the command in a toolbar/menu you can specify the parameter:
<menuContribution
      locationURI="toolbar:org.eclipse.ui.main.toolbar">
   <toolbar
         id="com.eclipse-tips.commands.toolbar1">
      <command
            commandId="com.eclipse-tips.commands.someCommand"
            id="com.eclipse-tips.commands.someCommandInToolBar">
      </command>
      <command style="push"
            commandId="com.eclipse-tips.commands.openFileCommand"
            label="Opens somefile">            
         <parameter
               name="com.eclipse-tips.commands.filePathParameter"
               value="MyProject/somefile.txt">
         </parameter>
      </command>
      <command style="push"
            commandId="com.eclipse-tips.commands.openFileCommand"
            label="Opens some other file">
         <parameter
               name="com.eclipse-tips.commands.filePathParameter"
               value="MyProject/someotherfile.txt">
         </parameter>
      </command>
   </toolbar>
</menuContribution>

The above example is a naive one. Lets see the real world example: "Show View" command. The command is generic and can show any view. The view id is given to the command as a parameter:
<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" />
  <commandParameter
        id="org.eclipse.ui.views.showView.makeFast"
        name="%command.showView.makeFastParameter"
        optional="true">
  </commandParameter>

The list of all possible values of the parameter is given by the class ViewParameterValues. The class would iterate thru the view registry and return it. This information is used in defining the key bindings:

Key bindings for parameterized command

If we define our own parameter values, we can also get our command in the key bindings page:
image

Defining the parameters is all about returning a map of display names & the ids:
public class FileParameters implements IParameterValues {
    public Map getParameterValues() {
        Map params = new HashMap();
        params.put("Some File", "MyProject/somefile.txt");
        params.put("Some Other File", "MyProject/someotherfile.txt");
        return params;
    }

}
The name would be displayed in the key bindings page and the id would be used to invoke the command when the key sequence is pressed.

See also:
Part 1: Actions Vs Commands
Part 2: Selection and Enablement of Handlers
Part 4: Misc items ...
Part 5: ISourceProvider & dynamically updating Commands
Part 6: 'toggle' & 'radio' style menu contribution

9 comments:

  1. Are you interested in turning these posts into an article for Eclipse Corner?

    Please see Bug 223445

    ReplyDelete
  2. Your example showed passing strings as parameters. But if my goal is to select a file in the Navigator for example, show a command label in the popup menu on the file and then have my handler take some action on the selected file - How does one pass the file name as a parameter back to the command and handler?

    ReplyDelete
  3. Nice series of tips on commands. It got me to think about reworking my old
    actions.

    Having one problem though...

    The example shows passing static strings as parameters but if the goal is to run a handler on a user selected resource, how does one pass the selection/ resource back to the command/handler from the menuContribution/command?
    (IActionDelegate had selectionChanged for this)

    John C.

    ReplyDelete
  4. @Wayne,
    Yes, I'll be very much interested :-)

    @Anonymous #1:
    I don't think you can change the name/label of a command.

    @Anonymous #2:
    In your handler's execute method,

    HandlerUtil.getVariable(event, ISources.ACTIVE_CURRENT_SELECTION_NAME);

    should give you the current selection. But you don't need a parameterized command for this. A normal command itself would do.

    ReplyDelete
  5. I'm sorry, but I'm a bit new to the Command Framework. I'm having a hard time thinking of a situation where command parameters are useful. Would it be possible for you to give an example where the parameter value is determined at runtime? Thanks.

    ReplyDelete
  6. @Anonymous,

    The 'Show View' command with view id parameter.

    ReplyDelete
  7. That top example is almost exactly what I have been searching for all day. However, I can't figure out how to use it to do what I want. I want to have an eclipse cheatsheet command that opens a specified file. If I use the file open command, it doesn't let me pass in parameters and just opens the window. If I can get it to open (execute) a file then I can run AHK and AutoIt scripts to further the cheatsheet automation. Please help.

    ReplyDelete
  8. HI,

    How to add command handler to the menumanager because

    Menumanager has add method which accept action has input it will not accept command handler…

    IMenuService menuservice = (IMenuService)PlatformUI.getWorkbench().getActiveWorkbenchWi ndow().getService(IMenuService.class);
    ICommandService commadnService = (ICommandService) PlatformUI.getWorkbench().getActiveWorkbenchWindow().getServ ice(ICommandService.class);
    Command cmnd = commadnService.getCommand(“com.jobsleaf.comman.display”);
    MenuManager menumgr = new MenuManager();

    /// how can i add command to menu manager

    menuservice.populateContributionManager(menumgr,”menu:com.ericsson.properties.view.view4 “);

    Please help me i am half the way of the problem

    more info

    http://www.eclipse.org/forums/index.php?t=msg&th=207827&start=0&S=bcb7e587d80fac913deba3389ec6e070
    Thanks
    Ashok

    ReplyDelete
  9. "org.eclipse.ui.handlers" allows to specify parameters, too, but it seems they are not made available in the handler's execute method. Is this right or do I miss something?

    Not working example:










    [...]

    ReplyDelete