Package org.eclipse.jface.resource

Class 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 (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:
    Image

    • Field Detail

      • DEFAULT_IMAGE_DATA

        protected static final ImageData DEFAULT_IMAGE_DATA
        A small red square used to warn that an image cannot be created.

    • Constructor Detail

      • ImageDescriptor

        protected ImageDescriptor()
        Constructs an image descriptor.

    • Method Detail

      • 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

      • 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:
        Image(Device, Image, int)

      • 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

      • imageDescriptorFromURI

        public ImageDescriptor imageDescriptorFromURI​(URI uriIconPath)
        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

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