public class Image extends Object
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
ImageView
s.
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);
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 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. |
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. |
public final ReadOnlyDoubleProperty progressProperty
getProgress()
public final ReadOnlyDoubleProperty widthProperty
0
if the image loading fails. While the image
is being loaded it is set to 0
.getWidth()
public final ReadOnlyDoubleProperty heightProperty
0
if the image loading fails. While the image
is being loaded it is set to 0
.getHeight()
public final ReadOnlyBooleanProperty errorProperty
isError()
public final ReadOnlyObjectProperty<Exception> exceptionProperty
error
property is set to true
.getException()
public Image(String url)
Image
with content loaded from the specified
url.url
- the string representing the URL to use in fetching the pixel
dataNullPointerException
- if URL is nullIllegalArgumentException
- if URL is invalid or unsupportedImage(java.lang.String, java.io.InputStream, double, double, boolean, boolean, boolean)
public Image(String url, boolean backgroundLoading)
Image
with the specified parameters.url
- the string representing the URL to use in fetching the pixel
databackgroundLoading
- indicates whether the image
is being loaded in the backgroundNullPointerException
- if URL is nullIllegalArgumentException
- if URL is invalid or unsupportedImage(java.lang.String, java.io.InputStream, double, double, boolean, boolean, boolean)
public Image(String url, double requestedWidth, double requestedHeight, boolean preserveRatio, boolean smooth)
Image
with the specified parameters.url
- the string representing the URL to use in fetching the pixel
datarequestedWidth
- the image's bounding box widthrequestedHeight
- the image's bounding box heightpreserveRatio
- indicates whether to preserve the aspect ratio of
the original image when scaling to fit the image within the
specified bounding boxsmooth
- indicates whether to use a better quality filtering
algorithm or a faster one when scaling this image to fit within
the specified bounding boxNullPointerException
- if URL is nullIllegalArgumentException
- if URL is invalid or unsupportedImage(java.lang.String, java.io.InputStream, double, double, boolean, boolean, boolean)
public Image(String url, double requestedWidth, double requestedHeight, boolean preserveRatio, boolean smooth, boolean backgroundLoading)
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()
url
- the string representing the URL to use in fetching the pixel
datarequestedWidth
- the image's bounding box widthrequestedHeight
- the image's bounding box heightpreserveRatio
- indicates whether to preserve the aspect ratio of
the original image when scaling to fit the image within the
specified bounding boxsmooth
- indicates whether to use a better quality filtering
algorithm or a faster one when scaling this image to fit within
the specified bounding boxbackgroundLoading
- indicates whether the image
is being loaded in the backgroundNullPointerException
- if URL is nullIllegalArgumentException
- if URL is invalid or unsupportedpublic Image(InputStream is)
Image
with content loaded from the specified
input stream.is
- the stream from which to load the imageNullPointerException
- if input stream is nullpublic Image(InputStream is, double requestedWidth, double requestedHeight, boolean preserveRatio, boolean smooth)
Image
with the specified parameters.is
- the stream from which to load the imagerequestedWidth
- the image's bounding box widthrequestedHeight
- the image's bounding box heightpreserveRatio
- indicates whether to preserve the aspect ratio of
the original image when scaling to fit the image within the
specified bounding boxsmooth
- indicates whether to use a better quality filtering
algorithm or a faster one when scaling this image to fit within
the specified bounding boxNullPointerException
- if input stream is nullpublic final double getProgress()
public final ReadOnlyDoubleProperty progressProperty()
getProgress()
public final double getRequestedWidth()
<= 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.public final double getRequestedHeight()
<= 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.public final double getWidth()
0
if the image loading fails. While the image
is being loaded it is set to 0
.public final ReadOnlyDoubleProperty widthProperty()
0
if the image loading fails. While the image
is being loaded it is set to 0
.getWidth()
public final double getHeight()
0
if the image loading fails. While the image
is being loaded it is set to 0
.public final ReadOnlyDoubleProperty heightProperty()
0
if the image loading fails. While the image
is being loaded it is set to 0
.getHeight()
public final boolean isPreserveRatio()
width
and height
.
If set to true
, it affects the dimensions of this Image
in the following way:
width
is set, height is scaled to preserve ratio
height
is set, width is scaled to preserve ratio
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:
width
is set, the image's width is scaled to
match and height is unchanged;
height
is set, the image's height is scaled to
match and height is unchanged;
width
and height
.public final boolean isSmooth()
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.
width
and height
.public final boolean isBackgroundLoading()
public final boolean isError()
public final ReadOnlyBooleanProperty errorProperty()
isError()
public final Exception getException()
error
property is set to true
.public final ReadOnlyObjectProperty<Exception> exceptionProperty()
error
property is set to true
.getException()
public void cancel()
Has no effect if this image isn't loaded in background or if loading has already completed.
public final PixelReader getPixelReader()
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.PixelReader
for reading the pixel data of the imageSubmit 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.