home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam  


Book Home Java Enterprise in a Nutshell Search this book

Chapter 12. The java.awt.dnd Package

The java.awt.dnd package contains classes and interfaces that support data transfer through the drag-and-drop metaphor; the package is new in Java 1.2. This functionality is built upon the data transfer framework of the java.awt.datatransfer package.

A DragSource object is a proxy for an object that initiates a drag, while a DropTarget object is a proxy for an object that wishes to accept drops. All inter-object communication during the drag process is done through the various event classes defined by this package. Figure 12-1 shows the class hierarchy of this package. See Chapter 6, "Data Transfer", for more details on drag-and-drop.

figure

Figure 12-1. The java.awt.dnd package

AutoscrollJava 1.2
java.awt.dnd

This interface allows a scrollable component to scroll itself as part of the drag-and-drop process, so that a user can drop an object anywhere within the component's scrollable content. Consider, for example, the problem of cutting a paragraph of text from the top of a long document and dragging it down to the bottom of the same document. While the drag-and-drop operation is in progress, the user obviously cannot operate the scrollbar, since the mouse is already in use. So some other technique is necessary to enable scrolling during a drag-and-drop operation.

The Autoscroll interface enables this specialized form of scrolling. When an object is first dragged over a component that implements Autoscroll, the drag-and-drop system calls the component's getAutoscrollInsets() method. This defines an autoscroll region at the edges of the component. If, during the drag, the user places the mouse within this autoscroll region and holds it there (for a platform-dependent amount of time), the drag-and-drop system begins to call the autoscroll() method repeatedly (at a platform-dependent repetition rate) until the user once again moves the mouse. The autoscroll() method of the component is responsible for scrolling the content. The direction of the scroll is determined by the position of the mouse pointer, which is passed as an argument to autoscroll().

public abstract interface Autoscroll {
// Public Instance Methods
public abstract void autoscroll (Point cursorLocn);
public abstract Insets getAutoscrollInsets ();
}
DnDConstantsJava 1.2
java.awt.dnd

Successful completion of a drag-and-drop operation can result in a number of different types of actions being performed. This interface defines constants that represent the possible actions:

ACTION_COPY

This is the most common action: the dragged object is to be copied in some way. ACTION_COPY is also used as a default action when there is only one possible action, even if that action is not really a copy.

ACTION_MOVE

The dragged object is to be copied by the destination. The source object deletes its copy after the object is successfully transferred.

ACTION_COPY_OR_MOVE

This constant is the combination of ACTION_COPY and ACTION_MOVE. Many drop targets can accept drops of either type; this constant is used to indicate that fact.

ACTION_LINK or ACTION_REFERENCE

These two constants are synonyms. They indicate that the destination object should create a link to the transferred object or share a reference to the transferred object with the source object. Note that this action has a particularly vague meaning; its use is not recommended except for intra-application drag-and-drop of specialized data types.

ACTION_NONE

This constant specifies that no actions are supported. It is used internally by the drag-and-drop API but is not commonly used by application-level code.

public final class DnDConstants {
// No Constructor
// Public Constants
public static final int ACTION_COPY ; =1
public static final int ACTION_COPY_OR_MOVE ; =3
public static final int ACTION_LINK ; =1073741824
public static final int ACTION_MOVE ; =2
public static final int ACTION_NONE ; =0
public static final int ACTION_REFERENCE ; =1073741824
}
DragGestureEventJava 1.2
java.awt.dndserializable event

This event type is fired by a DragGestureRecognizer and sent to the dragGestureRecognized() method of a DragGestureListener. Unlike many event classes, which are merely holders of event information, DragGestureEvent also defines the startDrag() method, which can be used to initiate the drag-and-drop process.

When the dragGestureRecognized() method is invoked, it should start the drag-and-drop process by invoking this startDrag() method, passing in the initial drag cursor to display, the Transferable data to transfer, and the DragSourceListener that monitors the drag process. If there is to be an image dragged along with the drag cursor, the image and its offset from the cursor hotspot may also be passed to startDrag().

The other methods of DragGestureEvent() are accessor methods that return information about the event. Most applications do not need to call them.

public class DragGestureEvent extends java.util.EventObject {
// Public Constructors
public DragGestureEvent (DragGestureRecognizer dgr, int act, Point ori, java.util.List evs);
// Property Accessor Methods (by property name)
public Component getComponent ();
public int getDragAction ();
public Point getDragOrigin ();
public DragSource getDragSource ();
public DragGestureRecognizer getSourceAsDragGestureRecognizer ();
public java.awt.event.InputEvent getTriggerEvent ();
// Public Instance Methods
public java.util.Iterator iterator ();
public void startDrag (Cursor dragCursor, java.awt.datatransfer.Transferable transferable, DragSourceListener dsl) throws InvalidDnDOperationException;
public void startDrag (Cursor dragCursor, Image dragImage, Point imageOffset, java.awt.datatransfer.Transferable transferable, DragSourceListener dsl) throws InvalidDnDOperationException;
public Object[ ] toArray ();
public Object[ ] toArray (Object[ ] array);
}

