< prev index next >

src/java.desktop/share/classes/javax/swing/TransferHandler.java

Print this page

        

@@ -51,30 +51,30 @@
 import jdk.internal.misc.JavaSecurityAccess;
 
 import sun.awt.AWTAccessor;
 
 /**
- * This class is used to handle the transfer of a <code>Transferable</code>
- * to and from Swing components.  The <code>Transferable</code> is used to
+ * This class is used to handle the transfer of a {@code Transferable}
+ * to and from Swing components.  The {@code Transferable} is used to
  * represent data that is exchanged via a cut, copy, or paste
  * to/from a clipboard.  It is also used in drag-and-drop operations
  * to represent a drag from a component, and a drop to a component.
  * Swing provides functionality that automatically supports cut, copy,
  * and paste keyboard bindings that use the functionality provided by
  * an implementation of this class.  Swing also provides functionality
  * that automatically supports drag and drop that uses the functionality
  * provided by an implementation of this class.  The Swing developer can
  * concentrate on specifying the semantics of a transfer primarily by setting
- * the <code>transferHandler</code> property on a Swing component.
+ * the {@code transferHandler} property on a Swing component.
  * <p>
  * This class is implemented to provide a default behavior of transferring
  * a component property simply by specifying the name of the property in
  * the constructor.  For example, to transfer the foreground color from
  * one component to another either via the clipboard or a drag and drop operation
- * a <code>TransferHandler</code> can be constructed with the string "foreground".  The
- * built in support will use the color returned by <code>getForeground</code> as the source
- * of the transfer, and <code>setForeground</code> for the target of a transfer.
+ * a {@code TransferHandler} can be constructed with the string "foreground".  The
+ * built in support will use the color returned by {@code getForeground} as the source
+ * of the transfer, and {@code setForeground} for the target of a transfer.
  * <p>
  * Please see
  * <a href="http://docs.oracle.com/javase/tutorial/uiswing/dnd/index.html">
  * How to Use Drag and Drop and Data Transfer</a>,
  * a section in <em>The Java Tutorial</em>, for more information.

@@ -86,36 +86,36 @@
  */
 @SuppressWarnings("serial")
 public class TransferHandler implements Serializable {
 
     /**
-     * An <code>int</code> representing no transfer action.
+     * An {@code int} representing no transfer action.
      */
     public static final int NONE = DnDConstants.ACTION_NONE;
 
     /**
-     * An <code>int</code> representing a &quot;copy&quot; transfer action.
+     * An {@code int} representing a "copy" transfer action.
      * This value is used when data is copied to a clipboard
      * or copied elsewhere in a drag and drop operation.
      */
     public static final int COPY = DnDConstants.ACTION_COPY;
 
     /**
-     * An <code>int</code> representing a &quot;move&quot; transfer action.
+     * An {@code int} representing a "move" transfer action.
      * This value is used when data is moved to a clipboard (i.e. a cut)
      * or moved elsewhere in a drag and drop operation.
      */
     public static final int MOVE = DnDConstants.ACTION_MOVE;
 
     /**
-     * An <code>int</code> representing a source action capability of either
-     * &quot;copy&quot; or &quot;move&quot;.
+     * An {@code int} representing a source action capability of either
+     * "copy" or "move".
      */
     public static final int COPY_OR_MOVE = DnDConstants.ACTION_COPY_OR_MOVE;
 
     /**
-     * An <code>int</code> representing a &quot;link&quot; transfer action.
+     * An {@code int} representing a "link" transfer action.
      * This value is used to specify that data should be linked in a drag
      * and drop operation.
      *
      * @see java.awt.dnd.DnDConstants#ACTION_LINK
      * @since 1.6

@@ -140,12 +140,12 @@
      * Components supporting drop may provide subclasses of this
      * containing more information.
      * <p>
      * Developers typically shouldn't create instances of, or extend, this
      * class. Instead, these are something provided by the DnD
-     * implementation by <code>TransferSupport</code> instances and by
-     * components with a <code>getDropLocation()</code> method.
+     * implementation by {@code TransferSupport} instances and by
+     * components with a {@code getDropLocation()} method.
      *
      * @see javax.swing.TransferHandler.TransferSupport#getDropLocation
      * @since 1.6
      */
     public static class DropLocation {

@@ -155,11 +155,11 @@
          * Constructs a drop location for the given point.
          *
          * @param dropPoint the drop point, representing the mouse's
          *        current location within the component.
          * @throws IllegalArgumentException if the point
-         *         is <code>null</code>
+         *         is {@code null}
          */
         protected DropLocation(Point dropPoint) {
             if (dropPoint == null) {
                 throw new IllegalArgumentException("Point cannot be null");
             }

@@ -202,11 +202,11 @@
      * and drop, such as whether or not to show the drop location,
      * and which drop action to use.
      * <p>
      * Developers typically need not create instances of this
      * class. Instead, they are something provided by the DnD
-     * implementation to certain methods in <code>TransferHandler</code>.
+     * implementation to certain methods in {@code TransferHandler}.
      *
      * @see #canImport(TransferHandler.TransferSupport)
      * @see #importData(TransferHandler.TransferSupport)
      * @since 1.6
      */

@@ -227,32 +227,32 @@
         private Object source;
 
         private DropLocation dropLocation;
 
         /**
-         * Create a <code>TransferSupport</code> with <code>isDrop()</code>
-         * <code>true</code> for the given component, event, and index.
+         * Create a {@code TransferSupport} with {@code isDrop()}
+         * {@code true} for the given component, event, and index.
          *
          * @param component the target component
-         * @param event a <code>DropTargetEvent</code>
+         * @param event a {@code DropTargetEvent}
          */
         private TransferSupport(Component component,
                              DropTargetEvent event) {
 
             isDrop = true;
             setDNDVariables(component, event);
         }
 
         /**
-         * Create a <code>TransferSupport</code> with <code>isDrop()</code>
-         * <code>false</code> for the given component and
-         * <code>Transferable</code>.
+         * Create a {@code TransferSupport} with {@code isDrop()}
+         * {@code false} for the given component and
+         * {@code Transferable}.
          *
          * @param component the target component
          * @param transferable the transferable
          * @throws NullPointerException if either parameter
-         *         is <code>null</code>
+         *         is {@code null}
          */
         public TransferSupport(Component component, Transferable transferable) {
             if (component == null) {
                 throw new NullPointerException("component is null");
             }

@@ -268,11 +268,11 @@
 
         /**
          * Allows for a single instance to be reused during DnD.
          *
          * @param component the target component
-         * @param event a <code>DropTargetEvent</code>
+         * @param event a {@code DropTargetEvent}
          */
         private void setDNDVariables(Component component,
                                      DropTargetEvent event) {
 
             assert isDrop;

@@ -307,15 +307,15 @@
              * drop location will be created lazily when requested.
              */
         }
 
         /**
-         * Returns whether or not this <code>TransferSupport</code>
+         * Returns whether or not this {@code TransferSupport}
          * represents a drop operation.
          *
-         * @return <code>true</code> if this is a drop operation,
-         *         <code>false</code> otherwise.
+         * @return {@code true} if this is a drop operation,
+         *         {@code false} otherwise.
          */
         public boolean isDrop() {
             return isDrop;
         }
 

@@ -539,11 +539,11 @@
         }
 
         /**
          * Returns whether or not the given data flavor is supported.
          *
-         * @param df the <code>DataFlavor</code> to test
+         * @param df the {@code DataFlavor} to test
          * @return whether or not the given flavor is supported.
          */
         public boolean isDataFlavorSupported(DataFlavor df) {
             if (isDrop) {
                 if (source instanceof DropTargetDragEvent) {

@@ -555,18 +555,18 @@
 
             return ((Transferable)source).isDataFlavorSupported(df);
         }
 
         /**
-         * Returns the <code>Transferable</code> associated with this transfer.
+         * Returns the {@code Transferable} associated with this transfer.
          * <p>
-         * Note: Unless it is necessary to fetch the <code>Transferable</code>
+         * Note: Unless it is necessary to fetch the {@code Transferable}
          * directly, use one of the other methods on this class to inquire about
          * the transfer. This may perform better than fetching the
-         * <code>Transferable</code> and asking it directly.
+         * {@code Transferable} and asking it directly.
          *
-         * @return the <code>Transferable</code> associated with this transfer
+         * @return the {@code Transferable} associated with this transfer
          */
         public Transferable getTransferable() {
             if (isDrop) {
                 if (source instanceof DropTargetDragEvent) {
                     return ((DropTargetDragEvent)source).getTransferable();

@@ -621,11 +621,11 @@
      * Constructs a transfer handler that can transfer a Java Bean property
      * from one component to another via the clipboard or a drag and drop
      * operation.
      *
      * @param property  the name of the property to transfer; this can
-     *  be <code>null</code> if there is no property associated with the transfer
+     *  be {@code null} if there is no property associated with the transfer
      *  handler (a subclass that performs some other kind of transfer, for example)
      */
     public TransferHandler(String property) {
         propertyName = property;
     }

@@ -700,26 +700,26 @@
         return new Point(dragImageOffset);
     }
 
     /**
      * Causes the Swing drag support to be initiated.  This is called by
-     * the various UI implementations in the <code>javax.swing.plaf.basic</code>
+     * the various UI implementations in the {@code javax.swing.plaf.basic}
      * package if the dragEnabled property is set on the component.
      * This can be called by custom UI
      * implementations to use the Swing drag support.  This method can also be called
-     * by a Swing extension written as a subclass of <code>JComponent</code>
+     * by a Swing extension written as a subclass of {@code JComponent}
      * to take advantage of the Swing drag support.
      * <p>
      * The transfer <em>will not necessarily</em> have been completed at the
      * return of this call (i.e. the call does not block waiting for the drop).
      * The transfer will take place through the Swing implementation of the
-     * <code>java.awt.dnd</code> mechanism, requiring no further effort
-     * from the developer. The <code>exportDone</code> method will be called
+     * {@code java.awt.dnd} mechanism, requiring no further effort
+     * from the developer. The {@code exportDone} method will be called
      * when the transfer has completed.
      *
      * @param comp  the component holding the data to be transferred;
-     *              provided to enable sharing of <code>TransferHandler</code>s
+     *              provided to enable sharing of {@code TransferHandler}s
      * @param e     the event that triggered the transfer
      * @param action the transfer action initially requested;
      *               either {@code COPY}, {@code MOVE} or {@code LINK};
      *               the DnD system may change the action used during the
      *               course of the drag operation

@@ -750,29 +750,29 @@
     /**
      * Causes a transfer from the given component to the
      * given clipboard.  This method is called by the default cut and
      * copy actions registered in a component's action map.
      * <p>
-     * The transfer will take place using the <code>java.awt.datatransfer</code>
+     * The transfer will take place using the {@code java.awt.datatransfer}
      * mechanism, requiring no further effort from the developer. Any data
-     * transfer <em>will</em> be complete and the <code>exportDone</code>
+     * transfer <em>will</em> be complete and the {@code exportDone}
      * method will be called with the action that occurred, before this method
      * returns. Should the clipboard be unavailable when attempting to place
-     * data on it, the <code>IllegalStateException</code> thrown by
+     * data on it, the {@code IllegalStateException} thrown by
      * {@link Clipboard#setContents(Transferable, ClipboardOwner)} will
      * be propagated through this method. However,
-     * <code>exportDone</code> will first be called with an action
-     * of <code>NONE</code> for consistency.
+     * {@code exportDone} will first be called with an action
+     * of {@code NONE} for consistency.
      *
      * @param comp  the component holding the data to be transferred;
-     *              provided to enable sharing of <code>TransferHandler</code>s
+     *              provided to enable sharing of {@code TransferHandler}s
      * @param clip  the clipboard to transfer the data into
      * @param action the transfer action requested; this should
-     *  be a value of either <code>COPY</code> or <code>MOVE</code>;
+     *  be a value of either {@code COPY} or {@code MOVE};
      *  the operation performed is the intersection  of the transfer
      *  capabilities given by getSourceActions and the requested action;
-     *  the intersection may result in an action of <code>NONE</code>
+     *  the intersection may result in an action of {@code NONE}
      *  if the requested action isn't supported
      * @throws IllegalStateException if the clipboard is currently unavailable
      * @see Clipboard#setContents(Transferable, ClipboardOwner)
      */
     public void exportToClipboard(JComponent comp, Clipboard clip, int action)

@@ -797,30 +797,30 @@
         exportDone(comp, null, NONE);
     }
 
     /**
      * Causes a transfer to occur from a clipboard or a drag and
-     * drop operation. The <code>Transferable</code> to be
+     * drop operation. The {@code Transferable} to be
      * imported and the component to transfer to are contained
-     * within the <code>TransferSupport</code>.
+     * within the {@code TransferSupport}.
      * <p>
      * While the drag and drop implementation calls {@code canImport}
      * to determine the suitability of a transfer before calling this
      * method, the implementation of paste does not. As such, it cannot
      * be assumed that the transfer is acceptable upon a call to
      * this method for paste. It is recommended that {@code canImport} be
      * explicitly called to cover this case.
      * <p>
-     * Note: The <code>TransferSupport</code> object passed to this method
+     * Note: The {@code TransferSupport} object passed to this method
      * is only valid for the duration of the method call. It is undefined
      * what values it may contain after this method returns.
      *
      * @param support the object containing the details of
-     *        the transfer, not <code>null</code>.
+     *        the transfer, not {@code null}.
      * @return true if the data was inserted into the component,
      *         false otherwise
-     * @throws NullPointerException if <code>support</code> is {@code null}
+     * @throws NullPointerException if {@code support} is {@code null}
      * @see #canImport(TransferHandler.TransferSupport)
      * @since 1.6
      */
     public boolean importData(TransferSupport support) {
         return support.getComponent() instanceof JComponent

@@ -828,23 +828,23 @@
             : false;
     }
 
     /**
      * Causes a transfer to a component from a clipboard or a
-     * DND drop operation.  The <code>Transferable</code> represents
+     * DND drop operation.  The {@code Transferable} represents
      * the data to be imported into the component.
      * <p>
-     * Note: Swing now calls the newer version of <code>importData</code>
-     * that takes a <code>TransferSupport</code>, which in turn calls this
+     * Note: Swing now calls the newer version of {@code importData}
+     * that takes a {@code TransferSupport}, which in turn calls this
      * method (if the component in the {@code TransferSupport} is a
      * {@code JComponent}). Developers are encouraged to call and override the
      * newer version as it provides more information (and is the only
      * version that supports use with a {@code TransferHandler} set directly
      * on a {@code JFrame} or other non-{@code JComponent}).
      *
      * @param comp  the component to receive the transfer;
-     *              provided to enable sharing of <code>TransferHandler</code>s
+     *              provided to enable sharing of {@code TransferHandler}s
      * @param t     the data to import
      * @return  true if the data was inserted into the component, false otherwise
      * @see #importData(TransferHandler.TransferSupport)
      */
     public boolean importData(JComponent comp, Transferable t) {

@@ -905,19 +905,19 @@
      * This method is not called internally in response to paste operations.
      * As such, it is recommended that implementations of {@code importData}
      * explicitly call this method for such cases and that this method
      * be prepared to return the suitability of paste operations as well.
      * <p>
-     * Note: The <code>TransferSupport</code> object passed to this method
+     * Note: The {@code TransferSupport} object passed to this method
      * is only valid for the duration of the method call. It is undefined
      * what values it may contain after this method returns.
      *
      * @param support the object containing the details of
-     *        the transfer, not <code>null</code>.
-     * @return <code>true</code> if the import can happen,
-     *         <code>false</code> otherwise
-     * @throws NullPointerException if <code>support</code> is {@code null}
+     *        the transfer, not {@code null}.
+     * @return {@code true} if the import can happen,
+     *         {@code false} otherwise
+     * @throws NullPointerException if {@code support} is {@code null}
      * @see #importData(TransferHandler.TransferSupport)
      * @see javax.swing.TransferHandler.TransferSupport#setShowDropLocation
      * @see javax.swing.TransferHandler.TransferSupport#setDropAction
      * @since 1.6
      */

@@ -929,20 +929,20 @@
 
     /**
      * Indicates whether a component will accept an import of the given
      * set of data flavors prior to actually attempting to import it.
      * <p>
-     * Note: Swing now calls the newer version of <code>canImport</code>
-     * that takes a <code>TransferSupport</code>, which in turn calls this
+     * Note: Swing now calls the newer version of {@code canImport}
+     * that takes a {@code TransferSupport}, which in turn calls this
      * method (only if the component in the {@code TransferSupport} is a
      * {@code JComponent}). Developers are encouraged to call and override the
      * newer version as it provides more information (and is the only
      * version that supports use with a {@code TransferHandler} set directly
      * on a {@code JFrame} or other non-{@code JComponent}).
      *
      * @param comp  the component to receive the transfer;
-     *              provided to enable sharing of <code>TransferHandler</code>s
+     *              provided to enable sharing of {@code TransferHandler}s
      * @param transferFlavors  the data formats available
      * @return  true if the data can be inserted into the component, false otherwise
      * @see #canImport(TransferHandler.TransferSupport)
      */
     public boolean canImport(JComponent comp, DataFlavor[] transferFlavors) {

@@ -974,13 +974,13 @@
      * Some models are not mutable, so a transfer operation of {@code MOVE}
      * should not be advertised in that case. Returning {@code NONE}
      * disables transfers from the component.
      *
      * @param c  the component holding the data to be transferred;
-     *           provided to enable sharing of <code>TransferHandler</code>s
+     *           provided to enable sharing of {@code TransferHandler}s
      * @return {@code COPY} if the transfer property can be found,
-     *          otherwise returns <code>NONE</code>
+     *          otherwise returns {@code NONE}
      */
     public int getSourceActions(JComponent c) {
         PropertyDescriptor prop = getPropertyDescriptor(c);
         if (prop != null) {
             return COPY;

@@ -990,42 +990,42 @@
 
     /**
      * Returns an object that establishes the look of a transfer.  This is
      * useful for both providing feedback while performing a drag operation and for
      * representing the transfer in a clipboard implementation that has a visual
-     * appearance.  The implementation of the <code>Icon</code> interface should
+     * appearance.  The implementation of the {@code Icon} interface should
      * not alter the graphics clip or alpha level.
      * The icon implementation need not be rectangular or paint all of the
      * bounding rectangle and logic that calls the icons paint method should
-     * not assume the all bits are painted. <code>null</code> is a valid return value
+     * not assume the all bits are painted. {@code null} is a valid return value
      * for this method and indicates there is no visual representation provided.
      * In that case, the calling logic is free to represent the
      * transferable however it wants.
      * <p>
      * The default Swing logic will not do an alpha blended drag animation if
-     * the return is <code>null</code>.
+     * the return is {@code null}.
      *
      * @param t  the data to be transferred; this value is expected to have been
-     *  created by the <code>createTransferable</code> method
-     * @return  <code>null</code>, indicating
+     *  created by the {@code createTransferable} method
+     * @return  {@code null}, indicating
      *    there is no default visual representation
      */
     public Icon getVisualRepresentation(Transferable t) {
         return null;
     }
 
     /**
-     * Creates a <code>Transferable</code> to use as the source for
+     * Creates a {@code Transferable} to use as the source for
      * a data transfer. Returns the representation of the data to
-     * be transferred, or <code>null</code> if the component's
-     * property is <code>null</code>
+     * be transferred, or {@code null} if the component's
+     * property is {@code null}
      *
      * @param c  the component holding the data to be transferred;
-     *              provided to enable sharing of <code>TransferHandler</code>s
+     *              provided to enable sharing of {@code TransferHandler}s
      * @return  the representation of the data to be transferred, or
-     *  <code>null</code> if the property associated with <code>c</code>
-     *  is <code>null</code>
+     *  {@code null} if the property associated with {@code c}
+     *  is {@code null}
      *
      */
     protected Transferable createTransferable(JComponent c) {
         PropertyDescriptor property = getPropertyDescriptor(c);
         if (property != null) {

@@ -1034,28 +1034,28 @@
         return null;
     }
 
     /**
      * Invoked after data has been exported.  This method should remove
-     * the data that was transferred if the action was <code>MOVE</code>.
+     * the data that was transferred if the action was {@code MOVE}.
      * <p>
-     * This method is implemented to do nothing since <code>MOVE</code>
+     * This method is implemented to do nothing since {@code MOVE}
      * is not a supported action of this implementation
-     * (<code>getSourceActions</code> does not include <code>MOVE</code>).
+     * ({@code getSourceActions} does not include {@code MOVE}).
      *
      * @param source the component that was the source of the data
      * @param data   The data that was transferred or possibly null
-     *               if the action is <code>NONE</code>.
+     *               if the action is {@code NONE}.
      * @param action the actual action that was performed
      */
     protected void exportDone(JComponent source, Transferable data, int action) {
     }
 
     /**
      * Fetches the property descriptor for the property assigned to this transfer
      * handler on the given component (transfer handler may be shared).  This
-     * returns <code>null</code> if the property descriptor can't be found
+     * returns {@code null} if the property descriptor can't be found
      * or there is an error attempting to fetch the property descriptor.
      */
     private PropertyDescriptor getPropertyDescriptor(JComponent comp) {
         if (propertyName == null) {
             return null;

@@ -1129,11 +1129,11 @@
         }
 
         // --- Transferable methods ----------------------------------------------
 
         /**
-         * Returns an array of <code>DataFlavor</code> objects indicating the flavors the data
+         * Returns an array of {@code DataFlavor} objects indicating the flavors the data
          * can be provided in.  The array should be ordered according to preference
          * for providing the data (from most richly descriptive to least descriptive).
          * @return an array of data flavors in which this data can be transferred
          */
         public DataFlavor[] getTransferDataFlavors() {

@@ -1150,11 +1150,11 @@
 
         /**
          * Returns whether the specified data flavor is supported for
          * this object.
          * @param flavor the requested flavor for the data
-         * @return true if this <code>DataFlavor</code> is supported,
+         * @return true if this {@code DataFlavor} is supported,
          *   otherwise false
          */
         public boolean isDataFlavorSupported(DataFlavor flavor) {
             Class<?> propertyType = property.getPropertyType();
             if ("application".equals(flavor.getPrimaryType()) &&

@@ -1195,16 +1195,16 @@
         PropertyDescriptor property;
     }
 
     /**
      * This is the default drop target for drag and drop operations if
-     * one isn't provided by the developer.  <code>DropTarget</code>
-     * only supports one <code>DropTargetListener</code> and doesn't
+     * one isn't provided by the developer.  {@code DropTarget}
+     * only supports one {@code DropTargetListener} and doesn't
      * function properly if it isn't set.
      * This class sets the one listener as the linkage of drop handling
-     * to the <code>TransferHandler</code>, and adds support for
-     * additional listeners which some of the <code>ComponentUI</code>
+     * to the {@code TransferHandler}, and adds support for
+     * additional listeners which some of the {@code ComponentUI}
      * implementations install to manipulate a drop insertion location.
      */
     static class SwingDropTarget extends DropTarget implements UIResource {
 
         SwingDropTarget(Component c) {

@@ -1425,11 +1425,11 @@
 
         /**
          * The timer fired, perform autoscroll if the pointer is within the
          * autoscroll region.
          * <P>
-         * @param e the <code>ActionEvent</code>
+         * @param e the {@code ActionEvent}
          */
         public void actionPerformed(ActionEvent e) {
             updateAutoscrollRegion((JComponent)component);
             if (outer.contains(lastPosition) && !inner.contains(lastPosition)) {
                 autoscroll((JComponent)component, lastPosition);

@@ -1582,11 +1582,11 @@
         }
     }
 
     /**
      * This is the default drag handler for drag and drop operations that
-     * use the <code>TransferHandler</code>.
+     * use the {@code TransferHandler}.
      */
     private static class DragHandler implements DragGestureListener, DragSourceListener {
 
         private boolean scrolls;
 
< prev index next >