1 /******************************************************************************* 2 * Copyright (c) 2006, 2015 IBM Corporation and others. 3 * 4 * This program and the accompanying materials 5 * are made available under the terms of the Eclipse Public License 2.0 6 * which accompanies this distribution, and is available at 7 * https://www.eclipse.org/legal/epl-2.0/ 8 * 9 * SPDX-License-Identifier: EPL-2.0 10 * 11 * Contributors: 12 * IBM Corporation - initial API and implementation 13 ******************************************************************************/ 14 15 package org.eclipse.ui.navigator; 16 17 import org.eclipse.jface.viewers.IStructuredSelection; 18 import org.eclipse.swt.dnd.TransferData; 19 20 /** 21 * 22 * Provides instances of {@link CommonDragAdapterAssistant} and 23 * {@link CommonDropAdapterAssistant} for the associated 24 * {@link INavigatorContentService}. 25 * 26 * <p> 27 * Clients should only take note of this Service they are are using the 28 * {@link INavigatorContentService} in the context of a viewer which is not or 29 * does not extend {@link CommonViewer}. Clients should take a look at the 30 * initialization of the DND support in the {@link CommonViewer} if they wish to 31 * support this capability in their own viewers. 32 * </p> 33 * 34 * @see CommonDragAdapter 35 * @see CommonDragAdapterAssistant 36 * @see CommonDropAdapter 37 * @see CommonDropAdapterAssistant 38 * @see CommonViewer 39 * @see INavigatorContentService#getDnDService() 40 * @see <a 41 * href="http://www.eclipse.org/articles/Article-SWT-DND/DND-in-SWT.html">Drag 42 * and Drop: Adding Drag and Drop to an SWT Application</a> 43 * @see <a 44 * href="http://www.eclipse.org/articles/Article-Workbench-DND/drag_drop.html">Drag 45 * and Drop in the Eclipse UI (Custom Transfer Types)</a> 46 * 47 * @noimplement This interface is not intended to be implemented by clients. 48 * @noextend This interface is not intended to be extended by clients. 49 * @since 3.2 50 * 51 * 52 */ 53 public interface INavigatorDnDService { 54 55 /** 56 * 57 * As part of the <b>org.eclipse.ui.navigator.viewer</b> extension point, 58 * clients may explicit extend the support Transfer Types of a particular 59 * viewer using the <b>dragAssistant</b> element. This element defines a 60 * class which extends {@link CommonDragAdapterAssistant} and can direct the 61 * viewer on how to provide different kinds of DND Transfer Types. The array 62 * is returned in no particular order. 63 * 64 * @return An array of {@link CommonDragAdapterAssistant} or an empty array. 65 */ getCommonDragAssistants()66 CommonDragAdapterAssistant[] getCommonDragAssistants(); 67 68 /** 69 * Clients may choose to programmatically bind drag assistants to an 70 * instance of the DND Service. A programmatic binding is not persisted 71 * between sessions and is not propagated to other instances of 72 * {@link INavigatorContentService} with the same id. 73 * 74 * @param anAssistant The assistant to bind. 75 */ bindDragAssistant(CommonDragAdapterAssistant anAssistant)76 void bindDragAssistant(CommonDragAdapterAssistant anAssistant); 77 78 /** 79 * 80 * This method returns an array of {@link CommonDropAdapterAssistant} from 81 * content extensions that are <i>visible</i> and <i>active</i> for the 82 * associated {@link INavigatorContentService}. The array is sorted by 83 * priority, with overrides taken into account. 84 * 85 * <p> 86 * The array should be processed from the first element to the last, asking 87 * each extension to 88 * {@link CommonDropAdapterAssistant#validateDrop(Object, int, org.eclipse.swt.dnd.TransferData)}. 89 * The first to successfully validate the drop operation will have the 90 * opportunity to 91 * {@link CommonDropAdapterAssistant#handleDrop(CommonDropAdapter, org.eclipse.swt.dnd.DropTargetEvent, Object) handle the drop} 92 * </p> 93 * 94 * @param aDropTarget 95 * The target element in the viewer of the drop operation. 96 * @param theTransferType 97 * The transfer type of the current drop operation. 98 * @return An array of {@link CommonDropAdapterAssistant}s that are defined 99 * by the set of 100 * <b>org.eclipse.ui.navigator.navigatorContent/navigatorContent</b> 101 * extensions that provide a <b>possibleChildren</b> expression 102 * that matches the given drop target. 103 */ findCommonDropAdapterAssistants( Object aDropTarget, TransferData theTransferType)104 CommonDropAdapterAssistant[] findCommonDropAdapterAssistants( 105 Object aDropTarget, TransferData theTransferType); 106 107 /** 108 * 109 * This method returns an array of {@link CommonDropAdapterAssistant} from 110 * content extensions that are <i>visible</i> and <i>active</i> for the 111 * associated {@link INavigatorContentService}. 112 * 113 * <p> 114 * The array should be processed from the first element to the last, asking 115 * each extension to 116 * {@link CommonDropAdapterAssistant#validateDrop(Object, int, org.eclipse.swt.dnd.TransferData)}. 117 * The first to successfully validate the drop operation will have the 118 * opportunity to 119 * {@link CommonDropAdapterAssistant#handleDrop(CommonDropAdapter, org.eclipse.swt.dnd.DropTargetEvent, Object) handle the drop} 120 * </p> 121 * 122 * @param aDropTarget 123 * The target element in the viewer of the drop operation. 124 * @param theDragSelection 125 * The drag selection of the current drop operation. 126 * @return An array of {@link CommonDropAdapterAssistant}s that are defined 127 * by the set of 128 * <b>org.eclipse.ui.navigator.navigatorContent/navigatorContent</b> 129 * extensions that provide a <b>possibleChildren</b> expression 130 * that matches the given drop target. 131 */ findCommonDropAdapterAssistants( Object aDropTarget, IStructuredSelection theDragSelection)132 CommonDropAdapterAssistant[] findCommonDropAdapterAssistants( 133 Object aDropTarget, IStructuredSelection theDragSelection); 134 } 135