# Class Image

java.lang.Object
com.codename1.ui.Image

All Implemented Interfaces:
  `ActionSource`

Direct Known Subclasses:
  `ComponentImage, DynamicImage, EncodedImage, FontImage, RGBImage, Timeline`

public class Image extends Object implements ActionSource
Abstracts the underlying platform images allowing us to treat them as a uniform object.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `Image(Object image)`
  Subclasses may use this and point to an underlying native image which might be null for a case of an image that doesn't use native drawing

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addActionListener(ActionListener l)`
  Adds ActionListener to receive action events form this source.
  `boolean`
  `animate()`
  Advances this image's animation state, if it is animated.
  `Image`
  `applyMask(Object mask)`
  Applies the given alpha mask onto this image and returns the resulting image see the createMask method for indication on how to convert an image into an alpha mask.
  `Image`
  `applyMask(Object mask, int x, int y)`
  Applies the given alpha mask onto this image and returns the resulting image see the createMask method for indication on how to convert an image into an alpha mask.
  `Image`
  `applyMaskAutoScale(Object mask)`
  Applies the given alpha mask onto this image and returns the resulting image see the createMask method for indication on how to convert an image into an alpha mask.
  `void`
  `asyncLock(Image internal)`
  Async lock is the equivalent of a lock operation, however it uses the given image as the hard cache and performs the actual image loading asynchronously.
  `static Image`
  `createImage(byte[] bytes, int offset, int len)`
  creates an image from a given byte array data
  `static Image`
  `createImage(int[] rgb, int width, int height)`
  creates an image from an RGB image
  `static Image`
  `createImage(int width, int height)`
  Creates a white opaque mutable image that may be manipulated using `#getGraphics()`.
  `static Image`
  `createImage(int width, int height, int fillColor)`
  Creates a mutable image that may be manipulated using `#getGraphics()`.
  `static Image`
  `createImage(InputStream stream)`
  creates an image from an InputStream
  `static Image`
  `createImage(Object nativeImage)`
  creates an image from the given native image (e.g. MIDP image object)
  `static Image`
  `createImage(String path)`
  Creates an image from a path.
  `static Image`
  `createIndexed(int width, int height, int[] palette, byte[] data)`
  Creates an indexed image with byte data this method may return a native indexed image rather than an instance of the IndexedImage class
  `Object`
  `createMask()`
  Creates a mask from the given image, a mask can be used to apply an arbitrary alpha channel to any image.
  `static Image`
  `createSVG(String baseURL, boolean animated, byte[] data)`
  Creates an SVG Image from the given byte array data and the base URL, this method will throw an exception if SVG is unsupported.
  `void`
  `dispose()`
  DO NOT CALL THIS METHOD UNLESS YOU KNOW WHAT YOU ARE DOING, IT WILL CAUSE PLATFORM SPECIFC CRASHES OTHERWISE! Images dispose automatically for most cases except for very rare special cases.
  `protected void`
  `drawImage(Graphics g, Object nativeGraphics, int x, int y)`
  Callback invoked internally by Codename One to draw the image/frame onto the display.
  `protected void`
  `drawImage(Graphics g, Object nativeGraphics, int x, int y, int w, int h)`
  Callback invoked internally by Codename One to draw the image/frame onto the display.
  `static Image`
  `exifRotation(String capturedImage)`
  The main use case of this method is the automatic rotation and flipping of an image returned from the camera or from the gallery, preserving the original format (jpeg or png); it detects the Exif Orientation Tag, if available (all the possible Exif Orientation Tag values are supported); transparency is not preserved.
  `static Image`
  `exifRotation(String capturedImage, String rotatedImage)`
  The main use case of this method is the automatic rotation and flipping of an image returned from the camera or from the gallery, preserving the original format (jpeg or png); it detects the Exif Orientation Tag, if available (all the possible Exif Orientation Tag values are supported); transparency is not preserved.
  `static Image`
  `exifRotation(String capturedImage, String rotatedImage, int maxSize)`
  The main use case of this method is the automatic rotation and flipping of an image returned from the camera or from the gallery, preserving the original format (jpeg or png); it detects the Exif Orientation Tag, if available (all the possible Exif Orientation Tag values are supported); transparency is not preserved.
  `Image`
  `fill(int width, int height)`
  Resizes/crops the image so that its center fills the given dimensions.
  `void`
  `fireChangedEvent()`
  `Image`
  `flipHorizontally(boolean maintainOpacity)`
  Flips this image on the horizontal axis
  `Image`
  `flipVertically(boolean maintainOpacity)`
  Flips this image on the vertical axis
  `static int`
  `getExifOrientationTag(InputStream is)`
  Gets the EXIF orientation tag of an image, if it's available.
  `static int`
  `getExifOrientationTag(String path)`
  Gets the EXIF orientation tag of an image if it's available.
  `Graphics`
  `getGraphics()`
  If this is a mutable image a graphics object allowing us to draw on it is returned.
  `int`
  `getHeight()`
  Returns the height of the image
  `Object`
  `getImage()`
  Returns the platform specific image implementation, warning the implementation class can change between revisions of Codename One and platforms.
  `String`
  `getImageName()`
  The name of the image is set for some images mostly to ease the debugging of Codename One application
  `int[]`
  `getRGB()`
  Returns the content of this image as a newly created ARGB array.
  `void`
  `getRGB(int[] rgbData)`
  Returns the content of this image in the supplied ARGB array.
  `int[]`
  `getRGBCached()`
  Returns the content of this image as a newly created ARGB array or a cached instance if possible.
  `Object`
  `getSVGDocument()`
  Returns a platform specific DOM object that can be manipulated by the user to change the SVG Image
  `int`
  `getWidth()`
  Returns the width of the image
  `static boolean`
  `isAlphaMutableImageSupported()`
  Returns true if mutable images support alpha transparency
  `boolean`
  `isAnimation()`
  Returns true if this is an animated image
  `static boolean`
  `isJPEG(InputStream inputStream)`
  Very fast method to detect if the given inputStream is a JPEG image (according to its guessed mime type)
  `boolean`
  `isLocked()`
  Returns true if the image is locked
  `boolean`
  `isOpaque()`
  Indicates whether this image is opaque or not
  `static boolean`
  `isPNG(InputStream inputStream)`
  Very fast method to detect if the given inputStream is a PNG image (according to its guessed mime type)
  `static boolean`
  `isSimdOptimizationsEnabled()`
  Indicates whether Image SIMD optimizations are enabled.
  `boolean`
  `isSVG()`
  Indicates if this image represents an SVG file or a bitmap file
  `static boolean`
  `isSVGSupported()`
  Indicates whether the underlying platform supports creating an SVG Image
  `void`
  `lock()`
  This callback indicates that a component pointing at this image is initialized, this allows an image to make performance sensitive considerations e.g.
  `Image`
  `mirror()`
  Creates a mirror image for the given image which is useful for some RTL scenarios.
  `Image`
  `modifyAlpha(byte alpha)`
  Creates a new image instance with the alpha channel of opaque/translucent pixels within the image using the new alpha value.
  `Image`
  `modifyAlpha(byte alpha, int removeColor)`
  Creates a new image instance with the alpha channel of opaque/translucent pixels within the image using the new alpha value.
  `Image`
  `modifyAlphaWithTranslucency(byte alpha)`
  Creates a new image instance with the alpha channel of opaque pixels within the image using the new alpha value.
  `void`
  `removeActionListener(ActionListener l)`
  Removes ActionListener so that it will no longer receive events from this source.
  `boolean`
  `requiresDrawImage()`
  New label optimizations don't invoke drawImage and instead just pass the native image directly to the underlying renderer.
  `static void`
  `resetSimdOptimizationsEnabled()`
  Clears the explicit Image SIMD override and restores the default behavior of using SIMD whenever it is supported by the current platform.
  `Image`
  `rotate(int degrees)`
  Returns an instance of this image rotated by the given number of degrees.
  `Image`
  `rotate180Degrees(boolean maintainOpacity)`
  Rotates the image by 180 degrees
  `Image`
  `rotate270Degrees(boolean maintainOpacity)`
  Rotates the image by 270 degrees while changing the ratio of the picture
  `Image`
  `rotate90Degrees(boolean maintainOpacity)`
  Rotates this image by 90 degrees while changing the ratio of the picture
  `void`
  `scale(int width, int height)`
  Scale the image to the given width and height, this is a fast algorithm that preserves translucent information
  `Image`
  `scaled(int width, int height)`
  Returns a scaled version of this image image using the given width and height, this is a fast algorithm that preserves translucent information.
  `Image`
  `scaledHeight(int height)`
  Scales the image to the given height while updating the width based on the aspect ratio of the height
  `Image`
  `scaledLargerRatio(int width, int height)`
  Scales the image while maintaining the aspect ratio to the larger size image
  `Image`
  `scaledSmallerRatio(int width, int height)`
  Scales the image while maintaining the aspect ratio to the smaller size image
  `Image`
  `scaledWidth(int width)`
  Scales the image to the given width while updating the height based on the aspect ratio of the width
  `void`
  `setImageName(String imageName)`
  The name of the image is set for some images mostly to ease the debugging of Codename One application
  `static void`
  `setSimdOptimizationsEnabled(boolean enabled)`
  Enables or disables Image SIMD optimizations explicitly.
  `Image`
  `subImage(int x, int y, int width, int height, boolean processAlpha)`
  Extracts a subimage from the given image allowing us to breakdown a single large image into multiple smaller images in RAM, this actually creates a standalone version of the image for use.
  `void`
  `toRGB(RGBImage image, int destX, int destY, int x, int y, int width, int height)`
  Extracts data from this image into the given RGBImage
  `void`
  `unlock()`
  This callback indicates that a component pointing at this image is now deinitilized This method may be invoked multiple times.

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### Image

    protected Image(Object image)

    Subclasses may use this and point to an underlying native image which might be null for a case of an image that doesn't use native drawing

    ###### Parameters

    - `image`: native image object passed to the Codename One implementation

