%
% DragNDrop.tex -- 
%
% (c) 1996 The Hungry Programmers
% (c) 1996 Harald Albrecht (albrecht@igpm.rwth-aachen.de)
% See the file PUBLIC for details.
%
\chapter{Drag and Drop}
\by{Harald Albrecht\\Mitch Miers}

\section{Introduction}

The "Drag \& Drop" mechanism is a metaphor for data transfer, which
allows the user to pick up an object with the mouse pointer, and move
it to another location (which can be even in another application) and
drop it there. This metaphor is the same no matter what kind of data
is transfered. In most cases, the ``Drag \& Drop'' gesture results in
data being moved or copied to the new location, but it can also invoke
an action -- like printing a file when dropping the icon of a file on
a printer icon, or de-installing some so-called ``operating system''
when dropping its flying logo into the trash bin.

Although the term ``Drag \& Drop'' suggests that both the drag and the
drop operation are inseparable, in fact the \emph{drop} operation is
independent of the \emph{drag} operation. To transfer data, only the
drop operation is needed. The drag operation is just there to make the
metaphor work better, as an application can provide accurate visual
feedback about the state of the operation. As a consequence of this,
we'll discuss the drag protocol and the drop protocol in separate
sections.

As you can easily imagine, a good part of the whole protocol mess is
undocumented. Fortunately, Daniel Dardailler's documentation and
initial implementation example of the dynamic drag protocol was
invaluable help for understanding the drag and drop
protocol. Unfortunately, his documentation does only cover the
\emph{dynamic} mode of operation, which is now standardized with
CDE~2. The other mode, \emph{preregister}, is still undocumented,
although it is the default mode for drag and drop operations in the
\Motif{} toolkit (one more own goal for the \CSF{}).


\section{Protocol Basics}

\index{initiator}\index{drop!initiator}%
\index{receiver}\index{drop!receiver}%
The top level window where the drag and drop operation starts is
called the ``source window''. The client who owns this window is
called the initiator client, or short ``initiator''. The drop
operation then takes place in the ``destination window'' and the
client who owns that window is called the ``receiver''. The initiator
and the receiver of the drag and drop operation can be the same client
-- but this need not necessarily be always the case. Besides this,
even the source and the destination window may be the same.

\index{drop!site}%
From the user's point of view there are no such things like windows
recognizable. The only ``objects'' the user deals with are the ``drop
sites'', which appear to her/him as entities supplying or receiving
information. On the technical side, a drop site may be drawn into its
own window or may be drawn as a part of a larger window containing
other objects too. The protocol does not put any restrictions on how
drop sites are organized within windows. To avoid a possible upcoming
confusion, the protocol only knows of and works with the top level
windows. Remember, according to the ICCCM 2.0, top level windows are
distinguishable from ordinary windows by their \code{WM\_STATE}
properties.

Okay, after you've now learned some new ``drag and drop'' buzz words,
you're now ready to dive into the world of bitfields and status codes.
Afterwards, you'll meet the various drag and drop messages which make
up the protocol.


\subsection{Drag Operation Modes}

Both the drag and the drop protocol are build around X client messages
which are send forth and back between the initiator and receiver of
the drag and drop operation. Such messages are emitted during the
start, cancelation or end of a drag and drop operation, or as the user
moves the mouse pointer around the screen and the pointer enters and
leaves valid drop sites. This way, the initiator client and the
potential receiver client(s) can provide to the user some visual
feedback about the current state of the drag operation. Such a visual
feedback could be highlighting a drop site so the user notices the
existence of a valid drop site. There are two sets of visual
feedbacks: the ``drag-over visuals'' of the initiator and the
``drag-under'' visuals of the receiver(s).

The drag operation as well as the handling of the drag-under visuals
are different depending on the operation mode of the drag:

\begin{itemize}
\index{dynamic mode}\index{drag!dynamic mode}%
\item When both the initiator and receiver have agreed to use the
  \emph{dynamic} mode they exchange protocol messages dealing (for
  example) with entering and leaving drop sites \emph{during} the drag
  operation. The advantages of this mode are that the X server is not
  grabbed and can still respond to other event sources, and the
  receiver can decide what data to accept on-the-fly.  On the other
  side, the dynamic operation mode requires more overhead on behalf of
  the application and the network.

\index{preregister mode}\index{drag!preregister mode}%
\item The \emph{preregister} mode is the other possible mode of
  operation (the appropriate protocol is still undocumented). In this
  mode, the \Motif{} toolkit handles on behalf of the initiator client
  the complete processing of the drag-under visuals which would
  ordinarily occour in the receiver client. The receiver is not
  involved in the process until the drop stage begins. But it has to
  supply information about drop sites so the initiator can handle the
  drag-under visuals accordingly. This mode minimises network trafic,
  but the drop site can't determine whether it wants to accept the
  drop data until the drop actually occurs. In addition, the server is
  grabbed during the drag operation.
\end{itemize}


\subsection{Protocol Messages}

