From: adrian@ora.com (adrian)
Newsgroups: fj.mail-lists.x-window
Subject: Re: Drag-and-Drop in Motif
Date: 13 Nov 92 01:27:33 GMT
Distribution: fj
Organization: Workstation Div., Supermicro Systems Group, Sony Corporation

Date: Thu, 12 Nov 92 09:17:50-060
Message-Id: <9211121517.AA00554@spike.ora.com>


> What specific drag-and-drop functionality is provided in 1.2?  We are running
> 1.1.x on Suns, and are contemplating bidding on a contract which would
> neccessitate d-n-d, but we have no docs to know what we can promise.  Is 
> 1.2 covered in Volume 6, or should we order a new programmer's manual from
> OSF? ... duh. 

The 1.2 edition of Vol 6 is not done yet.

Here is the conceptual discussion from Vol4M (1.2 edition) about drag 
and drop.  There are no examples of drag and drop in vol4M.
(This is copyrighted material.)

.Ah "Drag and Drop"
Motif 1.2 introduces a new user interface for transferring data within
an application or between applications,
called \fIdrag and drop\fR.  From the user's perspective,
data can be moved or copied by dragging an iconic representation of the
data.\(dg
.FS
\(dgDragging is the act of pressing a mouse button with the pointer
over the object, moving the mouse with the button held down, and
releasing the object in a new location by releasing the mouse button.
.FE
.LP
Mouse button 2 is reserved for drag-and-drop.  When the user
begins a drag with button two over a "drag source", the
pointer is replaced with a special drag icon.  This icon
indicates the type of data being dragged (text, pixmap,
etc.), the drag operation (copy, move, or "link"), and
whether the pointer is over a valid "drop site", an invalid
drop site or no drop site.  The drag icon may change as it
enters and leaves drop sites, and drop sites themselves may
change their visuals when the
drop icon is within them.  These changing graphics in drag
icon and drop site are referred to as "drag over" and "drag
under" visuals, respectively.
.LP
The type of data being dragged and the default operation
(copy, move, or link) depends on the drag source.  If the
drag source supports multiple operations, the user can
select an operation other than the default with the Shift
and Ctrl modifiers.
.LP
The user can cancel a drag by pressing the Escape key.  The
user can request help on a drop site before dropping by pressing
the F1 key.
.LP
Text, List, Label and Button widgets support drag and drop as
drag sources, which means that text can be dragged from them.  Text
and TextField widget support drag and drop as drop sites, which means
that text can be dragged to them.
The Label class also supports dragging of \f(CWPixmap\fP data.
If you use existing widgets, therefore, there is no extra programming
necessary to provide drag and drop.
Custom drag and drop support can be added to any widget.  Custom drag
icons and drop site visuals can also be implemented.
The details of implementing drag and drop in an application are
beyond the scope of this book.  See the \fIOSF/Motif Programming
Manual\fR for more information.
.\"
.\"
.Bh "Drag Protocol"
In order to implement drag-over effects, the originator of
the drag must know when it has entered a valid drop site.
In order to implement customized drag-under effects, the
process controlling the drop site must know when there is a
drag icon inside of it.  It is not possible to gracefully
satisfy all of these requirements with X.  To work around
this, Motif drag-and-drop supports two different drag
protocols with different tradeoffs.  The protocol used
depends on the preference of the user and on
which protocols are supported by the initiating client
and the drop site.
.LP
\fBPreregister Protocol.  \fP In the "preregister" protocol,
the client that initiated the drag is in complete control of
the drag, and the clients controlling drop sites are never
notified when the drag icon enters those drop sites.
Therefore this protocol does not allow a drop site to
implement custom drag-under visuals.  In this protocol, the
client that initiated the drag grabs the X server and
implements the drag icon with a shaped window it moves
around the screen.  When the icon enters a top-level window,
the initiating client reads a server property to determine
the (preregistered) list of valid drop sites within that
window.  The initiating client can implement drag-over
visuals when the icon enters a drop site, and can also
implement simple drag-under visuals (such as highlighting
the drop-site border) for the drop site.
.LP
\fBDynamic Protocol.  \fP In the "dynamic" drag protocol, the
initiating client communicates (dynamically) with other
clients to determine the list of valid drop sites and to
notify then when the drag icon enters one of these drop
sites.  This notification allows these clients to implement
custom drag-under visuals (which can include animation). The
initiating client does not perform a server grab in this
protocol, and the drag icon is implemented by specifying it
as the hardware pointer.  Many X servers restrict the
maximum size of the pointer cursor, so this protocol may not
work with large drag icons.
.\"
.\"
.Bh "Drop Protocol"
The drop protocol is primarily concerned with transferring the
data from initiator to receiver, and is much simpler than
the drag protocol.  It is based directly on the Xt Selection
mechanism used to implement standard Xt cut-and-paste.
.LP
The drag initiator registers a "convert proc" (of type
\f(CWXtConvertSelectionIncrProc\fP) when it starts the drag
with \f(CWXmDragStart()\fP.  In Xt selection terms, starting
a drag is analogous to calling \f(CWXtOwnSelection()\fP.
.LP
The receiving process registers each drop site along with a
callback to invoke when something is dropped on that site.
This callback registers a "transfer proc" (of type
\f(CWXtSelectionCallbackProc\fP) as well as a list of target
types that it would like the dragged data to be converted to
and calls \f(CWXmDropTransferStart()\fP.  In terms of the Xt
selection mechanism, \f(CWXmDropTransferStart()\fP is
analogous to \f(CWXtGetSelectionValues()\fP.
\f(CWXmDropTransferStart()\fP uses the underlying Xt
Selection mechanism to transfer the data.  The drag source's
convert proc is called once for each target type, and the
drop site's transfer proc is called once with the converted
data for each target.
.LP
The drop protocol is also responsible for providing help.
Each drop site should recognize when the user has requested
help and post a dialog box explaining the consequences of
dropping on that site.  This dialog box must give the user
the explicit options to continue with or cancel the drop.
.\"
.\"
.Bh "Operations"
Motif allows three drag-and-drop operations: copy, move, and
link.  The precise semantics of each operation will of
course depend on the dragged data and the drop site.  After
a copy operation there should be two copies of the dragged
data or object.
.LP
After a move, there should only be one copy.  Note that the
drop site is responsible for telling the drag source to
delete its copy of moved data.  It does this by sending a
request to convert the data to the special target "DELETE".
(This target is standardized by the ICCCM, described in Chapter 11.)
.LP
The semantics of the "link" operation are vague: "At the end
of the operation, there is only one copy of the data,
belonging to the initiator, but both applications have
access to it".  In the absence of shared memory, it is not
clear what this means, but the link operation should
presumably be used to establish any sort of "live link",
or to enable dynamic data sharing between applications.
.\"
.\"
.Bh "Application Programming Interface"
Initiating a drag or registering a drop site or initiating a
transfer once a drop has occurred each require a number of
parameters (many of which are optional) to be specified.  To
avoid having functions with large number of arguments, Motif
uses Xt Objects and allows these parameters to be specified
with standard Xt arglists.  Starting a drag with
\f(CWXmDragStart()\fP creates an object of type
\f(CWXmDragContext\fP.  Registering a drop site with
\f(CWXmDropSiteRegister()\fP creates an object of type
\f(CWXmDropSite\fP.  Initiating a data transfer with
\f(CWXmDropTransferStart()\fP creates an object of type
\f(CWXmDropTransfer\fP.  These objects have resources that control
many of the visual effects of drag-and-drop, and also have
callback list resources that provide hooks at many points
during both the drag and the drop.
.\"
.\"
.Bh "Summary: Drag and Drop in Applications"
Programming with Motif drag-and-drop can become almost
arbitrarily complex (the code for a single example in OSF's book is
65 pages).  There are three general approaches to incorporating
drag-and-drop into applications:
.LP
\fBDo Nothing.  \fP
Many of the standard Motif primitive widgets support
drag-and-drop.  Even if you do nothing, users will be able
to perform basic drag-and-drop of text.
.LP
\fBAdd New Drag Sources and Drop Types.  \fP
You can support additional drag sources by adding a
translation/action pair that calls \f(CWXmDragStart()\fP and
registers a convert proc to handle requests for the data
once it is dropped.  For example you might want to allow the
user to drag the value from a Slider widget, or if you
implemented a custom spreadsheet widget, you might want to
allow the user to drag a column of numbers.  To add a new
drop site, call \f(CWXmDropSiteRegister()\fP and specify a
callback to be called when a drop occurs.  This callback
should register a transfer proc to handle the dropped data
and then call \f(CWXmDropTransferStart()\fP to fetch that
data.
.LP
\fBCustomize Drag-and-Drop.  \fP There are many ways that
you can customize drag-and-drop, most of which can be
controlled through resources and callbacks. You can change
the components of the default drag icon, or specify custom
drag icon components for a particular drag source.  You can
also change the way that the components of the drag icon are
combined or "blended."  Using the \f(CWXtNdragCallback\fP
callback list of the \f(CWXmDragContext\fP 
and \f(CWXmDropSite\fP objects,
you can implements custom drag-over and drag-under visuals.
If a drag site implements custom visuals, you can set
resources to express a preference for the dynamic drag
protocol which allows these visuals.  You can specify a
non-rectangular outline for a drag site, and specify the
sort of highlighting should be done on that border when a
drag icon enters it.  You can specifying a stacking order
for overlapping drop sites.  You can only have one drop site
for a widget, but with some extra coding work, you can
.ne 2
implement a single drop site that appears and functions as a
number of separate sites within the widget.
.\"


*************************************************************
Adrian Nye (314) 531-1231    Editor, The X Resource
O'Reilly & Associates, Inc., Publishers of Nutshell Handbooks
4466 West Pine Blvd.  20-G   St. Louis MO 63108
Internet:   adrian@ora.com    	UUCP:   uunet!ora!adrian      
*************************************************************