CDE/cde/doc/C/guides/man/man4/DtDndPro.sgm

<!-- $XConsortium: DtDndPro.sgm /main/10 1996/08/31 14:54:19 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->
<refentry id="CDEMX.MAN89.rsml.1">
<refmeta><refentrytitle>DtDndProtocol</refentrytitle><manvolnum>special file
</manvolnum></refmeta>
<refnamediv><refname><structname role="typedef">DtDndProtocol</structname></refname>
<refpurpose>drag and drop matching and transfer protocols</refpurpose></refnamediv>
<!-- CDE Common Source Format, Version 1.0.0-->
<!-- (c) Copyright 1993, 1994, 1995 Hewlett-Packard Company-->
<!-- (c) Copyright 1993, 1994, 1995 International Business Machines Corp.-->
<!-- (c) Copyright 1993, 1994, 1995 Sun Microsystems, Inc.-->
<!-- (c) Copyright 1993, 1994, 1995 Novell, Inc.-->
<refsect1>
<title>DESCRIPTION</title>
<para>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.</para>
<para>The drag and drop protocols use the standard X11 selection targets,
where available, with the addition of several new selection targets where
required.</para>
<para>These protocols provide for the transfer of the following types of data:
</para>
<itemizedlist>
<!-- merged from xo+cde-->
<listitem><para>Selected Text</para>
</listitem><listitem><para>File Names</para>
</listitem><listitem><para>Buffers</para>
</listitem></itemizedlist>
</refsect1>
<refsect1>
<title>PROTOCOL OVERVIEW</title>
<para>Each protocol consists of the following:</para>
<refsect2>
<title>Drag and Drop API Protocol</title>
<para>Each protocol described corresponds to a specific <structname role="typedef">DtDndProtocol</structname> enumeration value.</para>
</refsect2>
<refsect2>
<title>Export/Import Targets</title>
<para>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.</para>
<para>The drag initiator sets the <systemitem class="Resource">XmNexportTargets</systemitem> resource of the <classname>XmDragContext</classname> to the
list of target atoms that describe the data being dragged. The drop receiver
sets the <systemitem class="Resource">XmNimportTargets</systemitem> resource
of the <Symbol>XmDropSite</Symbol> to the list of target atoms that describe
the data that it will accept. The Motif drag and drop subsystem allows drops
when the <systemitem class="Resource">XmNexportTargets</systemitem> and <systemitem class="Resource">XmNimportTargets</systemitem> have at least one target in
common.</para>
</refsect2>
<refsect2>
<title>Data Transfer Protocol</title>
<para>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.</para>
<para>The drop receiver starts all transfers by converting the selection into
the ICCCM <systemitem class="Constant">TARGETS</systemitem> 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 <function>XmDropTransferStart</function>.</para>
</refsect2>
<refsect2>
<title>Move Completion</title>
<para>When the operation of the drop is <systemitem class="Constant">XmDROP_MOVE</systemitem>, 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 <systemitem class="Constant">DELETE</systemitem> target to
tell the drag initiator that it may delete the data. For most file name transfers,
this is accomplished via the file system.</para>
</refsect2>
</refsect1>
<refsect1>
<title>TEXT TRANSFER PROTOCOL</title>
<para>The text transfer protocol is used to exchange text selections.</para>
<refsect2>
<title>Drag and Drop API</title>
<para>This is the protocol used when a <structname role="typedef">DtDndProtocol</structname> of <systemitem class="Constant">DtDND_TEXT_TRANSFER</systemitem>
is specified.</para>
</refsect2>
<refsect2>
<title>Export/Import Targets</title>
<para>The export or import targets are any of the following; the target describing
the character encoding of the text selection, <systemitem class="Constant">COMPOUND_TEXT</systemitem>, <systemitem class="Constant">STRING</systemitem>
or <systemitem class="Constant">TEXT</systemitem>.</para>
</refsect2>
<refsect2>
<title>Data Transfer Protocol</title>
<para>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: <systemitem class="Constant">COMPOUND_TEXT</systemitem>, <systemitem class="Constant">STRING</systemitem>
or <systemitem class="Constant">TEXT</systemitem>.</para>
</refsect2>
<refsect2>
<title>Move Completion</title>
<para>The move is completed by converting the selection into the ICCCM <systemitem class="Constant">DELETE</systemitem> target.</para>
</refsect2>
</refsect1>
<refsect1>
<title>FILE NAME TRANSFER PROTOCOL</title>
<para>The transfer protocol is used to exchange file names.</para>
<refsect2>
<title>Drag and Drop API</title>
<para>This is the protocol used when a <structname role="typedef">DtDndProtocol</structname> of <systemitem class="Constant">DtDND_FILENAME_TRANSFER</systemitem>
is specified.</para>
</refsect2>
<refsect2>
<title>Export/Import Targets</title>
<para>The export or import targets are <systemitem class="Constant">FILE_NAME</systemitem> and, optionally, <systemitem class="Constant">_DT_NETFILE</systemitem>
if capable of providing the file name in network canonical form using &cdeman.tt.file.netfile; and &cdeman.tt.netfile.file;.</para>
</refsect2>
<refsect2>
<title>Data Transfer Protocol</title>
<para>If the ICCCM <systemitem class="Constant">HOST_NAME</systemitem> 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 <systemitem class="Constant">_DT_NETFILE</systemitem> 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.</para>
<para>If the hosts are the same for both the drag initiator and the drop receiver
or either the <systemitem class="Constant">HOST_NAME</systemitem> or the <systemitem class="Constant">_DT_NETFILE</systemitem> targets are not in the list of target
atoms from the drag initiator, the drop receiver converts the ICCCM <systemitem class="Constant">FILE_NAME</systemitem> target. No encoding of the file names
occurs in this case.</para>
</refsect2>
<refsect2>
<title>Move Completion</title>
<para>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 <systemitem class="Constant">DELETE</systemitem> target to complete the <systemitem class="Constant">XmDROP_MOVE</systemitem> and the drag initiator must be ready to comply.</para>
</refsect2>
</refsect1>
<refsect1>
<title>BUFFER TRANSFER PROTOCOL</title>
<para>The transfer protocol is used to exchange memory buffers.</para>
<refsect2>
<title>Drag and Drop API</title>
<para>This is the protocol used when a <structname role="typedef">DtDndProtocol</structname> of <systemitem class="Constant">DtDND_BUFFER_TRANSFER</systemitem>
is specified.</para>
</refsect2>
<refsect2>
<title>Export/Import Targets</title>
<para>The export and import targets are <systemitem class="Constant">_DT_BUFFER_DATA</systemitem>, <systemitem class="Constant">_DT_BUFFER_LENGTHS</systemitem>
and, optionally, <systemitem class="Constant">_DT_BUFFER_NAMES</systemitem>.
</para>
</refsect2>
<refsect2>
<title>Data Transfer Protocol</title>
<para>The <systemitem class="Constant">_DT_BUFFER_DATA</systemitem> and <systemitem class="Constant">_DT_BUFFER_LENGTHS</systemitem> targets are converted to
transfer the buffer data.</para>
<para>The data of the buffers is encoded into the <systemitem class="Constant">_DT_BUFFER_DATA</systemitem> target as an array of bytes. The lengths in bytes
of each buffer are encoded into <systemitem class="Constant">_DT_BUFFER_LENGTHS</systemitem>. Each length is used to index into the <systemitem class="Constant">_DT_BUFFER_DATA</systemitem> array.</para>
<para>If the <systemitem class="Constant">_DT_BUFFER_NAMES</systemitem> target
is available, it is converted to transfer the names of the buffers.</para>
</refsect2>
<refsect2>
<title>Move Completion</title>
<para>The move is completed by converting the selection into the ICCCM <systemitem class="Constant">DELETE</systemitem> target.</para>
</refsect2>
</refsect1>
<refsect1>
<title>SELECTION TARGETS</title>
<para>The following table describes the selection targets used in the drag
and drop data matching and transfer protocols.</para>
<informaltable remap="center" orient="port">
<tgroup cols="3" colsep="0" rowsep="0">
<?PubTbl tgroup dispwid="6.08in">
<colspec align="left" colwidth="2.27in">
<colspec align="left" colwidth="2.02in">
<colspec align="left" colwidth="2.87in">
<tbody>
<row>
<entry align="left" valign="top"><structname role="typedef">Atom</structname></entry>
<entry align="left" valign="top"><literal>Type</literal></entry>
<entry align="left" valign="top"><literal>Description</literal></entry></row>
<row>
<entry align="left" valign="top">TARGETS</entry>
<entry align="left" valign="top">ATOM</entry>
<entry align="left" valign="top">A list of valid target atoms. See ICCCM section
2.6.2.</entry></row>
<row>
<entry align="left" valign="top">DELETE</entry>
<entry align="left" valign="top">NULL</entry>
<entry align="left" valign="top">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 <systemitem class="Constant">DELETE</systemitem> target. See ICCCM section 2.6.3.1.</entry></row>
<row>
<entry align="left" valign="top">COMPOUND_TEXT</entry>
<entry align="left" valign="top">COMPOUND_TEXT</entry>
<entry align="left" valign="top">The text selection in compound text format.
See ICCCM section 2.7.1.</entry></row>
<row>
<entry align="left" valign="top">STRING</entry>
<entry align="left" valign="top">STRING</entry>
<entry align="left" valign="top">The text selection in ISO Latin-1 format.
See ICCCM section 2.7.1.</entry></row>
<row>
<entry align="left" valign="top">TEXT</entry>
<entry align="left" valign="top">TEXT</entry>
<entry align="left" valign="top">The text selection in the format preferred
by the selection holder. See ICCCM section 2.7.1.</entry></row>
<row>
<entry align="left" valign="top">HOST_NAME</entry>
<entry align="left" valign="top">TEXT</entry>
<entry align="left" valign="top">The name of the machine running the client
as seen from the machine running the server. See ICCCM section 2.6.2.</entry>
</row>
<row>
<entry align="left" valign="top">FILE_NAME</entry>
<entry align="left" valign="top">TEXT</entry>
<entry align="left" valign="top">The full path name of the files. See ICCCM
section 2.6.2.</entry></row>
<row>
<entry align="left" valign="top">_DT_NETFILE</entry>
<entry align="left" valign="top">TEXT</entry>
<entry align="left" valign="top">The full pathname of the files, each encoded
using &cdeman.tt.file.netfile; and decoded using &cdeman.tt.netfile.file;.</entry></row>
<row>
<entry align="left" valign="top">_DT_BUFFER_DATA</entry>
<entry align="left" valign="top">_DT_BUFFER_DATA</entry>
<entry align="left" valign="top">The buffer data in an array of bytes.</entry>
</row>
<row>
<entry align="left" valign="top">_DT_BUFFER_LENGTHS</entry>
<entry align="left" valign="top">INTEGER</entry>
<entry align="left" valign="top">The lengths in bytes of each buffer in the <systemitem class="Constant">_DT_BUFFER_NAMES</systemitem> array.</entry></row>
<row>
<entry align="left" valign="top">_DT_BUFFER_NAMES</entry>
<entry align="left" valign="top">STRING</entry>
<entry align="left" valign="top">The names of each buffer, suitable for use
as a file name.</entry></row></tbody></tgroup><?Pub Caret></informaltable>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>&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;, <literal>X11/R5 Inter-Client
Communications Conventions Manual (ICCCM)</literal></para>
</refsect1>
</refentry>
<!--fickle 1.12 mancsf-to-docbook 1.2 08/07/95 01:31:55-->
<?Pub *0000042458>