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 '\" .AP type name in/out ?indent?
25 '\" Start paragraph describing an argument to a library procedure.
26 '\" type is type of argument (int, etc.), in/out is either "in", "out",
27 '\" or "in/out" to describe whether procedure reads or modifies arg,
28 '\" and indent is equivalent to second arg of .IP (shouldn't ever be
29 '\" needed; use .AS below instead)
32 '\" Give maximum sizes of arguments for setting tab stops. Type and
33 '\" name are examples of largest possible arguments that will be passed
34 '\" to .AP later. If args are omitted, default tab stops are used.
37 '\" Start box enclosure. From here until next .BE, everything will be
38 '\" enclosed in one large box.
41 '\" End of box enclosure.
44 '\" Begin code excerpt.
49 '\" .VS ?version? ?br?
50 '\" Begin vertical sidebar, for use in marking newly-changed parts
51 '\" of man pages. The first argument is ignored and used for recording
52 '\" the version when the .VS was added, so that the sidebars can be
53 '\" found and removed when they reach a certain age. If another argument
54 '\" is present, then a line break is forced before starting the sidebar.
57 '\" End of vertical sidebar.
60 '\" Begin an indented unfilled display.
63 '\" End of indented unfilled display.
66 '\" Start of list of standard options for a Tk widget. The
67 '\" options follow on successive lines, in four columns separated
71 '\" End of list of standard options for a Tk widget.
73 '\" .OP cmdName dbName dbClass
74 '\" Start of description of a specific option. cmdName gives the
75 '\" option's name as specified in the class command, dbName gives
76 '\" the option's name in the option database, and dbClass gives
77 '\" the option's class in the option database.
80 '\" Print arg1 underlined, then print arg2 normally.
82 '\" RCS: @(#) $Id: man.macros,v 1.3 2001/02/17 07:46:19 ghowlett Exp $
84 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
88 '\" # Start an argument description
92 . ie !"\\$2"" .TP \\n()Cu
97 \&\\$1 \\fI\\$2\\fP (\\$3)
110 '\" # define tabbing values for .AP
113 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
116 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
117 .nr )C \\n()Bu+\\w'(in/out)'u+2n
119 .AS Tcl_Interp Tcl_CreateInterp in/out
120 '\" # BS - start boxed text
121 '\" # ^y = starting y location
129 .if n \l'\\n(.lu\(ul'
132 '\" # BE - end boxed text (draw box now)
137 .ie n \l'\\n(^lu\(ul'
139 .\" Draw four-sided box normally, but don't draw top of
140 .\" box if the box started on an earlier page.
142 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
145 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
152 '\" # VS - start vertical sidebar
153 '\" # ^Y = starting y location
154 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
158 .ie n 'mc \s12\(br\s0
161 '\" # VE - end of vertical sidebar
169 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
176 '\" # Special macro to handle page bottom: finish off current
177 '\" # box/sidebar if in box/sidebar mode, then invoked standard
178 '\" # page bottom macro.
185 .\" Draw three-sided box if this is the box's first page,
186 .\" draw two sides but no top otherwise.
187 .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
188 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
191 .nr ^x \\n(^tu+1v-\\n(^Yu
192 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
205 '\" # DS - begin display
211 '\" # DE - end display
217 '\" # SO - start of list of standard options
219 .SH "STANDARD OPTIONS"
225 '\" # SE - end of list of standard options
230 See the \\fBoptions\\fR manual entry for details on the standard options.
232 '\" # OP - start of full description for a single option
237 Command-Line Name: \\fB\\$1\\fR
238 Database Name: \\fB\\$2\\fR
239 Database Class: \\fB\\$3\\fR
243 '\" # CS - begin code excerpt
251 '\" # CE - end code excerpt
261 .TH drag&drop n 2.4 BLT "BLT Built-In Commands"
263 '\" Note: do not modify the .SH NAME line immediately below!
265 drag&drop \- facilities for handling drag&drop data transfers
269 \fBdrag&drop source \fIwindow \fR?\fIoptions\fR?
271 \fBdrag&drop source \fIwindow \fBhandler \fR?\fIdataType\fR? ?\fIcommand arg arg...\fR?
275 \fBdrag&drop target \fIwindow \fBhandler \fR?\fIdataType command arg arg...\fR?
277 \fBdrag&drop target \fIwindow \fBhandle \fIdataType\fR ?\fIvalue\fR?
279 \fBdrag&drop token \fIwindow
281 \fBdrag&drop drag \fIwindow x y
283 \fBdrag&drop drop \fIwindow x y
287 \fBdrag&drop errors \fR?\fIproc\fR?
289 \fBdrag&drop location \fR?\fIx y\fR?
294 The \fBdrag&drop\fR command provides access to a set of facilities
295 for managing drag-and-drop data transfers. Any of the usual Tk widgets can
296 be registered to participate in the drag-and-drop process. Widgets
297 registered as a drag&drop \fIsource\fP can export data to other widgets
298 registered as a drag&drop \fItarget\fP. Note that a particular widget
299 can be registered as a source, as a target, or as both.
301 The drag-and-drop process begins when the user clicks and holds a mouse
302 button in a source window; a token window appears with an icon or message
303 to represent the data being transferred. As the user moves the mouse pointer,
304 the token window follows along, acting as a movable packet of data.
305 Whenever the mouse pointer falls on a valid target window, the border of the
306 token window is changed to a raised (active) state. When the mouse button is
307 released over the target window, a Tcl routine is invoked to send the data
308 to the desired application, and the target window is asked to "handle"
309 the data. If this communication process fails, a rejection symbol (a
310 circle with a line through it) is displayed on the token window to
313 The details of the communication process are fully configurable by the
314 application developer. In the simplest case, the value that is sent
315 to the target window is a simple string. The target window is simply
316 asked to "handle" that string value. In general, the source window
317 can have a special "handler" procedure to transfer a particular data
318 type by issuing a series of "send" commands. After this, the target
319 window is again asked to "handle" the result.
321 Both sources and targets can have a list of "handlers" for different
322 data types. As a token window is dragged from its source to various
323 targets, each target is checked to see if it recognizes a handler
324 offered by the source. If it does, it is treated as a valid target.
325 Otherwise, it is ignored. This scheme allows the same source to
326 interact with many different kinds of targets. For example, a source
327 for RGB color samples might have "color" and "string" handlers. This
328 would allow it to communicate with "color" targets (sending RGB data)
329 as well as entry widgets (sending strings of the form "#rrggbb").
331 This introduction was presented as a brief overview of the communication
332 process; further details are presented below:
334 \fBdrag&drop source\fR
335 Returns a list of path names for widgets registered as drag&drop
336 sources. Returns an empty string if no widgets have been registered.
338 \fBdrag&drop source \fIwindow \fR?\fIoptions\fR?
339 Registers a new drag&drop source window with the given options, or
340 modifies the options for an existing window:
344 Name: \fBbuttonBinding\fR
345 Class: \fBButtonBinding\fR
346 Switch: \fB\-button\fR \fIn\fR
349 Specifies the mouse button (integer 1-5) that will invoke the drag&drop
350 operation on the source window. This causes the following bindings to
351 be added to the widget:
355 \f(CWbind \fIwin\fP <ButtonPress-\fIn\fP> {drag&drop drag %W %X %Y}
356 \f(CWbind \fIwin\fP <B\fIn\fP-Motion> {drag&drop drag %W %X %Y}
357 \f(CWbind \fIwin\fP <ButtonRelease-\fIn\fP> {drag&drop drop %W %X %Y}\fR
361 The default value is button 3. If the value "0" is specified, then no
362 bindings are added; this enables the user to establish bindings
366 Name: \fBpackageCommand\fR
368 Switch: \fB\-packagecmd \fIcommand\fR
371 Specifies a Tcl command used to establish the appearance of the token
372 window at the start of each drag&drop operation. This command is
373 automatically invoked by the \fBdrag&drop drag\fP command whenever the
374 token window is about to be mapped for a drag operation. It should
375 update the appearance of the token window to represent the data that
378 The following substitutions are made in the \fIcommand\fR string
379 before it is executed:
383 Replaced with the window path name for the token which represents
384 the data being dragged.
387 Replaced with the window path name for the drag&drop source.
390 The return value from the package command represents the data being
391 transferred. If the package command returns an empty string, the
392 drag operation is quietly aborted. This can be used to disallow
393 drag&drop operations from certain parts of a widget, if the drag
394 position is inappropriate.
396 For example, the following package routine will select an item
397 from a listbox and configure the token window to display the selected
398 string. It uses the \fBdrag&drop location\fR command to
399 determine the entry in the listbox that the user has selected
400 and it returns this as the data value:
404 \f(CWproc package_list_item {lbox token} {
405 set xy [drag&drop location]
406 set y [expr [lindex $xy 1]-[winfo rooty $lbox]]
408 set str [$lbox get [$lbox nearest $y]]
409 $token.value configure -text $str
415 The return value is available later when the source and target
416 communicate. If the source has a command associated with its
417 data handler, then this value is substituted in place of "%v"
418 in the source handler. Otherwise, it is substituted in place
419 of "%v" in the target handler.
422 Name: \fBrejectBackground\fR
423 Class: \fBBackground\fR
424 Switch: \fB\-rejectbg \fIcolor\fR
427 Specifies the color used to draw the background of the rejection symbol
428 on the token window. The rejection symbol (a circle with a line through
429 it--the international "no") appears whenever communication fails.
432 Name: \fBrejectForeground\fR
433 Class: \fBForeground\fR
434 Switch: \fB\-rejectfg \fIcolor\fR
437 Specifies the color used to draw the foreground of the rejection symbol
441 Name: \fBrejectStipple\fR
443 Switch: \fB\-rejectstipple \fIpattern\fR
446 Specifies a stipple pattern used to draw the foreground of the rejection
447 symbol on the token window. Any of the forms acceptable to Tk_GetBitmap
451 Name: \fBselfTarget\fR
452 Class: \fBSelfTarget\fR
453 Switch: \fB\-selftarget \fIboolean\fR
456 If the \fIboolean\fR value is true, and if a source widget is also
457 registered as a compatible target, then the source will be able to transmit
458 to itself during drag&drop operations. This is primarily useful for
459 complex sources such as a canvas widget, where items may be moved from
460 place to place within the same widget. By default, this option is disabled.
465 Switch: \fB\-send \fIlist\fR
468 Specifies a \fIlist\fR of \fIdataTypes\fR enabled for communication. Only
469 \fIdataTypes\fR defined by commands of the form "\fBdrag&drop source
470 \fIwindow \fBhandler \fR?\fIdataType\fR ?\fIcommand arg arg...\fR?" are
471 allowed. This list also determines the priority of the various
473 When a token window is over a potential drag&drop target, this list is
474 searched from start to finish for a \fIdataType\fR that is also recognized
475 by the target. The first matching \fIdataType\fR found determines the
476 value that will be sent if the token is dropped. If no matching \fIdataType\fR
477 is found, then the target is incompatible, and is ignored. By default,
478 this option has the value "all", indicating that all \fIdataTypes\fR should
479 be considered in the order that they were defined for the source.
481 Note that this option makes it easy to control a drag&drop source. Setting
482 the value to an empty string disables the source; setting the value back
483 to "all" restores communication.
486 Name: \fBsiteCommand\fR
488 Switch: \fB\-sitecmd \fIcommand\fR
491 Specifies a Tcl command used to update the appearance of the token window.
492 If specified, this command is automatically invoked by the
493 \fBdrag&drop drag\fP command whenever the token window is over a
494 compatible drag&drop target.
496 The following substitutions are made in the \fIcommand\fR string
497 before it is executed:
501 Replaced with "1" if the token window is over a compatible target,
505 Replaced with the window path name for the token which represents
506 the data being dragged.
509 Regardless of this command, border of the token window will become
510 raised whenever the token is over a valid target. This command
511 can be used to display other visual cues.
514 Name: \fBtokenAnchor\fR
516 Switch: \fB\-tokenanchor \fIanchor\fR
519 Specifies how the token window is positioned relative to the mouse
520 pointer coordinates passed to the \fBdrag&drop drag\fP command.
521 Must be one of the values n, s, e, w, center, nw, ne, sw or se.
522 For example, "nw" means to position the token such that its upper-left
523 corner is at the mouse pointer. The default value is "center".
526 Name: \fBtokenBackground\fR
527 Class: \fBBackground\fR
528 Switch: \fB\-tokenbg \fIcolor\fR
531 Specifies the color used to draw the background of the token window.
534 Name: \fBtokenBorderWidth\fR
535 Class: \fBBorderWidth\fR
536 Switch: \fB\-tokenborderwidth \fIsize\fR
539 Specifies the width in pixels of the border around the token window.
540 This border becomes raised to indicate when the token is over a compatible
541 drag&drop target site. The value may have any of the forms acceptable
542 to Tk_GetPixels. The default value is "3".
545 Name: \fBtokenCursor\fR
547 Switch: \fB\-tokencursor \fIcursor\fR
550 Specifies the cursor used when a token window is active. The value
551 may have any of the forms acceptable to Tk_GetCursor. The default
552 value is "center_ptr".
555 \fBdrag&drop source \fIwindow \fBhandler \fR?\fIdataType\fR? ?\fIcommand arg arg...\fR?
556 With no extra arguments, this command returns a list of all \fIdataType\fR
557 names that have been registered for the source \fIwindow\fR. If only the
558 \fIdataType\fR is specified, then the \fIdataType\fR is created if
559 necessary, and the command associated with the \fIdataType\fR is returned.
560 Otherwise, it concatenates the \fIcommand\fR and any extra \fIarg\fR strings,
561 and registers a new \fIdataType\fR with this command.
563 The following substitutions are made in the \fIcommand\fR string
564 before it is executed:
568 Replaced with the name of the interpreter for the target application.
571 Replaced with the value returned from the "-packagecmd" command.
574 Replaced with the window path name for the target window.
577 A typical source handler contains one or more "send" commands which
578 transfer data to the remote application. The target window is then
579 asked to handle the new data. Whatever value is returned by the
580 source \fIcommand\fR handler is automatically substituted into the
581 "%v" fields of the target handler.
583 This separation between the transfer and the handling of the data is
584 important. It allows the same source handler to transfer data for
585 many different targets, and it allows each of the targets to handle
586 the incoming data differently. If an error is encountered during the
587 communication process, the rejection symbol is posted on the token window
592 \fBdrag&drop target\fR
593 Returns a list of path names for widgets registered as drag&drop
594 targets. Returns an empty string if no widgets have been registered.
596 \fBdrag&drop target \fIwindow \fBhandler \fR?\fIdataType command arg arg...\fR?
597 Registers a new drag&drop target window with a given handler, or
598 modifies the handlers for an existing window. If no \fIdataType\fR
599 is specified, this command returns the current list of recognized
600 \fIdataType\fR strings. Each \fIdataType\fR is a symbolic name
601 representing a form of data, and the corresponding \fIcommand\fR is
602 a Tcl command that specifies how the target will make use of the data.
603 This command is invoked indirectly after a source has transferred data
604 to a target application.
606 The following substitutions are made in the \fIcommand\fR string
607 before it is executed:
611 In the simplest case, the source window does not have a handler command
612 for the selected \fIdataType\fR, and this field is replaced with the
613 result from the "-packagecmd" command. When the source does have a
614 handler command, the result from the "-packagecmd" command is substituted
615 into its "%v" field, and the result from this command is substituted
616 into this field in the target command.
619 Replaced with the window path name for the target window.
622 \fBdrag&drop target \fIwindow \fRhandle \fIdataType\fR ?\fIvalue\fR?
623 Searches for the given \fIdataType\fR name among the handlers registered
624 for the target \fIwindow\fR, and invokes the appropriate \fIcommand\fR.
625 If a \fIvalue\fR is specified, it is substituted into any "%v" fields
626 in the handler command associated with the \fIdataType\fR. If the
627 \fIdataType\fR name is not recognized, this command returns an error.
628 This command is invoked automatically by the drag&drop facility when
629 data is being transferred from a source to a target.
631 \fBdrag&drop token \fIwindow\fR
632 Returns the token window associated with a drag&drop source \fIwindow\fR.
633 The token window is used to represent data as it is being dragged from
634 the source to a target. When a source is first established, its token
635 window must be filled with widgets to display the source data. For
640 \f(CWdrag&drop source .foo
642 set win [drag&drop token .foo]
643 label $win.label -text "Data"
649 \fBdrag&drop drag \fIwindow x y\fR
650 Marks the start of (or movement during) a drag&drop operation. If
651 the token window is unmapped when this command is invoked, then the
652 \fB\-packagecmd\fR for the source \fIwindow\fR is executed. If this
653 command is successful and returns a non-null string, the token window
654 is mapped. On subsequent calls, the token window is moved to the new
655 \fIx y\fR location. Unless the "\fB\-button 0\fR" option is specified for
656 the source, this command is automatically bound to <ButtonPress-\fIn\fR>
657 and <B\fIn\fR-Motion> events for "\fB\-button \fIn\fR" of the source widget.
659 \fBdrag&drop drop \fIwindow x y\fR
660 Marks the end of a drag&drop operation. If the mouse pointer is
661 over a compatible target window, then the appropriate send handler for
662 the first compatible \fIdataType\fR is invoked to handle the data transfer.
663 If the data transfer is successful, then the token window is unmapped;
664 otherwise, a rejection symbol is drawn on the token window, and the window
665 is unmapped after a small delay. Unless the "\fB\-button 0\fR" option is
666 specified for the source, this command is automatically bound to the
667 <ButtonRelease-\fIn\fR> event for "\fB\-button \fIn\fR" of the source widget.
669 \fBdrag&drop active\fR
670 Returns "1" if a drag&drop operation is in progress, and "0" otherwise.
671 A drag&drop operation officially starts after the package command has
672 been executed successfully, and ends after the send handler has been
673 executed (successfully or otherwise).
675 \fBdrag&drop errors \fR?\fIproc\fR?
676 Specifies a Tcl \fIproc\fR used to handle errors encountered during
677 drag&drop operations. If a \fIproc\fR is not specified, this command
678 returns the current error handler. By default, all errors are sent
679 to the usual \fBtkerror\fR command, and therefore appear in a dialog
680 box to the user. This behavior is quite useful when debugging
681 communication protocols, but may not be desirable in a finished
682 application. Errors can be suppressed entirely (leaving the rejection
683 symbol as the only error indicator) by specifying a null string in
684 place of the \fIproc\fR name.
686 \fBdrag&drop location \fR?\fIx y\fR?
687 Used to set or query the pointer location during a drag&drop operation.
688 The \fIx y\fR arguments specify the current location; if these arguments
689 are missing, then the last reported (x,y) location is returned as a list
690 with two elements. This command is issued automatically within the
691 \fBdrag&drop drag\fR and \fBdrag&drop drop\fR commands, to
692 keep track of pointer movement.
695 drag&drop, send, bind, widget
OSDN Git Service