Hierarchy: Object-->java.util.EventObject(Serializable)-->DragGestureEvent

Passed To: Toolkit.createDragSourceContextPeer(), DragGestureListener.dragGestureRecognized(), DragSource.{createDragSourceContext(), startDrag()}, DragSourceContext.DragSourceContext()

Returned By: DragSourceContext.getTrigger()

DragGestureListenerJava 1.2
java.awt.dndevent listener

This interface defines the method that is invoked by a DragGestureRecognizer when the user initiates a drag-and-drop action. When dragGestureRecognized() is called, the DragGestureListener should prepare a Transferable object to be transferred through the drag-and-drop process and then initiate that process by calling the startDrag() method of the DragGestureEvent object.

You do not typically pass a DragGestureListener to an addDragGestureListener() method. Instead, you specify the DragGestureListener when you call the createDefaultDragGestureRecognizer() method of a DragSource object. This method creates a DragGestureRecognizer and automatically registers the DragGestureListener with it.

public abstract interface DragGestureListener extends java.util.EventListener {
// Public Instance Methods
public abstract void dragGestureRecognized (DragGestureEvent dge);
}

Hierarchy: (DragGestureListener(java.util.EventListener))

Passed To: Toolkit.createDragGestureRecognizer(), DragGestureRecognizer.{addDragGestureListener(), DragGestureRecognizer(), removeDragGestureListener()}, DragSource.{createDefaultDragGestureRecognizer(), createDragGestureRecognizer()}, MouseDragGestureRecognizer.MouseDragGestureRecognizer()

Type Of: DragGestureRecognizer.dragGestureListener

DragGestureRecognizerJava 1.2
java.awt.dnd

Drag-and-drop operations may be initiated in different ways on different native platforms. This abstract class is the superclass of the platform-dependent classes that are used to recognize the platform-dependent gesture used to begin a drag. As an abstract class, you cannot instantiate a DragGestureRecognizer directly. Instead, you typically create a DragGestureRecognizer by calling the createDefaultDragGestureRecognizer() method of a DragSource object. If you want to allow the user to initiate drags with nonstandard gestures, you may implement your own DragGestureRecognizer subclass and instantiate it by calling the createDragGestureRecognizer() method of java.awt.Toolkit.

When you create a DragGestureRecognizer, you specify the Component it is to look for drag gestures over and the DragGestureListener it is to notify when it recognizes one. The creation process automatically links these three objects together, so you typically never need to do anything with a DragGestureRecognizer other than create it.

One additional piece of information you must supply when you create a DragGestureRecognizer is a bit mask of allowed drag actions. ACTION_COPY, ACTION_MOVE, and ACTION_LINK actions are usually initiated with different gestures (different modifier keys). A DragGestureRecognizer must know which actions are available so it can know which gestures to recognize and which to ignore.

public abstract class DragGestureRecognizer {
// Protected Constructors
protected DragGestureRecognizer (DragSource ds);
protected DragGestureRecognizer (DragSource ds, Component c);
protected DragGestureRecognizer (DragSource ds, Component c, int sa);
protected DragGestureRecognizer (DragSource ds, Component c, int sa, DragGestureListener dgl);
// Event Registration Methods (by event name)
public void addDragGestureListener (DragGestureListener dgl) throws java.util.TooManyListenersException; synchronized
public void removeDragGestureListener (DragGestureListener dgl); synchronized
// Property Accessor Methods (by property name)
public Component getComponent (); synchronized
public void setComponent (Component c); synchronized
public DragSource getDragSource ();
public int getSourceActions (); synchronized
public void setSourceActions (int actions); synchronized
public java.awt.event.InputEvent getTriggerEvent ();
// Public Instance Methods
public void resetRecognizer ();
// Protected Instance Methods
protected void appendEvent (java.awt.event.InputEvent awtie); synchronized
protected void fireDragGestureRecognized (int dragAction, Point p); synchronized
protected abstract void registerListeners ();
protected abstract void unregisterListeners ();
// Protected Instance Fields
protected Component component ;
protected DragGestureListener dragGestureListener ;
protected DragSource dragSource ;
protected java.util.ArrayList events ;
protected int sourceActions ;
}

Subclasses: MouseDragGestureRecognizer

Passed To: DragGestureEvent.DragGestureEvent()

Returned By: Toolkit.createDragGestureRecognizer(), DragGestureEvent.getSourceAsDragGestureRecognizer(), DragSource.{createDefaultDragGestureRecognizer(), createDragGestureRecognizer()}

