Eclipse Tips

Keyboard accessibility thru Command Framework

2009-06-26T13:10:00.000+05:30

Keyboard shortcuts is usually much speedier than reaching out your mouse, moving it, pointing it to something and clicking. But there are some things which cannot be done that easily by keyboard shortcuts. For me, one of them is finding out a closed project and open it. Unfortunately, I've quite a large set of projects in my workspace and try to keep most them closed, when not used. In addition to that in the Package Explorer, I've the 'Closed Projects' filter on. So if I need to open a project, I've use the pull down menu, uncheck 'Closed Projects' navigate thru the working sets to find the right project and double click it. To enable keyboard access to this regular task, I decided to make use of Commands Framework.

The solution is to add a parameterized command, and in the values, I compute the projects which are closed. So when I press the awesome shortcut (Ctrl+3) it would display me the list of closed projects. With few keys, I can navigate to the project I want and open it. Lets see how to do it. First step is the command with the parameter:

<extension point="org.eclipse.ui.commands">
   <command
            defaultHandler="com.eclipse_tips.handlers.OpenProjectHandler"
            id="com.eclipse-tips.openProject.command"
            name="Open Project">
      <commandParameter
               id="com.eclipse-tips.openProject.projectNameParameter"
               name="Name"
               optional="false"
               values="com.eclipse_tips.handlers.ProjectNameParameterValues">
      </commandParameter>
   </command>
</extension>

And the handler:

public Object execute(ExecutionEvent event) throws ExecutionException {
 String projectName = event.getParameter("com.eclipse-tips.openProject.projectNameParameter");
 IWorkspaceRoot root = ResourcesPlugin.getWorkspace().getRoot();
 IProject project = root.getProject(projectName);
 try {
  project.open(null);
 } catch (CoreException e) {
  throw new ExecutionException("Error occured while open project", e);
 }
 return null;
}

For the parameter values, I look for closed projects and return them:

public Map<String, String> getParameterValues() {

 IWorkspaceRoot root = ResourcesPlugin.getWorkspace().getRoot();
 IProject[] projects = root.getProjects();
 Map<String, String> paramValues = new HashMap<String, String>();
 for (IProject project : projects) {
  if (project.exists() && !project.isOpen()) {
   paramValues.put(project.getName(), project.getName());
  }

 }
 return paramValues;
}

So finally, When I press Ctrl+3 and type OPN, I get the list:

This idea can be extended to provide keyboard accessibility to many functionalities. Say in an RCP mail application, you can add a command like 'Go To Mail' with parameter as the Subject/Sender:

Hmmm, if only the 'Built On Eclipse' mail app that I *have* to use, knows the existence of threads other than the UI thread :-(

Subtask in ProgressMonitors

2009-06-03T13:51:00.003+05:30

Here is a trivial tip. When inspecting a bug, I found a interesting thing on Progress Monitors. We know monitor.worked() increments the progress bar, but how do we change the text to update the current subtask? The initial text is set by the beginTask() method and it should be called only once. I digged into the IProgressMonitor and found the subtask() method:

IRunnableWithProgress operation = new IRunnableWithProgress() {

 public void run(IProgressMonitor monitor) {

  monitor.beginTask("Main task running ...", 5);
  for (int i = 0; i < 5; i++) {
   monitor.subTask("Subtask # " + i + " running.");
   runSubTask(new SubProgressMonitor(monitor, 1), i);
  }
 }

};

Now the question is what happens when the runSubTask() method sets another subTask on the SubProgressMonitor?

private void runSubTask(IProgressMonitor monitor, int subTaskId) {

 monitor.beginTask("Sub task running", 10);
  for (int i = 0; i < 10; i++) {
   monitor.subTask("Inside subtask, " + i + " out of 10");
   // do something here ...
   monitor.worked(1);
   if (monitor.isCanceled())
    throw new OperationCanceledException();
 }
  monitor.done();
 }

}

Basically the SubProgressMonitor's subTask() overwrites the parent's subTask(). Thats the default behaviour. You can customize it with the style bits provided in the SubProgressMonitor:

If you want to append the SubProgressMonitor's subTask info, use the style PREPEND_MAIN_LABEL_TO_SUBTASK:

new SubProgressMonitor(monitor, 1, SubProgressMonitor.PREPEND_MAIN_LABEL_TO_SUBTASK), i);

Else if you want to ignore it altogher then use the SUPPRESS_SUBTASK_LABEL style:

new SubProgressMonitor(monitor, 1, SubProgressMonitor.SUPPRESS_SUBTASK_LABEL), i);

Search menu in Mac - the implementation

2009-05-29T15:10:00.004+05:30

In the previous entry I mentioned about the Search Menu in Mac. Lets see what that search menu contains:

The first item is the "Clear" menu. It clears the recent search history. Next comes the recent searches. If you want to call it as "Search History", you can do it in the title field menu item. The title field & clear menu item are visible only when there is at least one entry in the recent searches. The menu can also have custom items, where you can include you own action items. Lets see how to add all these in an SWT app:

Text searchText = new Text(shell, SWT.SEARCH | SWT.ICON_CANCEL | SWT.ICON_SEARCH);
  SearchFieldSupport searchFieldSupport = new SearchFieldSupport(searchText);
  Menu menu = new Menu(searchText);
  
  MenuItem customItem = new MenuItem(menu, SWT.NONE);
  customItem.setText("Custom Action");
  customItem.addSelectionListener(new SelectionAdapter() {
   public void widgetSelected(SelectionEvent e) {
    MessageDialog.openInformation(shell, "Search Field", "Custom action is done here");
   };
  });
  
  MenuItem sep1 = new MenuItem(menu, SWT.SEPARATOR);
  
  MenuItem recentMenuItem = new MenuItem(menu, SWT.NONE);
  recentMenuItem.setText("Search History");
  SearchFieldSupport.setRecentSearchesTitle(recentMenuItem);
  
  // for the search history
  MenuItem recentsMenuItem = new MenuItem(menu, SWT.PUSH);
  SearchFieldSupport.setRecentSearches(recentsMenuItem);
  
  MenuItem sep2 = new MenuItem(menu, SWT.SEPARATOR);

  MenuItem clearMenuItem = new MenuItem(menu, SWT.PUSH);
  clearMenuItem.setText("Clear History");
  SearchFieldSupport.setClearRecents(clearMenuItem);

  searchFieldSupport.setMenu(menu);

Here is the result:

Its almost perfect except that when we clear the search history and see the menu, it looks like this:

Its because the separators are still shown even when there is no recent menu items. The hack is to set the separator as a resentSearches menu item:

MenuItem sep2 = new MenuItem(menu, SWT.SEPARATOR);
  SearchFieldSupport.setRecentSearchesTitle(sep2);

The Search Field also supports a custom menu item which tells that there is no recent search items. This menu item is automatically hidden when there search history is not empty. We can add that also before the second separator:

MenuItem recentsMenuItem = new MenuItem(menu, SWT.PUSH);
  SearchFieldSupport.setRecentSearches(recentsMenuItem);
  
  MenuItem noRecentMenuItem = new MenuItem(menu, SWT.NONE);
  noRecentMenuItem.setText("No Search History");
  SearchFieldSupport.setNoRecentSearches(noRecentMenuItem);
  
  MenuItem sep2 = new MenuItem(menu, SWT.SEPARATOR);
  SearchFieldSupport.setRecentSearchesTitle(sep2);

Now we are all set:

The last missing piece of the puzzle, the SearchFieldSupport class:

package org.eclipse.ui.cocoa.ext;

import org.eclipse.swt.events.DisposeEvent;
import org.eclipse.swt.events.DisposeListener;
import org.eclipse.swt.events.KeyEvent;
import org.eclipse.swt.events.KeyListener;
import org.eclipse.swt.widgets.Menu;
import org.eclipse.swt.widgets.MenuItem;
import org.eclipse.swt.widgets.Text;
import org.eclipse.ui.cocoa.ext.internal.NSSearchField;

/**
 * 
 * @author Prakash G.R.
 * 
 */
public class SearchFieldSupport implements KeyListener, DisposeListener {
 
 private final NSSearchField nsSearchField;
 private final Text text;

 public SearchFieldSupport(Text text) {
  this.text = text;
  text.addKeyListener(this);
  text.addDisposeListener(this);
  nsSearchField = new NSSearchField(text);
 }

 public Text getText() {
  return text;
 }

 public String[] getRecentSearchStrings() {
  return nsSearchField.getRecentSearches();
 }
 
 public void setRecentSearchStrings(String[] recentSearches) {
  nsSearchField.setRecentSearches(recentSearches);
 }

 public void setMenu(Menu menu) {
  nsSearchField.setMenu(menu);
 }

