term::interact::menu(n)

💖 term::interact::menu — the manual page, but make it cute 💖

okay bestie, welcome to the term::interact::menu(n) page — that's section n of the manual, and it lives under Terminal control. it's a Tcl widget situation. a menu. in your terminal. iconic behavior fr fr. 🎀

---

✨ NAME ✨

term::interact::menu — Terminal widget, menu 🍓

---

✨ SYNOPSIS ✨

package require Tcl 8.5 9

package require term::interact::menu ?0.2?

term::interact::menu object dict ?options...?

object interact

object done

object clear

object configure

object configure option

object configure option value...

object cget option

no cap, that's the whole vibe up there. 👑

---

✨ DESCRIPTION ✨

so this package hands you a class 💅 and that class makes a simple menu control. that's it. that's the whole job. she's a menu, she shows up in your terminal, she gets picked from. periodt.

---

✨ CLASS API ✨

the package exports exactly one command — the class command — and that's what lets you spawn menu instances. here's her API:

• term::interact::menu object dict ?options...? — this makes a brand new menu object named object, initializes it, and hands you back the fully qualified name of the object command as the result. ✨

the argument is the menu you want to show, and after it you can drop configuration options and their values. those options are explained down in Configuration. and btw, the menu is a dictionary mapping labels to symbolic action codes. iykyk.

---

✨ OBJECT API ✨

the objects you get from the class command come with these methods, and they are all lowkey essential:

• object interact — shows the menu on the screen at whatever location you configured, then starts interacting with it. it opens its own event loop to process incoming characters. the method returns once the interaction is complete. wanna know what interactions are even possible? go read the Interaction section, bestie.

and when it returns? it gives you back the symbolic action of the menu item the user picked at the end of the interaction. slay. 💅

• object done — user-supplied actions can call this to terminate the interaction with the object. bye bestie 👋
• object clear — user-supplied actions can call this to remove the menu from the terminal. poof. 🦋
• object configure
• object configure option
• object configure option value...
• object cget option — the standard methods for retrieving and configuring the menu's options. nothing weird, just the classics. 🎀

---

✨ CONFIGURATION ✨

a menu instance recognizes these options, and yes we're going through all of them:

• -in chan — the channel to read character sequences from. defaults to stdin. 🌸
• -out chan — the channel to write the menu contents to. defaults to stdout. 🌈
• -column int — the column of the terminal where the left margin of the menu display should appear. defaults to 0, i.e. the left-most column. no wiggle room on the default, she starts at the wall. ⭐
• -line int — the line of the terminal where the top margin of the menu display should appear. defaults to 0, i.e. the top-most line. 💜
• -height int — how many lines of text to show at most in the display. defaults to 25. 👑
• -actions dict — a dictionary holding extra actions, using character sequences as keys. ⚠️ heads up: these sequences cannot override the hardwired sequences described in Interaction. them's the rules.
• -hilitleft int
• -hilitright int — by default the entire selected menu entry gets highlighted in reverse output. but when these two options are present, they restrict the reverse display to the specified sub-range of the entry. so it's a little spotlight instead of the whole stage. ✨
• -framed bool — by default the menu is shown using only header and footer out of the characters box graphics. if this flag is set, the menu gets fully enclosed in a box. boxed up like a gift fr fr 🎁

---

✨ INTERACTION ✨

a menu object recognizes these control sequences and acts like this. you can hand her more control sequences to act on via the configuration, but you cannot override these defaults. hard no. 💀

• Cursor Up — the selection moves up one entry. except if the first entry of the menu is already selected, then she just sits there. 🙈
• Cursor Down — the selection moves down one entry. except if the last entry of the menu is already selected. she's not going anywhere, bestie. 😭
• Enter/Return — the interaction with the object is terminated. that's the one. periodt. 💅

---

✨ 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 those in the category term of the Tcllib Trackers at [http://core.tcl.tk/tcllib/reportlist]. 🫶 and please also report any ideas for enhancements you have for either the package and/or the documentation, because we love a glow-up suggestion.

when you propose code changes, please provide unified diffs, i.e. the output of diff -u. that's the love language here.

and note further: attachments are strongly preferred over inlined patches. you make attachments by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. you got this. 💖

---

✨ KEYWORDS ✨

control, menu, terminal, text display 🌸

---

✨ CATEGORY ✨

Terminal control 🦋

---

✨ COPYRIGHT ✨

Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> 💜

---

and that's the whole page, bestie!! this one came from tcllib, version 0.2 — so if you ever need to cite her, it's tcllib, 0.2, the term::interact::menu(n) page. go forth and build a menu. main character energy only. 💅✨🎀