001: /*******************************************************************************
002: * Copyright (c) 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: ******************************************************************************/package org.eclipse.ui.navigator;
011:
012: import org.eclipse.jface.viewers.IStructuredSelection;
013: import org.eclipse.swt.dnd.TransferData;
014:
015: /**
016: *
017: * Provides instances of {@link CommonDragAdapterAssistant} and
018: * {@link CommonDropAdapterAssistant} for the associated
019: * {@link INavigatorContentService}.
020: *
021: * <p>
022: * Clients should only take note of this Service they are are using the
023: * {@link INavigatorContentService} in the context of a viewer which is not or
024: * does not extend {@link CommonViewer}. Clients should take a look at the
025: * initialization of the DND support in the {@link CommonViewer} if they wish to
026: * support this capability in their own viewers.
027: * </p>
028: *
029: * <p>
030: * This interface is not intended to be implemented by clients.
031: * </p>
032: *
033: * @see CommonDragAdapter
034: * @see CommonDragAdapterAssistant
035: * @see CommonDropAdapter
036: * @see CommonDropAdapterAssistant
037: * @see CommonViewer
038: * @see INavigatorContentService#getDnDService()
039: * @see <a
040: * href="http://www.eclipse.org/articles/Article-SWT-DND/DND-in-SWT.html">Drag
041: * and Drop: Adding Drag and Drop to an SWT Application</a>
042: * @see <a
043: * href="http://www.eclipse.org/articles/Article-Workbench-DND/drag_drop.html">Drag
044: * and Drop in the Eclipse UI (Custom Transfer Types)</a>
045: *
046: * @since 3.2
047: *
048: *
049: */
050: public interface INavigatorDnDService {
051:
052: /**
053: *
054: * As part of the <b>org.eclipse.ui.navigator.viewer</b> extension point,
055: * clients may explicit extend the support Transfer Types of a particular
056: * viewer using the <b>dragAssistant</b> element. This element defines a
057: * class which extends {@link CommonDragAdapterAssistant} and can direct the
058: * viewer on how to provide different kinds of DND Transfer Types. The array
059: * is returned in no particular order.
060: *
061: * @return An array of {@link CommonDragAdapterAssistant} or an empty array.
062: */
063: CommonDragAdapterAssistant[] getCommonDragAssistants();
064:
065: /**
066: * Clients may choose to programmatically bind drag assistants to an
067: * instance of the DND Service. A programmatic binding is not persisted
068: * between sessions and is not propagated to other instances of
069: * {@link INavigatorContentService} with the same id.
070: *
071: * @param anAssistant The assistant to bind.
072: */
073: void bindDragAssistant(CommonDragAdapterAssistant anAssistant);
074:
075: /**
076: *
077: * This method returns an array of {@link CommonDropAdapterAssistant} from
078: * content extensions that are <i>visible</i> and <i>active</i> for the
079: * associated {@link INavigatorContentService}. The array is sorted by
080: * priority, with overrides taken into account.
081: *
082: * <p>
083: * The array should be processed from the first element to the last, asking
084: * each extension to
085: * {@link CommonDropAdapterAssistant#validateDrop(Object, int, org.eclipse.swt.dnd.TransferData)}.
086: * The first to successfully validate the drop operation will have the
087: * opportunity to
088: * {@link CommonDropAdapterAssistant#handleDrop(CommonDropAdapter, org.eclipse.swt.dnd.DropTargetEvent, Object) handle the drop}
089: * </p>
090: *
091: * @param aDropTarget
092: * The target element in the viewer of the drop operation.
093: * @param theTransferType
094: * The transfer type of the current drop operation.
095: * @return An array of {@link CommonDropAdapterAssistant}s that are defined
096: * by the set of
097: * <b>org.eclipse.ui.navigator.navigatorContent/navigatorContent</b>
098: * extensions that provide a <b>possibleChildren</b> expression
099: * that matches the given drop target.
100: */
101: CommonDropAdapterAssistant[] findCommonDropAdapterAssistants(
102: Object aDropTarget, TransferData theTransferType);
103:
104: /**
105: *
106: * This method returns an array of {@link CommonDropAdapterAssistant} from
107: * content extensions that are <i>visible</i> and <i>active</i> for the
108: * associated {@link INavigatorContentService}.
109: *
110: * <p>
111: * The array should be processed from the first element to the last, asking
112: * each extension to
113: * {@link CommonDropAdapterAssistant#validateDrop(Object, int, org.eclipse.swt.dnd.TransferData)}.
114: * The first to successfully validate the drop operation will have the
115: * opportunity to
116: * {@link CommonDropAdapterAssistant#handleDrop(CommonDropAdapter, org.eclipse.swt.dnd.DropTargetEvent, Object) handle the drop}
117: * </p>
118: *
119: * @param aDropTarget
120: * The target element in the viewer of the drop operation.
121: * @param theDragSelection
122: * The drag selection of the current drop operation.
123: * @return An array of {@link CommonDropAdapterAssistant}s that are defined
124: * by the set of
125: * <b>org.eclipse.ui.navigator.navigatorContent/navigatorContent</b>
126: * extensions that provide a <b>possibleChildren</b> expression
127: * that matches the given drop target.
128: */
129: CommonDropAdapterAssistant[] findCommonDropAdapterAssistants(
130: Object aDropTarget, IStructuredSelection theDragSelection);
131: }
|