Image (JavaFX 8)

java.lang.Object
- javafx.scene.image.Image

Direct Known Subclasses:: WritableImage

public class Image
extends Object

The Image class represents graphical images and is used for loading images from a specified URL.

Supported image formats are:

Images can be resized as they are loaded (for example to reduce the amount of memory consumed by the image). The application can specify the quality of filtering used when scaling, and whether or not to preserve the original image's aspect ratio.

All URLs supported by URL can be passed to the constructor. If the passed string is not a valid URL, but a path instead, the Image is searched on the classpath in that case.

Use ImageView for displaying images loaded with this class. The same Image instance can be displayed by multiple ImageViews.

Example code for loading images.

import javafx.scene.image.Image;

// load an image in background, displaying a placeholder while it's loading
// (assuming there's an ImageView node somewhere displaying this image)
// The image is located in default package of the classpath
Image image1 = new Image("/flower.png", true);

// load an image and resize it to 100x150 without preserving its original
// aspect ratio
// The image is located in my.res package of the classpath
Image image2 = new Image("my/res/flower.png", 100, 150, false, false);

// load an image and resize it to width of 100 while preserving its
// original aspect ratio, using faster filtering method
// The image is downloaded from the supplied URL through http protocol
Image image3 = new Image("http://sample.com/res/flower.png", 100, 0, false, false);

// load an image and resize it only in one dimension, to the height of 100 and
// the original width, without preserving original aspect ratio
// The image is located in the current working directory
Image image4 = new Image("file:flower.png", 0, 100, false, false);

Since:: JavaFX 2.0

Property Summary

All Methods Instance Methods Concrete Methods
Type	Property and Description
`ReadOnlyBooleanProperty`	`error` Indicates whether an error was detected while loading an image.
`ReadOnlyObjectProperty<Exception>`	`exception` The exception which caused image loading to fail.
`ReadOnlyDoubleProperty`	`height` The image height or `0` if the image loading fails.
`ReadOnlyDoubleProperty`	`progress` The approximate percentage of image's loading that has been completed.
`ReadOnlyDoubleProperty`	`width` The image width or `0` if the image loading fails.

Constructor Summary

Constructors
Constructor and Description
`Image(InputStream is)` Construct an `Image` with content loaded from the specified input stream.
`Image(InputStream is, double requestedWidth, double requestedHeight, boolean preserveRatio, boolean smooth)` Construct a new `Image` with the specified parameters.
`Image(String url)` Constructs an `Image` with content loaded from the specified url.
`Image(String url, boolean backgroundLoading)` Construct a new `Image` with the specified parameters.
`Image(String url, double requestedWidth, double requestedHeight, boolean preserveRatio, boolean smooth)` Construct a new `Image` with the specified parameters.
`Image(String url, double requestedWidth, double requestedHeight, boolean preserveRatio, boolean smooth, boolean backgroundLoading)` Construct a new `Image` with the specified parameters.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`cancel()` Cancels the background loading of this image.
`ReadOnlyBooleanProperty`	`errorProperty()` Indicates whether an error was detected while loading an image.
`ReadOnlyObjectProperty<Exception>`	`exceptionProperty()` The exception which caused image loading to fail.
`Exception`	`getException()` Gets the value of the property exception.
`double`	`getHeight()` Gets the value of the property height.
`PixelReader`	`getPixelReader()` This method returns a `PixelReader` that provides access to read the pixels of the image, if the image is readable.
`double`	`getProgress()` Gets the value of the property progress.
`double`	`getRequestedHeight()` Gets the height of the bounding box within which the source image is resized as necessary to fit.
`double`	`getRequestedWidth()` Gets the width of the bounding box within which the source image is resized as necessary to fit.
`double`	`getWidth()` Gets the value of the property width.
`ReadOnlyDoubleProperty`	`heightProperty()` The image height or `0` if the image loading fails.
`boolean`	`isBackgroundLoading()` Indicates whether the image is being loaded in the background.
`boolean`	`isError()` Gets the value of the property error.
`boolean`	`isPreserveRatio()` Indicates whether to preserve the aspect ratio of the original image when scaling to fit the image within the bounding box provided by `width` and `height`.
`boolean`	`isSmooth()` Indicates whether to use a better quality filtering algorithm or a faster one when scaling this image to fit within the bounding box provided by `width` and `height`.
`ReadOnlyDoubleProperty`	`progressProperty()` The approximate percentage of image's loading that has been completed.
`ReadOnlyDoubleProperty`	`widthProperty()` The image width or `0` if the image loading fails.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Property Detail
  - progress
```
public final ReadOnlyDoubleProperty progressProperty
```
    The approximate percentage of image's loading that has been completed. A positive value between 0 and 1 where 0 is 0% and 1 is 100%.
    
    Default value:
    
    0
    
    See Also:
    
    getProgress()
  - width
```
public final ReadOnlyDoubleProperty widthProperty
```
    The image width or 0 if the image loading fails. While the image is being loaded it is set to 0.
    
    See Also:
    
    getWidth()
  - height