 public static void setNoRecentSearches(MenuItem menuItem) {
  NSSearchField.setTag(menuItem, NSSearchField.NSSearchFieldNoRecentsMenuItemTag);
 }

 public static void setClearRecents(MenuItem menuItem) {
  NSSearchField.setTag(menuItem, NSSearchField.NSSearchFieldClearRecentsMenuItemTag);
 }

 public static void setRecentSearchesTitle(MenuItem menuItem) {
  NSSearchField.setTag(menuItem, NSSearchField.NSSearchFieldRecentsTitleMenuItemTag);
 }

 public static void setRecentSearches(MenuItem menuItem) {
  NSSearchField.setTag(menuItem, NSSearchField.NSSearchFieldRecentsMenuItemTag);
 }

 public void widgetDisposed(DisposeEvent e) {
  text.removeKeyListener(this);
 }

 public void keyPressed(KeyEvent e) {
  // do nothing
 }

 public void keyReleased(KeyEvent e) {
  if (e.keyCode == '\r') {
   String[] recentSearchStrings = getRecentSearchStrings();
   int oldSize = recentSearchStrings.length;
   String[] newSearchStrings = new String[recentSearchStrings.length + 1];
   System.arraycopy(recentSearchStrings, 0, newSearchStrings, 0, recentSearchStrings.length);
   newSearchStrings[oldSize] = text.getText();
   setRecentSearchStrings(newSearchStrings);
   text.setSelection(0, text.getText().length());
  }
 }

}

and the custom NSSearchField class:

package org.eclipse.ui.cocoa.ext.internal;

import java.lang.reflect.Field;

import org.eclipse.swt.internal.cocoa.NSArray;
import org.eclipse.swt.internal.cocoa.NSMenu;
import org.eclipse.swt.internal.cocoa.NSMenuItem;
import org.eclipse.swt.internal.cocoa.NSMutableArray;
import org.eclipse.swt.internal.cocoa.NSString;
import org.eclipse.swt.internal.cocoa.OS;
import org.eclipse.swt.internal.cocoa.id;
import org.eclipse.swt.widgets.Menu;
import org.eclipse.swt.widgets.MenuItem;
import org.eclipse.swt.widgets.Text;

/**
 * @author Prakash G.R.
 * 
 */
@SuppressWarnings("restriction")
public class NSSearchField extends org.eclipse.swt.internal.cocoa.NSSearchField {

 public static final int NSSearchFieldRecentsTitleMenuItemTag = 1000;
 public static final int NSSearchFieldRecentsMenuItemTag = 1001;
 public static final int NSSearchFieldClearRecentsMenuItemTag = 1002;
 public static final int NSSearchFieldNoRecentsMenuItemTag = 1003;

 private static final int /* long */sel_setSearchMenuTemplate = OS.sel_registerName("setSearchMenuTemplate:");
 private static final int /* long */sel_setTag = OS.sel_registerName("setTag:");
 private static final int /* long */sel_setRecentSearches = OS.sel_registerName("setRecentSearches:");

 public NSSearchField(id id) {
  super(id);
 }

 public NSSearchField(Text text) {
  super(text.view);
 }

 public void setMenu(Menu menu) {
  try {
   Field field = Menu.class.getDeclaredField("nsMenu");
   field.setAccessible(true);

   NSMenu nsMenu = (NSMenu) field.get(menu);

   OS.objc_msgSend(this.id, sel_setSearchMenuTemplate, nsMenu.id);
  } catch (Exception e) {
   e.printStackTrace();
  }
 }

 public static boolean setTag(MenuItem menuItem, int tag) {
  try {
   Field field = MenuItem.class.getDeclaredField("nsItem");
   field.setAccessible(true);

   NSMenuItem nsMenuItem = (NSMenuItem) field.get(menuItem);
   OS.objc_msgSend(nsMenuItem.id, sel_setTag, tag);

   // no action for titles
   if (tag == NSSearchFieldRecentsTitleMenuItemTag || tag == NSSearchFieldNoRecentsMenuItemTag) {
    nsMenuItem.setAction(0);
   }
   return true;
  } catch (Exception e) {
   return false;
  }
 }

 public String[] getRecentSearches() {
  NSArray recentSearches = super.recentSearches();
  String[] recentSearchStrings = new String[recentSearches.count()];
  for (int i = 0; i < recentSearchStrings.length; i++) {
   recentSearchStrings[i] = (new NSString(recentSearches.objectAtIndex(i))).getString();
  }
  return recentSearchStrings;
 }

 public void setRecentSearches(String[] recentSearchStrings) {
  
  NSMutableArray recentSearches = NSMutableArray.arrayWithCapacity(recentSearchStrings.length);
  for (String aRecentSearcb : recentSearchStrings) {
   NSString nsString = NSString.stringWith(aRecentSearcb);
   recentSearches.addObject(nsString);
  }
  OS.objc_msgSend(this.id, sel_setRecentSearches, recentSearches.id);
  
 }
}

Enjoy!

Search menu in Mac

2009-05-26T17:24:00.001+05:30

In Mac applications, the little search box can have a pull down menu (similar to a View's pull down menu). It can have recent searches, user contributed menu entries, a menu item for clearing the recent searches etc. Here is the search box of Tweetie (the twitter app that I use):

Eclipse by default offers the SWT.SEARCH style which will bring this search box instead of the default text box. But there is no option to add the menu. For today's SWT-Cocoa hack, I tried to enhance the Search box with the search menu and here is the result:

The code is so ugly that I can't post it in public yet. Will post it with refinements tomorrow.

Update: The implementation is available here.

Badge label on Mac Dock icon

2009-05-23T01:17:00.002+05:30

I'm passionate on both Mac and Eclipse. Although Eclipse runs well on a Mac, its not a marriage made in heaven. Its really hard to get the complete Mac experience with a portable UI tool kit. If you think of features like this one, its actually endless list. One such thing is the badge on the Dock Icon. In Mac, the Dock icon can have a badge - like the number of unread mails in your inbox. How much effort does it takes to add a badge to our RCP mail sample? Not much. Since SWT doesn't have a NSDockTile, we need a NSDockTile class with two methods, one to get the DockTile for the application and the other to set the badge on it (there is an easier way by using the Mac Generator tool, but that will be a patch to SWT itself, which I wanted to avoid):

/**
 * @author Prakash G.R. (grprakash@gmail.com) 
 * 
 */
@SuppressWarnings("restriction")
public class NSDockTile extends NSResponder {

 private static final int sel_setBadgeLabel_ = OS.sel_registerName("setBadgeLabel:");
 private static final int sel_dockTile_ = OS.sel_registerName("dockTile");
 private static final int sel_display_ = OS.sel_registerName("display");

 public NSDockTile(int id) {
  super(id);
 }

 public static NSDockTile getApplicationDockTile() {
  NSApplication sharedApplication = NSApplication.sharedApplication();
  int id = OS.objc_msgSend(sharedApplication.id, sel_dockTile_);
  NSDockTile dockTile = new NSDockTile(id);
  return dockTile;
 }

 public void setBadgeLabel(String badgeLabel) {
   NSString nsBadgeLabel = NSString.stringWith(badgeLabel);
   OS.objc_msgSend(this.id, sel_setBadgeLabel_, nsBadgeLabel.id);
   OS.objc_msgSend(this.id, sel_display_);
 }
}

And a two line code to set the badge:

NSDockTile nsDockTile = NSDockTile.getApplicationDockTile();
nsDockTile.setBadgeLabel("6");

There you go in the dock icon and in the minimized window:

In case you were wondering how the GMail icon for the application is set, here is the code for that:

ImageDescriptor imageDescriptor = ImageDescriptor.createFromURL(iconUrl);
Image image = imageDescriptor.createImage();
NSApplication app = NSApplication.sharedApplication();
app.setApplicationIconImage(image.handle);

Oh, BTW, I've just started learning Objective C, Cocoa & related things. So stay tuned, you will see more Mac related posts here. Also what is your favourite Mac feature that you are missing in Eclipse?

Creating a custom Property View

2009-05-16T00:37:00.001+05:30

In an RCP application, you might need a Properties View, which shows only the properties of a specific view or a set of views. But the generic Properties View will show from all the other views that support it. Armed up with the knowledge of how a PageBookView works, lets see how to hack the Properties View to listen only to a specific view.

The isImportant() method is the one which decides whether to create an IPage for the specific IWorkbenchPart or not. The idea is to override that method and return false for all the workbenchPart that we are not interested in. Lets create the view first:

<view
            class="com.eclipse_tips.views.CustomPropertiesView"
            icon="icons/sample.gif"
            id="com.eclipse-tips.views.customePropertiesView"
            name="My Properties View">
</view>

The CustomPropertiesView should extend PropertySheet and override the isImportant():

public class CustomPropertiesView extends PropertySheet {

 @Override
 protected boolean isImportant(IWorkbenchPart part) {
  if (part.getSite().getId().equals(IPageLayout.ID_PROJECT_EXPLORER))
   return true;
  return false;
 }
}

In this case, I'm making the view only to respond to Project Explorer and ignore other views. Here is the CustomPropertyView in action:

If you are on 3.5 or above, you would see the Pin Action in your Custom Properties View. If you don't want the Pin action in your properties view, there is no way to prevent the PropertySheet to adding the action. The action is added to both tool bar and menu in the createControl() method. Only way to get rid of the action is to remove it after the PropertySheet adds it:

@Override
 public void createPartControl(Composite parent) {
  
  super.createPartControl(parent);
  IMenuManager menuManager = getViewSite().getActionBars().getMenuManager();
  IContributionItem[] items = menuManager.getItems();
  for (IContributionItem iContributionItem : items) {
   if(iContributionItem instanceof ActionContributionItem) {
    if(((ActionContributionItem) iContributionItem).getAction() instanceof PinPropertySheetAction) {
     menuManager.remove(iContributionItem);
     break;
    }
   }
  }

  IToolBarManager toolBarManager = getViewSite().getActionBars().getToolBarManager();
  items = toolBarManager.getItems();
  for (IContributionItem iContributionItem : items) {
   if(iContributionItem instanceof ActionContributionItem) {
    if(((ActionContributionItem) iContributionItem).getAction() instanceof PinPropertySheetAction)) {
     toolBarManager.remove(iContributionItem);
     break;
    }
   }
  }
 }

