Section 5.2.  Adding a Contacts View - Eclipse Rich Client Platform: Designing, Coding, and Packaging Java Applications

5.2. Adding a Contacts View

Since Hyperbola is a chat client, one of the most essential UI elements is a contacts list that displays your friends and their presence status (i.e., whether or not they are online).

In Eclipse, users interact with applications through views and editors. Perspectives are a mechanism for arranging views and editors and supporting scalable UIs. Put another way, views and editors contain the content for your application; perspectives allow those elements to be organized for users. We already have a perspective, it's just empty.

A view is added by contributing a view extension to the org.eclipse.ui.views extension point. Open the org.eclipsercp.hyperbola project's plugin.xml and go to the Extensions page. Click Add... and create an extension of type org.eclipse.ui.views. Right-click on the extension and add a view attribute using New > view from the context menu. When you click on the new view attribute, the details pane at the right shows the default values for the view. Update the id and name fields to match those shown in Figure 5-3.

Figure 5-3. Adding ContactsView to Hyperbola's plugin.xml

[View full size image]

You also need a class to implement the view. Click on the class link to create a new class. When the new class wizard appears, most of the fields, including superclass ViewPart, are already filled in. All you have to do is type "ContactsView" for the class name. Click Finish and a skeleton view class is created and opened in an editor.

Before moving on, make a constant for the view id. Set the value to be the same as in the extension and add it to the newly created ContactsView class. This will come in handy later. Save the Java file and go back to the plug-in editor. Notice that the name of the new view class is set in the class attribute of the extension.

org.eclipsercp.hyperbola/ContactsView
public class ContactsView extends ViewPart {
  public static final String ID =
      "org.eclipsercp.hyperbola.views.contacts";

  public ContactsView() {
    super();
    // TODO Auto-generated constructor stub
  }

  public void createPartControl(Composite parent) {
    // TODO Auto-generated method stub
  }

  public void setFocus() {
    // TODO Auto-generated method stub
  }
}

Finally, set the view's icon. View icons are optional but typically specified. You can either create your own GIF image and place it in Hyperbola's icons directory or copy the images supplied with the sample code for this chapter. Either way, fill in the icon field by browsing to the image or entering the location directly.

Save the plug-in and now you have created a skeleton view. The next step is to customize the perspective to include the new view and have it appear in the Hyperbola window.

5.2.1. Adding the Contacts View to a Perspective

All RCP applications must define at least one perspective; otherwise, there would be nothing to lay out the views. Think of a perspective as a set of layout hints for a window. Every IWorkbenchWindow has one page. The page owns its editor and view instances and uses the active perspective to decide its layout. The perspective details where, and whether or not, to show certain things, such as views, the editor area, and actions. Figure 5-4 provides an overview of the main parts of a IWorkbenchWindow.

Figure 5-4. Overview of a WorkbenchWindow's parts

[View full size image]

The initial perspective, and thus the look of Hyperbola when it is first run, is identified by WorkbenchAdvisor.getInitialWindowPerspectiveId(). The Hello RCP template defined the Hyperbola perspective and contributed to the Workbench's perspective extension point, as shown in Figure 5-5. Notice that the extension defines an id and identifies a class for the perspective.

A perspective factory provides the initial layout for a perspective. When a perspective is needed, the factory is created and passed an IPageLayout to which views are added. The factory is then discarded. As the user rearranges the contents of the perspective, the Workbench saves the settings on exit and restores them at startup (if so configured).

The perspective generated by the PDE template uses the default layout. This layout is just an editor area with no additional views. That's why Hyperbola is just an empty shellthe perspective is empty. Now that we have a view defined, go ahead and add the Contacts view to the Hyperbola perspective as shown here:

org.eclipsercp.hyperbola/Perspective
public class Perspective implements IPerspectiveFactory {
  public void createInitialLayout(IPageLayout layout) {
    layout.setEditorAreaVisible(false);
    layout.addView(ContactsView.ID, IPageLayout.LEFT,
        1.0f, layout.getEditorArea());
  }
}

IPageLayout contains several methods for defining the layout of a perspective. Everything added to a perspective is related to something else. Here, the editor area is used as the base for placing the Contacts view. The Contacts view is added to the left of the editor area and is given all available space in the page by specifying 1.0f as the layout ratio. The ratio describes how to divide the available space between the Contacts view and its reference part, in this case, the editor area. The ratio must be between 0.0f (only title bar is shown) and 1.0f (view takes up the entire window area).

When you run Hyperbola now, you should see the Contacts view, as shown in Figure 5-6.

It looks a little strange to have a tab when there is only one view shown, and there is no reason to allow the view to be closed. Views added to a perspective using IPageLayout.addView() inherit various default behaviors that allow them to be moved, un-docked, closed, minimized, and maximized. Using IPageLayout.addStandaloneView(), however, adds a standalone view. Standalone views hide the title area, thus preventing the view from being closed, moved, etc.

Make the Contacts view standalone by changing the code to use addStandaloneView(), as shown here. Notice that the new code is almost identical to the previous except for the boolean parameter that specifies if the title area should be hidden. The new Hyperbola looks like Figure 5-7.

org.eclipsercp.hyperbola/Perspective
public class Perspective implements IPerspectiveFactory {
  public void createInitialLayout(IPageLayout layout) {
    layout.setEditorAreaVisible(false);
    layout.addView(ContactsView.ID, IPageLayout.LEFT,
        1.0f, layout.getEditorArea());
    layout.addStandaloneView(ContactsView.ID, false,
        IPageLayout.LEFT, 1.0f, layout.getEditorArea());
  }
}

When you re-run Hyperbola, you may be surprised. The view still shows a title. The changes you made to the perspective seem to have been ignored. Since we told the Workbench to save settings on shutdown, it saves the perspective layouts in the workspace location and on startup does not consult with the perspective factory at all. IPerspectiveFactory is only needed the first time a perspective is created.

To debug changes to a perspective factory, you must configure your launch configuration to clear the workspace area on each launch. Open the launch configuration dialog as shown in Section 4.3.2, "Launch Configurations," and check the option called Clear workspace data before launching and uncheck Ask for confirmation before clearing. Re-run Hyperbola. You should see the empty view shown without a title bar, as shown in Figure 5-7.