```
public final ReadOnlyDoubleProperty heightProperty
```
    The image height or 0 if the image loading fails. While the image is being loaded it is set to 0.
    
    See Also:
    
    getHeight()
  - error
```
public final ReadOnlyBooleanProperty errorProperty
```
    Indicates whether an error was detected while loading an image.
    
    Default value:
    
    false
    
    See Also:
    
    isError()
  - exception
```
public final ReadOnlyObjectProperty<Exception> exceptionProperty
```
    The exception which caused image loading to fail. Contains a non-null value only if the error property is set to true.
    
    Since:
    
    JavaFX 8.0
    
    See Also:
    
    getException()
- Constructor Detail
  - Image
```
public Image(String url)
```
    Constructs an Image with content loaded from the specified url.
    
    Parameters:
    
    url - the string representing the URL to use in fetching the pixel data
    
    Throws:
    
    NullPointerException - if URL is null
    
    IllegalArgumentException - if URL is invalid or unsupported
    
    See Also:
    
    Image(java.lang.String, java.io.InputStream, double, double, boolean, boolean, boolean)
  - Image
```
public Image(String url,
             boolean backgroundLoading)
```
    Construct a new Image with the specified parameters.
    
    Parameters:
    
    url - the string representing the URL to use in fetching the pixel data
    
    backgroundLoading - indicates whether the image is being loaded in the background
    
    Throws:
    
    NullPointerException - if URL is null
    
    IllegalArgumentException - if URL is invalid or unsupported
    
    See Also:
    
    Image(java.lang.String, java.io.InputStream, double, double, boolean, boolean, boolean)
  - Image
```
public Image(String url,
             double requestedWidth,
             double requestedHeight,
             boolean preserveRatio,
             boolean smooth)
```
    Construct a new Image with the specified parameters.
    
    Parameters:
    
    url - the string representing the URL to use in fetching the pixel data
    
    requestedWidth - the image's bounding box width
    
    requestedHeight - the image's bounding box height
    
    preserveRatio - indicates whether to preserve the aspect ratio of the original image when scaling to fit the image within the specified bounding box
    
    smooth - indicates whether to use a better quality filtering algorithm or a faster one when scaling this image to fit within the specified bounding box
    
    Throws:
    
    NullPointerException - if URL is null
    
    IllegalArgumentException - if URL is invalid or unsupported
    
    See Also:
    
    Image(java.lang.String, java.io.InputStream, double, double, boolean, boolean, boolean)
  - Image
```
public Image(String url,
             double requestedWidth,
             double requestedHeight,
             boolean preserveRatio,
             boolean smooth,
             boolean backgroundLoading)
```
    Construct a new Image with the specified parameters. The url without scheme is threated as relative to classpath, url with scheme is treated accordingly to the scheme using URL.openStream()
    
    Parameters:
    
    url - the string representing the URL to use in fetching the pixel data
    
    requestedWidth - the image's bounding box width
    
    requestedHeight - the image's bounding box height
    
    preserveRatio - indicates whether to preserve the aspect ratio of the original image when scaling to fit the image within the specified bounding box
    
    smooth - indicates whether to use a better quality filtering algorithm or a faster one when scaling this image to fit within the specified bounding box
    
    backgroundLoading - indicates whether the image is being loaded in the background
    
    Throws:
    
    NullPointerException - if URL is null
    
    IllegalArgumentException - if URL is invalid or unsupported
  - Image
```
public Image(InputStream is)
```
    Construct an Image with content loaded from the specified input stream.
    
    Parameters:
    
    is - the stream from which to load the image
    
    Throws:
    
    NullPointerException - if input stream is null
  - Image
```
public Image(InputStream is,
             double requestedWidth,
             double requestedHeight,
             boolean preserveRatio,
             boolean smooth)
```
    Construct a new Image with the specified parameters.
    
    Parameters:
    
    is - the stream from which to load the image
    
    requestedWidth - the image's bounding box width
    
    requestedHeight - the image's bounding box height
    
    preserveRatio - indicates whether to preserve the aspect ratio of the original image when scaling to fit the image within the specified bounding box
    
    smooth - indicates whether to use a better quality filtering algorithm or a faster one when scaling this image to fit within the specified bounding box
    
    Throws:
    
    NullPointerException - if input stream is null
- Method Detail
  - getProgress
```
public final double getProgress()
```
    Gets the value of the property progress.
    
    Property description:
    
    The approximate percentage of image's loading that has been completed. A positive value between 0 and 1 where 0 is 0% and 1 is 100%.
    
    Default value:
    
    0
  - progressProperty
```
public final ReadOnlyDoubleProperty progressProperty()
```
    The approximate percentage of image's loading that has been completed. A positive value between 0 and 1 where 0 is 0% and 1 is 100%.
    
    Default value:
    
    0
    
    See Also:
    
    getProgress()
  - getRequestedWidth