And don't forget to override the isPinned() method:

@Override
 public boolean isPinned() {
  return false;
 }

There you go:

How to create a PageBookView

2009-05-14T15:22:00.166+05:30

Think of Properties View. It displays the properties of the selected element in the active part. Whenever the selection changes or the active part changes, it tracks them and displays the properties (unless you used the 'Pin to selection' feature available from 3.5) There are many views like this, which update themselves when the active part changes. Outline view, Templates view, GEF Palette view, etc. If you want to create such view, its not a tough job - Eclipse provides you all the basic features in the class PageBookView. All you need is to extend this class and fill the void by implementing the abstract methods. Thats what we are going to see in this tip. The use case is to create a ActivePartTrackerView, which will display the name of the current active workbench part.

First lets create a View:

<extension
         point="org.eclipse.ui.views">
      <view
            class="com.eclipse_tips.views.SelectionView"
            icon="icons/sample.gif"
            id="com.eclipse-tips.views.pagebookview"
            name="Selection Provider View">
      </view>
   </extension>

The contents of the PageBookView is arranged in pages (IPage). There can be multiple pages, each of them is associated with a corresponding IWorkbenchPart. When the associated part becomes active, the PageBookView automatically switches to the respective page. When a PageBookView is created, it asks for a bootstrap part by calling getBootstrapPart() method. When no bootstrap part is found, it uses a default page. That default page is also shown when there are no pages for the currently active part. Lets start by creating this default page. To do that we need to implement the createDefaultPage() method, which returns the default page. Lets use the MessagePage which simply displays a string.

@Override
 protected IPage createDefaultPage(PageBook book) {
  MessagePage messagePage = new MessagePage();
  initPage(messagePage);
  messagePage.setMessage("No interested in this part");
  messagePage.createControl(book);
  return messagePage;
 }

Now our SelectionView is up and running, except that its showing a static content not creating any IPages for the active parts. Before we create an IPage, how to determine whether to create an IPage for a given IWorkbenchPart or ignore it? Its by the isImportant() method. Lets say, we want to respond only to the parts that are contributed by the Platform UI.

@Override
 protected boolean isImportant(IWorkbenchPart part) {
  return part.getSite().getPluginId().startsWith("org.eclipse.ui");
 }

So if a Package Explorer(contributed by JDT) or the Manifest Editor(contributed by PDE) is the active part, then our SelectionView will not create any page and use the default page. If its a TextEditor or Project Explorer, then it will create the page and show it.

To create an IPage for a given part, we need to override the doCreatePage() method. Unlike the createDefaultPage() method this doesn't return a IPage, rather a PageRec. Why? This Page Record stores additional information - the associated workbench part and action bars:

@Override
 protected PageRec doCreatePage(IWorkbenchPart part) {
  MessagePage messagePage = new MessagePage();
  initPage(messagePage);
  messagePage.setMessage("Page for "+part.getTitle());
  messagePage.createControl(getPageBook());
  return new PageRec(part, messagePage);
 }

When you are switching between the TextEditor and the ProjectExplore view, the PageBookView will track and find the page for the active part and automatically show it. When the page is no longer needed (the associated part is closed), it would call the doDestroyPage(). This is where you would ideally remove any listeners and dispose of the resources.

So the whole class goes here:

package com.eclipse_tips.views;

import org.eclipse.ui.IWorkbenchPage;
import org.eclipse.ui.IWorkbenchPart;
import org.eclipse.ui.part.IPage;
import org.eclipse.ui.part.MessagePage;
import org.eclipse.ui.part.PageBook;
import org.eclipse.ui.part.PageBookView;

/**
 * @author Prakash G.R.
 *
 */
public class ActivePartTrackerView extends PageBookView {

 @Override
 protected IPage createDefaultPage(PageBook book) {
  MessagePage messagePage = new MessagePage();
  initPage(messagePage);
  messagePage.setMessage("No interested in this part");
  messagePage.createControl(book);
  return messagePage;
 }

 @Override
 protected PageRec doCreatePage(IWorkbenchPart part) {
  MessagePage messagePage = new MessagePage();
  initPage(messagePage);
  messagePage.setMessage("Page for "+part.getTitle());
  messagePage.createControl(getPageBook());
  return new PageRec(part, messagePage);
 }

 @Override
 protected void doDestroyPage(IWorkbenchPart part, PageRec pageRecord) {
  pageRecord.page.dispose();
 }

 @Override
 protected IWorkbenchPart getBootstrapPart() {
  IWorkbenchPage page = getSite().getPage();
  if(page != null) {
   // check whether the active part is important to us
   IWorkbenchPart activePart = page.getActivePart();
   return isImportant(activePart)?activePart:null;
  }
  return null;
 }

 @Override
 protected boolean isImportant(IWorkbenchPart part) {
  return part.getSite().getPluginId().startsWith("org.eclipse.ui");
 }

}

Sheet support in SWT

2009-05-12T16:29:00.002+05:30

For those who have downloaded 3.5 M7 would have seen Sheets support has been added to SWT and Platform UI has used the API wherever applicable. For those who are wondering what a Sheet means, its an eye-candy in Mac. Here is a sample of a MessageDialog shown with and without Sheet style:

(in case you didn't notice the obvious, I'm back on a Mac :-P)

So what is a Sheet?

A Sheet is essentially a Dialog, which is tied to a parent window. It acts as a Modal Dialog, so the user cannot perform any operations on a window until the Dialog is dismissed. (He is free to work on other windows) The dialog is

always attached with the window until dismissed
placed in the center of the window
moves along when the window is moved

To Sheet or not to Sheet?

Use Sheets when the interaction is very short like the question "Is Eclipse a cool product? ". Opening a 15 step Wizard to choose your life partner is not right place to use Sheet.
Do not use Sheets where the user might still need to interact with the Window (like copy something from window and paste it in the Sheet). Since Sheets are Window Modal, it doesn't allow the user to interact with the associated Window
Sheets are not Application Modal. So if you want a dialog to be Application Modal, don' use Sheets
Unlike normal Dialogs, Sheets do not have title. Avoid Sheets where title provides valuable information.
Do not use nested Sheets (says Apple's UI guidelines)

How do I use Sheet?

Simple. Set the SWT.Sheet style to the Shell of the dialog. In case you are using the MessageDialog, pass on the style bit as the last argument to the MessageDialog.open() method

Commands Part 7: Adding standard commands

2009-05-12T14:57:00.002+05:30

In the earlier installments, we have seen adding our commands to menus and toolbars. But what about the standard menu items like Cut, Copy, Paste etc? We'll see how to add these to a context menu of the Sample View.

Create the Sample View through the PDE's Extension Point Wizard. In the SampleView class, notice these lines:

private void hookContextMenu() {

// rest of the code...
getSite().registerContextMenu(menuMgr, viewer);
}

private void fillContextMenu(IMenuManager manager) {

//rest of the code
manager.add(new Separator(IWorkbenchActionConstants.MB_ADDITIONS));
}

The first one registers this context menu, so that other plugins can contribute their commands to it. The second one adds a separator, which serves as a place holder/location where the contribution goes. So the SampleView is ready to accept the contributions, lets now contribute:

<extension
point="org.eclipse.ui.menus">
<menuContribution
locationURI="popup:com.eclipse_tips.commands.part7.views.SampleView?after=additions">
<command commandId="org.eclipse.ui.edit.cut"/>
<command commandId="org.eclipse.ui.edit.copy"/>
<command commandId="org.eclipse.ui.edit.paste"/>
</menuContribution>
</extension>

The id for the context menu, is by default the View's id, and we add our contribution after the separator. We can add any command, either the Platform defined or our own. Result:

Now we have the menu items, images, shortcut keys everything in place (you ought to love the command framework :-)), except that the items are not enabled. Its because there is no handler for these commands for the given context. There are multiple ways to contribute the handler, since we are adding this to our view, lets use the activePartId variable:

