Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Programming
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Databases
Mail Systems
openSolaris
Eclipse Documentation
Techotopia.com
Virtuatopia.com

How To Guides
Virtualization
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Windows
Problem Solutions
Privacy Policy

  




 

 


Eclipse Platform
Release 3.5

org.eclipse.jface.resource
Class ImageDescriptor

java.lang.Object
  extended by 

org.eclipse.jface.resource.DeviceResourceDescriptor
      extended by 
org.eclipse.jface.resource.ImageDescriptor
Direct Known Subclasses:
CompositeImageDescriptor

public abstract class ImageDescriptor
extends DeviceResourceDescriptor

An image descriptor is an object that knows how to create an SWT image. It does not hold onto images or cache them, but rather just creates them on demand. An image descriptor is intended to be a lightweight representation of an image that can be manipulated even when no SWT display exists.

This package defines a concrete image descriptor implementation which reads an image from a file (FileImageDescriptor). It also provides abstract framework classes (this one and CompositeImageDescriptor) which may be subclassed to define news kinds of image descriptors.

Using this abstract class involves defining a concrete subclass and providing an implementation for the getImageData method.

There are two ways to get an Image from an ImageDescriptor. The method createImage will always return a new Image which must be disposed by the caller. Alternatively, createResource() returns a shared Image. When the caller is done with an image obtained from createResource, they must call destroyResource() rather than disposing the Image directly. The result of createResource() can be safely cast to an Image.

See Also:
Image

Field Summary
protected static  ImageData DEFAULT_IMAGE_DATA
          A small red square used to warn that an image cannot be created.
 
Constructor Summary
protected ImageDescriptor ()
          Constructs an image descriptor.
 
Method Summary
static  ImageDescriptor createFromFile ( Class location, String filename)
          Creates and returns a new image descriptor from a file.
static  ImageDescriptor createFromImage ( Image img)
          Creates and returns a new image descriptor for the given image.
static  ImageDescriptor createFromImage ( Image img, Device theDevice)
          Deprecated. use createFromImage(Image)
static  ImageDescriptor createFromImageData ( ImageData data)
          Creates and returns a new image descriptor given ImageData describing the image.
static  ImageDescriptor createFromURL ( URL url)
          Creates and returns a new image descriptor from a URL.
  Image createImage ()
          Creates and returns a new SWT image for this image descriptor.
  Image createImage (boolean returnMissingImageOnError)
          Creates and returns a new SWT image for this image descriptor.
  Image createImage (boolean returnMissingImageOnError, Device device)
          Creates and returns a new SWT image for this image descriptor.
  Image createImage ( Device device)
          Creates and returns a new SWT image for this image descriptor.
  Object createResource ( Device device)
          Creates the resource described by this descriptor
static  ImageDescriptor createWithFlags ( ImageDescriptor originalImage, int swtFlags)
          Creates an ImageDescriptor based on the given original descriptor, but with additional SWT flags.
 void destroyResource ( Object previouslyCreatedObject)
          Undoes everything that was done by a previous call to create(...), given the object that was returned by create(...).
abstract   ImageData getImageData ()
          Creates and returns a new SWT ImageData object for this image descriptor.
static  ImageDescriptor getMissingImageDescriptor ()
          Returns the shared image descriptor for a missing image.
 
Methods inherited from class java.lang. Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_IMAGE_DATA

protected static final 
ImageData DEFAULT_IMAGE_DATA
A small red square used to warn that an image cannot be created.

Constructor Detail

ImageDescriptor

protected ImageDescriptor()
Constructs an image descriptor.

Method Detail

createFromFile

public static 
ImageDescriptor createFromFile(
Class location,
                                             
String filename)
Creates and returns a new image descriptor from a file. Convenience method for new FileImageDescriptor(location,filename).

Parameters:
location - the class whose resource directory contain the file
filename - the file name
Returns:
a new image descriptor

createFromImageData

public static 
ImageDescriptor createFromImageData(
ImageData data)
Creates and returns a new image descriptor given ImageData describing the image.

Parameters:
data - contents of the image
Returns:
newly created image descriptor
Since:
3.1

createFromImage

public static 
ImageDescriptor createFromImage(
Image img)
Creates and returns a new image descriptor for the given image. Note that disposing the original Image will cause the descriptor to become invalid.

Parameters:
img - image to create
Returns:
a newly created image descriptor
Since:
3.1

createWithFlags

public static 
ImageDescriptor createWithFlags(
ImageDescriptor originalImage,
                                              int swtFlags)
Creates an ImageDescriptor based on the given original descriptor, but with additional SWT flags.

