NAME
olednd - Tcl OLE Drag and Drop Interface
SYNOPSIS
olednd bindtarget windowId
olednd bindtarget windowId type ?<event>?
olednd bindtarget windowId type ?<event>? script ?-priority <1-100>?
olednd cleartarget windowId
olednd bindsource windowId
olednd bindsource windowId type
olednd bindsource windowId type script
olednd clearsource windowId
olednd drag windowId
INTRODUCTION
The olednd command provides a Tcl interface to the OLE drag and drop
mechanism. To setup for drag and drop, register the drag/drop types
that can be handled by source and target windows. When a drag
operation commences, one or more of the types that was registered on
the window must match for a drop to occur. If no match is found, the
cursor shown is a small circle with a line through it. If a match is
found, the OLE2 cursor indicating a copy or move operation is shown.
SETTING UP THE TARGET
To register a data type that can be handled by a target window, use
the bindtarget option. For example, to handle plain dropped text, use
CF_TEXT as the type.
olednd bindtarget .tgt CF_TEXT <Drop> {puts}
When a drop occurs from a source that has data of CF_TEXT, the text
will be appended as the last argument to the command. In this case,
if the dragged data was a sentence such as "The quick brown fox jumped
over the moon", the command that would be run is
puts "The quick brown fox jumped over the moon"
You can specify anything as a data type. CF_TEXT is a special case
that represents all simple ASCII text that can be dragged and dropped.
Creating a handler for CF_TEXT on a window will allow that window to
handle text drags and drops from another OLE enabled application that
also uses the standard CF_TEXT mechanism.
Some other common types for dragging and dropping to and from web
browsers are UniformResourceLocator and "Netscape Bookmark". The type
FileName is used by Explorer to drag and drop a file from the desktop.
There are four events you can bind to: <DragEnter>, <Drag>,
<DragLeave>, and <Drop>. For <DragEnter> and <Drop>, the dragged text
is appended as the last argument. For <Drag> and <DragLeave>, no text
is appended to the command.
You can register more than a single type to be handled by a window.
Just run the command again with a different data type. Here is
another example for the same window.
olednd bindtarget .tgt TKNT_COLOR <Drop> {.tgt config -bg}
In this case, if a an object gets dropped on window .tgt, .tgt will
ask the source if it supports either CF_TEXT or TKNT_COLOR. If it
does, it will run the script for the match. It is possible that more
than one type would be matched between the source and target. For
this case, you can use the -priority <num> option to specify the order
in which you want the search for matches to occur. Priorities range
from 1 to 100. 1 is the highest priority, 50 is the default priority,
and 100 is the lowest priority. If two target data types have the
same priority, it is undetermined which one will be checked for first.
In the above example, if you want to check for the TKNT_COLOR datatype
before CF_TEXT, give a higher priority to the TKNT_COLOR datatype.
olednd bindtarget .tgt TKNT_COLOR <Drop> {.tgt config -bg} -priority
1
SETTING UP THE DRAG SOURCE
For sources, register the data types that can be provided by a window
the the bindsource option. For example, to be registered as a drop
source for ASCII text, use CF_TEXT as the data type.
olednd bindsource .src CF_TEXT <Drop> {return "Some text"}
More than one datatype can be registered with a source window. To go
along with our example, setup the window as a provider of data of type
TKNT_COLOR.
olednd bindsource .src TKNT_COLOR {return red}
THE DRAG OPERATION
Now that both the target window and the source window have been
configured, one as a data source and the other as a drop area, we
still need to do something to initiate the drag operation. If the
application that is being dragged from is not part of Tk, we let it
handle the drag & drop operation. If we want to drag something from
.src to .tgt, we initiate the drag and drop operation with the drag
option. Here, we start the operation on a press of mouse button 1.
bind .src <1> {olednd drag %W}
Once button 1 is pressed on .src, the drag operation begins. When the
button is released, a different button is pressed, or a modifier key
is pressed during the operation, then a drop operation occurs. If the
drop occurs over a window that has a type that matches the source
window, then the script for the source window gets run first. If you
do not want the source window to send data, it can do a
return -code break
If the return value is not an error or a break code, the target window
script for the matched datatype is then run.
For the example above, the datatype that matched would be TKNT_COLOR.
First, the script for data type TKNT_COLOR on window .src would be
run. This is
return red
The string "red" would now be appended to the command for datatype
TKNT_COLOR on the target window .tgt. The command would be
.tgt config -bg red
In our simple example, .tgt would change its background color to red
on a drag and drop from .src.
BINDING SCRIPTS AND SUBSTITUTIONS
If a script contains any % characters, then the script will not be
executed directly. Instead, a new script will be generated by
replacing each %, and the character following it, with information
from the current drop event. The replacement depends on the character
following the %, as defined in the list below.
%% Replaced with a single percent.
%T The name of the dropped data type.
%W The window the script was bound to.
%X The screen X cursor coordinate when the drop occurred. This is |
undefined for the source script. |
undefined for the source script. |
%x The window relative X cursor coordinate when the drop occurred. |
This is undefined for the source script. |
%y The window relative Y cursor coordinate when the drop occurred. |
This is undefined for the source script. |
COMMANDS
olednd bindtarget windowId
Returns a list of drag/drop datatypes that are handled by the window.
olednd bindtarget windowId type ?<event>?
Returns the script that would be invoked if an object of datatype type
matched the event type for the window windowId.
olednd bindtarget windowId type script <event> ?-priority num (1-100)?
Binds a script to run when a dropped object's datatype matches. If an
empty script is given, type is removed as a handled datatype.
olednd cleartarget windowId
Removes all dropped data handlers from the window.
olednd bindsource windowId
Returns a list of drag/drop datatypes that can be generated by the
window.
olednd bindsource windowId type
Returns the script that gets run when a drop operation has occurred
and the target has matched this type.
olednd bindsource windowId type script
Binds a script to run when a drop operation has occurred and the
target has matched this type.
olednd clearsource windowId
Removes all datatypes that could be generated by the window windowId.
olednd drag windowId
Initiates an OLE drag and drop operation.
NOTES
Only one match is generated for each source/dest. This means that a
maximum of one script will be run for source and one for the target.
If an error occurs in the source script, the drop operation fails.
- 4 - Formatted: September 4, 1998
tkerror mechanism is used to report the error. The tkerror command |
will be executed at global level (outside the context of any Tcl |
procedure). |
SEE ALSO
tkerror
KEYWORDS
OLE, drag, drop
- 5 - Formatted: September 4, 1998