Drag-and-Drop Protocol for the X Window System
Example walk-through
Note: Parenthesized numbers in bold-face are the number of packets sent to or from the server.
Step 0:
Windows announce that they support the XDND protocol by creating a window property XdndAware that contains the highest version supported.
Step 1:
When a drag begins, the source takes ownership of XdndSelection.
When the mouse enters a window that supports XDND (search for and retrieve window property: avg 8), the source sends a ClientMessage of type XdndEnter (2) which contains the protocol version to use (minimum of source and target versions) and the data types supported by the source.
An extension has been developed to allow dropping on other windows.
Step 2:
The target receives XdndEnter.
The ClientMessage only has space for three data types, so if the source supports more than this, the target must retrieve the property XdndTypeList from the source window in order to get the list of available types. (2)
Step 3:
The source sends a ClientMessage of type XdndPosition. (2) This tells the target the position of the mouse and the action that the user requested. It may also include a request to scroll the target.
Step 4:
The target receives XdndPosition.
The target window must determine which widget the mouse is in and ask it whether or not it will accept the drop. For efficiency, the target window should keep track of whether or not the widget will accept the drop and only ask again if the action changes or the mouse enters a different part of the widget. Once the widget has said that it will accept the drop and as long as the action remains the same and the mouse remains in the same part, the widget gets all the XdndPosition messages so that it can re-draw itself to show the user where the data will be inserted, if appropriate.
To determine whether or not it can accept the drop, the target widget consults the list of types from the XdndEnter message and the requested action from the XdndPosition message.
If the target cannot perform the requested action, it can return either XdndActionCopy or XdndActionPrivate. If neither of these are possible, then it should refuse the drop.
If the target needs to look at the data itself, it calls XConvertSelection() for XdndSelection, the data type that it is interested in, and the given time stamp. (7) It can do this more than once, if necessary.
If the target can accept the drop, it should hilight its border or otherwise notify the user visually. If it retrieved the data, it should cache it so it does not need to be retrieved again when the actual drop occurs.
Regardless of whether or not the target can accept the drop, it should process the request to scroll, if any, because scrolling may expose a drop zone.
Step 5:
The target sends a ClientMessage of type XdndStatus. (2) This tells the source whether or not it will accept the drop, and, if so, what action will be taken. It also includes a rectangle that means "don't send another XdndPosition message until the mouse moves out of here".
Step 6:
The source receives XdndStatus. It can use the action to change the cursor to indicate whether or not the user's requested action will be performed.
When the mouse moves out of the given rectangle, go to Step 3.
XdndPosition messages are normally triggered by MotionNotify events. However, if the mouse moves while the source is waiting for an XdndStatus message, the source has to cache the new mouse position and generate another XdndPosition message as soon as it receives the XdndStatus message. (This will be necessary when the server-target connection is much slower than the server-source connection.)
It is important to note that if the target does not return a "no more messages" rectangle, then sending periodic XdndPosition messages when the cursor is not moving is necessary to allow the target to scroll smoothly, e.g., when the cursor is in a scroll zone close to the edge of the target. If this is not done, the user will be forced to wiggle the cursor back and forth in order to tickle the target so it can scroll.
Step 7:
If the mouse leaves the window, the source sends a ClientMessage of type XdndLeave. (2)
If the mouse button is released in the window, the source waits for the last XdndStatus message (if necessary) and then sends a ClientMessage of type XdndLeave or XdndDrop, depending on the "accept" flag in the last XdndStatus. (2)
If the source never received any XdndStatus messages at all, it should send XdndLeave without waiting.
If the source doesn't receive the expected XdndStatus within a reasonable amount of time, it should send XdndLeave. While waiting for XdndStatus, the source can block, but it must at least process SelectionRequest events so the target can examine the data.
Step 8:
If the target receives XdndLeave, it frees any cached data and forgets the whole incident.
If the target receives XdndDrop and will accept it, it first uses XConvertSelection() to retrieve the data using the given time stamp (if it doesn't already have it cached). (7) It then uses the data in conjunction with the last action and mouse position that was acknowledged via XdndStatus. (Over a slow network, this makes the drop location consistent with the visual feedback given to the user.) Once it is finished, it sends XdndFinished.
If the target receives XdndDrop and will not accept it, it sends XdndFinished and then treats it as XdndLeave.