Package org.eclipse.jface.resource

Class CompositeImageDescriptor

java.lang.Object

org.eclipse.jface.resource.DeviceResourceDescriptor<Image>

org.eclipse.jface.resource.ImageDescriptor

org.eclipse.jface.resource.CompositeImageDescriptor

Direct Known Subclasses:

DecorationOverlayIcon, DiffImageDescriptor

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

Modifier and Type	Class	Description
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

Modifier	Constructor	Description
protected	CompositeImageDescriptor()	Constructs an uninitialized composite image.

Method Summary

Modifier and Type	Method	Description
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 final void	drawImage(ImageData src, int ox, int oy)	Deprecated. Use drawImage(ImageDataProvider, int, int) instead.
protected final 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, createFromURLSupplier, createImage, createImage, createImage, createImage, createResource, createWithFlags, destroyResource, getMissingImageDescriptor, imageDescriptorFromURI

Methods inherited from class java.lang.Object

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

Constructor Details

CompositeImageDescriptor

protected CompositeImageDescriptor()

Constructs an uninitialized composite image.

Method Details

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