\codeindex{XClientMessageEvent}%
\index{drag!window}\index{client message}\index{drag!client message}%
Unfortunately, X client messages (of type \code{XClientMessageEvent})
are limited in size: you can only transfer up to 20 bytes within them.
For this reason, \Motif{} applications use a ``drag window'' with
special properties attached to it to transfer any additional
information which uses up to much space. Some of the protocol messages
therefore just refer to a data structure stored with the drag window.

\codeindex{\_MOTIF\_DRAG\_AND\_DROP\_MESSAGE}%
The various X client messages used for the drag or drop protocol share
a common header and some common settings.
\begin{itemlist}
\item The \code{message\_type} of such an X client message event is
  always set to the atom with the name
  \code{\_MOTIF\_DRAG\_AND\_DROP\_MESSAGE}.
  
\item The \code{format} of the message event is \code{8}, so no byte
  swapping is performed by the X server. The clients participating in
  the drag and drop mechanism must do the byte swapping themselves.
  The reason for this is that the available 20 bytes can be exploited
  best this way.
  
\item The \code{window} identifier of the \code{XClientMessageEvent}
  contains the identifier of the window receiving this message.
  
\item The first user byte \code{data.b[0]} of the message event
  indicates why this message was sent. It is a bitfield with the high
  bit (bit 7) indicating whether the originator or the receiver
  generated the message, and the remaining bits 6--0 denoting the
  reason. The reason can be anyone of the message types listed in
  table \ref{cl_message_types}.  These message types are discussed in
  detail in the sections below.

\begin{figure}[h!]
  \hskip\leftmargin\includegraphics[scale=1.09]{DD_Reason}
\end{figure}

\begin{table}[h]\begin{center}\begin{tabular}[h]{|l|c|}
\hline
Identifier & Value\\
\hline
\code{XmTOP\_LEVEL\_ENTER} & \code{0x00} \\
\code{XmTOP\_LEVEL\_LEAVE} & \code{0x01} \\
\code{XmDRAG\_MOTION} & \code{0x02} \\
\code{XmDROP\_SITE\_ENTER} & \code{0x03} \\
\code{XmDROP\_SITE\_LEAVE} & \code{0x04} \\
\code{XmDROP\_START} & \code{0x05} \\
\code{XmDROP\_FINISH} & \code{0x06} \\
\code{XmDRAG\_DROP\_FINISH} & \code{0x07} \\
\code{XmOPERATION\_CHANGED} & \code{0x08} \\
\hline
\end{tabular}%
{\caption{\label{cl_message_types}Message types used for the Drag \& Drop
X client messages.}}%
\end{center}\end{table}\vspace{-0.2cm}

\index{byte order}
\item \code{data.b[1]} indicates the byte order used for the encoding
  of the following data. Like in the X Protocol it must be set to
  either the ASCII uppercase letter `\code{B}' when the
  \emph{most}-significant byte is transmitted first, or to the ASCII
  lowercase letter `\code{l}' when the \emph{least}-significant byte
  is transmitted first.
  
\item The data bytes \code{data.b[2]} through \code{data.b[19]}
  contain the remaining bytes of the drag and drop message.
\end{itemlist}


\subsection{Drag \& Drop Flags}

\index{drag!flags}%
Many of the drag and drop messages contain a flag bitfield, which is
called the ``DnD Flags'' throughout this documentation. The ``DnD
Flags'' consist of four distinct bitfields -- each of it is four bits
wide and is labeled \circled{1} through \circled{4} in figure
\ref{DD_Effect}.

Not every message makes use of every of the four bitfields. Some drag
and drop messages don't use the ``DnD Flags'' at all, although they
contain a spare field with the same size and in the same position as
the ``DnD Flags''. Below, the descriptions of the various drag and
drop messages will refer to this bitfields \circled{1} through
\circled{4}.  Thus, you can easily tell, which bitfields are used for
a particular message.

\begin{figure}[!ht]
\hskip\leftmargin\includegraphics[scale=1.09]{DD_Effect}
\caption{\label{DD_Effect}The ``DnD Flags'' signal various status conditions
during a drag and drop operation.}
\end{figure}

Their purpose is as follows:

\begin{itemlist}
\item[\circled{1}] Operation: this bitfield contains the
  \emph{recommended} type of drag and drop operation, if it is used in
  a message sent by the initiator. If the message was sent instead by
  the receiver, then this bitfield contains the \emph{selected} type
  of drag and drop operation.  Thus, the receiver is free to
  ``dictate'' the kind of drag and drop operation. See table
  \ref{operation_codes} for possible values.
\item[\circled{2}] Drop Site Status: this bitfield is only used by the
  receiver to inform the initiator whether the pointer is currently
  hoovering over a valid/invalid drop site or no drop site at all. See
  table \ref{drop_site_status} for possible values.
\item[\circled{3}] Other possible operations: this is a bitset (binary
  OR) of all the operations that can be carried out on the current
  drop site. If the pointer isn't currently over a valid drop site,
  then this bitset has all its bits set to zero (\code{XmDROP\_NOOP}).
  See table \ref{operation_codes} for the values of the various flags.
