org.eclipse.jface.resource
Class ResourceManager
java.lang.Object
org.eclipse.jface.resource.ResourceManager
-
Direct Known Subclasses:
-
DeviceResourceManager,
LocalResourceManager
-
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
Methods inherited from class java.lang.
Object
|
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
|
ResourceManager
public ResourceManager()
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)
- 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 this method should have
a corresponding call to
destroy(DeviceResourceDescriptor)
.
If the resource is intended to live for entire lifetime of the resource manager,
a subsequent call to
destroy(DeviceResourceDescriptor)
may be omitted and the
resource will be cleaned up when the resource manager is disposed. This pattern
is useful for short-lived
LocalResourceManager
s, but should never be used
with the global resource manager since doing so effectively leaks the resource.
The resources returned from this method are reference counted and may be shared
internally with other resource managers. They should never be disposed outside of the
ResourceManager framework, or it will cause exceptions in other code that shares
them. For example, never call
Resource.dispose()
on anything returned from this method.
Callers may safely downcast the result to the resource type associated with
the descriptor. For example, when given an ImageDescriptor, the return
value of this method will always be an Image.
-
-
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(DeviceResourceDescriptor)
.
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
get
public final
Object get(
DeviceResourceDescriptor descriptor)
-
Returns a previously-allocated resource or allocates a new one if none
exists yet. The resource will remain allocated for at least the lifetime
of this resource manager. If necessary, the resource will be deallocated
automatically when the resource manager is disposed.
The resources returned from this method are reference counted and may be shared
internally with other resource managers. They should never be disposed outside of the
ResourceManager framework, or it will cause exceptions in other code that shares
them. For example, never call
Resource.dispose()
on anything returned from this method.
Callers may safely downcast the result to the resource type associated with
the descriptor. For example, when given an ImageDescriptor, the return
value of this method may be downcast to Image.
This method should only be used for resources that should remain
allocated for the lifetime of the resource manager. To allocate shorter-lived
resources, manage them with create
, and destroy
rather than this method.
This method should never be called on the global resource manager,
since all resources will remain allocated for the lifetime of the app and
will be effectively leaked.
-
-
Parameters:
-
descriptor
- identifier for the requested resource
-
Returns:
- the requested resource. Never null.
-
Throws:
-
DeviceResourceException
- if the resource does not exist yet and cannot
be created for any reason. -
Since:
- 3.3
createImage
public final
Image createImage(
ImageDescriptor descriptor)
-
Creates an image, given an image descriptor. Images allocated in this manner must
be disposed by
destroyImage(ImageDescriptor)
, and never by calling
Resource.dispose()
.
If the image is intended to remain allocated for the lifetime of the ResourceManager,
the call to destroyImage may be omitted and the image will be cleaned up automatically
when the ResourceManager is disposed. This should only be done with short-lived ResourceManagers,
as doing so with the global manager effectively leaks the resource.
-
-
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
destroyImage(ImageDescriptor)
, and never by calling
Resource.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(ImageDescriptor)
.
-
-
Parameters:
-
descriptor
- identifier for the image to dispose -
Since:
- 3.1
createColor
public final
Color createColor(
ColorDescriptor descriptor)
- Allocates a color, given a color descriptor. Any color allocated in this
manner must be disposed by calling
destroyColor(ColorDescriptor)
,
or by an eventual call to
dispose()
.
Resource.dispose()
must
never been called directly on the returned color.
-
-
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)
- Allocates a color, given its RGB value. Any color allocated in this
manner must be disposed by calling
destroyColor(RGB)
,
or by an eventual call to
dispose()
.
Resource.dispose()
must
never been called directly on the returned color.
-
-
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(RGB)
.
-
-
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(ColorDescriptor)
.
-
-
Parameters:
-
descriptor
- identifier for the color to dispose -
Since:
- 3.1
createFont
public final
Font createFont(
FontDescriptor descriptor)
- Returns the Font described by the given FontDescriptor. Any Font
allocated in this manner must be deallocated by calling disposeFont(...),
or by an eventual call to
dispose()
. The method
Resource.dispose()
must never be called directly on the returned font.
-
-
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(FontDescriptor)
.
-
-
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 canceled 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
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.