canvas::drag(n)

📦 version 0.7, in alpine 3.24

💅 canvas::drag(n) — variations on a canvas, but make it drag

ok so first thing: this page lives in the canvas::drag corner of the tklib manual, and it's all about making canvas items (or whole lil groups of items) draggable without you having to touch a single binding yourself. genuinely iconic behaviour.

✨ NAME ✨

canvas::drag — manage the dragging of canvas items or item groups 🫶

🌸 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 bestie, this package is literally just utility commands that let you set up and remove dragging for items or item groups on a canvas. all the messy complexity around bindings? handled. hidden. gone. you don't have to think about it, no cap. 💅

👑 API 👑

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

this one initializes item dragging on the canvas widget. the items that act as your drag handles are the ones identified by tagOrId.

the command prefix cmd — which gets invoked for the drag start and for the movement — is the main character here. it's responsible for the initialization and the actual execution of the drag operation. yes ma'am.

the signature of that command prefix is described later, down in the Drag callback section. same deal for the accepted options and their values — those live in Options.

the result of the command is the empty string. (nothing, nada, don't @ me.)

🎀 ::canvas::drag off canvas tagOrId

removes any drag operation that was set on the items of canvas canvas identified by tagOrId. like a little 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. so chill.

the result of the command is the empty string.

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

also a convenience command wrapped around method on (see above), for dragging single items of the canvas widget identified by tagOrId.

it uses an internal standard callback for this. the cmd callback you pass in 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 referring to the whole group of items to move. in other words, it must convert from the drag handle (item id) to the dragged group (tag).

the result of the command is the empty string.

🌟 DRAG CALLBACK 🌟

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

💜 {*}cmd start canvas item

this form is invoked when dragging has been initiated using the drag handle identified by the canvas item id. at this point the callback has to do whatever is necessary for its type of drag operation.

the result of the command can be literally anything. the system stores it as client information and passes it unchanged to the movement callback for its use. this is how the drag callback keeps its own custom state from start → movement. cute, right? 🧚

💜 {*}cmd move canvas clientdata dx dy

this form is invoked when the mouse moves during a drag operation. it gets called with the client data from the start callback (or from the previous move callback), plus the distances the mouse has travelled horizontally and vertically.

the result of the command can be anything too. it's stored by the system as client information and passed unchanged to the next movement callback. that's how state flows from movement to movement. slay. 🔥

💜 {*}cmd done canvas clientdata

this form is invoked when the drag operation ends. it's called with the client data from the last movement callback (or the start callback, if there was no motion at all).

the result of the command is ignored. bye bestie. 👋

⭐ 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, plus the keyboard modifier, if there is one. some examples, because examples eat:

to kick off a drag by pressing mouse button 3 on a drag handle, use:

-event 3

and lowkey this is also the default if you don't specify the option at all. 🎁

to kick off a drag 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. it's giving "we know". 😭 please report such in the category canvas of the Tklib Trackers [http://core.tcl.tk/tklib/reportlist]. please also report any ideas for enhancements you may have for either the package and/or its documentation — they'd love that fr fr.

🔑 KEYWORDS 🔑

canvas, dragging

okay that's the whole page bestie, you're officially a canvas drag expert, iykyk 💅✨

this lil masterpiece comes from tklib, version 0.1, dated canvas::drag(n) — signed off with love, mwah 🫶🎀

📦 where this page comes from