<extension
point="org.eclipse.ui.handlers">
<handler
class="com.eclipse_tips.commands.part7.handlers.CutHandler"
commandId="org.eclipse.ui.edit.cut">
<activeWhen>
<with
variable="activePartId">
<equals
value="com.eclipse_tips.commands.part7.views.SampleView">
</equals>
</with>
</activeWhen>
</handler>

Other commands also have similar handlers. Now:

There you go. In the similar way you can add all the standard commands to any menu/context menu you prefer. Just make sure that you have the handler for the commands with the right activeWhen & enabledWhen expression.

The standard command Ids can be found in the IWorkbenchCommandConstants class (available in 3.5)

[Off Topic] Thank you!

2009-04-07T11:20:00.001+05:30

When Google Web Tookit was released to the public, I played with it and realized that an Eclipse plug-in could simply few things. Since I didn't find any, I started learning Eclipse plug-in development to create one. I've fallen in love with Eclipse and its been a wonderful journey since then. I created this blog to publish the tips I've learnt. Shifted myself from server-side-runtime to IDE. I was the first guy to offer Eclipse Plug-in development training in India. With few like-minded-friends, we even started a company to do this training. The clientele includes several small companies and big companies as well. When IBM extended the Eclipse team in Asia, I was the first hire and moved to Eclipse Platform UI team. Last week my committer election successfully concluded and I've become a committer now! Its one of my happiest moments and this blog has been partially responsible for all of this. I've learnt so many things just for the sake of publishing tips.

I really thank all of the readers of this blog. Your comments, emails, queries kept me going. Thanks!

Searching Eclipse Bugzilla

2009-03-18T12:21:00.001+05:30

There are many times you would want to search for a bug, say with a class name / stack trace. Using Bugzilla for this kind of searches is really painful. First the UI that it presents is not an elegant one (esp. if you are used to one single text box of Google) and then its very slow. It would have been much better if our Bugzilla allows Search Engines to index, but its still a work in progress. Meanwhile, Gunnar Wagenknecht has come up with an incubation project that allows searching the bugzilla. It just features one text box as opposed to the Bugzilla:

and you can type in the Bug Number or key words (like 'About Dialog') or a class name and search. Results are usually within a second. Whats even more nice is the right side bar, which has a tag-clouds-style attributes of the bug:

Click on the items and it will filter your results accordingly:

If you use Bugzilla frequently, this is very effective tool and I strongly recommend you to try it.

Do you need PDE custom attribute?

2009-03-14T17:10:00.003+05:30

One of the features that I was very eagerly expecting in 3.5 M6 is PDE's Custom Attribute. As of now, the Manifest editor has very limited ways of editing an attribute in the plug-in. It could be either String/boolean/Java/Resource/Id. What if PDE provides an extension point and you could plug in your own controls in the editor? Well thats exactly the Custom Attribute feature that I'm talking about. I've been playing it with for a while, and its awesome. The possibilities are really endless and here are some samples:

Pick your favourite color:

Select the SWT Platforms you support:

Choose an icon from your plug-in or shared images:

Or the best I've seen - define the location URI for a menu/toolbar contribution:

You can even provide auto complete in the text editor tab:

This feature is not just cool one, but also a useful one and will boost productivity. Its very unfortunate that it slipped this milestone (M6) due to work load. Its even unfortunate that beyond M6 no API/extension point can be added. What this means, we have to wait till 3.6 (released in 2010) to get this feature. Or somehow convince *everyone* that its should be pushed into 3.5 itself. Martin says "that is not impossible", and the way is: "to go through the process (e-mail and public discussion on eclipse-pmc list)". As everyone is busy with EclipseCon, I think that this process would start after EclipseCon.

Meanwhile, if you like this feature and want it in 3.5 itself, why don't you vote for this bug? I'm sure community's voice will be heard. If this gets into next milestone, I'll promise that I'll write a tip on how to use this extension point :-)

Eclipse Search - now with an Eclipse Plugin!

2009-03-11T20:27:00.001+05:30

Searching for Eclipse related material in Google is a painful task. It shows up lots of irrelevant results. With Eclipse Search, this was pretty much eliminated. It searches only our Eclipse related sites and provides relevant results. The results are even categorized into Blogs, Source, etc. To make things simple, I added a search plugin for the browsers. This helps to search help right from your search box of your browser. Still this has one problem - you need a browser to search. You need to copy & paste the class/method name from your Eclipse to Browser and start searching. Switch back to Eclipse and resume the work. Now this can be simplified by a search plugin for Eclipse.

When you open Search Page, you can see an Eclipse Search tab there. You don't even need to copy a text for searching - just a selection would do. The plug-in takes the current selection as the initial input. You can select the labels you want to search for and hit Enter. You get the results right there inside Eclipse itself:

The recent searches are available in the History Menu:

And in case want to switch to a browser from the current results:

Me and few of my team mates are using it regularly and find it very handy. Download and try it yourself.

Commands Part 6: Toggle & Radio menu contributions

2009-03-08T18:56:00.001+05:30

In the previous parts of the series, we saw how Commands contribute to push style menu items. But commands allow you to contribute menu items with 'toggle' and 'radio' style as well. Let us see how to contribute the familiar "Format" menu thru Commands:

First we will look at the toggle style menu contribution. Commands can have states associated with it. A state id known by its id and it can have any value, which is stored in a subclass of org.eclipse.core.commands.State. To know whether a command is checked or not, the Command Framework looks for a state with the id 'org.eclipse.ui.commands.toggleState'. Lets specify the default checked state of Bold to true and Italic to false:

The Framework expects a Boolean value from the state. It doesn't care about which class that holds the state. So why should we use the RegistryToggleState instead of our own state class? Two reasons:

It implements IExecutableExtension. So you can specify the default values in the plugin.xml as I've done above.
It extends PersistentState, so it can remember the value between Eclipse sessions. So if the user had checked/unchecked the menu, restarts Eclipse, he will get the same state as he left before - all this, you get without even your plugin being loaded.

So how should the handler work for this command?

public Object execute(ExecutionEvent event) throws ExecutionException {
     Command command = event.getCommand();
     boolean oldValue = HandlerUtil.toggleCommandState(command);
     // use the old value and perform the operation

return null;
}

Basically, its the Handler's responsibility to update the Command's state. The HandlerUtil has a convenient method which toggles the state and gives you the old value of the state. You can use the value to perform the operation.

The radio state is also similar, which expects the state with a predefined id. Since the same command is contributed for various option, its should be a parameterized command. The id of the parameter which denotes the radio state is also predefined:

Just like toggle state, the state must have the id and the class could be anything that stores the value as String. The RadioState class provides initializing from plugin.xml and also persists the value across sessions.

The menu contribution would specify the parameter value:

<menuContribution
      locationURI="menu:org.eclipse.ui.main.menu?after=additions">
   <menu
         label="Format">
      ... other contributions here
      <command
            commandId="com.eclipse-tips.commandState.alignCommand"
            label="Align Left"
            style="radio">
         <parameter
               name="org.eclipse.ui.commands.radioStateParameter"
               value="left">
         </parameter>
      </command>
      <command
            commandId="com.eclipse-tips.commandState.alignCommand"
            label="Align Center"
            style="radio">
         <parameter
               name="org.eclipse.ui.commands.radioStateParameter"
               value="center">
         </parameter>
      </command>
      <command
            commandId="com.eclipse-tips.commandState.alignCommand"
            label="Align Right"
            style="radio">
         <parameter
               name="org.eclipse.ui.commands.radioStateParameter"
               value="right">
         </parameter>
      </command>
   </menu>
</menuContribution>

The Command Framework understands this parameter and sets the UI contributions according to this value. Again its the handler's job to set the correct state from the command's parameter during execution. You have helper methods in the HandlerUtil to perform this:

public Object execute(ExecutionEvent event) throws ExecutionException {
    if(HandlerUtil.matchesRadioState(event))
        return null; // we are already in the updated state - do nothing
    String currentState = event.getParameter(RadioState.PARAMETER_ID);
    // perform task for current state
    if(currentState.equals("left"))
    // perform left alignment
    else if(currentState.equals("center"))
    // perform center alignment
    // and so on ...

    // and finally update the current state
    HandlerUtil.updateRadioState(event.getCommand(), currentState);

return null;
}

