Package ej.microui.display

Class Image

  • Direct Known Subclasses:
    ResourceImage
    public class Image
extends 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.

    • Constructor Detail

      • Image

        public Image()

    • Method Detail

      • canGetImage

        public static boolean canGetImage​(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.
        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​(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.
        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.

      • 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:
        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:
        ArrayIndexOutOfBoundsException - if the array is not big enough to hold the color of all the pixels of the region.
        IllegalArgumentException - if a part of the region is out of the bounds of this image.
        IllegalArgumentException - if the absolute value of scanLength is lower than width.