Eclipse Tips

Eclipse Tips on Twitter !

2009-11-03T15:20:00.000+05:30

Get (a different set of) Eclipse Tips in twitter: @Eclipse_Tips. If you are still in the RSS reader era, get the feed here.

Associating a Command with a Job

2009-10-28T00:29:00.001+05:30

Earlier we saw how to associate an Action with a Job. Now you can associate a Command. Its very similar - use the constant to set a property on the job:

ICommandService service = (ICommandService) serviceLocator.getService(ICommandService.class);
Command command = service.getCommand(commandId);
ParameterizedCommand parameterizedCommand = new ParameterizedCommand(command, null);
job.setProperty(IProgressConstants.COMMAND_PROPERTY, parameterizedCommand);

You have to specify either the ACTION_PROPERTY or COMMAND_PROPERTY, but not both. If you specify both, neither of them will get executed.

Note: You need a 3.6 M3 or a latest I-Build for this to work.

Eclipse Demo Camp, Bangalore

2009-09-23T11:24:00.000+05:30

Its back :-)

We are planning to organize a Demo Camp sometime in November. Date, time and venue to be decided. Since IBM's Eclipse team has grown since last Demo Camp, this time, you get a very good opportunity to learn right from the source, on whats coming up. From p2 to b3 and e4 (Am I the only one who thinks that things can be named better?) we can give a good number of demos/presentations. But we don't want to make it as the Big Blue show, so we need few contributions from the community as well. We are glad that Madhu and Anil have already signed up with some topics. I would encourage you to add a demo on what you are working on. Even if not sign up as an attendee, its a nice chance to meet other Eclipse plug-in developers and see what they are building with Eclipse.

http://wiki.eclipse.org/Eclipse_DemoCamps_November_2009/Bangalore

Catching up with Milestones and I-Builds

2009-09-22T12:51:00.007+05:30

Helios M2 is released. Now the biggest problem for the early adopters would be how to catch up with these milestones. Every time, you have to download the milestone build, and then update it with all your required plugins (svn, mylyn, etc). If you are on the I builds, then you have to do this on every week. If you feel that its a painful process, here is a tip.

The p2 repos for Eclipse are not only for the stable releases, but also for the Milestones, I Builds and Nightly builds.

Milestones: http://download.eclipse.org/eclipse/updates/3.6milestones
I-Builds: http://download.eclipse.org/eclipse/updates/3.6-I-builds
Nightly Builds: http://download.eclipse.org/eclipse/updates/3.6-N-builds

The build schedule is available here.

Go to your Preferences and add the required repo in your Available Software Site preferences (and disable all others, it will be slow to update).

Also enable the automatic updates. You are done. Whenever there is a new Milestone (or an I-Build), then your Eclipse gets updated automatically to it and you don't have to worry about installing other required plug-ins.

Enjoy with the latest and greatest without any pains :-)

Back to the basics: Display, Shell, Window ...

2009-09-15T22:39:00.002+05:30

Every Eclipse plugin developer has to deal with Shell and Window, but sometimes doesn't understand the difference between these two. In this tip, I'm trying to explain the basic things: Display, Shell, Window, Dialog, Workbench, WorkbenchPart, WorkbenchSite and WorkbenchPage. Yeah, I know, its probably the boring post you can read in this blog, if you are little bit experienced in these areas.

Display:

This class is the link between SWT and the underlying OS. It manages the interaction between widgets and the OS. The primary task for this class is to maintain the event loop (readAndDispatch()). Unless you are writing a plain SWT app, you won't be using that. The most common methods you would be using in this class are asyncExec(), syncExec() and timerExec(), which allows you to run a piece of code in the UI thread. (aka user interface thread or display thread)

Shell:

Shell is the "window" that you see in your desktop. The one that has a title, maximize, minimize, restore and close buttons. A shell can be either a top-level shell (no parent shell) or can be a secondary shell (will have a parent shell). The style that is passed in the constructor defines which of the above mentioned buttons are displayed and also whether the Shell is modal or not. If you are on a pure SWT app, then you should be create a Shell; create controls in it; open it; run the event loop; and dispose it. Speaking in code:

