Package org.eclipse.jface.resource

Class ImageDescriptor

java.lang.Object
org.eclipse.jface.resource.DeviceResourceDescriptor<Image>
org.eclipse.jface.resource.ImageDescriptor
Direct Known Subclasses:
CompositeImageDescriptor
public abstract class ImageDescriptor extends DeviceResourceDescriptor<Image>
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 (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 Details

    • DEFAULT_IMAGE_DATA

      protected static final ImageData 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

      public static ImageDescriptor createFromFile(Class<?> location, String filename)
      Creates and returns a new image descriptor from a file.
      Parameters:
      location - the class whose resource directory contain the file
      filename - the file name
      Returns:
      a new image descriptor

    • createFromImageData

      @Deprecated public static ImageDescriptor createFromImageData(ImageData data)
      Deprecated.
      use createFromImageDataProvider(ImageDataProvider)
      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

      public static ImageDescriptor createFromImageDataProvider(ImageDataProvider provider)
      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

      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:

    • createFromImage

      @Deprecated 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. If the URL requires scanning IO to calculate, consider using createFromURLSupplier(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 returns null, then an image from getMissingImageDescriptor() will be returned if useMissingImage is true, and null otherwise.
      Parameters:
      useMissingImage - if the supplied URL is null, use missing image or null
      supplier - the supplier of the image
      Returns:
      the image descriptor with a deferred lookup of the URL
      Since:
      3.21

    • createFromURI

      public static ImageDescriptor createFromURI(URI uriIconPath)
      Convenient method to create an ImageDescriptor from an URI. Delegates to createFromURL(URL). Important This method should only be used when it's guaranteed that the given URI is also a valid URL, in order to avoid the MalformedURLException thrown by URI.toURL(). If the URI is null or not a valid URL, then an image from getMissingImageDescriptor() will be returned.
      Parameters:
      uriIconPath - The URI of the image file.
      Returns:
      a new image descriptor
      Since:
      3.36

    • imageDescriptorFromURI

      @Deprecated(since="3.36", forRemoval=true) public ImageDescriptor imageDescriptorFromURI(URI uriIconPath)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use createFromURI(URI) instead.
      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

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

      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<Image>
      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 ImageData getImageData(int zoom)
      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 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 public ImageData getImageData()
      Deprecated.
      Use getImageData(int) instead.
      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.

      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

      public static ImageDescriptor getMissingImageDescriptor()
      Returns the shared image descriptor for a missing image.
      Returns:
      the missing image descriptor