org.eclipse.swt.graphics
Class Image

java.lang.Object
  org.eclipse.swt.graphics.Image

All Implemented Interfaces:

Drawable

public final class Image

extends java.lang.Object

implements Drawable

Instances of this class are graphics which have been prepared for display on a specific device. That is, they are ready to paint using methods such as GC.drawImage() and display on widgets with, for example, Button.setImage().

If loaded from a file format that supports it, an Image may have transparency, meaning that certain pixels are specified as being transparent when drawn. Examples of file formats that support transparency are GIF and PNG.

There are two primary ways to use Images. The first is to load a graphic file from disk and create an Image from it. This is done using an Image constructor, for example:

    Image i = new Image(device, "C:\\graphic.png");
 

A graphic file may contain a color table specifying which colors the image was intended to possess. In the above example, these colors will be mapped to the closest available color in SWT. It is possible to get more control over the mapping of colors as the image is being created, using code of the form:

    ImageData data = new ImageData("C:\\graphic.png"); 
    RGB[] rgbs = data.getRGBs(); 
    // At this point, rgbs contains specifications of all
    // the colors contained within this image. You may
    // allocate as many of these colors as you wish by
    // using the Color constructor Color(RGB), then
    // create the image:
    Image i = new Image(device, data);
 

Application code must explicitely invoke the Image.dispose() method to release the operating system resources managed by each instance when those instances are no longer required.

See Also:

Color, ImageData

Field Summary

int	type specifies whether the receiver is a bitmap or an icon (one of SWT.BITMAP, SWT.ICON)

Constructor Summary

Image(Device device, ImageData data)
Constructs an instance of this class from the given ImageData.

Image(Device device, java.io.InputStream stream)
Constructs an instance of this class by loading its representation from the specified input stream.

Image(Device device, int width, int height)
Constructs an empty instance of this class with the specified width and height.

Image(Device device, Rectangle bounds)
Constructs an empty instance of this class with the width and height of the specified rectangle.

Image(Device device, java.lang.String filename)
Constructs an instance of this class by loading its representation from the file with the specified name.

Method Summary

void	dispose() Disposes of the operating system resources associated with the image.
boolean	equals(java.lang.Object object) Compares the argument to the receiver, and returns true if they represent the same object using a class specific comparison.
Rectangle	getBounds() Returns the bounds of the receiver.
ImageData	getImageData() Returns an ImageData based on the receiver Modifications made to this ImageData will not affect the Image.
int	hashCode() Returns an integer hash code for the receiver.
boolean	isDisposed() Returns true if the image has been disposed, and false otherwise.
java.lang.String	toString() Returns a string containing a concise, human-readable description of the receiver.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

type

public int type

specifies whether the receiver is a bitmap or an icon (one of SWT.BITMAP, SWT.ICON)

Constructor Detail

Image

public Image(Device device,
             int width,
             int height)

Constructs an empty instance of this class with the specified width and height. The result may be drawn upon by creating a GC and using any of its drawing operations, as shown in the following example:

    Image i = new Image(device, width, height);
    GC gc = new GC(i);
    gc.drawRectangle(0, 0, 50, 50);
    gc.dispose();
 

Note: Some platforms may have a limitation on the size of image that can be created (size depends on width, height, and depth). For example, Windows 95, 98, and ME do not allow images larger than 16M.

Parameters:

device - the device on which to create the image

width - the width of the new image

height - the height of the new image

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if device is null and there is no current device
• ERROR_INVALID_ARGUMENT - if either the width or height is negative or zero

SWTError -

• ERROR_NO_HANDLES if a handle could not be obtained for image creation

Image

public Image(Device device,
             Rectangle bounds)

Constructs an empty instance of this class with the width and height of the specified rectangle. The result may be drawn upon by creating a GC and using any of its drawing operations, as shown in the following example:

    Image i = new Image(device, boundsRectangle);
    GC gc = new GC(i);
    gc.drawRectangle(0, 0, 50, 50);
    gc.dispose();
 

Note: Some platforms may have a limitation on the size of image that can be created (size depends on width, height, and depth). For example, Windows 95, 98, and ME do not allow images larger than 16M.

Parameters:

device - the device on which to create the image