DragSourceJava 1.2
java.awt.dnd

This class coordinates the initiation of drag-and-drop operations. Despite the central role it plays in the drag-and-drop system, it is not used much in typical drag-and-drop code.

You can create a DragSource object by calling the constructor, but because the DragSource object does not hold any state, you can continually reuse a single object. Call the static getDefaultDragSource() method to obtain a reference to a shared default DragSource object.

Once you have obtained a DragSource object, call createDefaultDragGestureRecognizer() to create and register a DragGestureRecognizer object that detects user gestures that should initiate drags. If you want to drag an image that represents the dragged data along with the drag cursor, you may also call the isDragImageSupported() method to find out whether that option is supported on the native platform.

After you have called these two methods, you typically never need to use the DragSource again. The startDrag() method of the DragSource is responsible for initiating a drag action, but it is easier to invoke it through the startDrag() utility method of the DragGestureEvent class instead.

public class DragSource {
// Public Constructors
public DragSource ();
// Public Constants
public static final Cursor DefaultCopyDrop ;
public static final Cursor DefaultCopyNoDrop ;
public static final Cursor DefaultLinkDrop ;
public static final Cursor DefaultLinkNoDrop ;
public static final Cursor DefaultMoveDrop ;
public static final Cursor DefaultMoveNoDrop ;
// Public Class Methods
public static DragSource getDefaultDragSource ();
public static boolean isDragImageSupported ();
// Public Instance Methods
public DragGestureRecognizer createDefaultDragGestureRecognizer (Component c, int actions, DragGestureListener dgl);
public DragGestureRecognizer createDragGestureRecognizer (Class recognizerAbstractClass, Component c, int actions, DragGestureListener dgl);
public java.awt.datatransfer.FlavorMap getFlavorMap (); default:SystemFlavorMap
public void startDrag (DragGestureEvent trigger, Cursor dragCursor, java.awt.datatransfer.Transferable transferable, DragSourceListener dsl) throws InvalidDnDOperationException;
public void startDrag (DragGestureEvent trigger, Cursor dragCursor, java.awt.datatransfer.Transferable transferable, DragSourceListener dsl, java.awt.datatransfer.FlavorMap flavorMap) throws InvalidDnDOperationException;
public void startDrag (DragGestureEvent trigger, Cursor dragCursor, Image dragImage, Point dragOffset, java.awt.datatransfer.Transferable transferable, DragSourceListener dsl) throws InvalidDnDOperationException;
public void startDrag (DragGestureEvent trigger, Cursor dragCursor, Image dragImage, Point imageOffset, java.awt.datatransfer.Transferable transferable, DragSourceListener dsl, java.awt.datatransfer.FlavorMap flavorMap) throws InvalidDnDOperationException;
// Protected Instance Methods
protected DragSourceContext createDragSourceContext (java.awt.dnd.peer.DragSourceContextPeer dscp, DragGestureEvent dgl, Cursor dragCursor, Image dragImage, Point imageOffset, java.awt.datatransfer.Transferable t, DragSourceListener dsl);
}

Passed To: Toolkit.createDragGestureRecognizer(), DragGestureRecognizer.DragGestureRecognizer(), MouseDragGestureRecognizer.MouseDragGestureRecognizer()

Returned By: DragGestureEvent.getDragSource(), DragGestureRecognizer.getDragSource(), DragSource.getDefaultDragSource(), DragSourceContext.getDragSource()

Type Of: DragGestureRecognizer.dragSource

DragSourceContextJava 1.2
java.awt.dnd

This class contains state information about a drag operation currently in progress. It is the DragSourceContext that is responsible for communicating with the native drag-and-drop system of the underlying platform and relaying drag-and-drop events to the DragSourceListener. Although this is an important class, it does its work in the background, and you typically do not need to use it. If you do want to use it, for example, to perform cursor animation with the setCursor() method, you may obtain the current DragSourceContext from any DragSourceEvent object.

public class DragSourceContext implements DragSourceListener {
// Public Constructors
public DragSourceContext (java.awt.dnd.peer.DragSourceContextPeer dscp, DragGestureEvent trigger, Cursor dragCursor, Image dragImage, Point offset, java.awt.datatransfer.Transferable t, DragSourceListener dsl);
// Protected Constants
protected static final int CHANGED ; =3
protected static final int DEFAULT ; =0
protected static final int ENTER ; =1
protected static final int OVER ; =2
// Event Registration Methods (by event name)
public void addDragSourceListener (DragSourceListener dsl) throws java.util.TooManyListenersException; synchronized
public void removeDragSourceListener (DragSourceListener dsl); synchronized
// Property Accessor Methods (by property name)
public Component getComponent ();
public Cursor getCursor ();
public void setCursor (Cursor c);
public DragSource getDragSource ();
public int getSourceActions ();
public java.awt.datatransfer.Transferable getTransferable ();
public DragGestureEvent getTrigger ();
// Public Instance Methods
public void transferablesFlavorsChanged ();
// Methods Implementing DragSourceListener
public void dragDropEnd (DragSourceDropEvent dsde); synchronized
public void dragEnter (DragSourceDragEvent dsde); synchronized
public void dragExit (DragSourceEvent dse); synchronized
public void dragOver (DragSourceDragEvent dsde); synchronized
public void dropActionChanged (DragSourceDragEvent dsde); synchronized
// Protected Instance Methods
protected void updateCurrentCursor (int dropOp, int targetAct, int status);
}

