Class WritableImage

java.lang.Object

javafx.scene.image.Image

javafx.scene.image.WritableImage

public class WritableImage
extends Image

The WritableImage class represents a custom graphical image that is constructed from pixels supplied by the application, and possibly from PixelReader objects from any number of sources, including images read from a file or URL.

Since:

JavaFX 2.2

Property Summary

Properties declared in class Image

error, exception, height, progress, width

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

Constructor Summary

Constructors

Constructor	Description
WritableImage(int width, int height)	Constructs an empty image of the specified dimensions.
WritableImage(PixelBuffer<? extends Buffer> pixelBuffer)	Constructs a WritableImage using the specified PixelBuffer.
WritableImage(PixelReader reader, int width, int height)	Constructs an image of the specified dimensions, initialized from the indicated PixelReader.
WritableImage(PixelReader reader, int x, int y, int width, int height)	Constructs an image of the specified dimensions, initialized from the indicated region of the PixelReader.

Method Summary

Modifier and Type	Method	Description
final PixelWriter	getPixelWriter()	This method returns a PixelWriter that provides access to write the pixels of the image.

Methods declared in class Image

cancel, errorProperty, exceptionProperty, getException, getHeight, getPixelReader, getProgress, getRequestedHeight, getRequestedWidth, getUrl, getWidth, heightProperty, isBackgroundLoading, isError, isPreserveRatio, isSmooth, progressProperty, widthProperty

Modifier and Type	Method	Description
void	cancel()	Cancels the background loading of this image.
final ReadOnlyBooleanProperty	errorProperty()	Indicates whether an error was detected while loading an image.
final ReadOnlyObjectProperty<Exception>	exceptionProperty()	The exception which caused image loading to fail.
final Exception	getException()	Gets the value of the exception property.
final double	getHeight()	Gets the value of the height property.
final PixelReader	getPixelReader()	This method returns a PixelReader that provides access to read the pixels of the image, if the image is readable.
final double	getProgress()	Gets the value of the progress property.
final double	getRequestedHeight()	Gets the height of the bounding box within which the source image is resized as necessary to fit.
final double	getRequestedWidth()	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 the width property.
final ReadOnlyDoubleProperty	heightProperty()	The image height or 0 if the image loading fails.
final boolean	isBackgroundLoading()	Indicates whether the image is being loaded in the background.
final boolean	isError()	Gets the value of the error property.
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.
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.
final ReadOnlyDoubleProperty	progressProperty()	The approximate percentage of image's loading that has been completed.
final ReadOnlyDoubleProperty	widthProperty()	The image width or 0 if the image loading fails.

Methods declared in class Object

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

Constructor Details

WritableImage

public WritableImage(int width,
 int height)

Constructs an empty image of the specified dimensions. The image will initially be filled with transparent pixels. Images constructed this way will always be readable and writable so the corresponding getPixelReader() and getPixelWriter() will always return valid objects. The dimensions must both be positive numbers (> 0).

Parameters:

width - the desired width of the writable image

height - the desired height of the desired image

Throws:

IllegalArgumentException - if either dimension is negative or zero.

WritableImage

public WritableImage(PixelBuffer<? extends Buffer> pixelBuffer)

Constructs a WritableImage using the specified PixelBuffer. The Buffer provided by the PixelBuffer will be used directly as the pixel data for this image. The PixelBuffer can be shared by multiple WritableImages. Images constructed this way are readable using Image.getPixelReader(), but are not writable using WritableImage.getPixelWriter().

Parameters:

pixelBuffer - the PixelBuffer used to construct this image

Throws:

NullPointerException - if pixelBuffer is null

Since:

13

WritableImage

public WritableImage(PixelReader reader,
 int width,
 int height)

Constructs an image of the specified dimensions, initialized from the indicated PixelReader. The image will initially be filled with data returned from the PixelReader. If the PixelReader accesses a surface that does not contain the necessary number of pixel rows and columns then an ArrayIndexOutOfBoundsException will be thrown. Images constructed this way will always be readable and writable so the corresponding getPixelReader() and getPixelWriter() will always return valid objects. The dimensions must both be positive numbers (> 0).

Parameters:

reader - the PixelReader to construct from

width - the desired width of the writable image and the width of the region to be read from the reader

height - the desired height of the desired image and the width of the region to be read from the reader

Throws:

ArrayIndexOutOfBoundsException - if the reader does not access a surface of at least the requested dimensions

IllegalArgumentException - if either dimension is negative or zero.

WritableImage

public WritableImage(PixelReader reader,
 int x,
 int y,
 int width,
 int height)

Constructs an image of the specified dimensions, initialized from the indicated region of the PixelReader. The image will initially be filled with data returned from the PixelReader for the specified region. If the PixelReader accesses a surface that does not contain the necessary number of pixel rows and columns then an ArrayIndexOutOfBoundsException will be thrown. Images constructed this way will always be readable and writable so the corresponding getPixelReader() and getPixelWriter() will always return valid objects. The dimensions must both be positive numbers (> 0).

Parameters:

reader - the PixelReader to construct from

x - the X coordinate of the upper left corner of the region to read from the reader

y - the Y coordinate of the upper left corner of the region to read from the reader

width - the desired width of the writable image and the width of the region to be read from the reader

height - the desired height of the desired image and the width of the region to be read from the reader

Throws:

ArrayIndexOutOfBoundsException - if the reader does not access a surface containing at least the indicated region

IllegalArgumentException - if either dimension is negative or zero.

Method Details

getPixelWriter

public final PixelWriter getPixelWriter()

This method returns a PixelWriter that provides access to write the pixels of the image. This method is not supported for images constructed using a PixelBuffer.

Returns:

the PixelWriter for writing pixels to the image

Throws:

UnsupportedOperationException - if this image was created using a PixelBuffer