Package org.eclipse.jface.resource

## Class CompositeImageDescriptor

- java.lang.Object
- - org.eclipse.jface.resource.DeviceResourceDescriptor
  - - org.eclipse.jface.resource.ImageDescriptor
    - - org.eclipse.jface.resource.CompositeImageDescriptor

Direct Known Subclasses:
  `DecorationOverlayIcon`

    public abstract class CompositeImageDescriptor
    extends ImageDescriptor

Abstract base class for image descriptors that synthesize an image from other images in order to simulate the effect of custom drawing. For example, this could be used to superimpose a red bar dexter symbol across an image to indicate that something was disallowed.

Subclasses must implement `getSize()` and `drawImage(ImageDataProvider, int, int)`. Little or no work happens until the image descriptor's image is actually requested by a call to `createImage` (or to `getImageData` directly).

See Also:
  `DecorationOverlayIcon`

### Nested Class Summary

Nested Classes
`protected class` `CompositeImageDescriptor.CachedImageDataProvider` An `ImageDataProvider` that caches the most recently returned `ImageData` object.

### Field Summary

### Fields inherited from class org.eclipse.jface.resource.ImageDescriptor

`DEFAULT_IMAGE_DATA`

### Constructor Summary

Constructors
`protected` `CompositeImageDescriptor()` Constructs an uninitialized composite image.

### Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
`protected int` `autoScaleDown​(int pixels)` Converts a value in high-DPI pixels to the corresponding value in SWT points.
`protected int` `autoScaleUp​(int points)` Converts a value in SWT points to the corresponding value in high-DPI pixels.
`protected CompositeImageDescriptor.CachedImageDataProvider` `createCachedImageDataProvider​(ImageDescriptor imageDescriptor)` Creates a new `CompositeImageDescriptor.CachedImageDataProvider` that is backed by the given image descriptor.
`protected CompositeImageDescriptor.CachedImageDataProvider` `createCachedImageDataProvider​(Image image)` Creates a new `CompositeImageDescriptor.CachedImageDataProvider` that is backed by the given image.
`protected abstract void` `drawCompositeImage​(int width, int height)` Draw the composite images.
`protected void` `drawImage​(ImageData src, int ox, int oy)` Deprecated. Use `drawImage(ImageDataProvider, int, int)` instead.
`protected void` `drawImage​(ImageDataProvider srcProvider, int ox, int oy)` Draws the given source image data into this composite image at the given position.
`ImageData` `getImageData()` Deprecated. Use `getImageData(int)` instead.
`ImageData` `getImageData​(int zoom)` Creates and returns a new SWT `ImageData` object for this image descriptor.
`protected abstract Point` `getSize()` Return the size of this composite image.
`protected int` `getTransparentPixel()` Return the transparent pixel for the receiver.
`protected int` `getZoomLevel()` Returns the current zoom level.
`protected void` `setImageData​(ImageData imageData)` Deprecated. This method doesn't make sense and should never have been made API.
`protected boolean` `supportsZoomLevel​(int zoom)` Returns whether the given zoom level is supported by this CompositeImageDescriptor.

### Methods inherited from class org.eclipse.jface.resource.ImageDescriptor

`createFromFile, createFromImage, createFromImage, createFromImageData, createFromImageDataProvider, createFromURL, createImage, createImage, createImage, createImage, createResource, createWithFlags, destroyResource, getMissingImageDescriptor`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### CompositeImageDescriptor

    protected CompositeImageDescriptor()

Constructs an uninitialized composite image.

### Method Detail

#### drawCompositeImage

    protected abstract void drawCompositeImage​(int width,
                                               int height)

Draw the composite images.

Subclasses must implement this framework method to paint images within the given bounds using one or more calls to the `drawImage(ImageDataProvider, int, int)` framework method.

Implementers that need to perform computations based on the size of another image are advised to use one of the `createCachedImageDataProvider(org.eclipse.swt.graphics.Image)` methods to create a `CompositeImageDescriptor.CachedImageDataProvider` that can serve as `ImageDataProvider`. The `CompositeImageDescriptor.CachedImageDataProvider` offers other interesting methods like `getWidth()` or `computeInPoints(...)` that can be useful to compute values in points, based on the resolution-dependent `ImageData` that is applicable for the current drawing operation.

Parameters:
  `width` - the width
  `height` - the height
See Also:
  `drawImage(ImageDataProvider, int, int)`, `createCachedImageDataProvider(Image)`, `createCachedImageDataProvider(ImageDescriptor)`

#### drawImage

    @Deprecated
    protected final void drawImage​(ImageData src,
                                   int ox,
                                   int oy)

Deprecated.
Use `drawImage(ImageDataProvider, int, int)` instead. Replace the code that created the ImageData by calls to `createCachedImageDataProvider(Image)` or `createCachedImageDataProvider(ImageDescriptor)` and then pass on that provider instead of ImageData objects. Replace references to `ImageData.width`/height by calls to `CompositeImageDescriptor.CachedImageDataProvider.getWidth()`/getHeight().
Draws the given source image data into this composite image at the given position.

