<HTML>
<HEAD><TITLE>DragSite</TITLE></HEAD>
<BODY BGCOLOR=white>
<DL><DT><I><A HREF="#descr">NAME</A></I></DT>
<DD><B>DragSite</B>
- Commands set for Drag facilities
</DD></DL>
<DL>
<DT><I><A HREF="#wc">COMMAND</A></I></DT>
<DD>DragSite::<A HREF="#include"><B>include</B></A>
<I>class</I>
<I>type</I>
<I>event</I>
</DD>
<DD>DragSite::<A HREF="#register"><B>register</B></A>
<I>path</I>
?<I>option value...</I>?
</DD>
<DD>DragSite::<A HREF="#setdrag"><B>setdrag</B></A>
<I>path</I>
<I>subpath</I>
<I>initcmd</I>
<I>endcmd</I>
?<I>force</I>?
</DD>
</DL>
<BR><HR WIDTH="100%"><BR>
<B><A NAME="descr"></A>DESCRIPTION</B><BR>
<P>
Commands of this namespace enable user to define a BWidget or a Tk widget as a drag site.
</P>
<HR WIDTH="50%"><BR>
<B><A NAME="wc">COMMAND</A></B><BR>
<DL><DT><A NAME="include">DragSite::<B>include</B></A>
<I>class</I>
<I>type</I>
<I>event</I>
</DT><DD>
This command provides a simple way to include options relatives to a drag site into
BWidget resources definition.
It includes the options needed for <B>register</B>: <I>-dragevent</I>, initialized to
<I>event</I>, <I>-draginitcmd</I> and <I>-dragendcmd</I>, initialized to empty string,
and two new options:
<TABLE BORDER=0 CELLSPACING=1>
<TR><TD><I>-dragenabled</I><TD>Specifies wether or not drag is active (initialized to 0)
<TR><TD><I>-dragtype</I><TD>Default or alternate dragged data type (initialized to <I>type</I>)
</TABLE>
</DD></DL>
<DL><DT><A NAME="register">DragSite::<B>register</B></A>
<I>path</I>
?<I>option value...</I>?
</DT><DD>
This command is used to declare <I>path</I> as a drag site. Options are:
<P>
<DL><DT><A NAME="DragSite-dragendcmd"><B>-dragendcmd</B></A></DT>
<DD>
Command called when drag terminates (ie when user release drag icon).
This command is called with the following arguments:
<UL>
<LI>the pathname of the drag source (the widget itself),
<LI>the pathname of the drop target,
<LI>the operation,
<LI>the type of the dragged data,
<LI>the dragged data,
<LI>result of the drop (result of the call to <B>-dropcmd</B> of the target),
</UL>
If the drop does not occurs, the target and the operation are empty string and the result
is 0.
</DD>
</DL>
<DL><DT><A NAME="DragSite-dragevent"><B>-dragevent</B></A></DT>
<DD>
Specifies the number of the mouse button associated to the drag.
Must be <B>1</B>, <B>2</B> or <B>3</B>.
</DD>
</DL>
<DL><DT><A NAME="DragSite-draginitcmd"><B>-draginitcmd</B></A></DT>
<DD>
Command called when drag initiates. When the event of option <B>dragevent</B> occurs on
<I>path</I>, this command is called with the following arguments:
<UL>
<LI>pathname of the drag source (<I>path</I>),
<LI>root x-coordinate of pointer,
<LI>root y-coordinate of pointer,
<LI>a toplevel created to represent dragged data. When returning, if it
has no children, a bitmap is automatically displayed.
</UL>
If the command returns an empty string, then the drag will be
suppressed. Otherwise the command must return a list containing three
elements:
<UL>
<LI>the type of the data,
<LI>the list of acceptable basic operations (<B>copy</B>, <B>move</B> and <B>link</B>)
<LI>and the data.
</UL>
Note that even if <B>copy</B> does not appear in the list of basic
operation, it is considered as an acceptable operation, since
<B>copy</B> semantic does not modify the drag source.
</DD>
</DL>
</DD></DL>
<DL><DT><A NAME="setdrag">DragSite::<B>setdrag</B></A>
<I>path</I>
<I>subpath</I>
<I>initcmd</I>
<I>endcmd</I>
?<I>force</I>?
</DT><DD>
This command provides a simple way to call <B>register</B> during a BWidget creation or
configuration.
<UL>
<LI><I>path</I> is the pathname of the BWidget,
<LI><I>subpath</I> is the pathname of the tk widget where drag event occurs,
<LI><I>initcmd</I> BWidget command for <I>drag-init</I> event,
<LI><I>endcmd</I> BWidget command for <I>drag-end</I> event,
<LI><I>force</I> specifies wether or not to call <B>register</B> whenever no option value has
changed (0 by default - for BWidget configuration, use 1 for BWidget creation).
</UL>
<B>setdrag</B> verifies the modification flag of options <B>dragenabled</B> and
<B>dragevent</B> and calls <B>register</B> if needed according to the options values and
<I>initcmd</I> and <I>endcmd</I> arguments. <B>draginitcmd</B> and <B>dragendcmd</B> are not
taken from options of widget because they are considered as user command, called by
BWidget implementation of <I>drag-init</I> and <I>drag-end</I> events.
</DD></DL>
</BODY></HTML>
