ej.microui.display

Class Image

java.lang.Object

ej.microui.display.Image

Direct Known Subclasses:

ResourceImage

public class Image
extends java.lang.Object

An Image represents a graphical two-dimensional object. An image is divided in pixels, and each pixel holds a value defining its color.

This class provides a static method in order to retrieve an image from a resource which is in the internal image format defined by the MicroUI implementation.

Method Summary

Modifier and Type	Method and Description
static boolean	canGetImage(java.lang.String path) Returns whether an image can be retrieved from a resource.
int	getHeight() Returns the height of the image.
static Image	getImage(java.lang.String path) Gets an immutable image from a resource.
byte[]	getSNIContext() Returns the SNI context data of this image.
int	getWidth() Returns the width of the image.
boolean	isTransparent() Returns whether this image is transparent.
int	readPixel(int x, int y) Returns the color of a pixel of this image.
void	readPixels(int[] array, int offset, int scanLength, int x, int y, int width, int height) Retrieves the color of the pixels of a region of this image.

Methods inherited from class java.lang.Object

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

Method Detail

canGetImage

public static boolean canGetImage(java.lang.String path)

Returns whether an image can be retrieved from a resource.

This method may be used to know whether calling getImage(String) with the given path would be successful or not.

Parameters:

path - the resource path.

Returns:

true if the image can be retrieved, false otherwise.

Throws:

MicroUIException - if the resource path doesn't start with "/".

MicroUIException - if MicroUI is not started.

java.lang.SecurityException - if a security manager exists and does not allow the caller to load an image.

Since:

3.0

See Also:

getImage(String)

getImage

public static Image getImage(java.lang.String path)

Gets an immutable image from a resource.

This method can only retrieve images which are in the internal image format defined by the MicroUI implementation. This operation does not require a dynamic allocation in order to store the image pixels.

If the resource cannot be retrieved, a MicroUIException is thrown even if the resource is present but requires a loading step.

Parameters:

path - the resource path.

Returns:

the retrieved image.

Throws:

MicroUIException - if the image could not be retrieved for any reason (see MicroUIException.getErrorCode()).

MicroUIException - if the resource path doesn't start with "/".

MicroUIException - if MicroUI is not started.

java.lang.SecurityException - if a security manager exists and does not allow the caller to retrieve an image.

Since:

3.0

getWidth

public int getWidth()

Returns the width of the image.

Returns:

the width of the image, in pixels.

getHeight

public int getHeight()

Returns the height of the image.

Returns:

the height of the image, in pixels.

isTransparent

public boolean isTransparent()

Returns whether this image is transparent.

An image is considered as transparent if it contains at least one transparent pixel.

Returns:

true if the image is transparent, false otherwise.

Throws:

MicroUIException - if this image has been closed (see ResourceImage.close()).

readPixel

public int readPixel(int x,
                     int y)

Returns the color of a pixel of this image.

For more information on the format of the color value returned by this method, refer to the first paragraphs of the centralized pixel reading documentation.

Parameters:

x - the x coordinate of the pixel.

y - the y coordinate of the pixel.

Returns:

the color of the pixel, in ARGB format.

Throws:

java.lang.IllegalArgumentException - if the given pixel coordinates are out of the bounds of this image.

MicroUIException - if this image has been closed (see ResourceImage.close()).

readPixels

public void readPixels(int[] array,
                       int offset,
                       int scanLength,
                       int x,
                       int y,
                       int width,
                       int height)

Retrieves the color of the pixels of a region of this image.

For more information on this method, refer to the centralized pixel reading documentation.

Parameters:

array - the array in which the pixel data should be stored.

offset - the index of the array at which the first pixel color should be stored.

scanLength - the relative offset in the array between two corresponding pixels in consecutive rows.

x - the x-coordinate of the top-left pixel of the region.

y - the y-coordinate of the top-left pixel of the region.

width - the width of the region.

height - the height of the region.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the array is not big enough to hold the color of all the pixels of the region.

java.lang.IllegalArgumentException - if a part of the region is out of the bounds of this image.

java.lang.IllegalArgumentException - if the absolute value of scanLength is lower than width.

getSNIContext

public byte[] getSNIContext()

Returns the SNI context data of this image.

The SNI context can be used to call a native method with SNI. This allows to identify and to use an image in the native world in order to perform drawings on the image (if it is mutable) or to use it as a source.

If the image is mutable, the data returned by this method is the same than the data returned when getting the SNI context of the graphics context of the image (see GraphicsContext.getSNIContext()).

If the SNI context is used in a native method, the application should synchronize the calls on the image object in order to prevent the image from being closed during the drawing.

The data format is implementation specific.

Returns:

the SNI context of this image.

Throws:

MicroUIException - if this image has been closed (see ResourceImage.close()).