com.google.gwt.user.client.ui
Interface ImageBundle

All Known Subinterfaces:
DisclosurePanelImages, TreeImages

public interface ImageBundle

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)