GWT and Image manipulation

GWT comes with a very interesting collection of tools to facilitate application development. But it is first necessary to know how to use them. I propose therefore in this post to discover some of the facilities offered by GWT for image manipulation.

The ClientBundle interface

ClientBundle defines a common way to manage external resources with GWT, images, text, stylesheets … all this in order to optimize the code produced by the compilation and resources management, including limiting the number of HTTP requests and the bandwidth used.

The first thing to do before using ClientBundle is to add the following tag in the application file gwt.xml

Then just create an interface that will extend ClientBundle. And at the same time, create an instance of this interface by using the method GWT.create (…)

public interface ImageResources extends ClientBundle {

    public static final ImageResources INSTANCE = GWT.create(ImageResources.class);

}

At this point, we have everything we need, now we will associate a few simple images

zenika1.png has an original size of 1280×800 for 83.7 KB
zenika1-small.png has an original size of 128×80 for 3.46 KB

public interface ImageResources extends ClientBundle {

    public static final ImageResources INSTANCE = GWT.create(ImageResources.class);

    @Source("zenika1.png")
    ImageResource zenika1Large();

    @Source("zenika1-small.png")
    ImageResource zenika1Small();
}

.. And we add them in our panel

Image largeImage = new Image(ImageResources.INSTANCE.zenika1Large());
demo1.add(largeImage);

Image smallImage = new Image(ImageResources.INSTANCE.zenika1Small());
demo1.add(smallImage);

So you can see that we just had to create a interface method that returns an object of type ImageResource and add the @Source annotation to specify the path to our image. (The annotation is optional if the name of the method is the same as the image and the interface ImageResources and images are in the same package.) Here’s the result.

GWT Optimizations

Ok, this is really nice, but what’s the advantage over a simple GWT Image with the path of the image. We’re getting there …

To see the difference, we must look at the generated code :

• For the left image (the big one), here is the produced code

For all images that are larger than 32 KB (which is the case with this one), GWT combines them into gwt cache.png file that can be seen here in the style tag.

• For the right image (the small one), here is the produced code (at least in part)

If the image size is less than 32K, the image is embedded directly within the HTML page, encoded in base64.

Resizing Images

Another interesting feature is to resize pictures directly in the code, by using annotations

In the example below, from the same source image, we will create 3 different images.

@Source("zenika1.png")
@ImageOptions(height = 80, width = 128)
ImageResource zenikaSmall();

@Source("zenika1.png")
@ImageOptions(height = 240, width = 384)
ImageResource zenikaMedium();

@Source("zenika1.png")
@ImageOptions(height = 640, width = 1024)
ImageResource zenikaLarge();

This gives after adding pictures to our page:

To go further …

The annotation ImageOptions provides additional options that are used in some rare cases.

• flipRtl: true | false

Sets whether the image must be tilted or not depending on y-axis, when the selected language is a “right to left”

Suppose we have specified this option to true, then if the method com.google.gwt.i18n.client.LocaleInfo.isRTL () returns false (meaning the writing is from left to right) the image displayed will be as

If writing is from right to left, the image displayed will be :

• repeatStyle: None | Horizontal | Vertical | Both

This option specifies how GWT “bundle-ize” the image when this one is intended to be repeated horizontally or vertically. This option is used with the @sprite attribute from GWT.

Conclusion

I strongly advise you to use the GWT bundle mechanism to manage your images in your GWT applications. This allows to simplify your code by just having to specify the characteristics of your image (path, size) in one place. Second, it improves the performance of your application, especially if it includes many icons and images used in different places.

The source code of this article is available on github here: https://github.com/julienvey/GWT-Stuff/tree/master/images