intro.html

jsf、swing的官方指南

     and begin to drag.
     Initially, on Microsoft Windows, you see the 
<IMG SRC="../../figures/uiswing/dnd/no.gif" WIDTH="20" HEIGHT="20" ALT="Copy cursor icon for Windows, the component won't accept."> cursor icon.
     This indicates that the area below the cursor, in this
     case the list itself, does not accept drops.
<li> Drag the cursor over a text area.  The cursor
     icon now changes to
<IMG SRC="../../figures/uiswing/dnd/win32_CopyDrop.gif" WIDTH="23" HEIGHT="32" ALT="Copy cursor icon for Windows, the component below accepts the drop.">. This text area will accept the data if you release the
     mouse button.
<li> As you can see in the <a href=#cursorIconTable>cursor icon
     table</a>, the Copy cursor icon
     gives you a visual clue that it will not disturb
     the contents of the original component.  In the case
     of Microsoft Windows, the clue is the small + sign.
<li> Drag the selected text over a text area. The insertion
     point for the text is indicated by a blinking cursor.
<li> Release the mouse and watch the text appear in the text area.
<li> Select some text in one of the text areas.
<li> Press and hold the mouse button while the cursor is
     over the selected text and begin to drag.
<li> Note that this time, the
<IMG SRC="../../figures/uiswing/dnd/win32_MoveDrop.gif" WIDTH="16" HEIGHT="27" ALT="Move cursor icon for Windows, the component accepts the drop."> icon appears.
     This indicates that the drag is a Move and will remove the
     text from the original component on a successful drop.
<li> Release the mouse button over an area that will not
     accept it.  The original text is undisturbed.
<li> Hold the Control key down and press again on the selected
     text.  The Copy icon now appears.
     Move the cursor over the text area and drop. The text
     appears in the new location but is not removed from the
     original location.
     The Control key can be used to change any Move to a Copy.
<li> Select a color from the color chooser. The selected color
     appears in the Preview panel.  Press and hold the mouse button
     over the color in the Preview panel and drag it over the
     other components.  Note that none of the components
     accepts color by default.  
<li> Play with dragging and dropping between the various components
     and note which components accept data.
</ol>
<hr></blockquote>

<p>When the <em>Turn drag and drop on</em> check box is checked,
<code>BasicDnD</code> demonstrates drag and drop behavior
that becomes available to a component with the following
line of code:

<blockquote><pre>
component.setDragEnabled(true);
</pre></blockquote>

Many components support cut/copy/paste of text using
the keyboard bindings Control-X, Control-C, and Control-V, respectively. 
This is because a <code>JTextComponent</code> installs the
cut/copy/paste key bindings
and action map when it is created.  You only need to add a bit more
code to create a menu with Cut, Copy and Paste menu items and
tie those items to the default text support.
We show you how to do that in the
<a href=#replacingSupport><code>DragColorTextFieldDemo</code></a> example.
Cut/copy/paste is further discussed in <a href=#cut>Adding
Cut/Copy/Paste Support</a>.

<p>
At the heart of the data transfer mechanism is the
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/javax/swing/TransferHandler.html"><code>TransferHandler</code></a> class.  A <code>TransferHandler</code> provides
an easy mechanism for transferring data to and from a
<code>JComponent</code>.  The data to be transferred is bundled
up into an object that implements the
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/java/awt/datatransfer/Transferable.html"><code>Transferable</code></a> interface.  The components in the
<a href=#defaultSupport>data transfer support table</a>
are provided with default transfer handlers, but a transfer
handler can be created and installed on any component using
the <code>JComponent</code> method <code>setTransferHandler</code>:

<blockquote><pre>
component.setTransferHandler(new MyTransferHandler());
</pre></blockquote>

<a name=customGotcha><p></a>
The default Swing transfer handlers, such as those used
by text components and the color chooser, provide the support 
considered to be most useful for
both importing and exporting of data.  If you install a custom
<code>TransferHandler</code> onto a Swing component,
the default support is replaced.  For example,
if you replace <code>JTextField</code>'s
<code>TransferHandler</code> with one that handles colors only,
you'll disable its ability to support import and export of text.

<p>This means that if you must replace a default
<code>TransferHandler</code> &#151; for example, one that handles
text &#151; you'll need to re-implement the text import and export ability. 
This does not need to be as extensive as what Swing provides &#151;
it could be as simple as supporting the <code>StringFlavor</code> data
flavor, depending on your application's needs.
The <a href=#replacingSupport><code>DragColorTextFieldDemo</code></a>
gives an example of this.  You might also want to watch RFE
<a class="OutsideLink" target="_blank" href="http://developer.java.sun.com/developer/bugParade/bugs/4830695.html">#4830695</a>, which requests the ability to add data import
on top of an existing <code>TransferHandler</code>.

