Eclipse Platform
Release 3.1

org.eclipse.jface.resource
Class ResourceManager

java.lang.Object
  extended byorg.eclipse.jface.resource.ResourceManager
Direct Known Subclasses:
org.eclipse.jface.resource.AbstractResourceManager

public abstract class ResourceManager
extends Object

This class manages SWT resources. It manages reference-counted instances of resources such as Fonts, Images, and Colors, and allows them to be accessed using descriptors. Everything allocated through the registry should also be disposed through the registry. Since the resources are shared and reference counted, they should never be disposed directly.

ResourceManager handles correct allocation and disposal of resources. It differs from the various JFace *Registry classes, which also map symbolic IDs onto resources. In general, you should use a *Registry class to map IDs onto descriptors, and use a ResourceManager to convert the descriptors into real Images/Fonts/etc.

Since:
3.1

Constructor Summary
ResourceManager()
           
 
Method Summary
 void cancelDisposeExec(Runnable r)
          Cancels a runnable that was previously scheduled with disposeExec.
abstract  Object create(DeviceResourceDescriptor descriptor)
          Returns the resource described by the given descriptor.
 Color createColor(ColorDescriptor descriptor)
          Allocates a color, given a color descriptor.
 Color createColor(RGB descriptor)
          Allocates a color, given its RGB values.
 Font createFont(FontDescriptor descriptor)
          Returns the Font described by the given FontDescriptor.
 Image createImage(ImageDescriptor descriptor)
          Creates an image, given an image descriptor.
 Image createImageWithDefault(ImageDescriptor descriptor)
          Creates an image, given an image descriptor.
abstract  void destroy(DeviceResourceDescriptor descriptor)
          Deallocates a resource previously allocated by create(...).
 void destroyColor(ColorDescriptor descriptor)
          Undoes everything that was done by a call to createColor(...).
 void destroyColor(RGB descriptor)
          Undoes everything that was done by a call to createColor(...).
 void destroyFont(FontDescriptor descriptor)
          Undoes everything that was done by a previous call to createFont().
 void destroyImage(ImageDescriptor descriptor)
          Undoes everything that was done by createImage(...).
 void dispose()
          Disposes any remaining resources allocated by this manager.
 void disposeExec(Runnable r)
          Causes the run() method of the runnable to be invoked just before the receiver is disposed.
abstract  Object find(DeviceResourceDescriptor descriptor)
          Returns a previously allocated resource associated with the given descriptor, or null if none exists yet.
protected abstract  Image getDefaultImage()
          Returns the default image that will be returned in the event that the intended image is missing.
abstract  Device getDevice()
          Returns the Device for which this ResourceManager will create resources
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ResourceManager

public ResourceManager()
Method Detail

getDevice

public abstract Device getDevice()
Returns the Device for which this ResourceManager will create resources

Returns:
the Device associated with this ResourceManager
Since:
3.1

create

public abstract Object create(DeviceResourceDescriptor descriptor)
                       throws DeviceResourceException
Returns the resource described by the given descriptor. If the resource already exists, the reference count is incremented and the exiting resource is returned. Otherwise, a new resource is allocated. Every call to create(...) should have a corresponding call to dispose(...).

Parameters:
descriptor - descriptor for the resource to allocate
Returns:
the newly allocated resource (not null)
Throws:
DeviceResourceException - if unable to allocate the resource
Since:
3.1

destroy

public abstract void destroy(DeviceResourceDescriptor descriptor)
Deallocates a resource previously allocated by create(...). Descriptors are compared by equality, not identity. If the same resource was created multiple times, this may decrement a reference count rather than disposing the actual resource.

Parameters:
descriptor - identifier for the resource
Since:
3.1

createImage

public final Image createImage(ImageDescriptor descriptor)
                        throws DeviceResourceException
Creates an image, given an image descriptor. Images allocated in this manner must be disposed by disposeImage, and never by calling Image.dispose().

Parameters:
descriptor - descriptor for the image to create
Returns:
the Image described by this descriptor (possibly shared by other equivalent ImageDescriptors)
Throws:
DeviceResourceException - if unable to allocate the Image
Since:
3.1

createImageWithDefault

public final Image createImageWithDefault(ImageDescriptor descriptor)
Creates an image, given an image descriptor. Images allocated in this manner must be disposed by disposeImage, and never by calling Image.dispose().

Parameters:
descriptor - descriptor for the image to create
Returns:
the Image described by this descriptor (possibly shared by other equivalent ImageDescriptors)
Since:
3.1

getDefaultImage

protected abstract Image getDefaultImage()
Returns the default image that will be returned in the event that the intended image is missing.

Returns:
a default image that will be returned in the event that the intended image is missing.
Since:
3.1

destroyImage

public final void destroyImage(ImageDescriptor descriptor)
Undoes everything that was done by createImage(...).

Parameters:
descriptor - identifier for the image to dispose
Since:
3.1

createColor

public final Color createColor(ColorDescriptor descriptor)
                        throws DeviceResourceException
Allocates a color, given a color descriptor. Any color allocated in this manner must be disposed by calling disposeColor(...) and never by calling Color.dispose() directly.

Parameters:
descriptor - descriptor for the color to create
Returns:
the Color described by the given ColorDescriptor (not null)
Throws:
DeviceResourceException - if unable to create the color
Since:
3.1

createColor

public final Color createColor(RGB descriptor)
                        throws DeviceResourceException
Allocates a color, given its RGB values. Any color allocated in this manner must be disposed by calling disposeColor(...) and never by calling Color.dispose() directly.

Parameters:
descriptor - descriptor for the color to create
Returns:
the Color described by the given ColorDescriptor (not null)
Throws:
DeviceResourceException - if unable to create the color
Since:
3.1

destroyColor

public final void destroyColor(RGB descriptor)
Undoes everything that was done by a call to createColor(...).

Parameters:
descriptor - RGB value of the color to dispose
Since:
3.1

destroyColor

public final void destroyColor(ColorDescriptor descriptor)
Undoes everything that was done by a call to createColor(...).

Parameters:
descriptor - identifier for the color to dispose
Since:
3.1

createFont

public final Font createFont(FontDescriptor descriptor)
                      throws DeviceResourceException
Returns the Font described by the given FontDescriptor. Any Font allocated in this manner must be deallocated by calling disposeFont(...) and never by calling Font.dispose() directly.

Parameters:
descriptor - description of the font to create
Returns:
the Font described by the given descriptor
Throws:
DeviceResourceException - if unable to create the font
Since:
3.1

destroyFont

public final void destroyFont(FontDescriptor descriptor)
Undoes everything that was done by a previous call to createFont().

Parameters:
descriptor - description of the font to destroy
Since:
3.1

dispose

public void dispose()
Disposes any remaining resources allocated by this manager.


find

public abstract Object find(DeviceResourceDescriptor descriptor)
Returns a previously allocated resource associated with the given descriptor, or null if none exists yet.

Parameters:
descriptor - descriptor to find
Returns:
a previously allocated resource for the given descriptor or null if none.
Since:
3.1

disposeExec

public void disposeExec(Runnable r)
Causes the run() method of the runnable to be invoked just before the receiver is disposed. The runnable can be subsequently cancelled by a call to cancelDisposeExec.

Parameters:
r - runnable to execute.

cancelDisposeExec

public void cancelDisposeExec(Runnable r)
Cancels a runnable that was previously scheduled with disposeExec. Has no effect if the given runnable was not previously registered with disposeExec.

Parameters:
r - runnable to cancel

Eclipse Platform
Release 3.1

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2005. All rights reserved.