2 '\" Copyright 1991-1997 by Bell Labs Innovations for Lucent Technologies.
4 '\" Permission to use, copy, modify, and distribute this software and its
5 '\" documentation for any purpose and without fee is hereby granted, provided
6 '\" that the above copyright notice appear in all copies and that both that the
7 '\" copyright notice and warranty disclaimer appear in supporting documentation,
8 '\" and that the names of Lucent Technologies any of their entities not be used
9 '\" in advertising or publicity pertaining to distribution of the software
10 '\" without specific, written prior permission.
12 '\" Lucent Technologies disclaims all warranties with regard to this software,
13 '\" including all implied warranties of merchantability and fitness. In no event
14 '\" shall Lucent Technologies be liable for any special, indirect or
15 '\" consequential damages or any damages whatsoever resulting from loss of use,
16 '\" data or profits, whether in an action of contract, negligence or other
17 '\" tortuous action, arising out of or in connection with the use or performance
21 '\" The definitions below are for supplemental macros used in Tcl/Tk
24 '\" .HS name section [date [version]]
25 '\" Replacement for .TH in other man pages. See below for valid
28 '\" .AP type name in/out [indent]
29 '\" Start paragraph describing an argument to a library procedure.
30 '\" type is type of argument (int, etc.), in/out is either "in", "out",
31 '\" or "in/out" to describe whether procedure reads or modifies arg,
32 '\" and indent is equivalent to second arg of .IP (shouldn't ever be
33 '\" needed; use .AS below instead)
36 '\" Give maximum sizes of arguments for setting tab stops. Type and
37 '\" name are examples of largest possible arguments that will be passed
38 '\" to .AP later. If args are omitted, default tab stops are used.
41 '\" Start box enclosure. From here until next .BE, everything will be
42 '\" enclosed in one large box.
45 '\" End of box enclosure.
48 '\" Begin vertical sidebar, for use in marking newly-changed parts
52 '\" End of vertical sidebar.
55 '\" Begin an indented unfilled display.
58 '\" End of indented unfilled display.
60 '\" # Heading for Tcl/Tk man pages
62 .if '\\$2'cmds' .TH \\$1 1 \\$3 \\$4
63 .if '\\$2'lib' .TH \\$1 3 \\$3 \\$4
64 .if '\\$2'tcl' .TH \\$1 3 \\$3 \\$4
65 .if '\\$2'tk' .TH \\$1 3 \\$3 \\$4
66 .if '\\$2'BLT' .TH \\$1 "BLT 2.4" \\$3 \\$4
71 '\" # Start an argument description
75 . ie !"\\$2"" .TP \\n()Cu
80 \&\\$1 \\fI\\$2\\fP (\\$3)
93 '\" # define tabbing values for .AP
96 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
99 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
100 .nr )C \\n()Bu+\\w'(in/out)'u+2n
102 '\" # BS - start boxed text
103 '\" # ^y = starting y location
111 .if n \l'\\n(.lu\(ul'
114 '\" # BE - end boxed text (draw box now)
119 .ie n \l'\\n(^lu\(ul'
121 '\" Draw four-sided box normally, but don't draw top of
122 '\" box if the box started on an earlier page.
124 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
127 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
134 '\" # VS - start vertical sidebar
135 '\" # ^Y = starting y location
136 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
139 .ie n 'mc \s12\(br\s0
142 '\" # VE - end of vertical sidebar
150 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
157 '\" # Special macro to handle page bottom: finish off current
158 '\" # box/sidebar if in box/sidebar mode, then invoked standard
159 '\" # page bottom macro.
166 '\" Draw three-sided box if this is the box's first page,
167 '\" draw two sides but no top otherwise.
168 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
169 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
172 .nr ^x \\n(^tu+1v-\\n(^Yu
173 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
186 '\" # DS - begin display
193 '\" # DE - end display
202 '\" Note: do not modify the .SH NAME line immediately below!
204 drag&drop \- facilities for handling drag&drop data transfers
208 \fBdrag&drop source \fIwindow \fR?\fIoptions\fR?
210 \fBdrag&drop source \fIwindow \fBhandler \fR?\fIdataType\fR? ?\fIcommand arg arg...\fR?
214 \fBdrag&drop target \fIwindow \fBhandler \fR?\fIdataType command arg arg...\fR?
216 \fBdrag&drop target \fIwindow \fBhandle \fIdataType\fR ?\fIvalue\fR?
218 \fBdrag&drop token \fIwindow
220 \fBdrag&drop drag \fIwindow x y
222 \fBdrag&drop drop \fIwindow x y
226 \fBdrag&drop errors \fR?\fIproc\fR?
228 \fBdrag&drop location \fR?\fIx y\fR?
233 The \fBdrag&drop\fR command provides access to a set of facilities
234 for managing drag-and-drop data transfers. Any of the usual Tk widgets can
235 be registered to participate in the drag-and-drop process. Widgets
236 registered as a drag&drop \fIsource\fP can export data to other widgets
237 registered as a drag&drop \fItarget\fP. Note that a particular widget
238 can be registered as a source, as a target, or as both.
240 The drag-and-drop process begins when the user clicks and holds a mouse
241 button in a source window; a token window appears with an icon or message
242 to represent the data being transferred. As the user moves the mouse pointer,
243 the token window follows along, acting as a movable packet of data.
244 Whenever the mouse pointer falls on a valid target window, the border of the
245 token window is changed to a raised (active) state. When the mouse button is
246 released over the target window, a Tcl routine is invoked to send the data
247 to the desired application, and the target window is asked to "handle"
248 the data. If this communication process fails, a rejection symbol (a
249 circle with a line through it) is displayed on the token window to
252 The details of the communication process are fully configurable by the
253 application developer. In the simplest case, the value that is sent
254 to the target window is a simple string. The target window is simply
255 asked to "handle" that string value. In general, the source window
256 can have a special "handler" procedure to transfer a particular data
257 type by issuing a series of "send" commands. After this, the target
258 window is again asked to "handle" the result.
260 Both sources and targets can have a list of "handlers" for different
261 data types. As a token window is dragged from its source to various
262 targets, each target is checked to see if it recognizes a handler
263 offered by the source. If it does, it is treated as a valid target.
264 Otherwise, it is ignored. This scheme allows the same source to
265 interact with many different kinds of targets. For example, a source
266 for RGB color samples might have "color" and "string" handlers. This
267 would allow it to communicate with "color" targets (sending RGB data)
268 as well as entry widgets (sending strings of the form "#rrggbb").
270 This introduction was presented as a brief overview of the communication
271 process; further details are presented below:
273 \fBdrag&drop source\fR
274 Returns a list of path names for widgets registered as drag&drop
275 sources. Returns an empty string if no widgets have been registered.
277 \fBdrag&drop source \fIwindow \fR?\fIoptions\fR?
278 Registers a new drag&drop source window with the given options, or
279 modifies the options for an existing window:
283 Name: \fBbuttonBinding\fR
284 Class: \fBButtonBinding\fR
285 Switch: \fB\-button\fR \fIn\fR
288 Specifies the mouse button (integer 1-5) that will invoke the drag&drop
289 operation on the source window. This causes the following bindings to
290 be added to the widget:
294 \f(CWbind \fIwin\fP <ButtonPress-\fIn\fP> {drag&drop drag %W %X %Y}
295 \f(CWbind \fIwin\fP <B\fIn\fP-Motion> {drag&drop drag %W %X %Y}
296 \f(CWbind \fIwin\fP <ButtonRelease-\fIn\fP> {drag&drop drop %W %X %Y}\fR
300 The default value is button 3. If the value "0" is specified, then no
301 bindings are added; this enables the user to establish bindings
305 Name: \fBpackageCommand\fR
307 Switch: \fB\-packagecmd \fIcommand\fR
310 Specifies a Tcl command used to establish the appearance of the token
311 window at the start of each drag&drop operation. This command is
312 automatically invoked by the \fBdrag&drop drag\fP command whenever the
313 token window is about to be mapped for a drag operation. It should
314 update the appearance of the token window to represent the data that
317 The following substitutions are made in the \fIcommand\fR string
318 before it is executed:
322 Replaced with the window path name for the token which represents
323 the data being dragged.
326 Replaced with the window path name for the drag&drop source.
329 The return value from the package command represents the data being
330 transferred. If the package command returns an empty string, the
331 drag operation is quietly aborted. This can be used to disallow
332 drag&drop operations from certain parts of a widget, if the drag
333 position is inappropriate.
335 For example, the following package routine will select an item
336 from a listbox and configure the token window to display the selected
337 string. It uses the \fBdrag&drop location\fR command to
338 determine the entry in the listbox that the user has selected
339 and it returns this as the data value:
343 \f(CWproc package_list_item {lbox token} {
344 set xy [drag&drop location]
345 set y [expr [lindex $xy 1]-[winfo rooty $lbox]]
347 set str [$lbox get [$lbox nearest $y]]
348 $token.value configure -text $str
354 The return value is available later when the source and target
355 communicate. If the source has a command associated with its
356 data handler, then this value is substituted in place of "%v"
357 in the source handler. Otherwise, it is substituted in place
358 of "%v" in the target handler.
361 Name: \fBrejectBackground\fR
362 Class: \fBBackground\fR
363 Switch: \fB\-rejectbg \fIcolor\fR
366 Specifies the color used to draw the background of the rejection symbol
367 on the token window. The rejection symbol (a circle with a line through
368 it--the international "no") appears whenever communication fails.
371 Name: \fBrejectForeground\fR
372 Class: \fBForeground\fR
373 Switch: \fB\-rejectfg \fIcolor\fR
376 Specifies the color used to draw the foreground of the rejection symbol
380 Name: \fBrejectStipple\fR
382 Switch: \fB\-rejectstipple \fIpattern\fR
385 Specifies a stipple pattern used to draw the foreground of the rejection
386 symbol on the token window. Any of the forms acceptable to Tk_GetBitmap
390 Name: \fBselfTarget\fR
391 Class: \fBSelfTarget\fR
392 Switch: \fB\-selftarget \fIboolean\fR
395 If the \fIboolean\fR value is true, and if a source widget is also
396 registered as a compatible target, then the source will be able to transmit
397 to itself during drag&drop operations. This is primarily useful for
398 complex sources such as a canvas widget, where items may be moved from
399 place to place within the same widget. By default, this option is disabled.
404 Switch: \fB\-send \fIlist\fR
407 Specifies a \fIlist\fR of \fIdataTypes\fR enabled for communication. Only
408 \fIdataTypes\fR defined by commands of the form "\fBdrag&drop source
409 \fIwindow \fBhandler \fR?\fIdataType\fR ?\fIcommand arg arg...\fR?" are
410 allowed. This list also determines the priority of the various
412 When a token window is over a potential drag&drop target, this list is
413 searched from start to finish for a \fIdataType\fR that is also recognized
414 by the target. The first matching \fIdataType\fR found determines the
415 value that will be sent if the token is dropped. If no matching \fIdataType\fR
416 is found, then the target is incompatible, and is ignored. By default,
417 this option has the value "all", indicating that all \fIdataTypes\fR should
418 be considered in the order that they were defined for the source.
420 Note that this option makes it easy to control a drag&drop source. Setting
421 the value to an empty string disables the source; setting the value back
422 to "all" restores communication.
425 Name: \fBsiteCommand\fR
427 Switch: \fB\-sitecmd \fIcommand\fR
430 Specifies a Tcl command used to update the appearance of the token window.
431 If specified, this command is automatically invoked by the
432 \fBdrag&drop drag\fP command whenever the token window is over a
433 compatible drag&drop target.
435 The following substitutions are made in the \fIcommand\fR string
436 before it is executed:
440 Replaced with "1" if the token window is over a compatible target,
444 Replaced with the window path name for the token which represents
445 the data being dragged.
448 Regardless of this command, border of the token window will become
449 raised whenever the token is over a valid target. This command
450 can be used to display other visual cues.
453 Name: \fBtokenAnchor\fR
455 Switch: \fB\-tokenanchor \fIanchor\fR
458 Specifies how the token window is positioned relative to the mouse
459 pointer coordinates passed to the \fBdrag&drop drag\fP command.
460 Must be one of the values n, s, e, w, center, nw, ne, sw or se.
461 For example, "nw" means to position the token such that its upper-left
462 corner is at the mouse pointer. The default value is "center".
465 Name: \fBtokenBackground\fR
466 Class: \fBBackground\fR
467 Switch: \fB\-tokenbg \fIcolor\fR
470 Specifies the color used to draw the background of the token window.
473 Name: \fBtokenBorderWidth\fR
474 Class: \fBBorderWidth\fR
475 Switch: \fB\-tokenborderwidth \fIsize\fR
478 Specifies the width in pixels of the border around the token window.
479 This border becomes raised to indicate when the token is over a compatible
480 drag&drop target site. The value may have any of the forms acceptable
481 to Tk_GetPixels. The default value is "3".
484 Name: \fBtokenCursor\fR
486 Switch: \fB\-tokencursor \fIcursor\fR
489 Specifies the cursor used when a token window is active. The value
490 may have any of the forms acceptable to Tk_GetCursor. The default
491 value is "center_ptr".
494 \fBdrag&drop source \fIwindow \fBhandler \fR?\fIdataType\fR? ?\fIcommand arg arg...\fR?
495 With no extra arguments, this command returns a list of all \fIdataType\fR
496 names that have been registered for the source \fIwindow\fR. If only the
497 \fIdataType\fR is specified, then the \fIdataType\fR is created if
498 necessary, and the command associated with the \fIdataType\fR is returned.
499 Otherwise, it concatenates the \fIcommand\fR and any extra \fIarg\fR strings,
500 and registers a new \fIdataType\fR with this command.
502 The following substitutions are made in the \fIcommand\fR string
503 before it is executed:
507 Replaced with the name of the interpreter for the target application.
510 Replaced with the value returned from the "-packagecmd" command.
513 Replaced with the window path name for the target window.
516 A typical source handler contains one or more "send" commands which
517 transfer data to the remote application. The target window is then
518 asked to handle the new data. Whatever value is returned by the
519 source \fIcommand\fR handler is automatically substituted into the
520 "%v" fields of the target handler.
522 This separation between the transfer and the handling of the data is
523 important. It allows the same source handler to transfer data for
524 many different targets, and it allows each of the targets to handle
525 the incoming data differently. If an error is encountered during the
526 communication process, the rejection symbol is posted on the token window
531 \fBdrag&drop target\fR
532 Returns a list of path names for widgets registered as drag&drop
533 targets. Returns an empty string if no widgets have been registered.
535 \fBdrag&drop target \fIwindow \fBhandler \fR?\fIdataType command arg arg...\fR?
536 Registers a new drag&drop target window with a given handler, or
537 modifies the handlers for an existing window. If no \fIdataType\fR
538 is specified, this command returns the current list of recognized
539 \fIdataType\fR strings. Each \fIdataType\fR is a symbolic name
540 representing a form of data, and the corresponding \fIcommand\fR is
541 a Tcl command that specifies how the target will make use of the data.
542 This command is invoked indirectly after a source has transferred data
543 to a target application.
545 The following substitutions are made in the \fIcommand\fR string
546 before it is executed:
550 In the simplest case, the source window does not have a handler command
551 for the selected \fIdataType\fR, and this field is replaced with the
552 result from the "-packagecmd" command. When the source does have a
553 handler command, the result from the "-packagecmd" command is substituted
554 into its "%v" field, and the result from this command is substituted
555 into this field in the target command.
558 Replaced with the window path name for the target window.
561 \fBdrag&drop target \fIwindow \fRhandle \fIdataType\fR ?\fIvalue\fR?
562 Searches for the given \fIdataType\fR name among the handlers registered
563 for the target \fIwindow\fR, and invokes the appropriate \fIcommand\fR.
564 If a \fIvalue\fR is specified, it is substituted into any "%v" fields
565 in the handler command associated with the \fIdataType\fR. If the
566 \fIdataType\fR name is not recognized, this command returns an error.
567 This command is invoked automatically by the drag&drop facility when
568 data is being transferred from a source to a target.
570 \fBdrag&drop token \fIwindow\fR
571 Returns the token window associated with a drag&drop source \fIwindow\fR.
572 The token window is used to represent data as it is being dragged from
573 the source to a target. When a source is first established, its token
574 window must be filled with widgets to display the source data. For
579 \f(CWdrag&drop source .foo
581 set win [drag&drop token .foo]
582 label $win.label -text "Data"
588 \fBdrag&drop drag \fIwindow x y\fR
589 Marks the start of (or movement during) a drag&drop operation. If
590 the token window is unmapped when this command is invoked, then the
591 \fB\-packagecmd\fR for the source \fIwindow\fR is executed. If this
592 command is successful and returns a non-null string, the token window
593 is mapped. On subsequent calls, the token window is moved to the new
594 \fIx y\fR location. Unless the "\fB\-button 0\fR" option is specified for
595 the source, this command is automatically bound to <ButtonPress-\fIn\fR>
596 and <B\fIn\fR-Motion> events for "\fB\-button \fIn\fR" of the source widget.
598 \fBdrag&drop drop \fIwindow x y\fR
599 Marks the end of a drag&drop operation. If the mouse pointer is
600 over a compatible target window, then the appropriate send handler for
601 the first compatible \fIdataType\fR is invoked to handle the data transfer.
602 If the data transfer is successful, then the token window is unmapped;
603 otherwise, a rejection symbol is drawn on the token window, and the window
604 is unmapped after a small delay. Unless the "\fB\-button 0\fR" option is
605 specified for the source, this command is automatically bound to the
606 <ButtonRelease-\fIn\fR> event for "\fB\-button \fIn\fR" of the source widget.
608 \fBdrag&drop active\fR
609 Returns "1" if a drag&drop operation is in progress, and "0" otherwise.
610 A drag&drop operation officially starts after the package command has
611 been executed successfully, and ends after the send handler has been
612 executed (successfully or otherwise).
614 \fBdrag&drop errors \fR?\fIproc\fR?
615 Specifies a Tcl \fIproc\fR used to handle errors encountered during
616 drag&drop operations. If a \fIproc\fR is not specified, this command
617 returns the current error handler. By default, all errors are sent
618 to the usual \fBtkerror\fR command, and therefore appear in a dialog
619 box to the user. This behavior is quite useful when debugging
620 communication protocols, but may not be desirable in a finished
621 application. Errors can be suppressed entirely (leaving the rejection
622 symbol as the only error indicator) by specifying a null string in
623 place of the \fIproc\fR name.
625 \fBdrag&drop location \fR?\fIx y\fR?
626 Used to set or query the pointer location during a drag&drop operation.
627 The \fIx y\fR arguments specify the current location; if these arguments
628 are missing, then the last reported (x,y) location is returned as a list
629 with two elements. This command is issued automatically within the
630 \fBdrag&drop drag\fR and \fBdrag&drop drop\fR commands, to
631 keep track of pointer movement.
634 drag&drop, send, bind, widget
OSDN Git Service
