15.4. Accessing Help Programmatically

So far, you have seen how to integrate help into the Eclipse Help window and access it using standard Eclipse mechanisms such as the Help > Help Contents menu and the F1 key. There may be times when you want to provide help in ways other than the standard mechanisms.

As seen earlier, the IWorkbenchHelpSystem interface defines a large number of useful APIs. This section concentrates on a couple of the display methods.

To programmatically open the Help window, call the displayHelp() method without an argument. To programmatically open context-sensitive help for a specific context ID, call the displayHelp() method with the context ID string as the single argument. For example, to open the context-sensitive help associated with the Favorites view, use the following code.

PlatformUI.getWorkbench().getHelpSystem().displayHelp(
   "com.qualityeclipse.favorites.favorites_view");

15.4.1. Opening a specific help page

The most interesting API, however, is the displayHelpReource() method, which takes a single string argument representing the path to the help page to be displayed. For example, to open the main help page for the Favorites plug-in, use the following code:

PlatformUI.getWorkbench().getHelpSystem().displayHelpResource(
   "/com.qualityeclipse.favorites.help/html/toc.html");

The path argument is composed of the ID of the plug-in containing the help file and the path to the resource relative to the plug-in root directory. Based on this last example, you can easily add a custom help button to the toolbar of the Favorites view (see Figure 15-19) by creating the following method in the FavoritesView class and calling it from the createPartControl() method.

private void addHelpButtonToToolBar() {
   final IWorkbenchHelpSystem helpSystem =
      getSite().getWorkbenchWindow().getWorkbench().getHelpSystem();
   Action helpAction = new Action() {
      public void run() {
         helpSystem.displayHelpResource(
            "/com.qualityeclipse.favorites.help" +
            "/html/toc.html");
      }
   };
   helpAction.setToolTipText("Open the Favorites view help");
   helpAction.setImageDescriptor(
       ImageDescriptor.createFromFile(
          FavoritesView.class, "help.gif"));
   getViewSite()
      .getActionBars()
      .getToolBarManager()
      .add(helpAction);
}

15.4.2. Opening a Web page

In addition to opening a specific help page in the Eclipse Help window, you might want to open a Web browser on a specific Web page. Eclipse includes a class, org.eclipse.swt.program.Program, which is used to launch external programs, including the system Web browser. In particular, you are interested in the launch() method, which takes a string encoding the path to the program to be launched or the URL of the Web page to be accessed.

You can now add a button to the Favorites view's toolbar (see Figure 15-20) that will open a specific Web page (use the Web page for this book as an example). Do this by adding the following method to the FavoritesView class and calling it from the createPartControl() method.

private void addWebButtonToToolBar() {
   Action webAction = new Action() {
      public void run() {
         Program.launch("http://www.qualityeclipse.com");
      }
   };

   webAction.setToolTipText("Open a web page");
   webAction.setImageDescriptor(
      ImageDescriptor.createFromFile(
         FavoritesView.class, "web.gif"));

   getViewSite()
       .getActionBars()
      .getToolBarManager()
       .add(webAction);
}

This technique works very well for Windows but will not work on other platforms such as Linux. For an alternative approach that will work on any platform, see Section 20.4, Opening a Browser or Creating an Email, on page 718.

Program.launch(
   "mailto:info@qualityeclipse.com" +
   "?Subject=Information Request")