drag&drop(n)

✨ NAME ✨

Okay bestie, this is drag&drop(n) from BLT Built-In Commands 💖. The whole vibe is: drag&drop - facilities for handling drag&drop data transfers.

🫶 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 💅

Okay so 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. And yes, iconic detail: 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:

💖 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:

• -button — 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> {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.

• -packagecmd — Name: packageCommand, Class: Command, Switch: -packagecmd 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 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.

• -rejectbg — 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.
• -rejectfg — Name: rejectForeground, Class: Foreground, Switch: -rejectfg color. Specifies the color used to draw the foreground of the rejection symbol on the token window.
• -rejectstipple — 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.
• -selftarget — 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.
• -send — 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 window 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 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.

• -sitecmd — Name: siteCommand, Class: Command, Switch: -sitecmd command. Specifies a Tcl command used to update the appearance of the token window. If specified, 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 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.

• -tokenanchor — 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".
• -tokenbg — Name: tokenBackground, Class: Background, Switch: -tokenbg color. Specifies the color used to draw the background of the token window.
• -tokenborderwidth — Name: tokenBorderWidth, Class: BorderWidth, Switch: -tokenborderwidth size.
• -tokenborder — sets the width, in pixels, of the border wrapped around the token window. That border becomes raised when the token is hovering over a compatible drag&drop target site, so it's basically a lil glow-up that means "yes bestie, you can drop here 💅". Value can be anything Tk_GetPixels accepts. Default? "3". 🎀
  • Name: tokenCursor
  • Class: Cursor
  • Switch: -tokencursor cursor

This one picks the cursor used while a token window is active. Value can be any of the forms Tk_GetCursor accepts. Default is "center_ptr" (the classic pointy little guy 🫵).

---

🌈 the drag&drop commands, one by one

🤝 drag&drop source window handler ?dataType? ?command arg arg...?

With no extra arguments, this command hands back a list of all the dataType names that have been registered for the source window. If you give it only the dataType, then that dataType gets created if it doesn't exist yet, and the command associated with it is returned. Otherwise it concatenates the command with any extra arg strings and registers a brand-new dataType pointing at that command. Slay, registration complete ✨

These substitutions happen inside the command string before it runs:

• %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 has one or more "send" commands in it that transfer data to the remote application. After that, the target window gets asked to handle the new data. Whatever value the source command handler returns is automatically substituted into the "%v" fields of the target handler. no cap, it just slots in 🧚

This separation between the transfer and the handling of the data is genuinely important — it's giving main character energy, honestly. It lets the same source handler transfer data for lots of different targets, and it lets each target handle the incoming data its own way. If an error shows up during the communication process, the rejection symbol gets posted on the token window to signal failure. 😭

🎯 drag&drop target

Returns a list of path names for widgets registered as drag&drop targets. If nothing's been registered, you get an empty string back. (Empty string, empty vibes, it's fine. 💀)

🎯 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 a window that already exists. If you don't specify a dataType, the command returns the current list of recognized dataType strings. Every dataType is a symbolic name standing for a form of data, and the matching command is a Tcl command that says how the target is gonna make use of that data. This command gets invoked indirectly after a source has transferred data to a target application.

Substitutions made in the command string before it runs:

• %v — in the simplest case, the source window has no handler command for the selected dataType, and this field gets 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 that command is substituted into this field in the target command. (Nested substitution, we love a relay race 🏃‍♀️)
• %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 handlers registered for the target window, and invokes the right command. If you pass a value, it gets substituted into any "%v" fields in the handler command tied to that dataType. If the dataType name isn't recognized, this command returns an error — sorry babe. This command is invoked automatically by the drag&drop facility when data is being transferred from a source to a target. iconic automation tbh 🦋

🎀 drag&drop token window

Returns the token window associated with a drag&drop source window. The token window is what represents the data while it's being dragged from the source to a target. When a source is first established, its token window must be filled with widgets to display the source data. Like so:

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 the movement during — a drag&drop operation. If the token window is unmapped when you invoke this, then the -packagecmd for the source window gets executed. If that command succeeds and returns a non-null string, the token window is mapped. On subsequent calls, the token window just moves to the new x y location. Unless the "-button 0" option was specified for the source, this command is automatically bound to <ButtonPress-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 transfer works out, the token window is unmapped. Otherwise a rejection symbol gets 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.

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

💀 drag&drop errors ?proc?

Specifies a Tcl proc used to handle errors encountered during drag&drop operations. If you don't specify a proc, the command returns the current error handler. By default, all errors go to the usual tkerror command, which means they show up in a dialog box to the user. That behavior is genuinely super useful when you're debugging communication protocols, but it may not be what you want in a finished application. You can suppress errors entirely — leaving the rejection symbol as the only error indicator — by passing a null string in place of the proc name. (Silence. Peace. 🧘‍♀️)

🌸 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 you leave them off, then the last reported (x,y) location is returned as a list with two elements. This command gets issued automatically inside the drag&drop drag and drag&drop drop commands, to keep track of pointer movement.

---

⭐ KEYWORDS ⭐

drag&drop, send, bind, widget

---

and that's the whole page, bestie — you ate that 💅✨ This is the drag&drop(n) man page from BLT 2.5 🎀 go forth and drag responsibly, mwah 🫶💖