Note that this sort of ImageDescriptor is slower and consumes more resources than a regular image descriptor. It will also never generate results that look as nice as a hand-drawn image. Clients are encouraged to supply their own disabled/grayed/etc. images rather than using a default image and transforming it.

Parameters:
originalImage - image to transform
swtFlags - any flag that can be passed to the flags argument of Image#Image(Device, Image, int)
Returns:
an ImageDescriptor that creates new images by transforming the given image descriptor
Since:
3.1
See Also:
Image.Image(Device, Image, int)

createFromImage

public static 
ImageDescriptor createFromImage(
Image img,
                                              
Device theDevice)
Deprecated. use createFromImage(Image)

Creates and returns a new image descriptor for the given image. This method takes the Device that created the Image as an argument, allowing the original Image to be reused if the descriptor is asked for another Image on the same device. Note that disposing the original Image will cause the descriptor to become invalid.

Parameters:
img - image to create
theDevice - the device that was used to create the Image
Returns:
a newly created image descriptor
Since:
3.1

createFromURL

public static 
ImageDescriptor createFromURL(
URL url)
Creates and returns a new image descriptor from a URL.

Parameters:
url - The URL of the image file.
Returns:
a new image descriptor

createResource

public 
Object createResource(
Device device)
                      throws 
DeviceResourceException
Description copied from class: DeviceResourceDescriptor
Creates the resource described by this descriptor

Specified by:
createResource in class DeviceResourceDescriptor
Parameters:
device - the Device on which to allocate the resource
Returns:
the newly allocated resource (not null)
Throws:
DeviceResourceException - if unable to allocate the resource

destroyResource

public void destroyResource(
Object previouslyCreatedObject)
Description copied from class: DeviceResourceDescriptor
Undoes everything that was done by a previous call to create(...), given the object that was returned by create(...).

Specified by:
destroyResource in class DeviceResourceDescriptor
Parameters:
previouslyCreatedObject - an object that was returned by an equal descriptor in a previous call to createResource(...).

createImage

public 
Image createImage()
Creates and returns a new SWT image for this image descriptor. Note that each call returns a new SWT image object. The returned image must be explicitly disposed using the image's dispose call. The image will not be automatically garbage collected. A default image is returned in the event of an error.

Note: this method differs from createResource(Device) in that the returned image must be disposed directly, whereas an image obtained from createResource(...) must be disposed by calling destroyResource(...). It is not possible to mix-and-match. If you obtained the Image from this method, you must not dispose it by calling destroyResource. Clients are encouraged to use create/destroyResource and downcast the result to Image rather than using createImage.

Note: it is still possible for this method to return null in extreme cases, for example if SWT runs out of image handles.

Returns:
a new image or null if the image could not be created

createImage

public 
Image createImage(boolean returnMissingImageOnError)
Creates and returns a new SWT image for this image descriptor. The returned image must be explicitly disposed using the image's dispose call. The image will not be automatically garbage collected. In the event of an error, a default image is returned if returnMissingImageOnError is true, otherwise null is returned.

Note: Even if returnMissingImageOnError is true, it is still possible for this method to return null in extreme cases, for example if SWT runs out of image handles.

Parameters:
returnMissingImageOnError - flag that determines if a default image is returned on error
Returns:
a new image or null if the image could not be created

createImage

public 
Image createImage(
Device device)
Creates and returns a new SWT image for this image descriptor. The returned image must be explicitly disposed using the image's dispose call. The image will not be automatically garbage collected. A default image is returned in the event of an error.

Note: it is still possible for this method to return null in extreme cases, for example if SWT runs out of image handles.

Parameters:
device - the device on which to create the image
Returns:
a new image or null if the image could not be created
Since:
2.0

createImage

public 
Image createImage(boolean returnMissingImageOnError,
                         
Device device)
Creates and returns a new SWT image for this image descriptor. The returned image must be explicitly disposed using the image's dispose call. The image will not be automatically garbage collected. In the even of an error, a default image is returned if returnMissingImageOnError is true, otherwise null is returned.

Note: Even if returnMissingImageOnError is true, it is still possible for this method to return null in extreme cases, for example if SWT runs out of image handles.

Parameters:
returnMissingImageOnError - flag that determines if a default image is returned on error
device - the device on which to create the image
Returns:
a new image or null if the image could not be created
Since:
2.0

getImageData

public abstract 
ImageData getImageData()
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.

Returns:
a new image data or null

getMissingImageDescriptor

public static 
ImageDescriptor getMissingImageDescriptor()
Returns the shared image descriptor for a missing image.

Returns:
the missing image descriptor

Eclipse Platform
Release 3.5

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.


 
 
  Published under the terms of the Eclipse Public License Version 1.0 ("EPL") Design by Interspire