Shell shell = new Shell(display);
// set layout and create widgets 
 shell.open ();
 while (!shell.isDisposed ()) {
  if (!display.readAndDispatch ()) display.sleep ();
 }
 display.dispose ();

Window:

If you are developing plugins/JFace applications, its better to use Window rather than Shells directly, because it manages the above things for you. It is not, but think it of as a wrapper for Shell. When you use a Window, a Shell is not created until the open() method is called. Since the Shell is not created till the Window is open and windows can be reopened (yes, you can reopen it), configuration of the Shell should be done in the configureShell() method. Remember, this is an abstract class and so you cannot directly use it. You must either use Dialog or ApplicationWindow or your own concrete class.

Dialog:

When you need a specialized communication with the user, you should be using Dialogs. In all other cases, you will be using ApplicationWindow. Dialog are more of helper windows that are attached to another main window. PreferenceDialog, PropertyDialog, ErrorDialog, InputDialog & WizardDialog are some frequently used dialogs.

ApplicationWindow:

Window + menu support + toolbar support + coolbar support + status line support = ApplicationWindow :-)

IWorkbenchWindow:

WorkbenchWindow is Eclipse specific ApplicationWindow, which adds few services and a set of IWorkbenchPages to the ApplicationWindow. Although the javadoc says "Each workbench window has a collection of 0 or more pages", in reality it has only one page. I believe this is due to backward compatibility with Eclipse 1.0.

IWorkbenchPage:

The area that lies between the toolbar and the status line of the WorkbenchWindow is known as WorkbenchPage. Simply put, this is the body of the WorkbenchWindow, where all the editors and views are showed. IWorkbenchPage contains IWorkbenchParts, which are the the visual representation of the Views and Editors. Both IViewPart and IEditorPart derive from IWorkbenchPart

IWorkbenchSite:

IWorkbenchPart resides inside the IWorkbenchPage. So it has no direct access to the workbench itself. So when it needs to interact with the workbench, then it needs the IWorkbenchSite. For example to get the shell inside a view, you call getSite().getShell().

Excluding a view from Properties View

2009-09-10T12:19:00.001+05:30

In a previous tip, we saw how to make a Properties View to respond only to a particular View or Editor. In this tip, we are going to see how to exclude a particular View or Editor from the Properties View. This will be very helpful in RCP apps, where they don't want the generic view like Outline view or an editor that contributes to the Properties View. Last time we extended the Properties View to create our own view and added some code. But this time its simple. You just have to use the org.eclipse.ui.propertiesView extension point.

<extension
         point="org.eclipse.ui.propertiesView">
      <excludeSources
            id="org.eclipse.ui.views.ContentOutline">
      </excludeSources>
      <excludeSources
            id="com.eclipse_tips.editors.MyOwnEditor">
      </excludeSources>
</extension>

Yes, its that simple :-) Don't try with Galileo, you would need Helios (3.6) M2 to get this working.

Remember the State

2009-08-06T23:31:00.001+05:30

As a rule of thumb, your application should try to remember the state across sessions. So when a user hits the close button and then opens it after few mins/days, it should present exactly in the same way where he left. In this tip, I'm going to explain few things of how this could be achieved.

The first and foremost thing is the number of windows opened and current perspective and its state in each window. If you are writing a plugin for the IDE, you need not worry about this. Eclipse does that for you. If you are an RCP app, you have to do it yourself. You have to do it in the WorkbenchAdvisor.initialize() method:

public class ApplicationWorkbenchAdvisor extends WorkbenchAdvisor {
 
 @Override
 public void initialize(IWorkbenchConfigurer configurer) {

  super.initialize(configurer);
  configurer.setSaveAndRestore(true);
 }

 // other methods ...
}

Now this will take care of lot of things - the number of windows that are opened; location & size of those windows; perspective of each window; view & editors in each perspective; their locations,... All by setting that one boolean variable!

