Package ej.microui.display

## Class Image

- java.lang.Object
- - ej.microui.display.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 Summary

    Constructors
    Constructor | Description
    --- | ---
    `Image()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static boolean` | `canGetImage​(String path)` | Returns whether an image can be retrieved from a resource.
    `int` | `getHeight()` | Returns the height of the image.
    `static Image` | `getImage​(String path)` | Gets an immutable image from a resource.
    `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`

- - ### 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`.