bounds - a rectangle specifying the image's width and height (must not be null)

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if device is null and there is no current device
• ERROR_NULL_ARGUMENT - if the bounds rectangle is null
• ERROR_INVALID_ARGUMENT - if either the rectangle's width or height is negative

SWTError -

• ERROR_NO_HANDLES if a handle could not be obtained for image creation

Image

public Image(Device device,
             ImageData data)

Constructs an instance of this class from the given ImageData.

Parameters:

device - the device on which to create the image

data - the image data to create the image from (must not be null)

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if device is null and there is no current device
• ERROR_NULL_ARGUMENT - if the image data is null

SWTException -

• ERROR_UNSUPPORTED_DEPTH - if the depth of the ImageData is not supported

SWTError -

• ERROR_NO_HANDLES if a handle could not be obtained for image creation

Image

public Image(Device device,
             java.io.InputStream stream)

Constructs an instance of this class by loading its representation from the specified input stream. Throws an error if an error occurs while loading the image, or if the result is an image of an unsupported type. Application code is still responsible for closing the input stream.

This constructor may be used to load a resource as follows:

     new Image(device, clazz.getResourceAsStream("file.png"));
 

Parameters:

device - the device on which to create the image

stream - the input stream to load the image from

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if device is null and there is no current device
• ERROR_NULL_ARGUMENT - if the stream is null

SWTException -

• ERROR_INVALID_IMAGE - if the image file contains invalid data
• ERROR_IO - if an IO error occurs while reading data
• ERROR_UNSUPPORTED_DEPTH - if the InputStream describes an image with an unsupported depth
• ERROR_UNSUPPORTED_FORMAT - if the image file contains an unrecognized format
*

SWTError -

• ERROR_NO_HANDLES if a handle could not be obtained for image creation

Image

public Image(Device device,
             java.lang.String filename)

Constructs an instance of this class by loading its representation from the file with the specified name. Throws an error if an error occurs while loading the image, or if the result is an image of an unsupported type. Application code is still responsible for closing the input stream.

This constructor is provided for convenience when loading a single image only. If the specified file contains multiple images, only the first one will be used.

Parameters:

device - the device on which to create the image

filename - the name of the file to load the image from

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if device is null and there is no current device
• ERROR_NULL_ARGUMENT - if the file name is null

SWTException -

• ERROR_INVALID_IMAGE - if the image file contains invalid data
• ERROR_IO - if an IO error occurs while reading data
• ERROR_UNSUPPORTED_DEPTH - if the image file has an unsupported depth
• ERROR_UNSUPPORTED_FORMAT - if the image file contains an unrecognized format

SWTError -

• ERROR_NO_HANDLES if a handle could not be obtained for image creation

Method Detail

dispose

public void dispose()

Disposes of the operating system resources associated with the image. Applications must dispose of all images which they allocate.

equals

public boolean equals(java.lang.Object object)

Compares the argument to the receiver, and returns true if they represent the same object using a class specific comparison.

Parameters:

object - the object to compare with this object

Returns:

true if the object is the same as this object and false otherwise

See Also:

hashCode()

getBounds

public Rectangle getBounds()

Returns the bounds of the receiver. The rectangle will always have x and y values of 0, and the width and height of the image.

Returns:

a rectangle specifying the image's bounds

Throws:

SWTException -

• ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
• ERROR_INVALID_IMAGE - if the image is not a bitmap or an icon

getImageData

public ImageData getImageData()

Returns an ImageData based on the receiver Modifications made to this ImageData will not affect the Image.

Returns:

an ImageData containing the image's data and attributes

Throws:

SWTException -

• ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
• ERROR_INVALID_IMAGE - if the image is not a bitmap or an icon

See Also:

ImageData

hashCode

public int hashCode()

Returns an integer hash code for the receiver. Any two objects that return true when passed to equals must return the same value for this method.

Returns:

the receiver's hash

See Also:

equals(java.lang.Object)

isDisposed

public boolean isDisposed()

Returns true if the image has been disposed, and false otherwise.

This method gets the dispose state for the image. When an image has been disposed, it is an error to invoke any other method using the image.

Returns:

true when the image is disposed and false otherwise

toString

public java.lang.String toString()

Returns a string containing a concise, human-readable description of the receiver.

Returns:

a string representation of the receiver