Bonus:

Q: I want the initial value always loaded from the plugin.xml, the state should not be remembered between sessions. Should I write my own State class?

A: Not necessary. You can specify both the default value of the state and whether to persist or not in the plugin.xml itself:

This applies for toggle state as well.

Q: I want to know the state of the command elsewhere in the code. How do I get it?

A: Just use Command.getState(<state id>).getValue(). The state ids are available as constants at RegistryToggleState.STATE_ID and RadioState.STATE_ID

My patch for this feature has just been checked in and should be available from 3.5 M6 onwards. If you are curious, pick up a recent Nightly build and play with this.

WireframeSketcher - Review and free licenses

2009-02-25T16:30:00.003+05:30

A picture is worth of 1000 words. That is why I have a habit of creating mockups/prototypes of UI before creating the real ones. There are umpteen number of tools available in the market, but I'm comfortable with plain old paper & pencil. Mostly because I don't need complex tools and partly because if I convert the price from Dollars to Rupees it would leave a bug hole in my wallet. Add to that I use Mac (my personal laptop), Windows (my official laptop) and Linux (my spare desktop). It is hard for me to find a simple tool that would work on all OS and still available for a cheaper price. To end my worries, here is WireframeSketcher.

Its an Eclipse plugin, so it works perfectly on all the platforms. Lets talk about simplicity.
The tool is as simple as it gets. The editor works on a .screen file, which can be kept under any project. In the editor, you have a drawing canvas and a palette with the most commonly used UI widgets. Drag and drop the elements you need from the palette to the canvas. You can group elements, adjust the Z-Order, move or resize them. Sounds like a perfect fit for me. Here is a screen shot of the product in action:

I usually create the mockup and then create the actual UI. For a change, I tried creating a mockup of the existing UI. The mimicked picture:

Thats a pretty rough sketch. But creating the above took me less than 5 mins! I can spend a little more time and make it look more like the original picture, but I think this conveys the message. I wish it supports more options like generating SWT/Swing code from the mock up. How cool that would be? Awesome, but that would would deviate from its mail goal - creating mockups. I think it will compromise on the simplicity as well.

I wish I could write more about this tool, but honestly there is nothing like you working on this. You don't have to go thru a a big manual. Just create a new .screen file and start using it. Period.

Overall, its a neat and simple tool that helps you to create mockups. If you are looking for a such a tool to prototype the UI and explain it to the customer/boss and willing to live with minor nuances, then this tool is for you. If you are looking for more advanced one with complete control over the UI, you have to look elsewhere.

Now lets come to the last part - cost of it. Right now there is no commercial version available. Evaluation licenses are available to play around with the tool. If you want a full free license, here is a chance exclusively for the readers of this blog.

All you have to do is to post a comment answering this simple question: "What are the pros of UI prototyping?". Remember to enter your comment on or before March 3rd, 2009 and your comment should have your name and email id. Peter will be selecting 5 random answers and will be giving out licenses to them.

