<HTML>
<HEAD><TITLE>DropSite</TITLE></HEAD>
<BODY BGCOLOR=white>
<DL><DT><I><A HREF="#descr">NAME</A></I></DT>
<DD><B>DropSite</B>
- Commands set for Drop facilities
</DD></DL>
<DL>
<DT><I><A HREF="#wc">COMMAND</A></I></DT>
<DD>DropSite::<A HREF="#include"><B>include</B></A>
<I>class</I>
<I>types</I>
</DD>
<DD>DropSite::<A HREF="#register"><B>register</B></A>
<I>path</I>
?<I>option value...</I>?
</DD>
<DD>DropSite::<A HREF="#setcursor"><B>setcursor</B></A>
<I>cursor</I>
</DD>
<DD>DropSite::<A HREF="#setdrop"><B>setdrop</B></A>
<I>path</I>
<I>subpath</I>
<I>dropover</I>
<I>drop</I>
?<I>force</I>?
</DD>
<DD>DropSite::<A HREF="#setoperation"><B>setoperation</B></A>
<I>op</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 drop site.
A drop site is composed of the type of object that can be dropped and associated operation,
a command called when drop occurs, and a command when an object is dragged over the widget.
A drop site must have at least one type of acceptable object and a drop command.
</P>
<HR WIDTH="50%"><BR>
<B><A NAME="wc">COMMAND</A></B><BR>
<DL><DT><A NAME="include">DropSite::<B>include</B></A>
<I>class</I>
<I>types</I>
</DT><DD>
This command provides a simple way to include options relatives to a drop site into
BWidget resources definition.
It includes the options needed for <B>register</B>, <I>-dropovercmd</I> and <I>-dropcmd</I>,
initialized to empty string, and <I>-droptypes</I>, initialized to <I>types</I>,
and one new option:
<TABLE BORDER=0 CELLSPACING=1>
<TR><TD><I>-dropenabled</I><TD>Specifies wether or not drop is active (initialized to 0)
</TABLE>
</DD></DL>
<DL><DT><A NAME="register">DropSite::<B>register</B></A>
<I>path</I>
?<I>option value...</I>?
</DT><DD>
This command is used to declare <I>path</I> as a drop site. Options are:
<P>
<DL><DT><A NAME="DropSite-dropcmd"><B>-dropcmd</B></A></DT>
<DD>
This command is called when user release the drag icon over a valid drop target widget.
It takes the same arguments as <B>-dragovercmd</B> command. Its return values is passed
as a result to the <B>-dragendcmd</B> command of the drag source widget.
</DD>
</DL>
<DL><DT><A NAME="DropSite-dropovercmd"><B>-dropovercmd</B></A></DT>
<DD>
This command can be used to provide a dynamic drag while <I>drag-over</I> events.
While a drag occurs, events <Enter>, <Motion> and <Leave> are catched.
Arguments passed to the command are:
<UL>
<LI>pathname of the drop target (the widget itself),
<LI>pathname of the drag source,
<LI>event over the drop target: <I>enter</I>, <I>motion</I> or <I>leave</I>,
<LI>root x-coordinate of the pointer,
<LI>root y-coordinate of the pointer,
<LI>operation,
<LI>type of the dragged data,
<LI>dragged data.
</UL>
Command must the new status of the drag:
<UL>
<LI>0 if widget refuse this drag. Command will not be recalled on motion/leave event.
<LI>1 if widget accept this drag. Command will not be recalled on motion/leave event.
<LI>2 if widget refuse this drag. Command will be recalled on each motion event to reevaluate.
<LI>3 if widget accept this drag. Command will be recalled on each motion event to reevaluate.
</UL>
Here is a list of events and associated actions on a DropSite widget. This example
assumes that dragged data type is valid for the drop target.
<B>status</B> is the status of the drag on a DropSite. Its value is:
<BR><BR>
<TABLE BORDER CELLSPACING=1 CELLPADDING=4>
<TR><TD WIDTH="18%" VALIGN="TOP">
<P ALIGN="CENTER"><FONT SIZE=2>Event</FONT></TD>
<TD WIDTH="10%" VALIGN="TOP">
<FONT SIZE=2><P ALIGN="CENTER">Old status</FONT></TD>
<TD WIDTH="48%" VALIGN="TOP">
<FONT SIZE=2><P ALIGN="CENTER">Action</FONT></TD>
<TD WIDTH="24%" VALIGN="TOP">
<FONT SIZE=2><P ALIGN="CENTER">New status</FONT></TD>
</TR>
<TR><TD WIDTH="18%" VALIGN="TOP" ROWSPAN=2>
<FONT SIZE=2><P><Enter></FONT></TD>
<TD WIDTH="10%" VALIGN="TOP" ROWSPAN=2>
<FONT SIZE=2><P>-</FONT></TD>
<TD WIDTH="48%" VALIGN="TOP">
<FONT SIZE=2><P>if DropSite has <B>dropovercmd</B>, call it with <I>enter</I></FONT></TD>
<TD WIDTH="24%" VALIGN="TOP">
<FONT SIZE=2><P>result of <B>dropovercmd</B></FONT></TD>
</TR>
<TR><TD WIDTH="48%" VALIGN="TOP">
<FONT SIZE=2><P>else</FONT></TD>
<TD WIDTH="24%" VALIGN="TOP">
<FONT SIZE=2><P>1</FONT></TD>
</TR>
<TR><TD WIDTH="18%" VALIGN="TOP" ROWSPAN=2>
<FONT SIZE=2><P><Motion></FONT></TD>
<TD WIDTH="10%" VALIGN="TOP">
<FONT SIZE=2><P>0 or 1</FONT></TD>
<TD WIDTH="48%" VALIGN="TOP"> </TD>
<TD WIDTH="24%" VALIGN="TOP">
<FONT SIZE=2><P>unchanged</FONT></TD>
</TR>
<TR><TD WIDTH="10%" VALIGN="TOP">
<FONT SIZE=2><P>2 or 3</FONT></TD>
<TD WIDTH="48%" VALIGN="TOP">
<FONT SIZE=2><P>call <B>dropovercmd</B> with <I>motion</I></FONT></TD>
<TD WIDTH="24%" VALIGN="TOP">
<FONT SIZE=2><P>result of <B>dropovercmd</B></FONT></TD>
</TR>
<TR><TD WIDTH="18%" VALIGN="TOP" ROWSPAN=2>
<FONT SIZE=2><P><Leave></P>
</FONT><P> </TD>
<TD WIDTH="10%" VALIGN="TOP">
<FONT SIZE=2><P>0 or 1</FONT></TD>
<TD WIDTH="48%" VALIGN="TOP"> </TD>
<TD WIDTH="24%" VALIGN="TOP">
<FONT SIZE=2><P>-</FONT></TD>
</TR>
<TR><TD WIDTH="10%" VALIGN="TOP">
<FONT SIZE=2><P>2 or 3</FONT></TD>
<TD WIDTH="48%" VALIGN="TOP">
<FONT SIZE=2><P>call <B>dropovercmd</B> with <I>leave</I></FONT></TD>
<TD WIDTH="24%" VALIGN="TOP">
<FONT SIZE=2><P>-</FONT></TD>
</TR>
<TR><TD WIDTH="18%" VALIGN="TOP" ROWSPAN=4>
<FONT SIZE=2><P><Drop></FONT></TD>
<TD WIDTH="10%" VALIGN="TOP">
<FONT SIZE=2><P>0</FONT></TD>
<TD WIDTH="48%" VALIGN="TOP">
<FONT SIZE=2><P>call <B>dragendcmd</B> of drag source</FONT></TD>
<TD WIDTH="24%" VALIGN="TOP" ROWSPAN=4>
<FONT SIZE=2><P>-</FONT></TD>
</TR>
<TR><TD WIDTH="10%" VALIGN="TOP">
<FONT SIZE=2><P>1</FONT></TD>
<TD WIDTH="48%" VALIGN="TOP">
<FONT SIZE=2><P>call <B>dropcmd</B> and call <B>dragendcmd</B> of drag source</FONT></TD>
</TR>
<TR><TD WIDTH="10%" VALIGN="TOP">
<FONT SIZE=2><P>2</FONT></TD>
<TD WIDTH="48%" VALIGN="TOP">
<FONT SIZE=2><P>call <B>dropovercmd</B> with <I>leave</I> and call <B>dragendcmd</B> of drag source</FONT></TD>
</TR>
<TR><TD WIDTH="10%" VALIGN="TOP">
<FONT SIZE=2><P>3</FONT></TD>
<TD WIDTH="48%" VALIGN="TOP">
<FONT SIZE=2><P>call <B>dropcmd</B> and call <B>dragendcmd</B> of drag source</FONT></TD>
</TR>
</TABLE>
<BR>
</DD>
</DL>
<DL><DT><A NAME="DropSite-droptypes"><B>-droptypes</B></A></DT>
<DD>
Specifies a list {<I>type</I> <I>oplist</I> ?<I>type</I> <I>oplist</I>? ...} of acceptable
types and associated operations for the drop target.
For each type, <I>oplist</I> is a list
{<I>descops</I> <I>mod</I> ?<I>descops</I> <I>mod</I>? ...} describing operations and
modifier keys for these operations.
<I>descops</I> describe an operation. It can be a predefined operations (<B>copy</B>,
<B>move</B> or <B>link</B>) or a new user defined operation, of the form {<I>subop</I>
<B>baseop</I> ?<I>bitmap</I>?}.
<I>subop</I> is the name given to the sub operation, <I>baseop</I> is the name of the
base operation (<B>copy</B>, <B>move</B> or <B>link</B>) and <I>bitmap</I> is a bitmap
to display for the operation.
<BR>If <I>bitmap</I> is empty, the default bitmap of the base operation is used for the
sub operation.
<BR><I>subop</I> can be a base operation, in order to change the bitmap of a base operation.
In this case, <I>baseop</I> must be empty or equal to <I>subop</I>.
<BR><I>mod</I> is the modifer key for the operation. It can be:
<UL>
<LI><B>none</B> to specify that no modifier key is pressed. This modifier can only be used
with a sub operation named <B>default</B> (and vice versa), which has the behaviour of not
display any bitmap operation. For all type, if the modifier <B>none</B> is not given, it is
automatically associated to the <B>default</B> sub operation of a <B>copy</B> base operation.
<LI><B>program</B> to specifies a sub operation accessible only by <B>DropSite::setoperation</B>.
<LI>A list combining <B>shift</B>, <B>control</B> and <B>alt</B>, which means their
corresponding key.
</UL>
</DD>
</DL>
</DD></DL>
<DL><DT><A NAME="setcursor">DropSite::<B>setcursor</B></A>
<I>cursor</I>
</DT><DD>
This command can be used within the script <B>dragovercmd</B>. It is usefull to provide
visual effect about the state of the drag.
</DD></DL>
<DL><DT><A NAME="setdrop">DropSite::<B>setdrop</B></A>
<I>path</I>
<I>subpath</I>
<I>dropover</I>
<I>drop</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>dropover</I> is a command for <I>drag-over</I> event,
<LI><I>drop</I> is a command for <I>drop</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>setdrop</B> verifies the modification flag of options <B>dropenabled</B> and
<B>droptypes</B> and calls <B>register</B> if needed according to the options values and
<I>dropover</I> and <I>drop</I> arguments. <B>dropovercmd</B> and <B>dropcmd</B> are not
taken from options of widget because they are considered as user command, called by
BWidget implementation of <I>drag-over</I> and <I>drop</I> events.
</DD></DL>
<DL><DT><A NAME="setoperation">DropSite::<B>setoperation</B></A>
<I>op</I>
</DT><DD>
Description text
</DD></DL>
</BODY></HTML>