Section 5.5.  Adding Images - Eclipse Rich Client Platform: Designing, Coding, and Packaging Java Applications

5.5. Adding Images

A contacts list without images doesn't look quite right. Beyond aesthetics, images are useful for showing the status of each contact. In this section we:

• Add images to the Hyperbola plug-in.

• Add images to the Contacts view.

The first thing is to create the needed images. Use your favorite image-editing program to create a couple of 16x16-pixel images in GIF format. Images used in trees and toolbars usually have a transparent background; as such, use a drawing tool that allows you to create GIF files with transparency. If you aren't much of an artist, copy the images we supplied with the code for this chapter.^[1] Table 5-1 shows the images included in the prototype.

^[1] As you can see, we are not artistically inclined, but the images serve their purpose.

Table 5-1. Hyperbola Contacts View Icons

Image	Description
	User is logged in and is available for a chat.
	User is not logged in.
	User is away from the computer. You can chat, but the user may not respond right away.
	User is logged in but doesn't want to be disturbed.
	Groups.

Add the images to the standard Eclipse location in the Hyperbola plug-inin a directory called icons at the root of the plug-in project. Next, identify the images in code so they can be referenced without having to remember where they are located on disk. A standard approach is to create an interface to track the image paths in your product. Create the IImageKeys interface shown here. The constants identify the relative path to each image in the icons directory.

org.eclipsercp.hyperbola/IImageKeys
public interface IImageKeys {
  public static final String ONLINE = "icons/online.gif";
  public static final String OFFLINE = "icons/offline.gif";
  public static final String DO_NOT_DISTURB = "icons/dnd.gif";
  public static final String GROUP = "icons/groups.gif";
  public static final String AWAY = "icons/away.gif";
}

Adding images to the Contacts view is easy; you simply update the appropriate IWorkbenchAdapters to provide an image for each item in the tree. In Eclipse, there are two image representations: Images and ImageDescriptors.

Images Images are graphical objects ready to be displayed. They maintain a handle to an underlying OS resource and as such are considered heavyweight objects. Care must be taken to dispose of these system resources when the image is no longer needed.

ImageDescriptors Descriptors are lightweight representations of an image. They know where to find the image and can create images, but do not do so immediately.

Descriptors are handy tokens you can use to talk about images before you actually need an Image object. The relationship is similar to the one between Java File and, say, FileInputStream. Files are lightweight and are not directly associated with any OS resources, whereas FileInputStreams retain file handles and trigger disk access.

The code below shows how to create an ImageDescriptor. The code first uses Bundle.getEntry(String) to locate the image file and then calls createFromURL(URL) to create an instance of the descriptor.

public ImageDescriptor createImageDescriptorFor(String id) {
  URL url = Platform.getBundle("org.eclipsercp.hyperbola").
      getEntry(id);
  return ImageDescriptor.createFromURL(url);
}

Since this is such a common coding pattern, AbstractUIPlugin has a static helper called imageDescriptorFromPlugin(String, String) that looks in all the right places for the requested image and returns a descriptor. This method uses the Bundle instance to access files in the plug-in, but does other bookkeeping that allows icons to be loaded from other locations. Since these and other methods need the plug-in's id, it's a good time to create a constant for it. The id is defined on the first page of the plug-in editor. Add the following to the Application class:

org.eclipsercp.hyperbola/Application
public static final String PLUGIN_ID = "org.eclipsercp.hyperbola";

As we discussed earlier, images need to be managed because they represent OS resources. Fortunately, when using the IWorkbenchAdapter, the Workbench manages the images that are created and all you have to do is return the appropriate image descriptor.

The image shown for a ContactsEntry depends on each user's presence. Add the presenceToKey() method below to HyperbolaAdapterFactory. It should return the appropriate image key given the provided presence.

org.eclipsercp.hyperbola/HyperbolaAdapterFactory
private String presenceToKey(Presence presence) {
  if(presence == Presence.ONLINE)
    return IImageKeys.ONLINE;
  if(presence == Presence.AWAY)
    return IImageKeys.AWAY;
  if(presence == Presence.DO_NOT_DISTURB)
    return IImageKeys.DO_NOT_DISTURB;
  if(presence == Presence.INVISIBLE)
    return IImageKeys.OFFLINE;
  return IImageKeys.OFFLINE;
}

Also, change the workbench adapters to return the image for both a contact group and a contact entry.

org.eclipsercp.hyperbola/HyperbolaAdapterFactory
public ImageDescriptor getImageDescriptor(Object object) {
  return AbstractUIPlugin.imageDescriptorFromPlugin(
      Application.PLUGIN_ID, IImageKeys.GROUP);
}
...
public ImageDescriptor getImageDescriptor(Object object) {
  ContactsEntry entry = ((ContactsEntry) object);
  String key = presenceToKey(entry.getPresence());
  return AbstractUIPlugin.imageDescriptorFromPlugin(
      Application.PLUGIN_ID, key);
}

Run Hyperbola and notice that the contacts have detailed labels and presences images, as shown in Figure 5-11the UI is coming together.