Hierarchy: Object-->DragSourceContext(DragSourceListener(java.util.EventListener))

Passed To: DragSourceDragEvent.DragSourceDragEvent(), DragSourceDropEvent.DragSourceDropEvent(), DragSourceEvent.DragSourceEvent(), java.awt.dnd.peer.DragSourceContextPeer.startDrag()

Returned By: DragSource.createDragSourceContext(), DragSourceEvent.getDragSourceContext()

DragSourceDragEventJava 1.2
java.awt.dndserializable event

This event type is fired by a DragSourceContext and passed to the dragEnter(), dragOver(), dragExit(), and dragActionChanged() methods of a DragSourceListener. These methods may use the notification as an opportunity to perform drag-over animation effects, by changing the cursor, for example.

isLocalDropTarget() specifies whether the drop target currently under the cursor is in the same Java VM as the drag source. getUserAction() returns the current drag action selected by the user. This is usually a function of the modifier keys the user is holding down; these modifiers are available from getGestureModifiers(). getTargetActions() returns a bit mask of the actions that the drop target can support, and getDropAction() is the intersection of the user action with the set of target actions.

public class DragSourceDragEvent extends DragSourceEvent {
// Public Constructors
public DragSourceDragEvent (DragSourceContext dsc, int dropAction, int actions, int modifiers);
// Property Accessor Methods (by property name)
public int getDropAction ();
public int getGestureModifiers ();
public int getTargetActions ();
public int getUserAction ();
}

Hierarchy: Object-->java.util.EventObject(Serializable)-->DragSourceEvent-->DragSourceDragEvent

Passed To: DragSourceContext.{dragEnter(), dragOver(), dropActionChanged()}, DragSourceListener.{dragEnter(), dragOver(), dropActionChanged()}

DragSourceDropEventJava 1.2
java.awt.dndserializable event

This event type is fired by the DragSourceContext and is passed to the dragDropEnd() method of a DragSourceListener to signify that the drag-and-drop operation is complete. getDropSuccess() returns true if the drop occurs and the data is successfully transferred. It returns false if the drag is cancelled, if the drop is performed over an invalid drop target, or if the data transfer is not successful. getDropAction() returns the action (see DnDConstants) that is actually performed. The user's selected action may change during the drag, so this value may not be the same as the initially selected action.

public class DragSourceDropEvent extends DragSourceEvent {
// Public Constructors
public DragSourceDropEvent (DragSourceContext dsc);
public DragSourceDropEvent (DragSourceContext dsc, int action, boolean success);
// Public Instance Methods
public int getDropAction ();
public boolean getDropSuccess ();
}

Hierarchy: Object-->java.util.EventObject(Serializable)-->DragSourceEvent-->DragSourceDropEvent

Passed To: DragSourceContext.dragDropEnd(), DragSourceListener.dragDropEnd()

DragSourceEventJava 1.2
java.awt.dndserializable event

This class is the superclass of event types fired by a DragSourceContext to notify a DragSourceListener about events in the drag-and-drop process. Although applications typically do not need to do so, they can call getDragSourceContext() or getSource() to obtain a reference to the current DragSourceContext. This object can be used, for example, to perform drag over animation effects by changing the current drag cursor. If you are writing a DragSourceListener that handles drags on more than one component, you can determine which component initiated the drag by calling getSource() to obtain a DragSourceContext and then calling its getComponent() method.

See also DragSourceDragEvent and DragSourceDropEvent.

public class DragSourceEvent extends java.util.EventObject {
// Public Constructors
public DragSourceEvent (DragSourceContext dsc);
// Public Instance Methods
public DragSourceContext getDragSourceContext ();
}

Hierarchy: Object-->java.util.EventObject(Serializable)-->DragSourceEvent

Subclasses: DragSourceDragEvent, DragSourceDropEvent

Passed To: DragSourceContext.dragExit(), DragSourceListener.dragExit()

DragSourceListenerJava 1.2
java.awt.dndevent listener

