Class ImageDescriptor
- Direct Known Subclasses:
CompositeImageDescriptor
This package defines a concrete image descriptor implementation
which reads an image from a file (createFromFile(Class, String)
).
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 re-implementing the getImageData(int)
method.
Legacy subclasses that are not HiDPI-aware used to override the
deprecated getImageData()
method. Subclasses must
re-implement exactly one of the getImageData
methods
and they should not re-implement both.
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:
-
Field Summary
Modifier and TypeFieldDescriptionprotected static final ImageData
A small red square used to warn that an image cannot be created. -
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionstatic 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) Deprecated.static ImageDescriptor
createFromImageDataProvider
(ImageDataProvider provider) Creates and returns a new image descriptor given an ImageDataProvider describing the image.static ImageDescriptor
createFromURL
(URL url) Creates and returns a new image descriptor from a URL.static ImageDescriptor
createFromURLSupplier
(boolean useMissingImage, Supplier<URL> supplier) Creates and returns a new image descriptor from a supplier of a URL.Creates and returns a new SWT image for this image descriptor.createImage
(boolean returnMissingImageOnError) Creates and returns a new SWT image for this image descriptor.createImage
(boolean returnMissingImageOnError, Device device) Creates and returns a new SWT image for this image descriptor.createImage
(Device device) Creates and returns a new SWT image for this image descriptor.createResource
(Device device) Creates the resource described by this descriptorstatic 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(...).Deprecated.UsegetImageData(int)
instead.getImageData
(int zoom) Creates and returns a new SWTImageData
object for this image descriptor.static ImageDescriptor
Returns the shared image descriptor for a missing image.imageDescriptorFromURI
(URI uriIconPath) Convenient method to create an ImageDescriptor from an URI Delegates to ImageDescriptor createFromURL
-
Field Details
-
DEFAULT_IMAGE_DATA
A small red square used to warn that an image cannot be created.
-
-
Constructor Details
-
ImageDescriptor
protected ImageDescriptor()Constructs an image descriptor.
-
-
Method Details
-
createFromFile
Creates and returns a new image descriptor from a file.- Parameters:
location
- the class whose resource directory contain the filefilename
- the file name- Returns:
- a new image descriptor
-
createFromImageData
Deprecated.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
-
createFromImageDataProvider
Creates and returns a new image descriptor given an ImageDataProvider describing the image.- Parameters:
provider
- contents of the image- Returns:
- newly created image descriptor
- Since:
- 3.13
-
createFromImage
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
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 transformswtFlags
- 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:
-
createFromImage
Deprecated.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 createtheDevice
- the device that was used to create the Image- Returns:
- a newly created image descriptor
- Since:
- 3.1
-
createFromURL
Creates and returns a new image descriptor from a URL. If the URL requires scanning IO to calculate, consider usingcreateFromURLSupplier(boolean,Supplier)
instead.- Parameters:
url
- The URL of the image file.- Returns:
- a new image descriptor
-
createFromURLSupplier
public static ImageDescriptor createFromURLSupplier(boolean useMissingImage, Supplier<URL> supplier) Creates and returns a new image descriptor from a supplier of a URL. The URL will not be calculated until the image data is requested, at which point, the URL supplier will be asked to provide the URL. If the URL supplier returnsnull
, then an image fromgetMissingImageDescriptor()
will be returned ifuseMissingImage
istrue
, andnull
otherwise.- Parameters:
useMissingImage
- if the supplied URL is null, use missing image or nullsupplier
- the supplier of the image- Returns:
- the image descriptor with a deferred lookup of the URL
- Since:
- 3.21
-
imageDescriptorFromURI
Convenient method to create an ImageDescriptor from an URI Delegates to ImageDescriptor createFromURL- Parameters:
uriIconPath
- The URI of the image file.- Returns:
- a new image descriptor
- Since:
- 3.19
-
createResource
Description copied from class:DeviceResourceDescriptor
Creates the resource described by this descriptor- Specified by:
createResource
in classDeviceResourceDescriptor<Image>
- 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
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 classDeviceResourceDescriptor<Image>
- Parameters:
previouslyCreatedObject
- an object that was returned by an equal descriptor in a previous call to createResource(...).
-
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
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 ifreturnMissingImageOnError
is true, otherwisenull
is returned.Note: Even if
returnMissingImageOnError
is true, it is still possible for this method to returnnull
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
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
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 ifreturnMissingImageOnError
is true, otherwisenull
is returned.Note: Even if
returnMissingImageOnError
is true, it is still possible for this method to returnnull
in extreme cases, for example if SWT runs out of image handles.- Parameters:
returnMissingImageOnError
- flag that determines if a default image is returned on errordevice
- 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
Creates and returns a new SWTImageData
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 or if no image data is available for the given zoom level.Since 3.13, subclasses should re-implement this method and should not implement
getImageData()
any more.Warning: This method does not implement
ImageDataProvider.getImageData(int)
, since legal implementations of that method must return a non-null value for zoom == 100.- 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:
- a new image data or
null
- Since:
- 3.13
-
getImageData
Deprecated.UsegetImageData(int)
instead.Creates and returns a new SWTImageData
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.This method was abstract until 3.13. Clients should stop re-implementing this method and should re-implement
getImageData(int)
instead.- Returns:
- a new image data or
null
-
getMissingImageDescriptor
Returns the shared image descriptor for a missing image.- Returns:
- the missing image descriptor
-
createFromImage(Image)