org.eclipse.jface.resource
Class ImageDescriptor
java.lang.Object
org.eclipse.jface.resource.DeviceResourceDescriptor
org.eclipse.jface.resource.ImageDescriptor
-
Direct Known Subclasses:
-
CompositeImageDescriptor
-
public abstract class ImageDescriptor
- extends
DeviceResourceDescriptor
An image descriptor is an object that knows how to create
an SWT image. It does not hold onto images or cache them,
but rather just creates them on demand. An image descriptor
is intended to be a lightweight representation of an image
that can be manipulated even when no SWT display exists.
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.
-
See Also:
-
Image
|
Constructor Summary
|
protected
|
ImageDescriptor
()
Constructs an image descriptor. |
|
Methods inherited from class java.lang.
Object
|
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
|
DEFAULT_IMAGE_DATA
protected static final
ImageData DEFAULT_IMAGE_DATA
- A small red square used to warn that an image cannot be created.
ImageDescriptor
protected ImageDescriptor()
- Constructs an image descriptor.
createFromFile
public static
ImageDescriptor createFromFile(
Class location,
String filename)
- Creates and returns a new image descriptor from a file.
Convenience method for
new FileImageDescriptor(location,filename).
-
-
Parameters:
-
location - the class whose resource directory contain the file -
filename - the file name
-
Returns:
- a new image descriptor
createFromImageData
public static
ImageDescriptor createFromImageData(
ImageData data)
- Creates and returns a new image descriptor given ImageData
describing the image.
-
-
Parameters:
-
data - contents of the image
-
Returns:
- newly created image descriptor
-
Since:
- 3.1
createFromImage
public static
ImageDescriptor createFromImage(
Image img)
- Creates and returns a new image descriptor for the given image. Note
that disposing the original Image will cause the descriptor to become invalid.
-
-
Parameters:
-
img - image to create
-
Returns:
- a newly created image descriptor
-
Since:
- 3.1
createWithFlags
public static
ImageDescriptor createWithFlags(
ImageDescriptor originalImage,
int swtFlags)
- Creates an ImageDescriptor based on the given original descriptor, but with additional
SWT flags.
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.
-
-
Parameters:
-
originalImage - image to transform -
swtFlags - any flag that can be passed to the flags argument of Image#Image(Device, Image, int)
-
Returns:
- an ImageDescriptor that creates new images by transforming the given image descriptor
-
Since:
- 3.1
-
See Also:
-
Image.Image(Device, Image, int)
createFromImage
public static
ImageDescriptor createFromImage(
Image img,
Device theDevice)
-
Deprecated. use
createFromImage(Image)
- Creates and returns a new image descriptor for the given image. This
method takes the Device that created the Image as an argument, allowing
the original Image to be reused if the descriptor is asked for another
Image on the same device. Note that disposing the original Image will
cause the descriptor to become invalid.
-
-
Parameters:
-
img - image to create -
theDevice - the device that was used to create the Image
-
Returns:
- a newly created image descriptor
-
Since:
- 3.1
createFromURL
public static
ImageDescriptor createFromURL(
URL url)
- Creates and returns a new image descriptor from a URL.
-
-
Parameters:
-
url - The URL of the image file.
-
Returns:
- a new image descriptor
createResource
public
Object createResource(
Device device)
throws
DeviceResourceException
-
Description copied from class:
DeviceResourceDescriptor
- Creates the resource described by this descriptor
-
-
Specified by:
-
createResource
in class
DeviceResourceDescriptor
-
-
Parameters:
-
device - the Device on which to allocate the resource
-
Returns:
- the newly allocated resource (not null)
-
Throws:
-
DeviceResourceException
- if unable to allocate the resource
destroyResource
public void destroyResource(
Object previouslyCreatedObject)
-
Description copied from class:
DeviceResourceDescriptor
- Undoes everything that was done by a previous call to create(...), given
the object that was returned by create(...).
-
-
Specified by:
-
destroyResource
in class
DeviceResourceDescriptor
-
-
Parameters:
-
previouslyCreatedObject - an object that was returned by an equal
descriptor in a previous call to createResource(...).
createImage
public
Image createImage()
- Creates and returns a new SWT image for this image descriptor. Note that
each call returns a new SWT image object. The returned image must be
explicitly disposed using the image's dispose call. The image will not be
automatically garbage collected. A default image is returned in the event
of an error.
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.
-
-
Returns:
- a new image or
null if the image could not be
created
createImage
public
Image createImage(boolean returnMissingImageOnError)
- Creates and returns a new SWT image for this image descriptor. The
returned image must be explicitly disposed using the image's dispose
call. The image will not be automatically garbage collected. In the event
of an error, a default image is returned if
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.
-
-
Parameters:
-
returnMissingImageOnError - flag that determines if a default image is returned on error
-
Returns:
- a new image or
null if the image could not be
created
createImage
public
Image createImage(
Device device)
- Creates and returns a new SWT image for this image descriptor. The
returned image must be explicitly disposed using the image's dispose
call. The image will not be automatically garbage collected. A default
image is returned in the event of an error.
Note: it is still possible for this method to return null
in extreme cases, for example if SWT runs out of image handles.
-
-
Parameters:
-
device - the device on which to create the image
-
Returns:
- a new image or
null if the image could not be
created -
Since:
- 2.0
createImage
public
Image createImage(boolean returnMissingImageOnError,
Device device)
- Creates and returns a new SWT image for this image descriptor. The
returned image must be explicitly disposed using the image's dispose
call. The image will not be automatically garbage collected. In the even
of an error, a default image is returned if
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.
-
-
Parameters:
-
returnMissingImageOnError - flag that determines if a default image is returned on error -
device - the device on which to create the image
-
Returns:
- a new image or
null if the image could not be
created -
Since:
- 2.0
getImageData
public abstract
ImageData getImageData()
- Creates and returns a new SWT
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.
-
-
Returns:
- a new image data or
null
getMissingImageDescriptor
public static
ImageDescriptor getMissingImageDescriptor()
- Returns the shared image descriptor for a missing image.
-
-
Returns:
- the missing image descriptor
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.
