jdk/src/share/classes/java/awt/dnd/package.html - edge/openjdk - Git at Google


            
            <!--

            
             Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.

            
             DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.


             This code is free software; you can redistribute it and/or modify it

            
             under the terms of the GNU General Public License version 2 only, as

            
             published by the Free Software Foundation.  Oracle designates this

            
             particular file as subject to the "Classpath" exception as provided

            
             by Oracle in the LICENSE file that accompanied this code.


             This code is distributed in the hope that it will be useful, but WITHOUT

            
             ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

            
             FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

            
             version 2 for more details (a copy is included in the LICENSE file that

            
             accompanied this code).


             You should have received a copy of the GNU General Public License version

            
             2 along with this work; if not, write to the Free Software Foundation,

            
             Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.


             Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

            
             or visit www.oracle.com if you need additional information or have any

            
             questions.

            
            -->


            <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

            
            <html>

            
            <head><title></title></head>

            
            <body bgcolor="white">


            Drag and Drop is a direct manipulation gesture found in many Graphical

            
            User Interface systems that provides a mechanism to transfer

            
            information between two entities logically associated with presentation

            
            elements in the GUI. Normally driven by a physical gesture of a

            
            human user using an appropriate input device, Drag and Drop provides both

            
            a mechanism to enable continuous feedback regarding the

            
            possible outcome of any subsequent data transfer to the user during

            
            navigation over the presentation elements in the GUI, and the facilities

            
            to provide for any subsequent data negotiation and transfer.

            
            <P>

            
            This package defines the classes and interfaces necessary to perform Drag

            
            and Drop operations in Java. It

            
            defines classes for the drag-source and the drop-target, as well as

            
            events for transferring the data being dragged. This package also provides

            
            a means for giving visual feedback to the user throughout the

            
            duration of the Drag and Drop operation.

            
            <P>

            
            A typical Drag and Drop operation can be decomposed into the following

            
            states (not entirely sequentially):

            
            <UL>

            
            <LI>A <code>DragSource</code> comes into existence,

            
            associated with some presentation

            
            element (<code>Component</code>) in the GUI, to initiate a Drag and Drop of

            
            some potentially <code>Transferable</code> data.

            
            <br><br>

            
            <LI>1 or more <code>DropTarget</code>(s) come into/go out of

            
            existence, associated

            
            with presentation elements in the GUI (Components), potentially

            
            capable of consuming <code>Transferable</code> data types.

            
            <br><br>

            
            <LI> A <code>DragGestureRecognizer</code> is

            
            obtained from the <code>DragSource</code> and is

            
            associated with a <code>Component</code> in order

            
            to track and identify any Drag

            
            initiating gesture by the user over the <code>Component</code>.

            
            <br><br>

            
            <LI> A user makes a Drag gesture over the <code>Component</code>,

            
            which the registered

            
            <code>DragGestureRecognizer</code> detects, and notifies its

            
            <code>DragGestureListener</code> of.

            
            <P>

            
            Note: Although this API consistently refers to the stimulus for a

            
            drag and drop operation being a physical gesture by a human user, this

            
            does not preclude a programmatically driven DnD operation given the

            
            appropriate implementation of a <code>DragSource</code>. This package

            
            contains the abstract class <code>MouseDragGestureRecognizer</code> for

            
            recognizing mouse device gestures. Other abstract subclasses may be

            
            provided by the platform to support other input devices or

            
            particular <code>Component</code> class semantics.

            
            <br><br>

            
            <LI> The <code>DragGestureListener</code> causes the

            
            <code>DragSource</code> to initiate the Drag

            
            and Drop operation on behalf of the user, perhaps animating the

            
            GUI Cursor and/or rendering an <code>Image</code> of the item(s) that are the

            
            subject of the operation.

            
            <br><br>

            
            <LI> As the user gestures navigate over <code>Component</code>(s)

            
            in the GUI with

            
            associated <code>DropTarget</code>(s), the <code>DragSource</code>

            
            receives notifications in order

            
            to provide "Drag Over" feedback effects, and the <code>DropTarget</code>(s)

            
            receive notifications in order to provide "Drag Under" feedback effects

            
            based upon the operation(s) supported and the data type(s) involved.

            
            </UL>

            
            <P>


            The gesture itself moves a logical cursor across the GUI hierarchy,

            
            intersecting the geometry of GUI Component(s), possibly resulting in

            
            the logical "Drag" cursor entering, crossing, and subsequently

            
            leaving <code>Component</code>(s) and associated <code>DropTarget</code>(s).

            
            <P>

            
            The <code>DragSource</code> object manifests "Drag Over" feedback to the user, in the typical case by animating the GUI <code>Cursor</code> associated with the

            
            logical cursor.

            
            <P>

            
            <code>DropTarget</code> objects manifest "Drag Under" feedback to the user, in

            
            the typical case, by rendering animations into their associated GUI

            
            <code>Component</code>(s) under the GUI Cursor.

            
            <P>

            
            The determination of the feedback effects, and the ultimate success

            
            or failure of the data transfer, should one occur, is parameterized

            
            as follows:

            
            <UL>

            
            <LI> By the transfer "operation" selected by the user, and supported by

            
            both the <code>DragSource</code> and <code>DropTarget</code>: Copy, Move or Reference(link).

            
            <br><br>

            
            <LI> By the intersection of the set of data types provided by the

            
            <code>DragSource</code> and the set of data types comprehensible by the

            
            <code>DropTarget</code>.

            
            <br><br>

            
            <LI>When the user terminates the drag operation, normally resulting in a

            
            successful Drop, both the <code>DragSource</code> and <code>DropTarget</code>

            
            receive

            
            notifications that include, and result in the type negotiation and

            
            transfer of, the information associated with the <code>DragSource</code> via a

            
            <code>Transferable</code> object.

            
            </UL>


            <!--

            
            <h2>Package Specification</h2>


            ##### FILL IN ANY SPECS NEEDED BY JAVA COMPATIBILITY KIT #####

            
            <ul>

            
              <li><a href="">##### REFER TO ANY FRAMEMAKER SPECIFICATION HERE #####</a>

            
            </ul>


            <h2>Related Documentation</h2>


            For overviews, tutorials, examples, guides, and tool documentation, please see:

            
            <ul>

            
              <li><a href="">##### REFER TO NON-SPEC DOCUMENTATION HERE #####</a>

            
            </ul>

            
            -->


            @since 1.2

            
            </body>

            
            </html>
	<!--
	Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
	DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

	This code is free software; you can redistribute it and/or modify it
	under the terms of the GNU General Public License version 2 only, as
	published by the Free Software Foundation. Oracle designates this
	particular file as subject to the "Classpath" exception as provided
	by Oracle in the LICENSE file that accompanied this code.

	This code is distributed in the hope that it will be useful, but WITHOUT
	ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
	version 2 for more details (a copy is included in the LICENSE file that
	accompanied this code).

	You should have received a copy of the GNU General Public License version
	2 along with this work; if not, write to the Free Software Foundation,
	Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

	Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	or visit www.oracle.com if you need additional information or have any
	questions.
	-->

	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
	<html>
	<head><title></title></head>
	<body bgcolor="white">

	Drag and Drop is a direct manipulation gesture found in many Graphical
	User Interface systems that provides a mechanism to transfer
	information between two entities logically associated with presentation
	elements in the GUI. Normally driven by a physical gesture of a
	human user using an appropriate input device, Drag and Drop provides both
	a mechanism to enable continuous feedback regarding the
	possible outcome of any subsequent data transfer to the user during
	navigation over the presentation elements in the GUI, and the facilities
	to provide for any subsequent data negotiation and transfer.
	<P>
	This package defines the classes and interfaces necessary to perform Drag
	and Drop operations in Java. It
	defines classes for the drag-source and the drop-target, as well as
	events for transferring the data being dragged. This package also provides
	a means for giving visual feedback to the user throughout the
	duration of the Drag and Drop operation.
	<P>
	A typical Drag and Drop operation can be decomposed into the following
	states (not entirely sequentially):
	<UL>
	<LI>A <code>DragSource</code> comes into existence,
	associated with some presentation
	element (<code>Component</code>) in the GUI, to initiate a Drag and Drop of
	some potentially <code>Transferable</code> data.
	<br><br>
	<LI>1 or more <code>DropTarget</code>(s) come into/go out of
	existence, associated
	with presentation elements in the GUI (Components), potentially
	capable of consuming <code>Transferable</code> data types.
	<br><br>
	<LI> A <code>DragGestureRecognizer</code> is
	obtained from the <code>DragSource</code> and is
	associated with a <code>Component</code> in order
	to track and identify any Drag
	initiating gesture by the user over the <code>Component</code>.
	<br><br>
	<LI> A user makes a Drag gesture over the <code>Component</code>,
	which the registered
	<code>DragGestureRecognizer</code> detects, and notifies its
	<code>DragGestureListener</code> of.
	<P>
	Note: Although this API consistently refers to the stimulus for a
	drag and drop operation being a physical gesture by a human user, this
	does not preclude a programmatically driven DnD operation given the
	appropriate implementation of a <code>DragSource</code>. This package
	contains the abstract class <code>MouseDragGestureRecognizer</code> for
	recognizing mouse device gestures. Other abstract subclasses may be
	provided by the platform to support other input devices or
	particular <code>Component</code> class semantics.
	<br><br>
	<LI> The <code>DragGestureListener</code> causes the
	<code>DragSource</code> to initiate the Drag
	and Drop operation on behalf of the user, perhaps animating the
	GUI Cursor and/or rendering an <code>Image</code> of the item(s) that are the
	subject of the operation.
	<br><br>
	<LI> As the user gestures navigate over <code>Component</code>(s)
	in the GUI with
	associated <code>DropTarget</code>(s), the <code>DragSource</code>
	receives notifications in order
	to provide "Drag Over" feedback effects, and the <code>DropTarget</code>(s)
	receive notifications in order to provide "Drag Under" feedback effects
	based upon the operation(s) supported and the data type(s) involved.
	</UL>
	<P>

	The gesture itself moves a logical cursor across the GUI hierarchy,
	intersecting the geometry of GUI Component(s), possibly resulting in
	the logical "Drag" cursor entering, crossing, and subsequently
	leaving <code>Component</code>(s) and associated <code>DropTarget</code>(s).
	<P>
	The <code>DragSource</code> object manifests "Drag Over" feedback to the user, in the typical case by animating the GUI <code>Cursor</code> associated with the
	logical cursor.
	<P>
	<code>DropTarget</code> objects manifest "Drag Under" feedback to the user, in
	the typical case, by rendering animations into their associated GUI
	<code>Component</code>(s) under the GUI Cursor.
	<P>
	The determination of the feedback effects, and the ultimate success
	or failure of the data transfer, should one occur, is parameterized
	as follows:
	<UL>
	<LI> By the transfer "operation" selected by the user, and supported by
	both the <code>DragSource</code> and <code>DropTarget</code>: Copy, Move or Reference(link).
	<br><br>
	<LI> By the intersection of the set of data types provided by the
	<code>DragSource</code> and the set of data types comprehensible by the
	<code>DropTarget</code>.
	<br><br>
	<LI>When the user terminates the drag operation, normally resulting in a
	successful Drop, both the <code>DragSource</code> and <code>DropTarget</code>
	receive
	notifications that include, and result in the type negotiation and
	transfer of, the information associated with the <code>DragSource</code> via a
	<code>Transferable</code> object.
	</UL>

	<!--
	<h2>Package Specification</h2>

	##### FILL IN ANY SPECS NEEDED BY JAVA COMPATIBILITY KIT #####
	<ul>
	<li><a href="">##### REFER TO ANY FRAMEMAKER SPECIFICATION HERE #####</a>
	</ul>

	<h2>Related Documentation</h2>

	For overviews, tutorials, examples, guides, and tool documentation, please see:
	<ul>
	<li><a href="">##### REFER TO NON-SPEC DOCUMENTATION HERE #####</a>
	</ul>
	-->

	@since 1.2
	</body>
	</html>