From Emitrom

Jump to: navigation, search

Back to Index

Picture is a Shape that acts as a wrapper for an HTML image. Because it's a Shape, it can be used in a LienzoPanel and supports the various Shape features, such as Shape Transformations, Dragging, Events etc.

Hand-point.png Picture Javadoc
Hand-point.png Draw Image Demo Hand-point.png Scale Image demo Hand-point.png Drag Image demo


Creating a Picture

Pictures can be created from an image URL or from an ImageResource (see GWT Developer's Guide - Bundling Image Resources.)

The Picture constructors come in various flavors:

All the constructors require the following two parameters: listening and pictureCategory, because these parameters are used when the underlying image is loaded and prepared for use in the Lienzo framework.

Note that the constructors that take an ImageResource simply set the URL attribute to ImageResource.getSafeUri().asString() and then invoke a URL-based constructor.


Attributes Description
url Image URL or URL of an ImageResource.
listening If set to false, the Picture can't be dragged and won't respond to Events. The upside is that it will not need to generate a separate Image for the Selection Layer, which saves memory and time, both for generating the selection layer Image and when drawing the Picture.
pictureCategory Used by PictureLoader when (all the images of) all the Pictures in a category are loaded.

Null (which is the default value) means: use the default category. See below.

clippedImageStartX X coordinate of the clip region. Default: 0.
clippedImageStartY Y coordinate of the clip region. Default: 0.
clippedImageWidth Width of the clip region. Default: 0, which means use the width of the actual image.
clippedImageHeight Height of the clip region. Default: 0, which means use the width of the actual image.
clippedImageDestinationWidth Width of the target image. Default: 0, which means use clippedImageWidth.
clippedImageDestinationHeight Height of the target image. Default: 0, which means use clippedImageHeight.
serializationMode Defines how the Picture is serialized. See Picture Serialization below.
resourceID Used during serialization when serializationMode is RESOURCE_ID

See Shape Attributes for additional attributes that are common to all Shapes.


When specified, the clip region (sx, sy, sw, sh) defines which part of the source image is used by the Picture instance. Specifying a target region (dx, dy, dw, dh) allows for initial scaling.

Clip region and destination region
Diagram Picture Attribute
sx clipImageStartX
sy clipImageStartY
sw clipImageWidth
sh clipImageHeight
dx Always 0.
dy Always 0.
dw clipImageDestinationWidth
dh clipImageDestinationHeight

Note that the top-left corner of the resulting (clipped) image is always at (0,0) unless the X, Y or Transform related attributes are set (see Shape Transformations.)

Note also that initial scaling is possible via the clipImageDestinationWidth and clipImageDestinationHeight attributes, but that additional scaling is possible via the scale and Transform attributes (see Shape Transformations.)


Because images are loaded asynchronously, it is likely that the image is not yet loaded when a Picture constructor completes execution. In this case, you may want to wait until the image has loaded, e.g. before you draw the Scene or Layer that the Picture is part of.

To wait for a single Picture to load:

Picture pic = new Picture("foo.png", false, null);
pic.onLoad(new PictureLoadedHandler() {
    public void pictureLoaded(Picture p)
        // continue ...

To wait for several pictures to load, use one or more picture categories:

String pictureCategory = "category1";

Picture pic1 = new Picture("foo.png", false, pictureCategory);
Picture pic2 = new Picture("bar.png", false, pictureCategory);

Picture.onCategoryLoaded(pictureCategory, new Runnable() {
    public void run()
        // continue ...

Note that the onLoad and onCategoryLoaded methods may be triggered immediately in case the images were already loaded.

If you only need one category, i.e. you just want to wait until all images are loaded, you can use a pictureCategory value of null:

Picture pic1 = new Picture("foo.png", false, null);
Picture pic2 = new Picture("bar.png", false, null);

Picture.onCategoryLoaded(null, new Runnable() {
    public void run()
        // continue ...

Hand-point.png Draw Image Demo

Picture Serialization

Just like all Shapes, Pictures can be serialized to JSON and the JSON string can be deserialized back into a Picture.

Lienzo supports three Serialization Modes:

Hand-point.png See also Serialization


The ResourceResolver should be used when the image URLs may differ between the application that serializes a Picture and the application that deserializes it.

When serializing, specify a SerializationMode of RESOURCE_ID and give the Picture a resourceID:

Picture pic1 = new Picture("foo.png", false, null);

When deserializing, install a custom ResourceResolver first:

ResourceResolver myResolver = new ResourceResolver()
    protected String resolvePictureResourceID(Picture p, String resourceID)
        if ("pic1_id".equals(resourceID))
            return "bar.png";

            // or, for an ImageResource:
            // ImageResource resource = Resources.IMAGES.myImage();
            // return resource.getSafeUri().asString();
        return null;
ResourceResolver.setInstance(myResolver); // install the ResourceResolver

// and continue with the deserialization ...

Hand-point.png SerializationMode Javadoc Hand-point.png ResourceResolver Javadoc


Picture has a getImageData() method that produces an ImageData object that can be further processed by Image Filters.

Hand-point.png See Image Filter demo.

Personal tools