public final class URLImage

  1. Object
  2. Image
  3. EncodedImage
  4. URLImage

ImplementsActionSource

URLImage allows us to create an image from a URL. If the image was downloaded already it is fetched from cache; if not it is downloaded optionally scaled/adapted and placed in cache.

By default an image is fetched lazily as it is asked for by the GUI unless the fetch() method is invoked in which case the IO code is executed immediately.

This sample code show a URLImage that is fetched to the title area background and scaled/cropped to fit device specific dimensions.

Toolbar.setGlobalToolbar(true);

Form hi = new Form("Toolbar", new BoxLayout(BoxLayout.Y_AXIS));
EncodedImage placeholder = EncodedImage.createFromImage(Image.createImage(hi.getWidth(), hi.getWidth() / 5, 0xffff0000), true);
URLImage background = URLImage.createToStorage(placeholder, "400px-AGameOfThrones.jpg",
        "http://awoiaf.westeros.org/images/thumb/9/93/AGameOfThrones.jpg/400px-AGameOfThrones.jpg");
background.fetch();
Style stitle = hi.getToolbar().getTitleComponent().getUnselectedStyle();
stitle.setBgImage(background);
stitle.setBackgroundType(Style.BACKGROUND_IMAGE_SCALED_FILL);
stitle.setPaddingUnit(Style.UNIT_TYPE_DIPS, Style.UNIT_TYPE_DIPS, Style.UNIT_TYPE_DIPS, Style.UNIT_TYPE_DIPS);
stitle.setPaddingTop(15);
SpanButton credit = new SpanButton("This excerpt is from A Wiki Of Ice And Fire. Please check it out by clicking here!");
credit.addActionListener((e) -> Display.getInstance().execute("http://awoiaf.westeros.org/index.php/A_Game_of_Thrones"));
hi.add(new SpanLabel("A Game of Thrones is the first of seven planned novels in A Song of Ice and Fire, an epic fantasy series by American author George R. R. Martin. It was first published on 6 August 1996. The novel was nominated for the 1998 Nebula Award and the 1997 World Fantasy Award,[1] and won the 1997 Locus Award.[2] The novella Blood of the Dragon, comprising the Daenerys Targaryen chapters from the novel, won the 1997 Hugo Award for Best Novella. ")).
        add(new Label("Plot introduction", "Heading")).
        add(new SpanLabel("A Game of Thrones is set in the Seven Kingdoms of Westeros, a land reminiscent of Medieval Europe. In Westeros the seasons last for years, sometimes decades, at a time.\n\n" +
            "Fifteen years prior to the novel, the Seven Kingdoms were torn apart by a civil war, known alternately as \"Robert's Rebellion\" and the \"War of the Usurper.\" Prince Rhaegar Targaryen kidnapped Lyanna Stark, arousing the ire of her family and of her betrothed, Lord Robert Baratheon (the war's titular rebel). The Mad King, Aerys II Targaryen, had Lyanna's father and eldest brother executed when they demanded her safe return. Her second brother, Eddard, joined his boyhood friend Robert Baratheon and Jon Arryn, with whom they had been fostered as children, in declaring war against the ruling Targaryen dynasty, securing the allegiances of House Tully and House Arryn through a network of dynastic marriages (Lord Eddard to Catelyn Tully and Lord Arryn to Lysa Tully). The powerful House Tyrell continued to support the King, but House Lannister and House Martell both stalled due to insults against their houses by the Targaryens. The civil war climaxed with the Battle of the Trident, when Prince Rhaegar was killed in battle by Robert Baratheon. The Lannisters finally agreed to support King Aerys, but then brutally... ")).
        add(credit);

ComponentAnimation title = hi.getToolbar().getTitleComponent().createStyleAnimation("Title", 200);
hi.getAnimationManager().onTitleScrollAnimation(title);
hi.show();

This sample code shows the usage of the nestoria API to fill out an infinitely scrolling list in it we use URLImage to fetch the icon.

Form hi = new Form("InfiniteScrollAdapter", BoxLayout.y());

Style s = UIManager.getInstance().getComponentStyle("MultiLine1");
FontImage p = FontImage.createMaterial(FontImage.MATERIAL_PORTRAIT, s);
EncodedImage placeholder = EncodedImage.createFromImage(
        p.scaled(p.getWidth() * 3, p.getHeight() * 3),
        false);

