001/* A drop target for the ptolemy editor.
002
003 Copyright (c) 1999-2016 The Regents of the University of California.
004 All rights reserved.
005 Permission is hereby granted, without written agreement and without
006 license or royalty fees, to use, copy, modify, and distribute this
007 software and its documentation for any purpose, provided that the above
008 copyright notice and the following two paragraphs appear in all copies
009 of this software.
010
011 IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
012 FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
013 ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
014 THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
015 SUCH DAMAGE.
016
017 THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
018 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
019 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
020 PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
021 CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
022 ENHANCEMENTS, OR MODIFICATIONS.
023
024 PT_COPYRIGHT_VERSION_2
025 COPYRIGHTENDKEY
026
027 */
028package ptolemy.vergil.basic;
029
030import java.awt.dnd.DropTarget;
031import java.awt.dnd.DropTargetListener;
032import java.util.Vector;
033
034import diva.graph.JGraph;
035import ptolemy.kernel.util.InternalErrorException;
036
037///////////////////////////////////////////////////////////////////
038//// EditorDropTarget
039
040/**
041 This class provides drag-and-drop support. When this drop target
042 receives a transferable object containing a ptolemy object, it creates
043 a new instance of the object, and adds it to the given graph.
044 If the drop location falls on top of an icon associated with an
045 instance of NamedObj, then the object may be deposited inside that
046 instance (so the instance becomes its container). If the object being
047 dropped implements the {@link RelativeLocatable} marker interface,
048 then instead of dropping it inside the target object, it is dropped
049 into the container of the target object and assigned a location relative
050 to the target object. If the drop location is not on top of any object, then
051 the object is deposited inside the model associated with the
052 target graph. In any case, if the target container implements
053 the DropListener interface, then it is informed of the drop by
054 calling its dropped() method.
055 <p>
056 Sometimes, you will want to disable the feature that a drop
057 onto a NamedObj results in the dropped object being placed inside
058 that NamedObj.  To disable this feature, call setDropIntoEnabled()
059 with a false argument.
060
061 @author Steve Neuendorffer and Edward A. Lee, Contributor: Michael Shilman and Sven Koehler
062 @version $Id$
063 @since Ptolemy II 2.0
064 @Pt.ProposedRating Red (eal)
065 @Pt.AcceptedRating Red (johnr)
066 */
067@SuppressWarnings("serial")
068public class EditorDropTarget extends DropTarget {
069
070    /** Construct a new graph target to operate on the given JGraph.
071     */
072    public EditorDropTarget() {
073        // Nullary constructor so that derived classes may extend this
074        // class.
075    }
076
077    /** Construct a new graph target to operate on the given JGraph.
078     *  @param graph The diva graph panel.
079     */
080    public EditorDropTarget(JGraph graph) {
081        setComponent(graph);
082
083        try {
084            EditorDropTargetListener listener = new EditorDropTargetListener();
085            listener.setDropTarget(this);
086            addDropTargetListener(listener);
087        } catch (java.util.TooManyListenersException ex) {
088            throw new InternalErrorException(ex);
089        }
090    }
091
092    ///////////////////////////////////////////////////////////////////
093    ////                         public methods                    ////
094
095    /** Remove an additional listener.
096     *  @param listener The DropTargetListener to be removed.
097     */
098    public void deRegisterAdditionalListener(DropTargetListener listener) {
099        _additionalListeners.remove(listener);
100    }
101
102    /** Return true if the feature is enabled that a a drop onto an
103     *  instance of NamedObj results in that NamedObj containing the
104     *  dropped object. Otherwise, return false.
105     *  @return True if drop into is enabled.
106     */
107    public boolean isDropIntoEnabled() {
108        return _dropIntoEnabled;
109    }
110
111    /** Register additional DropTargetListeners.
112     *  @param listener The DropTargetListener to be added.
113     */
114    public void registerAdditionalListener(DropTargetListener listener) {
115        _additionalListeners.addElement(listener);
116    }
117
118    /** If the argument is false, then disable the feature that a
119     *  a drop onto an instance of NamedObj results in that NamedObj
120     *  containing the dropped object.  If the argument is true, then
121     *  reenable the feature.  The feature is enabled by default.
122     *  @param enabled False to disable the drop into feature.
123     */
124    public void setDropIntoEnabled(boolean enabled) {
125        _dropIntoEnabled = enabled;
126    }
127
128    /** Return the Vector of listeners that have been registered.
129     *  @return The listeners that have been registered with
130     *  {@link #registerAdditionalListener(DropTargetListener)}.
131     */
132    public Vector<DropTargetListener> getAdditionalListeners() {
133        return _additionalListeners;
134    }
135
136    ///////////////////////////////////////////////////////////////////
137    ////                         private variables                 ////
138
139    /** Vector to contain additional listeners. */
140    private Vector<DropTargetListener> _additionalListeners = new Vector<DropTargetListener>();
141
142    /** Flag indicating whether drop into is enabled. */
143    private boolean _dropIntoEnabled = true;
144}