(In case you don't want to expose your email id in public, just leave the comment and send your name & email id to my email id: grprakash@gmail.com)

Commands Part 5: Authentication in RCP applications

2009-02-23T13:49:00.003+05:30

One of the frequently asked questions on Command Framework is 'how to dynamically update a command?' I thought I'll couple the answer with implementing ISourceProvider and explain it with a usecase: Authentication in RCP applications. Most of the RCP applications I've seen, needs authentication. Obviously it would need a Login/Logout menu items and other user related options. This can be accomplished in many ways, and I'm going to show you how to do it with Command Framework.
Lets do it in step by step.

Defining the session state thru ISourceProvider:

First, we need to store the session state in a variable. When we say variable in Command Framework, its not a public final static String. It is something that you can use it in the visibleWhen, activeWhen and enabledWhen expressions. The variable has to be provided thru a ISourceProvider:
<extension
      point="org.eclipse.ui.services">
   <sourceProvider
         provider="com.eclipse_tips.rcp.app.SessionSourceProvider">
      <variable
            name="com.eclipse-tips.rcp.app.sessionState"
            priorityLevel="workbench">
      </variable>
   </sourceProvider>
</extension>
A ISourceProvider can provide the state of multiple variables. However, our source provider will give the value of only one variable - 'com.eclipse-tips.rcp.app.sessionState'. The values of this variable would be either 'loggedIn' or 'loggedOut'. The list of values cannot be defined thru the extension, so this is up to you to define it, publish it and use it.
In the extension, you can see the priorityLevel attribute. This is used by the IHandlerService to determine which handler is active for a given command and its defined in the org.eclipse.ui.ISources interface. See my earlier tip on Command Framework for more explanation on this priority attribute.
The class should either implement ISourceProvider or extend AbstractSourceProvider. The preferred way is extending, so we'll do it that way:
public class SessionSourceProvider extends AbstractSourceProvider {
    public final static String SESSION_STATE = "com.eclipse-tips.rcp.app.sessionState";
    private final static String LOGGED_IN = "loggedIn";
    private final static String LOGGED_OUT = "loggedOut";
    boolean loggedIn;

    @Override
    public String[] getProvidedSourceNames() {
        return new String[] {SESSION_STATE};
    }
    @Override
    public Map<String, String> getCurrentState() {
        Map<String, String> currentState = new HashMap<String, String>(1);
        String currentState = loggedIn?LOGGED_IN:LOGGED_OUT;
        currentState.put(SESSION_STATE, currentState);
        return currentState;
    }
     @Override
    public void dispose() {}
    public void setLoggedIn(boolean loggedIn) {
        if(this.loggedIn == loggedIn)
            return; // no change
        this.loggedIn = loggedIn;
        String currentState = loggedIn?LOGGED_IN:LOGGED_OUT;
        fireSourceChanged(ISources.WORKBENCH, SESSION_STATE, currentState);
    }
}
The first method is simple. As I mentioned earlier, a source provider can provider the state of multiple variables. The list of the variables (source names) is returned in the call. The second method is called to get the current state. The variable:value pairs are put in a map and returned back to the caller. The third method dispose is a no-op method for us. These three methods completes the API contract, but we have added one more method, where the value is updated to the source provider itself. So whenever a Login/Logout happens we need to call this method. This method fires the sourceChanged event, so that all the listeners can update accordingly.
When the sourceChanged event is fired, the status of the Command Handlers which has activeWhen or enabledWhen expressions with this variable re-evaluated with the new value of the variable. This holds good for visibleWhen expressions of the Commands as well. So if you want to show/enable a contribution item only when the user has logged in, you can use this variable like:
<extension
      point="org.eclipse.ui.menus">
   <menuContribution
         locationURI="menu:file?after=additions">
      <command
            commandId="org.eclipse.ui.window.preferences">
         <visibleWhen>
            <with
                  variable="com.eclipse-tips.rcp.app.sessionState">
               <equals
                     value="loggedIn">
               </equals>
            </with>
         </visibleWhen>
      </command>
   </menuContribution>
</extension>
Now the File->Preferences will be visible only when the user has logged in.

Updating the state:

Now that we have the source provider and the menu items that are dynamically enabled/disabled or shown/hidden according to the sessionState, the problem is how to we update the state?
Elsewhere, when a command is executed for Login/Logout, we have to make a call to SessionSourceProvider.setLoggedIn() method. But how do we get hold of the instance of the SessionSourceProvider? This is where the ISourceProviderService comes into picture. This service has a getSourceProvider() method, where if you give the variable name, it will give the corresponding source provider. The next obvious question would be where to get the implementation of this service? Not this service, for any service, you can use IServiceLocator to get the implementation and fortunately the IWorkbenchWindow implements this service. So when we execute the Login/Logout command:
// get the window (which is a IServiceLocator)
IWorkbenchWindow window = HandlerUtil.getActiveWorkbenchWindow(event);
// get the service
ISourceProviderService service = (ISourceProviderService) window.getService(ISourceProviderService.class);
// get our source provider by querying by the variable name
SessionSourceProvider sessionSourceProvider = (SessionSourceProvider) service.getSourceProvider(SessionSourceProvider.SESSION_STATE);
// set the value
sessionSourceProvider.setLoggedIn(isSessionActive);

Dynamically updating the Login/Logout command:

The Login and Logout commands are mutually exclusive. When one appears the other won't. So you can have two different commands and use the visibleWhen with our sessionState variable to show/hide them. The other way is to have one command and update the text of the command according to the state. The first way is very similar to the Preference command that is explained above, so let me explain the second way here:
The idea is to define a single command and two handlers:
<extension
      point="org.eclipse.ui.commands">
   <command
         id="com.eclipse-tips.rcp.app.sessionCommand"
         name="Session Command">
   </command>
</extension>
<extension
      point="org.eclipse.ui.handlers">
   <handler
         class="com.eclipse_tips.rcp.app.handlers.LoginHandler"
         commandId="com.eclipse-tips.rcp.app.sessionCommand">
      <activeWhen>
         <with
               variable="com.eclipse-tips.rcp.app.sessionState">
            <equals
                  value="loggedOut">
            </equals>
         </with>
      </activeWhen>
   </handler>
   <handler
         class="com.eclipse_tips.rcp.app.handlers.LogoutHandler"
         commandId="com.eclipse-tips.rcp.app.sessionCommand">
      <activeWhen>
         <with
               variable="com.eclipse-tips.rcp.app.sessionState">
            <equals
                  value="loggedIn">
            </equals>
         </with>
      </activeWhen>
   </handler>
</extension>
<extension
      point="org.eclipse.ui.menus">
   <menuContribution
         locationURI="menu:file?before=quit">
      <command
            commandId="com.eclipse-tips.rcp.app.sessionCommand"
            style="push">
      </command>
   </menuContribution>
</extension>
So the first handler, LoginHandler will be active when the user is logged out and the LogoutHandler will be active when the user is logged in. Both the handlers after performing their respective actions will notify the SessionSourceProvider, but how do we change the menu text? This happens thru IElementUpdater. When a handler implements this interface, it can update the associated contributions. When I say update, it means the text, tooltip, image etc. So the LoginHandler would look like:
public class LoginHandler extends AbstractHandler implements IElementUpdater {
    @Override
    public Object execute(ExecutionEvent event) throws ExecutionException {

        // perform login here ...

        IWorkbenchWindow window = HandlerUtil.getActiveWorkbenchWindow(event);
        ISourceProviderService service = (ISourceProviderService) window.getService(ISourceProviderService.class);
        SessionSourceProvider sessionSourceProvider = (SessionSourceProvider) service.getSourceProvider(SessionSourceProvider.SESSION_STATE);

        // update the source provider
        sessionSourceProvider.setLoggedIn(true);
        return null;
    }
    @Override
    public void updateElement(UIElement element, Map parameters) {
        element.setText("Login");
    }
}
The LogoutHandler also will have a similar code. Remember its not a mandatory thing to have multiple handlers to update the command dynamically. You can do it even with single handler as well.
One last piece, the Command Framework will call the updateElement() method only when the value of the variables in the *when expression is changed. So in other places where you want to update a command when no variable change has occurred, you need to use the ICommandService:
ICommandService commandService = (ICommandService.class)serviceLocator.getService(ICommandService.class);
commandService.refreshElements(commandId, null);

Customizing the About Dialog

2009-02-18T22:40:00.001+05:30

In the About Dialog, the image, text etc, can be customized by the extension point org.eclipse.core.runtime.products (or PDE's product editor). But with few changes into the nightly build of 3.5, the About Dialog sports a new look and is much more customizable. In this tip, lets see how to extend it.

The new Eclipse About Dialog (for the RCP mail sample) looks like this:

If you click the "Installation Details" button, you will get this Dialog:

How about adding our own tab here? You need to extend the new org.eclipse.ui.installationPages extension point.
<extension
      point="org.eclipse.ui.installationPages">
   <page
         class="com.eclipse_tips.rcp.mail.MailInstallationpage"
         id="com.eclipse-tips.rcp.mail.Installationpage"
         name="RCP Mail">
   </page>
</extension>

The class should extend org.eclipse.ui.about.InstallationPage, which has the createControl() method. Create all the UI you want there:

If you see the Plug-ins tab or Configuration tab, there are few buttons. How to add a new button in our RCP Mail Tab? I was looking for a createButtons() method to override, but its not that way. The buttons are contributed thru Command Framework:

<extension
      point="org.eclipse.ui.commands">
   <command
         defaultHandler="com.eclipse_tips.rcp.mail.ShowRegistrationHandler"
         id="com.eclipse-tips.rcp.mail.showRegistrationCommand"
         name="Registration Details">
   </command>
</extension>
<extension
      point="org.eclipse.ui.menus">
   <menuContribution
         locationURI="toolbar:org.eclipse.ui.installationDialog.buttonbar">
      <command
            commandId="com.eclipse-tips.rcp.mail.showRegistrationCommand"
            style="push">
         <visibleWhen>
            <with
                  variable="org.eclipse.ui.installationPage.activePage.id">
               <equals
                     value="com.eclipse-tips.rcp.mail.InstallationPage">
               </equals>
            </with>
         </visibleWhen>
      </command>
   </menuContribution>
</extension>
If you don't understand the above extension, you need to refer to my earlier tips on Command Framework :-P
Result:

Why can't it be as simple as extending a createButtons() method? Well, flexibility for other plugins to extend. Say if we want to add a button to the existing Plug-ins tab, all we have to do is add a menuContribution:

<extension
      point="org.eclipse.ui.menus">
   <menuContribution
         locationURI="toolbar:org.eclipse.ui.installationDialog.buttonbar">
      <command
            commandId="com.eclipse-tips.rcp.mail.showRegistrationCommand"
            style="push">
         <visibleWhen>
            <with
                  variable="org.eclipse.ui.installationPage.activePage.id">
               <equals
                     value="30.PluginPage">
               </equals>
            </with>
         </visibleWhen>
      </command>
   </menuContribution>
</extension>

See. Extending it is now simple!

The id of the Plug-ins tab is "30.PluginPage" and the id of the Configuration tab is "31.SystemPage". Did you notice something odd there? The ids are prefixed with some numbers. These numbers decide the order of the tabs appearing in the dialog. This is not a documented behaviour, so don't expect to work the same in future versions, but for now it works. So if we prefix our ids with a lower number like "10.com.eclipse-tips.rcp.mail.InstallationPage", our tab will be shown first:

The Configuration lists out all the configuration details, so if you want to add your own configuration to it, you need to extend org.eclipse.ui.systemSummarySections:
<extension
      point="org.eclipse.ui.systemSummarySections">
   <section
         class="com.eclipse_tips.rcp.mail.MailSummarySection"
         id="com.eclipse_tips.rcp.mail.mailSummarySection"
         sectionTitle="RCP Mail Details">
   </section>
</extension>

The class should implement org.eclipse.ui.about.ISystemSummarySection, which has a single method write(PrintWriter writer). You can add all the configuration details to the writer:
public class MailSummarySection implements ISystemSummarySection {
    @Override
    public void write(PrintWriter writer) {
        writer.println("User Name=Prakash G.R.");
        writer.println("Mail Server=GMail");
        writer.println("Protocol=POP3");
    }
}

This has been there for a while, thought I'll add it for completeness :-)

Update [24-Feb-2009]: In the recent nightly, the Command Contribution story has been completely removed and createButtons() method have been added. Now the framework is not flexible enough, so you can't contribute to existing pages, but the code gets much simpler now. Trade offs :-)

Using progress bars ...

2009-02-12T23:32:00.000+05:30

In the last tip, I said the top most mistake done by Eclipse plug-in developers is running long running operations in the UI thread. Assuming that you are running it in a non-UI thread, how to show the progress of the execution? Obviously thru progress monitors. But how many different ways are there to show a progress monitor? Lets see them in this tip.
The first option is ProgressMonitorDialog. You have to create a IRunnableWithProgress and use the run method:
ProgressMonitorDialog dialog = new ProgressMonitorDialog(shell);
dialog.run(true, true, new IRunnableWithProgress(){
    public void run(IProgressMonitor monitor) {
        monitor.beginTask("Some nice progress message here ...", 100);
        // execute the task ...
        monitor.done();
    }
});
Result:

As you can see, the dialog is kind-of blocking the user. This dialog is advisable only in the rare cases where the user have to wait till the operation is completed. In most other cases, you should prefer running a Job. A Job is not blocking to the user and can still show the progress. The progress is available in the Progress View.

Job job = new Job("My new job") {
    @Override
    protected IStatus run(IProgressMonitor monitor) {
        monitor.beginTask("Some nice progress message here ...", 100);
        // execute the task ...
        monitor.done();
        return Status.OK_STATUS;
    }
};
job.schedule();

Result:

If you make the job as a user job by calling setUser(true), the progress dialog will be opened, where the user can chose to run the job as a background job. If the user doesn't want to see this dialog again, he can select to 'Always run in background':

When the job is initiated by the user interacting with a workbench part (like clicking a button in a view), a better way to schedule the job is thru the site's IWorkbencSiteProgressService.schedule. When the job begins to execute, the workbench part can show it visually. The default behaviour is to italize the part name:

But you can customize it by overriding the showBusy() method in your WorkbenchPart:
public void showBusy(boolean busy) {
    super.showBusy(busy);
    if(busy)
        setPartName("I'm doing a job right now...");
    else
        setPartName("Sample View");
}
Result:

In case your action doesn't have any WorkbenchPart associated with it, you can use the IWorkbenchWindow.run(...) to show the progress:

If you are running a long running operation in a wizard/wizardPage you should consider running it thru getContainer().run(). This will show the progressBar right there in the wizard dialog itself:

If you are updating the UI elements in the wizardPage during the execution, you have to note that if you do a setEnabled() on any widget, it won't reflect. Its because the container registers the enabled state of the widgets before execution; disables the widgets; executes the task and restores the widget's enabled state to the saved value. So if you have changed the state during the operation, it will be overwritten by the container.

In case, you can't display a progressbar, you should at least use BusyIndicator.showWhile() and display the busy cursor to show that some operation is being executed. Else the user might be wondering why the UI is frozen.

Top 10 mistakes in Eclipse Plug-in Development

2009-01-28T23:35:00.003+05:30

Having trained a lot of new comers to the Eclipse plug-in development, I've seen certain common mistakes repeated all the time. I've tried to compile a top 10 list of such common mistakes, so next time you hit them, you will know that you are not alone :-)

Update: Thanks to Hiroki Kondo(kompiro) a Japanese version of this entry is available here.

(10) Not reading the JavaDoc

This is nothing specific about Eclipse Plug-in development. Its more common among the Java programmers, or probably a common thing among all the programmers - not reading the documentation. How many of you know that there are classes that shouldn't be inherited or the interfaces that are not supposed to be implemented by you? Well API tooling will help you, but there are lot of other corner cases which you won't find unless you read the JavaDoc. I myself do this mistake all the time. Honestly for a long while I didn't know that a command's handler is supposed to return only null (which is the result of the execution)- When did you know this?
In case you didn't know, JDT provides you a JavaDoc view which shows up the Java doc with the formatting.

(9) Forgetting to add a default constructor

You had that nice wizard class which works fine when you create it yourself and put it in a WizardDialog. But you can't make it work with the INewWizard. After a "little" debugging you realize that you didn't have a default constructor for the Wizard class! Yes, its not just the Wizard class, but most of the other classes that you specify in your plugin.xml for that "class" attribute, should have a default constructor, as it will instantiated thru reflection.

(8) Not decomposing into different plugins

Another common thing among the newbies. They have a tendency to put everything into a single plug-in. Splitting your code base across different plug-in improves the modularity and maintainability. You should at least consider splitting the core and ui part, so that testing the core part becomes easy.

(7) Using "internal" code

I've seen this as an unavoidable thing in many cases. You see some functionality in the internal code that you would require, so make use of those internal classes. There are thousands of internal classes, but believe me, the one that used will be refactored and changed in the next release, so you will have a hard time upgrading to a newer release. It has happened to me more than once. Why *that* class of all the classes? sigh!
If you find any internal code generic and useful, raise a bug to make it a part of API. Instead of using the internal classes, you can copy the code into your code base and make use of it.

(6) Directly setting the classpath

Every plugin project is a Java Project, but that doesn't mean that you can simply update the Java classpath with the jar files that you require. Because your plug-in's classpath at runtime will be different. If you had to add a jar to the classpath, you should consider adding it thru the 'Add' button in Classpath section of the Runtime tab.

(5) Ignoring build.properties

Most common mistake among the newbies. Add an icon/resource under a new folder; test the plug-in, which works fine; export it and deploy it elsewhere; it stops working. Reason? The build.properties didn't have an entry for the folder/file that you added, so the exported plug-in doesn't have that resource. So, remember, whenever you add a folder/individual resource, make sure you update the build.properties file as well.

(4) Empty dispose method

Remember the the golden rule, "When you create, you dispose". SWT resources like images and fonts should be always disposed of when you are done with them. I've seen many people not doing this at all. Another important issue is when you are overriding the dispose method, you should always call the super.dispose() to ensure the resources created by the super class are properly disposed. Also, if you have attached any listeners like IPartListener or IResourceChangeListener, during the life cycle of your class, you should consider removing those listeners in the dispose method.

(3) Not honoring monitor.isCanceled()

Your Job does a lengthy operation and the user might want to cancel it. It can be done by pressing cancel in the ProgressMonitor dialog or in the Wizard or thru the Progress View. What ever way he does, the IProgressMonitor supplied to you will have the cancel flag set to true. Its your responsibility to periodically check the isCancelled() and abort the operation. When the user presses 'Cancel' and if nothing happens, believe me, its a very bad user experience.

(2) Blindly contributing to everywhere

People tend to add their contribution virtually everywhere thinking their plug-in is the important one to the user. But hard fact is it will be annoying for the user. So:

Stop adding your view to every perspective that you know

Do not extend org.eclipse.ui.startup unless its really, really, necessary

Do not make your action set to be visible in all the perspectives

Try not to create a modal dialog

When you adding menu items thru objectContributions, try to add it to the specific class, rather than simply Object

(1) Executing a long running operation in Display thread

Do I need to tell about this? Not just newbies, even experienced ones tend to do this mistake. In my present job, I have to use an internal RCP application on a regular basis, does this mistake for almost all the operations. The end result is a non-responding UI and a very frustrated user :-( Once I pointed out a piece of code and asked a developer why he was doing such a big calculation on a Display thread, he was very surprised. He said that he is neither doing a Display.asyncExec() nor a UIJob, so the code will not run in the display thread. Here is a thumb rule. The operation that you do inside the SWT listener methods will be run in the display thread. There are more than few people who don't realize this and think that only the that gets executed in Display.asyncExec or Display.syncExec are the ones that run in the UI thread. So don't do long calculations or contact a server across the network in those listeners. If you have to run such a lengthy operation, spawn off a separate job and return quickly, so the UI remains responsive.

What are the other mistakes that you frequently come across?

[Off Topic] Moving to Google's Feedburner

2009-01-17T17:48:00.001+05:30

This blogs RSS feed is available through FeedBurner. Now that its acquired by Google, they are moving their services to Google platform. The good news for me in that is I've one less password to remember :-) Today I've migrated this blogs feed to the Google services and it went fine and hope works for everyone. I've not seen the stats in the recent while, but looks like the subscribers count is steadily increasing. From a humble 20, its now gone above 500 !

Google Analytics says that planeteclipse.org and eclipsezone.com are the top referrers. So few posts make their way into these sites, are the major source of my subscribers. The more interesting part comes about the way people subscribe to this blog.

Looks like Google Reader+iGoogle takes a lions share and the next is email subscribers. When I added the email subscription option, I thought at most 10 people would sign up thru that service. The count stands above 60!

I started this blog with the intention of delivering tips and tricks of Eclipse Plugin development that I've learnt, and will continue doing that. Meanwhile excuse me for the occasional, pointless posts like this one :-)

Commands Part 4: Misc items ...

2009-01-11T00:22:00.003+05:30

How do I know about execution of a command?

You can use the IExecutionListener:

ICommandService service = (ICommandService) serviceLocator.getService(ICommandService.class);
service.addExecutionListener(new IExecutionListener() {
    public void notHandled(String commandId, NotHandledException exception) {
    }
    public void postExecuteFailure(String commandId, ExecutionException exception) {
    }
    public void postExecuteSuccess(String commandId, Object returnValue) {
    }
    public void preExecute(String commandId, ExecutionEvent event) {
    }
});

The IExecutionListener is merely an observer of the command execution so it can neither veto on it nor make any changes to the event.

How do I get the active Window/Shell in my handler code?

Use HandlerUtil. Its a handy class which gives you access to most common variables like active window, active shell, context ids, active part, current selection, etc.

Shell shell = HandlerUtil.getActiveShell(event);
ISelection selection = HandlerUtil.getCurrentSelection(event);

All of the get* methods will have a get*Checked variants. The first ones will return you null if the variable is not available. The checked ones will throw you an exception if the variable is null. If you have your own variable, you can use the getVariable() method to get it.

Can I programmatically execute a Command?

Yes. But don't simple call command.execute(), use the IHandlerService to execute a command:

IHandlerService handlerService = (IHandlerService) serviceLocator.getService(IHandlerService.class);
handlerService.executeCommand(commandId, null);

Can I programmatically create and manipulate a Command?

Yes! You can use ICommandService to create a new command and then associate a handler thru IHandlerService:

ICommandService commandService = (ICommandService) serviceLocator.getService(ICommandService.class);
Command command = commandService.getCommand("my.new.undefined.command");
command.define("New Command", "This is created Programatically!",
    commandService.getCategory("org.eclipse.ui.category.window"));
IHandlerService handlerService = (IHandlerService) serviceLocator.getService(IHandlerService.class);
handlerService.activateHandler(command.getId(), new AbstractHandler() {
    public Object execute(ExecutionEvent event) throws ExecutionException {
        System.out.println("Command executed !");
        return null;
    }
});

Adding an input prompt to SWT Text

2009-01-09T17:41:00.001+05:30

Adding an Input Prompt to a text control is most common in web applications. Today I happened to see a JavaScript that handles this elegantly. The script itself is just 18 lines and using it requires just 1 line of code. What would be the effort required to create something in SWT? hmmm not very different:

public static void addPrompt(final Text text, final String defaultText) {
    text.addFocusListener(new FocusListener() {

        public void focusGained(FocusEvent e) {
            if(text.getText().equals(defaultText)) {
                text.setText("");
                text.setForeground(null);
            }
        }

        public void focusLost(FocusEvent e) {
            if(text.getText().equals("")) {
                text.setText(defaultText);
                text.setForeground(text.getDisplay().getSystemColor(SWT.COLOR_GRAY));
            }
        }
    });
}

To use:

InputPrompter.addPrompt(text, "Click Me!");

The result

The same trick can be applied to Combo boxes as well.

Commands Part 3: Parameters for Commands

2009-01-07T23:55:00.004+05:30

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:

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

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

Commands Part 2: Selection and Enablement of IHandlers

2009-01-05T23:55:00.004+05:30

In the last tip, we saw that a Handler can be declared separately from a Command. This enables for multiple handler declarations for the same command. We can also customize when a handler is active and visible, thru plugin.xml itself. A handler that doesn't have any of these conditions is called as "default handler". When no other handler is associated with a command in a particular context, then the default handler will be the handler that gets executed. Remember, at any given point of time, there is at most only one handler is associated with a command. Lets have a look into how a particular handler is selected for a given context.
A handler can be specified with activeWhen condition using the expression language. Say for our command, we have two different handlers. One should be active when the current selection is an IFile and the other should be active when the current selection is IFolder. The expression for these would look like:

<handler
      class="com.eclipse_tips.commads.SomeCommandHandler1"
      commandId="com.eclipse-tips.commands.someCommand">
   <activeWhen>
      <with
            variable="selection">
         <iterate
               operator="or">
            <instanceof
                  value="org.eclipse.core.resources.IFile">
            </instanceof>
         </iterate>
      </with>
   </activeWhen>
</handler>
<handler
      class="com.eclipse_tips.commads.SomeCommandHandler2"
      commandId="com.eclipse-tips.commands.someCommand">
   <activeWhen>
      <with
            variable="selection">
         <iterate
               operator="or">
            <instanceof
                  value="org.eclipse.core.resources.IFolder">
            </instanceof>
         </iterate>
      </with>
   </activeWhen>
</handler>

I'll save the explanation for the expression language for a separate tip, but for now a short one line desc: the first handler will be enabled when the selection current contains at least one IFile and the second handler will be enabled when the selection contains at least one IFolder. This raises to two questions.
1) What if the selection is just an IProject?

In this case, as none of the handlers are eligible, the command is disabled. This is where the default handler, if you have provided one, would be associated with the command (and the command will be enabled).

2) What if the selection contains both IFile and IFolder?