InfiniteScrollAdapter.createInfiniteScroll(hi.getContentPane(), () -> {
    MultiButton[] cmps = new MultiButton[10];
    for (int i = 0; i < cmps.length; i++) {
        String imageKey = "listing-" + i;
        String imageUrl = "https://example.com/images/" + i + ".png";
        MultiButton row = new MultiButton("Listing " + i);
        row.setIcon(URLImage.createToStorage(placeholder, imageKey, imageUrl));
        cmps[i] = row;
    }
    InfiniteScrollAdapter.addMoreComponents(hi.getContentPane(), cmps, true);
}, true);
hi.show();

You can use adapters with masks using syntax similar to this to create a round image mask for a URLImage:

Image roundMask = Image.createImage(placeholder.getWidth(), placeholder.getHeight(), 0xff000000);
Graphics gr = roundMask.getGraphics();
gr.setColor(0xffffff);
gr.fillArc(0, 0, placeholder.getWidth(), placeholder.getHeight(), 0, 360);

URLImage.ImageAdapter ada = URLImage.createMaskAdapter(roundMask);
Image i = URLImage.createToStorage(placeholder, "fileNameInStorage", "http://xxx/myurl.jpg", ada);

Nested types

interface URLImage.RequestDecoratorDecorator hook applied to the ConnectionRequest that loads a network-backed URLImage.
interface URLImage.ErrorCallbackInvoked in a case of an error
interface URLImage.ImageAdapterAllows applying resize logic to downloaded images you can use constant resize behaviors defined in this class.

Fields

public static final int FLAG_RESIZE_FAIL = 3Flag used by java.lang.String, com.codename1.ui.Image, int).
public static final URLImage.ImageAdapter RESIZE_FAILWill fail if the downloaded image has a different size from the placeholder image
public static final int FLAG_RESIZE_SCALE = 1Flag used by java.lang.String, com.codename1.ui.Image, int) Equivalent to #RESIZE_SCALE.
public static final URLImage.ImageAdapter RESIZE_SCALEScales the image to match the size of the new image exactly
public static final int FLAG_RESIZE_SCALE_TO_FILL = 2Flag used by java.lang.String, com.codename1.ui.Image, int).
public static final URLImage.ImageAdapter RESIZE_SCALE_TO_FILLScales the image to match to fill the area while preserving aspect ratio

Methods

public static void setDefaultRequestDecorator(URLImage.RequestDecorator decorator)Installs a global RequestDecorator.
public static URLImage.RequestDecorator getDefaultRequestDecorator()Returns the global default decorator installed via #setDefaultRequestDecorator(RequestDecorator), or null.
public static void setDefaultBearerToken(String token)Convenience for the most common case: every URLImage fetch should carry the same Authorization: Bearer <token> header.
public static URLImage.ErrorCallback getExceptionHandler()The exception handler is used for callbacks in case of an error
public static void setExceptionHandler(URLImage.ErrorCallback aExceptionHandler)The exception handler is used for callbacks in case of an error
public static URLImage.ImageAdapter createMaskAdapter(Image imageMask)Creates an adapter that uses an image as a Mask, this is roughly the same as SCALE_TO_FILL with the exception that a mask will be applied later on.
public static URLImage.ImageAdapter createMaskAdapter(Object mask)
public static URLImage createToStorage(EncodedImage placeholder, String storageFile, String url)Creates an image the will be downloaded on the fly as necessary with RESIZE_SCALE_TO_FILL as the default behavior
public static URLImage createToStorage(EncodedImage placeholder, String storageFile, String url, URLImage.ImageAdapter adapter)Creates an image the will be downloaded on the fly as necessary
public static URLImage createToStorage(EncodedImage placeholder, String storageFile, String url, URLImage.ImageAdapter adapter, URLImage.RequestDecorator decorator)Same as #createToStorage(EncodedImage, String, String, ImageAdapter), plus a per-call RequestDecorator applied to the ConnectionRequest that fetches the image bytes.
public static URLImage createToFileSystem(EncodedImage placeholder, String file, String url, URLImage.ImageAdapter adapter)Creates an image the will be downloaded on the fly as necessary
public static Image createCachedImage(String imageName, String url, Image placeholder, int resizeRule)Creates an image that will be downloaded on the fly as necessary.
public void fetch()Images are normally fetched from storage or network only as needed, however if the download must start before the image is drawn this method can be invoked.
protected Image getInternal()Returns the actual image represented by the encoded image, this image will be cached in a weak/soft reference internally.
public boolean requiresDrawImage()New label optimizations don’t invoke drawImage and instead just pass the native image directly to the underlying renderer.
public byte[] getImageData()Returns the byte array data backing the image allowing the image to be stored and discarded completely from RAM.
public boolean animate()Advances this image’s animation state, if it is animated.
public void lock()Block this method from external callers as it might break the functionality
public void unlock()Block this method from external callers as it might break the functionality
public boolean isAnimation()Returns true if this is an animated image

