public abstract class ImageDescriptor extends DeviceResourceDescriptor
This package defines a concrete image descriptor implementation
which reads an image from a file (FileImageDescriptor
).
It also provides abstract framework classes (this one and
CompositeImageDescriptor
) which may be subclassed to define
news kinds of image descriptors.
Using this abstract class involves defining a concrete subclass
and providing an implementation for the getImageData
method.
There are two ways to get an Image from an ImageDescriptor. The method createImage will always return a new Image which must be disposed by the caller. Alternatively, createResource() returns a shared Image. When the caller is done with an image obtained from createResource, they must call destroyResource() rather than disposing the Image directly. The result of createResource() can be safely cast to an Image.
Image
Modifier and Type | Field and Description |
---|---|
protected static ImageData |
DEFAULT_IMAGE_DATA
A small red square used to warn that an image cannot be created.
|
Modifier | Constructor and Description |
---|---|
protected |
ImageDescriptor()
Constructs an image descriptor.
|
Modifier and Type | Method and Description |
---|---|
static ImageDescriptor |
createFromFile(Class<?> location,
String filename)
Creates and returns a new image descriptor from a file.
|
static ImageDescriptor |
createFromImage(Image img)
Creates and returns a new image descriptor for the given image.
|
static ImageDescriptor |
createFromImage(Image img,
Device theDevice)
Deprecated.
|
static ImageDescriptor |
createFromImageData(ImageData data)
Creates and returns a new image descriptor given ImageData
describing the image.
|
static ImageDescriptor |
createFromURL(URL url)
Creates and returns a new image descriptor from a URL.
|
Image |
createImage()
Creates and returns a new SWT image for this image descriptor.
|
Image |
createImage(boolean returnMissingImageOnError)
Creates and returns a new SWT image for this image descriptor.
|
Image |
createImage(boolean returnMissingImageOnError,
Device device)
Creates and returns a new SWT image for this image descriptor.
|
Image |
createImage(Device device)
Creates and returns a new SWT image for this image descriptor.
|
Object |
createResource(Device device)
Creates the resource described by this descriptor
|
static ImageDescriptor |
createWithFlags(ImageDescriptor originalImage,
int swtFlags)
Creates an ImageDescriptor based on the given original descriptor, but with additional
SWT flags.
|
void |
destroyResource(Object previouslyCreatedObject)
Undoes everything that was done by a previous call to create(...), given
the object that was returned by create(...).
|
abstract ImageData |
getImageData()
Creates and returns a new SWT
ImageData object
for this image descriptor. |
static ImageDescriptor |
getMissingImageDescriptor()
Returns the shared image descriptor for a missing image.
|
protected static final ImageData DEFAULT_IMAGE_DATA
public static ImageDescriptor createFromFile(Class<?> location, String filename)
new FileImageDescriptor(location,filename)
.location
- the class whose resource directory contain the filefilename
- the file namepublic static ImageDescriptor createFromImageData(ImageData data)
data
- contents of the imagepublic static ImageDescriptor createFromImage(Image img)
img
- image to createpublic static ImageDescriptor createWithFlags(ImageDescriptor originalImage, int swtFlags)
Note that this sort of ImageDescriptor is slower and consumes more resources than a regular image descriptor. It will also never generate results that look as nice as a hand-drawn image. Clients are encouraged to supply their own disabled/grayed/etc. images rather than using a default image and transforming it.
originalImage
- image to transformswtFlags
- any flag that can be passed to the flags argument of Image#Image(Device, Image, int)Image.Image(Device, Image, int)
@Deprecated public static ImageDescriptor createFromImage(Image img, Device theDevice)
createFromImage(Image)
img
- image to createtheDevice
- the device that was used to create the Imagepublic static ImageDescriptor createFromURL(URL url)
url
- The URL of the image file.public Object createResource(Device device) throws DeviceResourceException
DeviceResourceDescriptor
createResource
in class DeviceResourceDescriptor
device
- the Device on which to allocate the resourceDeviceResourceException
- if unable to allocate the resourcepublic void destroyResource(Object previouslyCreatedObject)
DeviceResourceDescriptor
destroyResource
in class DeviceResourceDescriptor
previouslyCreatedObject
- an object that was returned by an equal
descriptor in a previous call to createResource(...).public Image createImage()
Note: this method differs from createResource(Device) in that the returned image must be disposed directly, whereas an image obtained from createResource(...) must be disposed by calling destroyResource(...). It is not possible to mix-and-match. If you obtained the Image from this method, you must not dispose it by calling destroyResource. Clients are encouraged to use create/destroyResource and downcast the result to Image rather than using createImage.
Note: it is still possible for this method to return null
in extreme cases, for example if SWT runs out of image handles.
null
if the image could not be
createdpublic Image createImage(boolean returnMissingImageOnError)
returnMissingImageOnError
is true, otherwise
null
is returned.
Note: Even if returnMissingImageOnError
is true, it is
still possible for this method to return null
in extreme
cases, for example if SWT runs out of image handles.
returnMissingImageOnError
- flag that determines if a default image is returned on errornull
if the image could not be
createdpublic Image createImage(Device device)
Note: it is still possible for this method to return null
in extreme cases, for example if SWT runs out of image handles.
device
- the device on which to create the imagenull
if the image could not be
createdpublic Image createImage(boolean returnMissingImageOnError, Device device)
returnMissingImageOnError
is true, otherwise
null
is returned.
Note: Even if returnMissingImageOnError
is true, it is
still possible for this method to return null
in extreme
cases, for example if SWT runs out of image handles.
returnMissingImageOnError
- flag that determines if a default image is returned on errordevice
- the device on which to create the imagenull
if the image could not be
createdpublic abstract ImageData getImageData()
ImageData
object
for this image descriptor.
Note that each call returns a new SWT image data object.
This framework method is declared public so that it is possible to request an image descriptor's image data without creating an SWT image object.
Returns null
if the image data could not be created.
null
public static ImageDescriptor getMissingImageDescriptor()
Copyright (c) 2000, 2014 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.