KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > ui > navigator > CommonDropAdapterAssistant


1 /*******************************************************************************
2  * Copyright (c) 2003, 2006 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11 package org.eclipse.ui.navigator;
12
13 import org.eclipse.core.runtime.IStatus;
14 import org.eclipse.core.runtime.Status;
15 import org.eclipse.jface.util.LocalSelectionTransfer;
16 import org.eclipse.jface.viewers.IStructuredSelection;
17 import org.eclipse.swt.dnd.DropTargetEvent;
18 import org.eclipse.swt.dnd.TransferData;
19 import org.eclipse.swt.widgets.Shell;
20 import org.eclipse.ui.internal.navigator.NavigatorContentService;
21
22 /**
23  * <p>
24  * Used by the
25  * <b>org.eclipse.ui.navigator.navigatorContent/navigatorContent/commonDropAdapter</b>
26  * extension point to carry out pluggable drop operations.
27  * </p>
28  * <p>
29  * Each {@link CommonDropAdapterAssistant} is contained by single content
30  * extension. The opportunity for each assistant to handle the drop operation is
31  * determined by the <b>possibleChildren</b> expression of the
32  * <b>org.eclipse.ui.navigator.navigatorContent/navigatorContent</b> extension;
33  * whenever every element in the drag set matches the <b>possibleChildren</b>
34  * expression of an extension, it is eligible to handle the drop operation. This
35  * initial set is further culled using the <b>possibleDropTargets</b>
36  * expression of the <b>commonDropAdapter</b> using the current drop target.
37  * </p>
38  * <p>
39  * If drag operations originate outside of Eclipse, then the set of eligible
40  * drop adapters is determined based on the drop target (using the
41  * <b>possibleDropTargets</b> expression). Each assistant can then indicate
42  * whether {@link #isSupportedType(TransferData) the incoming type is supported}.
43  * <p>
44  * Whenever a match is found, the assistant will be given an opportunity to
45  * first {@link #validateDrop(Object, int, TransferData)}, and then if the
46  * assistant returns true, the assist must
47  * {@link #handleDrop(CommonDropAdapter, DropTargetEvent, Object)}. If
48  * multiple assistants match the drop target, then the potential assistants are
49  * ordered based on priority and their override relationships and given an
50  * opportunity to validate the drop operation in turn. The first one to validate
51  * will have the opportunty to carry out the drop.
52  * </p>
53  *
54  * <p>
55  * Clients may handle DND operations that begin and end in the current viewer by
56  * overriding the following methods:
57  * <ul>
58  * <li>{@link #validateDrop(Object, int, TransferData)}: Indicate whether this
59  * assistant can handle a drop onto the current viewer.</li>
60  * <li>{@link #handleDrop(CommonDropAdapter, DropTargetEvent, Object)}: Handle
61  * the drop operation onto the current viewer.</li>
62  * </ul>
63  * </p>
64  * <p>
65  * If a user originates a drag operation to another viewer that cannot handle
66  * one of the available drag transfer types, drop assistants may handle the drop
67  * operation for the target viewer. Clients must override :
68  * <ul>
69  * <li>{@link #validatePluginTransferDrop(IStructuredSelection, Object)}:
70  * Indicate whether this assistant can handle the drop onto another viewer.
71  * <li>{@link #handlePluginTransferDrop(IStructuredSelection, Object)}: Handle
72  * the drop operation onto the other viewer.</li>
73  * </ul>
74  * </p>
75  * <p>
76  * Clients may implement this interface.
77  * </p>
78  *
79  * @see INavigatorDnDService
80  * @see INavigatorDnDService#findCommonDropAdapterAssistants(Object,
81  * TransferData)
82  * @since 3.2
83  *
84  */
85 public abstract class CommonDropAdapterAssistant {
86
87     private INavigatorContentService contentService;
88
89     /**
90      * Perform any necessary initialization using the
91      * {@link INavigatorContentService}.
92      *
93      *
94      * @param aContentService
95      * The instance of {@link INavigatorContentService} that the
96      * current CommonDropAdapterAssistant will be associated with
97      */
98     public final void init(INavigatorContentService aContentService) {
99         contentService = aContentService;
100         doInit();
101     }
102
103     /**
104      * Override to perform any one-time initialization.
105      */
106     protected void doInit() {
107
108     }
109
110     /**
111      * Validates dropping on the given object. This method is called whenever
112      * some aspect of the drop operation changes.
113      * <p>
114      * Subclasses must implement this method to define which drops make sense.
115      * If clients return true, then they will be allowed to handle the drop in
116      * {@link #handleDrop(CommonDropAdapter, DropTargetEvent, Object) }.
117      * </p>
118      *
119      * @param target
120      * the object that the mouse is currently hovering over, or
121      * <code>null</code> if the mouse is hovering over empty space
122      * @param operation
123      * the current drag operation (copy, move, etc.)
124      * @param transferType
125      * the current transfer type
126      * @return A status indicating whether the drop is valid.
127      */
128     public abstract IStatus validateDrop(Object JavaDoc target, int operation,
129             TransferData transferType);
130
131     /**
132      * Carry out the DND operation.
133      *
134      * @param aDropAdapter
135      * The Drop Adapter contains information that has already been
136      * parsed from the drop event.
137      * @param aDropTargetEvent
138      * The drop target event.
139      * @param aTarget
140      * The object being dragged onto
141      * @return A status indicating whether the drop completed OK.
142      */
143     public abstract IStatus handleDrop(CommonDropAdapter aDropAdapter,
144             DropTargetEvent aDropTargetEvent, Object JavaDoc aTarget);
145
146     /**
147      * Clients may extend the supported transfer types beyond the default
148      * {@link LocalSelectionTransfer#getTransfer()} and
149      * {@link org.eclipse.ui.part.PluginTransfer#getInstance()} transfer types. When a transfer type
150      * other than one of these is encountered, the DND Service will query the
151      * <b>visible</b> and <b>active</b> descriptors that are <b>enabled</b>
152      * for the drop target of the current operation.
153      *
154      * @param aTransferType
155      * The transfer data from the drop operation
156      * @return True if the given TransferData can be understood by this
157      * assistant.
158      */
159     public boolean isSupportedType(TransferData aTransferType) {
160         return LocalSelectionTransfer.getTransfer().isSupportedType(
161                 aTransferType);
162     }
163
164     /**
165      *
166      * Return true if the client can handle the drop onto the target viewer of
167      * the drop operation.
168      * <p>
169      * The default behavior of this method is to return <b>Status.CANCEL_STATUS</b>.
170      * </p>
171      *
172      * @param aDragSelection
173      * The selection dragged from the viewer.
174      * @param aDropTarget
175      * The target of the drop operation.
176      *
177      * @return OK if the plugin transfer can be handled by this assistant.
178      */
179     public IStatus validatePluginTransferDrop(
180             IStructuredSelection aDragSelection, Object JavaDoc aDropTarget) {
181         return Status.CANCEL_STATUS;
182     }
183
184     /**
185      * Handle the drop operation for the target viewer.
186      * <p>
187      * The default behavior of this method is to return <b>Status.CANCEL_STATUS</b>.
188      * </p>
189      *
190      * @param aDragSelection
191      * The selection dragged from the viewer.
192      * @param aDropTarget
193      * The target of the drop operation.
194      *
195      * @return OK if the drop operation succeeded.
196      */
197     public IStatus handlePluginTransferDrop(
198             IStructuredSelection aDragSelection, Object JavaDoc aDropTarget) {
199         return Status.CANCEL_STATUS;
200     }
201
202     /**
203      *
204      * @return The associated content service.
205      */
206     protected INavigatorContentService getContentService() {
207         return contentService;
208     }
209
210     /**
211      *
212      * @return A shell for the viewer currently used by the
213      * {@link INavigatorContentService}.
214      */
215     protected final Shell getShell() {
216         return ((NavigatorContentService) contentService).getShell();
217     }
218
219 }
220
Popular Tags