<!DOCTYPE Book PUBLIC "-//HaL and O'Reilly//DTD DocBook V2.2.1//EN" [

<DocBook>
<Book>
<Title>Motif Drag And Drop Protocol</Title>

<Chapter Id="MOTIF.dnd.div.1">

<Title>Motif Drag And Drop Protocol</Title>
<Para><Anchor XRefLabel="dnd" Role="1" Id="MOTIF.dnd.anch.1"></Para>

<Para>
This chapter describes the protocol used to implement Drag and Drop 
in existing versions of the Motif Toolkit.
</Para>

<Para>
This protocol is based on X Client Messages, Properties and 
Selections, and its public specification should allow any X based 
toolkit or application to interoperate with any applications that use 
Motif Drag and Drop.
</Para>

<Sect1 Id="MOTIF.dnd.div.2">
<Title>Description</Title>
<Para><Anchor XRefLabel="dnd_desc" Role="2" Id="MOTIF.dnd.anch.2">
</Para>

<Para>
Drag and Drop is an interactive technique which allows transfer of 
information through a simple metaphor: the user picks an object on 
the display with the pointer, drags it across the screen while 
maintaining the pointer button pressed, and drops the object on some 
other place. Subsequently, the application where the object was 
dropped usually does some data transfer corresponding to the object.
</Para>

<Para>
A Drag and Drop operation starts in a window called the source 
window. The client owner of this window is called the initiator 
client. The drop operation occurs in a window called the destination 
window. The client owner of this window is called the receiver 
client. A client can be both initiator and receiver for an operation. 
A client can contain both the source and destination windows for an 
operation.  The source window may also be the destination window. 
There are no particular requirements on what the client should do or 
not do in those specific cases.
</Para>

<Para>
In many cases, the drop will occur on some area called a drop site, 
for example a printer icon or a trash can icon. A drop site may be 
drawn in its own window or may be simply drawn by the receiver 
application in a larger window. The protocol does not require to have 
one window per drop site.
</Para>

<Para>
During the drag, both the initiator client and the potential receiver 
clients may want to provide visual feed back to the user. The feed 
back provided by the initiator is called drag-over. The feed back 
provided by a receiver is called drag-under: typically doing some 
animation in the destination window under the drag icon.
</Para>

<Para>
The feedback may consist in:
</Para>
<ItemizedList>
<ListItem> <Para>an icon representing the data being dragged, called the source icon 
</Para></ListItem>
<ListItem> <Para>showing the existence of a drop site. Both initiator and receiver might want to provide feedback whether or not a drop is possible. For example, the receiver can be highlighting the drop site and the initiator showing a specific icon: the state icon.
</Para></ListItem>
<ListItem> <Para>a side effect icon indicating the side effect that would occur if a drop were made.
</Para></ListItem>
<ListItem> <Para>In the case where a drop is possible, both initiator and receiver may want to provide feedback indicating the validity of the operation for this particular drop. For example, if it is known that the object being dragged cannot be processed by the receiver.
</Para></ListItem>
</ItemizedList>

<Para>Implementing Drag and Drop requires multiple conventions:
</Para>
<ItemizedList>
<ListItem> <Para>Potential receivers need to signal that they contain one or more drop sites on their top level windows.
</Para></ListItem>
<ListItem> <Para>When a drag operation starts, the initiator client needs to obtain  from a service all windows where data can be dropped. This may be obtained by querying an external service (e.g.  the Window Manager).  If such a service does not exist, the initiator will have to determine when the pointer enters a new top level window,  if that window is a potential receiver. Refer to the ICCCM 2.0  manual for <Property>WM_STATE</Property> property that identifies toplevel window in clients. 
</Para></ListItem>
<ListItem> <Para>During the drag, the initiator send messages to the potential receivers, and expect responses from them. The set of states and messages exchanged during a drag define the Drag Protocol.
</Para></ListItem>
<ListItem> <Para>The set of states and messages exchanged with and after the drop event define the Drop Protocol.
</Para></ListItem>
</ItemizedList>

<Para>
The Drag protocol and the Drop protocol are independent. During a 
drag a client is at liberty to not use the drag protocol. For example 
because there is known latency or thrashing and using the drag 
protocol would be much too slow to provide accurate feedback. Hence a 
drag and drop operation may actually involve only the Drop protocol. 
This style of interaction is called "Drop Only" in the Motif toolkit.
</Para>

<Para>
The data is transfered through some action that may have side 
effects. For example in a file management system, when a file is 
transferred it can be physically moved from a directory to another 
one, or copied, or linked.  The Motif protocol supports three pre-
defined side effects named Copy (the initiator data is not altered 
after the drop), Move (the initiator data is removed after the drop) 
and Link (a reference to the initiator data has been made by the 
receiver). The Motif drag and drop dynamic protocol uses X11 Client 
Messages as the underlying transport mechanism and also exchanges 
data through X properties.
</Para>
</Sect1>

<Sect1 Id="MOTIF.dnd.div.3">
<Title>The Drag Protocol</Title>
<Para><Anchor XRefLabel="dnd_prot" Role="2" Id="MOTIF.dnd.anch.3">

In order to provide accurate feed back both the initiator and the 
receiver need information from the other side.  The messages from the 
drag protocol serve that purpose.  
</Para>
<Para>
The messages are X client messages sent from the source window to the 
destination window, and back.  
</Para>

<Para>
As the pointer moves, the initiator sends messages indicating the new 
pointer position and properties of the drag (targets, possible side 
effects, recommended side effects). From this message, the receiver 
obtains necessary information to achieve drag under feedback. The 
receiver then replies by providing information to the initiator about 
the existence, validity and side effects of the drop, so that the 
initiator can achieve proper drag over feedback.
</Para>

<Para>
Some data is stored on window properties of a persistent, override-
redirect, InputOnly child window of the display's default root 
window: the motif Drag Window.  A client looks for the motif Drag 
Window id on the <Property>_MOTIF_DRAG_WINDOW</Property> property of its display's default 
root window. If the window id is NULL or invalid, a client may create 
this Window itself (using SetCloseDownMode RetainPermanent, so that 
other clients don't have to create it).
</Para>

<Para>
Several sets of data are stored on the motif Drag Window properties. 
Of interest for the Dynamic Drag protocol is a targets list table.
</Para>

<Para>
The <Property>_MOTIF_DRAG_TARGETS</Property> property on the motif Drag Window (type 
<Property>_MOTIF_DRAG_TARGETS</Property>) contains a targets table, consisting of a 
sequence of target lists to be shared among clients.  In other words, 
this property is a list of lists. These target lists are sorted into 
ascending order to avoid permutations of otherwise compatible target 
list(e.g. client1 supports target list B,C,A and client2 C,B,A: they 
should both rely on A,B,C).  By sharing the targets table, clients 
may pass target lists between themselves by exchanging only the 
corresponding target list index in the protocol messages (X Client 
Message are limited in size). Note that the targets <Property>TARGETS</Property> and 
<Property>MULTIPLE</Property>, which are mandatory per ICCCM requirement, are not 
mentioned in this list.
</Para>

<Para>
To add a target list to the table, a client must first sorts its 
target list into ascending order, then search the targets table for a 
match. If it finds a match, it may use the index of the matching 
targets table entry in the drag protocol (starting at 0).  Otherwise, 
it adds the sorted target list to the table, anywhere, but atomically 
(e.g. under ServerGrab) updates the <Property>_MOTIF_DRAG_TARGETS</Property> property on 
motif Drag Window, and uses the index of the new targets table entry.
</Para>

<Para>
Since the protocol uses X client messages of fixed size, limited to 
20 bytes:
</Para>
<ItemizedList>
<ListItem> <Para>the protocol uses properties on the source and destination windows to exchange extra information that would not fit in the available bytes. The property name is indicated in the message data.
</Para></ListItem>

<ListItem> <Para>every X client message has an XClientMessageEvent message_type that uses the Atom <Property>_MOTIF_DRAG_AND_DROP_MESSAGE</Property>.  The actual type of the request or reply is indicated in a byte in the data buffer called the Reason. Thus every client message from the protocol contains:
</Para>
<ItemizedList>
<ListItem> <Para><Literal>window</Literal>          the window receiving the event            
</Para></ListItem>

<ListItem> <Para><Literal>message_type</Literal>    the atom <Property>_MOTIF_DRAG_AND_DROP_MESSAGE</Property>
</Para></ListItem>
      
<ListItem> <Para><Literal>format</Literal>      8  (no byte swapping done by X Server)        
</Para></ListItem>

<ListItem> <Para><Literal>data.b[0]</Literal>       one byte for the reason (type of request/reply + originator)            
</Para></ListItem>

<ListItem> <Para><Literal>data.b[1]</Literal>       byte order of the data buffer
</Para></ListItem>

<ListItem> <Para><Literal>data.b[...]</Literal>     rest of the message content
</Para></ListItem>

<ListItem> <Para>the protocol uses bit fields within bytes to transmit 
	information (see exact encoding section).
</Para></ListItem>
</ItemizedList>
</ListItem>
</ItemizedList>

<Para>A receiver is a top level window that contains drop sites. A receiver 
advertises itself by placing a property on its top level window:
</Para>
<ItemizedList>
<ListItem> <Para>property name <Property>_MOTIF_DRAG_RECEIVER_INFO </Property>
</Para></ListItem>

<ListItem> <Para>property type   <Property>_MOTIF_DRAG_RECEIVER_INFO </Property>
</Para></ListItem>

<ListItem> <Para>property format 8
</Para></ListItem>
</ItemizedList>

<Para>The property is at least 16 bytes and contains:
</Para>
<ItemizedList>
<ListItem> <Para><Literal>BYTE</Literal>    byte order of data in property 
</Para></ListItem>

<ListItem> <Para><Literal>BYTE</Literal>    protocol version of receiver 
</Para></ListItem>

<ListItem> <Para><Literal>BYTE</Literal>    protocol style == Dynamic, DropOnly, None 
</Para></ListItem>

<ListItem> <Para><Literal>BYTE</Literal>    unspecified 
</Para></ListItem>

<ListItem> <Para><Literal>CARD32</Literal>  unspecified 
</Para></ListItem>

<ListItem> <Para><Literal>CARD32</Literal>  unspecified 
</Para></ListItem>

<ListItem> <Para><Literal>CARD32</Literal>  unspecified
</Para></ListItem>
</ItemizedList>

<Para>
A style of Dynamic means that the receiver will accept and answer 
Drag Protocol X Client Messages sent by the source.
</Para>

<Para>
A style of DropOnly means that the source should not send any message 
to the receiver, except for DROP_START, and that drop will be 
accepted in the receiver toplevel. The default drag-over will 
indicate such a possibility to the user, anywhere in the target 
window. It acts as if a single drop-site was associated with the 
receiver toplevel window, accepting all possible targets and 
operations.
</Para>

<Para>
A style of None means that drops are not allowed anywhere in the 
receiver window, and will automatically fail. Drag-over feedback 
should indicate such an impossibility.
</Para>

<Para>
When starting a drag, the initiator creates a property on the source 
window, of type <Property>_MOTIF_DRAG_INITIATOR_INFO</Property>, containing information 
about the drag, of which the target index, i.e. the index in the 
target list table described above. The name of that property is 
passed in the drag protocol requests.
</Para>

<Para>
This source window property indicates:
</Para>
<ItemizedList>
<ListItem> <Para><Literal>BYTE</Literal>      byte order of data in the property 
</Para></ListItem>

<ListItem> <Para><Literal>BYTE</Literal>      protocol version 
</Para></ListItem>

<ListItem> <Para><Literal>CARD16</Literal>  an index in the pre-converted <Property>TARGETS</Property> table described above 
</Para></ListItem>

<ListItem> <Para><Literal>CARD32</Literal>  the selection Atom for the data transfer at drop time (itself., see below)
</Para></ListItem>
</ItemizedList>


<Para>
The drag protocol messages are the following (all timestamps are set 
to the corresponding X Event triggering the message: crossing event, 
mouse motion, button release, etc):
</Para>

<Para>
When entering a new top level, the initiator sends TOP_LEVEL_ENTER 
message (XClientMessage type <Property>_MOTIF_DRAG_AND_DROP_MESSAGE</Property>) 
containing:
</Para>
<ItemizedList>
<ListItem> <Para><Literal>BYTE</Literal>         reason = TOP_LEVEL_ENTER 
</Para></ListItem>

<ListItem> <Para><Literal>BYTE</Literal>         byte order 
</Para></ListItem>

<ListItem> <Para><Literal>CARD16</Literal>	   0 
</Para></ListItem>

<ListItem> <Para><Literal>CARD32</Literal>       timestamp 
</Para></ListItem>

<ListItem> <Para><Literal>CARD32</Literal>       source window id
</Para></ListItem>

<ListItem> <Para><Literal>CARD32</Literal>       Atom == initiator property on the source window and selection Atom for the data transfer at  drop time
</Para></ListItem>
</ItemizedList>

<Para>
The selection Atom in the above property must be unique for the 
duration of the Drag and Drop transaction, and the 
initiator must own the selection and be ready to convert data for its 
target from the start of the gesture, since the 
receiver may want to do a conversion dynamically to validate an 
operation.
</Para>

<Para>
The receiver does not reply to this message
</Para>

<Para>
When leaving a top level window the initiator sends a TOP_LEVEL_LEAVE 
message containing:
</Para>
<ItemizedList>
<ListItem> <Para><Literal>BYTE</Literal>         reason = TOP_LEVEL_LEAVE 
</Para></ListItem>

<ListItem> <Para><Literal>BYTE</Literal>         byte order 
</Para></ListItem>

<ListItem> <Para><Literal>CARD16</Literal>	     0 
</Para></ListItem>

<ListItem> <Para><Literal>CARD32</Literal>       timestamp 
</Para></ListItem>

<ListItem> <Para><Literal>CARD32</Literal>       source window 
</Para></ListItem>
</ItemizedList>

<Para>
The receiver does not reply to this message.
</Para>

<Para>
After entering a top level window, when the pointer moves, the 
initiator sends a DRAG_MOTION message:
</Para>
<ItemizedList>
<ListItem> <Para><Literal>BYTE</Literal>           reason = DRAG_MOTION 
</Para></ListItem>

<ListItem> <Para><Literal>BYTE</Literal>           byte order 
</Para></ListItem>

<ListItem> <Para><Literal>CARD16</Literal>         one recommended and a set of possible side effects (move,copy,link,noop) 
</Para></ListItem>

<ListItem> <Para><Literal>CARD32</Literal>          timestamp 
</Para></ListItem>

<ListItem> <Para><Literal>CARD16</Literal>          x relative to rootwindow 
</Para></ListItem>

<ListItem> <Para><Literal>CARD16</Literal>          y relative to rootwindow
</Para></ListItem>
</ItemizedList>

<Para>
The operation and operations fields of the side effect <Literal>CARD16</Literal> bit 
field are used to convey, resp., the recommended and possible side 
effects. 
</Para>

<Para>
If the pointer enters a drop site the receiver replies with a 
DROP_SITE_ENTER message:
</Para>
<ItemizedList>
<ListItem> <Para><Literal>BYTE</Literal>         reason = DROP_SITE_ENTER 
</Para></ListItem>

<ListItem> <Para><Literal>BYTE</Literal>         byte order 
</Para></ListItem>

<ListItem> <Para><Literal>CARD16</Literal>       one selected and a set of possible side effect, + status (valid-drop-site, invalid-drop-site) 
</Para></ListItem>

<ListItem> <Para><Literal>CARD32</Literal>        timestamp 
</Para></ListItem>

<ListItem> <Para><Literal>CARD16</Literal>        better-x  relative to rootwindow 
</Para></ListItem>

<ListItem> <Para><Literal>CARD16</Literal>        better-y  relative to rootwindow
</Para></ListItem>
</ItemizedList>

<Para>
The `better' position is set by the receiver as a hint for the source 
on where the drag-over icon should be placed during the gesture (the 
source can warp the pointer to that location). "operations" plural is 
the list of operations that the receiver supports,  "operation" 
singular is the one retained so far by the drag source and 
acknowledged by the receiver.
</Para>

<Para>
If the pointer leaves a drop site the receiver replies with a 
DROP_SITE_LEAVE message:
</Para>
<ItemizedList>

<ListItem> <Para><Literal>BYTE</Literal>         reason = DROP_SITE_LEAVE 
</Para></ListItem>

<ListItem> <Para><Literal>BYTE</Literal>         byte order 
</Para></ListItem>

<ListItem> <Para><Literal>CARD32</Literal>       timestamp
</Para></ListItem>
</ItemizedList>

<Para>
If the pointer does not enter or leave a drop site the receiver 
echoes a DRAG_MOTION message
</Para>
<ItemizedList>

<ListItem> <Para><Literal>BYTE</Literal>         byte order 
</Para></ListItem>

<ListItem> <Para><Literal>BYTE</Literal>         reason = DRAG_MOTION 
</Para></ListItem>

<ListItem> <Para><Literal>CARD16</Literal>       one selected and a set of  possible side effect, + status 
</Para></ListItem>

<ListItem> <Para><Literal>CARD32</Literal>        timestamp 
</Para></ListItem>

<ListItem> <Para><Literal>CARD16</Literal>        better-x  relative to rootwindow 
</Para></ListItem>

<ListItem> <Para><Literal>CARD16</Literal>        better-y  relative to rootwindow
</Para></ListItem>
</ItemizedList>

<Para>
The user may change the recommended side effect during the drag (e.g. 
using modifier key). The initiator then sends an OPERATION_CHANGED 
message:
</Para>
<ItemizedList>

<ListItem> <Para><Literal>BYTE</Literal>          reason = OPERATION_CHANGED 
</Para></ListItem>

<ListItem> <Para><Literal>BYTE</Literal>          byte order 
</Para></ListItem>

<ListItem> <Para><Literal>CARD16</Literal>        one recommended and a set of possible side effect 
</Para></ListItem>

<ListItem> <Para><Literal>CARD32</Literal>        timestamp
</Para></ListItem>
</ItemizedList>

<Para>
The receiver echoes the message with the selected side effect:
</Para>
<ItemizedList>

<ListItem> <Para><Literal>BYTE</Literal>         byte order 
</Para></ListItem>

<ListItem> <Para><Literal>BYTE</Literal>         reason = OPERATION_CHANGED 
</Para></ListItem>

<ListItem> <Para><Literal>CARD16</Literal>       the selected and the set of possible side effect, +  status 
</Para></ListItem>

<ListItem> <Para><Literal>CARD32</Literal>       timestamp
</Para></ListItem>
</ItemizedList>

</Sect1>

<Sect1 Id="MOTIF.dnd.div.4">
<Title>The Drop protocol</Title>
<Para><Anchor XRefLabel="dnd_drop" Role="2" Id="MOTIF.dnd.anch.4">
</Para>

<Para>
The drop protocol may be used independently of the drag protocol 
(i.e. in DropOnly mode). The drop protocol consists of a single 
message that is echoed by the receiver. After that message, if the 
drop is not cancelled or postponed, the receiver proceeds with an X 
selection transfer to transfer the data.
</Para>

<Para>
The initiator sends a drop message, which indicates:
</Para>
<ItemizedList>

<ListItem> <Para><Literal>BYTE</Literal>          reason = DROP_START 
</Para></ListItem>

<ListItem> <Para><Literal>BYTE</Literal>          byte order 
</Para></ListItem>

<ListItem> <Para><Literal>CARD16</Literal>        one recommended and a set of possible side effects 
</Para></ListItem>

<ListItem> <Para><Literal>CARD32</Literal>        timestamp 
</Para></ListItem>

<ListItem> <Para><Literal>CARD16</Literal>        x relative to rootwindow 
</Para></ListItem>

<ListItem> <Para><Literal>CARD16</Literal>        y relative to rootwindow 
</Para></ListItem>

<ListItem> <Para><Literal>CARD32</Literal>        Atom == property on the source window 
</Para></ListItem>

<ListItem> <Para><Literal>CARD32</Literal>        source Window 
</Para></ListItem>
</ItemizedList>

<Para>
The atom indicates the name of the property described above (in the 
drag protocol) that the initiator sets up when the drag starts, 
containing the target index and the selection atom to be used for 
selection requests.
</Para>

<Para>
The receiver echoes the message with:
</Para>
<ItemizedList>

<ListItem> <Para><Literal>BYTE</Literal>          reason = DROP_START
</Para></ListItem>

<ListItem> <Para><Literal>BYTE</Literal>          byte order 
</Para></ListItem>

<ListItem> <Para><Literal>CARD16</Literal>        selected and set of possible side effect, status, and drop action: (drop, drop-help, drop-cancel) 
</Para></ListItem>

<ListItem> <Para><Literal>CARD16</Literal>        better-x 
</Para></ListItem>

<ListItem> <Para><Literal>CARD16</Literal>        better-y
</Para></ListItem>
</ItemizedList>



<Para>
If the drop is Valid and the action is drop, the receiver will 
achieve a selection transfer, using the atom in the source window 
property. The initiator should select for DestroyNotify on the 
destination window such that it is aware of a potential receiver 
crash.
</Para>

<Para>
Similarly, the receiver should select for DestroyNotify on the source 
window if it intends to proceed with the drop.
</Para>

<Sect2 Id="MOTIF.dnd.div.5">
<Title>Data transfer and termination on the initiator side</Title>

<Para>
The receiver may request for as many transfer as it wants to, using X 
selection requests to the selected targets. On each conversion 
request, the initiator replies using the ICCCM selection.
</Para>

<Para>
The resources allocated during the Drag should not be released until 
the Drop is finished, i.e., the initiator must not release any 
resources concerning the drop until it receives a conversion request 
for the drop selection to either target <Property>XmTRANSFER_SUCCESS</Property> or 
<Property>XmTRANSFER_FAILURE</Property>.
</Para>

<Para>
When it receives such a conversion request it must reply with a empty 
value.
</Para>
</Sect2>

<Sect2 Id="MOTIF.dnd.div.6">
<Title>Data transfer and termination on the receiver side</Title>

<Para>
The receiver may proceed with multiple selection requests on the drop 
selection.
</Para>

<Para>
When it is finished, it must issue a conversion request to either 
<Property>XmTRANSFER_SUCCESS</Property> or <Property>XmTRANSFER_FAILURE</Property>. The receiver should release 
all resources about the drop. only when it receives acknowledgment of 
that. 
</Para>

<Para>
That's also when the melting or failure/snapback visual effect should 
occur.
</Para>

</Sect2>
</Sect1>

<Sect1 Id="MOTIF.dnd.div.7">
<Title>Encoding</Title>
<Para><Anchor XRefLabel="dnd_enc" Role="2" Id="MOTIF.dnd.anch.5">
</Para>

<Para>
In addition to the above byte size level description, this section 
gives detailed value encoding for most fields.
</Para>

<Sect2 Id="MOTIF.dnd.div.8">
<Title>byte_order</Title>

<Para>
The value of the byte must be octal 102 or 154 (same as X Protocol)	.  
</Para>
<ItemizedList>

<ListItem> <Para>the value 102 (ASCII uppercase B) means values are transmitted	most-significant byte first, 
</Para></ListItem>

<ListItem> <Para>the value 154 (ASCII lowercase l) means values are transmitted
 least-significant byte first.
</Para></ListItem>
</ItemizedList>
</Sect2>

<Sect2 Id="MOTIF.dnd.div.9">
<Title>protocol version  </Title>      
<ItemizedList>

<ListItem> <Para>byte value: 0 
</Para></ListItem>
</ItemizedList>

</Sect2>

<Sect2 Id="MOTIF.dnd.div.10">
<Title>protocol style  </Title>      
<ItemizedList>

<ListItem> <Para>drag_none: 0 	
</Para></ListItem>

<ListItem> <Para>drag_drop_only: 1, ==3 	
</Para></ListItem>

<ListItem> <Para>drag_dynamic: 5 ==2, ==4 	
</Para></ListItem>
</ItemizedList>

<Para>
The first number is the value a receiver should set. == points to 
additional values that must be interpreted as meaning the same for 
the source (i.e. is the protocol_style speficied by a receiver is 3, 
it means the source must act as if it had indicated drop-only: 1). 
</Para>

</Sect2>

<Sect2 Id="MOTIF.dnd.div.11">
<Title>target table  </Title>      

<Para>
As indicated above, it's list of atom list, sorted in ascending order 
(smaller atom value first).
</Para>

<Para>
The property starts with: 	    
</Para>

<ItemizedList>
<ListItem> <Para><Literal>BYTE</Literal>       byte order of data 	    
</Para></ListItem>

<ListItem> <Para><Literal>BYTE</Literal>       protocol version 	    
</Para></ListItem>

<ListItem> <Para><Literal>CARD16</Literal>     num_target_lists 	    
</Para></ListItem>

<ListItem> <Para><Literal>CARD32</Literal>     data_size 	 
</Para></ListItem>
</ItemizedList>

<Para>
data_size is the total size in bytes of the property: the above 8 
bytes + num_target_lists * (2 + num_target_in_each_list * 4). Each 
list starts with number of target in the list, on 2 bytes, and then 
the atoms. 	 
</Para>

</Sect2>

<Sect2 Id="MOTIF.dnd.div.12">
<Title>reason field  </Title>      

<Para>
The 8 bits of the reason (message type) field are allocated as 
follows:
</Para>
<ProgramListing>
                Low order   X  |

                            X  | 

                            X  |

                            X  |    reason     

                            X  |   

                            X  | 

                            X  |



                High order  X  |    originator

</ProgramListing>


<Para>The reason codes are:
</Para>

<ItemizedList>
<ListItem> <Para>top-level-enter: 0 	   
</Para></ListItem>

<ListItem> <Para>top-level-leave: 1 	   
</Para></ListItem>

<ListItem> <Para>drag-motion: 2 	   
</Para></ListItem>

<ListItem> <Para>drop-site-enter: 3 	   
</Para></ListItem>

<ListItem> <Para>drop-site-leave: 4 	   
</Para></ListItem>

<ListItem> <Para>operation-changed: 8 	   
</Para></ListItem>

<ListItem> <Para>drop-start: 5
</Para></ListItem>
</ItemizedList>

<Para>
The originator bit indicates where the message originated from:
</Para>

<ItemizedList>
<ListItem> <Para>0 for initiator, 
</Para></ListItem>

<ListItem> <Para>1 for receiver
</Para></ListItem>
</ItemizedList>
</Sect2>

<Sect2 Id="MOTIF.dnd.div.13">
<Title>side effect bitfield  </Title>      

<Para>
The 16 bits of the flag field are allocated as follows:
</Para>

<ProgramListing>
                Low order   X  |

                            X  |  Operation mask (4 bits)

                            X  |

                            X  |



                            X  |

                            X  |  Drop Site Status (4 bits)

                            X  |

                            X  |



                            X  |

                            X  |  Operations mask (4 bits)

                            X  |

                            X  |



                            X  |

                            X  |  Drop Action (Completion) (4 bits)

                            X  |

                High order  X  |

</ProgramListing>


<Para>
The operation is the recommended or selected side-effect, and 
operations is the set of possible alternatives.
</Para>

</Sect2>

<Sect2 Id="MOTIF.dnd.div.14">
<Title>operation(s)  </Title>      

<Para>
The valid value are in mask:
</Para>

<ItemizedList>
<ListItem> <Para>noop    0 	
</Para></ListItem>

<ListItem> <Para>move 	(1L << 0)         
</Para></ListItem>

<ListItem> <Para>copy  	(1L << 1)         
</Para></ListItem>

<ListItem> <Para>link	(1L << 2)
</Para></ListItem>
</ItemizedList>

</Sect2>

<Sect2 Id="MOTIF.dnd.div.15">
<Title>status  </Title>      

<Para>
The valid values are:
</Para>

<ItemizedList>
<ListItem> <Para>no-drop-site: 1 	
</Para></ListItem>

<ListItem> <Para>invalid-drop-site: 2 	
</Para></ListItem>

<ListItem> <Para>valid-drop-site: 3
</Para></ListItem>
</ItemizedList>

</Sect2>

<Sect2 Id="MOTIF.dnd.div.16">
<Title>drop action  </Title>      

<Para>
The valid values are:
</Para>

<ItemizedList>
<ListItem> <Para>drop: 0 	   
</Para></ListItem>

<ListItem> <Para>drop-help: 1 	   
</Para></ListItem>

<ListItem> <Para>drop-cancel: 2
</Para></ListItem>
</ItemizedList>
</Sect2>
</Sect1>
</Chapter>
</Book>
</DocBook>
