drag&drop target
drag&drop target window handler ?dataType command arg arg...?
drag&drop target window handle dataType ?value?
drag&drop token window
drag&drop drag window
x y
drag&drop drop window x y
drag&drop active
drag&drop errors ?proc?
drag&drop location ?x y?
The drag&drop 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 source can export data to other widgets registered as a drag&drop target. Note that a particular widget can be registered as a source, as a target, or as both.
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.
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.
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").
This introduction was presented as a brief overview of the communication process; further details are presented below:
Name: buttonBinding Class: ButtonBinding Switch: -button n
bind win <ButtonPress-n> {drag&drop drag %W %X %Y}
bind win <Bn-Motion> {drag&drop drag %W %X %Y}
bind win <ButtonRelease-n> {drag&drop drop %W %X %Y}
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.
Name: packageCommand Class: Command Switch: -packagecmd command
The following substitutions are made in the command string before it is executed:
- %t
- Replaced with the window path name for the token which represents the data being dragged.
- %W
- Replaced with the window path name for the drag&drop source.
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.
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 drag&drop location command to determine the entry in the listbox that the user has selected and it returns this as the data value:
proc package_list_item {lbox token} {
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
}
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.
Name: rejectBackground Class: Background Switch: -rejectbg color
Name: rejectForeground Class: Foreground Switch: -rejectfg color
Name: rejectStipple Class: Stipple Switch: -rejectstipple pattern
Name: selfTarget Class: SelfTarget Switch: -selftarget boolean
Name: send Class: Send Switch: -send list
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.
Name: siteCommand Class: Command Switch: -sitecmd command
The following substitutions are made in the command string before it is executed:
- %s
- Replaced with "1" if the token window is over a compatible target, and "0" otherwise.
- %t
- Replaced with the window path name for the token which represents the data being dragged.
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.
Name: tokenAnchor Class: Anchor Switch: -tokenanchor anchor
Name: tokenBackground Class: Background Switch: -tokenbg color
Name: tokenBorderWidth Class: BorderWidth Switch: -tokenborderwidth size
Name: tokenCursor Class: Cursor Switch: -tokencursor cursor
The following substitutions are made in the command string before it is executed:
- %i
- Replaced with the name of the interpreter for the target application.
- %v
- Replaced with the value returned from the "-packagecmd" command.
- %w
- Replaced with the window path name for the target window.
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 command handler is automatically substituted into the "%v" fields of the target handler.
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.
The following substitutions are made in the command string before it is executed:
- %v
- In the simplest case, the source window does not have a handler command for the selected dataType, 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.
- %W
- Replaced with the window path name for the target window.
drag&drop source .foo set win [drag&drop token .foo] label $win.label -text "Data" pack $win.label