<p>The remainder of this document describes how to use data transfer
in a variety of ways. Here is a list of some common scenarios and
where in the document you can find more information:

<dl>
<dt>How do I provide drop support for those components
    in the <a href=#defaultSupport>Data Transfer Support</a> table
    that do not have a check-mark in the drop column?
<dd>You need to implement a custom transfer handler to
    provide drop support.
    See <a href=#complex>Extending Default DnD Support</a>
    for an example of how this is done.
<p>
<dt>I want my component to import only.  How do I do that?
<dd>You need to provide a custom transfer handler with
    implementations for the <code>canImport</code> and
    <code>importData</code> methods.  The <code>DragColorDemo</code>
    example in <a href=#customImport>Importing a New Flavor:
    Color</a> does this.
<p>
<dt>How do I create a component that can accept multiple
    types of data?
<dd>A transfer handler can be created to accept more than one
    type of data.  <a href=#replacingSupport>Replacing Default
    Support: Color and Text</a> shows the example,
    DragColorTextFieldDemo, which installs a custom transfer
    handler on a <code>JTextField</code> to import both
    color and text, and export text. Also, the
    <code>DragFileDemo</code> in <a href=#importFiles>
    Importing a New Flavor: Files</a> installs a transfer
    handler on the text area/tabbed pane that imports both files
    and strings.
<p>
<dt>How do I create a custom transfer handler to import/export
    a non-standard type of data?
<dd><a href=#dataFormat>Specifying the Data Format</a> describes
    how to create a data flavor with a variety of data types.
    Also, the DragListDemo example in <a href=#customFlavor>
    Data Transfer with a Custom DataFlavor</a> shows how
    to transfer data in the <code>ArrayList</code> format.
<p>
<dt>How do I make data transfer work with my custom component?
<dd><a href=#customComp>Data Transfer with a Custom Component</a>
    discusses the requirements of making a custom component work
    with the data transfer system.
<p>
<dt>How do I enable the cut/copy/paste bindings?
<dd><a href=#cut>Adding Cut/Copy/Paste Support</a>
    describes how to enable the built-in cut/copy/paste support
    for text components.  Implementing cut/copy/paste for
    non-text components is also covered.
<p>
<dt>How do I obtain the drop position in the destination
    component?
<dd>You can obtain the drop location by way of the component's
    selection.  You'll notice that the selection changes in a component
    as you drag over it.  For lists, tables, and trees you can query
    the current selection at drop time to find the drop position.
    For text components, you can query the position of the caret.
    There is an example of this in
    <a href=examples/ArrayListTransferHandler.java>
    ArrayListTransferHandler</a>, part of the
    <a href=examples/DragListDemo.java>DragListDemo</a> example. 
    You might also want to watch RFE 
<a class="OutsideLink" target="_blank" href="http://developer.java.sun.com/developer/bugParade/bugs/4468566.html">#4468566</a>, which requests a better way of indicating (and displaying)
the drop location without changing the selection.
</dl>

<p>This has been a brief introduction to the Swing data transfer
mechanism.  If you want more details, see the
<a class="OutsideLink" target="_blank" href="http://java.sun.com/j2se/1.4.1/docs/guide/swing/1.4/dnd.html">Swing Data Transfer</a> document in the release notes for your particular J2SE release.

<p>

</blockquote>
<a name=label>
<h2>A Simple Example: Adding DnD to JLabel</h2></a>
<blockquote>

<p>
The <code>JLabel</code> component does not, by default, 
support drag or drop,
but it is a fairly simple exercise to add this support &#151;
the following demo shows how to do this.

<p><center><IMG SRC="../../figures/uiswing/dnd/LabelDnD.png" WIDTH="319" HEIGHT="136" ALIGN="BOTTOM" ALT="The LabelDnD example"></center></p>
<blockquote><hr><strong>Try this:</strong>&nbsp;<ol>
<li> <a href="http://java.sun.com/docs/books/tutorialJWS/uiswing/misc/examples/LabelDnD.jnlp">Run
     LabelDnD</a> using
     <a href=http://java.sun.com/products/javawebstart>
     Java Web Start</a>.
     Or, to compile and run the example yourself,
     consult the
     <a href="examples/index.html#LabelDnD">example index</a>.
<li> Press and hold the mouse button while the cursor is over
     the label.  As you begin to move the cursor the Copy cursor
     icon appears.
     Drop the text onto the text field.
<li> Type text into the text field.  Select and initiate the
     drag using the mouse. The Move cursor icon appears because
     the default behavior for text field is Move.
     Drop the text onto the label and note that the selected string
     has been removed from the original text.
