/*******************************************************************************
 * Copyright (c) 2006, 2007 IBM Corporation 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
 *******************************************************************************/

package org.eclipse.ui;

import org.eclipse.core.runtime.CoreException;
import org.eclipse.core.runtime.IAdaptable;
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.core.runtime.IStatus;
import org.eclipse.jface.resource.ImageDescriptor;
import org.eclipse.jface.window.IShellProvider;
import org.eclipse.swt.SWT;
import org.eclipse.swt.graphics.Cursor;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Control;
import org.eclipse.ui.internal.InternalSaveable;
import org.eclipse.ui.internal.PartSite;
import org.eclipse.ui.progress.IJobRunnable;

/**
 * A <code>Saveable represents a unit of saveability, e.g. an editable
 * subset of the underlying domain model that may contain unsaved changes.
 * Different workbench parts (editors and views) may present the same saveables
 * in different ways. This interface allows the workbench to provide more
 * appropriate handling of operations such as saving and closing workbench
 * parts. For example, if two editors sharing the same saveable with unsaved
 * changes are closed simultaneously, the user is only prompted to save the
 * changes once for the shared saveable, rather than once for each editor.
 * <p>
 * Workbench parts that work in terms of saveables should implement
 * {@link ISaveablesSource}.
 * </p>
 * 
 * @see ISaveablesSource
 * @since 3.2
 */
public abstract class Saveable extends InternalSaveable implements IAdaptable {

	private Cursor waitCursor;
	private Cursor originalCursor;

	/**
	 * Attempts to show this saveable in the given page and returns
	 * <code>true on success. The default implementation does nothing
	 * and returns <code>false.
	 * 
	 * @param page
	 *            the workbench page in which to show this saveable
	 * @return <code>true if this saveable is now visible to the user
	 * @since 3.3
	 */
	public boolean show(IWorkbenchPage page) {
		if (page == null) {
			// I wish it was easier to avoid warnings about unused parameters
		}
		return false;
	}

	/**
	 * Returns the name of this saveable for display purposes.
	 * 
	 * @return the model's name; never <code>null.
	 */
	public abstract String getName();

	/**
	 * Returns the tool tip text for this saveable. This text is used to
	 * differentiate between two inputs with the same name. For instance,
	 * MyClass.java in folder X and MyClass.java in folder Y. The format of the
	 * text varies between input types.
	 * 
	 * @return the tool tip text; never <code>null
	 */
	public abstract String getToolTipText();

	/**
	 * Returns the image descriptor for this saveable.
	 * 
	 * @return the image descriptor for this model; may be <code>null
	 *         if there is no image
	 */
	public abstract ImageDescriptor getImageDescriptor();

	/**
	 * Saves the contents of this saveable.
	 * <p>
	 * If the save is cancelled through user action, or for any other reason,
	 * the part should invoke <code>setCancelled on the
	 * <code>IProgressMonitor to inform the caller.
	 * </p>
	 * <p>
	 * This method is long-running; progress and cancellation are provided by
	 * the given progress monitor.
	 * </p>
	 * 
	 * @param monitor
	 *            the progress monitor
	 * @throws CoreException
	 *             if the save fails; it is the caller's responsibility to
	 *             report the failure to the user
	 */
	public abstract void doSave(IProgressMonitor monitor) throws CoreException;

	/**
	 * Returns whether the contents of this saveable have changed since the last
	 * save operation.
	 * <p>
	 * <b>Note: this method is called frequently, for example by actions to
	 * determine their enabled status.
	 * </p>
	 * 
	 * @return <code>true if the contents have been modified and need
	 *         saving, and <code>false if they have not changed since
	 *         the last save
	 */
	public abstract boolean isDirty();

	/**
	 * Clients must implement equals and hashCode as defined in
	 * {@link Object#equals(Object)} and {@link Object#hashCode()}. Two
	 * saveables should be equal if their dirty state is shared, and saving one
	 * will save the other. If two saveables are equal, their names, tooltips,
	 * and images should be the same because only one of them will be shown when
	 * prompting the user to save.
	 * 
	 * @param object
	 * @return true if this Saveable is equal to the given object
	 */
	public abstract boolean equals(Object object);

	/**
	 * Clients must implement equals and hashCode as defined in
	 * {@link Object#equals(Object)} and {@link Object#hashCode()}. Two
	 * saveables should be equal if their dirty state is shared, and saving one
	 * will save the other. If two saveables are equal, their hash codes MUST be
	 * the same, and their names, tooltips, and images should be the same
	 * because only one of them will be shown when prompting the user to save.
	 * <p>
	 * IMPORTANT: Implementers should ensure that the hashCode returned is
	 * sufficiently unique so as not to collide with hashCodes returned by other
	 * implementations. It is suggested that the defining plug-in's ID be used
	 * as part of the returned hashCode, as in the following example:
	 * </p>
	 * 
	 * <pre>
	 *     int PRIME = 31;
	 *     int hash = ...; // compute the "normal" hash code, e.g. based on some identifier unique within the defining plug-in
	 *     return hash * PRIME + MY_PLUGIN_ID.hashCode();
	 * </pre>
	 * 
	 * @return a hash code
	 */
	public abstract int hashCode();