This interface is implemented by objects that allow data to be transferred through drag-and-drop and want to be notified about the progress of the drag-and-drop process. The methods of this interface are invoked by a DragSourceContext at various interesting points during the drag-and-drop. The methods are passed a DragSourceDragEvent or a DragSourceDropEvent, both of which are subclasses of DragSourceEvent. The methods are:

dragDropEnd()

Invoked when the drag-and-drop operation is complete and has ended in success or failure. This is the only method that is passed a DragSourceDropEvent, instead of a DragSourceDragEvent. If the drag is of type ACTION_MOVE and the getDropSuccess() method of DragSourceDropEvent returns true, the DragSourceListener knows that the data has been safely transferred to the drop target and should delete the source copy of that data.

dragEnter()

Called when the drag cursor has entered an active drop target that has indicated an interest in and capability to receive a drop. This method should initiate any custom drag over effects.

dragExit()

Invoked when the drag cursor has left a receptive drop target. This method should terminate any custom drag over effects.

dragOver()

Called continuously while the mouse remains within a receptive drop target. Because this method is called very frequently, it should not perform any lengthy operations.

dropActionChanged()

Invoked if the user changes his desired drop action, typically by changing the keyboard modifiers she is holding down. If you are displaying a custom drag cursor, this method may need to modify the currently displayed cursor.

public abstract interface DragSourceListener extends java.util.EventListener {
// Public Instance Methods
public abstract void dragDropEnd (DragSourceDropEvent dsde);
public abstract void dragEnter (DragSourceDragEvent dsde);
public abstract void dragExit (DragSourceEvent dse);
public abstract void dragOver (DragSourceDragEvent dsde);
public abstract void dropActionChanged (DragSourceDragEvent dsde);
}

Hierarchy: (DragSourceListener(java.util.EventListener))

Implementations: DragSourceContext

Passed To: DragGestureEvent.startDrag(), DragSource.{createDragSourceContext(), startDrag()}, DragSourceContext.{addDragSourceListener(), DragSourceContext(), removeDragSourceListener()}

DropTargetJava 1.2
java.awt.dndserializable

This class holds the state necessary for a Component to accept drops. Create a DropTarget by specifying the Component with which it is to be associated and the DropTargetListener that responds to interesting events during a drag-and-drop operation. You may optionally specify a bit mask of drop actions that this DropTarget can support and a boolean value that indicates whether the DropTarget is currently active. If you do not specify these optional values, your DropTarget supports ACTION_COPY_OR_MOVE and is active.

Once you have created a DropTarget, you often never have to do anything else with it. The DropTarget() constructor automatically connects the DropTarget with the Component it serves and the DropTargetListener it notifies, so you do not have to perform any of the registration yourself. In fact, the only time you typically need to use the DropTarget object you create is if you need to activate or deactivate it with setActive().

public class DropTarget implements DropTargetListener, Serializable {
// Public Constructors
public DropTarget ();
public DropTarget (Component c, DropTargetListener dtl);
public DropTarget (Component c, int ops, DropTargetListener dtl);
public DropTarget (Component c, int ops, DropTargetListener dtl, boolean act);
public DropTarget (Component c, int ops, DropTargetListener dtl, boolean act, java.awt.datatransfer.FlavorMap fm);
// Inner Classes
;
// Event Registration Methods (by event name)
public void addDropTargetListener (DropTargetListener dtl) throws java.util.TooManyListenersException; synchronized
public void removeDropTargetListener (DropTargetListener dtl); synchronized
// Property Accessor Methods (by property name)
public boolean isActive (); synchronized default:true
public void setActive (boolean isActive); synchronized
public Component getComponent (); synchronized default:null
public void setComponent (Component c); synchronized
public int getDefaultActions (); synchronized default:3
public void setDefaultActions (int ops); synchronized
public DropTargetContext getDropTargetContext ();
public java.awt.datatransfer.FlavorMap getFlavorMap (); default:SystemFlavorMap
public void setFlavorMap (java.awt.datatransfer.FlavorMap fm);
// Public Instance Methods
public void addNotify (java.awt.peer.ComponentPeer peer);
public void removeNotify (java.awt.peer.ComponentPeer peer);
// Methods Implementing DropTargetListener
public void dragEnter (DropTargetDragEvent dtde); synchronized
public void dragExit (DropTargetEvent dte); synchronized
public void dragOver (DropTargetDragEvent dtde); synchronized
public void drop (DropTargetDropEvent dtde); synchronized
public void dropActionChanged (DropTargetDragEvent dtde);
// Protected Instance Methods
protected void clearAutoscroll ();
protected DropTarget.DropTargetAutoScroller createDropTargetAutoScroller (Component c, Point p);
protected DropTargetContext createDropTargetContext ();
protected void initializeAutoscrolling (Point p);
protected void updateAutoscroll (Point dragCursorLocn);
}