- ## Method Details

  - ### isSimdOptimizationsEnabled

    public static boolean isSimdOptimizationsEnabled()
    Indicates whether Image SIMD optimizations are enabled. When unset this defaults to the current platform SIMD support.

  - ### setSimdOptimizationsEnabled

    public static void setSimdOptimizationsEnabled(boolean enabled)
    Enables or disables Image SIMD optimizations explicitly.

  - ### resetSimdOptimizationsEnabled

    public static void resetSimdOptimizationsEnabled()
    Clears the explicit Image SIMD override and restores the default behavior of using SIMD whenever it is supported by the current platform.

  - ### isSVGSupported

    public static boolean isSVGSupported()

    Indicates whether the underlying platform supports creating an SVG Image

    ###### Returns

    Returns:
      true if the method create SVG image would return a valid image object from an SVG Input stream

  - ### createSVG

    public static Image createSVG(String baseURL, boolean animated, byte[] data) throws IOException

    Creates an SVG Image from the given byte array data and the base URL, this method will throw an exception if SVG is unsupported.

    ###### Parameters

    - `baseURL`: URL which is used to resolve relative references within the SVG file

    - `animated`: indicates if the SVG features an animation

    - `data`: the conten of the SVG file

    ###### Returns

    an image object that can be used as any other image object.

    ###### Throws

    - `IOException`: if resource lookup fail SVG is unsupported
    Throws:
      `IOException`

  - ### createIndexed

    public static Image createIndexed(int width, int height, int[] palette, byte[] data)

    Creates an indexed image with byte data this method may return a native indexed image rather than an instance of the IndexedImage class

    ###### Parameters

    - `width`: image width

    - `height`: image height

    - `palette`: the color palette to use with the byte data

    - `data`: byte data containing palette offsets to map to ARGB colors

    ###### Deprecated

    try to avoid using indexed images explicitly

  - ### createImage

    public static Image createImage(String path) throws IOException

    Creates an image from a path.

    ###### Parameters

    - `path`: @param path If path begins with file: then the image will be loaded from FileSystemStorage. Otherwise it will load from the jar resources.

    ###### Returns

    newly created image object

    ###### Throws

    - `java.io.IOException`
    Throws:
      `IOException`

  - ### createImage

    public static Image createImage(Object nativeImage)

    creates an image from the given native image (e.g. MIDP image object)

    ###### Parameters

    - `nativeImage`

    ###### Returns

    newly created Codename One image object

    ###### Deprecated

  - ### createImage

    public static Image createImage(InputStream stream) throws IOException

    creates an image from an InputStream

    ###### Parameters

    - `stream`: a given InputStream

    ###### Returns

    the newly created image

    ###### Throws

    - `java.io.IOException`
    Throws:
      `IOException`

  - ### createImage

    public static Image createImage(int[] rgb, int width, int height)

    creates an image from an RGB image

    ###### Parameters

    - `rgb`: the RGB image array data

    - `width`: the image width

    - `height`: the image height

    ###### Returns

    an image from an RGB image

  - ### createImage

    public static Image createImage(int width, int height)

    Creates a white opaque mutable image that may be manipulated using `#getGraphics()`.

    The sample below shows this method being used to create a screenshot for sharing the image:

        Form hi = new Form("ShareButton");
        ShareButton sb = new ShareButton();
        sb.setText("Share Screenshot");
        hi.add(sb);

        Image screenshot = Image.createImage(hi.getWidth(), hi.getHeight());
        hi.revalidate();
        hi.setVisible(true);
        hi.paintComponent(screenshot.getGraphics(), true);

        String imageFile = FileSystemStorage.getInstance().getAppHomePath() + "screenshot.png";
        try(OutputStream os = FileSystemStorage.getInstance().openOutputStream(imageFile)) {
            ImageIO.getImageIO().save(screenshot, os, ImageIO.FORMAT_PNG, 1);
        } catch(IOException err) {
            Log.e(err);
        }
        sb.setImageToShare(imageFile, "image/png");

    The sample below demonstrates the drawing of a mask image to create a round image effect

        Toolbar.setGlobalToolbar(true);
        Form hi = new Form("Rounder", new BorderLayout());
        Label picture = new Label("", "Container");
        hi.add(BorderLayout.CENTER, picture);
        hi.getUnselectedStyle().setBgColor(0xff0000);
        hi.getUnselectedStyle().setBgTransparency(255);
        Style s = UIManager.getInstance().getComponentStyle("TitleCommand");
        Image camera = FontImage.createMaterial(FontImage.MATERIAL_CAMERA, s);
        hi.getToolbar().addCommandToRightBar("", camera, (ev) -> {
            try {
                int width = Display.getInstance().getDisplayWidth();
                Image capturedImage = Image.createImage(Capture.capturePhoto(width, -1));
                Image roundMask = Image.createImage(width, capturedImage.getHeight(), 0xff000000);
                Graphics gr = roundMask.getGraphics();
                gr.setColor(0xffffff);
                gr.fillArc(0, 0, width, width, 0, 360);
                Object mask = roundMask.createMask();
                capturedImage = capturedImage.applyMask(mask);
                picture.setIcon(capturedImage);
                hi.revalidate();
            } catch(IOException err) {
                Log.e(err);
            }
        });

    ###### Parameters

    - `width`: the image width

    - `height`: the image height

    ###### Returns

    an image in a given width and height dimension

  - ### isAlphaMutableImageSupported

    public static boolean isAlphaMutableImageSupported()

    Returns true if mutable images support alpha transparency

    ###### Returns

    true if mutable images support alpha in their fillColor argument

  - ### createImage

    public static Image createImage(int width, int height, int fillColor)

    Creates a mutable image that may be manipulated using `#getGraphics()`.

    The sample below shows this method being used to create a screenshot for sharing the image:

        Form hi = new Form("ShareButton");
        ShareButton sb = new ShareButton();
        sb.setText("Share Screenshot");
        hi.add(sb);

        Image screenshot = Image.createImage(hi.getWidth(), hi.getHeight());
        hi.revalidate();
        hi.setVisible(true);
        hi.paintComponent(screenshot.getGraphics(), true);

        String imageFile = FileSystemStorage.getInstance().getAppHomePath() + "screenshot.png";
        try(OutputStream os = FileSystemStorage.getInstance().openOutputStream(imageFile)) {
            ImageIO.getImageIO().save(screenshot, os, ImageIO.FORMAT_PNG, 1);
        } catch(IOException err) {
            Log.e(err);
        }
        sb.setImageToShare(imageFile, "image/png");

    ###### Parameters

    - `width`: the image width

    - `height`: the image height

    - `fillColor`: the color with which the image should be initially filled

    ###### Returns

    an image in a given width and height dimension

  - ### createImage

    public static Image createImage(byte[] bytes, int offset, int len)

    creates an image from a given byte array data

    ###### Parameters

    - `bytes`: the array of image data in a supported image format

    - `offset`: the offset of the start of the data in the array

    - `len`: the length of the data in the array

    ###### Returns

    the newly created image

  - ### exifRotation

    public static Image exifRotation(String capturedImage) throws IOException

    The main use case of this method is the automatic rotation and flipping of an image returned from the camera or from the gallery, preserving the original format (jpeg or png); it detects the Exif Orientation Tag, if available (all the possible Exif Orientation Tag values are supported); transparency is not preserved.

    If there is no rotation or flipping, the image is only copied or scaled if necessary; if the capturedImage has a format different from jpeg and png, it is copied as it is. Note that this method doesn't rely on the file extension, but on the mime type of the capturedImage, since some devices don't give appropriate extension to images returned from the gallery.

    You can test all the possible orientation values downloading the images from the repository EXIF Orientation-flag example images

    Code example:

        Form hi = new Form("Hi World", BoxLayout.y());
        Button cameraBtn = new Button("Open Camera");
        Button galleryBtn = new Button("Open Gallery");
        Label imageLbl = new Label();
        hi.addAll(cameraBtn, galleryBtn, FlowLayout.encloseCenter(imageLbl));
        hi.show();

        SuccessCallback<String> callback = new SuccessCallback<String>() {
            public void onSucess(String capturedPhoto) {
            String rotatedPhoto = FileSystemStorage.getInstance().getAppHomePath() + "rotatedPhoto.jpg";
            if (capturedPhoto != null) {
                try {
                    // note: we set a maxSize to perform a faster rotation
                    int maxSize = CN.convertToPixels(50);
                    Image img = Image.exifRotation(capturedPhoto, rotatedPhoto, maxSize);
                    imageLbl.setIcon(img);
                    hi.revalidate();
                } catch (IOException ex) {
                    Log.e(ex);
                }
            }
            }
        };
        cameraBtn.addActionListener(a -> Capture.capturePhoto(l -> {
            if (l != null && l.getSource() != null) {
                callback.onSucess((String) l.getSource());
            }
        }));
        galleryBtn.addActionListener(a -> CN.openGallery(l -> {
            if (l != null && l.getSource() != null) {
                callback.onSucess((String) l.getSource());
            }
        }, CN.GALLERY_IMAGE));

    ###### Parameters

    - `capturedImage`: @param capturedImage is the FileSystemStorage path of a captured photo, usually inside a temporary directory

    ###### Returns

    the rotated and/or flipped image

    Throws:
      `IOException`

  - ### exifRotation

    public static Image exifRotation(String capturedImage, String rotatedImage) throws IOException

    The main use case of this method is the automatic rotation and flipping of an image returned from the camera or from the gallery, preserving the original format (jpeg or png); it detects the Exif Orientation Tag, if available (all the possible Exif Orientation Tag values are supported); transparency is not preserved.

    If there is no rotation or flipping, the image is only copied or scaled if necessary; if the capturedImage has a format different from jpeg and png, it is copied as it is. Note that this method doesn't rely on the file extension, but on the mime type of the capturedImage, since some devices don't give appropriate extension to images returned from the gallery.

    You can test all the possible orientation values downloading the images from the repository EXIF Orientation-flag example images

    Code example:

        Form hi = new Form("Hi World", BoxLayout.y());
        Button cameraBtn = new Button("Open Camera");
        Button galleryBtn = new Button("Open Gallery");
        Label imageLbl = new Label();
        hi.addAll(cameraBtn, galleryBtn, FlowLayout.encloseCenter(imageLbl));
        hi.show();

        SuccessCallback<String> callback = new SuccessCallback<String>() {
            public void onSucess(String capturedPhoto) {
            String rotatedPhoto = FileSystemStorage.getInstance().getAppHomePath() + "rotatedPhoto.jpg";
            if (capturedPhoto != null) {
                try {
                    // note: we set a maxSize to perform a faster rotation
                    int maxSize = CN.convertToPixels(50);
                    Image img = Image.exifRotation(capturedPhoto, rotatedPhoto, maxSize);
                    imageLbl.setIcon(img);
                    hi.revalidate();
                } catch (IOException ex) {
                    Log.e(ex);
                }
            }
            }
        };
        cameraBtn.addActionListener(a -> Capture.capturePhoto(l -> {
            if (l != null && l.getSource() != null) {
                callback.onSucess((String) l.getSource());
            }
        }));
        galleryBtn.addActionListener(a -> CN.openGallery(l -> {
            if (l != null && l.getSource() != null) {
                callback.onSucess((String) l.getSource());
            }
        }, CN.GALLERY_IMAGE));

    ###### Parameters

    - `capturedImage`: @param capturedImage is the FileSystemStorage path of a captured photo, usually inside a temporary directory

    - `rotatedImage`: @param rotatedImage is the FileSystemStorage path in which the rotated photo is stored, normally this should be inside the FileSystemStorage.getAppHomePath(); it can be null if you don't want to save the rotated image to the FileSystemStorage.

    ###### Returns

    the rotated and/or flipped image

    Throws:
      `IOException`

  - ### exifRotation

    public static Image exifRotation(String capturedImage, String rotatedImage, int maxSize) throws IOException

    The main use case of this method is the automatic rotation and flipping of an image returned from the camera or from the gallery, preserving the original format (jpeg or png); it detects the Exif Orientation Tag, if available (all the possible Exif Orientation Tag values are supported); transparency is not preserved.

    However, rotating and/or flipping an hi-res image is very inefficient, that's why you should consider to pass a maxSize value as small as possible: it makes this method working faster.

    If there is no rotation or flipping, the image is only copied or scaled if necessary; if the capturedImage has a format different from jpeg and png, it is copied as it is. Note that this method doesn't rely on the file extension, but on the mime type of the capturedImage, since some devices don't give appropriate extension to images returned from the gallery.

    You can test all the possible orientation values downloading the images from the repository EXIF Orientation-flag example images

    Code example:

        Form hi = new Form("Hi World", BoxLayout.y());
        Button cameraBtn = new Button("Open Camera");
        Button galleryBtn = new Button("Open Gallery");
        Label imageLbl = new Label();
        hi.addAll(cameraBtn, galleryBtn, FlowLayout.encloseCenter(imageLbl));
        hi.show();

        SuccessCallback<String> callback = new SuccessCallback<String>() {
            public void onSucess(String capturedPhoto) {
            String rotatedPhoto = FileSystemStorage.getInstance().getAppHomePath() + "rotatedPhoto.jpg";
            if (capturedPhoto != null) {
                try {
                    // note: we set a maxSize to perform a faster rotation
                    int maxSize = CN.convertToPixels(50);
                    Image img = Image.exifRotation(capturedPhoto, rotatedPhoto, maxSize);
                    imageLbl.setIcon(img);
                    hi.revalidate();
                } catch (IOException ex) {
                    Log.e(ex);
                }
            }
            }
        };
        cameraBtn.addActionListener(a -> Capture.capturePhoto(l -> {
            if (l != null && l.getSource() != null) {
                callback.onSucess((String) l.getSource());
            }
        }));
        galleryBtn.addActionListener(a -> CN.openGallery(l -> {
            if (l != null && l.getSource() != null) {
                callback.onSucess((String) l.getSource());
            }
        }, CN.GALLERY_IMAGE));

    ###### Parameters

    - `capturedImage`: @param capturedImage is the FileSystemStorage path of a captured photo, usually inside a temporary directory

    - `rotatedImage`: @param rotatedImage is the FileSystemStorage path in which the rotated photo is stored, normally this should be inside the FileSystemStorage.getAppHomePath(); it can be null if you don't want to save the rotated image to the FileSystemStorage.

    - `maxSize`: @param maxSize is the maximum value of the width and height of the rotated images, that is scaled if necessary, keeping the ratio.

    ###### Returns

    the com.codename1.ui.Image

    ###### Throws

    - `java.io.IOException`
    Throws:
      `IOException`

  - ### getExifOrientationTag

    public static int getExifOrientationTag(String path) throws IOException

    Gets the EXIF orientation tag of an image if it's available.

    The Exif Orientation Tag is a number from 0 to 8, for the explanation of each value see the Exif Orientation Tag page

    You can test all the possible orientation values downloading the images from the repository EXIF Orientation-flag example images

    ###### Parameters

    - `path`: FileSystemStorage path

    ###### Returns

    Returns:

      a value from 0 to 8; 0 is default in case of error or unavailable EXIF data.

      ###### Throws

      - `java.io.IOException`
    Throws:
      `IOException`

  - ### getExifOrientationTag

    public static int getExifOrientationTag(InputStream is)

    Gets the EXIF orientation tag of an image, if it's available.

    The Exif Orientation Tag is a number from 0 to 8, for the explanation of each value see the Exif Orientation Tag page

    You can test all the possible orientation values downloading the images from the repository EXIF Orientation-flag example images

    ###### Parameters

    - `is`

    ###### Returns

    Returns:
      a value from 0 to 8; 0 is default in case of error or unavailable EXIF data.

  - ### isJPEG

    public static boolean isJPEG(InputStream inputStream) throws IOException

    Very fast method to detect if the given inputStream is a JPEG image (according to its guessed mime type)

    ###### Parameters

    - `inputStream`

    ###### Returns

    true if jpeg, false otherwise

    Throws:
      `IOException`

  - ### isPNG

    public static boolean isPNG(InputStream inputStream) throws IOException

    Very fast method to detect if the given inputStream is a PNG image (according to its guessed mime type)

    ###### Parameters

    - `inputStream`

    ###### Returns

    true if PNG, false otherwise

    Throws:
      `IOException`

  - ### asyncLock

    public void asyncLock(Image internal)

    Async lock is the equivalent of a lock operation, however it uses the given image as the hard cache and performs the actual image loading asynchronously. On completion this method will invoke repaint on the main form if applicable.

    ###### Parameters

    - `internal`: the image to show while the actual image loads.

  - ### lock

    public void lock()
    This callback indicates that a component pointing at this image is initialized, this allows an image to make performance sensitive considerations e.g. an encoded image might choose to cache itself in RAM. This method may be invoked multiple times.

  - ### isLocked

    public boolean isLocked()

    Returns true if the image is locked

    ###### Returns

    false by default

  - ### unlock

    public void unlock()
    This callback indicates that a component pointing at this image is now deinitilized This method may be invoked multiple times.

  - ### getSVGDocument

    public Object getSVGDocument()

    Returns a platform specific DOM object that can be manipulated by the user to change the SVG Image

    ###### Returns

    Returns:
      Platform dependent object, when JSR 226 is supported an SVGSVGElement might be returned.

  - ### isSVG

    public boolean isSVG()

    Indicates if this image represents an SVG file or a bitmap file

    ###### Returns

    true if this is an SVG file

  - ### createMask

    public Object createMask()

    Creates a mask from the given image, a mask can be used to apply an arbitrary alpha channel to any image. A mask is derived from the blue channel (LSB) of the given image, other channels are ignored.

    The generated mask can be used with the apply mask method.

    The sample below demonstrates the masking of an image based on a circle drawn on a mutable image:

        Toolbar.setGlobalToolbar(true);
        Form hi = new Form("Rounder", new BorderLayout());
        Label picture = new Label("", "Container");
        hi.add(BorderLayout.CENTER, picture);
        hi.getUnselectedStyle().setBgColor(0xff0000);
        hi.getUnselectedStyle().setBgTransparency(255);
        Style s = UIManager.getInstance().getComponentStyle("TitleCommand");
        Image camera = FontImage.createMaterial(FontImage.MATERIAL_CAMERA, s);
        hi.getToolbar().addCommandToRightBar("", camera, (ev) -> {
            try {
                int width = Display.getInstance().getDisplayWidth();
                Image capturedImage = Image.createImage(Capture.capturePhoto(width, -1));
                Image roundMask = Image.createImage(width, capturedImage.getHeight(), 0xff000000);
                Graphics gr = roundMask.getGraphics();
                gr.setColor(0xffffff);
                gr.fillArc(0, 0, width, width, 0, 360);
                Object mask = roundMask.createMask();
                capturedImage = capturedImage.applyMask(mask);
                picture.setIcon(capturedImage);
                hi.revalidate();
            } catch(IOException err) {
                Log.e(err);
            }
        });

    ###### Returns

    mask object that can be used with applyMask

  - ### applyMask

    public Image applyMask(Object mask, int x, int y)

    Applies the given alpha mask onto this image and returns the resulting image see the createMask method for indication on how to convert an image into an alpha mask.

    The sample below demonstrates the masking of an image based on a circle drawn on a mutable image:

        Toolbar.setGlobalToolbar(true);
        Form hi = new Form("Rounder", new BorderLayout());
        Label picture = new Label("", "Container");
        hi.add(BorderLayout.CENTER, picture);
        hi.getUnselectedStyle().setBgColor(0xff0000);
        hi.getUnselectedStyle().setBgTransparency(255);
        Style s = UIManager.getInstance().getComponentStyle("TitleCommand");
        Image camera = FontImage.createMaterial(FontImage.MATERIAL_CAMERA, s);
        hi.getToolbar().addCommandToRightBar("", camera, (ev) -> {
            try {
                int width = Display.getInstance().getDisplayWidth();
                Image capturedImage = Image.createImage(Capture.capturePhoto(width, -1));
                Image roundMask = Image.createImage(width, capturedImage.getHeight(), 0xff000000);
                Graphics gr = roundMask.getGraphics();
                gr.setColor(0xffffff);
                gr.fillArc(0, 0, width, width, 0, 360);
                Object mask = roundMask.createMask();
                capturedImage = capturedImage.applyMask(mask);
                picture.setIcon(capturedImage);
                hi.revalidate();
            } catch(IOException err) {
                Log.e(err);
            }
        });

    ###### Parameters

    - `mask`: mask object created by the createMask() method.

    - `x`: starting x where to apply the mask

    - `y`: starting y where to apply the mask

    ###### Returns

    image masked based on the given object

  - ### applyMask

    public Image applyMask(Object mask)

    Applies the given alpha mask onto this image and returns the resulting image see the createMask method for indication on how to convert an image into an alpha mask.

    ###### Parameters

    - `mask`: mask object created by the createMask() method.

    ###### Returns

    image masked based on the given object

    ###### Throws

    - `IllegalArgumentException`: if the image size doesn't match the mask size

  - ### applyMaskAutoScale

    public Image applyMaskAutoScale(Object mask)

    Applies the given alpha mask onto this image and returns the resulting image see the createMask method for indication on how to convert an image into an alpha mask. If the image is of a different size it will be scaled to mask size.

    ###### Parameters

    - `mask`: mask object created by the createMask() method.

    ###### Returns

    image masked based on the given object

  - ### subImage

    public Image subImage(int x, int y, int width, int height, boolean processAlpha)

    Extracts a subimage from the given image allowing us to breakdown a single large image into multiple smaller images in RAM, this actually creates a standalone version of the image for use.

    ###### Parameters

    - `x`: the x offset from the image

    - `y`: the y offset from the image

    - `width`: the width of internal images

    - `height`: the height of internal images

    - `processAlpha`: whether alpha should be processed as well as part of the cutting

    ###### Returns

    An array of all the possible images that can be created from the source

  - ### mirror

    public Image mirror()

    Creates a mirror image for the given image which is useful for some RTL scenarios. Notice that this method isn't the most efficient way to perform this task and is designed for portability over efficiency.

    ###### Returns

    a mirrored image

  - ### rotate

    public Image rotate(int degrees)

    Returns an instance of this image rotated by the given number of degrees. By default 90 degree angle divisions are supported, anything else is implementation dependent. This method assumes a square image. Notice that it is inefficient in the current implementation to rotate to non-square angles,

    E.g. rotating an image to 45, 90 and 135 degrees is inefficient. Use rotatate to 45, 90 and then rotate the 45 to another 90 degrees to achieve the same effect with less memory.

    ###### Parameters

    - `degrees`: A degree in right angle must be larger than 0 and up to 359 degrees

    ###### Returns

    new image instance with the closest possible rotation

  - ### modifyAlpha

    public Image modifyAlpha(byte alpha)

    Creates a new image instance with the alpha channel of opaque/translucent pixels within the image using the new alpha value. Transparent (alpha == 0) pixels remain transparent. All other pixels will have the new alpha value.

    ###### Parameters

    - `alpha`: New value for the entire alpha channel

    ###### Returns

    Returns:
      Translucent/Opaque image based on the alpha value and the pixels of this image

  - ### modifyAlphaWithTranslucency

    public Image modifyAlphaWithTranslucency(byte alpha)

    Creates a new image instance with the alpha channel of opaque pixels within the image using the new alpha value. Transparent (alpha == 0) pixels remain transparent. Semi translucent pixels will be multiplied by the ratio difference and their translucency reduced appropriately.

    ###### Parameters

    - `alpha`: New value for the entire alpha channel

    ###### Returns

    Returns:
      Translucent/Opaque image based on the alpha value and the pixels of this image

  - ### modifyAlpha

    public Image modifyAlpha(byte alpha, int removeColor)

    Creates a new image instance with the alpha channel of opaque/translucent pixels within the image using the new alpha value. Transparent (alpha == 0) pixels remain transparent. All other pixels will have the new alpha value.

    ###### Parameters

    - `alpha`: New value for the entire alpha channel

    - `removeColor`: pixels matching this color are made transparent (alpha channel ignored)

    ###### Returns

    Returns:
      Translucent/Opaque image based on the alpha value and the pixels of this image

  - ### getGraphics

    public Graphics getGraphics()

    If this is a mutable image a graphics object allowing us to draw on it is returned.

    ###### Returns

    Graphics object allowing us to manipulate the content of a mutable image

  - ### getWidth

    public int getWidth()

    Returns the width of the image

    ###### Returns

    the width of the image

  - ### getHeight

    public int getHeight()

    Returns the height of the image

    ###### Returns

    the height of the image

  - ### drawImage

    protected void drawImage(Graphics g, Object nativeGraphics, int x, int y)

    Callback invoked internally by Codename One to draw the image/frame onto the display. Image subclasses can override this method to perform drawing of custom image types.

    ###### Parameters

    - `g`: the graphics object

    - `nativeGraphics`: the underlying native graphics which might be essential for some image types

    - `x`: the x coordinate

    - `y`: the y coordinate

  - ### drawImage

    protected void drawImage(Graphics g, Object nativeGraphics, int x, int y, int w, int h)

    Callback invoked internally by Codename One to draw the image/frame onto the display. Image subclasses can override this method to perform drawing of custom image types.

    ###### Parameters

    - `g`: the graphics object

    - `nativeGraphics`: the underlying native graphics which might be essential for some image types

    - `x`: the x coordinate

    - `y`: the y coordinate

    - `w`: the width to occupy

    - `h`: the height to occupy

  - ### toRGB

    public void toRGB(RGBImage image, int destX, int destY, int x, int y, int width, int height)

    Extracts data from this image into the given RGBImage

    ###### Parameters

    - `image`: RGBImage that would receive pixel data

    - `destX`: @param destX x location within RGBImage into which the data will be written

    - `destY`: @param destY y location within RGBImage into which the data will be written

    - `x`: location within the source image

    - `y`: location within the source image

    - `width`: size of the image to extract from the source image

    - `height`: size of the image to extract from the source image

  - ### getRGB

    public int[] getRGB()

    Returns the content of this image as a newly created ARGB array.

    ###### Returns

    new array instance containing the ARGB data within this image

  - ### getRGB

    public void getRGB(int[] rgbData)

    Returns the content of this image in the supplied ARGB array.

    ###### Parameters

    - `rgbData`

  - ### getRGBCached

    public int[] getRGBCached()

    Returns the content of this image as a newly created ARGB array or a cached instance if possible. Note that cached instances may be garbage collected.

    ###### Returns

    array instance containing the ARGB data within this image

  - ### scaledWidth

    public Image scaledWidth(int width)

    Scales the image to the given width while updating the height based on the aspect ratio of the width

    ###### Parameters

    - `width`: the given new image width

    ###### Returns

    the newly created image

  - ### scaledHeight

    public Image scaledHeight(int height)

    Scales the image to the given height while updating the width based on the aspect ratio of the height

    ###### Parameters

    - `height`: the given new image height

    ###### Returns

    the newly created image

  - ### scaledSmallerRatio

    public Image scaledSmallerRatio(int width, int height)

    Scales the image while maintaining the aspect ratio to the smaller size image

    ###### Parameters

    - `width`: the given new image width

    - `height`: the given new image height

    ###### Returns

    the newly created image

  - ### scaledLargerRatio

    public Image scaledLargerRatio(int width, int height)

    Scales the image while maintaining the aspect ratio to the larger size image

    ###### Parameters

    - `width`: the given new image width

    - `height`: the given new image height

    ###### Returns

    the newly created image

  - ### scaled

    public Image scaled(int width, int height)

    Returns a scaled version of this image image using the given width and height, this is a fast algorithm that preserves translucent information. The method accepts -1 to preserve aspect ratio in the given axis.

    ###### Parameters

    - `width`: width for the scaling

    - `height`: height of the scaled image

    ###### Returns

    new image instance scaled to the given height and width

  - ### fill

    public Image fill(int width, int height)

    Resizes/crops the image so that its center fills the given dimensions. This is similar to `com.codename1.ui.plaf.Style#BACKGROUND_IMAGE_SCALED_FILL`

    ###### Parameters

    - `width`: the width to fill

    - `height`: the height to fill

    ###### Returns

    a new image (or the same image if dimensions happen to match) filling the width/height

  - ### getImage

    public Object getImage()

    Returns the platform specific image implementation, warning the implementation class can change between revisions of Codename One and platforms.

    ###### Returns

    platform specific native implementation for this image object

  - ### scale

    public void scale(int width, int height)

    Scale the image to the given width and height, this is a fast algorithm that preserves translucent information

    ###### Parameters

    - `width`: width for the scaling

    - `height`: height of the scaled image

    ###### Deprecated

  - ### isAnimation

    public boolean isAnimation()

    Returns true if this is an animated image

    ###### Returns

    true if this image represents an animation

  - ### animate

    public boolean animate()

    Advances this image's animation state, if it is animated.

    ###### Returns

    `true` if the animation state changed.

  - ### isOpaque

    public boolean isOpaque()

    Indicates whether this image is opaque or not

    ###### Returns

    true if the image is completely opqaque which allows for some heavy optimizations

  - ### getImageName

    public String getImageName()

    The name of the image is set for some images mostly to ease the debugging of Codename One application

    ###### Returns

    the imageName

  - ### setImageName

    public void setImageName(String imageName)

    The name of the image is set for some images mostly to ease the debugging of Codename One application

    ###### Parameters

    - `imageName`: the imageName to set

  - ### dispose

    public void dispose()

    DO NOT CALL THIS METHOD UNLESS YOU KNOW WHAT YOU ARE DOING, IT WILL CAUSE PLATFORM SPECIFC CRASHES OTHERWISE! Images dispose automatically for most cases except for very rare special cases. Images on devices usually holds a native memory, some platforms garbage collectors might fail to release the native and to fail with out of memory errors. Use this method to make sure the image will be released from memory, after calling this the image will become unusable.

    ###### Deprecated

    SERIOUSLY, DON'T INVOKE THIS METHOD UNLESS YOU KNOW WHAT YOU ARE DOING IT WILL CAUSE PLATFORM SPECIFC CRASHES OTHERWISE. IF YOU INVOKED THIS METHOD YOU ARE PROBABLY MAKING A MISTAKE

  - ### rotate90Degrees

    public Image rotate90Degrees(boolean maintainOpacity)

    Rotates this image by 90 degrees while changing the ratio of the picture

    ###### Parameters

    - `maintainOpacity`: whether the opacity in the image should be maintained

    ###### Returns

    a new image rotated by 90 degrees

  - ### rotate180Degrees

    public Image rotate180Degrees(boolean maintainOpacity)

    Rotates the image by 180 degrees

    ###### Parameters

    - `maintainOpacity`: whether the opacity in the image should be maintained

    ###### Returns

    a new image rotated by 180 degrees

  - ### rotate270Degrees

    public Image rotate270Degrees(boolean maintainOpacity)

    Rotates the image by 270 degrees while changing the ratio of the picture

    ###### Parameters

    - `maintainOpacity`: whether the opacity in the image should be maintained

    ###### Returns

    a new image rotated by 270 degrees

  - ### flipHorizontally

    public Image flipHorizontally(boolean maintainOpacity)

    Flips this image on the horizontal axis

    ###### Parameters

    - `maintainOpacity`: whether the opacity in the image should be maintained

    ###### Returns

    a new image flipped

  - ### flipVertically

    public Image flipVertically(boolean maintainOpacity)

    Flips this image on the vertical axis

    ###### Parameters

    - `maintainOpacity`: whether the opacity in the image should be maintained

    ###### Returns

    a new image flipped

  - ### requiresDrawImage

    public boolean requiresDrawImage()

    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.

    ###### Returns

    true if a drawImage call is a required

  - ### addActionListener

    public void addActionListener(ActionListener l)
    Description copied from interface: `ActionSource`

    Adds ActionListener to receive action events form this source.

    ###### Parameters

    - `l`
    Specified by:
      `addActionListener` in interface `ActionSource`

  - ### removeActionListener

    public void removeActionListener(ActionListener l)
    Description copied from interface: `ActionSource`

    Removes ActionListener so that it will no longer receive events from this source.

    ###### Parameters

    - `l`
    Specified by:
      `removeActionListener` in interface `ActionSource`

  - ### fireChangedEvent

    public void fireChangedEvent()