Eclipse Plug-in Developer Guide (Galileo) - Image (Eclipse Platform API Specification)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse Platform
Release 3.5

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.eclipse.swt.graphics
Class Image


java.lang.Object
  

org.eclipse.swt.graphics.Resource
      
org.eclipse.swt.graphics.Image

All Implemented Interfaces:: Drawable

public final class Image
extends Resource
implements Drawable
extends Resource
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.bmp");

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.bmp"); 
    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);

Applications which require even greater control over the image loading process should use the support provided in class ImageLoader.

Application code must explicitly 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, ImageLoader, Image snippets, SWT Examples: GraphicsExample, ImageAnalyzer, Sample code and further information

Field Summary

int handle
          the handle to the OS image resource (Warning: This field is platform dependent) IMPORTANT: This field is not part of the SWT public API.

int type
          specifies whether the receiver is a bitmap or an icon (one of SWT.BITMAP, SWT.ICON) IMPORTANT: This field is not part of the SWT public API.

Constructor Summary

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

Image ( Device device, ImageData source, ImageData mask)
          Constructs an instance of this class, whose type is SWT.ICON, from the two given ImageData objects.

Image ( Device device, Image srcImage, int flag)
          Constructs a new instance of this class based on the provided image, with an appearance that varies depending on the value of the flag.

Image ( Device device, 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, String filename)
          Constructs an instance of this class by loading its representation from the file with the specified name.

Method Summary

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

Color getBackground ()
          Returns the color to which to map the transparent pixel, or null if the receiver has no transparent pixel.

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.

void internal_dispose_GC (int hDC, GCData data)
          Invokes platform specific functionality to dispose a GC handle.

int internal_new_GC ( GCData data)
          Invokes platform specific functionality to allocate a new GC handle.

boolean isDisposed ()
          Returns true if the image has been disposed, and false otherwise.

void setBackground ( Color color)
          Sets the color to which to map the transparent pixel.

String toString ()
          Returns a string containing a concise, human-readable description of the receiver.

static Image win32_new ( Device device, int type, int handle)
          Invokes platform specific functionality to allocate a new image.

Methods inherited from class org.eclipse.swt.graphics. Resource

dispose, getDevice

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)

IMPORTANT: This field is not part of the SWT public API. It is marked public only so that it can be shared within the packages provided by SWT. It is not available on all platforms and should never be accessed from application code.

handle

public int handle

the handle to the OS image resource (Warning: This field is platform dependent)

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:


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,
             
Image srcImage,
             int flag)

Constructs a new instance of this class based on the provided image, with an appearance that varies depending on the value of the flag. The possible flag values are:

SWT.IMAGE_COPY: the result is an identical copy of srcImage
SWT.IMAGE_DISABLE: the result is a copy of srcImage which has a disabled look
SWT.IMAGE_GRAY: the result is a copy of srcImage which has a gray scale look

Parameters:

device - the device on which to create the image

srcImage - the image to use as the source

flag - the style, either IMAGE_COPY, IMAGE_DISABLE or IMAGE_GRAY

Throws:


IllegalArgumentException

ERROR_NULL_ARGUMENT - if device is null and there is no current device
ERROR_NULL_ARGUMENT - if srcImage is null
ERROR_INVALID_ARGUMENT - if the flag is not one of IMAGE_COPY, IMAGE_DISABLE or IMAGE_GRAY
ERROR_INVALID_ARGUMENT - if the image has been disposed


SWTException

ERROR_INVALID_IMAGE - if the image is not a bitmap or an icon, or is otherwise in an invalid state
ERROR_UNSUPPORTED_DEPTH - if the depth of the image is not supported


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();

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:


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:


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,
             
ImageData source,
             
ImageData mask)

Constructs an instance of this class, whose type is SWT.ICON, from the two given ImageData objects. The two images must be the same size. Pixel transparency in either image will be ignored.

The mask image should contain white wherever the icon is to be visible, and black wherever the icon is to be transparent. In addition, the source image should contain black wherever the icon is to be transparent.

Parameters:

device - the device on which to create the icon

source - the color data for the icon

mask - the mask data for the icon

Throws:


IllegalArgumentException

ERROR_NULL_ARGUMENT - if device is null and there is no current device
ERROR_NULL_ARGUMENT - if either the source or mask is null
ERROR_INVALID_ARGUMENT - if source and mask are different sizes


SWTError

ERROR_NO_HANDLES if a handle could not be obtained for image creation

Image