<li> Type more text into the text field, if necessary, and select.
     While holding down the Control key, drag the text. 
     The Copy cursor icon appears.  Drop the text as desired.
</ol>
<hr></blockquote>

<p>While it is possible to extend this
example to show copy and paste, note that <code>JLabel</code>
does not have bindings for copy and paste and does not, by default,
receive the focus that is required to support this feature.

<p>The entire example can be found in
<a class="SourceLink" target="_blank" href="examples/LabelDnD.java"><code>LabelDnD.java</code></a>. Here is the code that creates the label and installs
a transfer handler on the label:

<blockquote><pre>
label = new JLabel("I'm a Label!", SwingConstants.LEADING);
label.setTransferHandler(new TransferHandler("text"));

MouseListener listener = new DragMouseAdapter();
label.addMouseListener(listener);
</pre></blockquote>

<p>To add drag support to <code>JLabel</code> or any
custom component, you must add the ability to detect 
activity on the mouse.  <code>LabelDnD</code> implements
a mouse listener to detect mouse pressed &#151; when the
mouse is pressed, the transfer handler initiates the
drag from the label by invoking <code>exportAsDrag</code>
with the Copy argument:

<blockquote><pre>
public class DragMouseAdapter extends MouseAdapter {
    public void mousePressed(MouseEvent e) {
        JComponent c = (JComponent)e.getSource();
        TransferHandler handler = c.getTransferHandler();
        handler.exportAsDrag(c, e, TransferHandler.COPY);
    }
}
</pre></blockquote>

<p>
To find what the call to 
<blockquote><pre>
new TransferHandler("text")
</pre></blockquote>
 does, see 
<a href=#dataFormat>Specifying the Data Format</a>.

</blockquote>
<a name=complex>
<h2>Extending Default DnD Support</h2></a>
<blockquote>

<p>
You've seen in the <a href=#defaultSupport>Data Transfer Support table</a>
that several components do not support drop by default. 
The reason for this is that there is no all-purpose way to handle
a drop on those components.
For example, what does it mean to drop on a particular node of
a <code>JTree</code>?  Does it replace the node, insert below it,
or insert as a child of that node? 
Also, we don't know what type of model is
behind the tree &#151; it might not be mutable.  However, while Swing
doesn't provide a default implementation, the framework for
drop is there.  You need only to provide a custom
<code>TransferHandler</code>
that deals with the actual transfer of data.

<p>The following example, <code>ExtendedDnDDemo</code>,
tweaks the default drag and drop behavior for
two components, <code>JList</code> and <code>JTable</code>. 
This demo shows how to:

<ul>
<li> Drop text onto a <code>JList</code> &#151; the incoming
     string can be newline-delimited so that a new list item
     is created at each new line.
<li> Move data from a <code>JList</code> (the default Swing behavior is Copy).
     On export, multiple list items are separated by newlines.
<li> Drop text onto a <code>JTable</code> &#151; the incoming
     string can be newline <i>and</i> comma-delimited. Strings
     are split into rows at newlines, and into columns at commas.
<li> Move data from a <code>JTable</code> (the default Swing behavior is Copy).
     On export, multiple table rows are separated by newlines,
     and table columns are separated by commas.
</ul>

<p>
If you've run the <code>BasicDnD</code> example previously, you'll
see that this tweaked behavior is slightly different than the
default Swing behavior which does not use commas as a separator.

<p><center><IMG SRC="../../figures/uiswing/dnd/ExtendedDnDDemo.png" WIDTH="418" HEIGHT="412" ALIGN="BOTTOM" ALT="The ExtendedDnDDemo example"></center></p>
<blockquote><hr><strong>Try this:</strong>&nbsp;<ol>
<li> <a href="http://java.sun.com/docs/books/tutorialJWS/uiswing/misc/examples/ExtendedDnDDemo.jnlp">Run
     ExtendedDnDDemo</a> using
     <a href=http://java.sun.com/products/javawebstart>
     Java Web Start</a>.
     Or, to compile and run the example yourself, consult the
     <a href="examples/index.html#ExtendedDnDDemo">example index</a>.
<li> Select a row in the table
<li> Press the row again and drag. As you drag the cursor
     icon over the list, the row that is currently under
     the cursor highlights &#151; the new data will be
     inserted after the selected row.
<li> Drop the row onto
     the list.  Note that the row has been removed from the
     table, and now appears in the list with commas separating
     the columns.
<li> Select two rows from the table and drop onto the list.
     Now there are two new items in the list with commas
     separating the columns.
<li> Select one of the items in the list and drag it to the table. 
     As you drag the icon over the table, the row that is under
     the curson highlights &#151; the new data will be inserted
     after the selected row.