NAME
blt_drag&drop - facilities for handling drag&drop data transfers

SYNOPSIS
blt_drag&drop source
blt_drag&drop source window ?config options?
blt_drag&drop source window handler ?dataType command ...?

blt_drag&drop target
blt_drag&drop target window handler ?dataType command ...?

blt_drag&drop target window handle dataType

blt_drag&drop drag window x y
blt_drag&drop drop window x y
blt_drag&drop active
blt_drag&drop errors ?proc?
blt_drag&drop location ?x y?

DESCRIPTION

The blt_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. 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. The general philosophy, however, is that the sender should invoke a series of commands in the remote application to transfer data into a buffer, and then request that the receiver "handle" the data. For example, the sender might invoke a command like "set DragDrop(number) 12.3" in the target application. The sender would then request that the target "handle" a "number". This separation between the data sent and the means of handling it is critical. It allows the developer a simple means of having several targets that all receive "numbers" but use them in different ways.

Both sources and targets must be registered with a list of "handlers" defining the data types that they recognize. 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. A source for RGB color samples, for instance, might have "color" and "text" handlers. This would allow it to communicate with "color" targets (sending RGB data) as well as entry widgets (sending strings of the form "#rrggbb").

For drag&drop to be effective across many applications, handlers for sending various data types should be common. For this reason, a directory "demos/dd_protocols" containing a number of example handlers is included with this distribution. Developers are encouraged to use this library and contribute new functions.

This introduction was presented as a brief overview of the communication process; further details are presented below:

blt_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.

blt_drag&drop source window ?config 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 following bindings to be added to the widget:

        bind win <ButtonPress-n> {blt_drag&drop drag %W %X %Y}
        bind win <Bn-Motion> {blt_drag&drop drag %W %X %Y}
        bind win <ButtonRelease-n> {blt_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 prefix

        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 blt_drag&drop drag command whenever the token window is about to be mapped for a drag operation. The path name for the token window is automatically appended to the command before it is executed:

        packagecmd token

    Typically, this command is the name of a procedure (taking the token window argument) which will pack a label--or update the text of a label--in the token window.

    The return value from the package command is later passed as an argument to the send handler; thus, it is the responsibility of the package command to determine what information will later be sent. For complex sources, such as a listbox containing a number of items, the package command can use the blt_drag&drop location command to determine the part of a widget that a user has selected and extract a value. For example, the following package routine will select an item from a listbox and configure the token window to display the selected string:

        proc package_list_item {lbox token} {
            if {[winfo children $token] == ""} {
                label $token.value
                pack $token.value
            }
            set xy [blt_drag&drop location]
            set y  [expr [lindex $xy 1]-[winfo rooty $lbox]]
            set str [$lbox get [$lbox nearest $y]]
            $token.value config -text $str
            return $str
        }

    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.

    Name:	rejectBackground
    Class:	Background
    Switch:	-rejectbg color

        Specifies the color used to draw the background 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 foreground 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 compatible target, then the source will be able to transmit to itself during drag&drop operations. This is primarily useful for complex 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 "blt_drag&drop source window handler ?dataType command ...?" 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 recognized by the target. The first matching dataType found determines the value that will be sent if the token is dropped. If no 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 considered 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 prefix

        Specifies a Tcl command used to update the appearance of the token window. If specified, this command is automatically invoked by the blt_drag&drop drag command whenever the token window is over a compatible drag&drop target. Two arguments are appended to this command:

        sitecmd state token

    state is an integer with a non-zero value whenever the token window is over a compatible target, and token is the path for the token window. 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 blt_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
    Class:	Background
    Switch:	-tokenbg color

        Specifies the color used to draw the background 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 acceptable to Tk_GetPixels. The default value is "3".

    Name:	tokenCursor
    Class:	Cursor
    Switch:	-tokencursor cursor

        Specifies the cursor used when a token window is active. The value may have any of the forms acceptable to Tk_GetCursor. The default value is "center_ptr".

blt_drag&drop source window handler ?dataType command ...?
    Defines one or more dataTypes available for communication, and the commands used to send them to remote applications. If no dataTypes are specified, then the list of previously defined dataTypes is returned.

Each command represents a Tcl command prefix. Three arguments are appended to this prefix when communication is initiated for a particular dataType:

    command interp target data

interp is the name of the interpreter containing the target widget; target is the name of the target widget; and data is the data string returned from the "package" command invoked at the start of the drag&drop operation.

A typical source handler contains one or more "send" commands which transfer data to the remote application, followed by a "blt_drag&drop widget handle the incoming data. An example source handler for a "text" data type is shown below:

    proc dd_send_text {interp ddwin data} {
        send $interp "
            global DragDrop
            set DragDrop(text) {$data}
        "
        send $interp "blt_drag&drop target $ddwin handle text"
    }

This handler transfers the text string to a global variable DragDrop(text) in the target interpreter, and then requests that the target "handle" the incoming data. 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.

blt_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.

blt_drag&drop target window handler ?dataType command ...?
    Registers a new drag&drop target window with the given handlers, or modifies the handlers for an existing window. If no handlers are 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 whenever a send routine transmits data and then issues the "blt_drag&drop ... handle dataType" command to make use of it.

blt_drag&drop target window handle dataType
    Searches for the given dataType name among the handlers registered for the target window, and invokes the appropriate command. If the dataType name is not recognized, this command returns an error. Typically, this command is invoked by one of the send handlers for a drag&drop source.

blt_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 <ButtonPress-n> and <Bn-Motion> events for "-button n" of the source widget.

blt_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 rejection 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 <ButtonRelease-n> event for "-button n" of the source widget.

blt_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 otherwise).

blt_drag&drop errors ?proc?
    Specifies a Tcl proc used to handle errors encountered 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.

blt_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 blt_drag&drop drag and blt_drag&drop drop commands, to keep track of pointer movement.

KEYWORDS
drag&drop, send, bind, widget