Hierarchy: Object-->DropTarget(DropTargetListener(java.util.EventListener),Serializable)

Passed To: Component.setDropTarget(), java.awt.dnd.peer.DropTargetPeer.{addDropTarget(), removeDropTarget()}

Returned By: Component.getDropTarget(), DropTargetContext.getDropTarget(), java.awt.dnd.peer.DropTargetContextPeer.getDropTarget()

DropTarget.DropTargetAutoScrollerJava 1.2
java.awt.dnd

This protected inner class implements autoscrolling behavior for a drop target. If the drop target is associated with a component that implements Autoscroll, this class invokes the autoscroll() method of that component as appropriate. Applications never need to use this class directly. Applications that want to override the default autoscrolling behavior can subclass this class and override the createDropTargetAutoScroller() method of DropTarget to return an instance of the subclass.

protected static class DropTarget.DropTargetAutoScroller implements java.awt.event.ActionListener {
// Protected Constructors
protected DropTargetAutoScroller (Component c, Point p);
// Methods Implementing ActionListener
public void actionPerformed (java.awt.event.ActionEvent e); synchronized
// Protected Instance Methods
protected void stop ();
protected void updateLocation (Point newLocn); synchronized
}

Returned By: DropTarget.createDropTargetAutoScroller()

DropTargetContextJava 1.2
java.awt.dnd

This class contains state information about a drag operation currently in progress above a DropTarget. The DropTargetContext is responsible for communicating with the native drag-and-drop system of the underlying platform and relaying drag-and-drop events from that native system to the DropTargetListener.

Although this is an important class, it does its work internally, and application-level code does not typically need to use it. DropTargetContext does define some important methods, such as acceptDrag() and acceptDrop(), but these are typically invoked through the utility methods of DropTargetDragEvent and DropTargetDropEvent. If you ever do need to use a DropTargetContext directly, it is available from any DropTargetEvent.

public class DropTargetContext {
// No Constructor
// Inner Classes
;
// Public Instance Methods
public void addNotify (java.awt.dnd.peer.DropTargetContextPeer dtcp); synchronized
public void dropComplete (boolean success) throws InvalidDnDOperationException;
public Component getComponent ();
public DropTarget getDropTarget ();
public void removeNotify (); synchronized
// Protected Instance Methods
protected void acceptDrag (int dragOperation);
protected void acceptDrop (int dropOperation);
protected java.awt.datatransfer.Transferable createTransferableProxy (java.awt.datatransfer.Transferable t, boolean local);
protected java.awt.datatransfer.DataFlavor[ ] getCurrentDataFlavors ();
protected java.util.List getCurrentDataFlavorsAsList ();
protected int getTargetActions ();
protected java.awt.datatransfer.Transferable getTransferable () throws InvalidDnDOperationException; synchronized
protected boolean isDataFlavorSupported (java.awt.datatransfer.DataFlavor df);
protected void rejectDrag ();
protected void rejectDrop ();
protected void setTargetActions (int actions);
}

Passed To: DropTargetDragEvent.DropTargetDragEvent(), DropTargetDropEvent.DropTargetDropEvent(), DropTargetEvent.DropTargetEvent()

Returned By: DropTarget.{createDropTargetContext(), getDropTargetContext()}, DropTargetEvent.getDropTargetContext()

Type Of: DropTargetEvent.context

DropTargetContext.TransferableProxyJava 1.2
java.awt.dnd

This protected inner class is used by the protected createTransferableProxy() method of DropTargetContext. Applications never need to use this class. This class is not defined by the JFC drag-and-drop specification and its inclusion in the public API of java.awt.dnd was probably unintentional.

protected class DropTargetContext.TransferableProxy implements java.awt.datatransfer.Transferable {
// No Constructor
// Methods Implementing Transferable
public Object getTransferData (java.awt.datatransfer.DataFlavor df) throws java.awt.datatransfer.UnsupportedFlavorException, java.io.IOException; synchronized
public java.awt.datatransfer.DataFlavor[ ] getTransferDataFlavors (); synchronized
public boolean isDataFlavorSupported (java.awt.datatransfer.DataFlavor flavor); synchronized
// Protected Instance Fields
protected boolean isLocal ;
protected java.awt.datatransfer.Transferable transferable ;
}
DropTargetDragEventJava 1.2
java.awt.dndserializable event

This event is fired by a DropTargetContext and passed to the dragEnter(), dragOver(), and dropActionChanged() methods of a DropTargetListener. Each of these methods should use getDropAction(), getCurrentDataFlavors(), and related methods to check whether the drop target knows how to handle the drag action and is able to interpret the data formats offered. If so, the method should call acceptDrag(). If not, it should call rejectDrag(). See DropTargetListener for further details.