Now that our views and editors are restored by Eclipse, we need to ensure the state of them. Most of the views will be tree/table based. In these cases, the current selection is an important one to restore.

To store these items and anyother stuff you want to, Eclipse provides IMemento. An instance of this IMemento is passed to the view when its initialized and when workbench is closed. The information can be stored hierarchically with string keys and it will be persisted as an XML. If you are wondering why can't it be as simple as passing a Serializable Java object and the workbench persisting it, the answer is simple. The same class may not be there when Eclipse starts next time or even if the same class is available, it might have changed. IMemento avoids this problem by persisting the stae as an XML string.

So how do we use it? In the view, you have to override the init() and saveState() methods:

@Override
public void init(IViewSite site, IMemento memento) throws PartInitException {
 this.memento = memento;
 super.init(site, memento);
}

public void createPartControl(Composite parent) {
        // create the viewer
 restoreSelection();
}

private void restoreSelection() {
 if (memento != null) {
  IMemento storedSelection = memento.getChild("StoredSelection");
  if (storedSelection != null) {
   // create a structured selection from it
   viewer.setSelection(selection);
  }
 }
}

@Override
public void saveState(IMemento memento) {
 IStructuredSelection selection = (IStructuredSelection) viewer.getSelection();
 if (!selection.isEmpty()) {
  IMemento storedSelection = memento.createChild("StoredSelection");
  // store the selection under storedSelection
 }
}

Not just the selection, we can store any other information (which of the tree nodes are expanded, sorter & filter settings etc) which will be useful to restore the state.

Great. Now moving on from the views, the next item would be dialogs. Similar to the workbench windows, you can store the size, location and other elements of a dialog as well. The functionality for size and location is available by default, but you need to enable it by overriding the Dialog.getDialogBoundsSettings() method. The Dialog class stores & retrieves the size and location from IDialogSettings returned from that method. The original implementation returns null, so nothing is saved. We need to create an instanceof IDialogSettings and return it. Your plugin's Activator simplifies that. When required, it creates a dialog_settings.xml under your plugin's data area and store the dialog settings of all the dialogs. You have to create a separate section for each dialog.

private static final String MY_DIALOG_SETTINGS = "MY_DIALOG_SETTINGS";

@Override
protected IDialogSettings getDialogBoundsSettings() {
 IDialogSettings settings = Activator.getDefault().getDialogSettings();
 IDialogSettings section = settings.getSection(MY_DIALOG_SETTINGS);
 if (section == null) {
  section = settings.addNewSection(MY_DIALOG_SETTINGS);
 }
 return section;
}

In case you want to store only the location or size, you can specify it by overriding the getDialogBoundsStrategy() method.

Much like the IMemento, the IDialogSettings basically organizes the key-value strings in an hierarchical way. So along with the size & location, you can store any other information in this IDialogSettings. Its a good practice to store the values of the widgets (which radion button is selecte, checked state of a check box, etc) in the dialog, so its faster for an user who frequently repeats an operation.

Talking about the widgets, the trickier one is Combo. When the list of options are predefined and the user can't enter a new value, then its easy. But in places where the user can enter the values, (like File/Directory selection, search boxes), remembering them is not straight forward.

We shouldn't be storing every single value the user enters, but only the recently used ones. Probably with a limit of 5 or 10 items only. This can be done with the help of LinkedHashSet. It guarantees the order of the element, so whenever the user enters a new values, put the current value first in the set then add the rest of the elements (even if the first element is repeated, it won't change the position). Then take the first N elements and store it.

private static final String COMBO_STATE="COMBO_STATE";

private static final int HISTORY_SIZE = 5;

private String []comboState;

private void restoreComboState(IDialogSettings settings) {
 comboState = settings.getArray(COMBO_STATE);
 if(comboState ==null)
  comboState = new String[0];
 for (String value : comboState) {
  myCombo.add(value);
 }
}

