Resource.java

/*******************************************************************************
 * Copyright (c) 2000, 2010, 2012 IBM Corporation, Gerhardt Informatics Kft. and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *     Gerhardt Informatics Kft. - GEFGWT port
 *******************************************************************************/
package org.eclipse.swt.graphics;

import org.eclipse.swt.SWT;

/**
 * This class is the abstract superclass of all graphics resource objects.
 * Resources created by the application must be disposed.
 * <p>
 * IMPORTANT: This class is intended to be subclassed <em>only</em> within the
 * SWT implementation. However, it has not been marked final to allow those
 * outside of the SWT development team to implement patched versions of the
 * class in order to get around specific limitations in advance of when those
 * limitations can be addressed by the team. Any class built using subclassing
 * to access the internals of this class will likely fail to compile or run
 * between releases and may be strongly platform specific. Subclassing should
 * not be attempted without an intimate and detailed understanding of the
 * workings of the hierarchy. No support is provided for user-written classes
 * which are implemented as subclasses of this class.
 * </p>
 * 
 * @see #dispose
 * @see #isDisposed
 * @see <a href="http://www.eclipse.org/swt/">Sample code and further
 *      information</a>
 * 
 * @since 3.1
 */
public abstract class Resource {

	/**
	 * the device where this resource was created
	 */
	Device device;

	public Resource() {
	}

	Resource(Device device) {
		if (device == null)
			device = Device.getDevice();
		if (device == null)
			SWT.error(SWT.ERROR_NULL_ARGUMENT);
		this.device = device;
	}

	void destroy() {
	}

	/**
	 * Disposes of the operating system resources associated with this resource.
	 * Applications must dispose of all resources which they allocate. This
	 * method does nothing if the resource is already disposed.
	 */
	public void dispose() {
		if (device == null)
			return;
		if (device.isDisposed())
			return;
		destroy();
		if (device.tracking)
			device.dispose_Object(this);
		device = null;
	}

	/**
	 * Returns the <code>Device</code> where this resource was created.
	 * 
	 * @return <code>Device</code> the device of the receiver
	 * 
	 * @since 3.2
	 */
	public Device getDevice() {
		Device device = this.device;
		if (device == null || isDisposed())
			SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
		return device;
	}

	void init() {
		if (device.tracking)
			device.new_Object(this);
	}

	/**
	 * Returns <code>true</code> if the resource has been disposed, and
	 * <code>false</code> otherwise.
	 * <p>
	 * This method gets the dispose state for the resource. When a resource has
	 * been disposed, it is an error to invoke any other method (except
	 * {@link #dispose()}) using the resource.
	 * 
	 * @return <code>true</code> when the resource is disposed and
	 *         <code>false</code> otherwise
	 */
	public abstract boolean isDisposed();

}