Package org.eclipse.ui.internal
Class WorkbenchImages
java.lang.Object
org.eclipse.ui.internal.WorkbenchImages
This class provides convenience access to many of the resources required by
the workbench. The class stores some images as descriptors, and some are
stored as real Images in the registry. This is a pure speed-space tradeoff.
The trick for users of this class is that images obtained from the registry
(using getImage()), don't require disposal since they are shared, while
images obtained using getImageDescriptor() will require disposal. Consult the
declareImages method to see if a given image is declared as a registry image
or just as a descriptor. If you change an image from being stored as a
descriptor to a registry image, or vice-versa, make sure to check all users
of the image to ensure they are calling the correct getImage... method and
handling disposal correctly.
Images: - use getImage(key) to access cached images from the registry. - Less
common images are found by calling getImageDescriptor(key) where key can be
found in IWorkbenchGraphicConstants
This class initializes the image registry by declaring all of the required
graphics. This involves creating image descriptors describing how to
create/find the image should it be needed. The image is not actually
allocated until requested.
Some Images are also made available to other plugins by being placed in the
descriptor table of the SharedImages class.
Where are the images? The images (typically png file) are found the plugins
install directory
How to add a new image Place the png file into the appropriate directories.
Add a constant to IWorkbenchGraphicConstants following the conventions Add
the declaration to this file
-
Field Summary
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionstatic void
declareImage
(String symbolicName, ImageDescriptor descriptor, boolean shared) Declares a workbench image.static void
dispose()
Disposes and clears the workbench images.static Map<String,
ImageDescriptor> Returns the map from symbolic name to ImageDescriptor.static Image
Returns the image stored in the workbench plugin's image registry under the given symbolic name.static ImageDescriptor
getImageDescriptor
(String symbolicName) Returns the image descriptor stored under the given symbolic name.static ImageDescriptor
getImageDescriptorFromProgram
(String filename, int offset) Convenience Method.static ImageRegistry
Returns the ImageRegistry.static ImageDescriptor
getWorkbenchImageDescriptor
(String relativePath) Get the workbench image with the given path relative to ICON_PATH.
-
Field Details
-
ICONS_PATH
- See Also:
-
-
Constructor Details
-
WorkbenchImages
public WorkbenchImages()
-
-
Method Details
-
declareImage
Declares a workbench image.The workbench remembers the given image descriptor under the given name, and makes the image available to plug-ins via
IWorkbench.getSharedImages()
. For "shared" images, the workbench remembers the image descriptor and will manages the image object create from it; clients retrieve "shared" images viaISharedImages.getImage()
. For the other, "non-shared" images, the workbench remembers only the image descriptor; clients retrieve the image descriptor viaISharedImages.getImageDescriptor()
and are entirely responsible for managing the image objects they create from it. (This is made confusing by the historical fact that the API interface is called "ISharedImages".)- Parameters:
symbolicName
- the symbolic name of the imagedescriptor
- the image descriptorshared
-true
if this is a shared image, andfalse
if this is not a shared image- See Also:
-
getDescriptors
Returns the map from symbolic name to ImageDescriptor.- Returns:
- the map from symbolic name to ImageDescriptor.
-
getImage
Returns the image stored in the workbench plugin's image registry under the given symbolic name. If there isn't any value associated with the name thennull
is returned. The returned Image is managed by the workbench plugin's image registry. Callers of this method must not dispose the returned image. This method is essentially a convenient short form of WorkbenchImages.getImageRegistry.get(symbolicName).- Parameters:
symbolicName
- the symbolic name- Returns:
- the image
-
getImageDescriptor
Returns the image descriptor stored under the given symbolic name. If there isn't any value associated with the name thennull
is returned. The class also "caches" commonly used images in the image registry. If you are looking for one of these common images it is recommended you use the getImage() method instead.- Parameters:
symbolicName
- the symbolic name- Returns:
- the image descriptor
-
getImageDescriptorFromProgram
Convenience Method. Returns an ImageDescriptor obtained from an external program. If there isn't any image thennull
is returned. This method is convenience and only intended for use by the workbench because it explicitly uses the workbench's registry for caching/retrieving images from other extensions -- other plugins must user their own registry. This convenience method is subject to removal. Note: This consults the plugin for extension and obtains its installation location. all requested images are assumed to be in a directory below and relative to that plugins installation directory.- Parameters:
filename
- the file nameoffset
- the offset- Returns:
- the image descriptor
-
getImageRegistry
Returns the ImageRegistry.- Returns:
- the image registry
-
dispose
public static void dispose()Disposes and clears the workbench images. Called when the workbench is shutting down.- Since:
- 3.1
-
getWorkbenchImageDescriptor
Get the workbench image with the given path relative to ICON_PATH.- Returns:
- ImageDescriptor
-