public class DropTargetDragEvent extends DropTargetEvent {
// Public Constructors
public DropTargetDragEvent (DropTargetContext dtc, Point cursorLocn, int dropAction, int srcActions);
// Property Accessor Methods (by property name)
public java.awt.datatransfer.DataFlavor[ ] getCurrentDataFlavors ();
public java.util.List getCurrentDataFlavorsAsList ();
public int getDropAction ();
public Point getLocation ();
public int getSourceActions ();
// Public Instance Methods
public void acceptDrag (int dragOperation);
public boolean isDataFlavorSupported (java.awt.datatransfer.DataFlavor df);
public void rejectDrag ();
}

Hierarchy: Object-->java.util.EventObject(Serializable)-->DropTargetEvent-->DropTargetDragEvent

Passed To: DropTarget.{dragEnter(), dragOver(), dropActionChanged()}, DropTargetListener.{dragEnter(), dragOver(), dropActionChanged()}

DropTargetDropEventJava 1.2
java.awt.dndserializable event

This event is fired by a DropTargetContext and delivered to the drop() method of a DropTargetListener. This method should call getDropAction() to ensure that it is able to perform the requested action. It should also call getCurrentDataFlavors() or isDataFlavorSupported() to ensure that it can interpret the data that is transferred. If it cannot perform the action or interpret the data, it should call rejectDrag() and return.

If the DropTargetListener can perform the action and interpret the data, it should accept the drop. It does this in a four-step process. First, it calls acceptDrop() to signal that it accepts the drop. Second, it calls getTransferable() to obtain a java.awt.datatransfer.Transferable object. Third, it calls the getTransferData() method of Transferable to actually transfer the data.

Finally, if the data transfer fails for any reason, the DropTargetListener should pass false to the dropComplete() method of the DropTargetDropEvent, indicating that the drop action is complete but that it was not successful. If the data transfer is successful and the data has been safely and completely transferred, the drop() method should pass true to the dropComplete() method. This notifies the system that the data has been successfully transferred. The notification is passed on to the DragSourceListener, which can then complete its part of the action. For example, if the action is ACTION_MOVE, the DragSourceListener deletes its copy of the data once it receives notification that the DropTargetListener has successfully copied it.

public class DropTargetDropEvent extends DropTargetEvent {
// Public Constructors
public DropTargetDropEvent (DropTargetContext dtc, Point cursorLocn, int dropAction, int srcActions);
public DropTargetDropEvent (DropTargetContext dtc, Point cursorLocn, int dropAction, int srcActions, boolean isLocal);
// Property Accessor Methods (by property name)
public java.awt.datatransfer.DataFlavor[ ] getCurrentDataFlavors ();
public java.util.List getCurrentDataFlavorsAsList ();
public int getDropAction ();
public boolean isLocalTransfer ();
public Point getLocation ();
public int getSourceActions ();
public java.awt.datatransfer.Transferable getTransferable ();
// Public Instance Methods
public void acceptDrop (int dropAction);
public void dropComplete (boolean success);
public boolean isDataFlavorSupported (java.awt.datatransfer.DataFlavor df);
public void rejectDrop ();
}

Hierarchy: Object-->java.util.EventObject(Serializable)-->DropTargetEvent-->DropTargetDropEvent

Passed To: DropTarget.drop(), DropTargetListener.drop()

DropTargetEventJava 1.2
java.awt.dndserializable event

This class is the superclass of both DropTargetDragEvent and DropTargetDropEvent. getDropTargetContext() returns the DropTargetContext object that generated the event, and getSource() returns the corresponding DropTarget object. Applications rarely need to use these methods, however.

public class DropTargetEvent extends java.util.EventObject {
// Public Constructors
public DropTargetEvent (DropTargetContext dtc);
// Public Instance Methods
public DropTargetContext getDropTargetContext ();
// Protected Instance Fields
protected DropTargetContext context ;
}

Hierarchy: Object-->java.util.EventObject(Serializable)-->DropTargetEvent

Subclasses: DropTargetDragEvent, DropTargetDropEvent

Passed To: DropTarget.dragExit(), DropTargetListener.dragExit()

DropTargetListenerJava 1.2
java.awt.dndevent listener

This interface is implemented by objects that want to be able to receive dropped data. Its methods are invoked by a DropTargetContext at various interesting points in the drag-and-drop process. The methods of this interface are passed a DropTargetEvent or one of its subclasses, a DropTargetDragEvent or a DropTargetDropEvent. The methods are:

dragEnter()

Invoked when a drag enters the Component associated with the DropTargetListener. This method should call getDropAction() to determine whether it can perform the requested action and either getCurrentDataFlavors() or isDataFlavorSupported() to determine whether it can interpret the data that is being offered. If so, it should call the acceptDrag() method of the event object. If not, it should call the rejectDrag() method.

