Section 6.2.  Adding to the Status Line - Eclipse Rich Client Platform: Designing, Coding, and Packaging Java Applications

6.2. Adding to the Status Line

The status line at the bottom of the Hyberbola window is a great place to show information that is either global to the application or pertinent to the user's current task. Most instant messaging applications place an indicator in the status line to show the user's online status and presence. Since it's somewhat of a standard, Hyperbola should have it too.

Figure 6-6 shows Hyperbola with an image that indicates whether or not the user is connected to a chat server and some text that indicates the current presence (e.g., available to chat, do not disturb). Eventually, we want the icon and text to update automatically as the user's status changes, but for now, let's keep it simple.

Remember earlier when you enabled the toolbar and menu in ApplicationWorkbenchWindowAdvisor.preWindowOpen()? Go back there to enable the status line. From within the preWindowOpen() method, type "configurer.set" and then press Ctrl+Space to see all the setters. Then, find the setShowStatusLine() method. This is a great use of Eclipse Java IDE's content-assistthere are fewer mistakes, less to remember, and it's better than cut-and-paste.

org.eclipsercp.hyperbola/ApplicationWorkbenchWindowAdvisor
public void preWindowOpen() {
  IWorkbenchWindowConfigurer configurer = getWindowConfigurer();
  configurer.setInitialSize(new Point(250, 350));
  configurer.setShowCoolBar(true);
  configurer.setShowMenuBar(true);
  configurer.setShowStatusLine(true);
  configurer.setTitle("Hyperbola");
}

Double-check that this worked by running Hyperbola. The status line should be empty, but nonetheless visible. Now you can add the icon and text using the following snippet for ApplicationWorkbenchWindowAdvisor. The statusImage is a field on the window advisor.

org.eclipsercp.hyperbola/ApplicationWorkbenchWindowAdvisor
public void postWindowOpen() {
  statusImage =
      AbstractUIPlugin.imageDescriptorFromPlugin(
      "org.eclipsercp.hyperbola",
      IImageKeys.ONLINE).createImage();
  IStatusLineManager statusline = getWindowConfigurer().
      getActionBarConfigurer().getStatusLineManager();
  statusline.setMessage(statusImage, "Online");
}
public void dispose() {
  statusImage.dispose();
}

Like the menu bar and toolbar, the status line is controlled by the ActionBarAdvisor. You may have noticed the fillStatusLine (IStatusLineManager) method in ActionBarAdvisor. IStatusLineManagers are regular contribution managers similar to IMenuManagers and IToolbarManagers. They include a handful of methods specific to status lines such as getProgressMonitor(), setMessage(Image, String), and setErrorMessage (Image, String).

There is one caveat on these additional methods: They can only be called after the status line's controls have been created. Since ActionBarAdvisor. fillStatusLine() is called before the status line has been created, you can't call these methods in the ActionBarAdvisor. Instead, a good place to set the message, for example, is in the WorkbenchWindowAdvisor.postWindowOpen() method, as shown in the previous snippet.

6.2.1. Status LineA Shared Resource

As you have seen, it's very easy to add images and messages to the status line. Unfortunately, the status line is a shared resource and can be written to by any plug-in. If your application is small, like Hyperbola, you can simply centralize the use of the status line and avoid conflicts. This is not always feasible.

The status line is also special because it is configured with a pre-defined layoutthe bar contains several reserved areas for standard controls, as shown in Figure 6-7.

Fast views The fast views area shows views that are removed from the window but can be accessed quickly from an icon docked in the fast view bar. For more information on fast views, consult the online help.

Icon/message You just used the icons and messages area to show the user's connection and presence in Hyperbola. Consider this the status line contribution that any part is allowed to make when it has focus.

Progress The first progress area is used for showing modal progress. It is normally invisible until an IWorkbenchWindow.run() operation is invoked. When the operation is running, a progress indicator and Cancel button are made visible.

Contributions The contributions area is reserved for the Workbench advisor and active part contributions.

Jobs progress The jobs progress area is hidden by default, but can be enabled by calling IWorkbenchWindowConfigurator.setShowProgress Indicator(boolean). See Sections 14.5.1, "Updating Hyperbola," and 17.8, "Reporting Progress," for more details.

Since the layout is somewhat fixed, it is not possible to left-align additional contributions to the status linethe reserved areas for the other items get in the way. However, when the job progress area is not shown, user contributions are right-aligned. You can make additions to the status line using IStatusLineManager.add(IContributionItem).

In any event, there are many uses of the status line and directly setting the icon and message area is very effective. For more advanced status line uses, see Section 17.7, "Adding Contributions to the Status Line."