Call this internal framework method to superimpose another image atop this composite image.

Parameters:
  `src` - the source image data
  `ox` - the x position
  `oy` - the y position

#### drawImage

    protected final void drawImage​(ImageDataProvider srcProvider,
                                   int ox,
                                   int oy)

Draws the given source image data into this composite image at the given position.

Subclasses call this framework method to superimpose another image atop this composite image. This method must only be called within the dynamic scope of a call to `drawCompositeImage(int, int)`.

Hint: Use `createCachedImageDataProvider(Image)` or `createCachedImageDataProvider(ImageDescriptor)` to create an `ImageDataProvider`. To calculate the width and height of the image that is about to be drawn, you can use `CompositeImageDescriptor.CachedImageDataProvider.getWidth()`/getHeight(). These methods already return values in SWT points, so that your code doesn't have to deal with device-dependent pixel coordinates.

Parameters:
  `srcProvider` - the source image data provider
  `ox` - the x position
  `oy` - the y position
Since:
  3.13

#### getImageData

    @Deprecated
    public ImageData getImageData()

Deprecated.
Use `getImageData(int)` instead.
Description copied from class: `ImageDescriptor`
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 `ImageDescriptor.getImageData(int)` instead.

Overrides:
  `getImageData` in class `ImageDescriptor`
Returns:
  a new image data or `null`

#### getImageData

    public ImageData getImageData​(int zoom)

Description copied from class: `ImageDescriptor`
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 `ImageDescriptor.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.

Overrides:
  `getImageData` in class `ImageDescriptor`
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`

#### getTransparentPixel

    protected int getTransparentPixel()

Return the transparent pixel for the receiver. NOTE This value is not currently in use in the default implementation.

Returns:
  int
Since:
  3.3

#### getSize

    protected abstract Point getSize()

Return the size of this composite image.

Subclasses must implement this framework method.

Returns:
  the x and y size of the image expressed as a point object

#### setImageData

    @Deprecated
    protected void setImageData​(ImageData imageData)

Deprecated.
This method doesn't make sense and should never have been made API.
Do not call this method! Behavior is unspecified.

Parameters:
  `imageData` - unspecified
Since:
  3.3

#### supportsZoomLevel

    protected boolean supportsZoomLevel​(int zoom)

Returns whether the given zoom level is supported by this CompositeImageDescriptor.

Parameters:
  `zoom` - the zoom level
Returns:
  whether the given zoom level is supported. Must return true for `zoom == 100`.
Since:
  3.13

#### getZoomLevel

    protected int getZoomLevel()

Returns the current zoom level.

Important: This method must only be called within the dynamic scope of a call to `drawCompositeImage(int, int)`.

Returns:
  The zoom level in % of the standard resolution (which is 1 physical monitor pixel == 1 SWT logical point). Typically 100, 150, or 200.
Since:
  3.13

#### autoScaleDown

    protected int autoScaleDown​(int pixels)

Converts a value in high-DPI pixels to the corresponding value in SWT points.

This method must only be called within the dynamic scope of a call to `drawCompositeImage(int, int)`.

Parameters:
  `pixels` - a value in high-DPI pixels
Returns:
  corresponding value in SWT points
Since:
  3.13

#### autoScaleUp

    protected int autoScaleUp​(int points)

Converts a value in SWT points to the corresponding value in high-DPI pixels.

This method must only be called within the dynamic scope of a call to `drawCompositeImage(int, int)`.

Parameters:
  `points` - a value in SWT points
Returns:
  corresponding value in high-DPI pixels
Since:
  3.13

#### createCachedImageDataProvider

    protected CompositeImageDescriptor.CachedImageDataProvider createCachedImageDataProvider​(Image image)

Creates a new `CompositeImageDescriptor.CachedImageDataProvider` that is backed by the given image. This method and the resulting cached image data provider are only intended to be used within the dynamic scope of a call to `drawCompositeImage(int, int)`.

Parameters:
  `image` - the image, must not be null
Returns:
  the new cached image provider
Since:
  3.13

#### createCachedImageDataProvider

    protected CompositeImageDescriptor.CachedImageDataProvider createCachedImageDataProvider​(ImageDescriptor imageDescriptor)

Creates a new `CompositeImageDescriptor.CachedImageDataProvider` that is backed by the given image descriptor. This method and the resulting cached image data provider are only intended to be used within the dynamic scope of a call to `drawCompositeImage(int, int)`.

The provider returns `ImageDescriptor.getMissingImageDescriptor()` if the image descriptor unexpectedly provides a null image data at zoom == 100.

Parameters:
  `imageDescriptor` - the image descriptor, must not be null
Returns:
  the new cached image provider
Since:
  3.13