Now both the handlers are equally qualified to handle the command. But since the framework cannot pick one randomly the command is simply disabled. Even if you have provided a default handler, it won't be associated with the command, because the other two handlers are more specific than the default one.

How is the "specificness" of a handler is defined? It depends on the conditions that you give in the activeWhen expression. The order is defined in the ISources class. You can go thru the complete set there, to get a glimpse of the most commonly used ones, the order from least specific to most specific is like this:

Active Context (activeContexts)
Active Actions Sets (activeActionSets)
Active Shell (activeShell)
Active Workbench Window (activeWorkbenchWindow)
Active Editor Id (activeEditorId)
Active Part Id (activePartId)
Current Selection (selection)

If a handler has activeWhen defined with active context and the other one with current selection, the second one will be selected as the selection is more specific than the active context. The activeWhen for all the handlers are evaluated and the one that returns true for the most specific condition is selected. When two handlers return true for the available most specific condition (like the selection having both IFile & IFolder in our case), no handler will be associated with the command.
All these things are done without even loading your handler in the memory. Even without loading your plugin!
In the previous tip, we saw how a handler is selected with the activeWhen expression, when more than one handler is declared. Now assuming a handler is selected, whether to enable the command or not, is determined by the enabledWhen expression.
In our previous example, we saw the handler that is active when the selection at least contained one IFile. Now lets we want to enable it only when the total count of the selection is 2. We can specify it as:

