SWAPLIST(n)

💅 swaplist — the manual, but make it make sense

okay bestie so this is swaplist(n), a Tcl manpage from the tklib fam, and I promise it's actually cute once you see it. it's a dialog with two listboxes and you just… move stuff between them. that's the whole vibe. icon behavior honestly. 🫶

---

✨ NAME ✨

swaplist — a dialog which allows a user to move options between two lists 🎀

---

🌸 SYNOPSIS 🌸

package require Tcl  8.4

package require Tk  8.4

package require swaplist  ?0.1?

::swaplist::swaplist   pathName   variable   completeList   selectedList
?options?

no cap, that ?0.1? is optional-version notation, not me being shady about it 💀

---

🦋 DESCRIPTION 🦋

bestie. it's so simple. this package hands you a dialog made of 2 listboxes, plus buttons to shuffle items between them and to reorder the right-hand list. two lists. buttons. slay. ✨

::swaplist::swaplist pathName variable completeList selectedList ?options?

creates a dialog which presents the user with a pair of listboxes. 🎀

the way it works: items get selected by using the buttons to move them over to the right list. then, when the dialog closes, the contents of the right list get dropped into the variable. main character energy tbh.

the command returns a boolean telling you whether the user pressed OK or not — 1 for yes bestie, 0 for nope.

and about placement 👀 — if -geometry is not specified, the dialog centers itself in its parent toplevel, unless its parent is ., in which case the dialog centers itself on the screen instead. tiny detail, big difference, iykyk.

💅 Options:

• -embed — if this flag is supplied, the procedure will create a swaplist widget named pathName, with the variable set as the listvariable for the right side listbox. heads up though: this flag will also cause the -title and -geometry flags to be ignored. they simply do not get an invite to this party 🙈
• -reorder — boolean specifying if buttons allowing the user to change the order of the right listbox should appear or not. defaults to true. yes queen, reorder the list.
• -title — sets the title of the dialog window. defaults to "Configuration".
• -llabel — sets the heading above the left list. defaults to "Available:".
• -rlabel — sets the heading above the right list. defaults to "Selected:".
• -lbuttontext — sets the text on the "move left" button. defaults to "<<".
• -rbuttontext — sets the text on the "move right" button. defaults to ">>".
• -ubuttontext — sets the text on the "move up" button. defaults to "Move Up".
• -dbuttontext — sets the text on the "move down" button. defaults to "Move Down".
• -geometry — sets the geometry of the dialog window. 📐

---

🌈 EXAMPLE 🌈

okay here's the moment you've been waiting for, the actual code, no notes:

package require swaplist
namespace import swaplist::*

if {[swaplist .slist opts "1 2 3 4 5 6 7 8 9" "1 3 5"]} {
    puts "user chose numbers: $opts"
}

see like — "1 2 3 4 5 6 7 8 9" is the complete list, "1 3 5" is what's preselected, and if they hit OK you get their picks in $opts. and if they don't, the if just doesn't fire. chef's kiss. 👑

---

🍓 BUGS, IDEAS, FEEDBACK 🍓

ngl, this document — and the package it describes — will undoubtedly contain bugs and other problems. it's giving "we're all just doing our best." 😭

please report such in the category swaplist of the Tklib Trackers at http://core.tcl.tk/tklib/reportlist.

please also report any ideas for enhancements you may have for either the package and/or this documentation. we want the glow-up, we welcome the glow-up. 🫶✨

---

🧚 KEYWORDS 🧚

dialog, disjointlistbox, listbox

---

👑 CATEGORY 👑

Widget

---

okay that's the whole page, you ate that. 💜 and for the cute sign-off: this little icon is from tklib, version 0.1 — go forth and swap your lists, bestie. 🎀✨💅