diff options
Diffstat (limited to 'blt/html/dragdrop.html')
| -rw-r--r-- | blt/html/dragdrop.html | 479 |
1 files changed, 479 insertions, 0 deletions
diff --git a/blt/html/dragdrop.html b/blt/html/dragdrop.html new file mode 100644 index 00000000000..9773d9b685d --- /dev/null +++ b/blt/html/dragdrop.html @@ -0,0 +1,479 @@ + <!-- manual page source format generated by PolyglotMan v3.0.8+XFree86, --> +<!-- available via anonymous ftp from ftp.cs.berkeley.edu:/ucb/people/phelps/tcltk/rman.tar.Z --> + +<HTML> +<HEAD> +<TITLE>drag&drop(n) manual page</TITLE> +</HEAD> +<BODY BGCOLOR="#efefef" TEXT="black" LINK="blue" VLINK="#551A8B" ALINK="red"> +<A HREF="#toc">Table of Contents</A><P> + +<H2><A NAME="sect0" HREF="#toc0">Name</A></H2> +drag&drop - facilities for handling drag&drop data +transfers +<H2><A NAME="sect1" HREF="#toc1">Synopsis</A></H2> +<B>drag&drop source </B><BR> +<B>drag&drop source <I>window </I></B>?<I>options</I>? <BR> +<B>drag&drop source <I>window <B>handler </B></I></B>?<I>dataType</I>? ?<I>command arg arg...</I>? <P> +<B>drag&drop target +</B><BR> +<B>drag&drop target <I>window <B>handler </B></I></B>?<I>dataType command arg arg...</I>? <P> +<B>drag&drop target +<I>window <B>handle <I>dataType</I></B></I></B> ?<I>value</I>? <P> +<B>drag&drop token <I>window </I></B><P> +<B>drag&drop drag <I>window +x y </I></B><BR> +<B>drag&drop drop <I>window x y </I></B><BR> +<B>drag&drop active </B><BR> +<B>drag&drop errors </B>?<I>proc</I>? <BR> +<B>drag&drop location </B>?<I>x y</I>? <P> + +<H2><A NAME="sect2" HREF="#toc2">Description</A></H2> +<P> +The <B>drag&drop</B> command provides access +to a set of facilities for managing drag-and-drop data transfers. Any of +the usual Tk widgets can be registered to participate in the drag-and-drop +process. Widgets registered as a drag&drop <I>source</I> can export data to other +widgets registered as a drag&drop <I>target</I>. Note that a particular widget +can be registered as a source, as a target, or as both. <P> +The drag-and-drop +process begins when the user clicks and holds a mouse button in a source +window; a token window appears with an icon or message to represent the +data being transferred. As the user moves the mouse pointer, the token +window follows along, acting as a movable packet of data. Whenever the mouse +pointer falls on a valid target window, the border of the token window +is changed to a raised (active) state. When the mouse button is released +over the target window, a Tcl routine is invoked to send the data to the +desired application, and the target window is asked to "handle" the data. + If this communication process fails, a rejection symbol (a circle with +a line through it) is displayed on the token window to indicate failure. +<P> +The details of the communication process are fully configurable by the +application developer. In the simplest case, the value that is sent to +the target window is a simple string. The target window is simply asked +to "handle" that string value. In general, the source window can have a +special "handler" procedure to transfer a particular data type by issuing +a series of "send" commands. After this, the target window is again asked +to "handle" the result. <P> +Both sources and targets can have a list of "handlers" +for different data types. As a token window is dragged from its source +to various targets, each target is checked to see if it recognizes a handler +offered by the source. If it does, it is treated as a valid target. Otherwise, +it is ignored. This scheme allows the same source to interact with many +different kinds of targets. For example, a source for RGB color samples +might have "color" and "string" handlers. This would allow it to communicate +with "color" targets (sending RGB data) as well as entry widgets (sending +strings of the form "#rrggbb"). <P> +This introduction was presented as a brief +overview of the communication process; further details are presented below: + +<DL> + +<DT><B>drag&drop source</B> </DT> +<DD>Returns a list of path names for widgets registered as +drag&drop sources. Returns an empty string if no widgets have been registered. +</DD> + +<DT><B>drag&drop source <I>window </I></B>?<I>options</I>? </DT> +<DD>Registers a new drag&drop source window +with the given options, or modifies the options for an existing window: +<blockquote></DD> +</DL> +<P> +<BR> +<PRE>Name:<tt> </tt> <tt> </tt> <B>buttonBinding</B> +Class:<tt> </tt> <tt> </tt> <B>ButtonBinding</B> +Switch:<tt> </tt> <tt> </tt> <B>-button</B> <I>n</I> +</PRE> +<DL> + +<DT>Specifies the mouse button (integer 1-5) that will invoke the drag&drop </DT> +<DD>operation +on the source window. This causes the following bindings to be added to +the widget: <P> +<BR> +<PRE><I>bind <I>win</I></I> <ButtonPress-<I>n</I>> {drag&drop drag %W %X %Y} +<I>bind <I>win</I></I> <B<I>n</I>-Motion> {drag&drop drag %W %X %Y} +<I>bind <I>win</I></I> <ButtonRelease-<I>n</I>> {drag&drop drop %W %X %Y} +</PRE><P> +The default value is button 3. If the value "0" is specified, then no bindings +are added; this enables the user to establish bindings manually. <P> +<BR> +<PRE>Name:<tt> </tt> <tt> </tt> <B>packageCommand</B> +Class:<tt> </tt> <tt> </tt> <B>Command</B> +Switch:<tt> </tt> <tt> </tt> <B>-packagecmd <I>command</I></B> +</PRE> +<DL> + +<DT>Specifies a Tcl command used to establish the appearance of the token </DT> +<DD>window +at the start of each drag&drop operation. This command is automatically +invoked by the <B>drag&drop drag</B> command whenever the token window is about +to be mapped for a drag operation. It should update the appearance of the +token window to represent the data that is being moved. </DD> +</DL> +<P> +The following substitutions +are made in the <I>command</I> string before it is executed: <blockquote> +<DL> + +<DT><B>%t</B> </DT> +<DD>Replaced with +the window path name for the token which represents the data being dragged. +</DD> + +<DT><B>%W</B> </DT> +<DD>Replaced with the window path name for the drag&drop source. </DD> +</DL> +</blockquote> +<P> +The return +value from the package command represents the data being transferred. If +the package command returns an empty string, the drag operation is quietly +aborted. This can be used to disallow drag&drop operations from certain +parts of a widget, if the drag position is inappropriate. <P> +For example, the +following package routine will select an item from a listbox and configure +the token window to display the selected string. It uses the <B>drag&drop location</B> +command to determine the entry in the listbox that the user has selected +and it returns this as the data value: <P> +<BR> +<PRE><I>proc package_list_item {lbox token} {</I> + set xy [drag&drop location] + set y [expr [lindex $xy 1]-[winfo rooty $lbox]] + set str [$lbox get [$lbox nearest $y]] + $token.value configure -text $str + return $str +} +</PRE><P> +The return value is available later when the source and target communicate. + If the source has a command associated with its data handler, then this +value is substituted in place of "%v" in the source handler. Otherwise, +it is substituted in place of "%v" in the target handler. <P> +<BR> +<PRE>Name:<tt> </tt> <tt> </tt> <B>rejectBackground</B> +Class:<tt> </tt> <tt> </tt> <B>Background</B> +Switch:<tt> </tt> <tt> </tt> <B>-rejectbg <I>color</I></B> +</PRE> +<DL> + +<DT>Specifies the color used to draw the background of the rejection symbol +</DT> +<DD>on the token window. The rejection symbol (a circle with a line through +it--the international "no") appears whenever communication fails. </DD> +</DL> +<P> +<BR> +<PRE>Name:<tt> </tt> <tt> </tt> <B>rejectForeground</B> +Class:<tt> </tt> <tt> </tt> <B>Foreground</B> +Switch:<tt> </tt> <tt> </tt> <B>-rejectfg <I>color</I></B> +</PRE> +<DL> + +<DT>Specifies the color used to draw the foreground of the rejection symbol +</DT> +<DD>on the token window. </DD> +</DL> +<P> +<BR> +<PRE>Name:<tt> </tt> <tt> </tt> <B>rejectStipple</B> +Class:<tt> </tt> <tt> </tt> <B>Stipple</B> +Switch:<tt> </tt> <tt> </tt> <B>-rejectstipple <I>pattern</I></B> +</PRE> +<DL> + +<DT>Specifies a stipple pattern used to draw the foreground of the rejection +</DT> +<DD>symbol on the token window. Any of the forms acceptable to Tk_GetBitmap +can be used. </DD> +</DL> +<P> +<BR> +<PRE>Name:<tt> </tt> <tt> </tt> <B>selfTarget</B> +Class:<tt> </tt> <tt> </tt> <B>SelfTarget</B> +Switch:<tt> </tt> <tt> </tt> <B>-selftarget <I>boolean</I></B> +</PRE> +<DL> + +<DT>If the <I>boolean</I> value is true, and if a source widget is also </DT> +<DD>registered +as a compatible target, then the source will be able to transmit to itself +during drag&drop operations. This is primarily useful for complex sources +such as a canvas widget, where items may be moved from place to place within +the same widget. By default, this option is disabled. </DD> +</DL> +<P> +<BR> +<PRE>Name:<tt> </tt> <tt> </tt> <B>send</B> +Class:<tt> </tt> <tt> </tt> <B>Send</B> +Switch:<tt> </tt> <tt> </tt> <B>-send <I>list</I></B> +</PRE> +<DL> + +<DT>Specifies a <I>list</I> of <I>dataTypes</I> enabled for communication. Only </DT> +<DD><I>dataTypes</I> +defined by commands of the form "<B>drag&drop source <I>window <B>handler </B></I></B>?<I>dataType</I> +?<I>command arg arg...</I>?" are allowed. This list also determines the priority +of the various <I>dataTypes</I>. When a token window is over a potential drag&drop +target, this list is searched from start to finish for a <I>dataType</I> that +is also recognized by the target. The first matching <I>dataType</I> found determines +the value that will be sent if the token is dropped. If no matching <I>dataType</I> +is found, then the target is incompatible, and is ignored. By default, +this option has the value "all", indicating that all <I>dataTypes</I> should be +considered in the order that they were defined for the source. </DD> +</DL> +<P> +Note that +this option makes it easy to control a drag&drop source. Setting the value +to an empty string disables the source; setting the value back to "all" +restores communication. <P> +<BR> +<PRE>Name:<tt> </tt> <tt> </tt> <B>siteCommand</B> +Class:<tt> </tt> <tt> </tt> <B>Command</B> +Switch:<tt> </tt> <tt> </tt> <B>-sitecmd <I>command</I></B> +</PRE> +<DL> + +<DT>Specifies a Tcl command used to update the appearance of the token window. +</DT> +<DD>If specified, this command is automatically invoked by the <B>drag&drop drag</B> +command whenever the token window is over a compatible drag&drop target. +</DD> +</DL> +<P> +The following substitutions are made in the <I>command</I> string before it is +executed: <blockquote> +<DL> + +<DT><B>%s</B> </DT> +<DD>Replaced with "1" if the token window is over a compatible +target, and "0" otherwise. </DD> + +<DT><B>%t</B> </DT> +<DD>Replaced with the window path name for the +token which represents the data being dragged. </DD> +</DL> +</blockquote> +<P> +Regardless of this command, +border of the token window will become raised whenever the token is over +a valid target. This command can be used to display other visual cues. <P> +<BR> +<PRE>Name:<tt> </tt> <tt> </tt> <B>tokenAnchor</B> +Class:<tt> </tt> <tt> </tt> <B>Anchor</B> +Switch:<tt> </tt> <tt> </tt> <B>-tokenanchor <I>anchor</I></B> +</PRE> +<DL> + +<DT>Specifies how the token window is positioned relative to the mouse </DT> +<DD>pointer +coordinates passed to the <B>drag&drop drag</B> command. Must be one of the values +n, s, e, w, center, nw, ne, sw or se. For example, "nw" means to position +the token such that its upper-left corner is at the mouse pointer. The default +value is "center". </DD> +</DL> +<P> +<BR> +<PRE>Name:<tt> </tt> <tt> </tt> <B>tokenBackground</B> +Class:<tt> </tt> <tt> </tt> <B>Background</B> +Switch:<tt> </tt> <tt> </tt> <B>-tokenbg <I>color</I></B> +</PRE> +<DL> + +<DT>Specifies the color used to draw the background of the token window. </DT> +<DD></DD> +</DL> +<P> +<BR> +<PRE>Name:<tt> </tt> <tt> </tt> <B>tokenBorderWidth</B> +Class:<tt> </tt> <tt> </tt> <B>BorderWidth</B> +Switch:<tt> </tt> <tt> </tt> <B>-tokenborderwidth <I>size</I></B> +</PRE> +<DL> + +<DT>Specifies the width in pixels of the border around the token window. </DT> +<DD>This +border becomes raised to indicate when the token is over a compatible drag&drop +target site. The value may have any of the forms acceptable to Tk_GetPixels. + The default value is "3". </DD> +</DL> +<P> +<BR> +<PRE>Name:<tt> </tt> <tt> </tt> <B>tokenCursor</B> +Class:<tt> </tt> <tt> </tt> <B>Cursor</B> +Switch:<tt> </tt> <tt> </tt> <B>-tokencursor <I>cursor</I></B> +</PRE> +<DL> + +<DT>Specifies the cursor used when a token window is active. The value </DT> +<DD>may +have any of the forms acceptable to Tk_GetCursor. The default value is +"center_ptr". </DD> +</DL> +</blockquote> + +<DL> + +<DT><B>drag&drop source <I>window <B>handler </B></I></B>?<I>dataType</I>? ?<I>command arg arg...</I>? +</DT> +<DD>With no extra arguments, this command returns a list of all <I>dataType</I> names +that have been registered for the source <I>window</I>. If only the <I>dataType</I> is +specified, then the <I>dataType</I> is created if necessary, and the command associated +with the <I>dataType</I> is returned. Otherwise, it concatenates the <I>command</I> and +any extra <I>arg</I> strings, and registers a new <I>dataType</I> with this command. </DD> +</DL> +<P> +The +following substitutions are made in the <I>command</I> string before it is executed: +<blockquote> +<DL> + +<DT><B>%i</B> </DT> +<DD>Replaced with the name of the interpreter for the target application. +</DD> + +<DT><B>%v</B> </DT> +<DD>Replaced with the value returned from the "-packagecmd" command. </DD> + +<DT><B>%w</B> </DT> +<DD>Replaced +with the window path name for the target window. </DD> +</DL> +</blockquote> +<P> +A typical source handler +contains one or more "send" commands which transfer data to the remote +application. The target window is then asked to handle the new data. Whatever +value is returned by the source <I>command</I> handler is automatically substituted +into the "%v" fields of the target handler. <P> +This separation between the +transfer and the handling of the data is important. It allows the same +source handler to transfer data for many different targets, and it allows +each of the targets to handle the incoming data differently. If an error +is encountered during the communication process, the rejection symbol is +posted on the token window to indicate failure. </blockquote> +<P> + +<DL> + +<DT><B>drag&drop target</B> </DT> +<DD>Returns +a list of path names for widgets registered as drag&drop targets. Returns +an empty string if no widgets have been registered. </DD> + +<DT><B>drag&drop target <I>window +<B>handler </B></I></B>?<I>dataType command arg arg...</I>? </DT> +<DD>Registers a new drag&drop target window +with a given handler, or modifies the handlers for an existing window. +If no <I>dataType</I> is specified, this command returns the current list of recognized +<I>dataType</I> strings. Each <I>dataType</I> is a symbolic name representing a form +of data, and the corresponding <I>command</I> is a Tcl command that specifies +how the target will make use of the data. This command is invoked indirectly +after a source has transferred data to a target application. </DD> +</DL> +<P> +The following +substitutions are made in the <I>command</I> string before it is executed: <blockquote> +<DL> + +<DT><B>%v</B> +</DT> +<DD>In the simplest case, the source window does not have a handler command +for the selected <I>dataType</I>, and this field is replaced with the result from +the "-packagecmd" command. When the source does have a handler command, +the result from the "-packagecmd" command is substituted into its "%v" field, +and the result from this command is substituted into this field in the +target command. </DD> + +<DT><B>%W</B> </DT> +<DD>Replaced with the window path name for the target window. +</DD> +</DL> +</blockquote> + +<DL> + +<DT><B>drag&drop target <I>window </I></B>handle <I>dataType</I> ?<I>value</I>? </DT> +<DD>Searches for the given <I>dataType</I> +name among the handlers registered for the target <I>window</I>, and invokes the +appropriate <I>command</I>. If a <I>value</I> is specified, it is substituted into any +"%v" fields in the handler command associated with the <I>dataType</I>. If the +<I>dataType</I> name is not recognized, this command returns an error. This command +is invoked automatically by the drag&drop facility when data is being transferred +from a source to a target. </DD> + +<DT><B>drag&drop token <I>window</I></B> </DT> +<DD>Returns the token window +associated with a drag&drop source <I>window</I>. The token window is used to represent +data as it is being dragged from the source to a target. When a source +is first established, its token window must be filled with widgets to display +the source data. For example, <P> +<BR> +<PRE><I>drag&drop source .foo</I> +set win [drag&drop token .foo] +label $win.label -text "Data" +pack $win.label +</PRE><P> + +<DL> + +<DT><B>drag&drop drag <I>window x y</I></B> </DT> +<DD>Marks the start of (or movement during) a drag&drop +operation. If the token window is unmapped when this command is invoked, +then the <B>-packagecmd</B> for the source <I>window</I> is executed. If this command +is successful and returns a non-null string, the token window is mapped. + On subsequent calls, the token window is moved to the new <I>x y</I> location. + Unless the "<B>-button 0</B>" option is specified for the source, this command +is automatically bound to <ButtonPress-<I>n</I>> and <B<I>n</I>-Motion> events for "<B>-button +<I>n</I></B>" of the source widget. </DD> + +<DT><B>drag&drop drop <I>window x y</I></B> </DT> +<DD>Marks the end of a drag&drop +operation. If the mouse pointer is over a compatible target window, then +the appropriate send handler for the first compatible <I>dataType</I> is invoked +to handle the data transfer. If the data transfer is successful, then the +token window is unmapped; otherwise, a rejection symbol is drawn on the +token window, and the window is unmapped after a small delay. Unless the +"<B>-button 0</B>" option is specified for the source, this command is automatically +bound to the <ButtonRelease-<I>n</I>> event for "<B>-button <I>n</I></B>" of the source widget. </DD> + +<DT><B>drag&drop +active</B> </DT> +<DD>Returns "1" if a drag&drop operation is in progress, and "0" otherwise. +A drag&drop operation officially starts after the package command has been +executed successfully, and ends after the send handler has been executed +(successfully or otherwise). </DD> + +<DT><B>drag&drop errors </B>?<I>proc</I>? </DT> +<DD>Specifies a Tcl <I>proc</I> +used to handle errors encountered during drag&drop operations. If a <I>proc</I> +is not specified, this command returns the current error handler. By default, +all errors are sent to the usual <B>tkerror</B> command, and therefore appear +in a dialog box to the user. This behavior is quite useful when debugging +communication protocols, but may not be desirable in a finished application. + Errors can be suppressed entirely (leaving the rejection symbol as the +only error indicator) by specifying a null string in place of the <I>proc</I> +name. </DD> + +<DT><B>drag&drop location </B>?<I>x y</I>? </DT> +<DD>Used to set or query the pointer location +during a drag&drop operation. The <I>x y</I> arguments specify the current location; +if these arguments are missing, then the last reported (x,y) location is +returned as a list with two elements. This command is issued automatically +within the <B>drag&drop drag</B> and <B>drag&drop drop</B> commands, to keep track of pointer +movement. <P> + </DD> +</DL> + +<H2><A NAME="sect3" HREF="#toc3">Keywords</A></H2> +drag&drop, send, bind, widget <P> + +<HR><P> +<A NAME="toc"><B>Table of Contents</B></A><P> +<UL> +<LI><A NAME="toc0" HREF="#sect0">Name</A></LI> +<LI><A NAME="toc1" HREF="#sect1">Synopsis</A></LI> +<LI><A NAME="toc2" HREF="#sect2">Description</A></LI> +<LI><A NAME="toc3" HREF="#sect3">Keywords</A></LI> +</UL> +</BODY></HTML> |