	/**
	 * Saves this saveable, or prepares this saveable for a background save
	 * operation. Returns null if this saveable has been successfully saved, or
	 * a job runnable that needs to be run to complete the save in the
	 * background. This method is called in the UI thread. If this saveable
	 * supports saving in the background, it should do only minimal work.
	 * However, since the job runnable returned by this method (if any) will not
	 * run on the UI thread, this method should copy any state that can only be
	 * accessed from the UI thread so that the job runnable will be able to
	 * access it.
	 * <p>
	 * The supplied shell provider can be used from within this method and from
	 * within the job runnable for the purpose of parenting dialogs. Care should
	 * be taken not to open dialogs gratuitously and only if user input is
	 * required for cases where the save cannot otherwise proceed - note that in
	 * any given save operation, many saveable objects may be saved at the same
	 * time. In particular, errors should be signaled by throwing an exception,
	 * or if an error occurs while running the job runnable, an error status
	 * should be returned.
	 * </p>
	 * <p>
	 * If the foreground part of the save is cancelled through user action, or
	 * for any other reason, the part should invoke <code>setCancelled
	 * on the <code>IProgressMonitor to inform the caller. If the
	 * background part of the save is cancelled, the job should return a
	 * {@link IStatus#CANCEL} status.
	 * </p>
	 * <p>
	 * This method is long-running; progress and cancellation are provided by
	 * the given progress monitor.
	 * </p>
	 * <p>
	 * The default implementation of this method calls
	 * {@link #doSave(IProgressMonitor)} and returns <code>null.
	 * </p>
	 * 
	 * @param monitor
	 *            a progress monitor used for reporting progress and
	 *            cancellation
	 * @param shellProvider
	 *            an object that can provide a shell for parenting dialogs
	 * @return <code>null if this saveable has been saved successfully,
	 *         or a job runnable that needs to be run to complete the save in
	 *         the background.
	 * 
	 * @since 3.3
	 */
	public IJobRunnable doSave(IProgressMonitor monitor,
			IShellProvider shellProvider) throws CoreException {
		doSave(monitor);
		return null;
	}

	/**
	 * Disables the UI of the given parts containing this saveable if necessary.
	 * This method is not intended to be called by clients. A corresponding call
	 * to
	 * <p>
	 * Saveables that can be saved in the background should ensure that the user
	 * cannot make changes to their data from the UI, for example by disabling
	 * controls, unless they are prepared to handle this case. This method is
	 * called on the UI thread after a job runnable has been returned from
	 * {@link #doSave(IProgressMonitor, IShellProvider)} and before
	 * spinning the event loop. The <code>closing flag indicates that
	 * this saveable is currently being saved in response to closing a workbench
	 * part, in which case further changes to this saveable through the UI must
	 * be prevented.
	 * </p>
	 * <p>
	 * The default implementation calls setEnabled(false) on the given parts'
	 * composites.
	 * </p>
	 * 
	 * @param parts
	 *            the workbench parts containing this saveable
	 * @param closing
	 *            a boolean flag indicating whether the save was triggered by a
	 *            request to close a workbench part, and all of the given parts
	 *            will be closed after the save operation finishes successfully.
	 * 
	 * @since 3.3
	 */
	public void disableUI(IWorkbenchPart[] parts, boolean closing) {
		for (int i = 0; i < parts.length; i++) {
			IWorkbenchPart workbenchPart = parts[i];
			Composite paneComposite = (Composite) ((PartSite) workbenchPart
					.getSite()).getPane().getControl();
			Control[] paneChildren = paneComposite.getChildren();
			Composite toDisable = ((Composite) paneChildren[0]);
			toDisable.setEnabled(false);
			if (waitCursor == null) {
				waitCursor = new Cursor(workbenchPart.getSite().getWorkbenchWindow().getShell().getDisplay(), SWT.CURSOR_WAIT);
			}
			originalCursor = paneComposite.getCursor();
			paneComposite.setCursor(waitCursor);
		}
	}

	/**
	 * Enables the UI of the given parts containing this saveable after a
	 * background save operation has finished. This method is not intended to be
	 * called by clients.
	 * <p>
	 * The default implementation calls setEnabled(true) on the given parts'
	 * composites.
	 * </p>
	 * 
	 * @param parts
	 *            the workbench parts containing this saveable
	 * 
	 * @since 3.3
	 */
	public void enableUI(IWorkbenchPart[] parts) {
		for (int i = 0; i < parts.length; i++) {
			IWorkbenchPart workbenchPart = parts[i];
			Composite paneComposite = (Composite) ((PartSite) workbenchPart
					.getSite()).getPane().getControl();
			Control[] paneChildren = paneComposite.getChildren();
			Composite toEnable = ((Composite) paneChildren[0]);
			paneComposite.setCursor(originalCursor);
			if (waitCursor!=null && !waitCursor.isDisposed()) {
				waitCursor.dispose();
				waitCursor = null;
			}
			toEnable.setEnabled(true);
		}
	}

	/**
	 * This implementation of {@link IAdaptable#getAdapter(Class)} returns
	 * <code>null. Subclasses may override. This allows two unrelated
	 * subclasses of Saveable to implement {@link #equals(Object)} and
	 * {@link #hashCode()} based on an underlying implementation class that is
	 * shared by both Saveable subclasses.
	 * 
	 * @since 3.3
	 */
	public Object getAdapter(Class adapter) {
		return null;
	}
}