<handler
      class="com.eclipse_tips.commads.SomeCommandHandler1"
      commandId="com.eclipse-tips.commands.someCommand">
   <activeWhen>
      <with
            variable="selection">
         <iterate
               operator="or">
            <instanceof
                  value="org.eclipse.core.resources.IFile">
            </instanceof>
         </iterate>
      </with>
   </activeWhen>
   <enabledWhen>
      <with
            variable="selection">
         <count
               value="2">
         </count>
      </with>
   </enabledWhen>
</handler>

So the handler will be active and associated with the command, if the selection contains at least one IFile. Still the command will be enabled only if selection has exactly 2 elements. activeWhen and enabledWhen are similar - with respective to the expression language and lazy loading of the plugin until the command is executed. But there is small difference - your handler might be loaded iff the enabledWhen expression returns true and your plugin is already loaded. The enablement algo works this way:

No enabledWhen specified, plugin is not loaded - command is enabled
No enabledWhen specified, but plugin is loaded - consult handler.isEnabled() and set command accordingly
enabledWhen specified, returns false, command is disabled (no matter plugin is loaded or not)
enabledWhen specified, returns true, plugin is not loaded - command is enabled
enabledWhen specified, returns true, plugin is loaded - consult handler.isEnabled() and set command accordingly

So far we saw commands, handlers and their enablements. But what about generalizing a command? That can be done by adding parameters for a command. And that would be the next tip in this series.

Update (31-Mar-2009): Thanks to Hiroki Kondo, a Japanese version of this blog entry is available here.

See also:
Part 1: Actions Vs Commands
Part 3: Parameters for Commands
Part 4: Misc items ...
Part 5: ISourceProvider & dynamically updating Commands
Part 6: 'toggle' & 'radio' style menu contribution

Commands Part 1: Actions Vs Commands

2009-01-02T23:55:00.005+05:30

As you would have seen, there are two different ways to contributing to the Workbench: Actions and Commands. Although Commands are newer and advanced, I've always preferred using Actions, simply because of my comfort level in using them. Now that I've started fixing some bugs in the Command framework, I'm forced to look into the details. The more deeper I look into the Commands, the more I'm loving it. So I decided to write a series of on the Commands and this is the first one in the series. Many of the information presented here is obtained by looking some old bugs, wiki and digging into CVS history. If I'm missing anything or wrong about something let me know.

Lets start with Actions. We are able to contribute to the menus, toolbars, pull down menu, etc. We are able to specify the UI details like label or tooltip in the plugin.xml itself, which helps in lazy loading. So whats wrong with them?

The UI and handling are always tied. There is no way you can separate each other
While Actions can be contributed to different parts of the workbench (popup menu/tool bar), all of them were different extension points and so you end up duplicating the XML in multiple places. The worst of it is that not all the extension points expect the same configuration.
Specifying Actions in multiple places is a maintenance nightmare. If you have to change the icon of an action, you need to change in all the places.
Another issue with duplicating Actions in plugin.xml is that multiple instance of the same Actions will be created in the memory

Lets see how the Commands Framework eliminates all this. Commands are defined by the org.eclipse.ui.commands extension point. A typical command would look like:

<command
         id="com.eclipse-tips.commands.someCommand"
         name="Some Command">
</command>

Yeah thats it. That defines a Command! If you want to place this in a tool bar, you have to use the extension point org.eclipse.ui.menus:

<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>
   </toolbar>
</menuContribution>

Now that takes of the placement in the UI. But what about the code that gets executed? That goes into a another extension point, org.eclipse.ui.handlers:

<handler
         class="com.eclipse_tips.commads.SomeCommandHandler"
         commandId="com.eclipse-tips.commands.someCommand">
</handler>

One last piece is to add an icon to the Command
No price for guessing that you need to use another extension point, org.eclipse.ui.commandImages:

<image
         commandId="com.eclipse-tips.commands.someCommand"
         icon="icons/sample.gif">
</image>

All set. Lets see the Command in action:

As you see, in the actions we would just use only one extension point, instead of the four which we have used now. Does it sounds like a round about way or doing things? Probably once we get to know about multiple handlers for a Command and context based association & enablement of the handlers etc, we will see the beauty of the framework. That would be the next in this series.

Update (31-Mar-2009): Thanks to Hiroki Kondo, a Japanese version of this blog entry is available here.

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