```
public final double getRequestedWidth()
```
    Gets the width of the bounding box within which the source image is resized as necessary to fit. If set to a value <= 0, then the intrinsic width of the image will be used.
    See preserveRatio for information on interaction between image's requestedWidth, requestedHeight and preserveRatio attributes.
    
    Returns:
    
    The requested width
  - getRequestedHeight
```
public final double getRequestedHeight()
```
    Gets the height of the bounding box within which the source image is resized as necessary to fit. If set to a value <= 0, then the intrinsic height of the image will be used.
    See preserveRatio for information on interaction between image's requestedWidth, requestedHeight and preserveRatio attributes.
    
    Returns:
    
    The requested height
  - getWidth
```
public final double getWidth()
```
    Gets the value of the property width.
    
    Property description:
    
    The image width or 0 if the image loading fails. While the image is being loaded it is set to 0.
  - widthProperty
```
public final ReadOnlyDoubleProperty widthProperty()
```
    The image width or 0 if the image loading fails. While the image is being loaded it is set to 0.
    
    See Also:
    
    getWidth()
  - getHeight
```
public final double getHeight()
```
    Gets the value of the property height.
    
    Property description:
    
    The image height or 0 if the image loading fails. While the image is being loaded it is set to 0.
  - heightProperty
```
public final ReadOnlyDoubleProperty heightProperty()
```
    The image height or 0 if the image loading fails. While the image is being loaded it is set to 0.
    
    See Also:
    
    getHeight()
  - isPreserveRatio
```
public final boolean isPreserveRatio()
```
    Indicates whether to preserve the aspect ratio of the original image when scaling to fit the image within the bounding box provided by width and height.
    If set to true, it affects the dimensions of this Image in the following way:
    - If only width is set, height is scaled to preserve ratio
    - If only height is set, width is scaled to preserve ratio
    - If both are set, they both may be scaled to get the best fit in a width by height rectangle while preserving the original aspect ratio
    The reported width and height may be different from the initially set values if they needed to be adjusted to preserve aspect ratio. If unset or set to false, it affects the dimensions of this ImageView in the following way:
    - If only width is set, the image's width is scaled to match and height is unchanged;
    - If only height is set, the image's height is scaled to match and height is unchanged;
    - If both are set, the image is scaled to match both.
    Returns:
    
    true if the aspect ratio of the original image is to be preserved when scaling to fit the image within the bounding box provided by width and height.
  - isSmooth
```
public final boolean isSmooth()
```
    Indicates whether to use a better quality filtering algorithm or a faster one when scaling this image to fit within the bounding box provided by width and height.
    If not initialized or set to true a better quality filtering will be used, otherwise a faster but lesser quality filtering will be used.
    
    Returns:
    
    true if a better quality (but slower) filtering algorithm is used for scaling to fit within the bounding box provided by width and height.
  - isBackgroundLoading
```
public final boolean isBackgroundLoading()
```
    Indicates whether the image is being loaded in the background.
    
    Returns:
    
    true if the image is loaded in the background
  - isError
```
public final boolean isError()
```
    Gets the value of the property error.
    
    Property description:
    
    Indicates whether an error was detected while loading an image.
    
    Default value:
    
    false
  - errorProperty
```
public final ReadOnlyBooleanProperty errorProperty()
```
    Indicates whether an error was detected while loading an image.
    
    Default value:
    
    false
    
    See Also:
    
    isError()
  - getException
```
public final Exception getException()
```
    Gets the value of the property exception.
    
    Property description:
    
    The exception which caused image loading to fail. Contains a non-null value only if the error property is set to true.
    
    Since:
    
    JavaFX 8.0
  - exceptionProperty
```
public final ReadOnlyObjectProperty<Exception> exceptionProperty()
```
    The exception which caused image loading to fail. Contains a non-null value only if the error property is set to true.
    
    Since:
    
    JavaFX 8.0
    
    See Also:
    
    getException()
  - cancel
```
public void cancel()
```
    Cancels the background loading of this image.
    Has no effect if this image isn't loaded in background or if loading has already completed.
  - getPixelReader
```
public final PixelReader getPixelReader()
```
    This method returns a PixelReader that provides access to read the pixels of the image, if the image is readable. If this method returns null then this image does not support reading at this time. This method will return null if the image is being loaded from a source and is still incomplete {the progress is still < 1.0) or if there was an error. This method may also return null for some images in a format that is not supported for reading and writing pixels to.
    
    Returns:
    
    the PixelReader for reading the pixel data of the image
    
    Since:
    
    JavaFX 2.2

Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 2008, 2017, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.

Class Image

Property Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Property Detail

progress

width

height

error

exception

Constructor Detail

Image

Image

Image

Image

Image

Image

Method Detail

getProgress

progressProperty

getRequestedWidth

getRequestedHeight

getWidth

widthProperty

getHeight

heightProperty

isPreserveRatio

isSmooth

isBackgroundLoading

isError

errorProperty

getException

exceptionProperty

cancel

getPixelReader