DtDndProtocol

special file

DtDndProtocol

drag and drop matching and transfer protocols

## 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:

- Selected Text

- File Names

- Buffers

## PROTOCOL OVERVIEW

Each protocol consists of the following:

### Drag and Drop API Protocol

Each protocol described corresponds to a specific DtDndProtocol 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 determine 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 `XmNimportTargets` 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 `XmNexportTargets` and `XmNimportTargets` have at least one target in common.

### 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 available selection targets. (See the &str-Zi; for a description of converting targets.) It then chooses the appropriate selections 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 initiated 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 selections.

### 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 selection, `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 target 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 following 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 canonical form using &cdeman.tt.file.netfile; and &cdeman.tt.netfile.file;.

### 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 different 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 &cdeman.tt.file.netfile; to encode the file names and the drop receiver uses &cdeman.tt.netfile.file; 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 complete 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 converted 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.

## 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 compound 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 section 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 &cdeman.tt.file.netfile; and decoded using &cdeman.tt.netfile.file;.
_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

&cdeman.Dt.Dnd.h;, &cdeman.DtDndDragStart;, &cdeman.DtDndDragStart;, &cdeman.DtDndDropRegister;, &cdeman.DtDndDropUnregister;, &cdeman.XmDropTransferStart;, &cdeman.XmDragContext;, &cdeman.XmDragStart;, &cdeman.XmDropSiteRegister;, &cdeman.XmDropSite;, &cdeman.tt.file.netfile;, &cdeman.tt.netfile.file;, `X11/R5 Inter-Client Communications Conventions Manual (ICCCM)`