Friday, February 1, 2008

I just added Context Sensitive Help to a Dialog window in the Spaces project and since I at first could not find the information how to do this, I thought it may be of value to share some pointers to get others started. The first step if you are writing a Dialog and want to have the same nice integrated help system as provided in the Eclipse IDE Wizards - is to derive your Dialog from the TrayDialog class instead of from the (plain) Dialog. The TrayDialog should perhaps have been called something related to help, because 'support for help' is what it is adding. After having derived the dialog from TrayDialog, the dialog gets the (?) in the lower left corner, and you click that, or press F1 to get context sensitive help. Super simple. Now you need to do a couple of things to make it work:
  • registering help contexts for the controls (either the entire dialog, or the dialog and all the individual controls in it). To do this you need to get the WorkbenchHelpSystem, and call setHelp(aControl, aContext) for each control.
  • make your plugin extend "" and specify that this is a context extension for some plugin and point to a contexts.xml file which defines what will be popped up as context help. This definition can be very simple, but may contain links into the rest of the help system.
  • Write the help topics that the context sensitive help links to. You do this by having html files in your plugin.
  • To make context sensitive help inside your dialog (in a tray to the right) instead of as an "infopop" you must also make sure that you set up the dialog area correctly (see below).
  • Once you see the context senitive help, you may be surprised that you also see a search result of help topics below the context sensitive things you added. The help system searches for help topics that match the title of your dialog shell. In my case, I used the project name "Spaces", and there where quite a few help articles with the term "spaces" in them. So select your dialog title carefully.
protected Control createDialogArea(Composite parent)
 Composite dialogArea = (Composite)super.createDialogArea(parent);
 Composite container = new Composite(dialogArea, SWT.NONE);
     new GridData(GridData.FILL, GridData.FILL, true, true));
 // then add your content to the Composite container...
The best information I found on how to get started with the Eclipse help system, and context sensitive help was in the book "Eclipse - building commercial quality plug-ins" - it is available on Safari. Chapter 15.3 (second edition) covers the help system. Here is a direct link to the chapter where extension points for context sensitive help and formats of files are described. If you are interested in the full source, take a look at the "AddSpaceDialog" in "org.eclipse.spaces.ui" project (in Eclipse SVN under technology/spaces). Bare in mind that right now this is work in progress...

No comments: