| /******************************************************************************* |
| * Copyright (c) 2003, 2009 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.DragSourceListener; |
| import org.eclipse.swt.dnd.DropTargetEvent; |
| import org.eclipse.swt.dnd.DropTargetListener; |
| 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 subclass this. |
| * </p> |
| * |
| * @see INavigatorDnDService |
| * @see INavigatorDnDService#findCommonDropAdapterAssistants(Object, |
| * TransferData) |
| * @since 3.2 |
| * |
| */ |
| public abstract class CommonDropAdapterAssistant { |
| |
| private INavigatorContentService contentService; |
| |
| private DropTargetEvent _currentEvent; |
| |
| private CommonDropAdapter _dropAdapter; |
| |
| /** |
| * 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. |
| * |
| * <p> |
| * Note: Contrary to the SWT {@link DropTargetListener} specification, you |
| * <i>must</i> make sure that the aDropTargetEvent.detail is not set to |
| * DND.DROP_MOVE unless actual work is required in the |
| * {@link DragSourceListener#dragFinished(org.eclipse.swt.dnd.DragSourceEvent)} |
| * to complete the operation (for example removing the moved file). In |
| * particular for the LocalSelectionTransfer case, DND.DROP_MOVE cannot be |
| * used as it will cause incorrect behavior in some existing drag handlers. |
| * |
| * In case of move operations where no action is required on the source side |
| * (e.g. LocalSelectionTransfer) you must set aDropTargetEvent.detail to |
| * DND.DROP_NONE to signal this to the drag source. Even though the SWT |
| * specification says this is canceling the drop, it is not really doing so, |
| * it is only preventing the DND.DROP_MOVE from being passed through to the |
| * dragFinished() method. |
| * |
| * @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(); |
| } |
| |
| /** |
| * Sets the current {@link DropTargetEvent}. |
| * |
| * This is used to make the event available to the client methods of this class. |
| * |
| * @param event |
| * the new event. |
| * |
| * @since 3.4 |
| */ |
| void setCurrentEvent(DropTargetEvent event) { |
| _currentEvent = event; |
| } |
| |
| /** |
| * Returns the current {@link DropTargetEvent}. |
| * |
| * @return event the current DropTargetEvent. |
| * |
| * @since 3.4 |
| */ |
| public DropTargetEvent getCurrentEvent() { |
| return _currentEvent; |
| } |
| |
| /** |
| * Sets the {@link CommonDropAdapter}. |
| * @param dropAdapter |
| * |
| * @noreference |
| * @nooverride This method is not intended to be re-implemented or extended by clients. |
| */ |
| public void setCommonDropAdapter(CommonDropAdapter dropAdapter) { |
| _dropAdapter = dropAdapter; |
| } |
| |
| /** |
| * Returns the {@link CommonDropAdapter}. |
| * |
| * @return the CommonDropAdapter. |
| * |
| * @since 3.4 |
| * |
| */ |
| protected CommonDropAdapter getCommonDropAdapter() { |
| return _dropAdapter; |
| } |
| |
| } |