NAME
drag&drop - facilities for handling drag&drop data trans
fers
SYNOPSIS
drag&drop source
drag&drop source window ?options?
drag&drop source window handler ?dataType? ?command arg
arg...?
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?
_________________________________________________________________
DESCRIPTION
The drag&drop command provides access to a set of facili
ties 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 regis
tered as a drag&drop target. Note that a particular wid
get 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 tar
get 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 pro
cess 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
plest 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 par
ticular 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 inter
act 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:
drag&drop source
Returns a list of path names for widgets registered
as drag&drop sources. Returns an empty string if
no widgets have been registered.
drag&drop source window ?options?
Registers a new drag&drop source window with the
given options, or modifies the options for an
existing window:
Name: buttonBinding
Class: ButtonBinding
Switch: -button n
Specifies the mouse button (integer 1-5)
that will invoke the drag&drop operation on
the source window. This causes the follow
ing bindings to be added to the widget:
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
Specifies a Tcl command used to establish
the appearance of the token window at the
start of each drag&drop operation. This
command is automatically invoked by the
drag&drop drag 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.
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 repre
sents 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 wid
get, 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 com
mand 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
Specifies the color used to draw the back
ground of the rejection symbol on the token
window. The rejection symbol (a circle with
a line through it--the international "no")
appears whenever communication fails.
Name: rejectForeground
Class: Foreground
Switch: -rejectfg color
Specifies the color used to draw the fore
ground of the rejection symbol on the token
window.
Name: rejectStipple
Class: Stipple
Switch: -rejectstipple pattern
Specifies a stipple pattern used to draw the
foreground of the rejection symbol on the
token window. Any of the forms acceptable
to Tk_GetBitmap can be used.
Name: selfTarget
Class: SelfTarget
Switch: -selftarget boolean
If the boolean value is true, and if a
source widget is also registered as a com
patible target, then the source will be able
to transmit to itself during drag&drop oper
ations. This is primarily useful for com
plex 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.
Name: send
Class: Send
Switch: -send list
Specifies a list of dataTypes enabled for
communication. Only dataTypes defined by
commands of the form "drag&drop source win
dow handler ?dataType ?command arg arg...?"
are allowed. This list also determines the
priority of the various dataTypes. When a
token window is over a potential drag&drop
target, this list is searched from start to
finish for a dataType that is also recog
nized by the target. The first matching
dataType found determines the value that
matching dataType is found, then the target
is incompatible, and is ignored. By
default, this option has the value "all",
indicating that all dataTypes should be con
sidered in the order that they were defined
for the source.
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
Specifies a Tcl command used to update the
appearance of the token window. If speci
fied, this command is automatically invoked
by the drag&drop drag command whenever the
token window is over a compatible drag&drop
target.
The following substitutions are made in the command
string before it is executed:
%s Replaced with "1" if the token win
dow 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
Specifies how the token window is positioned
relative to the mouse pointer coordinates
passed to the drag&drop drag 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".
Name: tokenBackground
Switch: -tokenbg color
Specifies the color used to draw the back
ground of the token window.
Name: tokenBorderWidth
Class: BorderWidth
Switch: -tokenborderwidth size
Specifies the width in pixels of the border
around the token window. 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 accept
able to Tk_GetPixels. The default value is
"3".
Name: tokenCursor
Class: Cursor
Switch: -tokencursor cursor
Specifies the cursor used when a token win
dow is active. The value may have any of
the forms acceptable to Tk_GetCursor. The
default value is "center_ptr".
drag&drop source window handler ?dataType? ?command arg
arg...?
With no extra arguments, this command returns a
list of all dataType names that have been regis
tered for the source window. If only the dataType
is specified, then the dataType is created if nec
essary, and the command associated with the
dataType is returned. Otherwise, it concatenates
the command and any extra arg strings, and regis
ters a new dataType with this command.
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" com
mands which transfer data to the remote application. The
target window is then asked to handle the new data. What
ever value is returned by the source command handler is
get 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 differ
ently. If an error is encountered during the communica
tion process, the rejection symbol is posted on the token
window to indicate failure.
drag&drop target
Returns a list of path names for widgets registered
as drag&drop targets. Returns an empty string if
no widgets have been registered.
drag&drop target window handler ?dataType command arg
arg...?
Registers a new drag&drop target window with a
given handler, or modifies the handlers for an
existing window. If no dataType is specified, this
command returns the current list of recognized
dataType strings. Each dataType is a symbolic name
representing a form of data, and the corresponding
command 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.
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 target window handle dataType ?value?
Searches for the given dataType name among the han
dlers registered for the target window, and invokes
the appropriate command. If a value is specified,
it is substituted into any "%v" fields in the han
dler command associated with the dataType. If the
dataType name is not recognized, this command
returns an error. This command is invoked
is being transferred from a source to a target.
drag&drop token window
Returns the token window associated with a
drag&drop source window. The token window is used
to represent data as it is being dragged from the
source to a target. When a source is first estab
lished, its token window must be filled with wid
gets to display the source data. For example,
drag&drop source .foo
set win [drag&drop token .foo]
label $win.label -text "Data"
pack $win.label
drag&drop drag window x y
Marks the start of (or movement during) a drag&drop
operation. If the token window is unmapped when
this command is invoked, then the -packagecmd for
the source window 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 x y location. Unless
the "-button 0" option is specified for the source,
this command is automatically bound to <Button
Press-n> and <Bn-Motion> events for "-button n" of
the source widget.
drag&drop drop window x y
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 dataType is invoked to handle the data
transfer. If the data transfer is successful, then
the token window is unmapped; otherwise, a rejec
tion symbol is drawn on the token window, and the
window is unmapped after a small delay. Unless the
"-button 0" option is specified for the source,
this command is automatically bound to the <Button
Release-n> event for "-button n" of the source wid
get.
drag&drop active
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 other
wise).
Specifies a Tcl proc used to handle errors encoun
tered during drag&drop operations. If a proc is
not specified, this command returns the current
error handler. By default, all errors are sent to
the usual tkerror 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 proc name.
drag&drop location ?x y?
Used to set or query the pointer location during a
drag&drop operation. The x y 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 drag&drop drag and
drag&drop drop commands, to keep track of pointer
movement.
KEYWORDS
drag&drop, send, bind, widget
Man(1) output converted with
man2html