- Direct Known Subclasses:
WritableImage
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.
If a URL string is passed to a constructor, it be any of the following:
- the name of a resource that can be resolved by the context
ClassLoader
for this thread - a file path that can be resolved by
File
- a URL that can be resolved by
URL
and for which a protocol handler exists
The RFC 2397 "data" scheme for URLs is supported in addition to
the protocol handlers that are registered for the application.
If a URL uses the "data" scheme, the data must be base64-encoded
and the MIME type must be a subtype of the image
type.
The MIME type must match the image format of the data contained in
the URL. In case of a mismatch between MIME type and image format,
the image will be loaded if the image format can be determined by
JavaFX, and a warning will be logged.
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);
- Since:
- JavaFX 2.0
-
Property Summary
TypePropertyDescriptionfinal ReadOnlyBooleanProperty
Indicates whether an error was detected while loading an image.final ReadOnlyObjectProperty<Exception>
The exception which caused image loading to fail.final ReadOnlyDoubleProperty
The image height or0
if the image loading fails.final ReadOnlyDoubleProperty
The approximate percentage of image's loading that has been completed.final ReadOnlyDoubleProperty
The image width or0
if the image loading fails. -
Constructor Summary
ConstructorDescriptionImage
(InputStream is) Constructs anImage
with content loaded from the specified input stream.Image
(InputStream is, double requestedWidth, double requestedHeight, boolean preserveRatio, boolean smooth) Constructs a newImage
with the specified parameters.Constructs anImage
with content loaded from the specified URL.Constructs anImage
with content loaded from the specified URL using the specified parameters.Image
(String url, double requestedWidth, double requestedHeight, boolean preserveRatio, boolean smooth) Constructs anImage
with content loaded from the specified URL using the specified parameters.Image
(String url, double requestedWidth, double requestedHeight, boolean preserveRatio, boolean smooth, boolean backgroundLoading) Constructs anImage
with content loaded from the specified URL using the specified parameters. -
Method Summary
Modifier and TypeMethodDescriptionvoid
cancel()
Cancels the background loading of this image.final ReadOnlyBooleanProperty
Indicates whether an error was detected while loading an image.final ReadOnlyObjectProperty<Exception>
The exception which caused image loading to fail.final Exception
Gets the value of theexception
property.final double
Gets the value of theheight
property.final PixelReader
This method returns aPixelReader
that provides access to read the pixels of the image, if the image is readable.final double
Gets the value of theprogress
property.final double
Gets the height of the bounding box within which the source image is resized as necessary to fit.final double
Gets the width of the bounding box within which the source image is resized as necessary to fit.final String
getUrl()
Returns the url used to fetch the pixel data contained in the Image instance, if specified in the constructor.final double
getWidth()
Gets the value of thewidth
property.final ReadOnlyDoubleProperty
The image height or0
if the image loading fails.final boolean
Indicates whether the image is being loaded in the background.final boolean
isError()
Gets the value of theerror
property.final boolean
Indicates whether to preserve the aspect ratio of the original image when scaling to fit the image within the bounding box provided bywidth
andheight
.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 bywidth
andheight
.final ReadOnlyDoubleProperty
The approximate percentage of image's loading that has been completed.final ReadOnlyDoubleProperty
The image width or0
if the image loading fails.
-
Property Details
-
progress
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:
-
width
The image width or0
if the image loading fails. While the image is being loaded it is set to0
.- See Also:
-
height
The image height or0
if the image loading fails. While the image is being loaded it is set to0
.- See Also:
-
error
Indicates whether an error was detected while loading an image.- Default value:
- false
- See Also:
-
exception
The exception which caused image loading to fail. Contains a non-null value only if theerror
property is set totrue
.- Since:
- JavaFX 8.0
- See Also:
-
-
Constructor Details
-
Image
Constructs anImage
with content loaded from the specified URL.- Parameters:
url
- a resource path, file path, or URL- Throws:
NullPointerException
- ifurl
is nullIllegalArgumentException
- ifurl
is invalid or unsupported
-
Image
Constructs anImage
with content loaded from the specified URL using the specified parameters.- Parameters:
url
- a resource path, file path, or URLbackgroundLoading
- indicates whether the image is being loaded in the background- Throws:
NullPointerException
- ifurl
is nullIllegalArgumentException
- ifurl
is invalid or unsupported
-
Image
public Image(String url, double requestedWidth, double requestedHeight, boolean preserveRatio, boolean smooth) Constructs anImage
with content loaded from the specified URL using the specified parameters.- Parameters:
url
- a resource path, file path, or URLrequestedWidth
- 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 box- Throws:
NullPointerException
- ifurl
is nullIllegalArgumentException
- ifurl
is invalid or unsupported
-
Image
public Image(String url, double requestedWidth, double requestedHeight, boolean preserveRatio, boolean smooth, boolean backgroundLoading) Constructs anImage
with content loaded from the specified URL using the specified parameters.- Parameters:
url
- a resource path, file path, or URLrequestedWidth
- 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 background- Throws:
NullPointerException
- ifurl
is nullIllegalArgumentException
- ifurl
is invalid or unsupported
-
Image
Constructs anImage
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) Constructs a newImage
with the specified parameters.- 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 box- Throws:
NullPointerException
- if input stream is null
-
-
Method Details
-
getUrl
Returns the url used to fetch the pixel data contained in the Image instance, if specified in the constructor. If no url is provided in the constructor (for instance, if the Image is constructed from anInputStream
), this method will return null.- Returns:
- a String containing the URL used to fetch the pixel data for this Image instance.
- Since:
- 9
-
getProgress
public final double getProgress()Gets the value of theprogress
property.- 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
- Returns:
- the value of the
progress
property - See Also:
-
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
- Returns:
- the
progress
property - See Also:
-
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'srequestedWidth
,requestedHeight
andpreserveRatio
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'srequestedWidth
,requestedHeight
andpreserveRatio
attributes.- Returns:
- The requested height
-
getWidth
public final double getWidth()Gets the value of thewidth
property.- Property description:
- The image width or
0
if the image loading fails. While the image is being loaded it is set to0
. - Returns:
- the value of the
width
property - See Also:
-
widthProperty
The image width or0
if the image loading fails. While the image is being loaded it is set to0
.- Returns:
- the
width
property - See Also:
-
getHeight
public final double getHeight()Gets the value of theheight
property.- Property description:
- The image height or
0
if the image loading fails. While the image is being loaded it is set to0
. - Returns:
- the value of the
height
property - See Also:
-
heightProperty
The image height or0
if the image loading fails. While the image is being loaded it is set to0
.- Returns:
- the
height
property - See Also:
-
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 bywidth
andheight
.If set to
true
, it affects the dimensions of thisImage
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
width
andheight
may be different from the initially set values if they needed to be adjusted to preserve aspect ratio. If unset or set tofalse
, it affects the dimensions of thisImageView
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
andheight
.
- If only
-
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 bywidth
andheight
.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
andheight
.
-
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 theerror
property.- Property description:
- Indicates whether an error was detected while loading an image.
- Default value:
- false
- Returns:
- the value of the
error
property - See Also:
-
errorProperty
Indicates whether an error was detected while loading an image.- Default value:
- false
- Returns:
- the
error
property - See Also:
-
getException
Gets the value of theexception
property.- Property description:
- The exception which caused image loading to fail. Contains a non-null
value only if the
error
property is set totrue
. - Returns:
- the value of the
exception
property - Since:
- JavaFX 8.0
- See Also:
-
exceptionProperty
The exception which caused image loading to fail. Contains a non-null value only if theerror
property is set totrue
.- Returns:
- the
exception
property - Since:
- JavaFX 8.0
- See Also:
-
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
This method returns aPixelReader
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
-