Inherited methods

Field details

FLAG_RESIZE_FAIL

public static final int FLAG_RESIZE_FAIL = 3
Flag used by java.lang.String, com.codename1.ui.Image, int). Equivalent to #RESIZE_FAIL

RESIZE_FAIL

public static final URLImage.ImageAdapter RESIZE_FAIL
Will fail if the downloaded image has a different size from the placeholder image

FLAG_RESIZE_SCALE

public static final int FLAG_RESIZE_SCALE = 1
Flag used by java.lang.String, com.codename1.ui.Image, int) Equivalent to #RESIZE_SCALE.

RESIZE_SCALE

public static final URLImage.ImageAdapter RESIZE_SCALE
Scales the image to match the size of the new image exactly

FLAG_RESIZE_SCALE_TO_FILL

public static final int FLAG_RESIZE_SCALE_TO_FILL = 2
Flag used by java.lang.String, com.codename1.ui.Image, int). Equivalent to #RESIZE_SCALE_TO_FILL.

RESIZE_SCALE_TO_FILL

public static final URLImage.ImageAdapter RESIZE_SCALE_TO_FILL
Scales the image to match to fill the area while preserving aspect ratio

Method details

setDefaultRequestDecorator

public static void setDefaultRequestDecorator(URLImage.RequestDecorator decorator)
Installs a global RequestDecorator. Pass null to clear the existing default. The decorator runs on every URLImage’s ConnectionRequest immediately before it’s queued.

getDefaultRequestDecorator

public static URLImage.RequestDecorator getDefaultRequestDecorator()
Returns the global default decorator installed via #setDefaultRequestDecorator(RequestDecorator), or null.

setDefaultBearerToken

public static void setDefaultBearerToken(String token)

Convenience for the most common case: every URLImage fetch should carry the same Authorization: Bearer <token> header. Equivalent to setDefaultRequestDecorator(req -> req.addRequestHeader( "Authorization", "Bearer " + token)).

Pass null to clear. Subsequent calls replace the previously-set header value; the same Authorization header is not appended twice.

getExceptionHandler

public static URLImage.ErrorCallback getExceptionHandler()
The exception handler is used for callbacks in case of an error

Returns

the exceptionHandler

setExceptionHandler

public static void setExceptionHandler(URLImage.ErrorCallback aExceptionHandler)
The exception handler is used for callbacks in case of an error

Parameters

aExceptionHandler URLImage.ErrorCallback
the exceptionHandler to set

createMaskAdapter

public static URLImage.ImageAdapter createMaskAdapter(Image imageMask)

Creates an adapter that uses an image as a Mask, this is roughly the same as SCALE_TO_FILL with the exception that a mask will be applied later on. This adapter requires that the resulting image be in the size of the imageMask!

See the sample usage code below that implements a circular image masked downloader:

Image roundMask = Image.createImage(placeholder.getWidth(), placeholder.getHeight(), 0xff000000);
Graphics gr = roundMask.getGraphics();
gr.setColor(0xffffff);
gr.fillArc(0, 0, placeholder.getWidth(), placeholder.getHeight(), 0, 360);

URLImage.ImageAdapter ada = URLImage.createMaskAdapter(roundMask);
Image i = URLImage.createToStorage(placeholder, "fileNameInStorage", "http://xxx/myurl.jpg", ada);

Parameters

imageMask Image
the mask image see the createMask() method of image for details of what a mask is, it will be used as the reference size for the image and resulting images must be of the same size!

Returns

the adapter

createMaskAdapter

public static URLImage.ImageAdapter createMaskAdapter(Object mask)

createToStorage

public static URLImage createToStorage(EncodedImage placeholder, String storageFile, String url)
Creates an image the will be downloaded on the fly as necessary with RESIZE_SCALE_TO_FILL as the default behavior

Parameters

