Section 20.4. Opening a Browser or Creating an Email

In your product, you may want to provide an easy way for users to reach your Web site or quickly compose an email to your company. Start by creating a button that opens a browser on your product's Web page or creates an email message in the user's default email client when clicked. The simple approach is to use the launch() method in the org.eclipse.swt.program.Program class (see Section 15.4.2, Opening a Web page, on page 562), but unfortunately, that approach does not work with platforms other than Windows. First, Eclipse provides the IWorkbenchBrowserSupport interface for opening an embedded browser and an external browser. Second, construct an action for launching the default email client.

20.4.1. IWorkbenchBrowserSupport

To use IWorkbenchBrowserSupport in the FavoritesView, modify the addWebButtonToToolBar() method to construct the URL and then open a browser inside the Eclipse workbench window showing the QualityEclipse Web site. To launch an external browser rather than an embedded browser, change the first argument of the createBrowser() call to IWorkbenchBrowserSupport.AS_EDITOR.

private void addWebButtonToToolBar() {
   Action webAction = new Action() {
      public void run() {
         IWorkbenchBrowserSupport browserSupport = getSite()
               .getWorkbenchWindow().getWorkbench()
               .getBrowserSupport();

         URL webUrl;
         try {
            webUrl = new URL("http://www.qualityeclipse.com");
         }
         catch (MalformedURLException e) {
            FavoritesLog.logError(e);
            return;
         }

         IWebBrowser browser;
         try {
            browser = browserSupport.createBrowser(
                  IWorkbenchBrowserSupport.AS_EDITOR, null,
                  "Quality Eclipse", "The Quality Eclipse website");
            browser.openURL(webUrl);
         }
         catch (PartInitException e) {
            FavoritesLog.logError(e);
            return;
         }
      }
   };

   webAction.setToolTipText("Open a web page"); //$NON-NLS-1$
   webAction.setImageDescriptor(ImageDescriptor.createFromFile(
         FavoritesView.class, "web.gif")); //$NON-NLS-1$
   getViewSite().getActionBars().getToolBarManager().add(webAction);
}

If you are building an RCP application and not building on top of the Eclipse Workbench, you will need to extract some functionality from the org.eclipse.ui.browser plug-in and build on top of the basic browser support provided in the SWT and JFace plug-ins . If you head down this path, be sure to review DefaultBrowserSupport, WebBrowserEditor, and BrowserViewer in the org.eclipse.ui.browser plug-in and Browser in the org.eclipse.swt plug-in.

Tip

See www.qualityeclipse.com/util/browser for more on using functionality similar to IWorkbenchBrowserSupport in an RCP application.

20.4.2. LaunchURL