\item[\circled{4}] Drop Action: this bitfield is used only when
  starting the \emph{drop} operation. In this particular case it is
  used by the receiver to indicate the drop action which the receiver
  is going to carry out. See table \ref{completion_status} for valid
  completion status codes.
\end{itemlist}

\vspace{0.5cm}
\begin{table}[!h]
\begin{minipage}[t]{70mm}
\begin{center}\begin{tabular}[h]{|l|c|}
\hline
Identifier & Value\\
\hline
\code{XmDROP\_NOOP} & \code{0x00} \\
\code{XmDROP\_MOVE} & \code{0x01} \\
\code{XmDROP\_COPY} & \code{0x02} \\
\code{XmDROP\_LINK} & \code{0x04} \\
\hline
\end{tabular}%
{\caption{\label{operation_codes}Operation codes.}}%
\vspace*{-0.4cm}
\end{center}
\end{minipage}
\hfill
\begin{minipage}[t]{70mm}
\begin{center}\begin{tabular}[h]{|l|c|}
\hline
Identifier & Value\\
\hline
\code{XmDROP} & \code{0x00} \\
\code{XmDROP\_HELP} & \code{0x01} \\
\code{XmDROP\_CANCEL} & \code{0x02} \\
\code{XmDROP\_INTERRUPT} & \code{0x03} \\
\hline
\end{tabular}%
{\caption{\label{completion_status}Completion status codes.}}%
\vspace{-0.4cm}
\end{center}
\end{minipage}
\end{table}

\begin{table}[h]\begin{center}\begin{tabular}[h]{|l|c|}
\hline
Identifier & Value\\
\hline
\code{XmNO\_DROP\_SITE} & \code{0x01} \\
\code{XmDROP\_SITE\_INVALID} & \code{0x02} \\
\code{XmDROP\_SITE\_VALID} & \code{0x03} \\
\code{XmINVALID\_DROP\_SITE} {\scriptsize\sc(Deprecated Symbol)}
  & \code{0x02} \\
\code{XmVALID\_DROP\_SITE} {\scriptsize\sc(Deprecated Symbol)}
  & \code{0x03} \\
\hline
\end{tabular}%
{\caption{\label{drop_site_status}Drop site status codes.}}%
\vspace{-0.4cm}
\end{center}\end{table}


\subsection{The Targets Table}

The \Motif{} toolkit uses a special persistent, input-only, and
override-redirected window to store some data needed for the whole
drag and drop infrastructure. This special window is a child of the
display's default root window and is called the ``\Motif{} Drag
Window''. In order that clients can find this window at all, they
should watch out for the property \code{\_MOTIF\_DRAG\_WINDOW} (of
type \code{WINDOW}, with a size of 32) on their display's default root
window. If there's no such property, or the window ID stored in the
property is either \code{0} or invalid, then an client should create
the ``\Motif{} Drag Window'' itself. The ``\Motif{} Drag Window''
should have a close-down mode of \code{RetainPermanent} (use
\code{XSetCloseDownMode()} for this), so other applications don't have
to create it themselves.

The ``\Motif{} Drag Window'' currently seems to posses three
properties named \code{\_MOTIF\_DRAG\_\-TARGETS} (of type
\code{\_MOTIF\_DRAG\_TARGETS}, size is 8), \code{\_MOTIF\_DRAG\_ATOMS}
(of type -- guess which -- \code{\_MO\-TIF\_DRAG\_ATOMS}), and finally
\code{\_MOTIF\_DRAG\_ATOM\_PAIRS} (of course of the type
\code{\_MOTIF\_\-DRAG\_ATOM\_PAIRS}).

\index{targets table}%
Of primary interest to us is the \code{\_MOTIF\_DRAG\_TARGETS}
property: it is a list of target lists, which is shared among all
clients, and is commonly called the ``targets table''. Every target
list within the targets table is a list of target (data types) an
initiator can supply to a receiver on request. Remember, that the X
client messages only provide precious little space for the client's
data.  Thus, instead of passing such lists around, you only need to
pass a single \code{CARD16} value that acts as an index (0-based) into
the list of target lists. By specifying such an index, a receiver
knows which kinds of data it can request from the initiator during the
drop phase.