public Image(
Device device,
             
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 is provided for convenience when loading a single image only. If the stream contains multiple images, only the first one will be loaded. To load multiple images, use ImageLoader.load().

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

     static Image loadImage (Display display, Class clazz, String string) {
          InputStream stream = clazz.getResourceAsStream (string);
          if (stream == null) return null;
          Image image = null;
          try {
               image = new Image (display, stream);
          } catch (SWTException ex) {
          } finally {
               try {
                    stream.close ();
               } catch (IOException ex) {}
          }
          return image;
     }

Parameters:

device - the device on which to create the image

stream - the input stream to load the image from

Throws:


IllegalArgumentException

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


SWTException

ERROR_IO - if an IO error occurs while reading from the stream
ERROR_INVALID_IMAGE - if the image stream contains invalid data
ERROR_UNSUPPORTED_DEPTH - if the image stream describes an image with an unsupported depth
ERROR_UNSUPPORTED_FORMAT - if the image stream contains an unrecognized format


SWTError

ERROR_NO_HANDLES if a handle could not be obtained for image creation

Image

public Image(
Device device,
             
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.

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:


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_IO - if an IO error occurs while reading from the file
ERROR_INVALID_IMAGE - if the image file contains invalid data
ERROR_UNSUPPORTED_DEPTH - if the image file 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

Method Detail

equals

public boolean equals(
Object object)

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

Overrides:: equals in class Object

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()

getBackground

public 
Color getBackground()

Returns the color to which to map the transparent pixel, or null if the receiver has no transparent pixel.

There are certain uses of Images that do not support transparency (for example, setting an image into a button or label). In these cases, it may be desired to simulate transparency by using the background color of the widget to paint the transparent pixels of the image. Use this method to check which color will be used in these cases in place of transparency. This value may be set with setBackground().

Returns:

the background color of the image, or null if there is no transparency in the image

Throws:


SWTException

ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

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.

Overrides:: hashCode in class Object

Returns:: the receiver's hash
See Also:: equals(java.lang.Object)

internal_new_GC

public int internal_new_GC(
GCData data)

Invokes platform specific functionality to allocate a new GC handle.

IMPORTANT: This method is not part of the public API for Image. It is marked public only so that it can be shared within the packages provided by SWT. It is not available on all platforms, and should never be called from application code.

Specified by:: internal_new_GC in interface Drawable

Parameters:: data - the platform specific GC data
Returns:: the platform specific GC handle

internal_dispose_GC

public void internal_dispose_GC(int hDC,
                                
GCData data)

Invokes platform specific functionality to dispose a GC handle.

Specified by:: internal_dispose_GC in interface Drawable

Parameters:: hDC - the platform specific GC handle; data - the platform specific GC data

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.

Specified by:: isDisposed in class Resource

Returns:: true when the image is disposed and false otherwise

setBackground

public void setBackground(
Color color)

Sets the color to which to map the transparent pixel.

There are certain uses of Images that do not support transparency (for example, setting an image into a button or label). In these cases, it may be desired to simulate transparency by using the background color of the widget to paint the transparent pixels of the image. This method specifies the color that will be used in these cases. For example:

    Button b = new Button();
    image.setBackground(b.getBackground());
    b.setImage(image);

The image may be modified by this operation (in effect, the transparent regions may be filled with the supplied color). Hence this operation is not reversible and it is not legal to call this function twice or with a null argument.

This method has no effect if the receiver does not have a transparent pixel value.

Parameters:

color - the color to use when a transparent pixel is specified

Throws:


IllegalArgumentException

ERROR_NULL_ARGUMENT - if the color is null
ERROR_INVALID_ARGUMENT - if the color has been disposed


SWTException

ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

toString

public 
String toString()

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

Overrides:: toString in class Object

Returns:: a string representation of the receiver

win32_new

public static 
Image win32_new(
Device device,
                              int type,
                              int handle)

Invokes platform specific functionality to allocate a new image.

Parameters:: device - the device on which to allocate the color; type - the type of the image (SWT.BITMAP or SWT.ICON); handle - the OS handle for the image
Returns:: a new image object containing the specified device, type and handle

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse Platform
Release 3.5

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

org.eclipse.swt.graphics Class Image

type

handle

Image

Image

Image

Image

Image

Image

Image

equals

getBackground

getBounds

getImageData

hashCode

internal_new_GC

internal_dispose_GC

isDisposed

setBackground

toString

win32_new

org.eclipse.swt.graphics
Class Image