Google Web Toolkit (Beta)
Search this site:

# Interface ImageBundle

public interface ImageBundle
// Extended by `TreeImages`, `DisclosurePanelImages`
A tag interface that is used in the generation of image bundles. An image bundle is a composition of multiple images into a single large image, along with an interface for accessing a specific image's prototype from within the composition. Obtain an image bundle instance by calling `GWT.create(T)`, where `T` is an interface that directly or indirectly extends `ImageBundle`.

To create and use an image bundle, extend the `ImageBundle` interface, and add a method declaration for each image that is to be part of the bundle. Each method must take no parameters and must have a return type of AbstractImagePrototype. The image name can optionally be specified using the `gwt.resource` metadata tag. Valid image name extensions are `png`, `gif`, or `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.

The easiest way to create image bundle is to omit the `gwt.resource` metadata tag, and name the method the same as the image name, excluding the extension. When the image name is inferred in this manner, the image name's extension is assumed to be either `png`, `gif`, or `jpg`, and the image location must be in the same package as the user-defined image bundle. In the event that there are multiple image files that have the same name with different extensions, the order of extension precedence is `png`, `gif`, `jpg`.

### Example

     public interface MyImageBundle extends ImageBundle {

       /**
        * Notice that the gwt.resource metadata tag is not present,
        * so the method name itself is assumed to match the associated
        * image filename.
        *
        * One of btn_submit_icon.png, btn_submit_icon.gif, or
        * btn_submit_icon.jpg must be located in the same package
        * as MyImageBundle.
        */
       public AbstractImagePrototype btn_submit_icon();

       // No doc comment is required if you want the default
       // name-matching behavior.
       public AbstractImagePrototype cancelButtonIcon();
     }

An image bundle that uses the `gwt.resource` metadata tag to specify image names might look something like this:

     public interface MyImageBundle extends ImageBundle {

       /**
        * The metadata tag contains no '/' characters, so
        * btn_submit_icon.gif must be located in the same
        * package as MyImageBundle.
        *
        * @gwt.resource btn_submit_icon.gif
        */
       public AbstractImagePrototype submitButtonIcon();

       /**
        * btn_cancel_icon.png must be located in the package
        * com.mycompany.myapp.icons (which must be on the classpath).
        *
        * @gwt.resource com/mycompany/myapp/icons/btn_cancel_icon.png
        */
       public AbstractImagePrototype cancelButtonIcon();
     }

Here is how MyImageBundle might be used in an application:

      ...

      // Create a new instance of MyImageBundle using GWT.create.
      // This only needs to be done once - a reference to myImageBundle can
      // be kept for use by other parts of the application.
      MyImageBundle myImageBundle = (MyImageBundle) GWT.create(MyImageBundle.class);

      // Retrieve the image prototypes from myImageBundle.
      AbstractImagePrototype submitButtonImgPrototype = myImageBundle.btn_submit_icon();
      AbstractImagePrototype cancelButtonImgPrototype = myImageBundle.cancelButtonIcon();

      // Add the images that are created based on the prototypes to the panel.
      panel.add(submitButtonImgPrototype.createImage());
      panel.add(cancelButtonImgPrototype.createImage());

     ...

### For More Information

See the GWT Developer Guide for an introduction to image bundles.

## See Also

AbstractImagePrototype, Image.Image(String, int, int, int, int), Image.setVisibleRect(int, int, int, int), Image.setUrlAndVisibleRect(String, int, int, int, int)