If this method accepts the drag, it may also perform or initiate custom graphical drag under effects on the associated Component. These effects provide feedback to the user that the drop target Component is interested in receiving the drop.

dragExit()

Called when a previously accepted drag leaves the DropTarget. If the dragEnter() method performed any custom drag under effects, this method should undo them.

dragOver()

Invoked continuously while the mouse pointer remains over the DragTarget. In most cases, this method need not do anything. If the DropTarget is a complex one that is capable of accepting drags in some regions but not in other regions, this method should behave like dragEnter() and call the acceptDrag() or rejectDrag() methods of the event object to inform the system whether a drag is possible at the current location. In this case, this method is also responsible for any custom drag under graphical effects.

drop()

Called when data is dropped over the DropTarget. This method should determine whether the DropTarget can accept the drop and call the acceptDrop() or rejectDrop() method of the DropTargetDropEvent event object. If it accepts the drop, it must then transfer the data, perform the requested action, and call dropComplete(). See DropTargetDropEvent for details on this process. This method need not undo your drag under effects; the dragExit() method is invoked for this purpose.

dropActionChanged()

Invoked when the user changes the requested action in mid-drag. This typically occurs if the user changes the modifier keys currently held down. This method should behave like dragEnter() to evaluate whether the drop target can perform the requested action on the offered data and then call acceptDrag() or rejectDrag() and begin or end custom drag under effects, as appropriate.

public abstract interface DropTargetListener extends java.util.EventListener {
// Public Instance Methods
public abstract void dragEnter (DropTargetDragEvent dtde);
public abstract void dragExit (DropTargetEvent dte);
public abstract void dragOver (DropTargetDragEvent dtde);
public abstract void drop (DropTargetDropEvent dtde);
public abstract void dropActionChanged (DropTargetDragEvent dtde);
}

Hierarchy: (DropTargetListener(java.util.EventListener))

Implementations: DropTarget

Passed To: DropTarget.{addDropTargetListener(), DropTarget(), removeDropTargetListener()}

InvalidDnDOperationExceptionJava 1.2
java.awt.dndserializable unchecked

Signals that a misconfiguration or error of some sort prevents a drag-and-drop operation from completing normally. This exception is thrown by methods throughout the java.awt.dnd package.

public class InvalidDnDOperationException extends java.lang.IllegalStateException {
// Public Constructors
public InvalidDnDOperationException ();
public InvalidDnDOperationException (String msg);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->RuntimeException-->java.lang.IllegalStateException-->InvalidDnDOperationException

Thrown By: Toolkit.createDragSourceContextPeer(), DragGestureEvent.startDrag(), DragSource.startDrag(), DropTargetContext.{dropComplete(), getTransferable()}, java.awt.dnd.peer.DragSourceContextPeer.{setCursor(), startDrag()}, java.awt.dnd.peer.DropTargetContextPeer.getTransferable()

MouseDragGestureRecognizerJava 1.2
java.awt.dnd

This class is a DragGestureRecognizer that is designed to recognize mouse gestures (as opposed, for example, to keyboard gestures). Like DragGestureRecognizer, this is an abstract class and cannot be instantiated. The createDefaultDragGestureRecognizer() method of DragSource returns a platform-specific concrete subclass of this class. Most applications do not need to use this class. Applications that want to support custom drag-and-drop gestures may find it convenient to subclass this class.

public abstract class MouseDragGestureRecognizer extends DragGestureRecognizer implements java.awt.event.MouseListener, java.awt.event.MouseMotionListener {
// Protected Constructors
protected MouseDragGestureRecognizer (DragSource ds);
protected MouseDragGestureRecognizer (DragSource ds, Component c);
protected MouseDragGestureRecognizer (DragSource ds, Component c, int act);
protected MouseDragGestureRecognizer (DragSource ds, Component c, int act, DragGestureListener dgl);
// Methods Implementing MouseListener
public void mouseClicked (java.awt.event.MouseEvent e); empty
public void mouseEntered (java.awt.event.MouseEvent e); empty
public void mouseExited (java.awt.event.MouseEvent e); empty
public void mousePressed (java.awt.event.MouseEvent e); empty
public void mouseReleased (java.awt.event.MouseEvent e); empty
// Methods Implementing MouseMotionListener
public void mouseDragged (java.awt.event.MouseEvent e); empty
public void mouseMoved (java.awt.event.MouseEvent e); empty
// Protected Methods Overriding DragGestureRecognizer
protected void registerListeners ();
protected void unregisterListeners ();
}

Hierarchy: Object-->DragGestureRecognizer-->MouseDragGestureRecognizer(java.awt.event.MouseListener(java.util.EventListener),java.awt.event.MouseMotionListener(java.util.EventListener))



Library Navigation Links

Copyright © 2001 O'Reilly & Associates. All rights reserved.