public class Image
extends java.lang.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 |
---|---|
(package private) <any> |
acc_platformImage |
ReadOnlyBooleanProperty |
error
Indicates whether an error was detected while loading an image.
|
<any> |
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. |
Modifier and Type | Class and Description |
---|---|
private static class |
Image.Animation |
private class |
Image.DoublePropertyImpl |
private class |
Image.ImageTask |
private class |
Image.ObjectPropertyImpl<T> |
Modifier and Type | Field and Description |
---|---|
private Image.Animation |
animation |
private PlatformImage[] |
animFrames |
private boolean |
backgroundLoading
Indicates whether the image is being loaded in the background.
|
private Image.ImageTask |
backgroundTask |
private ReadOnlyBooleanWrapper |
error
Indicates whether an error was detected while loading an image.
|
private <any> |
exception
The exception which caused image loading to fail.
|
private Image.DoublePropertyImpl |
height
The image height or
0 if the image loading fails. |
private java.io.InputStream |
inputSource |
private static int |
MAX_RUNNING_TASKS |
private static java.util.Queue<Image.ImageTask> |
pendingTasks |
private Image.ObjectPropertyImpl<PlatformImage> |
platformImage |
private boolean |
preserveRatio
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 . |
private ReadOnlyDoubleWrapper |
progress
The approximate percentage of image's loading that
has been completed.
|
private PixelReader |
reader |
private double |
requestedHeight
The height of the bounding box within which the source image is
resized as necessary to fit.
|
private double |
requestedWidth
The width of the bounding box within which the source image is
resized as necessary to fit.
|
private static int |
runningTasks |
private boolean |
smooth
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 . |
private java.lang.String |
url
The string representing the URL to use in fetching the pixel data.
|
private static java.util.regex.Pattern |
URL_QUICKMATCH |
private Image.DoublePropertyImpl |
width
The image width or
0 if the image loading fails. |
Modifier | Constructor and Description |
---|---|
|
Image(java.io.InputStream is)
Construct an
Image with content loaded from the specified
input stream. |
|
Image(java.io.InputStream is,
double requestedWidth,
double requestedHeight,
boolean preserveRatio,
boolean smooth)
Construct a new
Image with the specified parameters. |
(package private) |
Image(int width,
int height)
Package private internal constructor used only by
WritableImage . |
private |
Image(java.lang.Object externalImage) |
|
Image(java.lang.String url)
Constructs an
Image with content loaded from the specified
url. |
|
Image(java.lang.String url,
boolean backgroundLoading)
Construct a new
Image with the specified parameters. |
|
Image(java.lang.String url,
double requestedWidth,
double requestedHeight,
boolean preserveRatio,
boolean smooth)
Construct a new
Image with the specified parameters. |
|
Image(java.lang.String url,
double requestedWidth,
double requestedHeight,
boolean preserveRatio,
boolean smooth,
boolean backgroundLoading)
Construct a new
Image with the specified parameters. |
private |
Image(java.lang.String url,
java.io.InputStream is,
double requestedWidth,
double requestedHeight,
boolean preserveRatio,
boolean smooth,
boolean backgroundLoading) |
Modifier and Type | Method and Description |
---|---|
(package private) <any> |
acc_platformImageProperty() |
void |
cancel()
Cancels the background loading of this image.
|
private static java.lang.String |
constructDetailedExceptionMessage(java.lang.String mainMessage,
java.lang.Throwable cause) |
private void |
cycleTasks() |
(package private) void |
dispose() |
ReadOnlyBooleanProperty |
errorProperty()
Indicates whether an error was detected while loading an image.
|
private ReadOnlyBooleanWrapper |
errorPropertyImpl() |
<any> |
exceptionProperty()
The exception which caused image loading to fail.
|
private <any> |
exceptionPropertyImpl() |
private void |
finishImage(ImageLoader loader) |
(package private) static Image |
fromPlatformImage(java.lang.Object image) |
java.lang.Exception |
getException()
Gets the value of the property exception.
|
double |
getHeight()
Gets the value of the property height.
|
(package private) java.io.InputStream |
getInputSource() |
PixelReader |
getPixelReader()
This method returns a
PixelReader that provides access to
read the pixels of the image, if the image is readable. |
(package private) java.lang.Object |
getPlatformImage() |
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.
|
java.lang.String |
getUrl()
Returns the url used to fetch the pixel data contained in the Image instance,
if specified in the constructor.
|
double |
getWidth()
Gets the value of the property width.
|
(package private) PlatformImage |
getWritablePlatformImage() |
ReadOnlyDoubleProperty |
heightProperty()
The image height or
0 if the image loading fails. |
private Image.DoublePropertyImpl |
heightPropertyImpl() |
private void |
initialize(java.lang.Object externalImage) |
private void |
initializeAnimatedImage(ImageLoader loader) |
(package private) boolean |
isAnimation()
Indicates whether image is animated.
|
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 . |
private static ImageLoader |
loadImage(java.io.InputStream stream,
double width,
double height,
boolean preserveRatio,
boolean smooth) |
private static ImageLoader |
loadImage(java.lang.String url,
double width,
double height,
boolean preserveRatio,
boolean smooth) |
private static AsyncOperation |
loadImageAsync(<any> listener,
java.lang.String url,
double width,
double height,
boolean preserveRatio,
boolean smooth) |
private void |
loadInBackground() |
private static ImageLoader |
loadPlatformImage(java.lang.Object platformImage) |
(package private) void |
pixelsDirty() |
(package private) boolean |
pixelsReadable() |
private Image.ObjectPropertyImpl<PlatformImage> |
platformImagePropertyImpl() |
ReadOnlyDoubleProperty |
progressProperty()
The approximate percentage of image's loading that
has been completed.
|
private ReadOnlyDoubleWrapper |
progressPropertyImpl() |
private void |
setError(boolean value) |
private void |
setException(java.lang.Exception value) |
(package private) void |
setPlatformImage(PlatformImage newPlatformImage) |
private void |
setPlatformImageWH(PlatformImage newPlatformImage,
double newWidth,
double newHeight) |
(package private) void |
setProgress(double value)
This is package private *only* for the sake of testing.
|
private void |
storePlatformImageWH(PlatformImage platformImage,
double width,
double height) |
private static java.io.InputStream |
validateInputStream(java.io.InputStream inputStream) |
private static java.lang.String |
validateUrl(java.lang.String url) |
ReadOnlyDoubleProperty |
widthProperty()
The image width or
0 if the image loading fails. |
private Image.DoublePropertyImpl |
widthPropertyImpl() |
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 <any> exceptionProperty
error
property is set to true
.getException()
final <any> acc_platformImageProperty
private static final java.util.regex.Pattern URL_QUICKMATCH
private final java.lang.String url
private final java.io.InputStream inputSource
private ReadOnlyDoubleWrapper progress
private final double requestedWidth
<= 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.private final double requestedHeight
<= 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.
private Image.DoublePropertyImpl width
0
if the image loading fails. While the image
is being loaded it is set to 0
.private Image.DoublePropertyImpl height
0
if the image loading fails. While the image
is being loaded it is set to 0
.private final boolean preserveRatio
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;
private final boolean smooth
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.
private final boolean backgroundLoading
private ReadOnlyBooleanWrapper error
private <any> exception
error
property is set to true
.private Image.ObjectPropertyImpl<PlatformImage> platformImage
private Image.ImageTask backgroundTask
private Image.Animation animation
private PlatformImage[] animFrames
private static final int MAX_RUNNING_TASKS
private static int runningTasks
private static final java.util.Queue<Image.ImageTask> pendingTasks
private PixelReader reader
public Image(java.lang.String url)
Image
with content loaded from the specified
url.url
- the string representing the URL to use in fetching the pixel
datajava.lang.NullPointerException
- if URL is nulljava.lang.IllegalArgumentException
- if URL is invalid or unsupportedpublic Image(java.lang.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 backgroundjava.lang.NullPointerException
- if URL is nulljava.lang.IllegalArgumentException
- if URL is invalid or unsupportedpublic Image(java.lang.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 boxjava.lang.NullPointerException
- if URL is nulljava.lang.IllegalArgumentException
- if URL is invalid or unsupportedpublic Image(java.lang.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 backgroundjava.lang.NullPointerException
- if URL is nulljava.lang.IllegalArgumentException
- if URL is invalid or unsupportedpublic Image(java.io.InputStream is)
Image
with content loaded from the specified
input stream.is
- the stream from which to load the imagejava.lang.NullPointerException
- if input stream is nullpublic Image(java.io.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 boxjava.lang.NullPointerException
- if input stream is nullImage(int width, int height)
WritableImage
.
The dimensions must both be positive numbers (> 0)
.width
- the width of the empty imageheight
- the height of the empty imagejava.lang.IllegalArgumentException
- if either dimension is negative or zero.private Image(java.lang.Object externalImage)
private Image(java.lang.String url, java.io.InputStream is, double requestedWidth, double requestedHeight, boolean preserveRatio, boolean smooth, boolean backgroundLoading)
public final java.lang.String getUrl()
InputStream
), this method will return null.final java.io.InputStream getInputSource()
final void setProgress(double value)
value
- should be 0-1.public final double getProgress()
public final ReadOnlyDoubleProperty progressProperty()
getProgress()
private ReadOnlyDoubleWrapper progressPropertyImpl()
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()
public final ReadOnlyDoubleProperty widthProperty()
0
if the image loading fails. While the image
is being loaded it is set to 0
.getWidth()
private Image.DoublePropertyImpl widthPropertyImpl()
public final double getHeight()
public final ReadOnlyDoubleProperty heightProperty()
0
if the image loading fails. While the image
is being loaded it is set to 0
.getHeight()
private Image.DoublePropertyImpl heightPropertyImpl()
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()
private void setError(boolean value)
public final boolean isError()
public final ReadOnlyBooleanProperty errorProperty()
isError()
private ReadOnlyBooleanWrapper errorPropertyImpl()
private void setException(java.lang.Exception value)
public final java.lang.Exception getException()
public final <any> exceptionProperty()
error
property is set to true
.getException()
private <any> exceptionPropertyImpl()
final java.lang.Object getPlatformImage()
final <any> acc_platformImageProperty()
private Image.ObjectPropertyImpl<PlatformImage> platformImagePropertyImpl()
void pixelsDirty()
public void cancel()
Has no effect if this image isn't loaded in background or if loading has already completed.
void dispose()
private void initialize(java.lang.Object externalImage)
private void finishImage(ImageLoader loader)
private void initializeAnimatedImage(ImageLoader loader)
private void cycleTasks()
private void loadInBackground()
static Image fromPlatformImage(java.lang.Object image)
private void setPlatformImageWH(PlatformImage newPlatformImage, double newWidth, double newHeight)
private void storePlatformImageWH(PlatformImage platformImage, double width, double height)
void setPlatformImage(PlatformImage newPlatformImage)
private static ImageLoader loadImage(java.lang.String url, double width, double height, boolean preserveRatio, boolean smooth)
private static ImageLoader loadImage(java.io.InputStream stream, double width, double height, boolean preserveRatio, boolean smooth)
private static AsyncOperation loadImageAsync(<any> listener, java.lang.String url, double width, double height, boolean preserveRatio, boolean smooth)
private static ImageLoader loadPlatformImage(java.lang.Object platformImage)
private static java.lang.String validateUrl(java.lang.String url)
private static java.io.InputStream validateInputStream(java.io.InputStream inputStream)
private static java.lang.String constructDetailedExceptionMessage(java.lang.String mainMessage, java.lang.Throwable cause)
boolean isAnimation()
boolean pixelsReadable()
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 imagePlatformImage getWritablePlatformImage()