Creating and Using an Image Bundle

The derived interface can have zero or more methods, where each method

• takes no parameters,
• has a return type of AbstractImagePrototype, and
• may have an optional gwt.resource metadata tag which specifies the name of the image file in the module's classpath

Valid image file types are png, gif, and jpg. If the image name contains '/' characters, it is assumed to be the name of a resource on the classpath, formatted as would be expected by ClassLoader.getResource(String). Otherwise, the image must be located in the same package as the user-defined image bundle.

If the gwt.resource metadata tag is not specified, then

• the image filename is assumed to match the method name,
• the extension is assumed to be either .png, .gif, or .jpg, and
• the file is assumed to be in the same package as the derived interface

In the event that there are multiple image files with different extensions, the order of extension precedence is (1) png, (2) gif, then (3) jpg.

An image bundle for icons in a word processor application could be defined as follows:

public interface WordProcessorImageBundle extends ImageBundle {

  /**
   * Would match the file 'new_file_icon.png', 'new_file_icon.gif', or
   * 'new_file_icon.png' located in the same package as this type.
   */
  public AbstractImagePrototype new_file_icon();

  /**
   * Would match the file 'open_file_icon.gif' located in the same
   * package as this type.
   * 
   * @gwt.resource open_file_icon.gif
   */
  public AbstractImagePrototype openFileIcon();

  /**
   * Would match the file 'savefile.gif' located in the package
   * 'com.mycompany.mygwtapp.icons', provided that this package is part
   * of the module's classpath.
   * 
   * @gwt.resource com/mycompany/mygwtapp/icons/savefile.gif
   */
  public AbstractImagePrototype saveFileIcon();
}

Methods in an image bundle return AbstractImagePrototype objects (rather than Image objects, as you might have expected) because AbstractImagePrototype objects provide additional lightweight representations of an image. For example, the AbstractImagePrototype.getHTML() method provides an HTML fragment representing an image without having to create an actual instance of the Image widget. In some cases, it can be more efficient to manage images using these HTML fragments.

Another use of AbstractImagePrototype is to use AbstractImagePrototype.applyTo(Image) to transform an existing Image into one that matches the prototype without having to instantiate another Image object. This can be useful if your application has an image that needs to be swapped depending on some user-initiated action. Of course, if an Image is exactly what you need, the AbstractImagePrototype.createImage() method can be used to generate new Image instances.

The following example shows how to use the image bundle that we just defined in your application:

public void useImageBundle() {
  WordProcessorImageBundle wpImageBundle = (WordProcessorImageBundle) GWT.create(WordProcessorImageBundle.class);
  HorizontalPanel tbPanel = new HorizontalPanel();
  tbPanel.add(wpImageBundle.new_file_icon().createImage());
  tbPanel.add(wpImageBundle.openFileIcon().createImage());
  tbPanel.add(wpImageBundle.saveFileIcon().createImage());
}