DtDndProtocol(4)
DtDndProtocol(4) DEVICES AND NETWORK INTERFACES DtDndProtocol(4)
NAME
DtDndProtocol - drag and drop matching and transfer proto-
cols
DESCRIPTION
The drag and drop protocols provide policy for matching and
data transfer between the drag initiator and the drop
receiver of file names, selected text spans and
application-defined structured data formats.
The drag and drop protocols use the standard X11 selection
targets, where available, with the addition of several new
selection targets where required.
These protocols provide for the transfer of the following
types of data:
o Selected Text
o File Names
o Buffers
PROTOCOL OVERVIEW
Each protocol consists of the following:
Drag and Drop API Protocol
Each protocol described corresponds to a specific DtDndPro-
tocol enumeration value.
Export/Import Targets
The Motif drag and drop API provides support for matching of
the data transfer protocol between the drag initiator and
the various drop receivers. This allows the user to deter-
mine readily which drop sites will accept the dragged data.
The drag initiator sets the XmNexportTargets resource of the
XmDragContext to the list of target atoms that describe the
data being dragged. The drop receiver sets the XmNimport-
Targets resource of the XmDropSite to the list of target
atoms that describe the data that it will accept. The Motif
drag and drop subsystem allows drops when the XmNexportTar-
gets and XmNimportTargets have at least one target in com-
mon.
Data Transfer Protocol
Once the drag initiator has dropped on the drop receiver,
the transfer of data is begun. The transfer is accomplished
using X selections and is controlled by the drop receiver.
The drop receiver starts all transfers by converting the
selection into the ICCCM TARGETS target to get the set of
Unix System LaboratoLast change: 17 June 1994 1
DtDndProtocol(4) DEVICES AND NETWORK INTERFACES DtDndProtocol(4)
available selection targets. (See the for a description of
converting targets.) It then chooses the appropriate selec-
tions from that set and requests that the drag initiator
convert each requested selection. Each protocol has a set
of selection targets that are used to transfer all the
necessary data. These target conversions are usually ini-
tiated by calling XmDropTransferStart().
Move Completion
When the operation of the drop is XmDROP_MOVE, the drop
receiver must complete the move using an appropriate method.
For most data transfers, this is accomplished by converting
the selection into the ICCCM DELETE target to tell the drag
initiator that it may delete the data. For most file name
transfers, this is accomplished via the file system.
TEXT TRANSFER PROTOCOL
The text transfer protocol is used to exchange text selec-
tions.
Drag and Drop API
This is the protocol used when a DtDndProtocol of
DtDND_TEXT_TRANSFER is specified.
Export/Import Targets
The export or import targets are any of the following; the
target describing the character encoding of the text selec-
tion, COMPOUND_TEXT, STRING or TEXT.
Data Transfer Protocol
The transfer of text selections follows the protocols
described in the ICCCM manual. If the character encoding of
the drag initiator and drop receiver are the same, that tar-
get should be converted to get the text selection. If the
character encoding are different, the drop receiver should
attempt to convert the standard text targets in the follow-
ing order: COMPOUND_TEXT, STRING or TEXT.
Move Completion
The move is completed by converting the selection into the
ICCCM DELETE target.
FILE NAME TRANSFER PROTOCOL
The transfer protocol is used to exchange file names.
Drag and Drop API
This is the protocol used when a DtDndProtocol of
DtDND_FILENAME_TRANSFER is specified.
Export/Import Targets
The export or import targets are FILE_NAME and, optionally,
_DT_NETFILE if capable of providing the file name in network
Unix System LaboratoLast change: 17 June 1994 2
DtDndProtocol(4) DEVICES AND NETWORK INTERFACES DtDndProtocol(4)
canonical form using tt_file_netfile(3) and
tt_netfile_file(3).
Data Transfer Protocol
If the ICCCM HOST_NAME target is in the list of target
atoms, it is converted. If the returned host name is dif-
ferent than the host name for the drop receiver and the
_DT_NETFILE target is in the list of target atoms, it is
converted. The drag initiator uses tt_file_netfile(3) to
encode the file names and the drop receiver uses
tt_netfile_file(3) to decode the file names.
If the hosts are the same for both the drag initiator and
the drop receiver or either the HOST_NAME or the _DT_NETFILE
targets are not in the list of target atoms from the drag
initiator, the drop receiver converts the ICCCM FILE_NAME
target. No encoding of the file names occurs in this case.
Move Completion
Moves of file names can be accomplished atomically using
standard file system operations. Drop receivers are
encouraged to use the file system. The drop receiver may
alternatively choose to use the ICCCM DELETE target to com-
plete the XmDROP_MOVE and the drag initiator must be ready
to comply.
BUFFER TRANSFER PROTOCOL
The transfer protocol is used to exchange memory buffers.
Drag and Drop API
This is the protocol used when a DtDndProtocol of
DtDND_BUFFER_TRANSFER is specified.
Export/Import Targets
The export and import targets are _DT_BUFFER_DATA,
_DT_BUFFER_LENGTHS and, optionally, _DT_BUFFER_NAMES.
Data Transfer Protocol
The _DT_BUFFER_DATA and _DT_BUFFER_LENGTHS targets are con-
verted to transfer the buffer data.
The data of the buffers is encoded into the _DT_BUFFER_DATA
target as an array of bytes. The lengths in bytes of each
buffer are encoded into _DT_BUFFER_LENGTHS. Each length is
used to index into the _DT_BUFFER_DATA array.
If the _DT_BUFFER_NAMES target is available, it is converted
to transfer the names of the buffers.
Move Completion
The move is completed by converting the selection into the
ICCCM DELETE target.
Unix System LaboratoLast change: 17 June 1994 3
DtDndProtocol(4) DEVICES AND NETWORK INTERFACES DtDndProtocol(4)
SELECTION TARGETS
The following table describes the selection targets used in
the drag and drop data matching and transfer protocols.
Atom Type Description
__________________________________________________________________
TARGETS ATOM A list of valid target
atoms. See ICCCM section
2.6.2.
DELETE NULL Used to delete the dropped
data. If the drop receiver
wishes to perform a move
operation on the data,
after copying the data it
should request conversion
of the DELETE target. See
ICCCM section 2.6.3.1.
COMPOUND_TEXT COMPOUND_TEXT The text selection in com-
pound text format. See
ICCCM section 2.7.1.
STRING STRING The text selection in ISO
Latin-1 format. See ICCCM
section 2.7.1.
TEXT TEXT The text selection in the
format preferred by the
selection holder. See
ICCCM section 2.7.1.
HOST_NAME TEXT The name of the machine
running the client as seen
from the machine running
the server. See ICCCM sec-
tion 2.6.2.
FILE_NAME TEXT The full path name of the
files. See ICCCM section
2.6.2.
_DT_NETFILE TEXT The full pathname of the
files, each encoded using
tt_file_netfile(3) and
decoded using
tt_netfile_file(3).
_DT_BUFFER_DATA _DT_BUFFER_DATA The buffer data in an array
of bytes.
_DT_BUFFER_LENGTHS INTEGER The lengths in bytes of
each buffer in the
_DT_BUFFER_NAMES array.
_DT_BUFFER_NAMES STRING The names of each buffer,
suitable for use as a file
name.
__________________________________________________________________
SEE ALSO
DtDnd(5), DtDndDragStart(3), DtDndVaDragStart(3), DtDndVa-
DropRegister(3), DtDndDropUnregister(3),
Unix System LaboratoLast change: 17 June 1994 4
DtDndProtocol(4) DEVICES AND NETWORK INTERFACES DtDndProtocol(4)
DtDropTransferStart(3), XmDragContext(3), XmDragStart(3),
XmDropRegister(3), XmDropSite(3), tt_file_netfile(3),
tt_netfile_file(3), X11/R5 Inter-Client Communications Con-
ventions Manual (ICCCM)
Unix System LaboratoLast change: 17 June 1994 5
Man(1) output converted with
man2html