com.codename1.ui

Class URLImage

java.lang.Object

com.codename1.ui.Image

com.codename1.ui.EncodedImage

com.codename1.ui.URLImage

All Implemented Interfaces:

ActionSource

public class URLImage
extends EncodedImage

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.

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.

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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	URLImage.ErrorCallback Invoked in a case of an error
static interface	URLImage.ImageAdapter Allows applying resize logic to downloaded images you can use constant resize behaviors defined in this class.

Field Summary

Fields

Modifier and Type	Field and Description
static int	FLAG_RESIZE_FAIL Flag used by createCachedImage(java.lang.String, java.lang.String, com.codename1.ui.Image, int).
static int	FLAG_RESIZE_SCALE Flag used by createCachedImage(java.lang.String, java.lang.String, com.codename1.ui.Image, int) Equivalent to RESIZE_SCALE.
static int	FLAG_RESIZE_SCALE_TO_FILL Flag used by createCachedImage(java.lang.String, java.lang.String, com.codename1.ui.Image, int).
static URLImage.ImageAdapter	RESIZE_FAIL Will fail if the downloaded image has a different size from the placeholder image
static URLImage.ImageAdapter	RESIZE_SCALE Scales the image to match the size of the new image exactly
static URLImage.ImageAdapter	RESIZE_SCALE_TO_FILL Scales the image to match to fill the area while preserving aspect ratio

Method Summary

Modifier and Type	Method and Description
boolean	animate()
static Image	createCachedImage(String imageName, String url, Image placeholder, int resizeRule) Creates an image that will be downloaded on the fly as necessary.
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.
static URLImage.ImageAdapter	createMaskAdapter(Object mask)
static URLImage	createToFileSystem(EncodedImage placeholder, String file, String url, URLImage.ImageAdapter adapter) Creates an image the will be downloaded on the fly as necessary
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
static URLImage	createToStorage(EncodedImage placeholder, String storageFile, String url, URLImage.ImageAdapter adapter) Creates an image the will be downloaded on the fly as necessary
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.
static URLImage.ErrorCallback	getExceptionHandler() The exception handler is used for callbacks in case of an error
byte[]	getImageData() Returns the byte array data backing the image allowing the image to be stored and discarded completely from RAM.
protected Image	getInternal() Returns the actual image represented by the encoded image, this image will be cached in a weak/soft reference internally.
boolean	isAnimation() Returns true if this is an animated image
void	lock() Block this method from external callers as it might break the functionality
boolean	requiresDrawImage() New label optimizations don't invoke drawImage and instead just pass the native image directly to the underlying renderer.
static void	setExceptionHandler(URLImage.ErrorCallback aExceptionHandler) The exception handler is used for callbacks in case of an error
void	unlock() Block this method from external callers as it might break the functionality

Methods inherited from class com.codename1.ui.EncodedImage

asyncLock, create, create, create, create, create, createFromImage, createFromRGB, createMulti, drawImage, drawImage, getGraphics, getHeight, getImage, getWidth, isLocked, isOpaque, modifyAlpha, modifyAlpha, resetCache, rotate, scale, scaled, scaledEncoded, scaledHeight, scaledSmallerRatio, scaledWidth, subImage, toRGB

Methods inherited from class com.codename1.ui.Image

addActionListener, applyMask, applyMask, applyMaskAutoScale, createImage, createImage, createImage, createImage, createImage, createImage, createImage, createIndexed, createMask, createSVG, dispose, exifRotation, exifRotation, exifRotation, fill, fireChangedEvent, flipHorizontally, flipVertically, getExifOrientationTag, getExifOrientationTag, getImageName, getRGB, getRGB, getRGBCached, getSVGDocument, isAlphaMutableImageSupported, isJPEG, isPNG, isSVG, isSVGSupported, mirror, modifyAlphaWithTranslucency, removeActionListener, rotate180Degrees, rotate270Degrees, rotate90Degrees, scaledLargerRatio, setImageName

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FLAG_RESIZE_FAIL

public static final int FLAG_RESIZE_FAIL

Flag used by createCachedImage(java.lang.String, java.lang.String, com.codename1.ui.Image, int). Equivalent to RESIZE_FAIL

See Also:

Constant Field Values

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

Flag used by createCachedImage(java.lang.String, java.lang.String, com.codename1.ui.Image, int) Equivalent to RESIZE_SCALE.

See Also:

Constant Field Values

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

Flag used by createCachedImage(java.lang.String, java.lang.String, com.codename1.ui.Image, int). Equivalent to RESIZE_SCALE_TO_FILL.

See Also:

Constant Field Values

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 Detail

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 - 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:

Parameters:

imageMask - 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)

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!

Overrides:

getInternal in class EncodedImage

Returns:

drawable image instance

requiresDrawImage

public boolean requiresDrawImage()

Description copied from class: Image

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.

Overrides:

requiresDrawImage in class Image

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.

Overrides:

getImageData in class EncodedImage

Returns:

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

animate

public boolean animate()

Overrides:

animate in class Image

lock

public void lock()

Block this method from external callers as it might break the functionality

Overrides:

lock in class EncodedImage

unlock

public void unlock()

Block this method from external callers as it might break the functionality

Overrides:

unlock in class EncodedImage

isAnimation

public boolean isAnimation()

Returns true if this is an animated image

Overrides:

isAnimation in class EncodedImage

Returns:

true if this image represents an animation

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 - the image placeholder is shown as the image is loading/downloading and serves as the guideline to the size of the downloaded image.

storageFile - the file in storage to which the image will be stored

url - 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 - the image placeholder is shown as the image is loading/downloading and serves as the guideline to the size of the downloaded image.

storageFile - the file in storage to which the image will be stored

url - the url from which the image is fetched

adapter - 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

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 - the image placeholder is shown as the image is loading/downloading and serves as the guideline to the size of the downloaded image.

file - the file in the file system to which the image will be stored

url - the url from which the image is fetched

adapter - 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 createToFileSystem(com.codename1.ui.EncodedImage, 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 createToStorage(com.codename1.ui.EncodedImage, java.lang.String, java.lang.String).

Parameters:

imageName - The name of the image.

url - the URL from which the image is fetched

placeholder - the image placeholder is shown as the image is loading/downloading and serves as the guideline to the size of the downloaded image.

resizeRule - 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