/*******************************************************************************
 * Copyright (c) 2006 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.navigator;

import org.eclipse.jface.util.LocalSelectionTransfer;
import org.eclipse.jface.viewers.IStructuredSelection;
import org.eclipse.swt.dnd.DragSourceEvent;
import org.eclipse.swt.dnd.Transfer;
import org.eclipse.swt.dnd.TransferData;
import org.eclipse.swt.widgets.Event;
import org.eclipse.swt.widgets.Shell;
import org.eclipse.ui.PlatformUI;
import org.eclipse.ui.internal.navigator.NavigatorContentService;
import org.eclipse.ui.part.PluginTransfer;

/**
 * Assist the {@link CommonDragAdapter} by providing new TransferTypes and the
 * logic to handle setting up the transfer data. Clients must extend this class
 * as part of the <b>org.eclipse.ui.navigator.viewer/dragAssistant</b>
 * extension. By default, the Common Navigator supports
 * {@link LocalSelectionTransfer} and {@link PluginTransfer}.
 * 
 * <p>
 * Clients may extend this class.
 * </p>
 * 
 * @see INavigatorDnDService
 * @see CommonDragAdapter
 * @see CommonDropAdapter
 * @see CommonDropAdapterAssistant
 * @see CommonViewer
 * @see <a
 *      href="http://www.eclipse.org/articles/Article-SWT-DND/DND-in-SWT.html">Drag
 *      and Drop: Adding Drag and Drop to an SWT Application</a>
 * @see <a
 *      href="http://www.eclipse.org/articles/Article-Workbench-DND/drag_drop.html">Drag
 *      and Drop in the Eclipse UI (Custom Transfer Types)</a>
 * 
 * @since 3.2
 * 
 */
public abstract class CommonDragAdapterAssistant {

	private INavigatorContentService contentService;

	/**
	 * Extra TransferTypes allow the Navigator to generate different kinds of
	 * payloads for DND clients. By default, the {@link CommonDragAdapter}
	 * supports {@link LocalSelectionTransfer} and {@link PluginTransfer}.
	 * 
	 * <p>
	 * CommonDragAdapterAssistants can extend the available TransferTypes that a
	 * Common Navigator Viewer can generate. Clients should return the set of
	 * Transfer Types they support. When a drop event occurs, the available drag
	 * assistants will be searched for a <i>enabled</i> assistants for the
	 * {@link DragSourceEvent}. Only if the drop event occurs will
	 * {@link #setDragData(DragSourceEvent, IStructuredSelection)} be called. If
	 * the drop event is cancelled,
	 * {@link #setDragData(DragSourceEvent, IStructuredSelection)} will not be
	 * called.
	 * </p>
	 * 
	 * @return The added transfer types. (e.g. FileTransfer.getInstance()).
	 */
	public abstract Transfer[] getSupportedTransferTypes();

	/**
	 * Set the value of the {@link org.eclipse.swt.widgets.Event#data} field using the given selection.
	 * Clients will only have an opportunity to set the drag data if they have
	 * returned a matching Transfer Type from
	 * {@link #getSupportedTransferTypes()} for the
	 * {@link DragSourceEvent#dataType}.
	 * <p>
	 * Clients will only have an opportunity to set the data when the drop event
	 * occurs. If the drop operation is cancelled, then this method will not be
	 * called.
	 * </p>
	 * 
	 * @param anEvent
	 *            The event object should have its {@link Event#data} field set
	 *            to a value that matches a supported {@link TransferData} type.
	 * @param aSelection
	 *            The current selection from the viewer.
	 * @return True if the data could be set; false otherwise.
	 */
	public abstract boolean setDragData(DragSourceEvent anEvent,
			IStructuredSelection aSelection);

	/**
	 * Accept and remember the content service this assistant is associated
	 * with.
	 * 
	 * @param aContentService
	 */
	public final void setContentService(INavigatorContentService aContentService) {
		contentService = aContentService;
	}

	/**
	 * 
	 * @return The associated content service.
	 */
	public INavigatorContentService getContentService() {
		return contentService;
	}

	/**
	 * 
	 * @return The shell for the viewer this assistant is associated with or the
	 *         shell of the active workbench window.
	 */
	public final Shell getShell() {
		if (contentService != null) {
			((NavigatorContentService) contentService).getShell();
		}
		return PlatformUI.getWorkbench().getActiveWorkbenchWindow().getShell();
	}

}