placeholder EncodedImage
the image placeholder is shown as the image is loading/downloading and serves as the guideline to the size of the downloaded image.
storageFile String
the file in storage to which the image will be stored
url String
the url from which the image is fetched

Returns

a URLImage that will initialy just delegate to the placeholder

createToStorage

public static URLImage createToStorage(EncodedImage placeholder, String storageFile, String url, URLImage.ImageAdapter adapter)
Creates an image the will be downloaded on the fly as necessary

Parameters

placeholder EncodedImage
the image placeholder is shown as the image is loading/downloading and serves as the guideline to the size of the downloaded image.
storageFile String
the file in storage to which the image will be stored
url String
the url from which the image is fetched
adapter URLImage.ImageAdapter
the adapter used to adapt the image into place, it should scale the image if necessary

Returns

a URLImage that will initialy just delegate to the placeholder

createToStorage

public static URLImage createToStorage(EncodedImage placeholder, String storageFile, String url, URLImage.ImageAdapter adapter, URLImage.RequestDecorator decorator)

Same as #createToStorage(EncodedImage, String, String, ImageAdapter), plus a per-call RequestDecorator applied to the ConnectionRequest that fetches the image bytes. Use when the URL requires authentication, custom headers, or other ConnectionRequest configuration not covered by the default.

If a global default decorator is also installed via #setDefaultRequestDecorator(RequestDecorator), the global default runs first, then the per-call decorator – so the per-call decorator can override headers set by the default.

createToFileSystem

public static URLImage createToFileSystem(EncodedImage placeholder, String file, String url, URLImage.ImageAdapter adapter)
Creates an image the will be downloaded on the fly as necessary

Parameters

placeholder EncodedImage
the image placeholder is shown as the image is loading/downloading and serves as the guideline to the size of the downloaded image.
file String
the file in the file system to which the image will be stored
url String
the url from which the image is fetched
adapter URLImage.ImageAdapter
the adapter used to adapt the image into place, it should scale the image if necessary

Returns

a URLImage that will initialy just delegate to the placeholder

createCachedImage

public static Image createCachedImage(String imageName, String url, Image placeholder, int resizeRule)
Creates an image that will be downloaded on the fly as necessary. On platforms that support a native image cache (e.g. Javascript), the image will be loaded directly from the native cache (i.e. it defers to the platform to handle all caching considerations. On platforms that don’t have a native image cache but do have a caches directory FileSystemStorage#hasCachesDir(), this will call java.lang.String, java.lang.String, com.codename1.ui.URLImage.ImageAdapter) with a file location in the caches directory. In all other cases, this will call java.lang.String, java.lang.String).

Parameters

imageName String
The name of the image.
url String
the URL from which the image is fetched
placeholder Image
the image placeholder is shown as the image is loading/downloading and serves as the guideline to the size of the downloaded image.
resizeRule int
One of #FLAG_RESIZE_FAIL, #FLAG_RESIZE_SCALE, or #FLAG_RESIZE_SCALE_TO_FILL.

Returns

a Image that will initially just delegate to the placeholder

fetch

public void fetch()
Images are normally fetched from storage or network only as needed, however if the download must start before the image is drawn this method can be invoked. Notice that “immediately” doesn’t mean synchronously, it just means that the image will be added to the queue right away but probably won’t be available by the time the method completes.

getInternal

protected Image getInternal()
Returns the actual image represented by the encoded image, this image will be cached in a weak/soft reference internally. This method is useful to detect when the system actually created an image instance. You shouldn’t invoke this method manually!

Returns

drawable image instance

requiresDrawImage

public boolean requiresDrawImage()
New label optimizations don’t invoke drawImage and instead just pass the native image directly to the underlying renderer. This is problematic for some image types specifically timeline & FontImage and this method allows these classes to indicate that they need that legacy behavior of calling drawImage.

Returns

true if a drawImage call is a required

getImageData

public byte[] getImageData()
Returns the byte array data backing the image allowing the image to be stored and discarded completely from RAM.

Returns

byte array used to create the image, e.g. encoded PNG, JPEG etc.

animate

public boolean animate()
Advances this image’s animation state, if it is animated.

Returns

true if the animation state changed.

lock

public void lock()
Block this method from external callers as it might break the functionality

unlock

public void unlock()
Block this method from external callers as it might break the functionality

isAnimation

public boolean isAnimation()
Returns true if this is an animated image

Returns

true if this image represents an animation