Google Web Toolkit
Search Google Code:

# Creating and Using an Image Bundle

To define an image bundle, the user needs to extend the ImageBundle interface. The ImageBundle interface is a tag interface that can be extended to define new image bundles.

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());
    }

Tip
Image bundles are immutable, so you can keep a reference to a singleton instance of an image bundle instead of creating a new instance every time the image bundle is needed.

## Related topics

ImageBundle, AbstractImagePrototype