Class ImageUtilities

java.lang.Object

org.openide.util.ImageUtilities

public final class ImageUtilities
extends Object

Useful static methods for manipulation with images/icons, results are cached.

Images can be represented as instances of either Image or Icon. For best results on HiDPI displays, clients should use the image2Icon(Image) method provided by this class when converting an Image to an Icon, rather than constructing ImageIcon instances themselves. When doing manual painting, clients should use Icon.paintIcon(Component, Graphics, int, int) rather than Graphics.drawImage(Image, int, int, ImageObserver).

Since:

7.15

Field Summary

Fields

Modifier and Type	Field	Description
static final String	PROPERTY_URL	Property that holds URL of the image bits.

Method Summary

Modifier and Type	Method	Description
static final Image	addToolTipToImage(Image image, String text)	Add text to tool tip for given image (creates new or returns cached, original remains unmodified).
static final Image	assignToolTipToImage(Image image, String text)	Assign tool tip text to given image (creates new or returns cached, original remains unmodified).
static Icon	createDisabledIcon(Icon icon)	Creates disabled (color saturation lowered) icon.
static Image	createDisabledImage(Image image)	Creates disabled (color saturation lowered) image.
static URL	findImageBaseURL(Image image)	Attempts to find image's URL, if it is defined.
static final String	getImageToolTip(Image image)	Get tool tip text for given image
static final Image	icon2Image(Icon icon)	Converts given icon to a Image.
static final ImageIcon	icon2ImageIcon(Icon icon)	Convert an Icon instance to a delegating ImageIcon instance.
static final Icon	image2Icon(Image image)	Converts given image to an icon.
static final Icon	loadIcon(String resource)	Loads an icon based on a resource path.
static final Icon	loadIcon(String resource, boolean localized)	Loads an icon based on a resource path.
static final Image	loadImage(String resourceID)	Loads an image from the specified resource path.
static final Image	loadImage(String resource, boolean localized)	Loads an image based on a resource path.
static final Image	loadImage(URI uri)	Load an image from a URI/URL.
static final ImageIcon	loadImageIcon(String resource, boolean localized)	Loads an icon based on a resource path.
static final Icon	mergeIcons(Icon icon1, Icon icon2, int x, int y)	This method merges two icons into a new one.
static final Image	mergeImages(Image image1, Image image2, int x, int y)	This method merges two images into the a one.

Methods inherited from class Object

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

Field Details

PROPERTY_URL

public static final String PROPERTY_URL

Property that holds URL of the image bits.

Since:

9.24

See Also:

• Constant Field Values

Method Details

loadImage

public static final Image loadImage(String resourceID)

Loads an image from the specified resource path. The image is loaded using the "system" classloader registered in Lookup.

If the current look and feel is 'dark' (UIManager.getBoolean("nb.dark.theme")) then the method first attempts to load image <original file name>_dark.<original extension>. If such file doesn't exist the default one is loaded instead.

If the default lookup contains a service provider for the SVGLoader interface, and there exists an SVG version of the requested image (e.g. "icon.svg" exists when "icon.png" was requested), the SVG version will be loaded instead of the originally requested bitmap. SVG images can also be requested directly. The SVG document's root element must contain explicit width/height attributes. An SVG loader implementation can be installed via the optional openide.util.ui.svg module.

To paint SVG images at arbitrary resolutions, convert the returned Image to an Icon using image2Icon(Image), and set an appropriate transform on the Graphics2D instance passed to Icon.paintIcon(Component, Graphics, int, int). When painting on HiDPI-capable Graphics2D instances provided by Swing, the appropriate transform will already be in place.

Since version 8.12 the returned image object responds to call image.getProperty(PROPERTY_URL, null) by returning the internal URL of the found and loaded resource. The convenience method findImageBaseURL(Image) should be used in preference to direct property access.

Caching of loaded images can be used internally to improve performance.

Parameters:

resourceID - resource path of the icon (no initial slash)

Returns:

icon's Image, or null, if the icon cannot be loaded.

loadImage

public static final Image loadImage(String resource,
 boolean localized)

Loads an image based on a resource path. Exactly like loadImage(String) but may do a localized search. For example, requesting org/netbeans/modules/foo/resources/foo.gif might actually find org/netbeans/modules/foo/resources/foo_ja.gif or org/netbeans/modules/foo/resources/foo_mybranding.gif.

Parameters:

resource - resource path of the image (no initial slash)

localized - true for localized search

Returns:

the icon's Image, or null if the icon cannot be loaded

loadImage

public static final Image loadImage(URI uri)

Load an image from a URI/URL. If the URI uses the nbresloc or nbres protocols, it is loaded using the resource loading mechanism provided by loadImage(String,boolean), with and without localization, respectively. This includes handling of SVG icons and dark mode variations.

This method is intended for use only when a URL or URI must be used instead of a resource path, e.g. in the implementation of pre-existing NetBeans APIs. External URLs should be avoided, as they may be disallowed in the future. Do not use this method for new code; prefer image loading by resource paths instead (e.g. loadImage(String)).

Parameters:

uri - the URI of the image, possibly with the nbresloc or nbres protocol

Returns:

the loaded image, or either null or an uninitialized image if the image was not available

Since:

7.36

icon2ImageIcon

public static final ImageIcon icon2ImageIcon(Icon icon)

Convert an Icon instance to a delegating ImageIcon instance. If the supplied Icon instance is an SVG icon or has other HiDPI capabilities provided by the methods in this class, they are preserved by the conversion.

This method is intended for use only when existing APIs require the use of ImageIcon. In most other situations it is preferable to use the more general Icon type.

Parameters:

icon - the icon to be converted; may not be null

Returns:

the converted instance

Since:

7.36

loadImageIcon

public static final ImageIcon loadImageIcon(String resource,
 boolean localized)

Loads an icon based on a resource path. Similar to loadImage(String, boolean), but returns ImageIcon instead of Image.

When a general Icon instance can be used rather than more specifically an ImageIcon, it is recommended to use loadIcon(java.lang.String, boolean) instead. This method remains for compatibility.

Parameters:

resource - resource path of the icon (no initial slash)

localized - true for localized search

Returns:

ImageIcon or null, if the icon cannot be loaded.

Since:

7.22

loadIcon

public static final Icon loadIcon(String resource,
 boolean localized)

Loads an icon based on a resource path. Similar to loadImage(String, boolean), but returns Icon instead of Image.

Parameters:

resource - resource path of the icon (no initial slash)

localized - true for localized search

Returns:

ImageIcon or null, if the icon cannot be loaded.

Since:

7.36

loadIcon

public static final Icon loadIcon(String resource)

Loads an icon based on a resource path. Similar to loadImage(String), but returns Icon instead of Image.

Parameters:

resource - resource path of the icon (no initial slash)

Returns:

ImageIcon or null, if the icon cannot be loaded.

Since:

7.36

mergeImages

public static final Image mergeImages(Image image1,
 Image image2,
 int x,
 int y)

This method merges two images into the a one. The second image is drawn over the first one with its top-left corner at x, y. Images need not be of the same size. The new image will have a size of max(second image size + top-left corner, first image size). This method is used mostly when second image contains transparent pixels (e.g. for badging).

The implementation attempts to find the merged image in the cache first, then creates the image if it was not found.

Parameters:

image1 - underlying image

image2 - second image

x - x position of top-left corner

y - y position of top-left corner

Returns:

new merged image

mergeIcons

public static final Icon mergeIcons(Icon icon1,
 Icon icon2,
 int x,
 int y)

This method merges two icons into a new one. The second icon is drawn over the first one with its top-left corner at x, y. Icons need not be of the same size. The new icon will have a size of max(second icon size + top-left corner, first icon size). This method used mostly when second icon contains transparent pixels (e.g. for badging).

Similar to mergeImages(Image, Image, int, int), but on Icon instances rather than Image instances. This method is provided as a shortcut to avoid the need for conversions in client code.

Parameters:

icon1 - underlying icon

icon2 - second icon

x - x position of top-left corner

y - y position of top-left corner

Returns:

new merged icon

Since:

7.36

image2Icon

public static final Icon image2Icon(Image image)

Converts given image to an icon.

Parameters:

image - to be converted

Returns:

icon corresponding icon

icon2Image

public static final Image icon2Image(Icon icon)

Converts given icon to a Image.

A scalable Icon instance can always be recovered by passing the returned Image to image2Icon(Image) again, i.e. for painting on HiDPI screens.

Parameters:

icon - Icon to be converted.

assignToolTipToImage

public static final Image assignToolTipToImage(Image image,
 String text)

Assign tool tip text to given image (creates new or returns cached, original remains unmodified). Text can contain HTML tags e.g. "<b>my</b> text"

Parameters:

image - image to which tool tip should be set

text - tool tip text

Returns:

Image with attached tool tip

getImageToolTip

public static final String getImageToolTip(Image image)

Get tool tip text for given image

Parameters:

image - image which is asked for tool tip text

Returns:

String containing attached tool tip text

addToolTipToImage

public static final Image addToolTipToImage(Image image,
 String text)

Add text to tool tip for given image (creates new or returns cached, original remains unmodified). Text can contain HTML tags e.g. "<b>my</b> text"

Parameters:

text - text to add to tool tip

Returns:

Image with attached tool tip

createDisabledIcon

public static Icon createDisabledIcon(Icon icon)

Creates disabled (color saturation lowered) icon.

Parameters:

icon - original icon used for conversion

Returns:

less saturated Icon

Since:

7.28

createDisabledImage

public static Image createDisabledImage(Image image)

Creates disabled (color saturation lowered) image.

Parameters:

image - original image used for conversion

Returns:

less saturated Image

Since:

7.28

findImageBaseURL

public static URL findImageBaseURL(Image image)

Attempts to find image's URL, if it is defined. Image Observer features are not used during this call, the property is assumed to be populated. Note that the URL may be specific for a localization or branding, and may be the same for bare and badged icons.

Parameters:

image - image to inspect

Returns:

image's URL or null if not defined.

Since:

9.24