widget_listsimple(3tk)

🎀 widget_listsimple 🎀

okay bestie, pull up a chair because we're talking about widget_listsimple, a member of the widget::listsimple widget family, from the 3tk manual. it's a whole vibe and it's about to make your unordered list entry situation so much cuter. 💖

---

✨ SYNOPSIS ✨

first things first, the requirements. you gotta have all of these loaded or nothing works, no cap:

package require Tcl 8.5

package require Tk 8.5

package require widget::listsimple ?0.1.2?

package require widget::validator ?0.1?

package require widget::scrolledwindow

package require snit

package require tooltip

package require img::png

package require msgcat

widget::listsimple pathname ?options?

widgetCmd destroy

widgetCmd configure

widgetCmd configure option value ...

widgetCmd configure option

widgetCmd cget option

{*}cmdprefix get

{*}cmdprefix set values

{*}cmdprefix text errvar

---

🌸 DESCRIPTION 🌸

so this package hands you a megawidget for the interactive entry of unordered lists. that's the whole job. it does it gorgeously. 💅

now listen — if what you actually want is a megawidget for ordered lists (and, like, more than that), you're in the wrong place and you should go see the widget::listentry package instead. okay? okay. 🫶

---

👑 CLASS API 👑

the widget class keeps it simple: there's literally one command, and its whole personality is creating widgets.

• widget::listsimple pathname ?options? — this command creates and configures brand-new instances of the widget. wanna know about the options? scroll down to Widget Options, bestie. the result of this command is the pathname of the shiny new widget you just made. ✨

---

🦋 INSTANCE API 🦋

every widget instance comes with these methods. they're the whole support system.

• widgetCmd destroy — this one destroys the widget. and like, actually destroys it. any further access to the widget after that will generate errors, so don't come crawling back. 😭 the result of the command is the empty string.
• widgetCmd configure — this method comes in three variants, and this variant right here returns a list containing the current configuration of the widget, i.e. the values for all options. for details on the available options please see section Widget Options.
• widgetCmd configure option value ... — second of the three variants. this one reconfigures the widget, setting the specified options to the given values. > ⚠️ heads up: it is not possible to change the construction-time only options. for details on the available options please see section Widget General Options. the result of the command is the empty string.
• widgetCmd configure option — third variant, and honestly it's just an alias for the cget method below. literally identical. no notes. 💅
• widgetCmd cget option — returns the current value of the specified option. for details on the available options please see section Widget Options.

---

🌈 WIDGET OPTIONS 🌈

this section explains all the options available to instances of widget::listsimple. one thing to know: a few of these can only be set at instance construction time. the majority though? set them whenever, construction-time or runtime, we're flexible like that. ✨

💖 WIDGET CONSTRUCTION-TIME ONLY OPTIONS 💖

• -values cmdprefix — this option specifies a callback for the management of a predefined list of strings a user may enter.

if you specify it, the widget will use a combobox instead of a plain entry field, and it fills that combobox's list during widget construction using the data delivered by this callback. the callback also gets invoked whenever a new value is entered into the main list, so it can save the extended list of predefined values.

the signature of this callback is:

• {*}cmdprefix get — in this form the callback is expected to return a list of strings. those strings get loaded into the list of the internal combobox for quick access by the user. it will be invoked once, during widget construction, to load the list of predefined strings a user may enter.
• {*}cmdprefix set values — in this form the callback is given a list of new strings and expected to save them somewhere for future use. the return value of the callback is ignored. this form is invoked whenever the user entered a new string into the main list. the order of strings in values represents the order used to show them in the combobox's list.

• -validate cmdprefix — this option specifies a callback which is invoked after every single change of the contents of the internal entry field. its signature is:
  • {*}cmdprefix text errvar — where text is the string to validate, and errvar the name of a variable the callback can store an error message into when it detects invalid data. the system expects that the callback returns a boolean value, where true indicates that text is valid.

the default validation, when no callback was specified, will treat the empty string as invalid, and everything else as valid. 💅

⚠️ important, bestie: the widget will prevent the entry of duplicate values into the main list, regardless of the validity of the input otherwise. this is in keeping with that this widget is meant for the entry of unordered lists — essentially a set of strings.

🌸 WIDGET GENERAL OPTIONS 🌸

• -listvariable varname — specifies the variable holding the list to be manipulated by the widget. any changes to the list outside of the widget are automatically imported into the widget. similarly, all changes made to the list by the widget are automatically exported to this variable. two-way street, mutual, iconic. 💞
• -skin-add string
• -skin-remove string
• -skin-tip-add string
• -skin-tip-remove string
• -skin-tip-main string
• -skin-tip-entry string
• -skin-tip-list string
• -skin-tip-empty string
• -skin-tip-duplicate string
• -skin-tip-add-none string
• -skin-tip-remove-none string
• -skin-img-add image
• -skin-img-remove image
• -skin-invalid-color color — these options all modify the appearance of the widget, i.e. its skin. ✨

all options taking a string argument influence the various labels shown, with the -skin-tip-* options influencing the tooltips shown on hovering over the various parts in particular.

all the strings are run through msgcat first, enabling text localization through message catalogs. the default values are keys into the message catalogs which are part of the package itself.

the options taking images modify the images shown on the buttons for adding and removing elements of the list. they default to the PNG images distributed with the package itself. 🖼️

the single option taking a color value modifies the color used to highlight invalid data entered into the internal entry field of the widget. this option defaults to yellow. 💛

---

⭐ EXAMPLE ⭐

(this section is empty in the original, bestie. nothing to see here. it's giving mystery. 🙈)

---

💀 BUGS, IDEAS, FEEDBACK 💀

ngl, this document — and the package it describes — will undoubtedly contain bugs and other problems. 😭 please report such in the category widget::listsimple of the Tklib Trackers at http://core.tcl.tk/tklib/reportlist. and please also report any ideas for enhancements you may have for either the package and/or the documentation. we wanna hear it, fr fr. 🫶

---

🔥 KEYWORDS 🔥

data entry lists, data entry set of strings, data entry unordered list, list entry panel, set entry panel, widget

---

and that's the whole page, bestie!! this one's from tklib, version 0.1.2, page widget_listsimple(3tk). go forth and enter some unordered lists, you absolute main character. 💅✨🎀