private void saveComboState(IDialogSettings settings) {

 // use LinkedHashSet to have the recently entered ones
 LinkedHashSet<String> newState = new LinkedHashSet<String>();
 newState.add(myCombo.getText());
 newState.addAll(Arrays.asList(comboState));

 // now convert it to the array of required size
 int size = Math.min(HISTORY_SIZE, newState.size());
 String[] newStateArray = new String[size];
 newState.toArray(newStateArray);

 // store
 settings.put(COMBO_STATE, newStateArray);
}

One last piece. Look at this dialog:

Sometimes only for the first time you want to ask the question to the user. Thereafter if the user prefers, you can use the same answer. To simplify this, you can use the MessageDialogWithToggle. You need to pass the preference store and the key for the preference value. When the user selects the check box, the value will be stored. From the next time onwards, you can check the value from the preference and use it.

MessageDialogWithToggle.openYesNoQuestion(shell, "Remember me", "Is this tip useful?", 
  "Don't bug me with this question again", true, 
  Activator.getDefault().getPreferenceStore(), "BUG_USER_KEY");

There you go:

:-)

Eclipse Summit India - Day 2

2009-07-18T22:37:00.001+05:30

The second day, I was a little late and missed the Oracle's Plenary session. I was in time for IBM's session. Being an IBM-er nothing new for me there to see RAD or websphere. It was good.

The first session I took was by Ilya Shinkarenko. More than half of the hall had repeated audience. It was nice, just as yesterday. This time, I was able to attend till the end. After a heavy lunch, I felt very sleepy in the afternoon session. The presenter was partly responsible for that ;-) Then I moved to Anshu Jain's session called 'Eclipse as framework of frameworks', which was simply awesome. To quote Ankur, "a lot of meat added with a perfect aroma, the presentation was a feast". Of the ones I've attended, that was the best. Next was networking in the corridor. After many questions on Eclipse startup to command invocation, that marked the end of the day for me.

Some afterthoughts:

(*) The good thing about this conference is the focus. This is not an all-in-conference, which targets all the CEOs, CTOs, Managers, decision makers, IT guys and your office boys. This has complete focus on Eclipse plug-in developers and almost all of these sessions are well aligned towards this.

(*) Parallel tracks are good, but they could have been specific tracks like OSGi, EMF etc. Also there were instances like both the OSGi sessions were held in parallel, so if someone is interested in OSGi, they have to choose between these two. Probably the next time, it gets better.

(*) The venue was also much better, center of the city and well accessible. No need to talk about the food, it was great :-)

I believe that the photos, videos and the slides will be uploaded online soon. I'll post a link once its done.

Eclipse Summit India - Day 1

2009-07-17T14:44:00.002+05:30

Before I start, a question: How do you know you are in troubled economic times?

Today is the first day of Eclipse Summit India. Luckily, even after screwing up by taking a wrong road and going in a different direction, I did make it well before the keynote by Microsoft. Yes, Microsoft. They are one of the Platinum sponsors. Just like me, everyone was wondering what are they doing there, the answer told was "interoperability". I'm not going to summarize any of the topics presented, so I'll leave you to guess what how he positioned M$ in that.One thing that was interesting is they have PHP as a first class citizen in their IIS. That was surprising for me. Additionally they have some thing called a 'One Installer' which will download all that you want for a web site and install it on your server - not just PHP module for IIS or the latest .Net runtime, but Wordpress and Drupal as well! Wow!

After that it was Ilya Shinkarenko's workshop. It was good. Started a little slow and the pace moved up during the session. I've to cut it in the middle and rush to the other room. Adobe guys were just finishing their presentation. Both of them had a black Mac book and even before I said another 'wow', I noticed it was a windows machine with an Apple sticker. Good idea, I should say. The presentation was mine, and I hope it went well. I did get some good feedback during the lunch. Its definitely troubled ecomony now, but the buffet was good :-)

Post lunch, yeah, I'm in the EMF workshop and blogging this (yeah, we got free wi-fi). Got to run for Ankur's Presentation. Rest of the sessions in the evening/tomorrow.

Before I sign out, the answer: In the free goodies for attendees, you get a pencil instead of a pen ;-)

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);