| /******************************************************************************* |
| * Copyright (c) 2003, 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.core.runtime.IStatus; |
| import org.eclipse.core.runtime.Status; |
| import org.eclipse.jface.util.LocalSelectionTransfer; |
| import org.eclipse.jface.viewers.IStructuredSelection; |
| import org.eclipse.swt.dnd.DropTargetEvent; |
| import org.eclipse.swt.dnd.TransferData; |
| import org.eclipse.swt.widgets.Shell; |
| import org.eclipse.ui.internal.navigator.NavigatorContentService; |
| |
| /** |
| * <p> |
| * Used by the |
| * <b>org.eclipse.ui.navigator.navigatorContent/navigatorContent/commonDropAdapter</b> |
| * extension point to carry out pluggable drop operations. |
| * </p> |
| * <p> |
| * Each {@link CommonDropAdapterAssistant} is contained by single content |
| * extension. The opportunity for each assistant to handle the drop operation is |
| * determined by the <b>possibleChildren</b> expression of the |
| * <b>org.eclipse.ui.navigator.navigatorContent/navigatorContent</b> extension; |
| * whenever every element in the drag set matches the <b>possibleChildren</b> |
| * expression of an extension, it is eligible to handle the drop operation. This |
| * initial set is further culled using the <b>possibleDropTargets</b> |
| * expression of the <b>commonDropAdapter</b> using the current drop target. |
| * </p> |
| * <p> |
| * If drag operations originate outside of Eclipse, then the set of eligible |
| * drop adapters is determined based on the drop target (using the |
| * <b>possibleDropTargets</b> expression). Each assistant can then indicate |
| * whether {@link #isSupportedType(TransferData) the incoming type is supported}. |
| * <p> |
| * Whenever a match is found, the assistant will be given an opportunity to |
| * first {@link #validateDrop(Object, int, TransferData)}, and then if the |
| * assistant returns true, the assist must |
| * {@link #handleDrop(CommonDropAdapter, DropTargetEvent, Object)}. If |
| * multiple assistants match the drop target, then the potential assistants are |
| * ordered based on priority and their override relationships and given an |
| * opportunity to validate the drop operation in turn. The first one to validate |
| * will have the opportunty to carry out the drop. |
| * </p> |
| * |
| * <p> |
| * Clients may handle DND operations that begin and end in the current viewer by |
| * overriding the following methods: |
| * <ul> |
| * <li>{@link #validateDrop(Object, int, TransferData)}: Indicate whether this |
| * assistant can handle a drop onto the current viewer.</li> |
| * <li>{@link #handleDrop(CommonDropAdapter, DropTargetEvent, Object)}: Handle |
| * the drop operation onto the current viewer.</li> |
| * </ul> |
| * </p> |
| * <p> |
| * If a user originates a drag operation to another viewer that cannot handle |
| * one of the available drag transfer types, drop assistants may handle the drop |
| * operation for the target viewer. Clients must override : |
| * <ul> |
| * <li>{@link #validatePluginTransferDrop(IStructuredSelection, Object)}: |
| * Indicate whether this assistant can handle the drop onto another viewer. |
| * <li>{@link #handlePluginTransferDrop(IStructuredSelection, Object)}: Handle |
| * the drop operation onto the other viewer.</li> |
| * </ul> |
| * </p> |
| * <p> |
| * Clients may implement this interface. |
| * </p> |
| * |
| * @see INavigatorDnDService |
| * @see INavigatorDnDService#findCommonDropAdapterAssistants(Object, |
| * TransferData) |
| * @since 3.2 |
| * |
| */ |
| public abstract class CommonDropAdapterAssistant { |
| |
| private INavigatorContentService contentService; |
| |
| /** |
| * Perform any necessary initialization using the |
| * {@link INavigatorContentService}. |
| * |
| * |
| * @param aContentService |
| * The instance of {@link INavigatorContentService} that the |
| * current CommonDropAdapterAssistant will be associated with |
| */ |
| public final void init(INavigatorContentService aContentService) { |
| contentService = aContentService; |
| doInit(); |
| } |
| |
| /** |
| * Override to perform any one-time initialization. |
| */ |
| protected void doInit() { |
| |
| } |
| |
| /** |
| * Validates dropping on the given object. This method is called whenever |
| * some aspect of the drop operation changes. |
| * <p> |
| * Subclasses must implement this method to define which drops make sense. |
| * If clients return true, then they will be allowed to handle the drop in |
| * {@link #handleDrop(CommonDropAdapter, DropTargetEvent, Object) }. |
| * </p> |
| * |
| * @param target |
| * the object that the mouse is currently hovering over, or |
| * <code>null</code> if the mouse is hovering over empty space |
| * @param operation |
| * the current drag operation (copy, move, etc.) |
| * @param transferType |
| * the current transfer type |
| * @return A status indicating whether the drop is valid. |
| */ |
| public abstract IStatus validateDrop(Object target, int operation, |
| TransferData transferType); |
| |
| /** |
| * Carry out the DND operation. |
| * |
| * @param aDropAdapter |
| * The Drop Adapter contains information that has already been |
| * parsed from the drop event. |
| * @param aDropTargetEvent |
| * The drop target event. |
| * @param aTarget |
| * The object being dragged onto |
| * @return A status indicating whether the drop completed OK. |
| */ |
| public abstract IStatus handleDrop(CommonDropAdapter aDropAdapter, |
| DropTargetEvent aDropTargetEvent, Object aTarget); |
| |
| /** |
| * Clients may extend the supported transfer types beyond the default |
| * {@link LocalSelectionTransfer#getTransfer()} and |
| * {@link org.eclipse.ui.part.PluginTransfer#getInstance()} transfer types. When a transfer type |
| * other than one of these is encountered, the DND Service will query the |
| * <b>visible</b> and <b>active</b> descriptors that are <b>enabled</b> |
| * for the drop target of the current operation. |
| * |
| * @param aTransferType |
| * The transfer data from the drop operation |
| * @return True if the given TransferData can be understood by this |
| * assistant. |
| */ |
| public boolean isSupportedType(TransferData aTransferType) { |
| return LocalSelectionTransfer.getTransfer().isSupportedType( |
| aTransferType); |
| } |
| |
| /** |
| * |
| * Return true if the client can handle the drop onto the target viewer of |
| * the drop operation. |
| * <p> |
| * The default behavior of this method is to return <b>Status.CANCEL_STATUS</b>. |
| * </p> |
| * |
| * @param aDragSelection |
| * The selection dragged from the viewer. |
| * @param aDropTarget |
| * The target of the drop operation. |
| * |
| * @return OK if the plugin transfer can be handled by this assistant. |
| */ |
| public IStatus validatePluginTransferDrop( |
| IStructuredSelection aDragSelection, Object aDropTarget) { |
| return Status.CANCEL_STATUS; |
| } |
| |
| /** |
| * Handle the drop operation for the target viewer. |
| * <p> |
| * The default behavior of this method is to return <b>Status.CANCEL_STATUS</b>. |
| * </p> |
| * |
| * @param aDragSelection |
| * The selection dragged from the viewer. |
| * @param aDropTarget |
| * The target of the drop operation. |
| * |
| * @return OK if the drop operation succeeded. |
| */ |
| public IStatus handlePluginTransferDrop( |
| IStructuredSelection aDragSelection, Object aDropTarget) { |
| return Status.CANCEL_STATUS; |
| } |
| |
| /** |
| * |
| * @return The associated content service. |
| */ |
| protected INavigatorContentService getContentService() { |
| return contentService; |
| } |
| |
| /** |
| * |
| * @return A shell for the viewer currently used by the |
| * {@link INavigatorContentService}. |
| */ |
| protected final Shell getShell() { |
| return ((NavigatorContentService) contentService).getShell(); |
| } |
| |
| } |