The org.eclipse.help.ui.browser.LaunchURL class provides another mechanism for opening a browser . This action delegate, part of the org.eclipse.help.ui plug-in, can be used to add a workbench menu (see Section 6.2.3, Defining a menu item and toolbar button, on page 212) that opens a browser on a predefined Web page (reading the code, this action appears to have cross-platform support, but we've only tried this on Windows). For example, in the Favorites product, you could add a new action to the top-level Favorites menu by adding the following declaration to the "Favorites ActionSet" in the plug-in manifest.

<action
   id="com.qualityeclipse.favorites.browseWeb"
   menubarPath="com.qualityeclipse.favorites.workbenchMenu/content"
   label="Browse QualityEclipse"
   icon="icons/web.gif"
   style="push"
   tooltip="Use the LaunchURL class to open a browser"
   class="org.eclipse.help.ui.browser.LaunchURL"
   url="http://www.qualityeclipse.com"/>

The url attribute in the declaration above specifies the Web page displayed by the LaunchURL action delegate . Unfortunately, the plug-in manifest editor does not support the url attribute, so you must switch to the plugin.xml page to hand-code the attribute.

20.4.3. OpenEmailAction

The launch() method in the org.eclipse.swt.program.Program class is useful for opening the default email client in Windows, but not so in Linux. What you need is a separate action that opens email clients differently based on the current platform. To start, create a new OpenEmailAction class with fields and setters for standard email elements.

public class OpenEmailAction extends Action
{
   private String recipient;
   private String subject;
   private String body;

   public void setRecipient(String recipient) {
      this.recipient = recipient;
   }
   public void setSubject(String subject) {
      this.subject = subject;
   }

   public void setBody(String body) {
      this.body = body;
   }
}

Next add a run() method that determines a platform-specific template, fills in the specified email elements, and then launches the email client . Over time, you can enhance this method to check for additional Linux email clients.

public void run() {
   String template;
   if (SWT.getPlatform().equals("win32")) {
      template = "mailto:${recipient}" +
            "?Subject=${subject}&Body=${body}";
   }
   else {
      // Put code here to test for various Linux email clients
      template = "netscape mailto:${recipient}" +
            "?Subject=${subject}&Body=${body}";
   }

   String mailSpec = buildMailSpec(template);

   if (mailSpec.startsWith("mailto:")) {
      Program.launch(mailSpec);
   }
   else {
      try {
         Runtime.getRuntime().exec(mailSpec);
      }
      catch (IOException e) {
         FavoritesLog.logError(
            "Failed to open mail client: " + mailSpec,
            e);
      }
   }
}

Tip

The platform-specific code that appears above is inherently more fragile than the less specific Java code, so see www.qualityeclipse.com/util/email for the latest notes and code.

The preceding run() method calls the buildMailSpec() method to generate an email specification based on the platform-specific template provided. It replaces tokens, such as ${subject}, in the template with their respective values.

private String buildMailSpec(String template) {
   StringBuffer buf = new StringBuffer(1000);
   int start = 0;
   while (true) {
      int end = template.indexOf("${", start);
      if (end == -1) {
         buf.append(template.substring(start));
         break;
      }
      buf.append(template.substring(start, end));
      start = template.indexOf("}", end + 2);
      if (start == -1) {
         buf.append(template.substring(end));
         break;
      }
      String key = template.substring(end + 2, start);
      if (key.equalsIgnoreCase("recipient")) {
         buf.append(recipient);
      }
      else if (key.equalsIgnoreCase("subject")) {
         buf.append(subject);
      }
      else if (key.equalsIgnoreCase("body")) {
         appendBody(buf);
      }
      start++;
   }
   return buf.toString();
}

The buildMailSpec() method calls appendBody() to append email content to the email specification. Carriage return and line feed characters are replaced with "%0A" to create separate lines when appending the email's content.

private void appendBody(StringBuffer buf) {
   if (body == null)
      return;
   int start = 0;
   while (true) {
      int end = body.indexOf('\n', start);
      if (end == -1) {
         buf.append(body.substring(start));
         return;
      }
      if (end > 0 && body.charAt(end - 1) == '\r')
         buf.append(body.substring(start, end - 1));
      else
         buf.append(body.substring(start, end));
      buf.append("%0A");
      start = end + 1;
   }
}

Now you can modify the addEMailButtonToToolBar() method in the FavoritesView to use this new action.

private void addEMailButtonToToolBar() {
   OpenEmailAction emailAction = new OpenEmailAction();
   emailAction.setRecipient("info@qualityeclipse.com");
   emailAction.setSubject("Question");
   emailAction.setBody("My question is ..." +
         "\nSecond line\nThird line.");
   emailAction.setToolTipText("Send an email"); //$NON-NLS-1$
   emailAction.setImageDescriptor(
      ImageDescriptor.createFromFile(
         FavoritesView.class, "mail.gif")); //$NON-NLS-1$

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

This does not send the message, but signals the email client to create the message with the specific information so that the user can review and send it. The code above creates an email message that looks something like this:

To: info@qualityeclipse.com
Subject: Question

My question is ...
Second line
Third line.

Tip

Not all systems or browsers support all mailto options. For a complete listing of what can be encoded in a mailto request, google "mailto syntax" or see www.qualityeclipse.com/util/mailtoSyntax.htm