bundles/org.eclipse.jface/src/org/eclipse/jface/resource/ImageRegistry.java

/*******************************************************************************
 * Copyright (c) 2000, 2003 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials 
 * are made available under the terms of the Common Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/cpl-v10.html
 * 
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.jface.resource;


import java.util.*;

import org.eclipse.jface.util.Assert;
import org.eclipse.swt.graphics.Image;
import org.eclipse.swt.widgets.Display;

/**
 * An image registry maintains a mapping between symbolic image names 
 * and SWT image objects or special image descriptor objects which
 * defer the creation of SWT image objects until they are needed.
 * <p>
 * An image registry owns all of the image objects registered
 * with it, and automatically disposes of them when the SWT Display
 * that creates the images is disposed. Because of this, clients do not 
 * need to (indeed, must not attempt to) dispose of these images themselves.
 * </p>
 * <p>
 * Clients may instantiate this class (it was not designed to be subclassed).
 * </p>
 * <p>
 * Unlike the FontRegistry, it is an error to replace images. As a result
 * there are no events that fire when values are changed in the registry
 * </p>
 */
public class ImageRegistry {

	/**
	 * Table of known images keyed by symbolic image name
	 * (key type: <code>String</code>, 
	 *  value type: <code>org.eclipse.swt.graphics.Image</code>
	 *  or <code>ImageDescriptor</code>).
	 */
	private Map table = new HashMap(10);
	
	/**
	 * Creates an empty image registry.
	 * <p>
	 * There must be an SWT Display created in the current 
	 * thread before calling this method.
	 * </p>
	 */
	public ImageRegistry() {
		this(Display.getCurrent());
	}
	
	/**
	 * Creates an empty image registry.
	 */
	public ImageRegistry(Display display) {
		super();
		Assert.isNotNull(display);
		hookDisplayDispose(display);
	}
	
	/**
	 * Returns the image associated with the given key in this registry, 
	 * or <code>null</code> if none.
	 *
	 * @param key the key
	 * @return the image, or <code>null</code> if none
	 */
	public Image get(String key) {
		Entry entry = (Entry)table.get(key);
		if (entry == null) {
			return null;
		}
		if (entry.image == null && entry.descriptor != null) {
			entry.image = entry.descriptor.createImage();
		}
		return entry.image;
	}
	
	/**
	 * Returns the descriptor associated with the given key in this registry, 
	 * or <code>null</code> if none.
	 *
	 * @param key the key
	 * @return the descriptor, or <code>null</code> if none
	 * @since 2.1
	 */
	public ImageDescriptor getDescriptor(String key) {
		Entry entry = (Entry)table.get(key);
		if (entry == null) {
			return null;
		}
		return entry.descriptor;
	}
	
	/**
	 * Shut downs this resource registry and disposes of all registered images.
	 */
	private void handleDisplayDispose() {
		for (Iterator e = table.values().iterator(); e.hasNext();) {
			Entry entry = (Entry)e.next();
			if (entry.image != null) {
				entry.image.dispose();
			}
		}
		table = null;
	}
	
	/**
	 * Hook a dispose listener on the SWT display.
	 *
	 * @param display the Display
	 */
	private void hookDisplayDispose(Display display) {
		display.disposeExec(new Runnable() {
			public void run() {
				handleDisplayDispose();
			}
		});
	}
	
	/**
	 * Adds (or replaces) an image descriptor to this registry. The first time
	 * this new entry is retrieved, the image descriptor's image will be computed 
	 * (via </code>ImageDescriptor.createImage</code>) and remembered. 
	 * This method replaces an existing image descriptor associated with the 
	 * given key, but fails if there is a real image associated with it.
	 *
	 * @param key the key
	 * @param descriptor the ImageDescriptor
	 * @exception IllegalArgumentException if the key already exists
	 */
	public void put(String key, ImageDescriptor descriptor) {
		Entry entry = (Entry)table.get(key);
		if (entry == null) {
			entry = new Entry();
			table.put(key, entry);
		}
		if (entry.image == null) {
			entry.descriptor = descriptor;
			return;
		}
		throw new IllegalArgumentException("ImageRegistry key already in use: " + key); //$NON-NLS-1$
	}
	
	/**
	 * Adds an image to this registry.  This method fails if there
	 * is already an image or descriptor for the given key.
	 * <p>
	 * Note that an image registry owns all of the image objects registered
	 * with it, and automatically disposes of them the SWT Display is disposed. 
	 * Because of this, clients must not register an image object
	 * that is managed by another object.
	 * </p>
	 *
	 * @param key the key
	 * @param image the image
	 * @exception IllegalArgumentException if the key already exists
	 */
	public void put(String key, Image image) {
		Entry entry = (Entry)table.get(key);
		if (entry == null) {
			entry = new Entry();
			table.put(key, entry);
		}
		if (entry.image == null && entry.descriptor == null) {
			entry.image = image;
			return;
		}
		throw new IllegalArgumentException("ImageRegistry key already in use: " + key); //$NON-NLS-1$
	}
	
	
	/**
	 * Contains the data for an entry in the registry. 
 	 */
	private static class Entry {
		protected Image image;
		protected ImageDescriptor descriptor;
	}
}