Whenever a client needs to add his target list(s) to the targets
table, it must follow some guidelines, otherwise the targets table
could become messed up. Every target list must be sorted into
ascending order (according to the atom ID's) to avoid permutations of
otherwise compatible target lists.  Thus, if a client supports the
target types ``B,A,C'' and another client supports the target types
``C,B,A'', then they must both use the sorted target types list
``A,B,C'' instead.  Note however that the targets \code{TARGETS} and
\code{MULTIPLE} -- which are mandatory according to the ICCCM -- are
never listed. The structure of the targets table is fairly
straightforward and is shown in table \ref{target_table_bin}.

\codeindex{\_MOTIF\_DRAG\_TARGETS}%
\begin{table}[!ht]\begin{center}\begin{tabular}[h]{|l|l|p{9cm}|}
\hline
Offset & Size & Description\\
\hline
\code{+0x00} & \code{BYTE} &
\textbf{Byte Order}: either '\code{B}' (MSB first) or '\code{l}'
(LSB first).\\
\code{+0x01} & \code{BYTE} &
\textbf{Protocol Version}: currently \code{0}.\\
\code{+0x02} & \code{CARD16} &
\textbf{Number of Target Lists}: this should be really self-explanatory.\\
\code{+0x04} & \code{CARD32} &
\textbf{Data Size}: total size of the data stored in the property:\\
& & \hspace{2.5cm} 8 bytes for the header +\\
& & \hspace{2.5cm} Number of Target Lists * 2 +\\
& & \hspace{2.5cm} Total Number of Targets * 4\\
\hline
\code{+0x08} & \code{CARD16} &
\hspace{0.5cm}\textbf{Number of Targets in List}\\
\code{+0x0A} & \code{CARD32} &
\hspace{0.5cm}\textbf{List of Targets}\\
\hline
\code{+0x??} & \code{CARD16} &
\hspace{0.5cm}\textbf{Number of Targets in List}\\
\code{+0x??} & \code{CARD32} &
\hspace{0.5cm}\textbf{List of Targets}\\
\hline
& & \hspace{0.5cm}\emph{...and so on...}\\
\hline
\end{tabular}%
{\caption{\label{target_table_bin}Structure of the targets table
in the property \code{\_MOTIF\_DRAG\_TARGETS}.}}%
\vspace{-0.4cm}\end{center}\end{table}

In order to add its target list(s) to the targets table stored in the
\code{\_MOTIF\_DRAG\_TARGETS} property, a client must grab the X
server, so the operation is atomically. Then it has to search the
targets table for a match.  Otherwise, the client can add the
particular (sorted) target list to the table anywhere (the target
table itself is not sorted -- sigh).  After it has updated the
\code{\_MOTIF\_DRAG\_TARGETS} property, the client can remove the
grab.


\subsection{Advertising a Receiver}

A receiver advertises itself by placing a property with the name
\code{\_MOTIF\_DRAG\_RECEIVER\_INFO} (of type
\code{\_MOTIF\_DRAG\_RECEIVER\_INFO}, size is 8) on its top level
window. Depending on the protocol styles the receiver can handle
(dynamic mode and/or preregister mode), this property contains more or
less data. But at least the property must be 16 bytes long.

\codeindex{\_MOTIF\_DRAG\_RECEIVER\_INFO}%
\begin{table}[!ht]\begin{center}\begin{tabular}[h]{|l|l|p{9cm}|}
\hline
Offset & Size & Description\\
\hline
\code{+0x00} & \code{BYTE} &
\textbf{Byte Order}: either '\code{B}' (MSB first) or '\code{l}'
(LSB first).\\
\code{+0x01} & \code{BYTE} &
\textbf{Protocol Version of Receiver}: currently \code{0}.\\
\code{+0x02} & \code{BYTE} &
\textbf{Protocol Style}: one of the protocol styles listed in
table \ref{protocol_styles}\\
\code{+0x03} & \code{BYTE} &
\textbf{Padding}.\\
\hline
\code{+0x04} & \code{CARD32} &
\textbf{Proxy Window}: -- under construction --\\
\code{+0x08} & \code{CARD16} &
\textbf{Number of Drop Sites}: number of drop site blocks, which are
immediately following this header.\\
\code{+0x0A} & \code{CARD16} &
\textbf{Padding}.\\
\code{+0x0C} & \code{CARD32} &
\textbf{Total Size}: -- under construction --\\
\hline
\end{tabular}%
{\caption{\label{drag_receiver_info}The structure of the
\code{\_MOTIF\_DRAG\_RECEIVER\_INFO} property describes a drag
and drop receiver.}}%
\vspace{-0.4cm}\end{center}\end{table}

The second half of the header shown in table \ref{drag_receiver_info}
is only used in the preregister mode. For the dynamic mode and when
the drop site is a drop-only site, then the second half within the
header is not needed. Because the preregister mode is really tricky,
we're discussing it later in more detail.

\begin{table}[!ht]\begin{center}\begin{tabular}[h]{|l|c|}
\hline
Identifier & Value\\
\hline
\code{XmDRAG\_NONE} & \code{0x00} \\
\code{XmDRAG\_DROP\_ONLY} & \code{0x01} \\
\code{XmDRAG\_PREFER\_PREREGISTER} & \code{0x02} \\
\code{XmDRAG\_PREREGISTER} & \code{0x03} \\
\code{XmDRAG\_PREFER\_DYNAMIC} & \code{0x04} \\
\code{XmDRAG\_DYNAMIC} & \code{0x05} \\
\code{XmDRAG\_PREFER\_RECEIVER} & \code{0x06} \\
\hline
\end{tabular}%
{\caption{\label{protocol_styles}Drag protocol styles.}}%
\vspace{-0.4cm}
\end{center}\end{table}

When a receiver signals that it can handle the dynamic mode, then it
will accept and answer the drag messages sent by the initiator as
specified in the next section. If the protocol style of the receiver
is drop-only, then the initiator should not send any drag messages.
The only message the initiator is allowed to send then is the
\code{XmDROP\_START} message. In this case the visual effects during
the drag and drop gesture should indicate to the user that the whole
top level window of the receiver works as a single drop site accepting
all possible targets and operations.

A receiver with a protocol style of \code{XmDRAG\_NONE} wants not to
be disturbed by drag and drop operations at all. The initiator should
provide appropriate visual feedback whenever the drag icon is over
such a receiver.


\subsection{Starting a Drag or Drop}

When an initiator starts a drag -- or even only a drop --, then it
first creates a new property on the source window. The name of this
property can be arbitrary, but it must be of type
\code{\_MOTIF\_DRAG\_\-INITIATOR\_INFO} and have a data size of 8. This
property then should contain information about which targets the
initiator is able to serve and what selection atom to use for the data
transfer. Table \ref{drag_initiator_info} shows the structure of this
property.

\codeindex{\_MOTIF\_DRAG\_RECEIVER\_INFO}%
\begin{table}[!ht]\begin{center}\begin{tabular}[h]{|l|l|p{9cm}|}
\hline
Offset & Size & Description\\
\hline
\code{+0x00} & \code{BYTE} &
\textbf{Byte Order}: either '\code{B}' (MSB first) or '\code{l}'
(LSB first).\\
\code{+0x01} & \code{BYTE} &
\textbf{Protocol Version of Initiator}: currently \code{0}.\\
\code{+0x02} & \code{CARD16} &
\textbf{Targets Index}: the index of a targets list within the
targets table. The first list within the targets list has an index
of \code{0}. This index advertises which targets the initiator is willing
to handle.\\
\code{+0x04} & \code{CARD32} &
\textbf{Selection Atom}: atom ID to be used as the selection atom
for the data transfer when the drop actually takes place.\\
\hline
\end{tabular}%
{\caption{\label{drag_initiator_info}The structure of the
\code{\_MOTIF\_DRAG\_INITIATOR\_INFO} property describes the initiator.}}%
\vspace{-0.4cm}%
\end{center}\end{table}

Figure \ref{target_table} finally shows the four properties which are
representing an important part of the information infrastructure for the
drag and drop mechanism.

\vspace*{0.5cm}\vfill
\begin{figure}[!ht]
\centerline{\includegraphics[scale=1.09]{DD_TargetTable}}
\caption{\label{target_table}Properties involved in the Drag \& Drop game.}
\end{figure}\vspace*{0.5cm}


\section{The Drag Protocol}

\index{drag!protocol}%
During a drag operation the client is free to skip the drag protocol.
Reasons for this might be either complexity or known latencies. But in
turn the client looses the ability to provide accurate (dynamic)
feedback during the drag.


\subsection{Entering/Leaving Top Level Windows}

When the pointer enters a new top level window, the initiator notifies the
receiver with a \code{XmTOP\_\-LEVEL\_ENTER} message.

\codeindex{XmTOP\_LEVEL\_ENTER}%
\begin{table}[!h]\begin{center}\begin{tabular}[h]{|l|l|p{9cm}|}
\hline
Message User Data\hspace{0.2cm} & Size & Description\\
\hline
\code{data.b[0]} & \code{BYTE} &
\textbf{Reason}: \code{XmTOP\_LEVEL\_ENTER} (\code{0x00})\\
\code{data.b[1]} & \code{BYTE} &
\textbf{Byte Order}: either '\code{B}' (MSB first) or '\code{l}'
(LSB first).\\
\code{data.b[2..3]} & \code{CARD16} &
(\textbf{DnD Flags}: unused)\\
\code{data.b[4..7]} & \code{CARD32} &
\textbf{Timestamp}: set to the timestamp of the corresponding X event
triggering this message.\\
\code{data.b[8..11]} & \code{CARD32} &
\textbf{Source Window}: source window ID of the initiator.\\
\code{data.b[12..15]} & \code{CARD32} &
\textbf{Drag Initiator Info Atom}: atom ID of a property the initiator
set up when it started the drag or drop operation.\\
\hline
\end{tabular}%
{\caption{\label{top_level_enter_init}The \code{XmTOP\_LEVEL\_ENTER}
message send by the initiator.}}%
\end{center}\end{table}

\index{drag!initiator info atom}%
The atom ID (in table \ref{top_level_enter_init} it is called the
``Drag Initiator Info Atom'') sent in the \code{XmTOP\_LEVEL\_\-ENTER}
drag message is a selection atom. It must be unique for the duration
of the Drag \& Drop transaction. In addition, the initiator must own
the selection and must be ready to convert data from the early
beginning of the drag operation, since the receiver can ask for a
conversion dynamically during the drag to validate the operation.

When the pointer leaves a top level window, the initiator notifies the
receiver with a \code{XmTOP\_\-LEVEL\_LEAVE} message.

\codeindex{XmTOP\_LEVEL\_LEAVE}%
\begin{table}[!h]\begin{center}\begin{tabular}[h]{|l|l|p{9cm}|}
\hline
Message User Data\hspace{0.2cm} & Size & Description\\
\hline
\code{data.b[0]} & \code{BYTE} &
\textbf{Reason}: \code{XmTOP\_LEVEL\_LEAVE} (\code{0x01})\\
\code{data.b[1]} & \code{BYTE} &
\textbf{Byte Order}: either '\code{B}' (MSB first) or '\code{l}'
(LSB first).\\
\code{data.b[2..3]} & \code{CARD16} &
(\textbf{DnD Flags}: unused)\\
\code{data.b[4..7]} & \code{CARD32} &
\textbf{Timestamp}: set to the timestamp of the corresponding X event
triggering this message.\\
\hline
\end{tabular}%
{\caption{\label{top_level_leave_init}The \code{XmTOP\_LEVEL\_LEAVE}
message send by the initiator.}}%
\end{center}\end{table}

A receiver never replies (echoes) the \code{XmTOP\_LEVEL\_ENTER} and
\code{XmTOP\_LEVEL\_LEAVE} messages.


\subsection{Pointer Motion}

When the pointer moves, the initiator sends \code{XmDRAG\_MOTION}
messages to the receiver (which is the top level window the pointer is
currently in and which is willing to accept drag messages).

\codeindex{XmDRAG\_MOTION}%
\begin{table}[!h]\begin{center}\begin{tabular}[h]{|l|l|p{9cm}|}
\hline
Message User Data\hspace{0.2cm} & Size & Description\\
\hline
\code{data.b[0]} & \code{BYTE} &
\textbf{Reason}: \code{XmDRAG\_MOTION} (\code{0x02})\\
\code{data.b[1]} & \code{BYTE} &
\textbf{Byte Order}: either '\code{B}' (MSB first) or '\code{l}'
(LSB first).\\
\code{data.b[2..3]} & \code{CARD16} &
\textbf{DnD Flags}: \circled{1} + \circled{3}\\
\code{data.b[4..7]} & \code{CARD32} &
\textbf{Timestamp}: set to the timestamp of the corresponding X event
triggering this message.\\
\code{data.b[8..9]} & \code{CARD16} &
\textbf{Root X}: x position of the drag-over icon relative to the
root window.\\
\code{data.b[10..11]} & \code{CARD16} &
\textbf{Root Y}: y position relative to the root window.\\
\hline
\end{tabular}%
{\caption{\label{drag_motion_init}The \code{XmDRAG\_MOTION}
message send by the initiator.}}%
\end{center}\end{table}

Whenever the initiator sends a \code{XmDRAG\_MOTION} message, the receiver
responds with one out of three different messages, depending on whether the
pointer entered or left a valid drop site (\code{XmDROP\_SITE\_ENTER},
\code{XmDROP\_SITE\_LEAVE}), or just moved around (\code{XmDRAG\_MOTION}).

\codeindex{XmDROP\_SITE\_ENTER}%
\begin{table}[!h]\begin{center}\begin{tabular}[h]{|l|l|p{9cm}|}
\hline
Message User Data\hspace{0.2cm} & Size & Description\\
\hline
\code{data.b[0]} & \code{BYTE} &
\textbf{Reason}: \code{XmDROP\_SITE\_ENTER} (\code{0x83})\\
\code{data.b[1]} & \code{BYTE} &
\textbf{Byte Order}: either '\code{B}' (MSB first) or '\code{l}'
(LSB first).\\
\code{data.b[2..3]} & \code{CARD16} &
\textbf{DnD Flags}: \circled{1} + \circled{2} + \circled{3}\\
\code{data.b[4..7]} & \code{CARD32} &
\textbf{Timestamp}: set to the timestamp of the corresponding X event
triggering this message.\\
\code{data.b[8..9]} & \code{CARD16} &
\textbf{Root X}: better x position (hint for the initiator) of the
drag-over icon relative to the root window.\\
\code{data.b[10..11]} & \code{CARD16} &
\textbf{Root Y}: better y position relative to the root window.\\
\hline
\end{tabular}%
{\caption{\label{drop_site_enter_recv}The \code{XmDROP\_SITE\_ENTER}
message replied by the receiver.}}%
\end{center}\end{table}

\codeindex{XmDROP\_SITE\_LEAVE}%
\begin{table}[!h]\begin{center}\begin{tabular}[h]{|l|l|p{9cm}|}
\hline
Message User Data\hspace{0.2cm} & Size & Description\\
\hline
\code{data.b[0]} & \code{BYTE} &
\textbf{Reason}: \code{XmDROP\_SITE\_LEAVE} (\code{0x84})\\
\code{data.b[1]} & \code{BYTE} &
\textbf{Byte Order}: either '\code{B}' (MSB first) or '\code{l}'
(LSB first).\\
\code{data.b[2..3]} & \code{CARD16} &
(\textbf{DnD Flags}: unused)\\
\code{data.b[4..7]} & \code{CARD32} &
\textbf{Timestamp}: set to the timestamp of the corresponding X event
triggering this message.\\
\hline
\end{tabular}%
{\caption{\label{drop_site_leave_recv}The \code{XmDROP\_SITE\_LEAVE}
message replied by the receiver.}}%
\end{center}\end{table}

\codeindex{XmDRAG\_MOTION}%
\begin{table}[!h]\begin{center}\begin{tabular}[h]{|l|l|p{9cm}|}
\hline
Message User Data\hspace{0.2cm} & Size & Description\\
\hline
\code{data.b[0]} & \code{BYTE} &
\textbf{Reason}: \code{XmDRAG\_MOTION} (\code{0x82})\\
\code{data.b[1]} & \code{BYTE} &
\textbf{Byte Order}: either '\code{B}' (MSB first) or '\code{l}'
(LSB first).\\
\code{data.b[2..3]} & \code{CARD16} &
\textbf{DnD Flags}: \circled{1} + \circled{2} + \circled{3}\\
\code{data.b[4..7]} & \code{CARD32} &
\textbf{Timestamp}: set to the timestamp of the corresponding X event
triggering this message.\\
\code{data.b[8..9]} & \code{CARD16} &
\textbf{Root X}: better x position (hint for the initiator) of the
drag-over icon relative to the root window.\\
\code{data.b[10..11]} & \code{CARD16} &
\textbf{Root Y}: better y position relative to the root window.\\
\hline
\end{tabular}%
{\caption{\label{drag_motion_recv}The \code{XmDRAG\_MOTION}
message echoed by the receiver.}}%
\end{center}\end{table}


\subsection{Changing the Operation}

The user is free to change the drag operation (copy, move, link) at
any time during the drag gesture -- for example, if she/he presses or
releases modifier keys. The initiator then sends an
\code{XmOPERATION\_CHANGED} message.

\codeindex{XmOPERATION\_CHANGED}%
\begin{table}[!h]\begin{center}\begin{tabular}[h]{|l|l|p{9cm}|}
\hline
Message User Data\hspace{0.2cm} & Size & Description\\
\hline
\code{data.b[0]} & \code{BYTE} &
\textbf{Reason}: \code{XmOPERATION\_CHANGED} (\code{0x08})\\
\code{data.b[1]} & \code{BYTE} &
\textbf{Byte Order}: either '\code{B}' (MSB first) or '\code{l}'
(LSB first).\\
\code{data.b[2..3]} & \code{CARD16} &
\textbf{DnD Flags}: \circled{1} + \circled{3}\\
\code{data.b[4..7]} & \code{CARD32} &
\textbf{Timestamp}: set to the timestamp of the corresponding X event
triggering this message.\\
\hline
\end{tabular}%
{\caption{\label{op_change_init}The \code{XmOPERATION\_CHANGED}
message send by the initiator.}}%
\end{center}\end{table}

The receiver then echoes the \code{XmOPERATION\_CHANGED} message.

\begin{table}[!h]\begin{center}\begin{tabular}[h]{|l|l|p{9cm}|}
\hline
Message User Data\hspace{0.2cm} & Size & Description\\
\hline
\code{data.b[0]} & \code{BYTE} &
\textbf{Reason}: \code{XmOPERATION\_CHANGED} (\code{0x88})\\
\code{data.b[1]} & \code{BYTE} &
\textbf{Byte Order}: either '\code{B}' (MSB first) or '\code{l}'
(LSB first).\\
\code{data.b[2..3]} & \code{CARD16} &
\textbf{DnD Flags}: \circled{1} + \circled{2} + \circled{3}\\
\code{data.b[4..7]} & \code{CARD32} &
\textbf{Timestamp}: set to the timestamp of the corresponding X event
triggering this message.\\
\hline
\end{tabular}%
{\caption{\label{op_change_recv}The \code{XmOPERATION\_CHANGED}
message echoed by the receiver.}}%
\end{center}\end{table}


\section{The Drop Protocol}

\index{drop!protocol}%
The drop protocol can be used independently of the drag protocol, for
example when a drop site is in the \code{XmDRAG\_DROP\_ONLY} mode.
Fortunately, the whole drop protocol is really lean -- it just
consists of the single message \code{XmDROP\_START} sent by the
initiator, which must be echoed by the receiver.

\codeindex{XmDROP\_START}%
\begin{table}[!h]\begin{center}\begin{tabular}[h]{|l|l|p{9cm}|}
\hline
Message User Data\hspace{0.2cm} & Size & Description\\
\hline
\code{data.b[0]} & \code{BYTE} &
\textbf{Reason}: \code{XmDROP\_START} (\code{0x05})\\
\code{data.b[1]} & \code{BYTE} &
\textbf{Byte Order}: either '\code{B}' (MSB first) or '\code{l}'
(LSB first).\\
\code{data.b[2..3]} & \code{CARD16} &
\textbf{DnD Flags}: \circled{1} + \circled{3}\\
\code{data.b[4..7]} & \code{CARD32} &
\textbf{Timestamp}: set to the timestamp of the corresponding X event
triggering this message.\\
\code{data.b[8..9]} & \code{CARD16} &
\textbf{Root X}: x position relative to the root window.\\
\code{data.b[10..11]} & \code{CARD16} &
\textbf{Root Y}: y position relative to the root window.\\
\code{data.b[12..15]} & \code{CARD32} &
\textbf{Drag Initiator Info Atom}: atom ID of a property the initiator
set up when it started the drag (or drop, if we're in
\code{XmDRAG\_DROP\_ONLY} mode).\\
\code{data.b[16..19]} & \code{CARD32} &
\textbf{Source Window}: source window ID of the initiator.\\
\hline
\end{tabular}%
{\caption{\label{drop_start_init}The \code{XmDROP\_START} message send
by the initiator.}}%
\end{center}\end{table}

The receiver then echoes this \code{XmDROP\_START} message, indicating
whether it is willing to accept the drop and what operation (move, copy
or link) it want to carry out.

\begin{table}[!h]\begin{center}\begin{tabular}[h]{|l|l|p{9cm}|}
\hline
Message User Data\hspace{0.2cm} & Size & Description\\
\hline
\code{data.b[0]} & \code{BYTE} &
\textbf{Reason}: \code{XmDROP\_START} (\code{0x85})\\
\code{data.b[1]} & \code{BYTE} &
\textbf{Byte Order}: either '\code{B}' (MSB first) or '\code{l}'
(LSB first).\\
\code{data.b[2..3]} & \code{CARD16} &
\textbf{DnD Flags}: \circled{1} + \circled{2} + \circled{3} + \circled{4}\\
\code{data.b[4..5]} & \code{CARD16} &
\textbf{Better X}: better x position (hint for the initiator) of the
drag-over icon relative to the root window.\\
\code{data.b[6..7]} & \code{CARD16} &
\textbf{Better Y}: better y position (hint for the initiator) of the
drag-over icon relative to the root window.\\
\hline
\end{tabular}%
{\caption{\label{drop_start_recv}The \code{XmDROP\_START} message echoed
by the receiver.}}%
\end{center}\end{table}

If the receiver did not cancel the drop (which it must indidicate
within the echoed message), then it can proceed to transfer the drop
data using the X selection transfer mechanism. The receiver can
request as many transfers as it wants, using the selected targets. For
each conversion request, the initiator replies using the ICCCM
selection.

\codeindex{XmTRANSFER\_SUCCESS}%
\codeindex{XmTRANSFER\_FAILUR}%
The resources allocated during the drag operation should not be
released until the drop is finished. The receiver indicates this by
requesting a conversion for the targets \code{XmTRANSFER\_SUCCESS} or
\code{XmTRANSFER\_FAILURE}. When the initiator receives such a
conversion request, then it must reply with an empty value.The
receiver as well as the initiator can then release all resources
allocated for the drop operation. In addition, it's the right time to
show the melting or failure/snapback visual effect.


\section{The Preregister Mode}

The full protocol described in this chapter so far is only used when
both the initiator and receiver have agreed to use the dynamic mode.
When using the preregister mode, the initiator grabs the server when
the drag starts, and whenever the pointer enters a new top level
window, it reads all the drop site information it needs for doing its
tracking, visual feedback, etc., from a preregistered database
attached to the \code{\_MOTIF\_DRAG\_RECEIVER\_INFO} property of each
participating client top level window. Obviously, no drag X client
messages are sent, since no one is listening to them (remember, that
the X server is grabbed). The server gets ungrabbed when the user
drops the object, at which point the documented drop protocol comes in
effect (together with the convention for the transfer success or
failure).

For the preregister mode, the \code{\_MOTIF\_DRAG\_RECEIVER\_INFO}
property has also valid information stored in the second half, as
descibed in table \ref{drag_receiver_info}. In addition, the header
(which has a size of 16 bytes) is followed by ``drop site blocks''
that describe the drop sites located within the top level window of
a receiver.

\begin{figure}[!ht]
\hskip\leftmargin\includegraphics[scale=1.09]{DD_DSB}
\caption{\label{drop_site_block}Overall structure of the
\code{\_MOTIF\_DRAG\_RECEIVER\_INFO} property for the preregister mode.}
\end{figure}

For each drop site there is a corresponding drop site block in the
\code{\_MOTIF\_DRAG\_RECEIVER\_INFO} property. Each drop site block
starts with a 8 bytes long ``drop site header'', and is followed by a
``visual info block'' and a series of geometry boxes giving geometry
information about a drop site. This overall structure is shown in
figure \ref{drop_site_block}.

\begin{table}[!ht]\begin{center}\begin{tabular}[h]{|l|l|p{9cm}|}
\hline
Offset & Size & Description\\
\hline
\code{+0x00} & \code{CARD16} &
\textbf{Drop Site Flags}: bitfield containing various flags which
describe the possible operations, the drop type, the animation style,
as well as some other things.\\
\code{+0x02} & \code{CARD16} &
\textbf{Targets Index}: the index of a targets list within the targets
table. The first list within the targets table has an index of \code{0}.
This index advertises which targets the initiator is willing to handle.
This value is used in the same way as the Targets Index of the
\code{\_MOTIF\_DRAG\_INITIATOR\_INFO} property.\\
\code{+0x04} & \code{CARD32} &
\textbf{Number of Geometry Boxes}: the number of geometry boxes following
the visual info block for this drop site block.\\
\hline
\end{tabular}%
\caption{\label{drop_site_block_header}The structure of a drop site
block header}%
\vspace{-0.4cm}\end{center}\end{table}



-- under construction --

% End of DragNDrop.tex
