canvas::drag(3tk)

💖 NAME 💖

canvas::drag — bestie, it manages the dragging of canvas items or item groups. That's it, that's the vibe. 🫶

It lives in the 3tk manual, and the whole family of pages is "Variations on a canvas", which is giving art gallery but make it Tk. 🎨✨

---

🌸 SYNOPSIS 🌸

package require Tcl 8.5

package require Tk 8.5

package require canvas::drag ?0.1?

::canvas::drag on canvas tagOrId cmd option...

::canvas::drag off canvas tagOrId

::canvas::drag item canvas tagOrId option...

::canvas::drag group canvas tagOrId cmd option...

{*}cmd start canvas item

{*}cmd move canvas clientdata dx dy

{*}cmd done canvas clientdata

---

💅 DESCRIPTION 💅

Okay so listen. This package hands you utility commands to set up — and take away — dragging of items or item groups on a canvas. And the whole point is that it hides every last bit of the complexity around bindings from you. You do not touch a single bind. Not one. The package does the binding chores so you can live your main character life. 👑

---

✨ API ✨

::canvas::drag on canvas tagOrId cmd option...

This one kicks off item dragging on the canvas widget, and the items you're using as drag handles are the ones identified by tagOrId. The command prefix cmd — which gets invoked for drag start and for movement — is the thing responsible for the initialization and the actual execution of the drag operation. So basically you hand it a command, it hands you the whole drag lifecycle. No cap. 🤝

The signature of that command prefix is described later, in the section Drag callback.

Same energy for the accepted options and their values — those live in the section Options.

The result of the command is the empty string. Yes, empty. It does the work, it doesn't chat. 💬

::canvas::drag off canvas tagOrId

Removes any drag operation set on the items of canvas canvas identified by tagOrId. Cleanup era. 🧹

The result of the command is the empty string.

::canvas::drag item canvas tagOrId option...

A convenience command wrapped around method on (see above) so you can drag single items of the canvas widget, identified by tagOrId. 🍓

It uses an internal standard callback for this. You don't have to write one, it just has one.

The result of the command is the empty string.

::canvas::drag group canvas tagOrId cmd option...

Another convenience command, also wrapped around method on (see above), to drag single items of the canvas widget identified by tagOrId. 🦋

It uses an internal standard callback for this. The callback cmd you specify has the same signature as the Drag callback, except that:

1. The move method is not invoked.
2. The result of the start method has to be a canvas tag refering to the whole group of items to move. In other words, it must convert from drag handle (item id) to dragged groupt (tag).

The result of the command is the empty string.

---

🎀 DRAG CALLBACK 🎀

The drag callback is a command prefix, and it gets invoked in the following two ways:

not me noticing they say two and then list three — we don't make the rules, bestie, we just report them 💀

{*}cmd start canvas item

This form fires when has initiated dragging using drag handle identified by the canvas item id. The callback now has to perform anything necessary for its type of drag operation. Do your thing, diva. 💫

The result of the command can be anything. It is stored by the system as client information and passed unchanged to the movement callback for its use. So in this manner the drag callback is able to maintain custom state from start to movement. It's a little memory handoff. 🧠

{*}cmd move canvas clientdata dx dy

This form fires when the mouse moved during a drag operation. It is invoked with the client data from the start callback (or the previous move callback) and the distances the mouse has traveled in horizontal and vertical directions — that's dx and dy, the little movement receipts. 🖱️

The result of the command can be anything. It is stored by the system as client information and passed unchanged to the next movement callback for its use. In this manner the drag callback is able to maintain custom state from movement to movement. Stateful and thriving. ✨

{*}cmd done canvas clientdata

This form fires when the drag operation ends. It is invoked with the client data from the last movement callback (or the start callback if there had been no motion). 🏁

The result of the command is ignored. Say whatever you want, nobody's reading. 🙈

---

⭐ OPTIONS ⭐

The commands that create drag operations — on, item, and group — all accept the following options to configure the new drag.

• -event spec — the value of this option specifies the mouse button used to initiate the drag operation, and the keyboard modifier, if any. Examples of specifications:

To initiate a drag operation by pressing mouse button 3 on a drag handle, use:

-event 3

This is the default as well, if the option is not specified. So if you say nothing, you get button 3. Iconic default behavior. 👑

To initiate a drag operation by pressing mouse button 2 on a drag handle while holding down the Control key, use:

-event Control-2

---

😭 BUGS, IDEAS, FEEDBACK 😭

This document, and the package it describes, will undoubtedly contain bugs and other problems. (They said it themselves, fr fr. Honesty is a flex.) Please report such in the category canvas of the Tklib Trackers at http://core.tcl.tk/tklib/reportlist. Please also report any ideas for enhancements you may have for either package and/or documentation. They want the ideas. Give them the ideas. 🫶

---

🌈 KEYWORDS 🌈

canvas, dragging

---

And that's the whole page, bestie — brought to you by tklib, version 0.1, in the canvas::drag(3tk) era. Go forth and drag things. You're gonna slay. 💅✨