Class Image
- All Implemented Interfaces:
Drawable
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.
-
Field Summary
-
Constructor Summary
ConstructorDescriptionConstructs an empty instance of this class with the specified width and height.Image
(Device device, InputStream stream) Constructs an instance of this class by loading its representation from the specified input stream.Constructs an instance of this class by loading its representation from the file with the specified name.Constructs an instance of this class from the givenImageData
.Image
(Device device, ImageDataProvider imageDataProvider) Constructs an instance of this class by loading its representation from the ImageData retrieved from the ImageDataProvider.Constructs an instance of this class, whose type isSWT.ICON
, from the two givenImageData
objects.Image
(Device device, ImageFileNameProvider imageFileNameProvider) Constructs an instance of this class by loading its representation from the file retrieved from the ImageFileNameProvider.Constructs a new instance of this class based on the provided image, with an appearance that varies depending on the value of the flag.Constructs an empty instance of this class with the width and height of the specified rectangle. -
Method Summary
Modifier and TypeMethodDescriptionboolean
Compares the argument to the receiver, and returns true if they represent the same object using a class specific comparison.Returns the color to which to map the transparent pixel, or null if the receiver has no transparent pixel.Returns the bounds of the receiver.Deprecated.This API doesn't serve the purpose in an environment having multiple monitors with different DPIs, hence deprecated.Returns anImageData
based on the receiver.getImageData
(int zoom) Returns anImageData
for the given zoom level based on the receiver.Deprecated.This API doesn't serve the purpose in an environment having multiple monitors with different DPIs, hence deprecated.int
hashCode()
Returns an integer hash code for the receiver.void
internal_dispose_GC
(long hDC, GCData data) Invokes platform specific functionality to dispose a GC handle.long
internal_new_GC
(GCData data) Invokes platform specific functionality to allocate a new GC handle.boolean
Returnstrue
if the image has been disposed, andfalse
otherwise.void
setBackground
(Color color) Sets the color to which to map the transparent pixel.toString()
Returns a string containing a concise, human-readable description of the receiver.static Long
win32_getHandle
(Image image, int zoom) IMPORTANT: This method is not part of the public API for Image.static Image
Invokes platform specific functionality to allocate a new image.Methods inherited from class org.eclipse.swt.graphics.Resource
dispose, getDevice, setNonDisposeHandler
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.eclipse.swt.graphics.Drawable
isAutoScalable
-
Field Details
-
type
public int typespecifies whether the receiver is a bitmap or an icon (one ofSWT.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.
- Restriction:
- This field is not intended to be referenced by clients.
-
handle
public long handlethe handle to the OS image resource (Warning: This field is platform dependent)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.
- Restriction:
- This field is not intended to be referenced by clients.
-
-
Constructor Details
-
Image
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.
You must dispose the image when it is no longer required.
- Parameters:
device
- the device on which to create the imagewidth
- the width of the new imageheight
- 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
- See Also:
-
Image
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
You must dispose the image when it is no longer required.
- Parameters:
device
- the device on which to create the imagesrcImage
- the image to use as the sourceflag
- the style, eitherIMAGE_COPY
,IMAGE_DISABLE
orIMAGE_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
orIMAGE_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
- See Also:
-
Image
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.
You must dispose the image when it is no longer required.
- Parameters:
device
- the device on which to create the imagebounds
- 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
- See Also:
-
Image
Constructs an instance of this class from the givenImageData
.You must dispose the image when it is no longer required.
- Parameters:
device
- the device on which to create the imagedata
- 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
- See Also:
-
Image
Constructs an instance of this class, whose type isSWT.ICON
, from the two givenImageData
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.
You must dispose the image when it is no longer required.
- Parameters:
device
- the device on which to create the iconsource
- the color data for the iconmask
- 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
- See Also:
-
Image
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; }
You must dispose the image when it is no longer required.
- Parameters:
device
- the device on which to create the imagestream
- 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
- See Also:
-
Image
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.
You must dispose the image when it is no longer required.
- Parameters:
device
- the device on which to create the imagefilename
- 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
- See Also:
-
Image
Constructs an instance of this class by loading its representation from the file retrieved from the ImageFileNameProvider. 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 for loading image as per DPI level.
- Parameters:
device
- the device on which to create the imageimageFileNameProvider
- the ImageFileNameProvider object that is to be used to get the file name- Throws:
IllegalArgumentException
-- ERROR_NULL_ARGUMENT - if device is null and there is no current device
- ERROR_NULL_ARGUMENT - if the ImageFileNameProvider is null
- ERROR_INVALID_ARGUMENT - if the fileName provided by ImageFileNameProvider is null at 100% zoom
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
- Since:
- 3.104
-
Image
Constructs an instance of this class by loading its representation from the ImageData retrieved from the ImageDataProvider. 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 for loading image as per DPI level.
- Parameters:
device
- the device on which to create the imageimageDataProvider
- the ImageDataProvider object that is to be used to get the ImageData- Throws:
IllegalArgumentException
-- ERROR_NULL_ARGUMENT - if device is null and there is no current device
- ERROR_NULL_ARGUMENT - if the ImageDataProvider is null
- ERROR_INVALID_ARGUMENT - if the ImageData provided by ImageDataProvider is null at 100% zoom
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
- Since:
- 3.104
-
-
Method Details
-
win32_getHandle
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. Updates zoom and refresh the Image based on the native zoom level, if required.- Parameters:
image
- the image to get the handle ofzoom
- device zoom in % of the monitor on which the image is painted- Returns:
- true if image is refreshed
- Restriction:
- This method is not intended to be referenced by clients.
-
equals
Compares the argument to the receiver, and returns true if they represent the same object using a class specific comparison. -
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
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 in points.
- Throws:
SWTException
-- ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
- ERROR_INVALID_IMAGE - if the image is not a bitmap or an icon
-
getBoundsInPixels
Deprecated.This API doesn't serve the purpose in an environment having multiple monitors with different DPIs, hence deprecated.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 in pixels.- Returns:
- a rectangle specifying the image's bounds in pixels.
- Throws:
SWTException
-- ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
- ERROR_INVALID_IMAGE - if the image is not a bitmap or an icon
- Since:
- 3.105
-
getImageData
Returns anImageData
based on the receiver. Modifications made to thisImageData
will not affect the Image.- Returns:
- an
ImageData
containing the image's data and attributes at 100% zoom level. - 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:
-
getImageData
Returns anImageData
for the given zoom level based on the receiver.Note that this method is mainly intended to be used by custom implementations of
ImageDataProvider
that draw a composite image at the requested zoom level based on other images. For custom zoom levels, the image data may be an auto-scaled version of the native image and may look more blurred or mangled than expected.Modifications made to the returned
ImageData
will not affect thisImage
.- Parameters:
zoom
- The zoom level in % of the standard resolution (which is 1 physical monitor pixel == 1 SWT logical point). Typically 100, 150, or 200.- Returns:
- an
ImageData
containing the image's data and attributes at the given zoom level - Throws:
SWTException
-- ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
- ERROR_INVALID_IMAGE - if the image is not a bitmap or an icon
- Since:
- 3.106
-
getImageDataAtCurrentZoom
Deprecated.This API doesn't serve the purpose in an environment having multiple monitors with different DPIs, hence deprecated. UsegetImageData(int)
instead.Returns anImageData
based on the receiver. Modifications made to thisImageData
will not affect the Image.- Returns:
- an
ImageData
containing the image's data and attributes at the current zoom level. - Throws:
SWTException
-- ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
- ERROR_INVALID_IMAGE - if the image is not a bitmap or an icon
- Since:
- 3.105
- See Also:
-
hashCode
public int hashCode()Returns an integer hash code for the receiver. Any two objects that returntrue
when passed toequals
must return the same value for this method. -
internal_new_GC
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 interfaceDrawable
- Parameters:
data
- the platform specific GC data- Returns:
- the platform specific GC handle
- Restriction:
- This method is not intended to be referenced by clients.
-
internal_dispose_GC
Invokes platform specific functionality to dispose a 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_dispose_GC
in interfaceDrawable
- Parameters:
hDC
- the platform specific GC handledata
- the platform specific GC data- Restriction:
- This method is not intended to be referenced by clients.
-
isDisposed
public boolean isDisposed()Returnstrue
if the image has been disposed, andfalse
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 (except
Resource.dispose()
) using the image.- Specified by:
isDisposed
in classResource
- Returns:
true
when the image is disposed andfalse
otherwise
-
setBackground
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
Returns a string containing a concise, human-readable description of the receiver. -
win32_new
Invokes platform specific functionality to allocate a new image.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.- Parameters:
device
- the device on which to allocate the colortype
- the type of the image (SWT.BITMAP
orSWT.ICON
)handle
- the OS handle for the image- Returns:
- a new image object containing the specified device, type and handle
- Restriction:
- This method is not intended to be referenced by clients.
-