Package ej.microui.display

## Class ResourceImage

- java.lang.Object
- - ej.microui.display.Image
  - - ej.microui.display.ResourceImage

- All Implemented Interfaces:
    `Closeable`, `AutoCloseable`
  Direct Known Subclasses:
    `BufferedImage`

      public class ResourceImage
      extends Image
      implements Closeable

  A `ResourceImage` represents an image which may require dynamic allocation in order to be created.

  A resource image should be closed in order to free the dynamic allocation used to store the image pixels.

  This class provides statics method in order to load an image from a resource or from a given input stream.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `ResourceImage.OutputFormat` | Enumerates the different formats in which a resource image can store pixel colors.

  - ### Constructor Summary

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

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static boolean` | `canLoadImage​(String path)` | Returns whether an image can be loaded from a resource.
    `void` | `close()` | Closes this image and its associated resources.
    `boolean` | `isClosed()` | Returns whether this image has been closed.
    `static ResourceImage` | `loadImage​(InputStream stream, int size)` | Loads an immutable image from an `InputStream`.
    `static ResourceImage` | `loadImage​(InputStream stream, int size, ResourceImage.OutputFormat format)` | Loads an immutable image from an `InputStream`.
    `static ResourceImage` | `loadImage​(String path)` | Loads an immutable image from a resource.
    `static ResourceImage` | `loadImage​(String path, ResourceImage.OutputFormat format)` | Loads an immutable image from a resource.

    - ### Methods inherited from class ej.microui.display.Image

      `canGetImage, getHeight, getImage, getWidth, isTransparent, readPixel, readPixels`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### ResourceImage

          public ResourceImage()

  - ### Method Detail

    - #### canLoadImage

          public static boolean canLoadImage​(String path)

      Returns whether an image can be loaded from a resource.

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

      Parameters:
        `path` - the resource path.
      Returns:
        `true` if the image can be loaded, `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:
        `loadImage(String)`

    - #### loadImage

          public static ResourceImage loadImage​(String path)

      Loads an immutable image from a resource.

      This method can load images which are in the internal image format defined by the MicroUI implementation, and images which are in standard image formats (such as PNG), depending on the capabilities of the MicroUI implementation (such as having a PNG decoder).

      The MicroUI implementation is responsible for retrieving the correct image load/decoder in order to load the image.

      The output format of the returned image is the best format for the input format. For example, the output format for PNG images is `ResourceImage.OutputFormat.ARGB8888`. The output format for images in internal MicroUI image format is the output format specified in the `images.list` file.

      Calling this method is equivalent to calling `loadImage(name, null)`.

      Parameters:
        `path` - the resource path.
      Returns:
        the loaded image.
      Throws:
        `MicroUIException` - if the image could not be loaded 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 load an image.
      Since:
        2.0

    - #### loadImage

          public static ResourceImage loadImage​(String path,
                                                @Nullable
                                                ResourceImage.OutputFormat format)

      Loads an immutable image from a resource.

      This method can load images which are in the internal image format defined by the MicroUI implementation, and images which are in standard image formats (such as PNG), depending on the capabilities of the MicroUI implementation (such as having a PNG decoder).

      The MicroUI implementation is responsible for retrieving the correct image load/decoder in order to load the image.

      The output format of the image is the output format given as parameter. This format may be different from the default output format (@see `loadImage(String)`).

      Parameters:
        `path` - the resource path.
        `format` - the desired output format, or `null` to use the default output format.
      Returns:
        the loaded image.
      Throws:
        `MicroUIException` - if the image could not be loaded 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 load an image.
      Since:
        2.0

    - #### loadImage

          public static ResourceImage loadImage​(InputStream stream,
                                                int size)

      Loads an immutable image from an `InputStream`.

      Refer to `loadImage(String)` for more information.

      Calling this method is equivalent to calling `loadImage(stream, size, null)`.

      Parameters:
        `stream` - the input stream providing the image data.
        `size` - the number of bytes to read from the input stream.
      Returns:
        the loaded image.
      Throws:
        `MicroUIException` - if the image could not be loaded for any reason (see `MicroUIException.getErrorCode()`).
        `MicroUIException` - if MicroUI is not started.
        `SecurityException` - if a security manager exists and does not allow the caller to load an image.
      Since:
        2.0

    - #### loadImage

          public static ResourceImage loadImage​(InputStream stream,
                                                int size,
                                                @Nullable
                                                ResourceImage.OutputFormat format)

      Loads an immutable image from an `InputStream`.

      Refer to `loadImage(String, OutputFormat)` for more information.

      Parameters:
        `stream` - the input stream providing the image data.
        `size` - the number of bytes to read from the input stream.
        `format` - the desired output format, or `null` to use the default output format.
      Returns:
        the loaded image.
      Throws:
        `MicroUIException` - if the image could not be loaded for any reason (see `MicroUIException.getErrorCode()`).
        `MicroUIException` - if MicroUI is not started.
        `SecurityException` - if a security manager exists and does not allow the caller to load an image.
      Since:
        2.0

    - #### isClosed

          public boolean isClosed()

      Returns whether this image has been closed.
      Returns:
        `true` if the image has been closed, `false` otherwise.

    - #### close

          public void close()

      Closes this image and its associated resources.

      Calling this method on an image which has already been closed has no effect.

      Specified by:
        `close` in interface `AutoCloseable`
      Specified by:
        `close` in interface `Closeable`